Augment session evidence in Harness Inspector

Traceability

• Spec ID: augment-session-inspector-support
• Status: Implemented

Intent

Allow Harness Inspector and the shared session-analysis commands to inspect workspace-qualified Augment/Auggie sessions from the local Augment cache. The adapter must expose only provider-observed messages, tool lifecycle, token accounting, context-window occupancy, timestamps, and explicit history-summary boundaries. Missing or ambiguous evidence remains unobserved instead of being inferred from field names or represented as zero.

The native contract for this slice was observed from Auggie CLI 0.36.0 (@augmentcode/auggie, commit 7c61e5bb) and its local ~/.augment/sessions records. Deterministic tests use synthetic, redacted fixtures rather than copied local transcripts.

Acceptance Scenarios

• AC-1: session-analysis discovers JSON sessions under the default ~/.augment/sessions root and an explicit --augment-home, but admits only sessions whose recorded workspace folder, repository root, or terminal cwd matches the requested workspace. POSIX and Windows path semantics are covered without splitting native paths on /.
• AC-2: One Augment exchange produces bounded user and assistant observations, correlated tool call/result events, and one model response per native token_usage node. Native timestamps and ids preserve chronology without counting content, thinking, tool, or history-summary nodes as model calls.
• AC-3: Observed input, output, cache-read, and cache-creation counters remain separate. Prompt occupancy is derived only from the additive prompt lanes, max_context_tokens supplies the same-response window, and absent usage or window fields remain unobserved rather than zero.
• AC-4: A native history_summary_node produces one explicit compaction boundary without exporting summary text. Context shrink remains a measured delta; a shrink without that marker is not relabelled as provider-confirmed compaction.
• AC-5: Raw prompts, assistant content, thinking, history summaries, tool input, and tool output are omitted by default. Existing explicit content flags may expose only the bounded fields already owned by the shared session-analysis privacy contract.
• AC-6: augment is registered only for the session-analysis capability and is accepted by session-analysis and Harness Inspector help/dispatch. Other host capabilities continue to reject it rather than falling through to another provider.
• AC-7: Focused provider, workspace-isolation, usage/context, host-catalog, Inspector, documentation-link, and package-boundary checks pass. A bounded real-host smoke records the installed version and aggregate evidence without persisting private transcript content.

Non-goals

• Adding an Augment plugin shell, configured-asset inventory, Checkup support, lifecycle mutation, installation instructions, or public Quickstart status.
• Inferring parent/child or subagent ownership from rootTaskUuid, subAgentCreditsUsed, filename proximity, or session timestamps.
• Treating the session-level current model setting as attribution for every historical response.
• Reverse-engineering encrypted thinking, history-summary text, billing data, credits, prices, or remote Augment APIs.
• Claiming Windows, macOS, or Linux native-host verification from deterministic path fixtures alone.

Plan and Tasks

1. Add an Augment platform adapter under scripts/session-analysis/platforms/augment.mjs with a local-home override, bounded JSON discovery, workspace qualification, privacy-safe normalization, and visible malformed-source diagnostics.
2. Register the session-only host identity in the host catalog and capability loader/help surfaces used by session-analysis and Harness Inspector.
3. Add deterministic provider fixtures covering direct/foreign workspaces, Windows paths, usage/context, tool correlation, explicit compaction, missing evidence, malformed JSON, and default privacy behavior.
4. Document the partial support boundary and reproducible read-only commands in the host adapter matrix.
5. Run focused and full validation, then update this spec status only when the recorded evidence supports it.

Test and Review Evidence

• AC-1 through AC-5: npx vitest run test/sessions/session-analysis-augment-provider.test.mjs
• AC-6: npx vitest run test/sessions/session-analysis-providers.test.mjs test/plugins/host-support.test.mjs test/cli/better-harness-cli.test.mjs
• AC-6 and AC-7: focused Harness Inspector tests selected from the changed registration and report path.
• AC-7: node scripts/doc-link-graph/cli.mjs skills/better-harness
• AC-7: npx vitest run test/skills-docs/doc-link-graph.test.mjs
• AC-7: npm test
• AC-7: npm run pack:verify
• AC-7: git diff --check
• AC-7 native smoke: run auggie --version, then read-only sources, sessions, and a bounded Inspector render against the local Augment home; report missing workspace matches as unobserved rather than success.

Implemented evidence on 2026-08-29:

• npm run check passed on Node 24: root 1589 tests, Harness 173 tests, Harness UI 31 tests, Harness Studio 494 tests, generated-source checks, and package verification (607 npm entries; 869 runtime-zip entries).
• The English and Simplified Chinese Docusaurus production builds completed, and the documentation link graph remained current.
• Auggie 0.36.0 (commit 7c61e5bb) exposed six workspace-qualified native sessions in a bounded local smoke. A selected native session projected 26 unique usage nodes as 26 model calls and 29 tool-use nodes as 29 calls.
• A second native session exposed two request-lane history_summary_node records, both normalized as explicit compaction boundaries without summary text.
• The Inspector rendered two native sessions, including user-prompt time, response time, a 200K context window, additive processing lanes, and Usage & Context details. Wide and 390px visual checks had no console errors or horizontal overflow.

Risk notes:

• The local Augment schema is not a public compatibility promise. Unknown node types remain metadata and malformed files produce bounded diagnostics so a future host update degrades visibly.
• A session file can be large. Discovery reads remain file-count bounded and selected-session hydration remains governed by the shared selection limit.
• Workspace folders and terminal cwd may be absent. Such sessions are excluded rather than joined to the requested project by title or prompt content.