@treeseed/dsh-chapters 0.2.1 → 0.2.2

package/docs/contract.md

@@ -406,6 +406,56 @@ Entry `apply(ctx, config)`. Build with `tsc -p tsconfig.json` and **build before
 UI (later phase) additionally needs `dsh.client` and a `tsdown.client.config.ts` — see
 `dsh-session-fork/package.json` for the shape.
 
+### An armed goal has no rest state — measured, with the lines that prove it
+
+Verified while trying to make a goal-bearing tape leg deterministic (#138). The round driver gates on
+`phase === 'active' && activation === 'armed'` plus agent idleness
+(`@deepseek-ai/dsh-goal-round-driver` `src/index.ts:105-117`), and a round is itself a turn — so every round ends, and
+the next is scheduled. There is no moment in which an armed goal is also at rest:
+
+- **spending the budget ends the goal.** At `:182-188`, `roundsStarted >= maxGoalRounds` calls
+  `ctx.goals.block(agent, ref, { code: 'round-limit', message: 'Goal reached its configured limit of N rounds.' })`.
+- **the strip then disappears.** `@deepseek-ai/dsh-client-ui-goal` `GoalBar.tsx:85-86`: *"Loading, absent, and complete
+  goals have no strip at all"*, and the guard excludes blocked/complete. So the control a test wants to observe
+  (`Pause goal` → `Resume goal`) is not rendered in the state the budget produces.
+- **the per-goal budget is a plugin argument, not a user one.** `ctx.goals.create(agent, { objective, maxGoalRounds })`
+  (`@deepseek-ai/dsh-goal` `src/index.ts:303`, `types.ts:28-30`) — the human `/goal` command passes no budget
+  (`dsh-command-goal` usage is `goal <objective>, /goal clear`; `command-goal/src/index.ts:150` calls `create` without
+  one), so the default 256 applies.
+
+Consequences for this repo, both measured: a goal-bearing tape leg agrees with a runner only while the runner's latency
+happens to reproduce the capture's round count (staging's `prompt` leg failed twice on docs-only pushes:
+`MISS tape=prompt entries=23 storedCandidates: []`, runs 40697174778 / 40706037817); and bounding the budget to 1 makes
+the goal vanish before a leg can act on it (17-entry tape, `Round: 1/`, no second round, `the host goal bar appears once
+a goal exists`). Upstream's own test fixture takes the third path — create then `ctx.goals.disarm(agent)`, noting
+*"An armed goal makes the shipped goal-round-driver start a round at idle, racing the test driver's disposal"* — which
+is the disarmed state, not the armed one a displacement claim needs.
+
+What is needed to test this in a tape: a way to open an **armed** goal whose driver will not fire until released, or a
+non-terminal exhausted state that still renders the control (#138). Until then the goal/suggestion interplay is
+verified live under a wall-clock bound (`tests/e2e/prompt-goal-live.spec.ts`), not by the model-free acceptance job.
+
+### A profile patch may not re-declare a host plugin's row — measured on 0.2.0-rc.2
+
+`profiles/web/cordis.patch.yml` layers by row `id`, and the rig relies on that for its **own** rows
+(`preset-chapters`, `agent-preset-registry`, `llm-pi-ai`, `agent-default-model`, `llm-gate`,
+`fetch-timeouts`). Copying that trick onto a row that belongs to the installed bundle is not neutral. Three variants,
+each run against an unchanged spec and corpus so the only variable was the patch:
+
+| profile patch | result |
+|---|---|
+| `- id: goal` + `config: { defaultMaxGoalRounds: 1 }` | the `goal` plugin stops working: `/goal` creates no goal, so `[data-goal-bar]` never renders |
+| `- id: goal` with **no** config | every test passes, but the boot issues a request no tape has: `MISS tape=prompt entries=23 messages=1 closest=0000.json` — at the FIRST message, before any goal exists |
+| no `goal` row in the profile patch | clean run (`5 passed`, rc 0) |
+
+Read it as: duplicating a host row changes the mounted plugin set (extra registration → an extra request), and adding a
+`config:` block to that duplicate replaces the base row rather than merging into it, taking the plugin's real config
+surface with it. So the patch is a way to configure **rows you own**, not a way to reach into a host plugin's settings.
+The concrete consequence: `@deepseek-ai/dsh-goal` does export
+`config = z.object({ defaultMaxGoalRounds: z.number().default(256) })` and `resolveCreateGoal(request,
+defaultMaxGoalRounds)` honors it, but no boot can pin it from the profile — which is why goal-round bounding is a host
+ask (#138) and not a rig bug to fix.
+
 ### Presets are declaration rows now (host ≥ 0.1.7-alpha.1) — measured, with the incident
 
 A user preset used to be a directory `$DSH_HOME/.agent-presets/<id>/` holding `preset.yml` +
@@ -512,6 +562,11 @@ not stylistic:
   a plain function callable **without an agent turn** — build that seam in Phase 1, not Phase 5, or the
   UI and automatic paths both force a rewrite.
 
+> **SUPERSEDED as a surface by § "Suggested Next Step bar" below** (#113, chip removed in #114). The facts in
+> this section stay authoritative and are the reason the replacement is a docked row: the overlay geometry,
+> the non-writable placeholder, and `inputActions.setDraft`/`submit` were all measured here first. Reviving an
+> overlay must answer all four defects #113 recorded, with measurements.
+
 ## Composer Ghost Layer — measured host facts (#71, verified 2026-10-21 against `examples/dsh` @ 0.2.1-rc.2; runtime pin 0.2.0-rc.2, compile deps still 0.1.5-rc.2)
 
 The prompt-recommendation feature renders a ghost layer in the composer. What the host does
@@ -593,3 +648,241 @@ Two corollaries, both bought once:
 - An injected port that is optional and stops being wired fails as a symptom, not as an error:
   `tests/unit/client-doors.test.ts` has a row that fails if `src/client/index.ts` drops
   `uiWorkspace` from `inject` or stops passing it.
+
+## `ContinuePorts.mutateState` — the row write seam (#101)
+
+`ContinuePorts` exposes **both** `getState`/`putState` and `mutateState(sessionId, fn)`, and the split is
+load-bearing, not historical:
+
+- `getState` is for **reads** (ancestor walks, root resolution) and for nothing else.
+- `putState` survives only for **brand-new rows** — a child row that no other writer can hold yet
+  (`linkChild(freshSession(childId), …)` at `continue-core.ts:527`).
+- **Every write to an EXISTING row goes through `mutateState`**, because `store.put` replaces the whole
+  value: a `getState`→`putState` pair loses any commit another door made in between. The chapter allocator
+  (`reserve`, `reservePlan`) runs *after* hundreds of fs writes, and the commit runs after `agents.create`
+  plus the artifact work — both are windows. AGENTS records the incident class: an enrichment put at
+  04:53:52.841 rewound a compaction commit from 04:53:50.915, deleting its manifest, reservation,
+  `finalized` entry and chapter record while its 960 KB file survived on disk. Files present + records
+  gone is the signature, and `chapters-repair` then looks like a phantom-maker.
+
+`fn` must apply its change to the row it is handed and may not return a captured snapshot — a
+`mutate(id, () => snapshot)` is a stale `put` with better branding (fixed once already in `repair-run.ts`
+for the hollow-payload supersede).
+
+## Suggested Next Step bar
+
+> **Host fact, measured 2026-10-28 (the draft gesture's limit, and where it actually lives).** The composer surface a
+> dock receives carries `captureInsertion, insertText, setDraft, persistDraft, addAttachments, removeAttachment,
+> pruneAttachments, submit` — every verb is present and callable — and a programmatic write still throws
+> `Cannot read properties of undefined (reading 'draftRev')` with the composer text left empty. Reproduced identically
+> on host `0.2.0-rc.2` and `0.2.1-rc.4` (`var/e2e-prompt-draft-dump.json`, `LEG=prompt MODE=record`), which is the
+> evidence behind #126 staying a host ask: **`draftRev` is not referenced anywhere in `ui-conversation/src`** in either
+> tag — the identifier lives in `ui-commands/src/client/popup.ts` — so the write path's missing revision object is not
+> the module whose `setDraft` implementation changed between those versions. Do not infer a fix from that module's diff;
+> the source read looked convincing and the browser said otherwise. The shipped client therefore refuses visibly and
+> keeps Run as the working gesture (`docs/verify.md`'s "delivered, not assumed").
+
+
+**What a dock component is handed (measured from the host's own contract table,
+`dsh-cordis-client-runner/lib/client.js`, entry `key: "conversation.input.dock"`).** It is a `list` region,
+`scope: session`. Register options are `id` (required), `order` (optional, ascending, default 0), and `label`.
+The component's props are **hooks**, not scalars: `useSessions`, `useSessionStatus`, `useSessionRetainInfo`,
+`useWorkspaces`, `useChat`, `useConversation`, `useInput`, `inputActions`, `useSession`, `sessionId`,
+`useProjection`, `useTrajectory`. Shipped occupants: `todo` (order 0), `goal` (10), `queue` (20).
+
+Why this is written down: the bar's Autorun gate was written against a **scalar** `props.running` that no host
+version supplies, so Autorun reported itself unavailable on a host that exposes the very signal through
+`useSessionStatus`/`useChat`. Reading the contract table beats remembering a prop name. `inputActions` here is
+`{ captureInsertion, insertText, setDraft, addAttachments, removeAttachment, pruneAttachments, submit }`, and
+the composer-write limitation in #126 is measured against that same kit.
+
+**Verbs (interface lock, #113).** `/chapters-prompt` accepts `model …|clear`, `off`, `on`, `state`, `autorun on|off`,
+and **`run`** — submit the offer currently on screen as a **human-authored user turn**, through the same follow-up
+path autorun uses (`agent.followup(suggestPromptMessage(…))`). Run goes through the command plane rather than the
+composer's `inputActions.setDraft` because a dock cannot rely on writing the host editor: measured, `setDraft` is
+accepted and the composer still reads empty, and the goal bar's own `setDraft` is plain React state, not a
+composer write. A plugin's only dependable wire to its own server plane is the command — which is why the bar is
+push-shaped and pull-fed.
+
+**The dock's status hook is a SELECTOR hook (measured, 2026-10-27).** `useSessionStatus` is declared
+`SnapshotSelectorHook<SessionStatusSnapshot>` in `dsh-client-ui-session`'s client types, so it is called as
+`useSessionStatus(selector)` — passing a session id hands the host a string where it wants a function and it
+fails `TypeError: l is not a function`. Two consequences for anyone wiring the bar: the call must be hoisted
+above the component's early `return null` (a hook below that guard changes the hook count and React aborts the
+whole slot, `#310`), and the snapshot's field names are not ours to assume — the dock folds it through
+`deriveRunning`, which maps `boolean`, status words, `{status|state|phase}`, and `{running}`, and returns
+**`undefined` for anything unrecognized**, because `undefined` (unknown) and `false` (idle) are different
+safety answers: unknown must never start a turn.
+
+**State vocabulary (interface lock, #113).** `/chapters-prompt state` reports one of:
+`off` — switched off by the human (a stored override), or no defining model is configured, so the bar renders
+nothing; `idle` — **enabled and awaiting its first recommendation** (no completed turn yet); `analyzing` — a
+generation is in flight for the current turn; `ready` — an offer is on screen with `text`; `failed` — the
+generation could not run, with the reason. `idle` exists because collapsing "nothing yet" into `off` made a
+working feature indistinguishable from a disabled one: measured in the rig, the bar replied
+`suggested next step: off` while the profile row read `model: qwen-token-plan/qwen3.8-flash (config)`.
+The bar stays hidden on `off` only, and re-reads while the state is `idle`/`analyzing`/`ready`.
+ — interface lock (#113, builds on the measured goal-bar facts above)
+
+A composer dock row that, once per **completed turn**, generates a fresh prompt suggestion and offers
+**Run · Autorun · Off**. Modelled on the goal bar because the goal bar is tested and already fits — and the
+mechanical parallel is exact: *a goal re-injects the same directive every turn until the model stops; a
+suggestion re-derives a new directive every turn until the human stops it.*
+
+**Measured anchors for every claim below are in the section above** (dock slot, ordering, anatomy, hiding
+rules, `hooks:` observables, `remote.commands.execute` as the only plugin-reachable call path).
+
+### State, and who owns it
+
+| field | owner | values |
+|---|---|---|
+| `status` | server, persisted per session | `off` \| `analyzing` \| `ready` \| `failed` |
+| `text` | server | the suggestion, verbatim, never truncated (`promptMaxChars` is a **refusal** cap) |
+| `turnSeq` | server | the `turn/end` seq the suggestion was generated **for** — the identity of an offer |
+| `autorun` | **server, process-local** (exactly like the goal's `activation`) | `armed` \| `disarmed` |
+| `expanded` | client, per-mount | `false` collapsed one line · `true` full text shown |
+
+The durable pair (`status`, `turnSeq`) is the server's one-generation-per-turn key; the process-local pair
+(`autorun`, `expanded`) is never persisted — same split the goal bar uses between `goal.phase` and
+`activation`.
+
+**Correction, found while wiring the loop and kept visible because the first version of this table was
+wrong.** `autorun` is *not* client-local: the whole point of the feature is that a suggestion drives the
+next real turn, and a turn is started host-side (`agent.followup`), so the flag has to live where the loop
+does. It is **server-side process-local state**, disarmed on mount and on `agent/created`, re-armed only by
+an explicit human action through the command — the host goal driver's `WeakMap` semantics copied on purpose,
+including the safety property: **a loop cannot resurrect itself after a restart.** `expanded` stays purely
+client-local, because only a browser cares.
+
+### Dock placement
+`conversation.input.dock`, `order: 30` — after todo `0`, goal `10`, queue `20` (ascending sort), so it sits
+**under all other dock entries and directly above the composer card**, which is what "right above the chat
+input" means in this host. It is a docked row, never an overlay, so it cannot cover the placeholder.
+
+### Label and visibility (two fields decide both, as with the goal)
+- `analyzing` → **`Analyzing situation…`**
+- `ready` → **`Recommended Next Step`**
+- `failed` → **`Recommended Next Step`** *plus* an error span (`role="alert"`) naming the reason and code — a
+  detected failure must be a delivered failure (#61); nothing is silently blank.
+- `off`, or a **quiet** refusal (nothing to recommend yet) → renders **nothing**. A refusal is not an error,
+  and shouting it was defect #2 of the removed ghost.
+- Also renders nothing while the session zone is absent, and keeps a just-turned-off guard so it cannot
+  flicker back before the server state catches up (the goal's `clearedGoalId` trick).
+
+### Interactions
+1. **Click the prompt (collapsed)** → expand; full text shown in the same strip.
+2. **Click the prompt (expanded)** → `inputActions.setDraft(text)`: the draft is *replaced*, editable, and
+   nothing is sent. No `Edit`-button fallback unless a browser pass proves the click is captured by the host
+   editor — and if so the fallback is the goal's inline swap, which is already the house pattern.
+3. **Run** → `setDraft(text)` then `submit()`, in that order, so what goes out is visible in the composer
+   first and lands in the durable log as an ordinary **human** message.
+4. **Autorun / Autorun off** → toggles the process-local `armed`/`disarmed`. While armed, after each
+   completed turn the bar pulls, and on `ready` performs the Run path by itself.
+5. **Off** → server `status: 'off'`; generation stops, the row disappears, the configured model is kept so
+   turning it back on is one click.
+
+### Goal composition (per the maintainer's spec, which corrects my first plan)
+Autorun **runs alongside** an active goal — it does not stand aside. The suggested prompt is always generated
+*with the goal in view*: the server reads the newest `goal/change` from the session and feeds the live
+objective into the recommendation, with the directive that the next step must advance an active goal.
+**When the goal completes (or is cleared/paused out of `active`), autorun disarms itself** — the suggestion
+loop yields the stage back to the human at the moment the purpose it was serving is finished. A human prompt
+also disarms autorun, while generation continues on later turn boundaries; re-arming is a human act.
+
+### Enabling
+`promptModel` remains the single switch (empty ⇒ no bar, no calls, no cost) — the model *is* the enable.
+`promptAutorunDefault` (bool, **false**) decides only whether a fresh session starts armed; nothing autoruns
+that a human did not opt into.
+
+### Where the goal's loop actually lives, and what that changes for us (measured 2026-10-25)
+
+The second probe corrected two things I had assumed, and one thing I had written:
+
+- **The goal loop has no timer.** `dsh-goal-round-driver` chains turns off `agent/status === "idle"` and
+  `goal/changed`, coalesced into one serialized task per agent, and starts the next turn with
+  `agent.followup(createUserMessage({…, source:{kind:'goal', goalId, revision, round}}))`. It stops **silently**
+  unless `phase === "active" && activation === "armed"`.
+- **`activation` is process-local and starts disarmed.** On mount the driver disarms every agent, and
+  `agent/created` disarms new ones; only a human `ctx.goals.resume` re-arms. A loop cannot survive a restart
+  on its own.
+- **A plugin may read the goal through the host, not just the log**: `ctx.get('goals').get(agent)` → `GoalView`
+  (adds `roundsStarted` + `activation`), or `ctx.sessionProjections.stateOf(session, 'goal')`. `readActiveGoal`
+  remains for log-only paths (repair, distill, tests).
+- **Trap that governs our authorship**: two invariant companions re-fold the goal stream and
+  `deepEqual`-check every `source.kind:'goal'` message against the package-owned `<goal_round>` template. So
+  **we never author as `goal`** — impersonating that kind is a loud invariant failure by design.
+
+**Decision this forces (and the one I'm making, since it is a semantics choice, not a style one).** Run and
+Autorun are different acts and must not share a mechanism:
+
+| control | mechanism | durable effect | survives a closed tab? |
+|---|---|---|---|
+| **Run** (a button the human pressed) | client `setDraft` + `submit` | an ordinary **human** `user/message` (`source.kind:'user'`) | no — and correctly so |
+| **Autorun** (a loop the human opted into) | server-side `agent.followup(...)` with our **own** producer kind `plugin:dsh-chapters` | a plugin-authored message, screened like a notice, never counted as human input | the loop itself is process-local and **disarms on restart**, mirroring the goal |
+
+That split is what makes it goal-shaped *and* honest: the suggestion reaches the model with the session's full
+tool capability (it is a real turn, not a browser trick), while nothing we generate can masquerade as the
+human typing it. Autorun defaulting off, and being off after any restart, is a safety property inherited from
+the goal driver rather than a limitation to apologize for.
+
+### Goal ↔ suggestion authority and precedence — measured 2026-10-25, host 0.2.0-rc.2
+
+Read this before touching either loop. The two features start turns, and the host reserves *some* turns for
+humans. Facts, with anchors in `dsh-tool-goal/lib/index.js`:
+
+- **`hasDirectHumanInput(ctx, execution)`** = the agent is a runtime root **and** the open turn contains
+  `user/message` with `data.source.kind === 'user'` (:49-52). **`requireDirectHuman`** (:62-65) gates goal
+  `create`/`edit`/`pause`/`resume` — a model cannot re-cut a goal without a human turn in progress.
+- **`isMatchingGoalRound`** (:54-56) additionally grants *completion* authority to the exact admitted goal
+  round (`source.kind === 'goal'` with matching `goalId/revision/round`), so the worker may close the goal it
+  was handed — but not re-author it.
+
+Consequences for this plugin, in order of how much they matter:
+
+1. **A `Run`n suggestion is a human turn, so it CAN re-cut the goal.** The composer's `setDraft`+`submit`
+   produces `source.kind: 'user'`. This is the director path the maintainer is building: the big model writes
+   *"edit the goal to X, because step 2 of the plan showed Y"*, the human presses Run, and the worker now has
+   authority to edit the goal. Nothing about our authorship needs to change for this to work.
+2. **An autorun suggestion is NOT a human turn, so it MUST NOT try to edit the goal.** Our loop authors under
+   `plugin:dsh-chapters` (see above: faking `kind:'user'` here would be a privilege escalation — it would hand
+   an automated loop the authority the host deliberately reserves). So the host's refusal is the correct
+   behaviour, and the feature must respect it rather than route around it.
+3. **Therefore an offer carries an intent, and intent decides whether autorun may act on it.** The suggestion
+   model prefixes its answer: `GOAL:` = this step changes the standing objective → **never auto-run**; the bar
+   holds it for the human's keystroke and says why. Anything else = a worker step → auto-run is allowed.
+   The prefix is stripped before the prompt reaches the composer or the followup, so the worker never sees
+   protocol scaffolding.
+4. **Exactly one thing may start a turn at a boundary.** The host goal driver queues a round on
+   `agent/status === 'idle'` when `phase === 'active' && activation === 'armed'`. If our loop also followed
+   up, the session would start two turns per idle edge — a race against the driver's own reservation fence.
+   So when the service reports the goal `active` **and** `armed`, the suggestion loop **yields**: it keeps
+   generating offers (that is the director's eye on the work) and runs none of them. It runs again when the
+   goal is `paused`, `blocked`, `complete`, disarmed, or absent.
+   Activation is process-local and reachable only through the service (`ctx.get('goals').get(agent)` →
+   `GoalView.activation`), never from the log — that read is the point, not a convenience.
+5. **A goal edit invalidates the offer made under the old revision.** `revision` bumps exactly +1 per
+   accepted mutation, so the loop compares the revision it generated against and refuses to run a stale one
+   instead of pushing last cycle's directive into a re-cut objective.
+
+This is the shape of the pair: the **goal** is the thing the human owns and re-cuts, the **suggestion** is the
+thing the director model re-derives every turn. Autorun drives the worker; the keystroke drives the objective.
+
+### Displacement, not yielding — the maintainer's rule for two autoruns in one session (2026-10-25)
+
+My first pass had the suggestion loop **yield** whenever a goal was `active`+`armed`. That was wrong against
+the spec: *"the autorun for the suggested prompt … can either introduce or **replace** the autorun by the goal
+if it is running."* Yielding made the two features mutually exclusive, which is the opposite of built for each
+other — with a goal armed, a director's autorun would have quietly done nothing at all.
+
+The rule now: **arming prompt autorun displaces the goal's continuation, and the suggestion carries the goal.**
+- Mechanism: `GoalService.disarm(agent)` (`dsh-goal/lib/index.js:622-627`) — *"without changing durable goal
+  phase or revision"*, a later human-authorized `resume` records the new activation edge. That is precisely a
+  cooperative brake: the objective stays authoritative in the log, the driver simply stops re-injecting it, so
+  **exactly one loop starts a turn** at each boundary, and it is whichever the human armed last.
+- The goal is not lost by being disarmed: every suggestion is generated *from* `goal/change` (objective +
+  revision) and the directive still says the next step must advance it. The director's words replace the host's
+  repeated round; the objective is unchanged.
+- If `disarm` is unavailable (no `goals` service on this host) arming still succeeds, and the loop yields the
+  turn — so a missing seam degrades to the safe behaviour rather than double-firing.
+- Re-arming the goal (`/goal resume`, or the bar's next human Run of a `GOAL:` step) is a human act, matching
+  the host's own rule that a model may not resume a paused goal (`GOAL_TOOL_RESUME_PAUSED`).

package/docs/development.md

@@ -217,6 +217,53 @@ Re-record discipline (learned the hard way 2026-09-22/23):
   the missing host-plane route) that every deterministic layer had missed because each side
   only ever tested against its own convention. The e2e is the integration witness — keep it.
 
+### Reading a dead boot (#165, #166)
+
+When a rig boot never announces its URL, `tests/e2e/boot.ts` throws `bootFailureMessage()` from
+`tests/e2e/boot-failure.ts`, and the message carries: the measured wait, the port, the name of the knob that raises the
+window for diagnosis (`E2E_BOOT_TIMEOUT_MS` — readiness to serve, never a product claim), and the **child's own tail**.
+That tail is the whole value: on 2026-10-28 the single line `[chapters-prompt] turn/end door armed` distinguished "the
+child mounted and stalled before listening" from "the child crashed", and separated the real cause from four wrong
+theories I had already published.
+
+Three shapes must not be blurred, and are pinned by `tests/unit/boot-failure-message.test.ts`: a tail with no lines reads
+`(empty)`; a log that could not be read reads `unreadable or never written` (absence is not emptiness); and output is
+bounded at 1,200 characters with any removal marked `…[redacted]`, so suppression is never mistaken for silence. The
+redaction is not cosmetic: the child prints its own boot URL **carrying a session token**, and the old verbatim slice
+copied it into the Playwright error, the per-leg log and CI annotations. Read `var/e2e-server-<port>.log` and
+`var/e2e-boot-<port>.json` as sensitive for the same reason — I `cat`-ed one during tonight's diagnosis.
+
+**One boot per journey still applies** (site §24, #129): a chain failure after leg one is an environment symptom, not a
+tape symptom. Ruled out on this machine by check rather than hope: dangling tool links, orphan servers, port squatting,
+`ulimit`, inotify instances, free memory, lock files. If a lone leg passes and a chain does not, stop and read the boot
+message before touching a test.
+
+### What `coverage:e2e` promises, and what it cannot deliver
+
+`coverage:e2e` runs the replay chain under `E2E_COVERAGE=1` (a V8 profile per boot, aggregated by
+`scripts/e2e-coverage.mjs`). **It is a coverage report, not an acceptance gate, and it cannot carry the browser timing
+guarantees acceptance has.** Measured 2026-10-28 on one tree with load recorded (3.16–4.30 average on 20 CPUs, two other
+live harnesses on this host, ~68 GB free):
+
+| attempt | legs that failed | signature |
+|---|---|---|
+| 1 | `suite` | `button[aria-label="Fork with chapters"]:visible` — `Timeout: 120000ms` |
+| 2 | `prompt` | `locator.click` — `Test timeout of 300000ms exceeded` |
+| 3 | eight of nine | mixed |
+| 4 | `fanout` | `new-session click never set dsh.sessions.current` |
+
+The controlled A/B fixes the cause: `LEG=suite MODE=replay` → **`4 passed`**; the same command with `E2E_COVERAGE=1` →
+the same 120 s door timeout. So it is V8 instrumentation cost on the server process, landing on whichever leg happens to
+be slow — not a stale corpus or a broken product. Profile volume is not it (19 MB / 4 files for a failing boot), which is
+why narrowing what gets instrumented is the only lever, and that changes what the percentage means.
+
+**Rules that follow.** Two ceilings are involved (120 s `toBeVisible`, 300 s test timeout) and **neither is to be raised**:
+widening a wait to satisfy an instrumentation mode is `AGENTS.md`'s "never widen a test to pass". Read the e2e number as
+a report; the blocking coverage verdict is CI's deterministic gate (statements/branches/functions against 85, in the merge
+job). And when quoting an e2e figure, quote the tree and the machine conditions with it — that is how 77.94%, 77.97%,
+78.05% and 78.34% came to be cited interchangeably when each belongs to a different corpus. See #158, and site §24 for the
+user-facing version.
+
 ### The coverage ledgers (added 2026-09-23 by the coverage audit; gated same day)
 
 - `npm run coverage:ci` — **the gate CI enforces.** `c8 --check-coverage
@@ -800,13 +847,144 @@ correct. The corpus spanning them is not.
 
 Rules that follow, in the order they bite:
 
-1. **Change `src/` → rebuild → re-distill ALL nine legs.** A partial re-record is a mixed corpus, and a
-   mixed corpus fails at whichever step the builds disagreed — usually inside compaction, where message
-   counts are the thing being matched.
-2. **`PROVENANCE.md` per leg is necessary, not sufficient.** It records the host and regime; it does not
-   say "this leg predates three plugin commits". When in doubt about build drift, re-record everything.
+1. **Two questions, two answers — `npm run corpus:check` (#156).** A rebuild changes the *bundle*; that alone does **not**
+   make the corpus stale, it makes the *stamp* stale: the check prints an `ADVISORY` and the replay still runs, then
+   `npm run corpus:stamp` re-records `BUILD_STAMP.json` (`lib` + `promptAnchor`) once the legs are green. What does
+   invalidate a corpus is the **prompt-byte anchor** moving — tool and command `description`s, dock `label`s, the preset
+   persona, and the realm keys whose values reach the model (`thresholdRatio`, `retain*`, `headroom*`, artifact/defer
+   tokens, …). Then `verdictFor` refuses with `REFUSED: model-facing bytes moved …` and **all** affected projects must be
+   re-distilled before anything is trusted, because a partial re-record yields a mixed corpus and matching happens across
+   the whole set. The rule in `AGENTS.md` — "re-record when PRODUCT prompt bytes change" — is now a computed quantity
+   rather than a judgement call; logging keys, store paths and `maxBytes` are deliberately outside the anchor, and a
+   manifest file that contributes no tokens fails its own row, so a silently-dead extraction rule cannot masquerade as
+   protection.
+2. **`PROVENANCE.md` per leg is necessary, not sufficient.** It records the host and regime; it cannot
+   say "this leg predates three plugin commits". The stamp is what says that, and #156's split is what stops the stamp from
+   crying wolf on every rebuild.
 3. **Test-only changes (`tests/e2e/**`) need no re-record** — normalization folds apply at load to both
    sides. Product-behavior changes do. The distinction is exactly AGENTS' "re-record when PRODUCT prompt
    bytes change", generalized: anything that changes what the plugin *sends*.
 4. If a green replay is ever obtained on a corpus whose legs have different build stamps, treat it as
    unexplained rather than as evidence.
+
+## Harness-native acceptance (`E2E_PROVIDER=harness`)
+
+The rig used to have exactly one model route: a tracked profile block pinning `local` at
+`http://localhost:8080/v1`, because a GitHub runner has no credentials and can start a llama.cpp server. On
+this machine that made acceptance a second-class citizen — the model was almost never up, live legs
+`test.skip`-ed themselves (which reads like a pass), and re-distilling meant standing up an inference server
+before you could look at UI.
+
+`E2E_PROVIDER=harness` takes the route from **the profile this host is actually running** — read from
+`$DSH_HOME/profiles/web/cordis.patch.yml` (override with `E2E_AMBIENT_PROFILE`) — and the credential from, in
+order:
+
+1. **the parent environment**, `QWEN_TOKEN_PLAN_API_KEY` — the same way this harness instance got it. When you
+   run a leg from your own shell, this is the only step.
+2. `.dshdev-local/e2e.env`, untracked and gitignored, parsed **without executing it** (`readEnvFile` — values
+   are data, never a shell).
+3. otherwise the boot **refuses**, naming the remedy. No fallback to `local`, no silent skip, no guessed route.
+
+What it deliberately keeps: the **pinned 32K stress window**. `harnessProviderPatch` rewrites
+`contextWindow` rather than inheriting the endpoint's 196K, because the whole pressure/cache journey exists to
+observe `context-overflow` — a hosted window would swallow a 33K prompt and the leg would measure a boot where
+nothing is wrong.
+
+Commands (all of them print one `[provider] …` line naming provider, model, window and where the key came
+from, with the credential's length but never its value):
+
+| command | mode | what it's for |
+|---|---|---|
+| `npm run e2e:harness:live` | live | a real look at the UI on the model the product runs against |
+| `npm run e2e:harness:heal` | replay + fallback | tape hits replay, **misses go live and are appended** — a self-healing pass instead of a full re-record (the switch existed in code but was never surfaced) |
+| `npm run corpus:heal -- --project=<leg>` | replay + fallback | one leg, when you know which one drifted |
+| `npm run corpus:record -- --project=<leg>` | record | re-distill one leg after a deliberate product-prompt change |
+
+Why this is more than convenience: the `#90 REASONING-BLIND` entry in the tape's blind list masks
+`reasoning_content` shape differences. Tapes distilled through a different provider than the product uses will
+always need masks; distilling through the product's own route removes a class of divergence instead of hiding
+it. Stated as strong inference from the measurement, to be confirmed the first time a harness-native
+re-distill stops needing that mask.
+
+Note on what an agent shell can see: the harness **withholds** `QWEN_TOKEN_PLAN_API_KEY` from tool processes
+(measured — the harness's own process env has it, the agent's child shell does not). So a distill or live run
+from inside an agent session needs the `.dshdev-local/e2e.env` path, or the operator runs it. Reading the key
+out of the parent process's environment is technically possible for the same user and is deliberately **not**
+done: the withholding looks intentional, and reaching around it to move a credential into a tool shell would be
+exactly the kind of quiet workaround this project documents itself out of.
+
+## The provider identity is part of the tape key
+
+A tape is matched on the **request**, and the request's first message is the composed system header — which
+states the provider and model. So a corpus distilled with one provider row cannot replay under another, and the
+failure does not look like configuration: it looks like a corrupt tape, because matching dies at
+`commonPrefix=0` and every leg then reports its own downstream symptom (no assistant message, no fork door, no
+plan card, a post-compaction turn that never answers).
+
+Measured the hard way on 2026-10-27: re-distilling the corpus with `E2E_PROVIDER=harness` while hosted CI
+replays in the tracked-local shape produced `MISS tape=suite … tied=[every entry]` on CI and a green chain
+locally — the same command, two different headers. The fix is placement, not normalization:
+
+- **the host profile stays on the fixture provider** (`local/qwen3.8-flash-next`) in record and replay, so the
+  header is identical on every machine and in CI;
+- **the real endpoint lives in the tape proxy** — `E2E_UPSTREAM` derived from the installed provider module and
+  `E2E_UPSTREAM_MODEL` translating the fixture name — so the model answering is the maintainer's while the
+  bytes being recorded are the rig's;
+- `E2E_HARNESS_PROFILE=1` restores the profile rewrite for **live** runs, where there is no tape to stay
+  identical with and the point is genuinely to exercise the ambient provider.
+
+Two consequences worth holding onto: the `reasoning`/`retryPolicy` fields of the synthesized row change product
+behavior (`maxRetries: 0` versus the host default), so "same model, different row" is not a neutral edit; and
+a re-distill must run the leg to **green** — a tape distilled by a failing journey is an incomplete capture, and
+replaying it back as a miss blames the artifact for a run that never finished.
+
+## Two rig rules from the 2026-10-27 mount chase
+
+**A boot must resolve what its profile declares, before the host starts.** The booted profile's preset names 28
+`@deepseek-ai/*` plugin packages, and none of them is a dependency of this repository. On a development host they
+resolve out of `~/node_modules`; on a CI runner they resolve nowhere, `pruneUnresolvableRows()` drops them
+without complaint, and the session composes a 7-tool surface where a laptop gets 34. Because the system header
+is message 0 of every request — the thing tapes match on — that asymmetry makes a locally recorded corpus
+unreplayable in CI, which is what every `commonPrefix=0` on this branch actually was. `linkPinnedToolPackages()`
+now symlinks the pinned install's packages into `node_modules/@deepseek-ai` **before** `spawn`, skipping anything
+the repo already provides (never replace a hoisted dependency with a symlink and risk the build under test), and
+`var/e2e-tool-links-<port>.log` records `rows/linked/skippedAlreadyPresent/missingFromPin` for every boot. The
+ordering is not ceremonial: linking after the URL line was measured to change nothing, because the host has
+already mounted by then.
+
+**Normalize, THEN diff.** Comparing two machines' RAW header dumps showed an 18-character gap — exactly the
+length of the two checkout paths — and produced a duplicate blind for a fold that already existed
+(`<DSH-CHECKOUT>`, `model-proxy.ts:159`). The #89 ordering row caught the collision the moment it shipped; the
+procedure error was mine and is the one to remember: run the text through `substituteAll` before concluding a
+fold is missing. One predicate per semantic decision, and a fold that already exists is not a missing fold.
+
+## A recorded journey must not depend on when the host compacts
+
+**Symptom that gives it away:** the acceptance run misses a *different set of legs* each time, while message 0 keeps
+matching. That is not an unblinded identity token and not a matcher bug. It means the two machines ran the same
+journey and both compacted — at different moments. A checkpoint rewrites the surface, so the same assistant turn
+lands at message index 6 here and index 2 there, and the surface is the tape key.
+
+**The rule:** a leg that is NOT testing the machinery pins `noAuxModel`. It is a rig-side alias, translated at
+profile-write time into the realm keys the engine really reads — `auto: false` + `elicitedPlot: false`,
+`tests/e2e/rig-preset-pin.ts:79`, declared at `src/engine.ts:287` — so the request sequence in the tape is the whole
+story regardless of how large a runner's header happens to be.
+
+**The exceptions are measured, not preferred:** `heavy`, `suite`, `arrival` and `fanout` stay unpinned, because
+pinning them deletes the behavior under test — a pinned `suite` never renders its fork door, a pinned `arrival`
+never gets its stub pair, a pinned `fanout` loses parent synthesis, and `heavy`'s journey *is* the pressure one. Same
+family as setting the arrival floor below the chunk size and calling the passing row a result. The drift row
+(`only the pressure journeys leave model-involving machinery enabled`, `tests/unit/rig-pins.test.ts`) names offenders
+in its failure text and asserts those four stay unpinned.
+
+**And the method trap I walked into, recorded so it costs the next reader nothing:** I searched `src/` for the string
+`noAuxModel`, found none, and concluded the switch was decorative — then shipped a "fix" folding a check into
+`overTrigger`, a local that is computed and dropped, plus a guard test asserting the plugin must contain the alias's
+literal name. Absence of a NAME in a source directory is not absence of an EFFECT: read what the rig writes into the
+profile it boots, not what it calls the field on the way in.
+
+**Why the transcript has to travel with the artifact:** this took three runs to see because the workspace-only
+artifact never contained the booted home's session logs. `scripts/chain-replay.sh` now copies each leg's
+`session.v4.jsonl.zstd` files and registry into `var/e2e-session-logs/<leg>-<port>` (six files, under 4 MB each) so
+the runner's own history sits next to the tape diffs and the misses. When a miss claims "the conversation had
+already taken a different shape", the answer is in that transcript — read it, don't theorize about it.

package/docs/host-protected-head-ask.md

@@ -0,0 +1,80 @@
+# Ask of the host team: the protected system head and a plugin-seeded first message (#105)
+
+**Filed 2026-10-24 against `dsh 0.2.1` / session format v4.** Reproduced on the maintainer's own data:
+a `chapters_continue` child (`ch-dc3be3ab-c3d9-4afc-bc53-9994c06600d6`) refuses to open in the UI with
+`SessionFormatError: system/message requires a protected first surface head`, while its 2,924-line log
+decodes cleanly. Nothing about that file is damaged.
+
+## The two kernel rules that cannot both hold for our children
+
+1. **The seed contract**, established by measurement against the installed kernel (`spikes/probe/FINDINGS.md`)
+   and recorded in `AGENTS.md` invariant 2: a continuation is
+   `agents.create({ sessionId, seed: [noticeEvent] })` with **one synthetic `user/message` at `seq 0`**, a
+   producer-owned `source.kind` (`plugin:dsh-chapters`, `form: 'snapshot'`), no `plugin` field (format v4
+   retired it and refuses it at row admission), and the kernel's own `permission/preset` / `sandbox/mode` /
+   `approval/policy` events appended **after** the seed. Seeding from the parent's events is refused as
+   capability-gated, and is the failure mode this plugin exists to avoid.
+2. **The protected head**, as read out of `@deepseek-ai/dsh-session-format-v2-to-v3/lib/index.js`:
+
+```js
+const SURFACE_TYPES = new Set(["system/message", "user/message", "assistant/message", "tool/result"])
+// inside restoreReleasedV3Artifact's event walk:
+if (system) {
+  …
+  if (hasSurface && head === void 0)
+    throw new SessionFormatError("system/message requires a protected first surface head")
+}
+…
+if (SURFACE_TYPES.has(event.type)) hasSurface = true
+```
+
+`user/message` **is** a surface type. So a kernel-sanctioned seed at `seq 0` sets `hasSurface` before the
+host composes and writes its own `system/message` header at the first step — and at that moment the header
+can no longer claim the protected head, because `head` is only assigned to a `system/message` that arrives
+while `hasSurface` is still false.
+
+## The statistics that make this a rule collision, not a corrupt file
+
+53 durable logs on this machine, first surface event preceding the header:
+
+| shape | sessions |
+|---|---|
+| header **is** the first surface event | 50 |
+| a `user/message src=plugin:dsh-chapters` at `seq 0` precedes it | **2** |
+
+Both of the 2 are children this plugin created (`ch-dc3be3ab…`, 2,924 events — refused; `ch-c2a7ee0f…`,
+105 events — same shape, not yet opened). Also observed: that child's header carries `isSeeded: false`.
+
+## What we are asking for
+
+**Preferred:** for the protected-head rule, do not treat a `user/message` whose `source.kind` is
+producer-owned plugin (`form: 'snapshot'`) at `seq 0` as a surface event that pre-empts the head. The rule
+exists to protect the system head from being shadowed or replaced; a plugin snapshot that the kernel
+itself invited to `seq 0` is not a competing user turn.
+
+**Acceptable alternative:** admit the mid-run header by letting the first `system/message` claim the head
+when the preceding surface events are all plugin-produced seeds, and record the head position as it is
+written.
+
+**What would NOT fix it:** telling us to seed nothing. Then a continuation starts with no TOC, which is the
+whole feature. And we cannot write the header ourselves — invariant 3, and a per-session system contribution
+changes every session's header in the profile.
+
+## Why we are not just changing our own shape unilaterally
+
+We could seed a non-surface synthetic event instead (the `plan/mode` seed in `docs/plans-carriage.md` § 10
+proves the kernel accepts plugin-authored STATE events in a seed) and deliver the TOC as an appended message
+at the child's first step. We are **not** building that on an assumption: it needs a measurement first —
+does a state-only seed get admitted, and does the header then land as the first surface event so the session
+loads? The spike design is in `spikes/seed-protected-head/` (see `docs/backlog.md`); one boot, zero model
+tokens, a fake provider supplying the turn. If the measurement says the kernel admits it, we ship it behind
+a config flag and the ask above becomes belt-and-braces. If it says otherwise, the ask is the only path, and
+we would rather know that before a user loses a child.
+
+## Side observation, offered as a fact rather than a claim
+
+We tried to reproduce the throw by calling `restoreReleasedV3Artifact` directly with the real bytes. Every
+variant — the refused child *and* healthy sessions — failed earlier at `assertV3EventAdmission` with
+`"system message requires plugin source"`. So that module's admission gate is not the path that validated
+this v4 log, even though its message text is what the UI shows. Whatever the actual v4 validator is, the
+statistics above and the rule text are consistent; a pointer to the right entry point would help us pin it.