fix: resolve 14 test failures, add coverage tooling, and align docs with codebase

.github/workflows/prompt-parity.yml

@@ -1,4 +1,4 @@
-name: Prompt Parity
+name: CI
 
 on:
   pull_request:
@@ -8,7 +8,7 @@ on:
       - master
 
 jobs:
-  prompt-parity:
+  test:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
@@ -30,3 +30,11 @@ jobs:
 
       - name: Verify generated prompt artifacts
         run: npm run prompts:check
+
+      - name: Run tests
+        run: npm test
+        working-directory: shadow-agent
+
+      - name: Build
+        run: npm run build
+        working-directory: shadow-agent

.husky/pre-commit

@@ -1,2 +1,4 @@
 #!/usr/bin/env sh
+set -e
 npm run prompts:check
+npm test --prefix shadow-agent

AGENTS.md

@@ -40,6 +40,8 @@ When facing a tradeoff, choose visual quality over faster implementation.
 
 You are not required to use all of them. Mix, augment, or ignore as the moment demands.
 The research docs catalog which specific patterns are worth stealing and how to adapt them.
+`third_party/` is reference material, not product surface area: do not add runtime imports from it,
+and if a checkout is no longer useful after its patterns are absorbed, removing it is fine.
 
 ## Read-Only Constraint (v1)
 

README.md

@@ -8,7 +8,15 @@ Layout:
 - `third_party/sidecar/`: reference clone for runtime and shadow-session patterns
 - `third_party/agent-flow/`: reference clone for ingestion, replay, and visualization patterns
 
-The `third_party` repos are local references. They are intentionally not part of the main repo history.
+How to read this repo:
+- this root `README.md` explains the workspace-level layout and shared tooling
+- `shadow-agent/README.md` explains the app itself: scope, commands, and current behavior
+
+The `third_party` repos are disposable local references.
+- They exist so we can inspect and port patterns into `shadow-agent/`.
+- Product code should not import from them at runtime.
+- Once a pattern has been absorbed or we no longer need the reference checkout, removing it is fine.
+- They are intentionally not part of the main repo history.
 
 Prompt workflow:
 - `prompts/*.json` are the single source of truth

docs/architecture.md

@@ -100,19 +100,24 @@ record tests for drawing semantics plus a small curated set of visual regression
 
 ## Current Status & Roadmap
 
-We are currently transitioning from **Phase 1 (MVP)** to **Phase 2 (Release Candidate)**.
+We are currently in **Phase 2 (Release Candidate)** with inference scaffolding landed
+and the Canvas2D renderer and live capture pipeline still on feature branches.
 
-### Phase 1: Core Foundation (Completed/Merging)
+### Phase 1: Core Foundation (Completed)
 - Canonical event schema and derivation logic.
 - File-based persistence and session replay.
 - Initial Electron shell and React renderer.
 - Base fixture corpus for testing.
-- PRs: #29 (Fixtures), #30 (Observability), #31 (Renderer Tests).
+- Logger, privacy sanitization, and observability seams.
+- Merged via: #29 (Fixtures), #30 (Observability), #31 (Renderer Tests).
 
 ### Phase 2: Live Interaction (In Progress)
-- **Live Event Capture**: `fs.watch` based transcript tailing (PR #27).
-- **Advanced Rendering**: Porting Canvas2D + D3-Force from `agent-flow` (PR #26).
-- **Inference Engine**: OpenCode integration and system prompt triggers (PR #28, #32).
+- **Inference Engine**: Auth loader, context packager, prompt builder (with
+  `ShadowContextPacket` type and `buildUserMessage`), response parser, trigger logic,
+  shadow inference engine orchestrator, direct Anthropic API fallback, and MCP server.
+  Landed on main via PR #28 and #32. OpenCode client not yet implemented.
+- **Live Event Capture**: `fs.watch` based transcript tailing (PR #27 — not yet merged).
+- **Advanced Rendering**: Porting Canvas2D + D3-Force from `agent-flow` (PR #26 — not yet merged).
 - **Integration**: Full end-to-end flow from agent activity to holographic insight.
 
 ### Phase 3+: Advanced Features (Planned)

docs/domain-inference.md

@@ -1,8 +1,10 @@
 # Domain: Inference Engine
 
-> **Status: Implementation Reference** — This document describes the full OpenCode
-> inference engine targeted by PR #28. Current main has `src/inference/prompts.ts` and
-> `src/inference/prompt-builder.ts` scaffolding only.
+> **Status: Partially Implemented** — Current main has auth loader (`auth.ts`), context
+> packager (`context-packager.ts`), prompt builder (`prompt-builder.ts` with
+> `ShadowContextPacket` type and `buildUserMessage`), response parser, inference trigger,
+> shadow inference engine orchestrator, direct Anthropic API fallback, and MCP server.
+> The OpenCode client (`opencode-client.ts`) is not yet implemented.
 
 The inference engine is shadow-agent's brain — it consumes the observed agent's event
 stream and produces structured interpretations (phase, risk, predictions, confidence).
@@ -100,15 +102,15 @@ All tools are `readOnlyHint: true`. Pattern from sidecar's `mcp-server.js`.
 
 ```
 src/inference/
-  auth.ts                — Credential loader
-  opencode-client.ts     — OpenCode server + client
-  context-packager.ts    — Build ShadowContextPacket from DerivedState
-  prompt-builder.ts      — Assemble user message from context packet
-  prompts.ts             — Generated prompt strings from prompts/*.json
-  response-parser.ts     — JSON → ShadowInsight[]
-  trigger.ts             — When to invoke inference
-  shadow-inference-engine.ts  — Orchestrator
-  direct-api.ts          — Anthropic SDK fallback
+  auth.ts                — Credential loader (implemented)
+  opencode-client.ts     — OpenCode server + client (not yet implemented)
+  context-packager.ts    — Build ShadowContextPacket from DerivedState (implemented)
+  prompt-builder.ts      — ShadowContextPacket type, buildUserMessage, buildInferenceRequest (implemented)
+  prompts.ts             — Generated prompt strings from prompts/*.json (implemented)
+  response-parser.ts     — JSON → ShadowInsight[] (implemented)
+  trigger.ts             — When to invoke inference (implemented)
+  shadow-inference-engine.ts  — Orchestrator (implemented)
+  direct-api.ts          — Anthropic SDK fallback (implemented)
 src/mcp/
-  shadow-mcp-server.ts   — MCP server exposing shadow tools
+  shadow-mcp-server.ts   — MCP server exposing shadow tools (implemented)
 ```

docs/getting-started.md

@@ -36,9 +36,11 @@ npm start
 
 ## Project Structure
 
-- `shadow-agent/src/electron/`: Main process code, including IPC handling, session management, and filesystem watching.
-- `shadow-agent/src/renderer/`: React-based UI code, including the Canvas2D visualization engine and D3-Force layout.
-- `shadow-agent/src/shared/`: Code shared between the main and renderer processes (types, utilities, logging).
+- `shadow-agent/src/electron/`: Main process code, including IPC handling, session management, and file loading.
+- `shadow-agent/src/renderer/`: React-based UI code. The full Canvas2D + D3-Force visualization engine is on a feature branch (PR #26); current main uses simplified React panels.
+- `shadow-agent/src/shared/`: Code shared between the main and renderer processes (types, utilities, logging, privacy, transcript parsing, replay store).
+- `shadow-agent/src/inference/`: Shadow inference engine — auth, context packaging, prompt building, response parsing, trigger logic, and Anthropic API fallback. OpenCode client is not yet implemented.
+- `shadow-agent/src/mcp/`: MCP server exposing shadow tools to other agents.
 - `docs/`: Technical documentation, architecture decisions, and project plans.
 
 ## Prompt Workflow

docs/todo.md

@@ -9,42 +9,50 @@
 
 - 2026-04-01: **Implement Phase 2 live transcript watcher** — Build the `shadow-agent/src/capture/` pipeline from `docs/plans/plan-event-capture.md`: session discovery, transcript watcher, incremental parser, normalizer, event buffer, IPC bridge, and session manager. [In Progress - PR #27](https://github.com/Coldaine/AgentVisualCrazy/pull/27)
 
-- 2026-04-01: **Implement inference auth loader** — Create `src/inference/auth.ts`. Copy sidecar's `auth-json.js` pattern. Priority: `process.env` > `~/.shadow-agent/.env` > OpenCode `auth.json`. [In Progress - PR #28](https://github.com/Coldaine/AgentVisualCrazy/pull/28)
+- 2026-04-01: ~~**Implement inference auth loader**~~ — Completed 2026-04-18. `src/inference/auth.ts` implements priority chain: `process.env` → `~/.shadow-agent/.env` → OpenCode `auth.json`. Merged via PR #28.
 
-- 2026-04-01: **Implement OpenCode inference client** — Create `src/inference/opencode-client.ts`. Copy sidecar's `opencode-client.js`. Start server, create session, send prompt, poll completion. [In Progress - PR #28](https://github.com/Coldaine/AgentVisualCrazy/pull/28)
+- 2026-04-01: **Implement OpenCode inference client** — Create `src/inference/opencode-client.ts`. Copy sidecar's `opencode-client.js`. Start server, create session, send prompt, poll completion. Not yet implemented — direct Anthropic API fallback exists as an interim path.
 
-- 2026-04-01: **Build shadow context packager** — Create `src/inference/context-packager.ts`. Takes `DerivedState` + recent events → `ShadowContextPacket`. Token budget ~10k. [In Progress - PR #28](https://github.com/Coldaine/AgentVisualCrazy/pull/28)
+- 2026-04-01: ~~**Build shadow context packager**~~ — Completed 2026-04-18. `src/inference/context-packager.ts` exports `buildContextPacket` and `packContext`. Merged via PR #28.
 
-- 2026-04-01: **Build shadow prompt builder** — Create `src/inference/prompt-builder.ts`. System prompt from `prompts/shadow-system-prompt.json`. User message from context packet. [In Progress - PR #28](https://github.com/Coldaine/AgentVisualCrazy/pull/28)
+- 2026-04-01: ~~**Build shadow prompt builder**~~ — Completed 2026-04-18. `src/inference/prompt-builder.ts` exports `ShadowContextPacket` type, `buildUserMessage`, and `buildInferenceRequest`. Merged via PR #28.
 
-- 2026-04-01: **Wire inference trigger engine** — Create `src/inference/trigger.ts`. Triggers on: N events, 30s timer, risk escalation, specific event kinds. [In Progress - PR #28](https://github.com/Coldaine/AgentVisualCrazy/pull/28)
+- 2026-04-01: ~~**Wire inference trigger engine**~~ — Completed 2026-04-18. `src/inference/trigger.ts` implements event-count, time, and specific-event triggers. Merged via PR #28.
 
-- 2026-04-01: **Wire inference engine** — Create `src/inference/shadow-inference-engine.ts`. Connects trigger → context packager → prompt builder → OpenCode/direct API → response parser → ShadowInsight events. [In Progress - PR #28](https://github.com/Coldaine/AgentVisualCrazy/pull/28)
+- 2026-04-01: ~~**Wire inference engine**~~ — Completed 2026-04-18. `src/inference/shadow-inference-engine.ts` orchestrates trigger → context → prompt → client → parser. Merged via PR #28.
 
-- 2026-04-01: **Build shadow MCP server** — Create `src/mcp/shadow-mcp-server.ts`. Tools: `shadow_status`, `shadow_events`, `shadow_ask`. stdio transport.
+- 2026-04-01: ~~**Build shadow MCP server**~~ — Completed 2026-04-18. `src/mcp/shadow-mcp-server.ts` exposes `shadow_status`, `shadow_events`, `shadow_ask`. Merged via PR #28.
 
-- 2026-04-01: **Implement direct Anthropic API fallback** — Create `src/inference/direct-api.ts`. Fallback when OpenCode not available. [In Progress - PR #28](https://github.com/Coldaine/AgentVisualCrazy/pull/28)
+- 2026-04-01: ~~**Implement direct Anthropic API fallback**~~ — Completed 2026-04-18. `src/inference/direct-api.ts` implements `InferenceClient` using `@anthropic-ai/sdk`. Merged via PR #28.
 
 ## Observability
 
-- 2026-04-12: **Harden logger behavior and sinks** — Add explicit Error serialization, configurable log levels via environment, and durable file-write backpressure/rotation policies for `shadow-agent/src/shared/logger.ts`. [In Progress - PR #30](https://github.com/Coldaine/AgentVisualCrazy/pull/30)
+- 2026-04-12: ~~**Harden logger behavior and sinks**~~ — Completed 2026-04-18. Structured logger with level filtering, memory ring, file sink, redaction, and circular-reference handling. Merged via PR #30.
 
-- 2026-04-12: **Finish instrumentation coverage** — Extend logging across capture, IPC, inference, and persistence boundaries with consistent event names and redacted context payloads. [In Progress - PR #30](https://github.com/Coldaine/AgentVisualCrazy/pull/30)
+- 2026-04-12: **Finish instrumentation coverage** — Extend logging across capture, IPC, inference, and persistence boundaries with consistent event names and redacted context payloads. [Partially done — core seams instrumented; capture pipeline not yet on main]
 
 ## Documentation
 
 - 2026-04-01: **Enable GitHub Issues** on the AgentVisualCrazy repo (currently disabled) and create issues for each implementation task above.
 
 ## Testing
 
-- 2026-04-12: **Expand Phase 1 edge coverage** — Add transcript-adapter, derive, replay-store, and persistence edge/corruption tests plus one transcript -> canonical events -> derive integration test. [In Progress - PR #29](https://github.com/Coldaine/AgentVisualCrazy/pull/29)
+- 2026-04-12: ~~**Expand Phase 1 edge coverage**~~ — Completed 2026-04-18. Transcript-adapter, derive, replay-store, and persistence edge/corruption tests plus integration tests. Merged via PR #29.
 
-- 2026-04-12: **Add Phase 2 capture tests before shipping the watcher** — Cover incremental parsing, session discovery, ring buffer behavior, temp-file append/truncation/rotation, and session-manager integration with fake IPC. [In Progress - PR #27](https://github.com/Coldaine/AgentVisualCrazy/pull/27)
+- 2026-04-12: **Add Phase 2 capture tests before shipping the watcher** — Cover incremental parsing, session discovery, ring buffer behavior, temp-file append/truncation/rotation, and session-manager integration with fake IPC. [Blocked — capture pipeline not yet on main]
 
-- 2026-04-12: **Add Electron and renderer contract tests** — Cover preload bridge API drift, main-process replay/export behavior, and renderer busy/error/open/export state transitions. [In Progress - PR #31](https://github.com/Coldaine/AgentVisualCrazy/pull/31)
+- 2026-04-12: ~~**Add Electron and renderer contract tests**~~ — Completed 2026-04-18. Preload bridge API, main-process replay/export, and renderer state machine tests. Merged via PR #31.
 
-- 2026-04-12: **Add inference contract tests with a fake client** — Cover context packing, prompt building, parser fallback, trigger thresholds, and orchestrator behavior with no live model dependency in CI. [In Progress - PR #32](https://github.com/Coldaine/AgentVisualCrazy/pull/32)
+- 2026-04-12: ~~**Add inference contract tests with a fake client**~~ — Completed 2026-04-18. Context packing, prompt building, parser fallback, trigger thresholds, and `FakeInferenceClient`. Merged via PR #32.
 
-- 2026-04-12: **Add Canvas2D command tests and selective visual regressions** — Protect node/edge/particle semantics with a recorded 2D context and add a small curated screenshot suite for canonical scenes. [In Progress - PR #26](https://github.com/Coldaine/AgentVisualCrazy/pull/26)
+- 2026-04-12: **Add Canvas2D command tests and selective visual regressions** — Protect node/edge/particle semantics with a recorded 2D context and add a small curated screenshot suite for canonical scenes. [Blocked — Canvas2D renderer not yet on main]
 
-- 2026-04-12: **Maintain a shared replay fixture corpus** — Store representative transcript/replay fixtures under `shadow-agent/tests/fixtures/` for parsing, derive, renderer, and inference regression coverage. [In Progress - PR #29](https://github.com/Coldaine/AgentVisualCrazy/pull/29)
+- 2026-04-12: ~~**Maintain a shared replay fixture corpus**~~ — Completed 2026-04-18. Transcript and replay fixtures under `shadow-agent/tests/fixtures/`. Merged via PR #29.
+
+## Infrastructure
+
+- 2026-04-19: **Fix broken test suite on main** — `buildUserMessage` and `ShadowContextPacket` were imported from generated `prompts.ts` but never exported; `packContext` was imported from `context-packager.ts` but didn't exist. Fixed by moving `ShadowContextPacket` and `buildUserMessage` to `prompt-builder.ts` and adding `packContext` to `context-packager.ts`. See branch `fix/test-remediation-and-docs-consistency`.
+
+- 2026-04-19: **Add test execution to CI** — The `prompt-parity.yml` workflow only checked prompt sync. Updated to also run `npm test` and `npm run build`. See branch `fix/test-remediation-and-docs-consistency`.
+
+- 2026-04-19: **Add test execution to pre-commit hook** — The Husky pre-commit hook only ran `prompts:check`. Updated to also run `npm test`. See branch `fix/test-remediation-and-docs-consistency`.

shadow-agent/.gitignore

@@ -2,3 +2,4 @@ dist/
 dist-electron/
 node_modules/
 
+coverage/

shadow-agent/README.md

@@ -2,6 +2,9 @@
 
 `shadow-agent` is a passive observer for agent sessions.
 
+This README is for the app inside the larger workspace. For workspace layout, shared tooling,
+and the role of `third_party/`, see the repo-root [README.md](../README.md).
+
 It combines:
 - Sidecar-style separation between the observed agent and a secondary shadow runtime
 - Agent Flow-style event ingestion, replay, and visualization