feat(session): review wire protocol and daemon mirror derived from the intent vocabulary (Phase 3)

[benvinegar]

Phase 3 of the browser-review rebuild (docs/browser-review-rebuild.md) — the final phase of this run. Stacked on Phase 2 (#721). Phases 4–6 (HTTP surface, browser client, entry points) are deferred; the audit doc now carries a run-boundary note listing exactly what remains open.

What

The wire protocol and the daemon's review mirror — the layer that makes the producer's publications consumable beyond the terminal process, serving the existing hunk session agent surface. Five commits: wire schema → mirror + resources → agent errors → conformance → naming cleanup.

• src/session/reviewProtocol.ts — the wire schema derived from the intent vocabulary (B12): HUNK_REVIEW_ACTION_TYPES = deriveReviewActionTypes(REVIEW_INTENT_TYPES, exclusions) with an empty, documented exclusion list — all twelve intents are wire-reachable, and a wire-reachable intent without a parser fails to compile. Carries expandedLineProof (B10) and a required actor tag (clientId + terminal|browser|agent, G2 wire fields — policy deliberately not applied) from version one, so the browser never needs a schema break. Passes the Phase 0 browser-safe boundary gate.
• src/session/broker/reviewMirror.ts — the daemon mirrors each session's publication with exactly one classifyReviewPublication call (C1 broker site): a publication address plus a resource catalog — no notes, no manifest. The prototype mirrored notes, which is what forced its broker to re-derive anchors (D3, the dropped-fallback-branch bug); not mirroring them makes that duplication impossible rather than merely fixed.
• core/review/resourceAssembly.ts — the single chunk-assembly/verification path (C2 broker site) with an injected hasher; the broker's loop only fetches and decodes. reviewResourceCache.ts bounds daemon-wide bytes with reservations taken before bytes are requested (genuinely bounded in-flight — the prototype bounded only completed bytes), and reservation resize so unmeasured resources don't serialize loads meant to run in parallel.
• Agents get the payoff: hunk session review --include-patch reconstructs patches through bounded resource reads; registrations no longer embed patch text at all (the memory win the resource path exists for), with an older in-process session's inline patches still served unchanged.
• Rung 5 activates: scripts/review-vocabulary.test.ts asserts wire vocabulary ≡ intent vocabulary minus named exclusions, every wire type actually reaches a parser (probed to distinguish "rejected" from "unrouted"), no session module re-declares a review-model constant or hand-writes a digest regex, and MAX_WS_MESSAGE_BYTES ≥ MAX_HUNK_REVIEW_ENVELOPE_BYTES — the one coupling the browser-safe protocol can't express as an import.

The shape, in one diagram

flowchart LR
    subgraph term["Terminal session (producer)"]
        STORE["review store"] --> PROD["ReviewProducer"]
    end
    subgraph daemon["Daemon (loopback only)"]
        MIR["reviewMirror<br/>publication address + resource catalog<br/>ONE classify() call — no notes, no anchors"]
        CACHE["reviewResourceCache<br/>reserved-before-read byte budget"]
        ASM["core resourceAssembly<br/>single verification path, injected hasher"]
        MIR --- CACHE --- ASM
    end
    PROD -- "publishes generation:producer:seq" --> MIR
    AGENT["hunk session CLI<br/>review --include-patch"] -- "bounded chunk reads" --> MIR
    AGENT -- "apply_review_action<br/>{actor, expandedLineProof, …}" --> MIR
    MIR -- "toReviewIntent → producer.applyIntent<br/>(same planner as the keyboard)" --> PROD
    WEB["browser — Phase 5"] -.-> MIR
    subgraph derive["Wire schema is derived, not restated"]
        IV["REVIEW_INTENT_TYPES (core)"] -->|"deriveReviewActionTypes<br/>exclusions: [] (documented)"| WT["HUNK_REVIEW_ACTION_TYPES"]
        WT -->|"parser table keyed by vocabulary<br/>missing parser = compile error"| P["strict parsers on shared validation"]
    end

Loading

Findings repaid (recorded inline in the audit doc)

B10 (wire+producer: ReviewExpandedLineClaim, resolved only by resolveReviewExpandedLine), B12 (derived vocabulary), C1 broker site (one classify), C2 broker site (one assembler), D1 wire site (isTransportableReviewNote is reviewNoteWithinBounds — the every-field-fits/whole-note-fails case now rejected at the wire, pinned by the harness), D3 broker site (repaid by absence; the prototype's rejected-registration case pinned from the wire end), D5 broker/wire sites, G2 wire fields. Wire round-trip and broker mirror registered as conformance consumers over the Phase 2 ordering fixtures.

Behavior notes

• Existing hunk session command output verified byte-identical against a Phase 2 worktree (review --json, --include-patch --json, text mode), via a real TUI session + daemon exercise.
• --include-patch now round-trips to the session; a session that closes mid-read fails with a new, specific agent-facing message (generated skill regenerated via bun run generate:skill).
• Oversized-patch sessions now appear in hunk session list (previously silently rejected at registration) — net improvement, recorded.
• Daemon version 7 → 8; stale daemons restart through the existing capability flow.
• One honest gap recorded for Phase 5: the vocabulary has no draft-body intent, so a remote client can open and save a draft but not type into it — remote note composition is Phase 5's note-editing work.
• apply_review_action has no production caller yet by design (Phase 4/5); it is implemented and tested end-to-end (broker → socket → bridge → producer → intent), not stubbed.

Gates

• bun run typecheck, bun run lint (0/0), bun run format — clean; empty changeset.
• bun test: 2695 pass / 5 fail — strict subset of the Phase 2 baseline's failures (dev-dep ×2 + three known flakes).
• bun run test:integration (PTY): 106/106 (baseline had 1 flake).
• bun test test/session/: 11/11, files untouched (new integration coverage colocated at src/session/broker/reviewResources.integration.test.ts to honor that literally).
• Boundary suite green — reviewProtocol.ts passes the browser-safe gate written for it in Phase 0; vocabulary-derivation suite green.

---

Generated by Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

1 Skipped Deployment

Project	Deployment	Actions	Updated (UTC)
hunk-web	Ignored	Preview	Aug 13, 2026 12:49am

[greptile-apps]

Greptile Summary

The PR introduces the review wire protocol and daemon-side mirror that expose producer publications and digest-verified resources to session clients.

• Derives the complete wire action vocabulary from core review intents and adds strict action parsing.
• Mirrors publication addresses and resource catalogs while applying shared generation-order semantics.
• Adds bounded, single-flight resource reconstruction with digest and chunk verification.
• Routes remote review actions through the existing producer intent planner.
• Moves optional patch delivery from session registration into bounded resource reads while preserving compatibility with older inline registrations.

Confidence Score: 5/5

The PR appears safe to merge; no concrete changed-code failure remained after checking action concurrency, resource bounds, and mirror lifecycle behavior.

Remote stale-action checks use the publication classifier correctly, resource sizes remain below the production cache ceiling with eviction preserving the completed-byte budget, and failure or generation-change paths clean up reservations and prevent obsolete resources from being served.

Important Files Changed

Filename	Overview
src/session/reviewProtocol.ts	Defines the derived wire action vocabulary, strict parsers, actor metadata, expanded-line proofs, and resource catalog envelopes.
src/session/broker/reviewMirror.ts	Maintains one generation-ordered publication and resource catalog per live session.
src/session/broker/reviewResourceCache.ts	Adds generation-qualified LRU storage and pre-read reservation accounting under separate completed and in-flight budgets.
src/session/broker/state.ts	Integrates mirror lifecycle, single-flight chunk loading, digest-verified assembly, cache invalidation, and legacy inline-patch compatibility.
src/core/review/resourceAssembly.ts	Centralizes ordered chunk assembly, progress validation, size enforcement, and final digest verification.
src/session/app/reviewCommands.ts	Validates remote action position and expanded-line evidence before lowering the action into the producer’s existing intent path.
src/session/app/registration.ts	Publishes review resources separately from registration and retains compatibility with older inline-patch sessions.
src/session/broker/brokerServer.ts	Exposes the new review operations through the existing validated loopback daemon surface.
src/ui/hooks/useHunkSessionBridge.ts	Connects current UI review state and producer operations to the expanded session bridge.

Sequence Diagram

sequenceDiagram
    participant Producer as ReviewProducer
    participant Mirror as Daemon ReviewMirror
    participant Cache as Resource Cache
    participant Client as Session Client
    Producer->>Mirror: Publish generation, revision, catalog
    Client->>Mirror: Request review with patch
    Mirror->>Cache: Load generation-qualified resource
    alt cache miss
        Cache->>Producer: Request bounded chunks
        Producer-->>Cache: Chunk envelopes
        Cache->>Cache: Assemble and verify digest
    end
    Cache-->>Client: Reconstructed patch
    Client->>Mirror: Apply review action
    Mirror->>Producer: Validated ReviewIntent
    Producer-->>Mirror: Updated publication

Loading

_{Reviews (1): Last reviewed commit: "refactor(session): name the action resul..." | Re-trigger Greptile}