@treeseed/dsh-chapters 0.1.16 → 0.1.18

package/cordis.patch.yml

@@ -10,17 +10,41 @@
 # Two planes, two surfaces:
 #   HOST PLANE  — the `config:` block below (defaults shown commented; set any
 #                 under your profile's plugin entry).
-#   REALM PLANE — the compaction ENGINE row in the preset
-#                 (presets/chapters/agent.cordis.yml); shared names behave per
+#   REALM PLANE — the compaction ENGINE row inside the preset's composition (the
+#                 `preset-chapters` row at the foot of this file); shared names behave per
 #                 plane. Design record: docs/knowledge-repo.md §12.
 #
+# PRESET DELIVERY — the preset is a DECLARATION ROW, exactly like the host's own presets.
+#   `preset-chapters` (the id is the host convention `preset-<id>`) is inserted by this
+#   file, its `config` IS the preset definition (`id/name/description/order/plugins`), and
+#   because it is an ordinary Loader entry you can see it in the plugin list and the config
+#   editor, override it from your profile patch, or `disabled: true` it.
+#     Its row module is ours — '@treeseed/dsh-chapters/preset' (src/preset.ts) — not the
+#   host's '@deepseek-ai/dsh-agent-preset'. It mirrors that plugin line for line (injects
+#   `agentPresets`, preserves child `!!js` expressions, yields the registry disposer to
+#   Cordis) and adds one thing: rows this host cannot import are dropped at boot and NAMED,
+#   because a single unresolvable child row makes the WHOLE preset `broken` — which is the
+#   same user-visible failure as no preset at all (measured: `DECLARED BUT BROKEN —
+#   tool-schedule … never started` on a host where that package was never published). The
+#   host package cannot be named directly because a row that fails to import aborts the
+#   plugin tree of any host predating declaration rows; ours resolves everywhere our
+#   package runs. Support floor: 0.2.0.
+#     After activation the plugin then ASKS THE ROSTER, and the mounted rows: file presence
+#   is not preset existence, and "declared" is not "usable". The `dsh-chapters:` lines at
+#   startup say which of the four states you are in.
+#
 # config:
-#   # ---- identity & install --------------------------------------------
-#   installChaptersPreset: true    # copy presets/chapters into the home's
-#                                  # .agent-presets at boot; a user-edited
-#                                  # preset is never clobbered (write-once)
-#   fallbackPreset: 'chapters'     # preset mounted for children when the
-#                                  # caller's own preset cannot be resolved
+#   # ---- identity -------------------------------------------------------
+#   installChaptersPreset: true    # INERT since 0.1.18 — the preset is the `preset-chapters`
+#                                  # row above, so `disabled: true` on THAT row is the switch.
+#                                  # Kept so an existing profile patch still parses.
+#   compactionThresholdRatio: 0.9  # INERT since 0.1.18 for the same reason: it is
+#                                  # `thresholdRatio` on the preset's chapters-engine row now.
+#   #   fallbackPreset: 'chapters'     # preset mounted for children when the
+#                                  # caller's own preset cannot be resolved — and
+#                                  # the id the roster check looks for. This id is
+#                                  # DURABLE STATE: every child's log records it,
+#                                  # so renaming it orphans those sessions.
 #   harnessId: '<hostname>'        # per-machine identity: git commit author,
 #                                  # token scoping, edits/<harness>/ curation
 #                                  # partition, rule-approval authorship
@@ -98,3 +122,182 @@
 - insert:
     - id: '@treeseed/dsh-chapters'
       name: '@treeseed/dsh-chapters'
+
+# ── the `chapters` agent preset — a DECLARATION ROW, exactly as @deepseek-ai/dsh-web-app
+#    ships its own presets/standard.patch.yml. Row id `preset-chapters` follows the host's
+#    `preset-<id>` convention; `config.id: chapters` is DURABLE STATE (every continuation
+#    child records it as `agent-preset/selected`, so renaming it orphans those sessions).
+#
+#    The row's `name` is OUR plugin (`@treeseed/dsh-chapters/preset`), which mirrors
+#    @deepseek-ai/dsh-agent-preset line for line — `inject: ['agentPresets']`,
+#    `static [EntryGroup.key] = true` so child `!!js` expressions survive until the child
+#    activates, `[Service.init]` yields the registry disposer so Cordis owns its lifetime —
+#    and drops rows THIS host cannot import before registering. Why not the host package
+#    directly: a row naming @deepseek-ai/dsh-agent-preset is unresolvable on a pre-0.1.7
+#    host and an unresolvable row aborts that host's whole plugin tree, while one stale
+#    child row (e.g. @deepseek-ai/dsh-tool-schedule, unpublished at 0.2.0-rc.2) makes the
+#    ENTIRE preset `broken` — measured both ways. Same row, same visibility in
+#    `dsh --dump-default-config`/the config editor, no boot that it can brick.
+#
+#    Four deltas from the host's own standard list, each ours deliberately:
+#      1. compaction-basic -> chapters-engine (the zero-inference summarize())
+#      2. tool-result-pruner.thresholdChars 8192 -> 1000000 (dormant by choice: chapters
+#         defer oversized results at ARCHIVE time; an in-surface prune is a prefix cliff
+#         on local hardware — and that plugin REJECTS unknown config keys, so the three
+#         keys below are the whole surface)
+#      3. the PLOT: persona suffix, with NO {{cwd}} (hosts from 0.2.1-alpha.2 register only
+#         provider/model and an unregistered variable throws at prompt assembly, killing
+#         every turn of every chapters session)
+#      4. tool-ralph ENABLED (the host standard list mounts it disabled)
+#    `noUnusedLocals`-equivalent discipline applies: keys the host dropped between versions
+#    are not carried here (toolFilter was one — alpha.4 throws on it).
+- insert:
+    - id: preset-chapters
+      name: '@treeseed/dsh-chapters/preset'
+      config:
+        id: chapters
+        name: Chapters
+        description: Full coding agent; context relief via zero-inference chapter compaction.
+        order: 0
+        plugins:
+          - id: persona
+            name: '@deepseek-ai/dsh-persona'
+            config:
+              prefix: You are a coding agent powered by the {{model}} model.
+              suffix: "When a task spans multiple turns, end each reply with one line beginning 'PLOT:' (max 60 words — objective, current hypothesis, immediate next step). A checkpoint carries this plot forward; if it looks stale, revise it on your next plot line."
+          - id: agent-instructions
+            name: '@deepseek-ai/dsh-agent-instructions'
+            config:
+              maxBytes: 65536
+          - id: time-context
+            name: '@deepseek-ai/dsh-time-context'
+          - id: tool-bash
+            name: '@deepseek-ai/dsh-tool-bash'
+            disabled: !!js process.platform === 'win32'
+          - id: tool-pwsh
+            name: '@deepseek-ai/dsh-tool-pwsh'
+            disabled: !!js process.platform !== 'win32'
+          - id: tool-fs
+            name: '@deepseek-ai/dsh-tool-fs'
+          - id: tool-fs-search
+            name: '@deepseek-ai/dsh-tool-fs-search'
+            config:
+              sampleOverCapGlobResults: false
+          - id: tool-jobs
+            name: '@deepseek-ai/dsh-tool-jobs'
+          - id: tool-schedule
+            name: '@deepseek-ai/dsh-tool-schedule'
+          - id: skill-filesystem
+            name: '@deepseek-ai/dsh-skill-filesystem'
+          - id: tool-skill
+            name: '@deepseek-ai/dsh-tool-skill'
+          - id: command-goal
+            name: '@deepseek-ai/dsh-command-goal'
+          - id: tool-goal
+            name: '@deepseek-ai/dsh-tool-goal'
+          - id: planning
+            name: cordis:group
+            group: true
+            isolate:
+              planMode: true
+            config:
+              - id: plan-mode
+                name: '@deepseek-ai/dsh-plan-mode'
+                config:
+                  section: |
+                    You are in plan mode. Stay in plan mode until exit_plan_mode succeeds or the user switches the session mode. Imperative language to implement changes means plan the implementation, not execute it. A user's conversational agreement — including an answer confirming something you asked — approves nothing and does not end plan mode; fold the confirmed decision into the plan and submit it through exit_plan_mode.
+
+                    Explore first. Use non-mutating reads, searches, static analysis, and checks to ground the plan in the actual repository. Do not edit or write files, change configuration, run formatters or code generation that rewrites tracked files, commit, or otherwise carry out the plan. Prefer existing functions and patterns over new machinery.
+
+                    The tool catalog stays the same across modes for request-cache stability. These plan-mode rules override any later tool description or guidance that suggests using mutation tools; those tools remain listed to keep the tool catalog unchanged. Do not use todo_write to track this planning phase: it tracks implementation after an approved plan, while the plan itself belongs in exit_plan_mode.
+
+                    Resolve discoverable facts by inspection. Use ask_user_question only for user-owned choices or material ambiguity that inspection cannot answer. Do not ask the user where code lives or how current behavior works when you can find out.
+
+                    Make the plan decision-complete: state the goal and success criteria; group implementation changes by subsystem; identify public API, schema, and data-flow changes; cover edge cases, failure modes, tests, acceptance criteria, and explicit assumptions. Keep it concise enough to review but detailed enough that another engineer can implement it without making design decisions.
+
+                    When ready, call exit_plan_mode with the complete plan markdown, starting with a # title. Make exit_plan_mode the only and final tool call in that assistant response: it presents the plan for approval, and implementation begins only in a later step after approval. Do not paste the final plan as a plain reply or ask "should I proceed?" through prose or ask_user_question. If review rejects it, incorporate the feedback and present again. If the review channel is unavailable or aborted, stay in plan mode and ask the user to switch modes manually; do not proceed with implementation.
+          - id: compaction
+            name: cordis:group
+            group: true
+            isolate:
+              compaction: true
+              toolResultPruner: true
+            config:
+              - id: chapters-engine
+                name: '@treeseed/dsh-chapters/engine'
+                config:
+                  thresholdRatio: 0.9
+              - id: command-compact
+                name: '@deepseek-ai/dsh-command-compact'
+              - id: tool-result-pruner
+                name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
+                config:
+                  thresholdChars: 1000000
+                  headChars: 4096
+                  tailChars: 1024
+          - id: delegation
+            name: cordis:group
+            group: true
+            isolate:
+              workflowEngine: true
+            config:
+              - id: tool-subagent-control
+                name: '@deepseek-ai/dsh-tool-subagent-control'
+              - id: tool-subagent-list-agents
+                name: '@deepseek-ai/dsh-tool-subagent-control/list-agents'
+              - id: tool-subagent
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: spawn
+                  toolName: subagent
+                  modelSelectionSettings: true
+                  backgroundMode: continuable
+              - id: tool-subagent-fork
+                name: '@deepseek-ai/dsh-tool-subagent'
+                config:
+                  provider: fork
+                  toolName: subagent_fork
+                  backgroundMode: continuable
+              - id: tool-subagent-codex
+                name: '@deepseek-ai/dsh-tool-subagent'
+                disabled: true
+                config:
+                  provider: codex
+                  toolName: subagent_codex
+                  backgroundMode: one-shot
+                  maxDepth: provider-managed
+              - id: tool-subagent-claude-code
+                name: '@deepseek-ai/dsh-tool-subagent'
+                disabled: true
+                config:
+                  provider: claude-code
+                  toolName: subagent_claude_code
+                  backgroundMode: one-shot
+                  maxDepth: provider-managed
+              - id: workflow-ptc
+                name: '@deepseek-ai/dsh-workflow-ptc'
+                config:
+                  provider: spawn
+              - id: tool-workflow
+                name: '@deepseek-ai/dsh-tool-workflow'
+              - id: tool-ralph
+                name: '@deepseek-ai/dsh-tool-ralph'
+                config:
+                  subagentProvider: spawn
+                  maxRounds: 64
+          - id: tool-ask-user
+            name: '@deepseek-ai/dsh-tool-ask-user'
+          - id: tool-todo
+            name: '@deepseek-ai/dsh-tool-todo'
+            config:
+              allowParallelInProgress: true
+          - id: tool-web
+            name: '@deepseek-ai/dsh-tool-web'
+            config:
+              fetch: true
+              searchTimeoutMs: 60000
+          - id: present
+            name: '@deepseek-ai/dsh-tool-present'
+          - id: tool-plugin-manager
+            name: '@deepseek-ai/dsh-plugin-manager/tools'
+            disabled: true

package/docs/backlog.md

@@ -95,3 +95,82 @@ about.
   machine-only when you expected the pool, that note is the first thing to read.
 - **`/chapters-continue` vs `/chapters-fork`** is the intent line: continue carries the operative plan
   and may seed plan mode; fork carries nothing.
+
+## Preset delivery on 0.1.7+/0.2.x — landed, and what it exposed (2026-10-16)
+
+**Landed:** the `chapters` preset now EXISTS on a declaration-row host, by `agentPresets.register()` at
+activation (`src/preset.ts`), with rows the host cannot import dropped and named, a held disposer, and a
+deferred ROSTER check (`present` / `DECLARED BUT BROKEN` / `absent` / `unknown`) as the only health signal.
+**Support floor is 0.2.0** (user decision 2026-10-16): the legacy `.agent-presets` copy, the
+`presets/chapters/` tree, `installChaptersPreset`'s copy arm and `preset-install.test.ts` are DELETED; a
+pre-0.2.0 host gets `delivery: REFUSED` with its tools intact. The engine row's `thresholdRatio` became
+the host-plane config `compactionThresholdRatio` (no hardcoded tunables). Verified on real boots:
+0.2.0-rc.2 → `register: pruned, roster: present, inventoryRows: 28, unusableRows: []`;
+0.2.1-alpha.4 → `register: registered, roster: present, inventoryRows: 29, unusableRows: []`
+(after dropping `toolFilter`, which alpha.4 THROWS on — see the config-key row of the drift test). `tests/unit/preset-declaration.test.ts`
+(13 rows, `src/preset.ts` at 100%) is the drift gate, and it now RUNS on this box instead of skipping.
+
+**Why the row is not a shipped patch layer** — measured, because it looks like the obvious fix and it is a
+boot-breaking one: `dsh.bundle.patch` as an ARRAY throws `ERR_INVALID_ARG_TYPE` at
+`dsh-app-boot/lib/index.js:853` on every host before 0.1.7-alpha.1, and a row naming
+`@deepseek-ai/dsh-agent-preset` aborts that host's plugin tree (`Cannot find package`). `disabled: !!js`
+cannot gate it either: the Loader evaluates `disabled` before services mount, so the row is disabled on the
+NEW host too (measured). Full record: `docs/contract.md` § Presets are declaration rows.
+
+**Open, in order:**
+
+0. **Re-anchor the e2e host, then re-distill the tapes.** `tests/e2e/boot.ts` now refuses by name
+   while `dev/dsh-host-lock` pins a pre-0.2.0 host, and the refusal lifts itself when the lock moves —
+   that is the upgrade path, not a TODO. `ci.yml`'s `host-capability` job reads that same lock and
+   SKIPS the acceptance job with a step-summary reason plus a `::warning::` while the pinned host
+   predates declaration rows: visibly skipped, never red-by-accident, never green-by-omission.
+   Publishing is unaffected — the release gate is the deterministic suite. The per-boot row pins (`thresholdRatio`, `enrichmentEnabled`,
+   `auto`, `elicitedPlot`, `toolResultArtifactTokens`) and the `[e2e] boot pins:` line were deleted with
+   the YAML they patched; they come back expressed as CONFIG on the registered row (`compactionThresholdRatio`
+   exists now; the rest need the same treatment). Until then the browser acceptance chain does not run, and
+   `docs/verify.md`'s P23 is retired rather than passing.
+1. **The roster verdict is a boot log line, and a user has no terminal.** 0.1.18 made the preset a
+   visible Loader row (`preset-chapters`) and put the mounted-row count in that line, so the
+   "is it actually usable" fact is one grep away — but it is still a grep. Candidate: surface it in
+   `/chapters-status`. Nothing else in the plugin reports health to a human today.
+2. **`installChaptersPreset` and `compactionThresholdRatio` are accepted-and-inert** since 0.1.18 (the
+   preset is a row; the engine threshold is row config). They must be DELETED in the next minor — a key
+   that silently does nothing is its own drift — and the removal needs the same care: check no shipped
+   profile patch sets them, then drop both from `Config` and from `cordis.patch.yml`'s header.
+2. **`compositionInventory()` is used by the dev witness only.** Making the boot check itself compare
+   mounted rows would catch a row that resolves but never activates — the `broken` flag does not always
+   cover that, and the witness proves the shape of the answer already.
+3. **A reset registry can overwrite a chapter — no guard exists today.** `writeArchive`
+   (`src/archive.ts:106`) reserves numbers from the registry and writes them; nothing checks whether that
+   path already exists on disk. So the exact incident shape — registry gone (host reinstall) while chapter
+   files remain, or restored by rehydration — lets a NEW archive reuse number 001 and clobber a surviving
+   file, which breaks the append-only rule from the inside. Two rows are missing: at boot, report files the
+   registry does not know (`<store>/<root>/chapters/*.md` vs registry rows, counted); and refuse a
+   reservation whose target path exists, with the numbers.
+4. **Rehydration restores bytes, not rows.** `rehydrateStoreFromMirror` (`src/sync.ts:476`) fills absent
+   chapter and artifact files only. Search works off the files' own frontmatter, but numbering, ancestry and
+   collections are registry state, so a rehydrated store can be searched and cannot be continued cleanly.
+   Decide: rebuild rows from frontmatter (honest — the bytes are the ground truth), or refuse continuation
+   over a partially restored store with numbers. Do not let it look like a fresh chain.
+
+## Host bug we cannot fix: the workspace directory-picker modal (2026-10-16)
+
+Reported by the user as "the directory selection modal crashes before I can select a workspace", and it
+survived a host upgrade. Root-caused with real boots (`var/picker-probe/FINDINGS.md`, kept out of the
+repo's claims — it is host code): the picker's CLIENT bundle and the shell's client module table must come
+from the same host generation. The 0.1.x picker asks for `IconFolderOpen16`/`IconFolderClose16`;
+0.2.0-rc.2's shell exports only the `…Regular` spellings, with no compat alias in either direction. The
+slot boundary catches it, so the symptom is a rendered-then-dead dialog:
+`Error: Minified React error #130 … got: undefined`, logged as
+`slot entry crashed in 'sidebar.workspaces.directoryFlow'`
+(`@deepseek-ai/dsh-client-ui-renderer/lib/client.js:618`). A stale profile-local copy of
+`@deepseek-ai/dsh-client-ui-directory-picker-*` under `$DSH_HOME/profiles/<p>/node_modules` shadows the
+upgraded global install and reproduces "the new host did not fix it" exactly.
+
+Nothing in this plugin contributes to that slot (its client half registers
+`conversation.chat.assistant-actions` only), so the repo can ship no fix — only the recipe, which the
+site documents: purge the stale picker copies, and if the auto-resolved backend is not the one you want,
+pin the pair deliberately in the profile patch (`disabled: true` on `directory-picker`, insert
+`@deepseek-ai/dsh-host-directory-picker-browse` + `@deepseek-ai/dsh-client-ui-directory-picker-browse`).
+Upstream ask: compat aliases for the renamed icon exports, or a boot-time shell↔plugin version handshake
+that rejects a mismatched bundle instead of crashing at render.

package/docs/contract.md

@@ -244,12 +244,13 @@ The subclass seam, with everything measured by rounds 12-17 (sources: the instal
   `resolveConfig` **rejects unknown keys at runtime** (`BasicCompactionConfig:
   unknown key "artifactStoreRoot"`, r18) — peel engine-specific keys in the
   subclass constructor before `super(ctx, baseConfig)`.
-- Preset delivery: profile `!!js` evaluates `new Function("ctx", …) with (ctx)` —
-  `dshHomePath`/`process` reachable, **`require` is not** (r20 boot-killer) — so a
-  patch cannot name a package-relative `agentPresets` roots path. The plugin
-  copies its `presets/chapters/` into `$DSH_HOME/.agent-presets/` at boot,
-  write-if-missing (`installChaptersPreset`, schemastery default import —
-  version line `@deepseek-ai/schemastery@3.x`, NOT host rc.x).
+- Preset delivery: the plugin registers the `chapters` declaration row at activation
+  (`src/preset.ts` -> `ctx.get('agentPresets').register(...)`). The old copy of
+  `presets/chapters/` into `$DSH_HOME/.agent-presets/` is GONE with the 0.2.0 support
+  floor; the section "Presets are declaration rows" records why the row is not a shipped
+  patch layer (`!!js` evaluates `disabled` before services mount, and an array
+  `dsh.bundle.patch` throws on a pre-0.1.7 host). Related: profile `!!js` reaches
+  `dshHomePath`/`process` but NOT `require` (r20 boot-killer).
 - `ctx.logger` output is invisible to headless `dsh web` (r19); engine failures
   mirror to `$DSH_CHAPTERS_ENGINE_ERRORS` when set. Engine finalization runs on
   BOTH the success and rejection paths of `compactIfNeeded`/`compactNow` — the
@@ -354,6 +355,92 @@ 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.
 
+### 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` +
+`agent.cordis.yml`. The host's own migration note is blunt: *"Nothing reads that directory any more."*
+(`@deepseek-ai/dsh-agent-preset/skills/editing-cordis-compositions/SKILL.md`). A preset is now an
+`@deepseek-ai/dsh-agent-preset` **declaration row** (`config: {id, name?, description?, order, plugins}`;
+`dsh-agent-preset/lib/index.js:13-20`) carried by a patch layer, and `AgentPresetRegistry.register()` is
+fed only by such rows (`dsh-agent-preset-registry/lib/index.js:470`, installed 0.2.0-rc.2). Nothing
+crashes when a plugin misses this: the bundle boots, its tools register, Settings says "enabled and
+running", the preset is simply absent — and a session's preset id is **durable state** (`resumeObserved()`
+→ `presets.resolve(id)`, `dsh-api-session-controller/lib/index.js:404`, `:364`; `resolve()` throws
+`agent-preset/not-found`, `dsh-agent-preset-registry/lib/index.js:596`), so every chapters session refuses
+to OPEN while its log sits there intact.
+
+**This bundle DOES ship the row — in its one existing patch layer, with our own row module.**
+`cordis.patch.yml` ends with `- insert: [{id: preset-chapters, name: '@treeseed/dsh-chapters/preset',
+config: <the preset definition>}]`, so the preset is an ordinary Loader entry: visible in the plugin
+list and `dsh --dump-default-config`, overridable or disable-able from a profile patch, positioned by
+`config.order`. The row module (`src/preset.ts`) mirrors `@deepseek-ai/dsh-agent-preset`'s plugin line
+for line and adds the pruning described below. Why not the host package directly, measured on the
+0.1.5-rc.1 closure and on 0.2.0-rc.2:
+
+- `dsh.bundle.patch` as an **array** (what a second layer requires) dies at profile load on a pre-0.1.7
+  host: `TypeError [ERR_INVALID_ARG_TYPE]: The "path" argument must be of type string. Received an
+  instance of Array` (`dsh-app-boot/lib/index.js:853`, `join(packageDir, declared)`). Array support and
+  declaration rows arrive in the SAME release, 0.1.7-alpha.1 — so one layer, still a string, is both
+  enough and the only boot-safe shape.
+- a row naming `@deepseek-ai/dsh-agent-preset` in ANY layer a legacy host reads aborts its plugin tree:
+  `plugin tree failed to load: … failed to import loader entry … Cannot find package` (the package is
+  first published at 0.1.7-alpha.1). A row naming our own module resolves wherever our package runs.
+- **`disabled: !!js` cannot capability-gate a root row**: the Loader evaluates `disabled` before services
+  are mounted (`cordis-plugin-loader/lib/index.js:348` → `with (ctx) { eval(expr) }`), so
+  `get('agentPresets')?.register === undefined` is true on the MODERN host too and the row never
+  registers — measured (`preset-v2 … failed to import`, roster without it, while the same row with
+  `disabled: !!js false` registered normally). Bare `get(...)` also throws there; only `ctx` is bound.
+- and the row must be *ours* anyway for the reason below: it is the one place that can drop a child the
+  host cannot load before the mount is attempted.
+
+Three consequences of reading the registry rather than the filesystem:
+
+- **A row that does not resolve is dropped, never mounted.** `mountPreset` throws if ANY enabled row failed
+  (`dsh-agent-preset-registry/lib/index.js:272`), the registry stores it as `record.broken` (`:541`), and
+  `retain()` then refuses with `agent-preset/invalid` (`:651`) — so one stale row makes the whole preset
+  unusable, which is the same user-visible failure as a missing preset. Measured on 0.2.0-rc.2 with a row
+  for `@deepseek-ai/dsh-tool-schedule` (published only from 0.2.1-alpha.1):
+  `preset "chapters" is DECLARED BUT BROKEN — tool-schedule …: never started`. `pruneResolvableRows`
+  (`src/preset.ts`) drops such rows and NAMES them in the mount line; `resolvableFromThisPackage` is the
+  probe, asked with the row's full specifier so a lost subpath export is caught too.
+- **A held disposer, not an effect.** `register()` returns an unregister disposer, and wiring it through
+  `ctx.effect` un-registers the preset the moment our activation finishes — measured: `register()`
+  succeeded while the roster came back WITHOUT `chapters`. The same apply-fiber trap bit the storage
+  domain in r35. The disposer is held in a module array instead.
+- **The roster is the health check, and it must be asked after activation.** The registry re-audits a mount
+  by awaiting the settled loader tree (`:562`), and its doc says callers "must not run inside a Host row's
+  own activation, which the settlement would wait on". So `reportPresetRoster()` runs deferred, and
+  `compositionInventory()` rows say which mounted rows are actually `active` — `broken` alone hides a row
+  that resolved but never started.
+
+Rows are renamed and dropped between host versions, so re-anchor `src/preset.ts` against the installed
+host's own `@deepseek-ai/dsh-web-app/presets/standard.patch.yml` after an upgrade. Measured drift across
+the five published versions (rc.1, rc.2, alpha.1, alpha.2, alpha.4): alpha.1 ADDS `dsh-time-context` +
+`dsh-tool-schedule` + `toolFilter.deny[schedule_*]`; alpha.2 DROPS the persona `suffix` (with its
+`{{cwd}}`), `backgroundMode`, and the codex/claude-code/ralph rows; alpha.4 rewrites the plan-mode
+sentence, drops `toolFilter`, adds `dsh-plugin-market`. rc.1 and rc.2 are byte-identical.
+`tests/unit/preset-declaration.test.ts` is what turns the next rename into a red row instead of a broken
+user session — and it pins that `dsh.bundle.patch` is still a string.
+
+- **Prompt variables are a closed set, and violating them throws per turn, not at boot.** `dsh-agent-loop`
+  registers `provider`/`model`/`cwd` through 0.2.0-rc.2 (`lib/index.js:1564-1566`) and only `provider` and
+  `model` from 0.2.1-alpha.2 (`:1591-1592`); `interpolate()` rejects any other reference with `prompt
+  variable "{{x}}" has no value for this assembly` (`dsh-system-prompt/lib/index.js:171`). There is no
+  `{{cwd}}` worth writing: `dsh-working-directory` (host plane) already prints `Current working directory:
+  "…"` into the runtime context. This is what broke every new chapters session immediately AFTER the
+  delivery fix above — the preset composed fine, the legacy `persona.suffix` interpolated `{{cwd}}`, and
+  assembly threw on every turn. Pinned by the `{{variable}}` row of the test.
+- **Some host plugins reject unknown config keys**, so a preset row's config is not free-form:
+  `dsh-compaction-tool-result-pruner`, `dsh-compaction-basic` and `dsh-plan-mode` throw on any key they do
+  not know (`PlanModeConfig has unknown key(s) …`); `dsh-tool-subagent` and `dsh-tool-ralph` are plain zod
+  objects that strip them. Keep exactly `{thresholdChars, headChars, tailChars}` on the pruner and exactly
+  `{section}` on plan mode.
+- **Persona wording is load-bearing for the engine.** `src/engine-core.ts`'s `PLOT_TEMPLATE_ECHO` suppresses
+  a "plot" that is really our own instruction quoted back (the 2026-09-25 audit: eight checkpoints of a
+  real run inherited boilerplate, and because the result was non-null the bounded elicited fallback never
+  ran). It matches phrases inside the suffix, so reword the suffix and the guard in the same change — the
+  gate asserts that coupling by behaviour, not by copying the regex.
+
 ## Trigger Constraints
 
 Two different actions, two different timings — Phase 0b measured the seam so this split is now factual,

package/docs/development.md

@@ -355,7 +355,7 @@ happened in these notes before it was caught.
 | `src/notice.ts` + `test/notice.test.ts` — TOC-notice builder, kernel-rejection reproduction, vocabulary pins + drift guard (Phase 0b check 5) | **done**, 10 tests |
 | `src/registry.ts` + `src/store.ts` — pure numbering/ancestry/plan state; zod domain spec, storage-domain + node-fs adapters | **done**, 13 + 7 tests; durability witness passed |
 | `src/engine-core.ts` + `src/engine.ts` — ChaptersCompactionEngine | **done & boot-proven** (r18/r19: realm subpath row mounts; real cascade finalizes; catch-path fix — FINDINGS § Phase 1) |
-| `presets/chapters/` + copy-on-boot install | **done & boot-proven** (r21; `!!js` has no `require`, so copying is the delivery mechanism — r20) |
+| preset delivery | **0.1.18: the preset IS a declaration row** — `preset-chapters` in `cordis.patch.yml`, mounted by `@treeseed/dsh-chapters/preset` (`src/preset.ts`), which registers what the host can load and drops what it cannot. The `presets/chapters/` + copy-on-boot mechanism is deleted with the 0.2.0 floor. Verify.md P24 (rows + three-host boots) |
 | `npm test` (unit + integration) | **188 passing, <2 s** — unit imports no harness services; integration runs the sync loop against a fake git driver AND a real git smart-HTTP server (git-http-backend on loopback; the git binary is test-only scaffolding, the product stays pure-JS) |
 | 20-check verify.md pass | **r26/26b**: 18 mechanical on `.dshdev2` (refusals with numbers, tamper marks, idempotent retry, cross-boot registry + resume); human rows per verify.md evidence map |
 | dsh-session-fork coexistence | **moot at this version** (r26a pair-boot): the example fails to boot the installed host ALONE (unguarded `webServer` read in the installed dsh-client-connection) — assumed-neutral until a version-matched pair-boot |
@@ -465,3 +465,66 @@ commands were *verified*.
 
 `docs/contract.md`'s file:line citations are from the `examples/` snapshot (rc.1-era), not the rc.2 fork —
 re-anchor them against whichever version a test actually boots.
+
+### Running the TS tests on this box (node 22, no native type stripping)
+
+Measured 2026-10-16: `npm test` (`node --test tests/unit/*.test.ts`) needs node ≥ 23 for type
+stripping, and this machine's `/usr/bin/node` is **v22.22.1 compiled WITHOUT TypeScript support**
+(`ERR_NO_TYPESCRIPT`, not merely a missing flag). The package's `engines` floor is node 24, and CI
+installs it; locally, run the same files through `tsx`:
+
+```bash
+npm install --no-save --no-audit --no-fund tsx unrun     # both, in ONE command
+node --import tsx --test tests/unit/*.test.ts tests/integration/*.test.ts
+npx c8 --check-coverage --statements 85 --branches 85 --functions 85 --lines 85 \
+  node --import tsx --test tests/unit/*.test.ts tests/integration/*.test.ts
+```
+
+Two traps measured while finding that:
+
+- **`npm install --no-save A` then `--no-save B` removes A.** npm prunes what is not in the manifest,
+  so unsaved helpers must be installed in a single command (`unrun` disappeared the moment `tsx` was
+  added, and `npm run build` — which bundles the client through `tsdown` — failed with
+  `Cannot find module "unrun"`).
+- `tsconfig.test.json` (committed) transpiles `src` + `tests` to `var/tsbuild` with `--noCheck` for
+  the rare case you want emitted JS instead of a loader. It is NOT how the suite is meant to run;
+  tests import `.ts` sources directly and are not typechecked by design (`npm run typecheck` covers
+  `src/` only).
+
+Never fix a missing test runner by editing the tests. The suite is the contract; the runner is local.
+
+### Verifying against a host version that is not the installed one
+
+A preset/delivery change must be proven on EVERY host release the package claims to serve, and the
+installed host is one data point. Recipe measured 2026-10-16 (this is how 0.1.17 was verified on
+0.2.0-rc.2, 0.2.1-alpha.4 and the pinned 0.1.5-rc.1 in one sitting):
+
+```bash
+# 1. a second host, installed as its own tree — never over the running one
+mkdir -p var/host-versions/a4 && cd var/host-versions/a4
+echo '{"name":"a4-host","private":true,"dependencies":{"@deepseek-ai/dsh":"0.2.1-alpha.4"}}' > package.json
+npm install --no-audit --no-fund           # ~1 min, 616 packages
+# 2. a THROWAWAY home for it (profiles/web/package.json listing the bundles + this plugin),
+#    then boot THAT bin with DSH_HOME pointed at the new home:
+DSH_HOME=$PWD/var/a4-home DSH_CHAPTERS_WITNESS=$PWD/var/a4-home/w.json \
+  node var/host-versions/a4/node_modules/@deepseek-ai/dsh/lib/bin.js web --port 0 --no-open
+```
+
+The witness JSON is the answer — `presetRegister`, `presetDroppedRows`, `presetRoster` and
+`presetInventoryRows`/`presetUnusableRows` say what a log line only hints at, and `presetUnusableRows: []`
+is the assertion that the composition actually ACTIVATES rather than merely being declared.
+
+Three traps, all paid for:
+
+- **Never symlink a host tree into an npm-managed profile's `node_modules`.** `npm install` treats what it
+  does not recognize as extraneous and **deletes it through the link** — it ate a 500-package host closure
+  this way ("the closure is gone, `ls` returns nothing"). Copy instead (`cp -r`), or point the boot's own
+  installation anchor at the other tree and install ONLY the plugin into the profile.
+- **`npm pack` + install-from-tarball, not `file:`-linked sources.** The artifact users get is the packed
+  `files` list; a linked working tree hides a missing `files` entry (e.g. an asset the preset needs).
+- Boot with `timeout 45 …` and read the exit code: **124 means it stayed up** (healthy), `1` means the
+  plugin tree refused to load. A crashed boot and a slow boot both print to the same log; the code is the
+  difference between "no preset" and "no harness".
+
+Prune after: `var/host-versions/`, the throwaway homes and `var/coverage` are all regenerable in minutes and
+together cost ~2 GB — this repository's contract is the *measurements written down*, not their scratch.

package/docs/plans-carriage.md

@@ -4,7 +4,7 @@ Written 2026-10-09. **Read before writing code.** Human decisions for this featu
 § Decisions Taken and are binding; anything marked *deferred* is a human call, not ours.
 
 DSh ships plan mode (`@deepseek-ai/dsh-plan-mode`) and our own preset mounts it
-(`presets/chapters/agent.cordis.yml:109-133`). Today a session plan survives an archive only as the
+(the `plan-mode` row of the registered preset: `PLAN_MODE_SECTION` in `src/preset.ts`; before the 0.2.0 floor it lived in `presets/chapters/agent.cordis.yml`). Today a session plan survives an archive only as the
 first 400 characters of a tool-call line. That is the worst possible outcome for the one artifact in a
 conversation that is *deliberately* decision-complete — and the reason the plugin exists at all: a
 continuation that cannot see the approved plan either re-plans from recall (lossy) or implements

package/docs/verify.md

@@ -152,7 +152,8 @@ renderer, the segmentation tool, and the child's notice.
 | P10 | Artifact citations resolve wherever they were written | a chapter's `artifacts/aa/<sha>.txt` reference resolves whether the blob sits at the STORE ROOT (arrival stubs) or inside the ANCESTRY TREE (`<store>/<root>/artifacts/…`, where `writeArchive` puts deferred results and every plan) — before this fix the second form was unreadable through `chapters_artifact`, which is what "every byte remains retrievable" actually promised | `artifact-query.test.ts` rows + integration `plans-carriage.test.ts` (`resolveArtifactWithMirror` over the real tree) |
 | P11 | The browser plane runs in the chain | `/plan <message>` → a real `exit_plan_mode` call → the host's review card opened and answered by a real CLICK → fork; asserts the submission's bytes are the artifact's bytes (or provably only-redacted), `planMode: inactive` from the fold, a `kind: plan` document on disk, and that the BRANCH child carries **no** `## Active plan` and no call-out while still citing the archive; plus a guard that no `compaction/*` entered the journey | `tests/e2e/plans.spec.ts` = chain project `plans` (13 s replay, no LLM; 3-entry tape). **Scope, learned at cost:** the continuation leg was REMOVED from this journey because a tape freezes the model's tool ARGUMENTS — my scripted upstream derived `chapters_continue` ranges from the ceiling the live segment tool reported while distilling (30 here), and the runner's session lands at 29, so `validateRanges` refused the stale input (correctly). A journey whose recorded request embeds a machine-specific seq cannot be hardware-neutral. Continuation semantics — `## Active plan`, `## Previous plans`, the seeded `plan/mode`, the checkpoint carry — are covered by the deterministic plane (`continue-plans`, `plans-engine`, `plan-documents`, the § 10 kernel probe) and the in-place path by the heavy/arrival/enrich/fanout journeys. Tape provenance: scripted upstream, see `tests/fixtures/model-tape/plans/PROVENANCE.md` |
 
-| P23 | A partially-wiped preset **self-heals and says so** | `installChaptersPreset(srcDir, dstDir, log, parent)` validates the **whole shipped file set**, not just `preset.yml`; missing shipped files are restored **additively** (files the user already has are never overwritten, so edits survive); statuses `installed / repaired / complete / failed / no-source` are returned, not just logged; the mount line now carries the status and logs **UNHEALTHY** on `failed` instead of claiming it mounted; the dev witness reports `presetComplete` + `presetMissing` (it had the same one-file blindness, in the very tool a user reaches for when this breaks) | unit `preset-install.test.ts` (7 rows, real temp dirs — the function previously hard-resolved its own paths so it was untestable): fresh install, complete-left-alone, **THE INCIDENT** (delete `agent.cordis.yml` → `repaired`, user's `preset.yml` edit preserved, warn names it), nested subdirectory, failure→`failed`+warn+error carried, source-without-manifest→`no-source` and no partial dir left |
+| P23 | **Retired in 0.1.17 with the legacy copy** (support floor 0.2.0): `installChaptersPreset` and `presets/chapters/` are deleted, so there is no installed file set to half-delete. The key is ACCEPTED-and-inert since 0.1.18 — removing it would make an existing profile patch fail to parse, and a bundle that will not mount is worse than a key that does nothing | see P24 |
+| P24 | The preset is a **visible declaration row**, and the row composes on every host in range | `preset-chapters` is inserted by our own `cordis.patch.yml` with the preset definition in its `config`, mounted by `@treeseed/dsh-chapters/preset` (`src/preset.ts`) — the visible Loader entry the host's own presets are, overridable and `disabled`-able from a profile patch, with the registration's lifetime yielded to Cordis (an `apply()`-scoped disposer un-registered it: measured as `register()` succeeding with the roster WITHOUT `chapters`). Rows the host cannot import are dropped and NAMED, because one unresolvable child makes the whole preset `broken` | 15 rows in `preset-declaration.test.ts`, **each verified to fail on the mutation it guards** (ralph re-disabled, an unknown pruner key, `toolFilter` restored, `{{cwd}}` restored, the durable id renamed) — plus real boots of the packed tarball on 0.2.0-rc.2 (`roster: present`, `inventoryRows: 28`, `unusableRows: []`, tool-schedule pruned), 0.2.1-alpha.4 (`registered`, `inventoryRows: 29`, nothing pruned) and 0.1.5-rc.1 (boots; the row says the host cannot register rows) |
 | P21 | The continuation has a **human-pulled door**, and the two doors cannot drift | `/chapters-continue` = `deterministicCommand({intent:'continue'})`, the same builder as `/chapters-fork`; only name/verbs/intent/no-directive prose differ; archive semantics identical (everything since the watermark). CLIENT SIDE, same discipline: the assistant row registers both doors from ONE runner (`src/client/doors.ts` `makeDoorRunner` + a two-row `DOOR_ACTIONS` table) — a composer-only continue left the user with a created child and no affordance | unit `continue-command.test.ts` (7 rows) incl. the **no-drift row**: same events in ⇒ same ranges, titles and plan facts out of both doors; the no-plan case, the refusal naming its own door, and approved ⇒ NOT seeded vs still-planning ⇒ seeded `['user/message','plan/mode']`. Unit `client-doors.test.ts` (7 rows) pins the two client rows (distinct id/order/label/command, the fork label frozen for the specs), that ONE child-id regex parses BOTH door wordings, that both rows fire their own command through the same body, and — by reading the server's own templates — that the reply wording the client parses is still what `deterministicCommand` emits. Browser: project `fork` asserts BOTH buttons render |
 | P22 | The continuation shape is covered **in the browser**, on every push | the leg that a tape could not carry (§ 15) is back, driven by the command — no model request, no frozen `endSeq`; asserted from the child's durable log without switching the UI: `## Active plan`, the operative plan by title with its real verdict, `plan document:` and `chapters_artifact` citations, `## Finding things`, no seeded gate after approval, exactly one synthetic notice (invariant 2) | `tests/e2e/plans.spec.ts` project `plans` — replays in ~14 s with no LLM/GPU, eight-project chain green |
 | P18 | Search answers **without a pool linked** — the findability audit | `buildLocalCorpus` walks the workspace store (chapters, `kind: plan` documents, rules) and answers through the SAME scorer as the mirror door (`rankEntries`), so ranking cannot drift between doors; artifacts are deliberately not indexed (they answer to `chapters_artifact`); the answer names its door ("searched this machine's store, N docs, no pool mirror") so a session never reads *this machine only* as *the whole project*; "nothing matched" (`documents>0`) is distinguished from "nothing here" (`empty`); a pool miss falls back to the local store before answering empty | unit `local-corpus.test.ts` (5) + integration `find-without-a-pool.test.ts` through the real tool wrapper — the empty answer used to be born in the wrapper, not the pure function |