@treeseed/dsh-chapters 0.1.24 → 0.2.0

package/docs/project-state.md

@@ -0,0 +1,323 @@
+# Project state — the history of what was built and measured
+
+**Moved out of `AGENTS.md` verbatim on 2026-10-22.** `AGENTS.md` is loaded into every agent session
+against a workspace instruction budget, and it had grown to 70,401 bytes — over the limit, so the file was
+being silently TRUNCATED when delivered: the rules near the top survived and the ones at the bottom did not,
+which is worse than a smaller honest file. This is the project's record of what happened, what was measured,
+and what remains unverified. It is reference material, not a rule surface: **read it when you need the
+history of a decision, not before every task.** The rules that lived inside it are in
+`AGENTS.md` § Rig and metering rules, and the load-bearing spec stays in `docs/`.
+
+---
+
+## Start Here
+## 2026-10-22/23 — the host 0.2.0-rc.2 acceptance sweep (#56)
+
+**What actually happened, in order.** The pinned host moved to 0.2.x; the tape corpus stayed at
+0.1.5-rc.1, so `CORPUS_HOST` closed the acceptance chain and no e2e claim was current (#56/#57). While
+re-anchoring it, seven distinct failures turned out to be **one root cause plus six real defects**: the
+preset pin had been written to a row id the host retired (`agent-presets` → `agent-preset-registry`), so
+every browser boot since the move ran the STANDARD realm — no `compaction/*`, no arrival artifacting, no
+`chapters_rules`. The legs were measuring an absence. Fixing the pin is what made the other six visible.
+
+**Defects found by measurement, each with red-first rows, on `feature/56-reanchor-tape-corpus`:**
+- **#77** — the continuation door called `sessions.open`, a verb that does not exist; the real seam is
+  `uiWorkspace.openSession` (`docs/contract.md` § Client Sessions Service). Three evenings of "the client
+  refuses to catalogue plugin-created children" were a door that never switched anything, while the tool
+  reported success. The door now verifies the switch from live state and degrades to
+  `switched:false, note:…` rather than claiming it.
+- **The flattened 0.2.x `tool/result` shape** silently disabled arrival artifacting chain-wide (the
+  probe decoded `data.message` at the top level, where 0.2.x puts `data.message.message`). Arrival
+  artifacted nothing because the predicate was never true — `src/arrival.ts` now takes both dialects,
+  with a row that rebuilds the assertion against the host's real event shape.
+- **#79** — the composer ghost ran `command/run` on **every render** (measured 4–26 per session, into
+  the transcript this plugin archives) because a `useEffect` listed `[props]` under a comment claiming
+  "once per mount"; and it kept pulling suggestions from a disabled feature.
+- **#78** — relief that declines while the surface is over the trigger said nothing. It now prints
+  `surface=/trigger=/window=/ratio=` plus the offending node count; observed live:
+  `relief declined … (surface=33442 trigger=16000 window=32000 ratio=0.5)`. The engine deliberately does
+  **not** override the operator's arrival floor (AGENTS calls that switch a behavior switch, and a rig
+  that reinterprets config is the same dishonesty as a pin that is collected and never applied).
+- **#81/#84** — `typeComposer` decided "did my send work?" from the editor's own emptiness, which the
+  host clears asynchronously: one session received the same instruction twice (seq 40 and 47). Then the
+  guard, matching an 80-character prefix, **swallowed** a genuinely different second instruction. Delivery
+  is now decided from the durable log, by the full instruction, after a bounded grace — and a drift row
+  fails if any composer call decides from the editor again.
+- **#85** — replay booted a **different realm than record** because the rig's regime lived in three
+  places (distill tables, the chain script's inline env, boot defaults) and Playwright project `env`
+  reaches only workers, so `globalSetup` used defaults. One table now (`tests/e2e/rig-pins.ts`), read by
+  both the config and the boot.
+- **#87** — the deepest one, and the last to become visible: **relief shadows the newest human
+  instruction.** Measured from one session's durable log: 13 compaction summaries, 108 distinct shadowed
+  seqs, `STILL-HERE` sent eleven times, **ten of them shadowed away**, final assistant text empty.
+  `retainRatio` reserves a token fraction as a verbatim tail, so an oversized node in the tail consumes
+  it and the question disappears with no error anywhere. The fix is inside our seam and honors
+  invariant 1: `carryOpenRequest` appends the newest human turn **verbatim** into the summary we author
+  (`openRequestCarryMaxChars`, default 4000; truncation is stated, never silent; injected scaffolding is
+  excluded by the one canonical predicate, `isInjectedProse`).
+
+**The instruments earned their keep, and four bugs lived in the instruments.** `pending` never
+matched a JSON-escaped newline; `ids.size > 0` disabled every #77 candidate; a report helper resolved
+logs against the import-time home so its own gate could never pass; an unbounded
+`scrollIntoViewIfNeeded` hung a leg for 17 minutes; my own MISS dump was swallowed by its own `catch`
+for a whole run; and a second injected-prose list was caught by the #59 drift row within minutes.
+`docs/verify.md` now carries a release gate shaped by these failures ("an unexercised assertion is a
+rumor of an assertion"), and `npm run typecheck:e2e` exposes **77 errors in a browser plane that has
+never been type-checked** (#83) — after I subtracted the ones my own new code caused.
+
+**Still open as this lands:** #86 (a session with the arrival floor off can livelock on one oversized
+result — 89 requests in 20 minutes, three outcomes for the same leg minutes apart), #80 (plugin command
+results are durable but render nothing operator-visible), #82 (a distill and the deterministic suite share
+the corpus directory), #81 criteria 3-4, and the #78 A/B product decision, which is the maintainer's.
+
+
+**Phase 0 passed.** Across nine probe boots on an isolated instance, a plugin created a session seeded with
+exactly one synthetic `user/message`, and that session was **listed** by `sessionQuery.listSessions`,
+**resumable** via `agents.resume({ resumeSessionId })` after disposing the create handle, **durable across a
+process kill**, and its TOC text round-tripped **byte-identical**. Structurally the head is bounded: ~102
+tokens of notice versus ~2,476 for the equivalent transcript. Full measurements and the seed contract:
+[spikes/probe/FINDINGS.md](spikes/probe/FINDINGS.md).
+
+**Phase 0b passed (rounds 12-17): the compaction seam is real.** A plugin-subclassed `BasicCompactionEngine`
+with a deterministic `summarize()` ran both the manual (`/compact`) and automatic (`agent/pre-step`)
+paths to durable commit — surface 504→206 tokens, **zero summarization tokens**, log append-only
+throughout. The live engine slot is the **agent-preset realm**, not the host plane; double-provisioning
+one plane fails boot loudly; and the Phase 1 mount is a shipped preset naming `dsh-chapters` +
+`setup`-mounted creation (all of it measured, cited, in
+[docs/host-compaction-seam.md](docs/host-compaction-seam.md) and FINDINGS).
+
+**Phase 1 stages 0-4 landed (rounds 18-22): the whole loop works with the real parts.** Registry/store/engine/
+preset-install/tools pass — a realm row names our subpath export (`dsh-chapters/engine`), the cascade
+finalizes post-commit, `presets/chapters/` installs itself into `.agent-presets` at boot (profile
+`!!js` has no `require`, copying was the delivery mechanism) — and since 0.1.16 that copy validates the
+WHOLE shipped file set and repairs missing files additively: the guard once tested only for `preset.yml`
+while `agent.cordis.yml` is the file that mounts the engine, so a partial wipe was a permanent silent
+failure (never clobber a user's edits; DO restore what is absent), and r22 closed the MVP loop: parent →
+`chapters_segment` → `chapters_continue` (ranges only; plugin renders) → TOC-only child with the composed
+preset (15K head) → the CHILD `read` its chapter and echoed its title back. Two real bugs caught and
+fixed en route: finalization must run on the rejection path too (the retry loop can commit, then throw),
+and `validateRanges` refuses before any file is written.
+
+**Host 0.1.7-alpha.1 retired the preset mechanism that paragraph describes — do not carry it forward as
+current.** Nothing reads `$DSH_HOME/.agent-presets` any more; a preset is an `@deepseek-ai/dsh-agent-preset`
+*declaration row*, and the chapters preset IS one now: `preset-chapters`, inserted by our own bundle patch,
+with the preset definition in its `config` — so it is a visible Loader entry you can inspect, override, or
+`disabled: true` from a profile patch, exactly like the host's `preset-standard`. **Its row module is ours**
+(`@treeseed/dsh-chapters/preset`, `src/preset.ts`), not the host package: it mirrors the host's plugin line
+for line (`inject: ['agentPresets']`, `static [EntryGroup.key] = true` so child `!!js` expressions survive
+until the child activates, `[Service.init]` yielding the registry disposer so **Cordis** owns the
+registration's lifetime) and adds drop-what-will-not-load. Why not name the host package: one unresolvable
+row aborts the plugin tree of a host predating declaration rows, and one unresolvable *child* makes the
+whole preset `broken` — measured both ways; our module resolves wherever our package runs, and pruning a
+missing child keeps the preset usable instead of declaring it unusable. **The lifecycle is the trap that
+took longest**: registering in `apply()` and disposing through `ctx.effect` un-registered the preset the
+moment activation finished (`register()` reported success while the roster came back WITHOUT `chapters`) —
+same apply-fiber trap r35 caught for the storage domain; a row's own init is the only place with the right
+lifetime. **Support floor is 0.2.0** (user decision 2026-10-16): the legacy `.agent-presets` copy, the
+`presets/chapters/` tree and `preset-install.test.ts` are DELETED, and a pre-0.2.0 host logs
+`this host cannot register preset rows` while its tools keep working. The tape acceptance chain needs
+`dev/dsh-host-lock` moved to 0.2.x plus a re-distill. **#54 did the move: the lock now
+resolves 0.2.0-rc.2 — chosen by WITNESS (the host this box runs the plugin on), not by npm's
+latest — the refusal has lifted itself, and `hostSupportsPresetRows()` is what lifts it (a
+version test in `tests/e2e/boot.ts`, because it runs before any host exists; silently skipping
+the pins would make every segment pass a run that never exercised the preset).** Three 0.2.x
+drifts were found by booting rather than guessing, all rig-side (and a fourth was NOT the host:
+the acceptance chain's remaining failure is a **stale tape corpus**, now gated by
+`tests/fixtures/model-tape/CORPUS_HOST` — `scripts/corpus-anchor.mjs` refuses replay by name and CI
+skips the acceptance job with a tracked reason, issues #56/#57; a gate that blocks `record` too
+would strand itself, so record stays allowed), all the kind that yields a
+WRONG conclusion rather than an error: the durable log is `session.v4.jsonl.zstd` (five hardcoded
+`v3` paths made every log assertion decode nothing and report "the archive never landed" —
+`sessionLogFileFor()` resolves the highest now, pinned by a row); the host opens a **Preview
+Notice**, a focus trap like the 2026-09-18 `Internal Testing Notice`, and dismissal must target
+`[role=dialog]`-shaped elements (matching "any div mentioning a notice" matched the app wrapper
+and pressed an unrelated 'Close'); and **provider config rides `cordis.patch.yml`** — a
+profile-dir `settings.yaml` is read by nothing on 0.2.x, so without an `llm-pi-ai` block the
+host has no `local` provider and the browser opens on "Add an API key to get started" with the
+composer never reachable. Distillation no longer needs the GPU box: `E2E_UPSTREAM[_KEY|_MODEL]`
+makes the tape proxy translate on the way out while the fixture keeps its pinned model id and a
+key-free profile (the tape RECORDS the profile's name — a fixture of this rig, not of the
+service that distilled it). Remaining: re-distill all eight legacy projects (the ninth, `prompt`, was distilled ON 0.2.0-rc.2 in #71 and needs no re-record), then a strict replay and a
+fresh `coverage:e2e` ledger — until then no browser-plane claim is verified.** Health is still the host ROSTER's answer, asked AFTER activation, plus
+`compositionInventory()` rows — **file presence is not preset existence, and "declared" is not "usable"**.
+A session's preset id is durable state (`agent-preset/selected`), so an unregistered id makes every session
+that chose it fail to *open* (`agent-preset/not-found`) while its log sits there intact — and meanwhile the
+plugin boots, registers its tools, and Settings says "enabled and running". Facts with file:line:
+`docs/contract.md` § Presets are declaration rows; the gate that turns the next host rename into a red row
+instead of a broken user session is `tests/unit/preset-declaration.test.ts` (15 rows, each verified to fail
+on the mutation it guards: ralph re-disabled, an unknown pruner key, `toolFilter` restored, `{{cwd}}`
+restored, the preset id renamed).
+Rounds 23-28 then: E3 measured (per-machine — see the Cache section, never cross the numbers),
+`chapters_fork` (r24), the durable title (r25), the 20-check mechanical pass (r26/26b: 18/20 proven
+on-scratch, the rest human-only), the target-hardware verdict (r28: zero-token compaction confirmed at
+llama.cpp counters, ~2 s steady-state turns), and a full-install product bug found-and-fixed by the
+same run — one domain, one opener, `acquireChapterStore` (e0e67d0).
+**MVP state: engine + tools + preset verified ON THE REAL MODEL, and the message-level fork AND
+continue BUTTONS are shipped and e2e-green** (both rows come from one table + one runner in
+`src/client/doors.ts` — adding a third door must extend that table, never copy the body; a test refuses a
+second runner) (`conversation.chat.assistant-actions` → `remote.commands` → watermark
+fork → `sessions.open` after `refresh`; `tests/{unit,integration,e2e}`, Playwright with
+workspace-cached chromium — client-plane facts are now measured, never guessed).
+**Long-context mechanics (architecture amendments, 2026-09-19) are BUILT**: arrival-time
+artifacting — tool results ≥ `toolResultArtifactTokens` never enter the surface (stub +
+content-addressed artifact, queried via `chapters_artifact` toc/search/read; measured: 373KB
+book, zero blob prefills, cacheRead monotone across the stub) — and plot carriage (persona
+`PLOT:` discipline carried through in-place checkpoints; bounded elicited fallback behind
+`elicitedPlot`). e2e is now TWELVE specs in NINE replay projects, each with its own boot (#71 adds the prompt-ghost journey, `prompt` @ 0.99 + NO_AUX_MODEL + E2E_PROMPT=1, scripted-distilled like plans — suite = knowledge-loop +
+discovery @ 0.75 of the pinned 32K/15K stress regime; heavy @ 0.5 with the arrival floor OFF —
+measured: a floor below the chunk size arrival-stubs the surface and silently prevents
+compaction from ever being needed; arrival @ production 0.9 + floor 500; fanout @ 0.75 — the
+chains its child sessions write are the deepest on this hardware and must be distilled in
+isolation, and its child prompt caps readers at SIX 300-line reads (an uncapped qwen looped
+past 30 exchanges; the cap still crosses the threshold inside every child); enrich @ 0.9 with
+enrichmentEnabled; rules @ 0.9; fork @ suite pins — carved out of the shared suite boot 2026-09-25
+when knowledge's fork child became the SPA's restore target for later specs (the fanout lesson
+generalized: one journey, one boot); explore.spec is an on-demand selector-archaeology DEV
+project, never in the CI chain) against port-keyed throwaway homes `var/e2e-home-<port>` — the dev
+home is SHARED with live agents and must never be the test ledger (FINDINGS 2026-09-19: run 13
+asserted against an agent transcript; draft identity, YAML colon-in-plain-scalar, worker-bound
+setupFiles, and same-home sibling boots all bit; identity is now verified via localStorage + the
+log's own header event). ACCEPTANCE RUNS OFF THE MODEL TAPE by default:
+`npm run test:e2e:replay` serves every model turn from `tests/fixtures/model-tape/<project>` (proxy
+`tests/e2e/model-proxy.ts`; explore 14.7 s replayed vs 1.7 min live; recorded usage keeps the
+token meter — and thus threshold behavior — bit-identical); `npm run test:e2e:record` distills
+tapes from the real model (once per scenario; re-record when PRODUCT prompts change —
+persona, tool descriptions, thresholds — but NOT the notice: measured 2026-10-11 that no committed tape prefix contains a seeded notice, so notice prose is currently free; that is coverage luck (no journey makes a continuation child speak), not a guarantee. Workspace docs (AGENTS.md itself,
+skill catalogs) are masked out of matching by the AGENTS-BLIND rule (user decision
+2026-09-20: development artifacts, every real project ships its own — doc edits are
+FREE, no re-record; reaffirmed 2026-10-01 with no exceptions: the tapes stand in for
+ANOTHER project, not development of this one, so no doc edit — near-threshold
+compaction summaries included — ever couples a tape to this repo's docs).
+`rm -rf tests/fixtures/model-tape` for a clean corpus. The normalization
+pipeline is CLOSED — escape/whitespace classes, volatile rules, tool-result content and
+injected instruction blocks matched out; the AGENTS-blind addition was the last change
+and required one final re-record; 2026-09-23 added two DERIVED-COUNT collapses to the
+same family — `(N est tokens)` in chapter index lines and the char count inside
+`⟦omitted:host-injected …⟧` markers (both move with doc/render drift, both identified
+already by their line — pinning them made heavy/enrich tapes brittle across builds). Replay chain verified green — ALL SEVEN segments strict 2026-09-25 and — for the first time — GREEN ON HOSTED CI (GitHub Actions, no model, no GPU): the tape is machine-neutral by contract now — injections mask to fixed tokens everywhere (skill catalogs incl. the 'catalog changed' notice), marker RUNS collapse (a dev box injects more spans than a runner), digest message-tallies collapse to <MSGCOUNT> (they count injections), the enricher's input defuses markers before its cap (hosted divergence at char 758), WS-PATH/DSH-CHECKOUT blind the system prompt's identity lines, the sessions-dir slug is COMPUTED from ROOT (a hardcoded /home/adrian one made CI poll an invisible log for 7 minutes per spec), zstd is a runner dep, the host comes from dev/dsh-host-lock's hermetic lockfile (npm global mode rewrites the plugin tree; rc-ranges float), workspaces boot PRISTINE (sessionIds cleared — restore races ended), and an unborn-mirror push is an honest no-op, not local-only (pristine-store discovery: the old knowledge assertion passed only on accumulated dev state). All 464 deterministic + 85/85/85 gate green on the hosted runner too. The `rules` browser scenario was UN-PARKED — the r39 diagnosis: the spec read zstd-compressed session directories as flat files and hardcoded a rule id; the product was always right. The enrich e2e earned its keep: it exposed two real product bugs invisible to every deterministic layer (verify.md T9/T10 — the body-hash anchor convention mismatch that silently blocked enrichment since P2, and the missing host-plane route) (r38 lesson: the DRAFT screen turns composer text into a first MESSAGE, not a command — establish a session before exercising command surfaces; and RR2=137: a chatty live loop that records mid-test can be OOM-killed — keep e2e prompts tool-free in WORDS the model obeys; and 2026-09-23: a tape records the CONTEXT it was distilled in — re-record whole projects, never one spec of a shared boot, and never run two GPU suites at once). 608 unit/integration, zero skips when the TreeDX container is up (live-gate fails loudly when configured-but-unreachable; skips only with no configuration at all), under a GATED coverage ledger: `npm run coverage:ci` (c8 --check-coverage) enforces ≥85% statements/branches/functions/lines in CI — current 97.94 / 86.47 / 93.82; `npm run coverage:e2e` remains the browser-plane ledger (eight replays since the plans journey joined, boot-level V8 profiles remapped through REAL source maps; current 79.92/64.64/76.28 — reported, not tuned; first ledger 80/62 before the audit). The 2026-09-23 coverage audit closed its own gap list the same way: providerKindFor policy rows, credential migration, the git-command surface incl. every refusal text (T13), the TreeDX client's failure vocabulary (timeout/bad_json/envelope), git-plane auth (T11), the push retry/divergence paths, scheduler pull rows, listing pagination over a paginating stub (T12), overlay-delete, rule-number walk-past by prefix (id-uniqueness), the composer busy-retry budget, and the coverage instrumentation itself; then the deterministic plane was swept to the gate — engine-lifecycle (real cordis Context + real base engine: engine.ts 40→91 stmts), the tool wrappers' full success/refusal surface, the TreeDX error taxonomy over stub faults + parser-shape drift via injected fetchImpl, the local-path git transport, host-command error arms, and the pure planners (vocabulary/enrich/indexing/search/arrival/archive) — catching one REAL bug (canonicalizeRemote carried embedded credentials into the project key: same repo with/without creds forked the pool; fixed + pinned). CI/CD shipped 2026-09-24 and went fully green 2026-09-25: .github/workflows/ci.yml (deterministic gate + seven-segment tape-replay acceptance with NO LLM/GPU/key — tape misses fail loud, hosted runs ship diff-dumps sorted by shared prefix) and release.yml (tag = package version → suite-gated npm publish --provenance; NPM_TOKEN strategy chosen, wired for the treeseed-ai org move); the pristine-runner dress rehearsal caught the scaffold-clobbering patch guard, the credential-less-provider death, and the unregistered-workspace home — plus the profile is now built with plain npm (dsh plugin add was a pnpm forwarder — nothing in this repo touches pnpm, and it is not and never will be a monorepo; the host lock is a standalone manifest). docs/development.md § Hosted CI.
+Git history was rewritten 2026-09-20 (test-results/.dsh purged, .git 7M→840K) and force-pushed —
+clone fresh or `git reset --hard origin/main` after pulling.
+**Knowledge layer P1 (record §13) is complete and live-proven**: signatures collect at real
+`turn/end`s (r35j), the fork composes topics live (r36 — same-file turns merge, topic changes
+split), the index + `chapters_search` + redaction + `/chapters-link`/`/chapters-status` ride a
+sync loop that degrades to local-only honestly and rebuilds the mirror on divergence, with the
+two-machine exit criterion automated over a real git smart-HTTP remote (integration + the
+`knowledge.spec.ts` browser journey). **P2 is BUILT (2026-09-20)**: the idle/after-push
+enrichment ladder with validation-before-commit, provenance chains (`generated:` newest-first),
+the body-hash guard as the only sanctioned chapter-file mutation, `/chapters-enrich
+run|model|report`; shadow-by-default emergent vocabulary writing git-visible `topic-alias`
+curation + derived `topics/vocabulary.json`; and index-level fragment stitching (adjacent
+legacy fragments cohere into ONE search entry citing all members — nothing merged on disk). Two-machine exit criterion proven — catching r37 on the way: stageAllAndCommit compared the workdir against itself, making modifications to tracked files permanently invisible to commits (additive P1 hid it; enrichment would never have traveled). **P3 is BUILT (2026-09-20, §15 amendment: approval = per-machine curation fact, never a file rewrite)**: write-once proposed rule files, /chapters-rule add|list|approve|revoke, chapters_rule_propose tool, verbatim core block in the continuation notice (byte-identical ABSENT, golden-tested), refuse-with-numbers overflow budget, category-aware search with a per-machine core bonus, and the rules lifecycle proven transport-grade over a real pool with three machines. **P3c — two-tier rules is BUILT, both capture speeds (#50; record §7.1 + §7.3–§7.9, amendments 2026-10-20 and 2026-10-21). Two things remain unverified, for different reasons: the **browser plane** (the host pin moved to 0.2.0-rc.2 in #54 and the boot's named refusal lifted, but the corpus still has to be re-distilled on the new host before ANY browser-plane claim is real — this feature added a tool AND changed the preset persona, both prompt bytes), and **mining quality beyond n=3** — `npm run mining:probe` did run against the real session model (`qwen3.8-flash`, regional token-plan door; the GPU box was unnecessary) on three of this repo's own chapters: 9 rules, 6 stated / 3 inferred, all inferences confined to the chapter with no human text. See `docs/verify.md § Two-Tier Rules` R5 and `docs/backlog.md` 1b/1c.** The hole was concrete, not vague: `planSummarize` composes `leadSections = [planSection, plotSection]`, so a plan survives an in-place compaction and a plot survives it, and a **rule does not**. Session rules (`scope: session`, local, never staged — one filter in `planStoreToRepo`) captured by a deterministic `ADD RULE:` parse at the existing `turn/end` listener (zero model tokens, invariant 1) plus enrichment capture (`rulesEnrichment`, ON) that MINES standing orders the human never said and lets them govern on arrival — `rulesAutoActivate: true` is the default, and the earlier design that required a verbatim human quote before a mined rule could apply was REJECTED by the maintainer and removed (record Amendment 2026-10-21): demanding proof that a human already said it makes the tier redundant with the deterministic marker, and the premise of the tier is that the human may not know. Visibility replaced permission: each mined rule renders with its warrant (`stated by you, mined from ch.N` / `inferred from ch.N — nobody said it`), the agent must NAME the session rules that shaped its reply, at most 3 per chapter plus per-tier display caps, and `reviewOnly` + `approve` is the opt-in review-before-trust posture; `rulesModel` gives mining a model of its own (one extra bounded call, and its answer REPLACES the annotation pass's rules). One auxiliary completion budget, `enrichmentMaxTokens` (default 4000), is the single source for that ceiling on both planes — the route measured here does not enforce `max_tokens` and counts reasoning tokens toward completion usage, so a small number is not safety, it is truncation on a stricter provider. What did not loosen: a session rule never overrides a project rule, and never becomes one without a human. Activation itself is unchanged: **DERIVED** from the ancestor path, never a `curation.jsonl` fact — the 2026-09-20 per-machine approval boundary is NOT relaxed, it still governs the entire shared tier. Rules are carried at the two moments a head is rebuilt — the continuation notice AND the in-place compaction checkpoint (`rulesCarry` is the third lead section in `planSummarize`, and `session-rules.renderRulesBlock` is the ONE builder both paths plus `chapters_rules` call: a source-shape row fails if either door starts picking rules itself) — **never injected per request**: invariant 3, and measured llama.cpp `cacheReuse 0` on a head-position replacement means a churning ruleset is a cache-wipe machine. `chapters_continue` carries both tiers, `chapters_fork` carries project only — the SAME `intent` axis plans already use (`docs/plans-carriage.md` §§ 9–13), not a new distinction. **#52 (same round, second half): rule ancestry ALSO crosses the delegation edge** —
+  `session-rules.ruleAncestorSet` walks registry `parentSession` ∪ the kernel header's
+  `parentSession`, transitively, READ-ONLY, upward only (a subagent inherits its delegator's orders; a
+  child's inferences never govern the parent), bounded at 64 expansions and LOUD when the cap bites;
+  every door, the checkpoint and `/chapters-rule active` call that ONE walk, and an anti-drift row
+  fails if a plane computes ancestry by hand again — hand-built ancestry is how delegated subagents
+  ended up with zero rules. And the `chapters` preset's **persona suffix** is the per-composition
+  channel that tells a session — fresh, continued, or delegated — to run `chapters_rules` before a
+  task and `chapters_search` for history: that is allowed because it is preset-scoped, not a
+  system-prompt contribution (invariant 3), and two couplings are pinned by behaviour: the suffix must
+  stay matched by the plot template-echo guard, and it may not introduce a `{{variable}}` the host has
+  not registered. Changing that suffix is a PRODUCT PROMPT change — the tape re-distill debt GROWS,
+  it does not shrink. Selection is pinned → topicality → index-only, via `rules.selectRules` — the head's selector, deliberately NOT `search.rankEntries`, which ranks the corpus (one implementation of each job, and bending a rebuilt head to read index shards was rejected); per-tier count caps config-driven, and the **withheld count is mandatory** — silent selection would rebuild "lost in the noise" inside the fix for it; the token ceiling still refuses with numbers, never clips. **No global tier was built, because none was needed**: `projectKey` is UUIDv5 over the canonicalized *remote* and `harnessId` defaults to hostname, so checkouts of one repository already share one rule namespace; what that round actually owes is loudness for the four ways the identity silently diverges (record §7.8) — a `path-derived` key, a fork listed first, TreeDX keying on the pool location, and an unlinked/un-synced clone, each of which must SAY it rendered zero rules: `/chapters-status` now prints an `Identity:` line and warns when the derived key differs from the bound one (the repo's own non-git test fixture trips it, so the warning is not theoretical).
+  One design lesson from that reversal, because it is the recurring mistake in this repo: a safety mechanism must block the harm, not the value. The quote gate blocked invented rules by also blocking every inferred one; the mechanisms that replaced it (a rendered warrant, the agent naming its rules, caps, one-command revoke) hold the same risk without amputating the feature. Suspicion of model authorship is a reason to make output visible and reversible, not a reason to demand human provenance.
+  Two local build facts, both learned the hard way: the deterministic suites need **Node ≥ 24** (`engines`), and on this box's Node 22 every test file fails in a way that looks like your diff; and until 2026-10-21 `npm run coverage:ci` intermittently reddened `git-auth-classification`/`sync-remote` with an EPIPE blamed on their `before` hook — **diagnosed as pre-existing, which was true and not the point**: the test git server wrote request bodies into a CGI child's `stdin` with no error listener, so a child that had already exited raised an async EPIPE nobody handled. Streams are guarded now (three consecutive combined runs: 800 pass / 0 fail). Recording the sequence because the mistake is the reusable part: proving a failure predates your diff is a step, not an answer.
+**Knowledge transport is now a provider seam (2026-09-21, record §15: "transport is pluggable; git is one provider" + "host-injected context is not conversation")**: `src/provider.ts`'s six verbs carry every sync path; `kind:'git'` (default, every pre-existing record — zero behavior change) or `kind:'treedx'` (`/chapters-link treedx+<url>/<repo> <token>`, `src/treedx/`: workspace-create → overlay-write → commit transport, `.treedx-state.json` mirror memory). Search/rules/index/notice layers read the materialized mirror unchanged — §3.1 survives both backends; divergence routes through rebuild-from-the-store in both; TreeDX lease contention maps to the existing rejected→pull-retry, moved head to diverged. Contract + truth table in `docs/provider.md`; TreeDX API facts (doc-reads vs live-measured, with corrections) in `spikes/treedx/FINDINGS.md`; dev loop `scripts/treedx-local.sh` + `dev/treedx.compose.yaml` (the cloned repo's own compose is platform-bound and will not boot standalone — measured). Transport-grade proof: 24 tests over an in-process stub (`treedx-{provider,sync,link}.test.ts`); the real-container exit criterion (`treedx-live.test.ts`) ran and PASSED 2026-09-21 (5/5 against a booted dev-auth service; full suite 286/286 zero skips — the live run caught three parser shapes, the born-with-`.treedxkeep` phantom-deletion trap, the lease-survives-TTL close requirement, and a swallowed auth detail, all fixed and pinned). **Re-verification 2026-09-23 caught one more, in the wild:** `paths/list` PAGINATES (limit 100, base64 offset cursor in `page.nextCursor`) — reading one page silently truncated the corpus once the shared dev repo grew past 100 paths (machine B reported 'up to date' while missing real files). `corpusPaths` now follows the cursor to the end; the paginating stub + a 150-file row pin it (T12), and the live container proves it at the real service. **The same round landed the injection screen** (`src/injections.ts`): host-injected context (instruction files, runtime snapshots, skill catalogs, our own TOC notice — event-level and `<system-reminder>` spans inside human messages) is marked-and-counted, never archived; the conversation-bytes guarantee and TOC `(N msgs)` now say what is actually true, and the knowledge corpus carries no project's instruction bytes (H1 rows in `docs/verify.md`).
+**Session-plan carriage is BUILT (2026-10-09, `docs/plans-carriage.md`)**: `src/plans.ts` pairs an
+`exit_plan_mode` call with the `tool/result` that carries the human verdict (approved / rejected /
+dismissed / pending / superseded / failed — the fifth class is the review never opening, which is not a
+verdict); chapters carry a `## Plans in this chapter` block AFTER the verbatim transcript with the plan's
+outline, bounded head and content-addressed full text; `plan/mode` folds last-value-wins into `planMode:`
+instead of falling into `unrenderedSeqs`; the child's notice carries the operative plan (intent-aware
+since the second round — see below; a pending one is marked unapproved); plans are forced chapter boundaries in
+both segmenters and title the chapter they conclude. Two truths worth keeping: the token meter is NEVER
+exempted (the block is counted by `preflight`, and a plan-less path renders zero bytes — which is why all
+seven tapes still replay WITHOUT re-recording, verified 2026-10-09), and a plan whose review is still open
+sits in an unfinished turn above the archive ceiling, so it is carried as live and un-stored. Fixed on the
+way: chapter `artifacts/…` citations pointed at paths `chapters_artifact` could not resolve at all
+(`writeArchive` writes inside the session tree; the resolver only looked at the store root) — true for
+every deferred blob since arrival-stubbing shipped, now pinned (verify.md P10). The browser plane is IN the chain (project `plans`, verified 2026-10-10); its tape is distilled from
+the scripted upstream `tests/e2e/stub-model.ts` because this box's model server drops the stream
+mid-turn — read `tests/fixtures/model-tape/plans/PROVENANCE.md` before quoting what it proves (the
+carriage yes, a model's choice to plan no). **Second round, same day, four decisions landed**
+(`docs/plans-carriage.md` §§ 9–13, verify.md P12–P17):
+- **Intent decides what a child is told.** A CONTINUATION (`chapters_continue`) extends the same stream
+  of work, so it gets `## Active plan` + `## Previous plans on this path` and, while the parent was still
+  planning, a seeded `plan/mode`. A BRANCH (`chapters_fork`, the fork button) splits a new direction, so it
+  gets **zero** plan bytes — its plans are history, in the cited chapters and as documents.
+- **A plan is a document of a third kind**: `kind: plan`, written in `chapters/` as `plan-NNN-<slug>.md`
+  with its own registry counter (`nextPlanNumber`, allocated through the registry — never a directory
+  scan), so it never consumes a chapter number, is carried by the pool transport and the mirror rehydrate
+  for free, and is findable with `chapters_search` **as a plan**. Superseding writes a new document; the
+  old one keeps its bytes.
+- **The enrichment ladder never touches a plan document.** Directives are not narrative; paraphrasing an
+  order is the drift this store exists to prevent. The guard reads the file's own frontmatter.
+- **The operative plan is carried into every in-place checkpoint** (the plot mechanism, but chosen
+  session-wide and newest-first), bounded, with truncation announced.
+- **Findability round (0.1.12, `docs/plans-carriage.md` § 14, knowledge-repo Amendment 2026-10-11): two
+  doors, ONE scorer (`search.rankEntries`) — the pool mirror when pulled, the workspace store otherwise
+  (and as a fallback when the pool has no match). A bare workspace used to answer `chapters_search` with
+  "link a remote" while its own chapters, `kind: plan` documents and rules sat two directories away; that
+  was the flaw the audit found. The answer must NAME ITS DOOR ("searched this machine's store, N docs …")
+  so "this machine only" is never read as "the whole project", and "nothing matched" ≠ "nothing archived
+  here" are reported apart (`documents`/`empty`). Artifacts are never indexed (they answer to
+  `chapters_artifact`; a second index is forbidden). The notice gains `## Finding things` naming
+  read/chapters_artifact/chapters_search (`retrievalHints`, default on) because an unmentioned tool does
+  not exist to a small model. Two pinned rows asserted the old contract and failed loudly — that is why
+  this is a fact rather than a guess; amended with the reason in the diff.
+- **Kernel-drift gate (`tests/unit/host-seed-contract.test.ts`)**: the seeded `plan/mode` depends on the
+  host knowing the type and treating it as NOT surface-eligible. Read the kernel's OWN exported predicates
+  (`KNOWN_SESSION_EVENT_TYPES`, `isSurfaceEligibleType`, `isAppendSurfaceEvent`), never reimplement them —
+  a kernel change that silently ungates a child must show up as a red row, not as a passing suite.
+- **Two deterministic doors, one builder (`/chapters-fork`, `/chapters-continue`)** — the load-bearing
+  lesson of attempt 5: **a tape cannot carry a model-authored range.** The recorded `chapters_continue`
+  said `endSeq: 30`, the runner's ceiling was 29, and `validateRanges` refused it — correctly. And a small
+  local model will not reliably chain `chapters_segment` → `chapters_continue` at all. So anything that must
+  be accepted repeatably goes through the plugin's OWN derivation (`deriveRanges`/`composeChapters`, zero
+  model involvement); the tool remains for the model's use but is never the only proof path. Both doors come
+  from `deterministicCommand(door)` and a row pins that they **archive identically** (same ranges, titles,
+  plan facts) — two implementations would drift. `intent` is the ONLY semantic difference: continue ⇒
+  `## Active plan` (+ seeded `plan/mode` while still planning); branch ⇒ zero directive bytes.
+  Also measured there: **the turn containing a plan submission does not end until the review is answered**,
+  so a session whose only turn is pending has no archive ceiling and the door refuses with its first guard.
+- **The one exception to the injection screen**: the harness's `plan-mode` + `form:'notice'`
+  mode-flip sentence archives verbatim (named by producer AND form, so it cannot widen — v3 wrapper
+  `{kind:'plugin', plugin:'plan-mode'}` and v4 `{kind:'plan-mode'}` both match, issue #43).
+  `isHumanAuthored` stays strict on purpose — it drives topic signatures, and the r28 lesson was that
+  injected text moves chapter boundaries.
+**Outstanding: the human verification rows (live `/compact` in a real browser, readability
+judgment), the seeded-gate case OBSERVED in a browser (pinned deterministically; needs a second distilled session — `docs/plans-carriage.md` § 15), per-message anchoring (the button forks at the conversation's end today; `deriveRanges`
+already supports any anchor), and the default-preset shipping policy (opt-in menu vs profile
+default), which is the user's call, not ours.**
+
+The fiber-eviction trap `dsh-session-fork/src/branch.ts:10-14` warns about did **not** bite — an unattached
+session was the whole explanation for round 6's "not listed", fixed by
+`workspaceRegistry.createCanonical(cwd)` → `workspace.attachSession(id)`.
+
+**Cache behaviour measured (rounds 10-11, 13, 16, real provider).** A continuation builds its own cache —
+0% hit cold, 74% warm — and the parent keeps hitting across the boundary, so **G3 and G2 are green**. G1's
+head is now *measured* for the composed shape: r16's `setup`-mounted child's first request was **13,315
+tokens (27-tool header, this roster)** — quote the older "≈ 8K" only as a projection. Steady state it
+protects: 396,800 cached + 822 uncached (**99.79%**) live session. E3 measured — and it is
+per-machine (r23/r28): on the cloud provider a replacement keeps ~7.4K of prefix cached (refill
+halves, 13,658 → ~7,000); on llama.cpp (the target) the slot reuses NOTHING across a head-position
+replacement (cacheReuse 0) — the local win is zero-token compaction (r28: 0 prompt tokens vs ~11 min
+for an LLM summary on that box) plus ~2 s steady-state turns. **Never quote one machine's cache
+number for the other.**
+
+Metric formula, since getting it wrong produces 1721% hit rates: `totalPrompt = inputTokens +
+cacheReadTokens`; `hit = cacheReadTokens / totalPrompt`. Judge "cache undisturbed" by
+`cacheReadTokens` not collapsing, **not** by hit percentage, which falls innocently as the prompt grows
+past a cache-block boundary.
+
+Phase 1 follow-ups CLOSED: the title call is the *service* (`sessionController.rename`, live-handle
+window — r25 durable), and the preset/composition note in invariant 2 ships in every child.
+
+Coexistence with `dsh-session-fork` is currently **untestable, not disputed**: the shipped example fails
+to boot the installed host ALONE (its rc.2-era code vs rc.1's `webServer` inject requirement — verified
+by pair-boot then solo-boot, r26). Name-spaces are disjoint by inspection; re-run the pair-boot on a
+version-matched host before claiming either way. The dev/test loop that avoids restarting the harness
+being edited from is solved — see [docs/development.md](docs/development.md).
+
+Then [docs/contract.md](docs/contract.md) for how to declare things, and
+[docs/verify.md](docs/verify.md) before claiming any step passes.

package/docs/verify.md

@@ -165,6 +165,88 @@ renderer, the segmentation tool, and the child's notice.
 | P15 | Plan mode survives a continuation only when it should | seeded `plan/mode` ONLY for `intent: 'continue'` while the fold says active (measured: kernel accepts the two-event seed, host projection folds it to `active:true`, one-event control does not); never for a branch, never after an approval — because approving a plan EXITS plan mode | unit `continue-plans.test.ts` (four rows: seed shape, approved-no-seed, branch-no-seed, `planSeedMode:false`) against the installed-kernel probe recorded in docs/plans-carriage.md § 10 |
 | P16 | The notice reads the intent, not just the log | continuation → `## Active plan` + `## Previous plans on this path` (marked history); branch → zero bytes, plans live in the cited chapters and as documents; the mode statement is either "the directive above is live" or "this child starts OUTSIDE plan mode", never both | unit `plans.test.ts` (seeded/unseeded/branch rows) |
 | P17 | The one injection-screen exception is named, not open-ended | `kind:'plugin' + plugin:'plan-mode' + form:'notice'` archives verbatim; any other plugin notice, snapshot or instruction shape still screens; `isHumanAuthored` (which drives topic signatures and `(N msgs)`) is unchanged | unit `injections.test.ts` (two rows, incl. wrong-form and wrong-plugin negatives) |
+## Repair (#60) — recovering an archive from the durable log
+
+| # | Claim | Procedure | Status 2026-10-22 |
+|---|---|---|---|
+| R1 | The auditor finds the measured damage | `node scripts/chapters-repair.mjs --home <lab> --project <cwd> --cwd-override <lab-tree>` on a COPY of SAIP's live registry + store + 26 session logs | **PASS** — 436 findings: hollow 5, empty-artifact 335, never-archived-span 19, unregistered-file 73, ghost manifest 2, stuck reservation 2. Matches the manual audit exactly. |
+| R2 | A repair re-derives lost knowledge | apply, then grep for three phrases that previously matched 0 files | **PASS** — span 5265-5467 (the "foundational to the project" hosting brief) is now in `chapters/030-hosting-…-plan-1.md`; 719 moves across 3 passes |
+| R3 | Repair converges (idempotent) | run apply again; the third pass must move 0 | **PASS** — pass 3 = 0 moves; audit falls 436 → 3 findings |
+| R4 | What it will NOT do | 3 files remain: two `015-*.md` claiming one number. Re-registering needs a new number = renumbering a chapter → refused, with the reason printed | **PASS** — residue is a human decision, reported as such, not silently "fixed" |
+| R5 | Nothing is deleted or rewritten | after a full apply, the husk files still exist (copied to `.repair-quarantine/`), the registry keeps every record (append-only), and the log's md5 is unchanged | **PASS** |
+| R6 | The run is reversible | `restoreRepair` walks the journal backwards; new files return from quarantine | **PASS** — `tests/integration/repair-apply.test.ts` |
+| R7 | Dry-run is genuinely read-only | registry bytes and directory listing identical before/after | **PASS** — pinned by a row |
+| R8 | LIVE application | `~/.dsh` is read-only to the agent sandbox (EROFS), so SAIP and this repo have NOT been repaired for real | **BLOCKED on the user**: run `node scripts/chapters-repair.mjs --project /home/adrian/Projects/saip --apply all --yes` yourself, or approve the sandbox |
+
+Known limitation, stated rather than hidden: an audit through `ctx.fs` cannot list a directory, so it
+reports `blindSpots: ['orphan-file','test-litter']`; the offline script has `readdir` and sees them.
+
+## Two-Tier Rules — SPEC (record §7.1, §7.3–§7.9; issue #50)
+
+Rows **R1–R10 verified 2026-10-20** except **R-e2e**, which this host cannot run (see the last row
+and §13 P3c). Each row below was written docs-first and then proven to fail on the mutation it
+guards — the mutation runs are named per row so a future reader can repeat them. The P3 rows above
+stay the shipped-behavior record; these extend it with the session tier.
+
+| # | Claim | Status | How it is witnessed (and the mutation that proves it) |
+|---|---|---|---|
+| R0 | The empty tier still renders **zero bytes**, and the pre-#50 option shape renders **byte-identically** to the previous builder | ✅ verified | The golden literal was captured by running **HEAD's** `buildRulesSection` over the same fixture and diffing it against the new one (text-equal, kind-equal, only the non-rendered `withheld` field added). On the checkpoint path an empty set asserts neither header nor announcement appears |
+| R1 | A rule survives an in-place compaction | ✅ verified | `rules-checkpoint.test.ts` drives the **REAL realm engine** through `summarize()` and reads the text that would be prefilled next: project rule + session rule verbatim, project before session (positional precedence); a parent's rule rides the child's checkpoint (R1b — the tier binds the TREE); over budget the omission is announced. Mutation: dropping `rulesSection` from `leadSections` breaks 3 of 4 rows |
+| R2 | `chapters_continue` carries both tiers; `chapters_fork` carries project and **zero session bytes** | ✅ verified | `rules-doors.test.ts` asserts the asymmetry through the shared renderer, and a **source-shape row** fails if `tools.ts` or `engine.ts` calls `buildRulesSection` directly — two rule-pickers would drift apart invisibly (the same argument that pins `rankEntries` and `doors.ts`) |
+| R3 | `ADD RULE:` is deterministic and free | ✅ verified | `session-rules.test.ts` (8 rows): line-start-only, minimum length, dedupe; the two injection screens (`isHumanAuthored`, `stripReminderSpans`) each with a positive and a negative; assistant-restatement never captures (the amplification path); idempotent across repeated turn/ends; numbers honor registry **and** disk; §9 credential screen; listener containment (disabled / missing cwd / throwing store). The module holds no `ctx.llm` reference at all |
+| R4 | Session rules never reach the shared pool, on **either** provider | ✅ verified | `rules-transport.test.ts`: a real git pool (A stages project only, B pulls and never sees the session file, A still renders it locally — exclusion ≠ invisibility) and the TreeDX stub's commit tree. Mutation: deleting the single `isSessionRuleFile` skip reddens both |
+| R5 | Mined rules are governed by **policy**, not by proof that a human said them, and each one carries its **warrant** (§7.5, Amendment 2026-10-21) | ✅ verified | `rules-mining.test.ts` (20 rows): `rules` is OPTIONAL so the old three-field answer still validates; bounds (≤3 **written** per chapter, sub-minimum dropped, a garbage `rules` value cannot cost the annotation); the quote check is a LABEL — `stated` when the chapter's human bytes contain it, `inferred` when they don't, and BOTH govern under the default `rulesAutoActivate: true`; the row named "THE REVERSAL, PINNED" asserts exactly that, and the rendered head shows `inferred from ch.N — nobody said it` beside the text with the agent required to name the rules it applied; `autoActivate: false` writes `reviewOnly: true` and renders NOTHING until `approve` (a curation fact — the write-once file is byte-compared unchanged); assistant prose is inadmissible even as a label; ladder rows prove human-bytes-only evidence, mining before the hash-guarded write, `rulesEnrichment: false` logging the drop, an unwired plane WARNING, a throwing sink not losing the annotation, and `rulesModel` making a second call on its own route whose answer replaces the annotation pass's; `/chapters-rule active` prints the posture and the inferred count. Mutations: predicate ignoring `reviewOnly` → 2 rows; `autoActivate` ignored → 2; `rulesModel` ignored → 2; basis classification collapsed → 1 |
+| R6 | Selection is deterministic and announced | ✅ verified | Shuffled input order yields byte-identical selection; two identical runs render identical text; the withheld line appears exactly when `shown < active`, and its ABSENCE is asserted when no cap is set. `active`/`chapters_rules` return the counts even when nothing was withheld, so "you are seeing all of it" is a fact |
+| R7 | Nothing was silently clipped anywhere the budget bites | ✅ verified | Token ceiling still returns `refusal` with per-rule numbers and now counts **both** tiers; the checkpoint announces the omission instead of squeezing; the door path still refuses the continuation with numbers (§1.2) |
+| R8 | Ungoverned never looks like governed | ✅ verified | `/chapters-status` prints an `Identity:` line with the divergence warning — and this repo's own non-git test workspace hit that branch during verification, which is the honest evidence the warning is not theoretical; `chapters_rules` answers "no linked project" separately from "nothing approved on this machine" separately from "nothing captured this session"; the head states the zero-project tier only when session rules are actually governing it |
+| R10 | Every chapters session — fresh, continued, or DELEGATED — is told to use `chapters_rules` and `chapters_search` | persona row parsed from the shipped patch: the suffix names both tools, names delegation, keeps the `PLOT:` discipline, adds no unregistered prompt variable, and remains matched by the plot template-echo guard. Verified by mutation — dropping `chapters_rules` from the suffix reddens the row |
+| R11 | Rule ancestry crosses the delegation edge, and every door uses the ONE walk | `tests/unit/rules-lineage.test.ts` (8 rows: header-only parent, transitive mixed edges, one-way direction, cycle termination, the 64-expansion cap with its loud flag, unknown session, throwing reader, anti-drift). Verified by mutation: disabling the header edge reddens 4 rows |
+| R9 | A conflict is reported, never resolved | ✅ verified | `conflicts` wrote no file (directory listing asserted unchanged), the prompt explicitly forbids rewriting, and with no conversation route the verb refuses rather than half-answering |
+| R10 | Losing a checkout is re-derivation, not corruption | 🟡 partial | `parseRuleMarkers` is deterministic over message text and capture dedupes against disk, so a replay fills gaps without duplicating — but the **end-to-end wipe-and-replay row is not written**. The mining half is now re-derivable by re-running the ladder, and capture dedupes against disk, so a replay fills gaps rather than duplicating. |
+| R-e2e | The browser plane: a live model, the `rules` journey, the new tool in the header | ❌ cannot run on this host | `npm run test:e2e:replay` **refuses by name** (`tests/e2e/boot.ts:130`: the pinned host predates preset declaration rows). The re-record this feature owes is queued with the `dev/dsh-host-lock` move in `docs/backlog.md` — stated, not skipped silently |
+
+**First live witness (2026-10-21, `npm run mining:probe`).** Three real archived chapters of this repo,
+mined by `qwen3.8-flash` — the model that powers live sessions here — through the shipped code paths
+(`buildMineInput` → `parseMinedRules` → `quoteIsHuman` → `captureMinedRules`), local :8080 down so the
+token-plan hosted route was used. Nine rules captured (the 3-per-chapter cap bound every chapter),
+**6 stated / 3 inferred**, and all three inferences came from the one chapter with ZERO human bytes —
+a subagent chapter — which is exactly what the classification should do. The model's own `basis` claim
+was the weaker signal: chapters 2 and 3 each declared only 1 stated rule, while the plugin's check
+found 3/3 quotes genuinely present in the human text. So the label is earned from evidence, not from
+the model's say-so, and the head rendered all nine in 479 tokens with nothing withheld at a cap of 12.
+On quality: none of the nine was wrong or unsafe; the three inferences were arguably the most
+transferable ("verify decisive architectural claims in shipped code before treating them as settled").
+n = 3 chapters on one repo's own history is not proof, but it is no longer nothing.
+
+**A cost finding, stated twice because the first version was wrong.** The probe reported completion
+usage of 969–3237 tokens against a 700-token request. The inference I drew — that the annotation
+ceiling was truncating mining — was **wrong**: a direct test of the same route with a 64-token cap
+still produced 113 tokens with `finish_reason: stop`, and usage itemizes
+`completion_tokens_details.reasoning_tokens`. `max_tokens` is advisory on this provider, not
+enforced, and reasoning counts toward completion usage. So nothing was truncating; what was true is
+that the ceiling had no business being a literal at three call sites (900/900/600) sized for
+pre-mining answers. It is now `enrichmentMaxTokens`, default **4000** — above the observed 3.2K —
+because a *strict* provider would enforce it, and one that itemizes reasoning deserves a budget that
+covers the thinking. The lesson stays worth recording: a usage number is not evidence about a
+mechanism until the mechanism is tested directly.
+
+**Inference QUALITY had no witness when the posture was set; the first data is below and it is thin.** The mechanisms are proven against fixtures; nothing here can say how often a small model infers a *correct* standing order, now that inferences govern by default. That is the open risk of the 2026-10-21 decision, and the measured first step is cheap: point the enrichment route at a reachable model, run `/chapters-enrich run` over real archives, then read the `stated` vs `inferred` ratio in `/chapters-rule list --scope session`. If inferences are wrong more often than a human catches them in replies, the answer is `rulesAutoActivate: false` — not a new evidence gate (the amendment records why the gate was the wrong instrument). The box's GPU driver was unreachable when this landed (`nvidia-smi` cannot talk to it), so no vLLM boot and no real mining pass ran.
+
+**Two environmental facts, learned the hard way on 2026-10-20 and worth repeating.** (1) The
+deterministic suites need **Node ≥ 24** (`package.json` engines); on Node 22 every test file fails
+with `ERR_NO_TYPESCRIPT`/unknown-extension, which looks exactly like a broken change and is not one.
+(2) Under `npm run coverage:ci`'s parallel load the real-HTTP-git files
+(`git-auth-classification`, `sync-remote`) intermittently failed with an EPIPE blamed on their
+`before` hook. It was **recorded as a box-level flake and left alone — which was the wrong call**: the
+"prove it predates my diff" step was right, and stopping there was not. The cause was real and is now
+fixed in the rig: the test git server wrote each request body into a CGI child's `stdin` with **no
+error listener**, so a child that had already exited raised an async EPIPE with no handler, which the
+runner reported as uncaughtException after the test ended. Guards now sit on the child's three
+streams and on both request/response objects ([tests/integration/http-git-server.ts](http-git-server.ts));
+three consecutive combined runs since then are 800 pass / 0 fail. Lesson for the next agent, in the
+repo's own style: a pre-existing failure is still a failure.
+Ledger on this branch: **93.16% statements / 85.53% branches / 90.01% functions** — the gate holds.
+
 ## The Cache Metric, Before You Trust a Number
 
 `usage.inputTokens` is the **uncached delta** and `usage.cacheReadTokens` is the cached prefix, so:
@@ -204,6 +286,27 @@ that still need a running chapter engine:
 | E7 | Arrival-time artifacting (architecture amendment) | **green 2026-09-19 (9.3m)**: 373KB book / one read → exactly 1 arrival prune at the tail; model answers buried token + chapter count via 5 `chapters_artifact` calls; ZERO compaction events at production 0.9; blob fingerprint in no `request/*` event; cache table in FINDINGS shows prefix intact (cacheRead monotonically 15.7K→24.5K) |
 | E8 | Plot carriage across in-place checkpoints | forward path live (persona discipline — suiteB oversized run carries `PLOT:` blocks through 7 compactions); render→extract round trip pinned in unit (`carried plot survives the checkpoint round-trip`); elicited fallback unit-pinned (capped input/output, degrades to null) — fires only when the agent writes no note | compaction lands at `agent/pre-step`, bracketed `compaction/start.turn` = open turn number (r13/r17 `turn: 2`); never mid-request, never mid-step |
 
+## Door 5 — Subagent Settlement (#47; read contract corrected by #58)
+
+The settlement door is the only archive that runs with nobody watching, so its checks are about **payload**,
+not about plumbing. Every row here was verified to fail on the mutation it guards.
+
+| # | Check | How to verify |
+|---|---|---|
+| S1 | The durable read is payload-bearing | `tests/unit/host-durable-read.test.ts` reads the **host's own published types** and asserts `SessionEventRecord` has no `data` key while `readSession`/`snapshotSessionEvent` yields one. This is a kernel-drift gate: a host rename must turn it red, not re-create husks. Cross-check by hand: `zstd -dc ~/.dsh/sessions/<slug>/<id>/session.v4.jsonl.zstd \| head -20` for a settled child — the real log has `data.name`, `data.arguments`, `data.message.content`; a hollow chapter has none of them. |
+| S2 | Both arms, both modes | A **one-shot** child settles with a live handle (`snapshotEvents()`); a **continuable** child is disposed *before* `subagent/end` (`dsh-subagent/lib/index.js:1240-1250`) so only the durable arm runs. Integration rows cover each arm × each mode, and one covers **depth 2** (a continuation child that delegates — `d57b4710`'s parent is `ch-dc3be3ab` in the SAIP field data). |
+| S3 | No archive that rendered nothing | Feed the real `data`-less record shape to `saveSession` and assert: skipped `payloadless`, **no file written**, **no chapter number reserved**, `nextChapterNumber` unchanged. Then the converse pair: the same span read through `readSession` archives with `stats.messages > 0`. |
+| S4 | The watermark is never poisoned | After a S3 refusal, a later settle of the same child still archives (i.e. `max(endSeq)` did not advance). This is the property that makes the defect recoverable instead of permanent. |
+| S5 | Warnings survive the door | `writeArchive` emits `N event(s) rendered no output` for a low-content chapter; assert door 5 logs it (via the injected `warn`/sink), not returns-and-drops. |
+| S6 | Lineage recorded, tree NOT re-homed | After a settle the child's own row/frontmatter carry `subagent` + `parentSession` from the durable header, and the child keeps its OWN tree: `rootSession` is unchanged and its chapter paths still resolve. **AMENDED 2026-10-22 (#58):** this row originally demanded `linkChild` onto the parent's path. Measured against the code, that buys no reach (`buildIndex` walks ancestors only) and re-homes files already written under the child's root, so the door does not link; the row now pins the absence, and `subagent-auto-save.test.ts` ("lineage by design") holds both halves. |
+| S7 | Fanout containment | A 10-child fanout schedules sync 10× and runs enrichment **0** times (`runNow` never per settlement) and no child blocks another (per-child promise chains). |
+| S8 | Field census (human, one-time) | `SELECT` the store: no chapter may have `messages === 0` with `events > 0`. The recovery half of this defect is #60; measure **before/after counts** there, and quote them as a repair result, never as a passing test. |
+
+**Anti-pattern that created this section:** a stub that returns *your* type instead of the host's.
+`tests/integration/subagent-auto-save.test.ts` once faked `listEvents: async () => durable` with full
+events and passed against a host verb that returns metadata. If a test proves a door works while the
+production arm returns a different shape, the test is the bug.
+
 ## Bug Reports
 
 Cache and context behaviour are the plugin's core promise, so a report must include:
@@ -234,3 +337,117 @@ transport registry). The first push against a real remote is therefore a
 If isomorphic-git ever chokes on a specific forge's smart-HTTP, the documented
 fallback is a CLI driver (the `GitDriver` seam in `src/gitops.ts` exists for
 exactly this swap) — the loop's logic is driver-agnostic by design.
+
+## Prompt recommendations (#71) — SPEC + verification rows
+
+Interface: site §28 (`concepts/prompt-recommendations`); host facts in `docs/contract.md`
+§ Composer Ghost Layer. Off by default — **the effective model string non-empty IS the
+enable**; there is deliberately no second boolean.
+
+Deterministic rows (each must be proven to fail on the mutation it guards):
+
+| Row | Pins |
+|---|---|
+| enable derivation | `effectiveModel = setting('prompt.model') ?? config.promptModel`; empty or unset ⇒ OFF, and a stored empty override beats a non-empty config (`off` verb) |
+| input assembly | chapter summaries first, then the live tail; total ≤ `promptContextChars`; host-injected spans defused BEFORE the cap; deterministic order (same input ⇒ same bytes) |
+| answer validation | trim → reject empty → reject > `promptMaxChars` → ONE retry with the cap restated → refuse with the measured length. Never truncate |
+| cache & watermark | one entry per session keyed by the last completed `turn/end` seq; fresh hit ⇒ zero llm calls; new turn ⇒ recompute on next ask; in-flight dedup shares one promise |
+| command arms | `model` show/set/clear texts, `off`, `suggest` refusals (off / no route / not computable / model failure) each name their remedy |
+| status line | `/chapters-status` prints ON with the model + source, or OFF — both states, linked store or not |
+| client pure logic | `shouldShowGhost` matrix: enabled ∧ !running ∧ draft==='' ∧ hasText ∧ !suppressed/boundary; accept ⇒ setDraft; typing ⇒ hidden; Esc ⇒ suppressed until the boundary moves |
+| client anti-dup | `src/client/index.ts` contains no `commands.execute` for the ghost either — the wire body lives in `src/client/prompt-ghost.ts` ONE time, mirroring the door-runner rule (tests/unit/client-doors.test.ts pattern) |
+| honesty | a suggestion never reaches a chapter file, the notice, the pool, or any model request: an archived session that used the feature contains zero recommendation bytes |
+
+Manual browser procedure (browser-plane claim stays **gated by #56** — the corpus must be
+re-anchored before replay can vouch for it):
+
+1. `/chapters-prompt model local/qwen3.8-flash` (or a cloud route) ⇒ expect "…enables the feature".
+2. Finish a turn, idle with an empty draft ⇒ the ghost line appears dimmed inside the
+   composer card, labeled with the model; the host placeholder is HIDDEN beneath it (draft
+   empty ⇒ host placeholder visible — our layer renders over it; if both are readable at
+   once, that is a styling bug).
+3. Type one character ⇒ ghost gone instantly; delete it ⇒ ghost back (while not accepted).
+4. Click into the editor, press Right-arrow ⇒ suggestion lands as real draft text, cursor
+   at its end; nothing sends. Enter sends as a normal human message — then verify in the
+   log that the message is plain human-authored.
+5. Esc on a fresh ghost ⇒ hidden for this turn; send any turn ⇒ boundary moves, a new offer
+   may come.
+6. `/chapters-prompt off` ⇒ ghost never reappears in this or later sessions, `suggest`
+   refuses; `/chapters-status` says OFF.
+7. Kill the model route (wrong provider) ⇒ ghost hidden, refusal only in command output, no banner.
+
+**Distilled, observed, AND replay-verified 2026-10-22** (`prompt-suggestion.spec.ts`, project `prompt`,
+port 41739): the scripted-upstream record run PASSED in a real browser on host 0.2.0-rc.2 — chip visible
+with the suggestion, hidden by one typed character, re-shown on an emptied draft, Escape dismissed
+boundary 1, the next boundary re-armed, ArrowRight accepted into the draft via the host's own
+`InputActions.setDraft`, Enter sent it, and the log held the human message with zero persona bytes.
+A true `E2E_MODEL=replay` run then passed with ALL SIX requests served from tape and zero misses
+(corpus gate lifted for that check ALONE and restored byte-identical — the committed gate still
+refuses the chain until #56 re-anchors the other eight; `tests/fixtures/model-tape/prompt/PROVENANCE.md`). The distill ALSO caught a rig bug worth remembering: `localModelUp` answered "no upstream" while a
+healthy stub ran on the `E2E_UPSTREAM` port — the guard probed :8080 for any LOCAL base, the same
+silent-skip family #54 fixed for remotes. A ROW had pinned that behavior ("loopback is answered on
+:8080, not by E2E_UPSTREAM") — and the row was measured WRONG in use, twice, by this very journey
+refusing to run against a live stub. Per the house rule (change obsolete behavior with its tests):
+the row now pins probe-the-actual-base for local upstreams, plus a dead-local-port NO arm, with the
+reason in its comment. The guard lying by REFUSING is the same disease as lying by nodding.
+
+## Release gate — field checks, because green tests shipped a broken product twice
+
+Every item below is the shape of a defect that reached `main` or was found in the field (SAIP,
+issues #58–#61, #77–#82) **while the suite was green**. They are not more unit tests: several of
+this week's bugs had rows passing correctly around them. The gate is that a human or an agent
+observes the affordance working on a real project, and that every new instrument is shown to be
+capable of failing.
+
+Run on a scratch clone of a real project (not this repo), at the pinned host and pinned window.
+
+1. **A continuation opens, not just a continuation created.** Fork (button or `chapters_continue`),
+   then require: the app's current session IS the child (read `dsh.sessions.current`, or the door's
+   own note — it now refuses to claim a switch it cannot verify), the child is in the sidebar, and
+   the state survives a reload. *Why: #77 — three evenings of "the client refuses to catalogue
+   plugin-created children" were a door calling `sessions.open`, a verb that does not exist
+   (`docs/contract.md` § Client Sessions Service). Green throughout, because no test read the id.*
+2. **The realm is mounted, not declared.** One session header must read `agentPreset: "chapters"`,
+   and the sink must show at least one `compactIfNeeded entered` line. *Why: the preset pin sat on
+   a retired row id (`agent-presets` → `agent-preset-registry`) and every acceptance boot ran the
+   standard realm for two days — zero `compaction/*` events in 15 logs, while leg verdicts looked
+   like product failures (#56, #78). "Declared" was asserted; "invoked" never was.*
+3. **Context relief actually happens, with numbers.** Force one oversized read at the pinned
+   window; require `compaction/*` events (or an arrival stub pair) in the durable log, then that the
+   NEXT turn answers a plain question. *Why: #78's decline is now reported with
+   `surface=/trigger=/window=/ratio=`, and a session that survives but answers a stale transcript
+   token is exactly what `oversized-turn.spec` caught — after #81, the wrong answer had been the rig
+   sending the instruction twice.*
+4. **A command reaches the human.** Run `/chapters-status` and check BOTH the durable
+   `command/done` AND the screen; today the screen half fails and that is #80, not a flake. A
+   delivered-but-invisible result is a feature the operator cannot use (#61a, #67).
+5. **A disabled feature is quiet in the durable log.** On a boot without `promptModel`,
+   `countGhostCommandRuns(log)` must be ≤ 1 (one capability probe per mount). *Why: #79 measured 4–26
+   `chapters-prompt` command pairs per session — a "once per mount" effect depending on `[props]`,
+   writing into the transcript this plugin archives, with the OFF test passing because it only
+   looked at the chip.*
+6. **The rig's pins reach the realm.** The boot's own `cordis.patch.yml` must carry this project's
+   `thresholdRatio` and arrival floor on the `chapters-engine` row. *Why: `Pins` were collected and
+   applied to nothing for a whole release cycle (leg headers claimed 0.5 while realm defaults
+   ran).*
+7. **The corpus is one behavior.** `CORPUS_HOST`'s `host` equals the pin, and every project's
+   `recordedAgainst` names the same code generation. If any leg was recorded before a rig-behavior
+   change (send timing, window enforcement), re-record it: a mixed corpus passes for the wrong
+   reason (#56, #81, #82).
+8. **A boot may read only tracked state.** List every file the e2e home is seeded from and prove each is
+   in `git ls-files` — a gitignored path in that chain makes the corpus a recording of one laptop.
+   *Why: #89, three layers deep. First the matcher folded no workspace root (CI's `/home/runner/…` vs
+   the recorded `/home/adrian/…`); then `spawn('dsh')` took PATH and got a **linked dev build** whose
+   version string matched the pin; and even with the pinned tarball booted by absolute path, CI sent a
+   2-message first request against a 6-message tape — because `boot.ts` copied
+   `.dshdev-local/settings.yaml` (gitignored) with the provider route and `contextWindow: 32000`. Each
+   layer looked like the end of the story; the tape diff (`E2E_TAPE_DIFF` / `E2E_MISS_DUMP`) is what
+   said otherwise every time. Reproduce across machines before believing a green local chain.*
+
+9. **Instrumentation must be shown to be capable of failing.** For every gate this week added, name
+   the mutation that reddens it — the hygiene guard, the roster predicate, the report helper, the
+   window rows and the bounded-scroll row all have one. *Why: three bugs this week lived in code
+   written to observe the fourth — `\bpending\b` missing an escaped newline, `ids.size > 0`
+   disabling every #77 candidate, a helper resolving logs against an import-time home so a gate
+   could never pass, and an unbounded `scrollIntoViewIfNeeded` that hung a leg for 17 minutes. Each
+   looked like a product failure. **An unexercised assertion is a rumor of an assertion.**