Story-2170: Wave B app sender — the ACP stamps where counsel is standing

A matter's pinned ContextBundle is matter-wide. But counsel is on one page, reading one document, and their question is about that document. Wave B closes that gap: the app tells the broker which surface counsel is viewing, so Mira can say Counsel is viewing: Order_S.17.pdf and the broker can float that document's cards, chunks and assertions to the front of the same pinned bundle.

pramaan-functions already shipped the receiving half. This story is the sender.

The load-bearing discovery: this contract is not in src/gen, and it never will be

The obvious first move — grep surface_context openapi/ src/gen/ — returns nothing, which reads like "the mirror is stale, run pnpm codegen". That is a trap. The field rides a WebSocket message model (router_ws.WebSocketClientMessage), not an HTTP DTO, so make openapi produced no snapshot diff — exactly as pramaan-functions #600 reported. There is nothing to codegen and no mirror to sync.

The brief also credits fn#600 (Story-2152). #600 added SurfaceContext, AgentInvoke.surface_context and the document-first bundle scoping. The WS boundary field the app actually fills arrived in fn#612 (Story-2171). Both are on main, and — checked, not assumed — both are inside the deployed artifacts.

Two casings meet on this wire, and both are load-bearing

Both failure modes are silent, and one is severe. A mis-cased outer key is rejected outright — and per Story-2181 / Bug-2210 a rejected launch renders as endless "thinking". A mis-cased inner key is simply ignored, so document-first scoping quietly never happens. Neither surfaces an error. Hence a test that pins the literal wire keys, not just the happy path.

The matterId trap — Bug-2210, one layer down

The CPC store hands us the live route params, so the lazy move is to snake_case them all: documentId → document_id, matterId → matter_id. That would have been a bug, and a silent one.

The [matterId] route segment is the per-firm matter number (e.g. 13), not the matter UUID the brain keys on. The app's own generated contract says so outright:

deep_link contract v1: /matters/{matter_number}/record/doc/{document_id}
  … the shipped matter.record.doc permalink route, whose [matterId]
    segment is the per-firm matter_number.
                                     — src/gen/zod/citeResolutionSchema.ts

This is precisely the shape of Bug-2210 ("key the Mira rail on the matter UUID, not the route param"). And the broker coerces with UUID(str(raw)), degrading to None on junk — so a wrong id would not error, it would just stop working. So the map is explicit and narrow:

const CONTRACT_PARAMS = { documentId: "document_id" };  // matterId deliberately absent

[documentId] is the document UUID (same contract line), so it maps cleanly. The broker already receives the real matter UUID on the launch envelope; it does not need ours.

One seam, not three

Three rails send launches — the wizard intake rail, the Atlas dock-chat rail, and Mira's converse/command rails. All three inject only a builder into the same agent-agnostic AgentRailConnection. So the stamp goes at the single launch() send site rather than into each builder:

const cpc = useCpcStore.getState();
socket.send(JSON.stringify(
  stampSurfaceContext(this.buildLaunch({ … }), {
    surfaceKey: cpc.active?.key ?? null,
    params: cpc.params,
  }),
));

• Read at send time, not prime time. The surface is whatever page counsel is on when they hit send — not whatever page the connection was created on.
• Launches only. query/cancel/resume go out through a separate query() method and stay clean. AgentCommand treats surface_context as a launch-only field and rejects it on non-launch commands — so this separation is not stylistic, it is required. There is a test for it.
• Fail-open. No active surface → the key is omitted and the message is byte-identical to today's, matching how memory_pack and context_bundle already behave.

Lighting up the Counsel Control Bar

Story-2168 shipped the CCB's Explain and What this means for us verbs deliberately dimmed, with a comment: present-but-dimmed ("wired next") until the Wave B app sender lands. This is that sender, so the verbs go live and the wiredNext badge is deleted rather than left to lie.

The CCB lives inside the document reading surface; Mira's rail lives in the layout-mounted Agent Dock. They never see each other's React tree — but they share the module-scoped rail registry, so useAskMira() reaches the same live connection the Dock already primed, by matter UUID. No prop drilling, no second socket, no duplicated chat state.

The selected passage rides as the quoted anchor of a counsel turn (clamped to 1,200 chars — the document is already in Mira's bundle, so the quote is an anchor, not the payload). The surface stamp attaches automatically at the launch seam; the CCB never knows about it.

useAskMira() returns null off a matter shell, and the verb then renders dimmed rather than as a button that silently does nothing — the Story-2181 discipline: a dead affordance never dresses up as a live one.

What ships

Verification

Unit tests prove the shape we intended. They cannot prove the deployed Pydantic model accepts it. So the exact message the sender now emits was validated against the real broker models (WebSocketClientMessage, AgentCommand, _surface_document_id):

1. camelCase `surfaceContext` ACCEPTED by extra='forbid' envelope; inner snake_case parsed.
2. Broker `_surface_document_id` extracts the document UUID -> doc-first scoping arms.
3. Non-document surface -> no document_id -> bundle unchanged.
4. Absent surfaceContext -> None (fail-open, unchanged).
5. `query` + surface_context REJECTED -> confirms we must stamp launches only.
6. A mis-cased outer key is REJECTED outright (extra='forbid') -> casing is load-bearing.
7. All 40 app surface keys accepted by the broker's surface_key validator.

Check 7 matters because a surface_key failing ^[a-zA-Z0-9][a-zA-Z0-9_.-]*$ would 400 the launch; all 40 registry keys pass.

Local: pnpm lint (0 errors), tsc --noEmit clean, pnpm test — 1082 passed / 175 files, pnpm build clean, pnpm check:routes — registry fresh (40 surfaces).