feat(delivery): context-scoped delivery ledger, dispatch accounting, checkpoint-entry guard (#353 server)

[m2ux]

Server half of #353 (§1.1–§1.4), plus §2.3's pointer bump and walk re-baseline.

Review this first; merge it second. The corpus PR is #355 (workflow/353-context-scoped-delivery → workflows). The second commit here bumps the gitlink to it, which is what makes the split safe: the corpus reaches the server only through that pointer, so the relaxed delivery rule is never live without the context-scoped ledger underneath it. It is also mechanically necessary — CI runs the guards against the pinned commit, and §1.4's new guard rejects four activities in the corpus this tree pinned before the bump.

§1.1 — scope the delivery ledger to a worker context

deliveredHash read state.deliveredContent[state.agentId], and a dispatched worker authenticates against the orchestrator's session_index. Every worker of a session therefore shared one ledger, and reference delivery on a worker session would have handed worker B unchanged-markers for content worker A received. workers-need-full-delivery was a correct guard over a ledger that could not distinguish worker contexts.

The three delivery tools now take an optional agent_id naming the calling agent context, and the ledger keys on that (deliveryScope in src/utils/delivery.ts) instead of the session agent:

• fresh spawn → empty ledger → full delivery (unchanged behaviour)
• same agent_id resumed → its own ledger → unchanged-references (the win)
• sibling worker → its own empty ledger → unaffected either way
• omitted → the session's agent, so solo persistent walks keep their exact ledger shape

It scopes the ledger only and never rebinds session.agentId (asserted on disk in the tests). force-full-after-summarization (bundle: "full" / full: true) remains the escape for a resume that did not preserve context.

Convention over invention: deliveredContent was already keyed by agent id, start_session / dispatch_child already take an agent_id, and the corpus already mints a worker agent_id per dispatch and binds it into the spawn stub. Nothing new was named; the existing identity simply now reaches the wire. No session-schema change.

§1.2 — per-call reference opt-in on get_technique / get_resource

Both gated on state.contextMode === 'persistent' alone, so a resumed worker could not dedup the 86 technique and 30 resource deliveries that run paid for. Both now accept bundle: 'reference' | 'full', mirroring get_activity. full: true still overrides, and the contextMode default path is untouched.

§1.3 — ledger the invisible third

Gap	Instrument
activity_usage fired 11 times against 33 dispatches	activity_dispatched — one event per dispatched context arriving, { agentId, dispatch: "fresh" | "resume", chars }, echoed on _meta.dispatch. The discriminator is derived (does this scope already have a dispatch event for this activity?), so no orchestrator cooperation is required and it cannot be under-reported by an orchestrator that forgets to relay. projectHistory.byType therefore already tallies dispatches.
Delivery events carried no magnitude	technique_fetched / technique_bundled / resource_fetched carry chars — the FULL payload size on both delivery paths — and delivery: "full" | "unchanged". Delivered and saved characters are both summable, so the planning folder's payload figures stop being estimates.
Out-of-band dispatches invisible	An out-of-band worker mints its own agent_id, so its first server call of any kind records the dispatch. The prism run that cost 176,215 tokens and produced CR-0 and B7 would now leave a record without calling get_activity at all.

§1.4 — guard: a checkpoint may not be an activity's first step

scripts/check-checkpoint-entry.ts, registered in scripts/guards.ts so check:all and CI pick it up without editing the workflow file. A when/condition gate does not exempt a first-step checkpoint: a gate that is usually true is the same wasted dispatch and the remedy is the same relocation. It found four violations, not the one the issue named.

Verification

The success criteria call for re-running a comparable walk — a ~4h, ~4M-token exercise. Standing in for it, deterministically and in-process:

npm run bench:dispatch (new, scripts/run-dispatch-benchmark.ts) measures the axis this issue is about, which bench:token does not: per activity, a fresh worker dispatch against the same worker resumed, fetching the activity payload plus every step-bound technique in both passes. Figures are read from the server's own history events, so they are the server's accounting rather than the script's estimate. Over 6 work-package activities:

freshPass  1,115,373 chars
resumePass   403,934 chars      → 63.8% of delivery characters no longer resent
dispatchEvents { fresh: 6, resume: 6 }

The resume pass is not zero, and honestly so: reference delivery ships eager resource bodies that full delivery replaces with resource_refs (#322/#323 T1), so the first resume takes on payload the fresh pass never sent — the 63.8% is net of that.

Tests (+19, all green):

• tests/reference-delivery.test.ts — a fresh scope gets full delivery even when it asks for references; the same scope resumed gets references; worker B never receives worker A's markers (the actual defect §1.1 fixes); bundle/full precedence on technique and resource fetches; the on-disk ledger keys on the passed id with session.agentId untouched.
• tests/fetch-observability.test.ts — fresh-then-resume dispatch events with chars strictly decreasing; a second worker reads as its own fresh dispatch; an out-of-band dispatch that only ever fetches a technique records exactly one event, not one per call; chars + delivery on every delivery event, with the collapsed pass reporting the same magnitude it saved.
• tests/checkpoint-entry-guard.test.ts — hard zero over the real corpus, plus fixtures in both directions and a gated-checkpoint case; an empty corpus throws rather than passing vacuously.

Suite and guards: 757 pass, 18/18 guards. One pre-existing failure is unrelated and reproduces identically on untouched main — tests/session-crypto.test.ts expects EACCES from mkdir / and this sandbox returns ENOENT.

§2.3 — pointer bump and re-baseline (second commit)

workflows → the #355 corpus commit, with npm run baseline:stamp and the refreshed corpus-sha.json + snapshot.test.ts.snap in the same commit. The snapshot delta is the checkpoint relocation and nothing else. One walk row flips warning → valid: that is a pre-existing off-by-one in manifest attribution — the manifest submitted on the call entering an activity carries the exited activity's steps and is validated against the entered one, so removing validate's entry checkpoint removed one spurious "missing steps in manifest" warning. The equivalent warning from post-impl-review's file-index-table still stands. Diagnosed rather than absorbed; worth its own issue, deliberately not widened into this one.

Authoring rule (second commit)

AGENTS.md § Code and doc style gains "describe the design, not the change to it" — definitions, code comments, doc comments and commit subjects state what the system is and why it holds, in the present tense, without naming the design they replaced. A reader a year from now has no memory of the previous design, so naming it makes them learn a dead design just to parse the sentence, and the sentence rots once the thing it contrasts against is gone.

Two failures in this change were the worked examples, both now fixed here: deliveryScope's doc comment explained the ledger by way of the rule it replaced, and the checkpoint-entry guard header's worked example was an activity this same change had already fixed — a reader would have grepped for it and found nothing. Live hazards survive the rule, stated as invariants rather than history: a marker is unreadable to a context that never received the bytes is the design; this is why the old rule forbade it is the change.

The workflow canon already states the same discipline for definition prose as Document in Positive Present; this gives the server tree its half. The corpus PR's definition prose was swept against it too.

Docs

resource_resolution_model.md §11 rewritten around agent-context scoping, with the dispatch-accounting and delivery-magnitude contracts; api-reference.md tool rows; workflow-fidelity.md Layer 5 magnitude clause; development.md gains the dispatch-benchmark section. Generated site regions rebuilt.

Not in scope

Trace-token emission, artifact handoff digests, repo-binding waste, packaged execution manifests, and splitting post-impl-review all stay excluded per the issue's own table.

🤖 Generated with Claude Code