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

AGENTS.md

@@ -16,14 +16,16 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript,
 - **Typecheck:** `npm run typecheck`
 - **Guards:** `npm run check:all` (every guard, one table) / `npm run check:delta` (only what your change added, against the merge-base)
 - **Worktree setup:** `npm run worktree:provision` — checks out the submodules and makes `node_modules` resolvable, so guards and tests measure the worktree you are editing
+- **A worktree is named for the branch it holds.** `.worktrees/workflow/353-context-scoped-delivery` holds `workflow/353-context-scoped-delivery` — the branch name in full, slashes and all, as nested directories. `git worktree list` then reads as a branch index, and a path in a command or a stack trace says which branch it belongs to without anyone inspecting its `HEAD`. Rename with `git worktree move`, which fixes the administrative files a `mv` leaves dangling.
 - **Workflow data:** `git worktree add ./workflows workflows` (see [README.md](README.md), [setup.md](setup.md), [stdio.md](stdio.md), [http.md](http.md)).
 
 ## Code and doc style
 
 - TypeScript; follow existing patterns in `src/` and `schemas/`.
 - Use clear, professional language; no process attribution in code comments (e.g. “Added by agent”).
-- **Describe the design, not the change to it.** Definitions (workflow, activity, technique, resource prose), code comments, doc comments, and **commit subjects** state the system as it is. A reader next year has no memory of the previous design, so naming it makes them learn it just to parse the sentence. Write `account for token usage per dispatch`, not `move usage accounting off the transition and onto the dispatch`; write `cost travels on its own call`, not `a transition can only account for a dispatch it exits`. Same for a value's absence: say what holds when it is missing, not what the old path did.
-  - **PR and issue bodies are the exception.** They exist to explain a change against what preceded it, and stop being read once merged — a reviewer needs the before-state to judge the change. Keep the narrative there and out of everything that persists.
+- **Describe the design, not the change to it.** Definitions (workflow, activity, technique, resource prose), code comments, doc comments, and **commit subjects** state the system as it is, in the present tense, without naming the design they replaced. A reader next year 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 the moment the thing it contrasts against is gone. Write `account for token usage per dispatch`, not `move usage accounting off the transition and onto the dispatch`; write `cost travels on its own call`, not `a transition can only account for a dispatch it exits`. Same for a value's absence: say what holds when it is missing, not what the old path did. Cut “instead of”, “no longer”, “previously”, “unchanged behaviour”, and any example that was true before the change and false after it. The workflow canon states the same discipline for definition prose as [Document in Positive Present](workflows/workflow-design/resources/design-principles.md#17-document-in-positive-present).
+  - **Keep a hazard that is still live, stated as an invariant.** *A marker is unreadable to a context that never received the bytes* survives; *this is why the old rule forbade it* does not.
+  - **PR and issue bodies are the exception, and so is a commit body.** They exist to explain a change against what preceded it, and stop being read once merged — a reviewer needs the before-state to judge the change. Keep the narrative there and out of everything that persists. A measurement that is a tool's reason to exist may likewise be cited with its provenance.
   - After a behaviour change, sweep for surviving descriptions of the old behaviour: doc comments, tool descriptions, technique `## Rules`, resource prose, READMEs. A grep for the old phrasing finds most of them; a stale claim reads as current fact.
 - **Prefer removing the thing that needs a prohibition.** When a change leaves prose warning "do not also use X", that usually means two paths now do one job. Retire one and the warning has nothing left to say — along with any validation or edge-case handling that existed only to police the overlap.
 - **Keep `CLAUDE.md` and `AGENTS.md` in sync by merging, never by copying.** They have diverged before, each gaining content the other lacked; overwriting one with the other silently drops the difference.

CLAUDE.md

@@ -16,14 +16,16 @@ This repo is an **MCP server** for AI agent workflow orchestration (TypeScript,
 - **Typecheck:** `npm run typecheck`
 - **Guards:** `npm run check:all` (every guard, one table) / `npm run check:delta` (only what your change added, against the merge-base)
 - **Worktree setup:** `npm run worktree:provision` — checks out the submodules and makes `node_modules` resolvable, so guards and tests measure the worktree you are editing
+- **A worktree is named for the branch it holds.** `.worktrees/workflow/353-context-scoped-delivery` holds `workflow/353-context-scoped-delivery` — the branch name in full, slashes and all, as nested directories. `git worktree list` then reads as a branch index, and a path in a command or a stack trace says which branch it belongs to without anyone inspecting its `HEAD`. Rename with `git worktree move`, which fixes the administrative files a `mv` leaves dangling.
 - **Workflow data:** `git worktree add ./workflows workflows` (see [README.md](README.md), [setup.md](setup.md), [stdio.md](stdio.md), [http.md](http.md)).
 
 ## Code and doc style
 
 - TypeScript; follow existing patterns in `src/` and `schemas/`.
 - Use clear, professional language; no process attribution in code comments (e.g. “Added by agent”).
-- **Describe the design, not the change to it.** Definitions (workflow, activity, technique, resource prose), code comments, doc comments, and **commit subjects** state the system as it is. A reader next year has no memory of the previous design, so naming it makes them learn it just to parse the sentence. Write `account for token usage per dispatch`, not `move usage accounting off the transition and onto the dispatch`; write `cost travels on its own call`, not `a transition can only account for a dispatch it exits`. Same for a value's absence: say what holds when it is missing, not what the old path did.
-  - **PR and issue bodies are the exception.** They exist to explain a change against what preceded it, and stop being read once merged — a reviewer needs the before-state to judge the change. Keep the narrative there and out of everything that persists.
+- **Describe the design, not the change to it.** Definitions (workflow, activity, technique, resource prose), code comments, doc comments, and **commit subjects** state the system as it is, in the present tense, without naming the design they replaced. A reader next year 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 the moment the thing it contrasts against is gone. Write `account for token usage per dispatch`, not `move usage accounting off the transition and onto the dispatch`; write `cost travels on its own call`, not `a transition can only account for a dispatch it exits`. Same for a value's absence: say what holds when it is missing, not what the old path did. Cut “instead of”, “no longer”, “previously”, “unchanged behaviour”, and any example that was true before the change and false after it. The workflow canon states the same discipline for definition prose as [Document in Positive Present](workflows/workflow-design/resources/design-principles.md#17-document-in-positive-present).
+  - **Keep a hazard that is still live, stated as an invariant.** *A marker is unreadable to a context that never received the bytes* survives; *this is why the old rule forbade it* does not.
+  - **PR and issue bodies are the exception, and so is a commit body.** They exist to explain a change against what preceded it, and stop being read once merged — a reviewer needs the before-state to judge the change. Keep the narrative there and out of everything that persists. A measurement that is a tool's reason to exist may likewise be cited with its provenance.
   - After a behaviour change, sweep for surviving descriptions of the old behaviour: doc comments, tool descriptions, technique `## Rules`, resource prose, READMEs. A grep for the old phrasing finds most of them; a stale claim reads as current fact.
 - **Prefer removing the thing that needs a prohibition.** When a change leaves prose warning "do not also use X", that usually means two paths now do one job. Retire one and the warning has nothing left to say — along with any validation or edge-case handling that existed only to police the overlap.
 - **Keep `CLAUDE.md` and `AGENTS.md` in sync by merging, never by copying.** They have diverged before, each gaining content the other lacked; overwriting one with the other silently drops the difference.

docs/api-reference.md

@@ -47,7 +47,7 @@ Require `session_index`. Workflow identity comes from the session.
 |------|------------|---------|-------------|
 | `get_workflow` | `session_index` | Orchestrator technique bundle + workflow stubs | Orchestrator load: rules, variables, `initialActivity`, activity list. [Resolution](resource_resolution_model.md) |
 | `next_activity` | `session_index`, `activity_id`, manifests? | `activity_id`, `name`; trace in `_meta` | Advance to an activity (does not return its body). [Fidelity](workflow-fidelity.md) |
-| `get_activity` | `session_index`, `context_tokens`, `bundle?` | Worker bundle + activity body | Worker load for the current activity. `context_tokens` is required. [Bundling](resource_resolution_model.md#12-hybrid-technique-bundling) |
+| `get_activity` | `session_index`, `context_tokens`, `agent_id?`, `bundle?` | Worker bundle + activity body, `_meta.dispatch` | Worker load for the current activity. `context_tokens` is required; `agent_id` scopes delivery to this worker context. [Bundling](resource_resolution_model.md#12-hybrid-technique-bundling) · [Reference delivery](resource_resolution_model.md#11-reference-delivery) |
 | `yield_checkpoint` | `session_index`, `checkpoint_id` | `yielded` or `replayed` | Pause for a user decision (or replay a prior answer). [Checkpoints](checkpoint_model.md) |
 | `resume_checkpoint` | `session_index` | Status | Worker continues after the checkpoint is resolved. |
 | `present_checkpoint` | `session_index` | Message, options, effects | Load the active checkpoint for the user. |
@@ -57,8 +57,8 @@ Require `session_index`. Workflow identity comes from the session.
 
 | Tool | Parameters | Returns | Description |
 |------|------------|---------|-------------|
-| `get_technique` | `session_index`, `step_id?`, `full?` | Composed technique (or unchanged marker) | Load one technique on demand. [Resolution](resource_resolution_model.md) |
-| `get_resource` | `session_index`, `resource_id`, `full?` | Resource body (or unchanged marker) | Load reference material by slug (`workflow/id` or `#section`). |
+| `get_technique` | `session_index`, `step_id?`, `agent_id?`, `bundle?`, `full?` | Composed technique (or unchanged marker) | Load one technique on demand. [Resolution](resource_resolution_model.md) · [Reference delivery](resource_resolution_model.md#11-reference-delivery) |
+| `get_resource` | `session_index`, `resource_id`, `agent_id?`, `bundle?`, `full?` | Resource body (or unchanged marker) | Load reference material by slug (`workflow/id` or `#section`). |
 
 ### Trace
 

docs/development.md

@@ -201,6 +201,12 @@ Run `npm test -- --run` for the live count and pass/fail summary.
 - **MCP Testing:** Uses `InMemoryTransport` for integration tests
 - **Schema Validation:** Tests all Zod schemas with valid/invalid inputs
 
+### Dispatch overhead benchmark
+
+[`scripts/run-dispatch-benchmark.ts`](../scripts/run-dispatch-benchmark.ts) (`npm run bench:dispatch`) prices a **re-dispatch**, where `bench:token` prices a session mode. For each sampled activity it runs two passes against the same worker `agent_id` — a fresh spawn (full delivery) and the same context resumed (`bundle: "reference"`) — fetching the activity payload plus every step-bound technique in both, so the pair is what a second cold dispatch would pay against what reusing the context pays. Figures come from the server's own `activity_dispatched` / `technique_fetched` / `technique_bundled` / `resource_fetched` events, so `chars` is the server's accounting and not the script's estimate.
+
+Stdout is one JSON object with per-activity fresh/resume characters and the aggregate `savingPct`; stderr carries a one-line summary and names any activity that failed to record a fresh/resume dispatch pair. `--gate --min-saving-pct=<n>` turns the saving into an exit-3 gate.
+
 ### Token delivery benchmark
 
 [`scripts/run-token-benchmark.ts`](../scripts/run-token-benchmark.ts) measures payload-char and history/ledger cost for a fixed headless walk (`work-package` / e2e `skip-optional`), comparing `context_mode: fresh` vs `persistent` and resource reference delivery. It reuses the e2e harness/walker and probes `get_resource` for linked + hot templates (the robot walker does not call `get_resource` on its own).