@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/docs/contract.md

@@ -0,0 +1,938 @@
+# DSH Plugin Contract
+
+Verified against `examples/deepseek-harness` and the reference plugins. Every claim here cites a file
+so it can be re-checked after an upgrade. **Nothing in this file is inferred.**
+
+## Three Schema Systems
+
+Conflating these is the top time-waster in this project.
+
+| Declaring | Format | Import |
+|---|---|---|
+| Plugin `Config` | `Schema.object({...})` | `import Schema from '@deepseek-ai/schemastery'` — **default** |
+| Tool `parameters` | plain declarative spec (`ParameterSchemaSpec`) | none; `defineTool` from `@deepseek-ai/dsh-tools` |
+| Storage-domain records | zod | `import { z } from 'zod'` |
+
+Plain objects are *required* for tool parameters and *rejected* for plugin config.
+
+`import { z } from '@deepseek-ai/schemastery'` **does not exist** — 0 occurrences upstream versus 128
+default imports. Copying the named form fails to build.
+
+## Config
+
+Shape copied from `examples/dsh-compact/src/index.ts:15,26-37`.
+
+```ts
+import Schema from '@deepseek-ai/schemastery'
+
+export interface Config {
+  continuationBudgetRatio: number
+  chapterTokenTarget: number
+  toolResultDeferFloorTokens: number
+  artifactStoreRoot: string
+  tocBulletBudgetTokens: number
+  pressureSuggestionRatio: number
+}
+
+// Per-model, mirroring the host's `modelPolicies[]` — do NOT invent a flat project-wide ratio.
+export const Config: Schema<Config> = Schema.object({
+  compactAtRatio: Schema.number().default(0.90),               // host thresholdRatio, ours defaults higher
+  continuationBudgetRatio: Schema.number().default(0.25),      // of the window REMAINING after the header
+  chapterTokenTarget: Schema.number().default(8000),
+  toolResultDeferFloorTokens: Schema.number().default(200),    // a floor, not the policy — see below
+  artifactStoreRoot: Schema.string().default('.dsh-chapters'),
+  tocBulletBudgetTokens: Schema.number().default(2000),
+  pressureSuggestionRatio: Schema.number().default(0.75),
+})
+```
+
+These are **defaults overridable per model**, matching the host's own `modelPolicies: z.array(modelPolicy)`
+(`compaction-basic/src/index.ts:113`) — some models have huge windows, some have 32K, and one flat number
+serves neither. Resolve the window with `ctx.llm.resolveModelInfo()` and keep our own keys alongside the
+host's rather than shadowing them. Three notes on the defaults, so nobody trusts them as settled:
+
+- `continuationBudgetRatio` is a share of **(window − system prompt tokens)**, never of the whole window.
+  See `docs/architecture.md § Budgets`. Measure the header once per process generation and cache it.
+- `toolResultDeferFloorTokens` is **a floor, not the policy.** The keep/defer decision belongs to the model
+  (`toolResultOverrides` below); the floor exists only so trivial results stay inline without being
+  itemized, keeping the chapter's narrative readable and the exception list sparse. The number is a guess
+  to calibrate in Phase 1 — too high and meaningful short outputs get deferred, too low and chapters bloat.
+- **One exception since 2026-09-19:** `toolResultArtifactTokens` IS a policy — a hard band for results too
+  large to be reasoning context at all (see architecture.md's arrival-time amendment). It intercepts at
+  the tail node before the next request composes (the pruner's mid-history rewrite is NOT this); the
+  model still judges everything below the floor, at archive time, exactly as before. Queries go through
+  `chapters_artifact` (toc | search | read), which is read-only and store-contained by construction.
+- There is deliberately **no maximum.** Deferral is a judgement with a size floor; over-sized output is
+  caught by the continuation budget and by the chapter split signal, both of which refuse or report rather
+  than silently clip.
+
+Note `forkThresholdRatio` from earlier drafts is renamed to `pressureSuggestionRatio`: with the reordered
+plan it gates a *suggestion*, not an action.
+
+## Entry Point
+
+```ts
+export const name = 'dsh-chapters'          // must match package.json and cordis.patch.yml
+export const inject = [/* service names */]
+export const Config: Schema<Config> = …
+export function apply(ctx: Context, config: Config) { … }
+```
+
+## Services (`inject`)
+
+`dsh-session-fork/src/index.ts:161` shows the full menu: `commands`, `storageDomain`, `sessions`,
+`sessionPersistence`, `sessionQuery`, `agents`, `tokenMeter`, `llm`, `sessionController`, `connection`,
+`tools`, `systemPrompt`.
+
+Ours, minimal and honest:
+
+```ts
+export const inject = [
+  'sessions', 'sessionPersistence', 'sessionQuery', 'storageDomain',
+  'agents', 'tokenMeter', 'llm', 'tools',
+]
+```
+
+- `agents` — `ctx.agents.create`, the continuation primitive. **The load-bearing one.**
+- `storageDomain` — chain registry.
+- `sessionQuery` — `observeSession` for the calling agent's own log and preset projection, plus the
+  durable reads for **other** sessions (see § Durable reads — the verbs are not interchangeable).
+- `tokenMeter` — pressure math and the continuation budget preflight.
+- **`systemPrompt` is excluded on purpose** (invariant 3).
+- Add `commands` at the UI/CLI trigger phase; `connection` / `sessionController` only if a create path
+  turns out to need the client RPC round-trip.
+
+Declare only what you use — `dsh-compact` gets by on `inject = ["commands"]`.
+
+## Durable reads — `sessionQuery` verbs are NOT interchangeable
+
+Measured 2026-10-22 against host `0.2.0-rc.2` while root-causing #58. The rule this section exists to
+enforce: **measure a host verb's payload *shape*, not its presence.** `spikes/subagent-end/FINDINGS.md`
+finding 5 recorded `{count, types}` from `listEvents`, saw 10 plausible event types, wrote "returned the
+full durable log", and the whole of door 5 was built on that. The types were real; the payloads were not
+there at all.
+
+| verb | returns | safe as an archive input? |
+|---|---|---|
+| `listEvents(sessionId)` | `SessionEventRecord[]` = `{sessionId, seq, type, time, surface}` — **no `data`** | **No.** Types and seqs only: a metadata index. |
+| `readSession(sessionId)` | `{session: structuredClone(header), inheritedEventCount, events: snapshotSessionEvent(e)[]}` | **Yes**, and it carries the header too — one call, so no `listSessions()` scan. |
+| `readSurface(sessionId)` | cloned header + `currentSurfaceEvents` (folded surface, snapshot-detached) | Yes for surface work; it is *folded*, so it is not the whole log. |
+| `filterEvents(sessionId, filters)` | semantic event documents | No — search documents, not events. |
+
+File:line (host install, `/home/adrian/node_modules/@deepseek-ai/dsh-session-query/`):
+`lib/index.js:1141` `async listEvents(sessionId) { return eventRecords(sessionId, (await this._corpus.load(sessionId)).events) }`
+→ `:845-847` `eventRecords` → `analyzeEventLog(sessionId, events).records`, built at `:966-973` as
+`records: events.map((event) => ({ sessionId, seq: event.seq, type: event.type, time: event.time, surface: … }))`.
+Published type: `lib/types/types.d.ts:43-54` (`interface SessionEventRecord` — the doc comment says
+*"Lightweight metadata for one event"*, which is the sentence the spike skipped).
+`lib/index.js:1079-1087` `readSession` → `events: loaded.events.map(snapshotSessionEvent)`;
+`snapshotSessionEvent = adoptSessionEvent(structuredClone(event))` at
+`@deepseek-ai/dsh-session/lib/index.js:1106-1108`, i.e. a **validated, payload-bearing** clone.
+
+Read the header, never infer it: `readSession().session` is the kernel's own `SessionHeader` clone, so
+`origin` / `parentSession` / `agentPreset` / `cwd` come from the same observation as the bytes being
+archived — which is what door 5's gate needs (#58). The header is *recorded* on the child's own row
+(`subagent`/`parentSession` frontmatter), not used to re-link the tree — see docs/architecture.md
+§ The archive moments for why `linkChild` was measured and rejected.
+
+And the host's own teardown ordering, which decides **which** arm runs:
+`@deepseek-ai/dsh-subagent/lib/index.js:1240-1250` (continuable) — `flushFinalState` →
+`await activation.handle.dispose()` → `resident.delete(childId)` → `observer.settle(failure)`, and
+`settle` is what emits `subagent/end` (`:317-324`). `observeRun` (one-shot, `:296-306`) emits earlier,
+before disposal. So a continuable child's live handle is **always** gone at settlement: the durable arm
+is the only arm for it, and the fast path is the only arm for one-shot children. Both must be tested;
+one measurement of one mode is what #58 is.
+
+`SessionEventLike.data` is therefore **required** in `src/types.ts` (was optional). Optionality is the
+reason a `listEvents` record passed as `SessionEventLike[]` type-checked, and the renderer's
+`ev.data ?? {}` then made a hollow chapter legal instead of failing to compile.
+
+## Tools
+
+`defineTool` at `packages/core/tools/src/schema.ts:545`:
+`defineTool<const S extends ParameterSchemaSpec, const O extends ValueSchemaSpec>(...)`.
+
+**`output` is mandatory** on every `ToolDefinition` — the `O` — and needs `{ schema, render }`. Idiom
+from `dsh-session-fork/src/tools.ts:110-121`:
+
+```ts
+function jsonOutput<T>(schema: ValueSchemaSpec) {
+  return { schema, render: (_args: unknown, value: T) => [{ type: 'text', text: JSON.stringify(value) }] }
+}
+```
+
+Definitions (names pending the rename decision — see `docs/architecture.md § Naming`):
+
+```ts
+const chaptersContinue = defineTool({
+  name: 'chapters_continue',
+  description:
+    'Archive this conversation as Markdown chapters and open a new session that starts from their '
+    + 'table of contents. This session is left untouched. Supply event ranges, not text.',
+  parameters: {
+    title:       { type: 'string', required: true, description: 'Name for the continued session.' },
+    handoffNote: { type: 'string', required: true, description: 'State of play: what was in progress, decisions held, next step. As long as it needs to be — it is budget-checked, not truncated.' },
+    chapters: {
+      type: 'array', required: true,
+      description: 'Ranges ascending by startSeq, non-overlapping, all <= archiveCeiling, covering every event below the ceiling.',
+    },
+  },
+  output: jsonOutput(CHAPTERS_CONTINUE_RESULT),
+  async execute(args, exec) {
+    // caller agent from `exec`; refuse cleanly when absent
+  },
+})
+```
+
+Register host-side: `ctx.tools.register(tool)`. Call-site precedent:
+`dsh-session-fork/src/index.ts:786`.
+
+## LLM Calls
+
+Segmentation and summaries go through **`ctx.llm.stream()`** — the concrete method, not `ctx.llm`
+generically. Window sizes via `ctx.llm.resolveModelInfo(provider, model, signal)`.
+
+The cache-friendly pattern — a stream call reusing the conversation's own system prompt as its prefix —
+is at `packages/compaction/compaction-basic/src/index.ts:225,290`. Copy that for segmentation so the
+pass is served from cache.
+
+## Session Creation
+
+**Never** `ctx.sessions.fork(...)`. *(Corrected by Phase 0 measurement — an earlier draft of this file
+claimed the method was client-only. It is not.)* `ctx.sessions` does expose `fork`, `_forkSeed` and
+`_resolveForkSource` host-side; calling `fork` from a plugin is refused:
+
+> `session fork is owned by session-controller; ambient plugin access is denied`
+
+So the prohibition holds for a better reason than we stated: the copy-the-log path is capability-gated
+away from plugins, and the kernel handler seeds with
+`commands.ts:260` → `seed: source.events.slice(0, cut)` (invariant 2). Do not go looking for a way
+through the gate — `agents.create` is the sanctioned seam.
+
+Ours — `seed` is optional per `packages/core/agent/src/index.ts:95`
+(`readonly seed?: readonly SessionEvent[]`); the multi-event and one-event seed contracts are measured
+in [spikes/probe/FINDINGS.md](../spikes/probe/FINDINGS.md). **Phase 0b rewrote this call**: `agents.create`
+composes NO preset — `meta.agentPreset` is a durable label only (r15: child first request 974 tokens,
+`tools: 0`, a tool-less agent that cannot `read` its own chapters). Composition goes through the `setup`
+callback exactly as session-controller's `composeAgent` does it
+(`api/session-controller/src/agent.ts:377-390`; the service itself says so at
+`preset/agent-presets/src/index.ts:221`):
+
+```ts
+ctx.agents.create({
+  sessionId: newId,
+  seed: [tocNoticeEvent],                      // exactly one event at seq 0 (invariant 2)
+  inheritedEventCount: 0,
+  meta: { cwd: parentCwd, agentPreset: presetId },
+  agentOptions: ctx.get('agentDefaultModel').currentSelection(),
+  setup: async (agentCtx) => { await ctx.get('agentPresets').mount(agentCtx, presetId) },
+})
+// then attach to the parent's workspace (r6 lesson: unattached sessions list nowhere)
+```
+
+Without `agentOptions` every turn dies pre-provider (`{{model}}` no value, r10); without `setup` the
+child has no tools (r15); with both, r16 measured the real composed head: 13,315 tokens / 27 tools.
+Carry over from `dsh-session-fork`: `src/vendor/fork.ts` (`forkWorkspace`, `composeAgent`,
+`readSessionState`) already follows this shape. `branch.ts:10-14` warns that kernel `SessionStore.fork`
+yields fiber-scoped sessions evicted from the sidebar — `agents.create` is the only durable, listed,
+resumable route. *(Phase 0 confirmed: durable, listed, resumable, byte-identical across a kill.)*
+
+Keep `anchoredBoundaryOf` (`vendor/fork.ts:213`) with its role changed: it yields the **archive ceiling**
+(`boundarySeq`, `cut`) for *what to render*, never for seeding.
+
+Notice event shape — built and vocabulary-pinned by `src/notice.ts` (+ `test/notice.test.ts`, + the
+v4 admission rows in `tests/unit/host-seed-contract.test.ts`): one `user/message`, `surfaceOp: 'append'`,
+at `seq = 0`, `source { kind: 'plugin:dsh-chapters', form: 'snapshot', sections: [{ name: 'chapters:toc', text }] }`
+— **producer-owned kind, no `plugin` field**. Session format v4 (host 0.2.x, measured 2026-10-18 on
+`0.2.0-rc.2`) retired the bare `kind: 'plugin'` wrapper: persistence-row admission refuses it with
+`format v4 message requires a producer-owned source kind`
+(`@deepseek-ai/dsh-session-format-v3-to-v4` `lib/index.js:126`; also
+`dsh-session-persistence-jsonl/lib/worker.cjs:10902`). The v3→v4 migration's own
+`rewritePluginSource` does exactly what we now emit: "kind is the producer's own kind and whose
+`plugin` field is dropped". Continuity validation in `Session.create`
+requires the seq to be the next contiguous seed position (rejection message measured in r5).
+
+## Compaction Engine Integration (Phase 0b)
+
+The subclass seam, with everything measured by rounds 12-17 (sources: the installed
+`@deepseek-ai/dsh-compaction-basic@0.1.5-rc.2`; same tree in `examples/deepseek-harness`):
+
+- `class X extends BasicCompactionEngine` (`export default` it; the loader mounts class plugins directly)
+  and override `protected summarize(input, agent, signal?)` — the **sole** customization hook; `compactRegion`,
+  `compactIfNeeded`, `compactNow` stay inherited. Subclassing inherits `static inject
+  = ['llm','tokenMeter','sessions']` — extend it or `ctx.agents` throws *cannot get property "agents" without
+  inject* (r12 crash).
+- Deterministic summaries use the unmarked `SummaryResult` branch: `{ summary, provider, model }` with
+  **no `llmStreamCall`** — the union explicitly admits "template, remote, or other summarizer"
+  (`compaction-basic/src/summarizer.ts:100-106`); the durable `compaction/summary` schema matches
+  (`compaction/src/types.ts`). Omit `usage` — its absence is the zero-token record (r12 verified).
+- `summarize()` gets content, not seqs: `SummarizationInput = { tools?, messages }` where messages are the
+  system head (when present) + the region's derived messages (`region.ts:545`). Correlate chapter files
+  to ranges **post-commit** from `CompactionResult.shadowedSeqs` / the `compaction/summary` event — and
+  remember the manual path calls `compactSurfaceRegion` directly (`index.ts:382`), so overriding
+  `compactRegion` sees only the automatic paths.
+- The kernel enforces the transaction: `compaction/start` lock, `SurfaceChangedError` → `changed`,
+  shrink floor `framed ≥ priced` → refuse (`code='summary'`, r12), replacement `user/message` carries
+  `source { kind: 'plugin', plugin: 'compact', compactionId }` — a NEW vocabulary member to pin against
+  (our notices use `plugin: 'dsh-chapters'`; the checkpoint's is the host's own).
+- Config: `retainRatio ∈ (0, 1]` (rc.2 validates; boot dies), `retainTokens ≥ 0`, `retainRatio <
+  thresholdRatio`, `modelPolicies[]` per exact target, `auto` default true. Mounting shape per
+  `docs/host-compaction-seam.md`: OUR row goes inside a preset's `cordis:group` realm
+  (`isolate: { compaction: true }`), where `ctx.get('toolResultPruner')` also resolves in-realm —
+  the standard preset deliberately mounts basic + command-compact + pruner as one group.
+- Cross-copy identity rules (we ship our own `0.1.5-rc.2` deps; the host runs its copies):
+  `ctx.get('compaction')` returns the host's receiver proxy — property reads work, `=== this` never
+  (r12); duplicate provision of `compaction` on one plane fails boot loudly (r14); a host-plane
+  `command-compact` does not classify OUR `ManualCompactionError` (different class objects) — put the
+  command in our own realm rows or ship our command (r12 §J).
+
+### Mounting shape, measured (stages 0-3)
+
+- Realm rows resolve **subpath exports**: `name: dsh-chapters/engine` →
+  `exports["./engine"]` (r18). Host-plane mounting is the wrong shape (double-fire
+  with preset realms; the kernel's duplicate guard is same-plane only).
+- The loader passes row config to constructors **unstripped**, and the base's
+  `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: 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
+  retry loop can commit then throw, and success-path-only finalization strands
+  committed records (measured: 3 plans / 1 finalized / no errors).
+- `@deepseek-ai/dsh-home-paths` exports `dshHomePath(...segments)` — the sanctioned
+  way to reach `$DSH_HOME` from plugin code (host rc.2 line).
+
+## Lineage: Kernel Fields We Must Not Lean On
+
+`SessionHeader` (`packages/core/session/src/types.ts:93-122`) carries `version`, `id`, `createdAt`,
+`cwd`, `parentSession`, `isSeeded`, `origin`, `delegationDepth` — and **no system prompt or tool
+schemas**.
+
+- `isSeeded` means "contains a fork-inherited event prefix"; our one-event synthetic seed is not that.
+- `parentSession` is documented as *seed lineage*. Setting it to fake a relationship would be a misuse.
+- Therefore **our storage-domain registry is the sole authority on ancestry**, and the web UI's branch
+  graph will show our child as an unrelated root. A chain/manifest view is this plugin's job.
+- The header being composed per request from the preset plus plugin contributions is *why* invariant 3
+  holds, and why cache validity is per-process-generation: a restart or config edit recomposes it for
+  everyone.
+
+## Storage Domain Registry
+
+Precedent verbatim: `examples/dsh-session-fork/src/store.ts:36-43`.
+
+```ts
+import { z } from 'zod'
+import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain'
+
+const chapterRecord = z.object({
+  id: z.string(),                     // `${authorSession}/${n}`
+  authorSession: z.string(),          // keying by creator, not by a linear chain
+  path: z.string(),
+  startSeq: z.number().int().nonnegative(),
+  endSeq: z.number().int().nonnegative(),
+  sha256: z.string(),                 // integrity: verified before citing
+  tokens: z.number().int().nonnegative(),
+  summary: z.string(),
+  createdAt: z.string(),
+})
+
+const sessionState = z.object({
+  parentSession: z.string().nullable(),
+  rootSession: z.string(),
+  nextChapterNumber: z.number().int().nonnegative(),
+  chapters: z.array(chapterRecord),
+})
+
+export const chapterDomainSpec = defineDomain({
+  name: 'dsh_chapters',
+  version: 0,
+  tables: { sessions: domainTable<string, SessionState>(sessionState) },
+})
+```
+
+Open with `ctx.storageDomain.open(spec)` → `table(name).get/put/entries/size`. `put` reaches backend
+durability before resolving, so a resolved save survives restart. Backend is JSON under
+`~/.dsh/storages`.
+
+## Chapter File Format: Markdown + Frontmatter, Not XML
+
+Decision with reasoning in `docs/architecture.md § File Format`. Short form: `.md` with YAML frontmatter.
+
+```markdown
+---
+chapter: "003-database-schema"
+title: "Database Schema"
+session: 01HTZ6Q8K3
+root: 01HTAB12CD7
+seqRange: [184, 231]
+sha256: 6d59…
+tokens: 7420
+generatedAt: 2026-09-15T17:22:04Z
+artifacts: 2
+---
+
+# Database Schema
+
+**User:** Let's design the user table…
+```
+
+Frontmatter carries every machine-queriable fact a parser would want. The body stays token-dense prose.
+The `read` tool returns both; the harness's own skill loader uses this same frontmatter-plus-body idiom,
+so it is an established convention here. **Do not convert chapters to XML** — see
+`docs/architecture.md § File Format` for the full rationale and the one case that would reopen it.
+
+## Packaging
+
+`cordis.patch.yml` is required for the bundle to mount — a one-entry list that `insert`s the package by
+name (compare `examples/dsh-session-fork/cordis.patch.yml`). Its `name` must match `package.json`. In
+`package.json` the patch appears in **three** places:
+
+```jsonc
+"main": "lib/index.js",
+"exports": { ".": {…}, "./cordis.patch.yml": "./cordis.patch.yml", "./package.json": "./package.json" },
+"files": ["lib", "cordis.patch.yml"],
+"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
+```
+
+Entry `apply(ctx, config)`. Build with `tsc -p tsconfig.json` and **build before installing**. A client
+UI (later phase) additionally needs `dsh.client` and a `tsdown.client.config.ts` — see
+`dsh-session-fork/package.json` for the shape.
+
+### An armed goal has no rest state — measured, with the lines that prove it
+
+Verified while trying to make a goal-bearing tape leg deterministic (#138). The round driver gates on
+`phase === 'active' && activation === 'armed'` plus agent idleness
+(`@deepseek-ai/dsh-goal-round-driver` `src/index.ts:105-117`), and a round is itself a turn — so every round ends, and
+the next is scheduled. There is no moment in which an armed goal is also at rest:
+
+- **spending the budget ends the goal.** At `:182-188`, `roundsStarted >= maxGoalRounds` calls
+  `ctx.goals.block(agent, ref, { code: 'round-limit', message: 'Goal reached its configured limit of N rounds.' })`.
+- **the strip then disappears.** `@deepseek-ai/dsh-client-ui-goal` `GoalBar.tsx:85-86`: *"Loading, absent, and complete
+  goals have no strip at all"*, and the guard excludes blocked/complete. So the control a test wants to observe
+  (`Pause goal` → `Resume goal`) is not rendered in the state the budget produces.
+- **the per-goal budget is a plugin argument, not a user one.** `ctx.goals.create(agent, { objective, maxGoalRounds })`
+  (`@deepseek-ai/dsh-goal` `src/index.ts:303`, `types.ts:28-30`) — the human `/goal` command passes no budget
+  (`dsh-command-goal` usage is `goal <objective>, /goal clear`; `command-goal/src/index.ts:150` calls `create` without
+  one), so the default 256 applies.
+
+Consequences for this repo, both measured: a goal-bearing tape leg agrees with a runner only while the runner's latency
+happens to reproduce the capture's round count (staging's `prompt` leg failed twice on docs-only pushes:
+`MISS tape=prompt entries=23 storedCandidates: []`, runs 40697174778 / 40706037817); and bounding the budget to 1 makes
+the goal vanish before a leg can act on it (17-entry tape, `Round: 1/`, no second round, `the host goal bar appears once
+a goal exists`). Upstream's own test fixture takes the third path — create then `ctx.goals.disarm(agent)`, noting
+*"An armed goal makes the shipped goal-round-driver start a round at idle, racing the test driver's disposal"* — which
+is the disarmed state, not the armed one a displacement claim needs.
+
+What is needed to test this in a tape: a way to open an **armed** goal whose driver will not fire until released, or a
+non-terminal exhausted state that still renders the control (#138). Until then the goal/suggestion interplay is
+verified live under a wall-clock bound (`tests/e2e/prompt-goal-live.spec.ts`), not by the model-free acceptance job.
+
+### A profile patch may not re-declare a host plugin's row — measured on 0.2.0-rc.2
+
+`profiles/web/cordis.patch.yml` layers by row `id`, and the rig relies on that for its **own** rows
+(`preset-chapters`, `agent-preset-registry`, `llm-pi-ai`, `agent-default-model`, `llm-gate`,
+`fetch-timeouts`). Copying that trick onto a row that belongs to the installed bundle is not neutral. Three variants,
+each run against an unchanged spec and corpus so the only variable was the patch:
+
+| profile patch | result |
+|---|---|
+| `- id: goal` + `config: { defaultMaxGoalRounds: 1 }` | the `goal` plugin stops working: `/goal` creates no goal, so `[data-goal-bar]` never renders |
+| `- id: goal` with **no** config | every test passes, but the boot issues a request no tape has: `MISS tape=prompt entries=23 messages=1 closest=0000.json` — at the FIRST message, before any goal exists |
+| no `goal` row in the profile patch | clean run (`5 passed`, rc 0) |
+
+Read it as: duplicating a host row changes the mounted plugin set (extra registration → an extra request), and adding a
+`config:` block to that duplicate replaces the base row rather than merging into it, taking the plugin's real config
+surface with it. So the patch is a way to configure **rows you own**, not a way to reach into a host plugin's settings.
+The concrete consequence: `@deepseek-ai/dsh-goal` does export
+`config = z.object({ defaultMaxGoalRounds: z.number().default(256) })` and `resolveCreateGoal(request,
+defaultMaxGoalRounds)` honors it, but no boot can pin it from the profile — which is why goal-round bounding is a host
+ask (#138) and not a rig bug to fix.
+
+### Presets are declaration rows now (host ≥ 0.1.7-alpha.1) — measured, with the incident
+
+A user preset used to be a directory `$DSH_HOME/.agent-presets/<id>/` holding `preset.yml` +
+`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: '@fractalsynapse/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,
+not stylistic:
+
+- **In-place compaction** (the engine's job) fires at the base's own timings, which we inherit:
+  `agent/pre-step` pressure and `agent/request-error` overflow recovery
+  (`compaction-basic/src/index.ts:144,176`). Pre-step is BETWEEN steps, never mid-request; the pressure
+  loop is retry-bounded and its failures are caught, warned, and the turn continues (r13 watched it).
+  An earlier draft called `agent/pre-step` "mid-turn, breaks the in-flight request" — the shipped design
+  contradicts that reading; the harness itself compacts there, replay-safely. One structural limit worth
+  remembering: `compactIfNeeded` needs a durable routed request, so the FIRST step of a fresh session can
+  never compact (index.ts:260, measured r13).
+- **Session creation** (`chapters_continue`, `chapters_fork`) fires at `turn/end` boundaries only — an
+  archive ceiling is a completed `turn/end` by construction, and an in-flight exchange belongs to the
+  handoff note, never a mid-turn cut.
+- Manual is MVP. The button path cannot supply model-authored titles or ranges, so segmentation must be
+  a plain function callable **without an agent turn** — build that seam in Phase 1, not Phase 5, or the
+  UI and automatic paths both force a rewrite.
+
+> **SUPERSEDED as a surface by § "Suggested Next Step bar" below** (#113, chip removed in #114). The facts in
+> this section stay authoritative and are the reason the replacement is a docked row: the overlay geometry,
+> the non-writable placeholder, and `inputActions.setDraft`/`submit` were all measured here first. Reviving an
+> overlay must answer all four defects #113 recorded, with measurements.
+
+## Composer Ghost Layer — measured host facts (#71, verified 2026-10-21 against `examples/dsh` @ 0.2.1-rc.2; runtime pin 0.2.0-rc.2, compile deps still 0.1.5-rc.2)
+
+The prompt-recommendation feature renders a ghost layer in the composer. What the host does
+and does not let a plugin do, with anchors:
+
+- **The placeholder text is NOT plugin-writable.** `placeholderText` is computed inside the
+  host's `InputBar.tsx:363-372` (`packages/client/ui-conversation/src/client/skeleton/`): an
+  owner prop (passed only by the host's own `ConversationContent`) ?? offline/disabled/steer
+  states ?? `useProjection('plan')` swap ?? locale defaults. Every string is locale-owned
+  (`client/locales.ts`, enforced upstream by `verify-client-ui-i18n`); no config key, slot,
+  projection input, or service feeds a plugin value into that chain. Plan mode swaps it from
+  host code (`InputBar.tsx:67-68`) — mechanism precedent, not an extension point.
+- **The composer overlay slot is the hole.** `'conversation.input.overlay'` — "floating
+  entries rendered inside the resident composer card", `{ kind: 'list'; scope: 'session' }`
+  (`contract/slots.ts:271-272`), rendered at `InputBar.tsx:404` inside
+  `[data-composer-overlay]`. The shipped slash-menu occupies it
+  (`ui-input-trigger/src/client/index.ts:65`) — registering there is a proven path, and
+  `slots.inject(name, …)` waits for the declaration, same as our assistant-actions door rows.
+- **Standard session props give the composer machine.** Session-scope slot entries receive
+  `useConversation` / `useInput` / `inputActions` (`contract/slots.ts:329-336`); `InputActions`
+  carries `setDraft(text)` ("replace the whole draft with plain text"), `insertText`,
+  `persistDraft`, `submit` (`contract/input.ts:263-291`), and `InputState.draft` is the
+  published draft text (`contract/input.ts`, `InputState`). `useProjection` is on
+  `SessionStandardProps` (`ui-session/src/client/index.ts:166-173`) for the 0.2.x push upgrade.
+- **ArrowRight is free.** The composer keymap registers `KEY_ARROW_UP/DOWN`, `KEY_TAB`,
+  `KEY_ESCAPE`, `KEY_SPACE`, `KEY_ENTER` at `COMMAND_PRIORITY_CRITICAL`
+  (`input/editor/keymap.ts:104-140`); `grep ArrowRight` over `ui-conversation/src/client` is
+  empty on both 0.1.5 and the 0.2.1 checkout. `ComposerKeyboard` itself is
+  "InputBar-exclusive … never across a plugin boundary" (`contract/draft-editor.ts:54-58`),
+  so the plugin's accept gesture attaches a capture-phase `keydown` listener at the DOM level
+  while its ghost is visible — fail-open: if the host ever claims the key or reshapes the DOM,
+  the click-to-accept path still works and nothing else breaks.
+- **Host→client pull channel: `remote.commands.execute(sessionId, line, [])`**, the exact wire
+  the door buttons ride (`src/client/doors.ts`, Playwright-verified; result arm
+  `{value.result.kind/text}`). New **wire events are NOT available to plugins**: the forwarded
+  allowlist is app-owned ("the one home of this application's forwarded-Host-event allowlist",
+  `packages/api/remotes/src/remote-events.ts:24`).
+  **Every execution is recorded** (measured, `packages/interaction/commands/src/index.ts:365-385`):
+  `command/run` + `command/done` lifecycle events, log-only (never model surface) but rendered as
+  history nodes by the web UI; `recordInput: false` (definition flag, `index.ts:71-75`) suppresses
+  only the `args` payload, NOT the node pair. There is no quiet-invocation mode — a polling client
+  on this wire writes visible history every pull, which is why the bar's cadence is a tested
+  decision (#193) and the push swap (#194) is the structural fix.
+- **Push transport is 0.2.1+ (measured 2026-10-30, #193 — this line said "0.2.x-only" and was
+  wrong):** `appendPluginRecord` has **zero occurrences** at tag `dsh-v0.2.0-rc.2`
+  (`packages/core/session/src/index.ts`) and is present at `dsh-v0.2.1-rc.2` (`:492`). The pinned
+  rig host (0.2.0-rc.2) therefore CANNOT serve the push swap; #194 gates on a host-pin bump plus
+  feature detection with pull fallback. `appendPluginRecord(session, 'plugin:<name>', data)`
+  (`packages/core/session/src/index.ts:492`, grammar/types at `types.ts:525-543`, reader
+  `pluginRecordOf` at `index.ts:508`): durable, append-only, "never enters the model-visible
+  surface", retained by fork/resume, skipped by unknown readers. The `verify-plugin-record-callers`
+  gate is a **source-tree policy inside the dsh repo** ("rejects any other production caller
+  *in this repository*") — it does not and cannot gate an external plugin, and the `plugin:`
+  grammar is precisely the external-plugin carrier. `PluginRecordMap` is declaration-merged
+  (`export interface PluginRecordMap {}`, `types.ts:533`); a `ProjectionDefinition` registered
+  on `ctx.sessionProjections` (the plan/goal pattern; our host plane ALREADY injects
+  `sessionProjections`) folds committed events to client-pushed values. Both APIs are absent
+  from our installed `@deepseek-ai/dsh-session@0.1.5-rc.2` (grep-verified on `lib/types`),
+  which is why #71 ships the PULL transport; the push swap is the backlog item, and it needs
+  the compile-time `@deepseek-ai/*` closure moved to 0.2.x alongside the runtime pin.
+
+## Client Sessions Service: which verbs exist (measured 0.2.0-rc.2, #77)
+
+The client service injected as `sessions` (`dsh-api-session-controller/lib/types/client/sessions/
+service.js`) is a **session store and lifecycle**, not a navigator. Its verbs are
+`create / fork / using / retain / retainInfo / release / refresh / projectList / binding /
+handleSessionAdded / handleSessionRemoved / handleSessionActivity / …`. There is **no
+`sessions.open`** — a guard written as `if (typeof sessions.open !== 'function') return false`
+fails silently on every call, which is exactly how the chapters door spent three evenings looking
+like a client that refused to catalogue a plugin-created child.
+
+The navigation verb lives on the workspace service (`dsh-client-ui-workspace/lib/client.js`):
+
+```js
+openSession(target) { this.replaceMain(target, this.lifetime.signal, "reveal"); }
+```
+
+and the host's own fork affordance uses it — `dsh-client-ui-chat/lib/client.js`, right after its
+fork RPC resolves: `.then((childId) => { ctx.uiWorkspace.openSession(childId); })`. So a plugin
+that must move the visible session injects **`uiWorkspace`** and calls `openSession(sessionId)`;
+`sessions.*` cannot do it. `sessions.using/retain` materialize a scope for a session the client
+addresses; they do not change what is displayed.
+
+Two corollaries, both bought once:
+- A client capability you assume is a client capability you must assert at the decision point —
+  `src/client/doors.ts` now prints which verbs were actually present when it decided
+  (`+c/+u/+o/+w`), because a note that blames the user's client for the plugin's own missing port
+  sends the next reader down the wrong path.
+- An injected port that is optional and stops being wired fails as a symptom, not as an error:
+  `tests/unit/client-doors.test.ts` has a row that fails if `src/client/index.ts` drops
+  `uiWorkspace` from `inject` or stops passing it.
+
+## `ContinuePorts.mutateState` — the row write seam (#101)
+
+`ContinuePorts` exposes **both** `getState`/`putState` and `mutateState(sessionId, fn)`, and the split is
+load-bearing, not historical:
+
+- `getState` is for **reads** (ancestor walks, root resolution) and for nothing else.
+- `putState` survives only for **brand-new rows** — a child row that no other writer can hold yet
+  (`linkChild(freshSession(childId), …)` at `continue-core.ts:527`).
+- **Every write to an EXISTING row goes through `mutateState`**, because `store.put` replaces the whole
+  value: a `getState`→`putState` pair loses any commit another door made in between. The chapter allocator
+  (`reserve`, `reservePlan`) runs *after* hundreds of fs writes, and the commit runs after `agents.create`
+  plus the artifact work — both are windows. AGENTS records the incident class: an enrichment put at
+  04:53:52.841 rewound a compaction commit from 04:53:50.915, deleting its manifest, reservation,
+  `finalized` entry and chapter record while its 960 KB file survived on disk. Files present + records
+  gone is the signature, and `chapters-repair` then looks like a phantom-maker.
+
+`fn` must apply its change to the row it is handed and may not return a captured snapshot — a
+`mutate(id, () => snapshot)` is a stale `put` with better branding (fixed once already in `repair-run.ts`
+for the hollow-payload supersede).
+
+## Suggested Next Step bar
+
+> **Host fact, measured 2026-10-28 (the draft gesture's limit, and where it actually lives).** The composer surface a
+> dock receives carries `captureInsertion, insertText, setDraft, persistDraft, addAttachments, removeAttachment,
+> pruneAttachments, submit` — every verb is present and callable — and a programmatic write still throws
+> `Cannot read properties of undefined (reading 'draftRev')` with the composer text left empty. Reproduced identically
+> on host `0.2.0-rc.2` and `0.2.1-rc.4` (`var/e2e-prompt-draft-dump.json`, `LEG=prompt MODE=record`), which is the
+> evidence behind #126 staying a host ask: **`draftRev` is not referenced anywhere in `ui-conversation/src`** in either
+> tag — the identifier lives in `ui-commands/src/client/popup.ts` — so the write path's missing revision object is not
+> the module whose `setDraft` implementation changed between those versions. Do not infer a fix from that module's diff;
+> the source read looked convincing and the browser said otherwise. The shipped client therefore refuses visibly and
+> keeps Run as the working gesture (`docs/verify.md`'s "delivered, not assumed").
+
+
+**What a dock component is handed (measured from the host's own contract table,
+`dsh-cordis-client-runner/lib/client.js`, entry `key: "conversation.input.dock"`).** It is a `list` region,
+`scope: session`. Register options are `id` (required), `order` (optional, ascending, default 0), and `label`.
+The component's props are **hooks**, not scalars: `useSessions`, `useSessionStatus`, `useSessionRetainInfo`,
+`useWorkspaces`, `useChat`, `useConversation`, `useInput`, `inputActions`, `useSession`, `sessionId`,
+`useProjection`, `useTrajectory`. Shipped occupants: `todo` (order 0), `goal` (10), `queue` (20).
+
+Why this is written down: the bar's Autorun gate was written against a **scalar** `props.running` that no host
+version supplies, so Autorun reported itself unavailable on a host that exposes the very signal through
+`useSessionStatus`/`useChat`. Reading the contract table beats remembering a prop name. `inputActions` here is
+`{ captureInsertion, insertText, setDraft, addAttachments, removeAttachment, pruneAttachments, submit }`, and
+the composer-write limitation in #126 is measured against that same kit.
+
+**The running signal has seats, and the scalar is only one of them (measured 2026-10-31, #194).**
+`SessionSnapshot.running: boolean` (`packages/api/session-controller/src/client/contract/snapshot.ts:69-73`)
+arrives through the dock's standard prop `useSession` — a `MaybeSnapshotSelectorHook<SessionSnapshot>`
+(`useSession((s) => s.running)`), the same seat `ui-session` documents in `SessionStandardProps`.
+Some builds ALSO hand a scalar `running` prop. The shipped dock declared both hook channels
+(`useSessionStatus?`, `useSession?`) and consumed only the scalar — so on a hook-only host the #193
+idle edge never fired and the cadence silently degraded to the conservative 10s-active fallback
+(`props.running ?? true`). Resolution order, locked here: scalar `running` → `useSession((s) =>
+s.running)` → unknown (conservative true, legacy cadence). Conditional invocation of an optional
+hook prop is deliberate: the prop face is fixed per host build, so hook order is stable across
+renders within any one deployment, which is the invariant React actually keeps.
+
+**Push transport (interface lock, #194 — probe-verified on host 0.2.1-rc.5, `spikes/push-probe/FINDINGS.md`).**
+Where the host has `appendPluginRecord` (0.2.1+; absent from 0.2.0-rc.2 — grep-verified on both tags),
+the bar's state rides a plugin record and a projection, and the steady state costs ZERO command runs:
+
+- Record type: `plugin:dsh-chapters/prompt`. Payload = the bar's durable facts, versioned:
+  `{ v: 1, status, text, turnSeq, error, intent, goalRevision, autorun, at }`.
+- Append sites: every durable row write — the runner's `analyzing`/`ready`/`failed`/quiet-`off`
+  transitions (it holds the live session) and the bar-access mutations (`setAutorun`, `setOff`,
+  `setOn`, `runNow`'s consumption), which gain an optional live-session parameter for the purpose.
+- The function comes ONLY from the host's own module instance — `createRequire(process.argv[1])
+  → resolve('@deepseek-ai/dsh-session') → await import(resolved)`. The plugin's OWN copy at the
+  IDENTICAL version throws `Receiver must be an instance of class Session` against a host session
+  (measured), and a bare import from a `link:` install resolves by realpath into the source tree —
+  on a dev machine, into a DIFFERENT host checkout than the running server. No plugin dependency is
+  declared for it; detection is `typeof appendPluginRecord === 'function'`, one try behind try/catch,
+  and any failure marks push unavailable for the process.
+- Projection: key `chaptersPrompt`, registered ONLY when the writer resolved — registration is the
+  feature signal. `apply` folds records last-wins; `wire.view` passes the payload through.
+- Client: the dock reads the standard prop `useProjection('chaptersPrompt')`. A live value renders
+  through the SAME reducer (one fold path); `undefined` ⇒ the #203/#208 pull schedule stands,
+  unchanged — the fallback is the floor. In push mode the only pulls are the bar's own actions and
+  ONE staleness-confirm per idle edge, scheduled at +20s and cancelled when a fresher record arrives
+  (the runner writes `analyzing` within moments of turn/end, so a healthy push cancels every confirm):
+  a silently dead push degrades to one pull per turn, never to a frozen bar.
+- Records are `ignorable: true` with an unknown `plugin:` type — skipped by readers, rendered by
+  nothing; the projection value travels the host's own push channel. Verbs, state block, and the
+  pull schedule below are unchanged and remain the contract for pre-0.2.1 hosts.
+
+**Verbs (interface lock, #113).** `/chapters-prompt` accepts `model …|clear`, `off`, `on`, `state`, `autorun on|off`,
+and **`run`** — submit the offer currently on screen as a **human-authored user turn**, through the same follow-up
+path autorun uses (`agent.followup(suggestPromptMessage(…))`). Run goes through the command plane rather than the
+composer's `inputActions.setDraft` because a dock cannot rely on writing the host editor: measured, `setDraft` is
+accepted and the composer still reads empty, and the goal bar's own `setDraft` is plain React state, not a
+composer write. A plugin's only dependable wire to its own server plane is the command — which is why the bar is
+push-shaped and pull-fed.
+
+**The dock's status hook is a SELECTOR hook (measured, 2026-10-27).** `useSessionStatus` is declared
+`SnapshotSelectorHook<SessionStatusSnapshot>` in `dsh-client-ui-session`'s client types, so it is called as
+`useSessionStatus(selector)` — passing a session id hands the host a string where it wants a function and it
+fails `TypeError: l is not a function`. Two consequences for anyone wiring the bar: the call must be hoisted
+above the component's early `return null` (a hook below that guard changes the hook count and React aborts the
+whole slot, `#310`), and the snapshot's field names are not ours to assume — the dock folds it through
+`deriveRunning`, which maps `boolean`, status words, `{status|state|phase}`, and `{running}`, and returns
+**`undefined` for anything unrecognized**, because `undefined` (unknown) and `false` (idle) are different
+safety answers: unknown must never start a turn.
+
+**State vocabulary (interface lock, #113).** `/chapters-prompt state` reports one of:
+`off` — switched off by the human (a stored override), or no defining model is configured, so the bar renders
+nothing; `idle` — **enabled and awaiting its first recommendation** (no completed turn yet); `analyzing` — a
+generation is in flight for the current turn; `ready` — an offer is on screen with `text`; `failed` — the
+generation could not run, with the reason. `idle` exists because collapsing "nothing yet" into `off` made a
+working feature indistinguishable from a disabled one: measured in the rig, the bar replied
+`suggested next step: off` while the profile row read `model: qwen-token-plan/qwen3.8-flash (config)`.
+The bar stays hidden on `off` only, and re-reads while the state is `idle`/`analyzing`/`ready`.
+ — interface lock (#113, builds on the measured goal-bar facts above)
+
+A composer dock row that, once per **completed turn**, generates a fresh prompt suggestion and offers
+**Run · Autorun · Off**. Modelled on the goal bar because the goal bar is tested and already fits — and the
+mechanical parallel is exact: *a goal re-injects the same directive every turn until the model stops; a
+suggestion re-derives a new directive every turn until the human stops it.*
+
+**Measured anchors for every claim below are in the section above** (dock slot, ordering, anatomy, hiding
+rules, `hooks:` observables, `remote.commands.execute` as the only plugin-reachable call path).
+
+### State, and who owns it
+
+| field | owner | values |
+|---|---|---|
+| `status` | server, persisted per session | `off` \| `analyzing` \| `ready` \| `failed` |
+| `text` | server | the suggestion, verbatim, never truncated (`promptMaxChars` is a **refusal** cap) |
+| `turnSeq` | server | the `turn/end` seq the suggestion was generated **for** — the identity of an offer |
+| `autorun` | **server, process-local** (exactly like the goal's `activation`) | `armed` \| `disarmed` |
+| `expanded` | client, per-mount | `false` collapsed one line · `true` full text shown |
+
+The durable pair (`status`, `turnSeq`) is the server's one-generation-per-turn key; the process-local pair
+(`autorun`, `expanded`) is never persisted — same split the goal bar uses between `goal.phase` and
+`activation`.
+
+**Correction, found while wiring the loop and kept visible because the first version of this table was
+wrong.** `autorun` is *not* client-local: the whole point of the feature is that a suggestion drives the
+next real turn, and a turn is started host-side (`agent.followup`), so the flag has to live where the loop
+does. It is **server-side process-local state**, disarmed on mount and on `agent/created`, re-armed only by
+an explicit human action through the command — the host goal driver's `WeakMap` semantics copied on purpose,
+including the safety property: **a loop cannot resurrect itself after a restart.** `expanded` stays purely
+client-local, because only a browser cares.
+
+### Dock placement
+`conversation.input.dock`, `order: 30` — after todo `0`, goal `10`, queue `20` (ascending sort), so it sits
+**under all other dock entries and directly above the composer card**, which is what "right above the chat
+input" means in this host. It is a docked row, never an overlay, so it cannot cover the placeholder.
+
+### Label and visibility (two fields decide both, as with the goal)
+- `analyzing` → **`Analyzing situation…`**
+- `ready` → **`Recommended Next Step`**
+- `failed` → **`Recommended Next Step`** *plus* an error span (`role="alert"`) naming the reason and code — a
+  detected failure must be a delivered failure (#61); nothing is silently blank.
+- `off`, or a **quiet** refusal (nothing to recommend yet) → renders **nothing**. A refusal is not an error,
+  and shouting it was defect #2 of the removed ghost.
+- Also renders nothing while the session zone is absent, and keeps a just-turned-off guard so it cannot
+  flicker back before the server state catches up (the goal's `clearedGoalId` trick).
+
+### Interactions
+1. **Click the prompt (collapsed)** → expand; full text shown in the same strip.
+2. **Click the prompt (expanded)** → `inputActions.setDraft(text)`: the draft is *replaced*, editable, and
+   nothing is sent. No `Edit`-button fallback unless a browser pass proves the click is captured by the host
+   editor — and if so the fallback is the goal's inline swap, which is already the house pattern.
+3. **Run** → `setDraft(text)` then `submit()`, in that order, so what goes out is visible in the composer
+   first and lands in the durable log as an ordinary **human** message.
+4. **Autorun / Autorun off** → toggles the process-local `armed`/`disarmed`. While armed, after each
+   completed turn the bar pulls, and on `ready` performs the Run path by itself.
+5. **Off** → server `status: 'off'`; generation stops, the row disappears, the configured model is kept so
+   turning it back on is one click.
+
+### Goal composition (per the maintainer's spec, which corrects my first plan)
+Autorun **runs alongside** an active goal — it does not stand aside. The suggested prompt is always generated
+*with the goal in view*: the server reads the newest `goal/change` from the session and feeds the live
+objective into the recommendation, with the directive that the next step must advance an active goal.
+**When the goal completes (or is cleared/paused out of `active`), autorun disarms itself** — the suggestion
+loop yields the stage back to the human at the moment the purpose it was serving is finished. A human prompt
+also disarms autorun, while generation continues on later turn boundaries; re-arming is a human act.
+
+### Enabling
+`promptModel` remains the single switch (empty ⇒ no bar, no calls, no cost) — the model *is* the enable.
+`promptAutorunDefault` (bool, **false**) decides only whether a fresh session starts armed; nothing autoruns
+that a human did not opt into.
+
+### Where the goal's loop actually lives, and what that changes for us (measured 2026-10-25)
+
+The second probe corrected two things I had assumed, and one thing I had written:
+
+- **The goal loop has no timer.** `dsh-goal-round-driver` chains turns off `agent/status === "idle"` and
+  `goal/changed`, coalesced into one serialized task per agent, and starts the next turn with
+  `agent.followup(createUserMessage({…, source:{kind:'goal', goalId, revision, round}}))`. It stops **silently**
+  unless `phase === "active" && activation === "armed"`.
+- **`activation` is process-local and starts disarmed.** On mount the driver disarms every agent, and
+  `agent/created` disarms new ones; only a human `ctx.goals.resume` re-arms. A loop cannot survive a restart
+  on its own.
+- **A plugin may read the goal through the host, not just the log**: `ctx.get('goals').get(agent)` → `GoalView`
+  (adds `roundsStarted` + `activation`), or `ctx.sessionProjections.stateOf(session, 'goal')`. `readActiveGoal`
+  remains for log-only paths (repair, distill, tests).
+- **Trap that governs our authorship**: two invariant companions re-fold the goal stream and
+  `deepEqual`-check every `source.kind:'goal'` message against the package-owned `<goal_round>` template. So
+  **we never author as `goal`** — impersonating that kind is a loud invariant failure by design.
+
+**Decision this forces (and the one I'm making, since it is a semantics choice, not a style one).** Run and
+Autorun are different acts and must not share a mechanism:
+
+| control | mechanism | durable effect | survives a closed tab? |
+|---|---|---|---|
+| **Run** (a button the human pressed) | client `setDraft` + `submit` | an ordinary **human** `user/message` (`source.kind:'user'`) | no — and correctly so |
+| **Autorun** (a loop the human opted into) | server-side `agent.followup(...)` with our **own** producer kind `plugin:dsh-chapters` | a plugin-authored message, screened like a notice, never counted as human input | the loop itself is process-local and **disarms on restart**, mirroring the goal |
+
+That split is what makes it goal-shaped *and* honest: the suggestion reaches the model with the session's full
+tool capability (it is a real turn, not a browser trick), while nothing we generate can masquerade as the
+human typing it. Autorun defaulting off, and being off after any restart, is a safety property inherited from
+the goal driver rather than a limitation to apologize for.
+
+### Goal ↔ suggestion authority and precedence — measured 2026-10-25, host 0.2.0-rc.2
+
+Read this before touching either loop. The two features start turns, and the host reserves *some* turns for
+humans. Facts, with anchors in `dsh-tool-goal/lib/index.js`:
+
+- **`hasDirectHumanInput(ctx, execution)`** = the agent is a runtime root **and** the open turn contains
+  `user/message` with `data.source.kind === 'user'` (:49-52). **`requireDirectHuman`** (:62-65) gates goal
+  `create`/`edit`/`pause`/`resume` — a model cannot re-cut a goal without a human turn in progress.
+- **`isMatchingGoalRound`** (:54-56) additionally grants *completion* authority to the exact admitted goal
+  round (`source.kind === 'goal'` with matching `goalId/revision/round`), so the worker may close the goal it
+  was handed — but not re-author it.
+
+Consequences for this plugin, in order of how much they matter:
+
+1. **A `Run`n suggestion is a human turn, so it CAN re-cut the goal.** The composer's `setDraft`+`submit`
+   produces `source.kind: 'user'`. This is the director path the maintainer is building: the big model writes
+   *"edit the goal to X, because step 2 of the plan showed Y"*, the human presses Run, and the worker now has
+   authority to edit the goal. Nothing about our authorship needs to change for this to work.
+2. **An autorun suggestion is NOT a human turn, so it MUST NOT try to edit the goal.** Our loop authors under
+   `plugin:dsh-chapters` (see above: faking `kind:'user'` here would be a privilege escalation — it would hand
+   an automated loop the authority the host deliberately reserves). So the host's refusal is the correct
+   behaviour, and the feature must respect it rather than route around it.
+3. **Therefore an offer carries an intent, and intent decides whether autorun may act on it.** The suggestion
+   model prefixes its answer: `GOAL:` = this step changes the standing objective → **never auto-run**; the bar
+   holds it for the human's keystroke and says why. Anything else = a worker step → auto-run is allowed.
+   The prefix is stripped before the prompt reaches the composer or the followup, so the worker never sees
+   protocol scaffolding.
+4. **Exactly one thing may start a turn at a boundary.** The host goal driver queues a round on
+   `agent/status === 'idle'` when `phase === 'active' && activation === 'armed'`. If our loop also followed
+   up, the session would start two turns per idle edge — a race against the driver's own reservation fence.
+   So when the service reports the goal `active` **and** `armed`, the suggestion loop **yields**: it keeps
+   generating offers (that is the director's eye on the work) and runs none of them. It runs again when the
+   goal is `paused`, `blocked`, `complete`, disarmed, or absent.
+   Activation is process-local and reachable only through the service (`ctx.get('goals').get(agent)` →
+   `GoalView.activation`), never from the log — that read is the point, not a convenience.
+5. **A goal edit invalidates the offer made under the old revision.** `revision` bumps exactly +1 per
+   accepted mutation, so the loop compares the revision it generated against and refuses to run a stale one
+   instead of pushing last cycle's directive into a re-cut objective.
+
+This is the shape of the pair: the **goal** is the thing the human owns and re-cuts, the **suggestion** is the
+thing the director model re-derives every turn. Autorun drives the worker; the keystroke drives the objective.
+
+### Displacement, not yielding — the maintainer's rule for two autoruns in one session (2026-10-25)
+
+My first pass had the suggestion loop **yield** whenever a goal was `active`+`armed`. That was wrong against
+the spec: *"the autorun for the suggested prompt … can either introduce or **replace** the autorun by the goal
+if it is running."* Yielding made the two features mutually exclusive, which is the opposite of built for each
+other — with a goal armed, a director's autorun would have quietly done nothing at all.
+
+The rule now: **arming prompt autorun displaces the goal's continuation, and the suggestion carries the goal.**
+- Mechanism: `GoalService.disarm(agent)` (`dsh-goal/lib/index.js:622-627`) — *"without changing durable goal
+  phase or revision"*, a later human-authorized `resume` records the new activation edge. That is precisely a
+  cooperative brake: the objective stays authoritative in the log, the driver simply stops re-injecting it, so
+  **exactly one loop starts a turn** at each boundary, and it is whichever the human armed last.
+- The goal is not lost by being disarmed: every suggestion is generated *from* `goal/change` (objective +
+  revision) and the directive still says the next step must advance it. The director's words replace the host's
+  repeated round; the objective is unchanged.
+- If `disarm` is unavailable (no `goals` service on this host) arming still succeeds, and the loop yields the
+  turn — so a missing seam degrades to the safe behaviour rather than double-firing.
+- Re-arming the goal (`/goal resume`, or the bar's next human Run of a `GOAL:` step) is a human act, matching
+  the host's own rule that a model may not resume a paused goal (`GOAL_TOOL_RESUME_PAUSED`).