@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.20

package/lib/index.js

@@ -0,0 +1,1162 @@
+/**
+ * dsh-chapters — cordis entry point (host plane). The ONLY host-facing function
+ * plugin; engine logic lives in engine.ts (mounted per preset realm), every
+ * decision in the pure modules (docs/development.md § L0).
+ *
+ * Responsibilities:
+ *  1. Make the `chapters` preset EXIST in the host's preset roster, and say loudly
+ *     when it does not. Hosts before 0.2.0 are NOT supported: a preset is an
+ *     `@deepseek-ai/dsh-agent-preset` declaration row, and this plugin registers
+ *     that row at activation through the host's own `agentPresets.register()`
+ *     (`src/preset.ts`). The old `$DSH_HOME/.agent-presets/` directory copy is
+ *     gone — no 0.2.x host reads it, and shipping the row as a patch layer instead
+ *     breaks the boot of every pre-0.1.7 host (measured; docs/contract.md).
+ *  2. Open the dsh_chapters storage domain and register chapters_segment /
+ *     chapters_continue (src/tools.ts adapts them to the pure core).
+ *  3. Witness/dev diagnostics.
+ *
+ * Protocol notes (each measured, docs/contract.md):
+ *  - function plugin: named exports `name` / `inject` / `Config` / `apply`;
+ *    NO default export (mixing forms makes the Loader discard the namespace).
+ *  - Config uses schemastery (default import) — plain specs are for tool
+ *    parameters, zod for domain records; never mix.
+ */
+import { writeFileSync, readFileSync } from 'node:fs';
+import { dirname, join, isAbsolute } from 'node:path';
+import { hostname } from 'node:os';
+import { fileURLToPath } from 'node:url';
+import Schema from '@deepseek-ai/schemastery';
+import { appendChapters, reserve } from "./registry.js";
+import { acquireChapterStore, makeDomainStore, resolveStoreRoot } from "./store.js";
+import { registerChaptersTools } from "./tools.js";
+import { CHAPTERS_PRESET_ID, inventoryEntry, unusableRows } from "./preset.js";
+import { registerHostCommands } from "./commands.js";
+import { wireSubagentAutoSave } from "./auto-save.js";
+import { createEnrichWiring } from "./enrich-wire.js";
+import { ENRICH_MAX_TOKENS_DEFAULT } from "./enrich.js";
+import { carryActivePlan } from "./plans.js";
+import { buildRulesSection } from "./rules.js";
+import { createPromptSurface, promptChaptersForLineage, PROMPT_SETTING_KEY } from "./prompt.js";
+import { makePromptLoop, suggestPromptMessage } from "./prompt-loop.js";
+import { makePromptRoundRunner } from "./prompt-runner.js";
+import { resolvePushWriter, promptProjectionDefinition, promptRecordPayload } from "./prompt-push.js";
+import { classifyOffer, goalDirectiveOf, noSuggestion, readActiveGoal } from "./prompt-state.js";
+import { rulesCommand } from "./rules-commands.js";
+import { ancestorSessionIds, captureMinedRules, makeHeaderParentReader, ruleAncestorSet } from "./session-rules.js";
+import { configureDiagnostics, configureDiagnosticsCap, diagnosticStatusLine } from "./diag.js";
+import { BlockAssembler } from '@deepseek-ai/dsh-llm';
+import { auxPromptMessage } from "./aux-message.js";
+import { createSyncScheduler, makeCollectionsReader, projectForCwd, readToken, DEFAULT_CLONE_DIR } from "./sync.js";
+import { removedGuard } from "./removal.js";
+import { parseKnowledgeRemote, projectKeyForTarget, resolveProject } from "./repo.js";
+import { providerKindFor, registerProvider } from "./provider.js";
+import { createTreedxProvider } from "./treedx/provider.js";
+export const Config = Schema.object({
+    // The preset is how the engine reaches real sessions (preset realm mount);
+    // turning this off means opting into manual preset authoring instead.
+    // Accepted-then-ignored, deliberately: removing a key would make an old profile patch
+    // fail to PARSE, and a bundle that will not mount is worse than a key that does nothing.
+    installChaptersPreset: Schema.boolean().default(true),
+    // The engine row of the registered preset (docs/host-compaction-seam.md). This is the
+    // one row config that used to live in a preset YAML a human edited in the home; with
+    // the row registered from code it belongs to THIS config, so a profile patch retunes it.
+    compactionThresholdRatio: Schema.number().default(0.9),
+    artifactStoreRoot: Schema.string().default('.dsh-chapters'),
+    // #85: pool-mirror root for rules/knowledge reads that produce model-visible text.
+    knowledgeMirrorDir: Schema.string().default('.dsh-knowledge'),
+    // Lines of the chapter index a continuation notice lists. 0 = list every chapter (the historical behavior).
+    // A small cap keeps the notice's SIZE settled, which is what makes a leg parked on the compaction boundary
+    // reproducible as a tape; the omission is stated in the notice itself, never silent (#56).
+    noticeIndexCap: Schema.number().step(1).min(0).default(6),
+    // #87: the newest human turn carried verbatim into a relief summary, capped.
+    openRequestCarryMaxChars: Schema.number().step(1).min(200).default(4000),
+    // #78 A: survivability switch, default on (docs/host-compaction-seam.md).
+    lastResortArtifact: Schema.boolean().default(true),
+    chapterTokenTarget: Schema.number().default(8000),
+    toolResultDeferFloorTokens: Schema.number().default(200),
+    // Share of the window REMAINING after the header bound — never of the
+    // whole window (docs/architecture.md § Budgets).
+    continuationBudgetRatio: Schema.number().default(0.25),
+    fallbackPreset: Schema.string().default('chapters'),
+    // Topic-sequential composition (record §4.2) for the model-free fork path.
+    mergeThreshold: Schema.number().default(0.3),
+    subagentAutoSave: Schema.boolean().default(true),
+    chapterLimit: Schema.number().default(8000),
+    chapterOversizeFactor: Schema.number().default(2),
+    warningsDisplayCap: Schema.number().default(6),
+    segmentCandidateCapTokens: Schema.number().default(4000),
+    diagnosticsLog: Schema.string().default(''),
+    diagnosticsMaxBytes: Schema.number().step(1).min(0).default(8388608),
+    // Plans (docs/plans-carriage.md § 7). A plan's full text is ALWAYS
+    // artifact-backed, so planInlineChars is display economy and never a data
+    // decision. callArgArtifactTokens defaults to 0 = OFF: turning it on changes
+    // chapter bytes for sessions with large tool-call arguments (a `write` call
+    // carries a whole file), which means model tapes must be re-recorded — so a
+    // deployment opts in deliberately rather than by accident.
+    planInlineChars: Schema.number().default(900),
+    callArgArtifactTokens: Schema.number().default(0),
+    // Renders zero bytes when the path holds no plans, so the default-on cost for
+    // sessions that never enter plan mode is exactly nothing.
+    plansInNotice: Schema.boolean().default(true),
+    retrievalHints: Schema.boolean().default(true),
+    // Seeding is measured-safe (kernel accepts the two-event seed and the host's own
+    // plan projection folds it to active) and it is what keeps the agent anchored to
+    // the task across a continuation — so it ships ON, for continuations only.
+    planSeedMode: Schema.boolean().default(true),
+    plansInCheckpoint: Schema.boolean().default(true),
+    planCheckpointChars: Schema.number().default(1600),
+    // Per-machine identity for the knowledge repo (commit author + per-harness
+    // token scoping, record §2.1). The hostname is the honest default; override
+    // per machine when two sessions on one box must be told apart.
+    harnessId: Schema.string().default(hostname()),
+    // Knowledge repo (record §12): '' leaves linking to /chapters-link; a URL
+    // auto-links every workspace on its first archive event.
+    knowledgeRemote: Schema.string().default(''),
+    projectKeyOverride: Schema.string().default(''),
+    syncDebounceMs: Schema.number().default(30000),
+    searchDefaultMaxTokens: Schema.number().default(400),
+    enrichmentEnabled: Schema.boolean().default(true),
+    enrichmentModel: Schema.string().default(''),
+    enrichmentIdleMs: Schema.number().default(60000),
+    enrichmentMaxTokens: Schema.number().default(ENRICH_MAX_TOKENS_DEFAULT),
+    enrichmentBatchCap: Schema.number().default(5),
+    vocabApply: Schema.boolean().default(false),
+    vocabCoMin: Schema.number().default(3),
+    vocabOverlapMin: Schema.number().default(0.5),
+    coreRulesBudgetTokens: Schema.number().default(1200),
+    rulesCoreBonus: Schema.number().default(0.15),
+    // #50 §7.3–§7.5: the session tier + per-tier display caps. The three the
+    // checkpoint also needs are mirrored into the engine row (docs/configuration).
+    sessionRulesEnabled: Schema.boolean().default(true),
+    rulesMarkerPrefix: Schema.string().default('ADD RULE:'),
+    projectRulesDisplayCap: Schema.number().default(12),
+    sessionRulesDisplayCap: Schema.number().default(12),
+    rulesRelevance: Schema.boolean().default(true),
+    rulesEnrichment: Schema.boolean().default(true),
+    rulesMinedPerChapter: Schema.number().default(3),
+    rulesAutoActivate: Schema.boolean().default(true),
+    rulesModel: Schema.string().default(''),
+    // #71 prompt recommendations: the model IS the switch (empty ⇒ off); the two
+    // caps bound the auxiliary call's input slice and its answer. The completion
+    // rides the existing enrichmentMaxTokens budget — one auxiliary budget, now
+    // three consumers (annotation, mined rules, recommendations).
+    promptModel: Schema.string().default(''),
+    // #188: the caps belong to the model. contextChars is now the NO-WINDOW FALLBACK — when the prompt
+    // model is set through /chapters-prompt model, the budget derives from its real context window
+    // (window × promptContextRatio at 4 chars/token); 32000 keeps a 32K-class model whole when no
+    // window resolves. maxChars rises 240 → 4096: a cap that cannot carry a paragraph cannot carry an
+    // instruction (the maintainer's number, 2026-10-30).
+    promptContextChars: Schema.number().default(32000),
+    promptMaxChars: Schema.number().default(4096),
+    promptContextRatio: Schema.number().default(0.5),
+    // #229: the ambient heartbeat is OFF by default — "never repeated chapters-prompt executions" is
+    // the user's absolute rule, and every pull is two visible history nodes on every host so far.
+    promptQuietHeartbeatSec: Schema.number().default(0),
+    promptMaxRounds: Schema.number().default(24),
+    /** #117: how many lines a `/chapters-repair` report may print. The finding COUNT always leads; */
+    repairReportMaxLines: Schema.number().default(60),
+    // enum-style string (same register as `fallbackPreset`): 'auto' | 'git' |
+    // 'treedx', validated at use — schemastery has no literal schema.
+    knowledgeProvider: Schema.string().default('auto'),
+    treedxFetchTimeoutMs: Schema.number().default(15000),
+    treedxWorkspaceTtlSeconds: Schema.number().default(900),
+    treedxLeaseRetries: Schema.number().default(3),
+    treedxLeaseRetryDelayMs: Schema.number().default(1000),
+    // CodeGraph integration: auto-detect by default. The CLI is probed lazily
+    // at first use; if absent, every integration point is a silent no-op.
+    codegraphEnabled: Schema.boolean().default(true),
+    codegraphEnrich: Schema.boolean().default(true),
+    codegraphSearchBonus: Schema.number().default(0.2),
+});
+export const name = '@fractalsynapse/dsh-chapters';
+export const inject = ['storageDomain', 'tools', 'agents', 'llm', 'sessionProjections'];
+const HERE = dirname(fileURLToPath(import.meta.url));
+const PKG_ROOT = join(HERE, '..');
+/** Registrations this module owns for the life of the process. The registry hands back an
+ *  unregister disposer, and holding it — never calling it — is the point: a disposer wired
+ *  through `ctx.effect` runs when the apply fiber's activation completes, which un-registered
+ *  the preset the instant it had been registered (measured: `register()` reported success
+ *  while the roster came back without `chapters`). The same apply-fiber trap bit the storage
+ *  domain in r35. */
+const heldDisposers = [];
+export async function apply(ctx, config) {
+    // #61: the diagnostics sink defaults ON. An operator who set `diagnosticsLog` in the profile gets
+    // that path; `DSH_CHAPTERS_ENGINE_ERRORS` beats it; the literal `off` is the only silence. With
+    // neither set, the FIRST door that touches a project resolves `<store-root>/diagnostics.log`
+    // (ensureDiagnosticsDefault in tools/engine), which is why nothing is configured here yet — the
+    // three SAIP compaction finalization failures left no trace precisely because the sink had to be
+    // turned on before it could help.
+    if (config.diagnosticsLog !== '')
+        configureDiagnostics(config.diagnosticsLog);
+    configureDiagnosticsCap(config.diagnosticsMaxBytes);
+    // § Preset delivery lives in `src/preset.ts` — the `preset-chapters` declaration row in
+    // this bundle's patch, NOT here. A row is visible (`dsh --dump-default-config`, the config
+    // editor, `list_plugins`), overridable and disable-able from a profile patch, and its
+    // registration's lifetime belongs to Cordis rather than to our `apply()` fiber. What stays
+    // here is only the VERIFICATION: whether the roster ends up holding the preset at all
+    // (below), because declaring it and having it usable are different facts.
+    let domain;
+    try {
+        const storageDomain = ctx.get?.('storageDomain');
+        if (storageDomain === undefined)
+            throw new Error('storageDomain absent');
+        const handle = await acquireChapterStore(storageDomain);
+        domain = handle.domain;
+        const store = handle.store;
+        // No close effect here: the facility's own disposer closes domains still
+        // open at facility unmount (its documented teardown), and a close effect
+        // on the apply fiber fires when THAT fiber is disposed — mid-run, which
+        // closed the domain under later commands (r35 caught it). One opener, and
+        // the closer is the facility's unmount, not our fiber.
+        void handle.owner;
+        // §15 amendment: the TreeDX transport, configured and registered in THIS
+        // module instance (host plane). The realm engine registers its own copy
+        // (separate module instances under isolation) — same code, per-plane.
+        registerProvider(createTreedxProvider({
+            fetchTimeoutMs: config.treedxFetchTimeoutMs,
+            workspaceTtlSeconds: config.treedxWorkspaceTtlSeconds,
+            leaseRetries: config.treedxLeaseRetries,
+            leaseRetryDelayMs: config.treedxLeaseRetryDelayMs,
+        }));
+        // P2: host-plane enrichment wiring — command surface + status only
+        // (trigger forced manual; the realm engine owns auto drains).
+        // The routed model of the last real tool-carrying session on this plane:
+        // the host has no live agent, so without this a fork-only flow (never any
+        // in-place compaction => realm never captures lastRoute) leaves
+        // /chapters-enrich run with no route to call. Persisted immediately so
+        // the realm's resolver sees it via the shared settings table too.
+        let hostRoute = null;
+        const enrich = createEnrichWiring({
+            store,
+            cwd: () => undefined,
+            config: {
+                enabled: config.enrichmentEnabled,
+                model: config.enrichmentModel,
+                trigger: 'manual',
+                idleMs: config.enrichmentIdleMs,
+                maxTokens: config.enrichmentMaxTokens,
+                batchCap: config.enrichmentBatchCap,
+                mineRules: config.rulesEnrichment,
+                mineCap: config.rulesMinedPerChapter,
+                rulesAutoActivate: config.rulesAutoActivate,
+                rulesModel: config.rulesModel,
+            },
+            // §7.5 host-plane sink: `/chapters-enrich run` drains here, so a manual run
+            // mines exactly like the realm's auto pass. Local files only — nothing is
+            // armed on the scheduler, because session rules never travel (§7.5).
+            onMinedRules: async ({ cwd, sessionId, chapterNumber, humanText, rules, max, autoActivate }) => {
+                const res = captureMinedRules({
+                    storeDir: resolveStoreRoot(cwd, config.artifactStoreRoot),
+                    harnessId: config.harnessId,
+                    sessionId,
+                    records: store.rules(),
+                    humanText,
+                    rules,
+                    maxPerChapter: max,
+                    chapterNumber,
+                    autoActivate,
+                });
+                return { written: res.ids.length, stated: res.stated, inferred: res.inferred, pending: res.pending };
+            },
+            fetch: async (prompt, route) => {
+                if (route === null)
+                    throw new Error('no enrichment route resolvable (set /chapters-enrich model … or run a turn first)');
+                const llm = ctx.llm;
+                if (llm?.stream === undefined)
+                    throw new Error('llm.stream absent');
+                const assembler = new BlockAssembler();
+                for await (const chunk of llm.stream({
+                    provider: route.provider, model: route.model,
+                    messages: [auxPromptMessage(prompt)],
+                    maxTokens: config.enrichmentMaxTokens,
+                    purpose: 'compaction',
+                }))
+                    assembler.push(chunk);
+                return assembler.blocks().filter((b) => b.type === 'text').map((b) => b.text ?? '').join('');
+            },
+            conversationRoute: () => hostRoute,
+            log: (m) => ctx.logger?.info?.(`dsh-chapters: ${m}`),
+            warn: (m) => ctx.logger?.warn?.(`dsh-chapters: ${m}`),
+        });
+        // #71: prompt recommendations, host plane only (the web composer pulls;
+        // headless sessions have no ghost and never pay the call). The route for a
+        // bare model name rides the same last-seen route enrichment uses, with the
+        // persisted route as fallback — a fork-only flow that never compacted in
+        // place still has a provider to route through after one tool call.
+        /** Pull the host's own failure text out of a `finish` chunk whose reason kind is `error`. */
+        function hostStreamFailure(chunks) {
+            for (const raw of chunks) {
+                try {
+                    const j = JSON.parse(raw);
+                    if (j.type === 'finish' && j.reason?.kind === 'error') {
+                        const msg = j.reason.failure?.message ?? 'the host reported an error without a message';
+                        return `host llm.stream failed: ${msg.replace(/\s+/g, ' ').slice(0, 300)}`;
+                    }
+                }
+                catch { /* truncated probe slice, not an error signal */ }
+            }
+            return null;
+        }
+        const prompt = createPromptSurface({
+            getSetting: (k) => store.getSetting(k),
+            putSetting: (k, v) => store.putSetting(k, v),
+            deleteSetting: (k) => store.deleteSetting(k),
+            // #188: the ANCESTOR PATH's chapters with plots, not the live row alone — a continuation
+            // mid-goal inherits its lineage's trajectory. Bodies are read from the archive itself
+            // (deterministic, zero model tokens); an unreadable body degrades to no plots, never to an
+            // assembly failure.
+            chaptersOf: async (session) => {
+                const rows = [];
+                const seen = new Set();
+                let cur = session.id;
+                while (cur !== null && !seen.has(cur)) {
+                    seen.add(cur);
+                    const row = await store.get(cur);
+                    if (row === undefined)
+                        break;
+                    rows.unshift(row);
+                    cur = row.parentSession;
+                }
+                const cwd = session.cwd ?? '';
+                return promptChaptersForLineage({
+                    rows,
+                    readBody: (rel) => {
+                        try {
+                            return readFileSync(isAbsolute(rel) ? rel : join(cwd, rel), 'utf8');
+                        }
+                        catch {
+                            return null;
+                        }
+                    },
+                });
+            },
+            // #188: the caps derive from the selected model's REAL window; null falls back to config loudly.
+            resolveWindow: async (route) => {
+                const info = await ctx.llm?.resolveModelInfo(route.provider, route.model).catch(() => undefined);
+                return info?.context?.contextWindow ?? null;
+            },
+            // #188: the standing orders a rebuilt head would render — the SAME builder and budget, so the
+            // director and the worker can never operate under different rule sets. A degraded rules read
+            // degrades the suggestion (empty section); it never fails the assembly.
+            rulesOf: async (session) => {
+                try {
+                    const cwd = session.cwd ?? '';
+                    if (cwd === '')
+                        return '';
+                    const project = projectForCwd(store.projects(), cwd);
+                    if (project === undefined)
+                        return '';
+                    const walk = await ruleAncestorSet({
+                        seeds: [session.id],
+                        registryAncestors: async (sid) => await ancestorSessionIds(async (x) => await store.get(x), sid),
+                    });
+                    const built = buildRulesSection(join(cwd, DEFAULT_CLONE_DIR), {
+                        projectKey: project.projectKey,
+                        harnessId: config.harnessId,
+                        budgetTokens: config.coreRulesBudgetTokens,
+                        storeDir: resolveStoreRoot(cwd, config.artifactStoreRoot),
+                        ancestorSessions: walk.ancestors,
+                    });
+                    return 'text' in built ? built.text : '';
+                }
+                catch {
+                    return '';
+                }
+            },
+            // #188: the operative plan via the SAME carry mechanism continuations seed with, budgeted at the
+            // context cap — its own announced clip (which names the archive chapter citing the full text)
+            // fires only if the plan alone would eat the entire budget.
+            planOf: async (session) => {
+                try {
+                    const row = await store.get(session.id);
+                    const docs = (row?.planDocs ?? []);
+                    return carryActivePlan(docs, { maxChars: config.promptContextChars }) ?? '';
+                }
+                catch {
+                    return '';
+                }
+            },
+            config: {
+                model: config.promptModel,
+                contextChars: config.promptContextChars,
+                maxChars: config.promptMaxChars,
+                contextRatio: config.promptContextRatio,
+            },
+            conversationRoute: () => {
+                if (hostRoute !== null)
+                    return hostRoute;
+                const persisted = store.getSetting('enrichment.route') ?? '';
+                const i = persisted.indexOf('/');
+                return i > 0 ? { provider: persisted.slice(0, i), model: persisted.slice(i + 1) } : null;
+            },
+            fetch: async (input, route) => {
+                const llm = ctx.llm;
+                if (llm?.stream === undefined)
+                    throw new Error('llm.stream absent');
+                const assembler = new BlockAssembler();
+                const seen = [];
+                const lastChunk = [];
+                for await (const chunk of llm.stream({
+                    provider: route.provider, model: route.model,
+                    messages: [auxPromptMessage(input)],
+                    maxTokens: config.enrichmentMaxTokens,
+                    purpose: 'compaction',
+                })) {
+                    // Measured, not assumed: the fold below keeps only `type === 'text'` blocks, and the bar said
+                    // "the model returned no text" on a route that returns text when called directly — so the shapes the
+                    // host stream hands us are exactly what had to be seen.
+                    lastChunk.push(JSON.stringify(chunk).slice(0, 120));
+                    const c = chunk;
+                    seen.push(`${String(c.type ?? '?')}:${String(c.content?.type ?? c.text ?? c.delta?.text ?? '').slice(0, 10)}`);
+                    assembler.push(chunk);
+                }
+                // #61: the host already told us what went wrong, inside the stream. Before this, a provider with no
+                // adapter, a refused request, and an empty completion all arrived here as "the model returned no text"
+                // — the detected failure was thrown away and a stranger diagnosis took its place. Now the FIRST real
+                // failure is what the surface reports.
+                const failure = hostStreamFailure(lastChunk);
+                if (failure !== null)
+                    throw new Error(failure);
+                return assembler.blocks().filter((b) => b.type === 'text').map((b) => b.text ?? '').join('');
+            },
+            warn: (m) => ctx.logger?.warn?.(`dsh-chapters: ${m}`),
+        });
+        // #113: the Suggested Next Step bar's server-side state. ONE instance, built here, because it is the
+        // only place that has the store, the model switch, and the live agents at once — and a loop that starts
+        // real turns must not have two copies of "is it armed" to disagree about. `autorun` is process-local on
+        // purpose: like the host goal driver's activation, it starts disarmed and cannot resurrect itself after a
+        // restart, so an unattended loop is impossible by construction rather than by promise.
+        // ONE path from "run this suggestion" to a human-authored turn. Autorun calls it from the idle edge; the
+        // bar's Run calls it from the command plane. Two implementations of "run it" would be two behaviors, and
+        // only one of them is the one the human clicks.
+        const submitOffer = (sessionId, text) => {
+            const agents = ctx.agents;
+            const agent = agents?.get?.(sessionId);
+            if (agent?.followup === undefined)
+                throw new Error(`no live agent for ${String(sessionId)}`);
+            agent.followup(suggestPromptMessage(text, sessionId));
+        };
+        const promptLoop = makePromptLoop({
+            followup: submitOffer,
+            maxRounds: () => config.promptMaxRounds,
+            // The host's cooperative brake: `GoalService.disarm` stops the driver re-injecting rounds and changes
+            // NOTHING durable ("without changing durable goal phase or revision"), so the objective stays
+            // authoritative while exactly one loop — the one the human armed last — starts the next turn.
+            displaceGoal: (sessionId) => {
+                try {
+                    const goals = (typeof ctx.get === 'function' ? ctx.get('goals') : undefined);
+                    const agents = ctx.agents;
+                    const agent = agents?.get?.(sessionId);
+                    if (goals?.disarm === undefined || agent === undefined)
+                        return false;
+                    goals.disarm(agent);
+                    return true;
+                }
+                catch {
+                    return false;
+                }
+            },
+            // The goal signal comes from the SERVICE, never folded from the log: `activation` is process-local by
+            // design (dsh-goal keeps it in a WeakMap), so the only honest read is the live GoalView. This is what
+            // lets the loop know when the driver owns the next turn.
+            goalSignal: (sessionId) => {
+                try {
+                    const goals = (typeof ctx.get === 'function' ? ctx.get('goals') : undefined);
+                    const agents = ctx.agents;
+                    const agent = agents?.get?.(sessionId);
+                    if (goals === undefined || agent === undefined)
+                        return null;
+                    const view = goals.get?.(agent);
+                    if (view === undefined || typeof view.revision !== 'number')
+                        return null;
+                    const phase = view.phase === 'paused' ? 'paused' : view.phase === 'blocked' ? 'blocked' : view.phase === 'complete' ? 'complete' : 'active';
+                    return { phase, activation: view.activation === 'armed' ? 'armed' : 'disarmed', revision: view.revision };
+                }
+                catch {
+                    return null;
+                }
+            },
+            log: (m) => ctx.logger?.info?.(`dsh-chapters: ${m}`),
+            warn: (m) => ctx.logger?.warn?.(`dsh-chapters: ${m}`),
+        });
+        // A narrow, explicit view of the registry row for the bar. The surrounding `store` handle is loosely
+        // typed here, and widening a host-facing type to make a call compile is the exact habit this repo has
+        // been bitten by (#58) — so the two verbs the bar needs are named, not assumed.
+        const promptRow = store;
+        // #194: the push transport. The writer resolves against the HOST's own module instance (the
+        // probe-proven recipe — a plugin-side copy throws `Receiver must be an instance of class Session`
+        // even at the identical version), and the projection is registered ONLY when the writer exists:
+        // registration is the feature signal the client reads through its standard `useProjection` seat.
+        // No writer ⇒ no projection ⇒ every client keeps the #203/#208 pull schedule, unchanged.
+        let pushWriter = null;
+        try {
+            pushWriter = await resolvePushWriter({ log: (m) => { console.error(`[chapters-push] ${m}`); ctx.logger?.warn?.(`dsh-chapters: ${m}`); } });
+            if (pushWriter !== null) {
+                const projections = ctx.sessionProjections;
+                if (typeof projections?.register === 'function') {
+                    projections.register(promptProjectionDefinition());
+                    // stderr witness, same discipline as the turn/end door's armed line: ctx.logger.info never
+                    // reaches a boot log a probe can read, and "is push live?" is exactly the question a
+                    // failed proof must answer first (#194).
+                    console.error('[chapters-push] transport LIVE — the bar rides plugin records; zero command runs in steady state');
+                    ctx.logger?.info?.('dsh-chapters: prompt push transport LIVE — the bar rides plugin records; zero command runs in steady state');
+                }
+                else {
+                    pushWriter = null; // no seat to fold records into; the pull floor stands
+                }
+            }
+        }
+        catch (error) {
+            pushWriter = null;
+            ctx.logger?.warn?.(`dsh-chapters: prompt push wiring failed (${String(error?.message ?? error).slice(0, 140)}) — pull transport stands`);
+        }
+        // One serialized push per session: the fold is last-wins, so records must land in mutation
+        // order — a ready that overtakes its own analyzing would show a stale offer as fresh.
+        const pushChains = new Map();
+        // #218: sessions that already carry a birth record this process; a Set, not persistence —
+        // the record itself is durable, and a restarted process re-birthing would append a duplicate
+        // (harmless: the fold is last-wins, but a duplicate is a log write for nothing).
+        const seenBirthSessions = new Set();
+        // #225: sessions whose first-boundary verdict has been printed (per process), and the total
+        // boundaries sighted — the status command prints both. "No suggestion ever" must not be a
+        // silence to interpret; it is a printed verdict per session at its first boundary.
+        const promptVerdictSighted = new Set();
+        let promptBoundariesSighted = 0;
+        const pushBar = (session, sessionId) => {
+            if (pushWriter === null || session === undefined || session === null)
+                return;
+            const writer = pushWriter;
+            const prev = pushChains.get(sessionId) ?? Promise.resolve();
+            const next = prev.then(async () => {
+                const row = (await promptRow.get(sessionId)).promptSuggestion ?? noSuggestion;
+                const live = promptLoop.statusOf(sessionId);
+                writer.append(session, promptRecordPayload({
+                    status: row.status, text: row.text, turnSeq: row.turnSeq, error: row.error,
+                    intent: row.intent, goalRevision: row.goalRevision, autorun: live.autorun, at: row.at,
+                }));
+            }, () => undefined);
+            pushChains.set(sessionId, next.then(() => undefined, () => undefined));
+        };
+        const promptBar = {
+            // #229: the ambient heartbeat is config-gated and defaults to ZERO — the maintainer's rule is
+            // absolute ("never want to see repeated chapters-prompt executions in a session again"), and
+            // the measurement that proved it: exact 60.0s pull gaps on their live log even with 0.2.11
+            // installed correctly. The value rides EVERY state reply (quietHeartbeatSec) so the client's
+            // schedule is the server's setting, not a compile-time guess; the same number lands in the
+            // /chapters-prompt state text for humans.
+            quietHeartbeatSec: config.promptQuietHeartbeatSec,
+            read: async (sessionId) => {
+                const status = (await promptRow.get(sessionId)).promptSuggestion ?? noSuggestion;
+                const live = promptLoop.statusOf(sessionId);
+                return { ...status, ...live };
+            },
+            // #231: the row without the loop — cheap, pure, and the answer to almost every pull. The
+            // maintainer's host pulled once a minute for hours; each of those hit the full read + mirror.
+            peekRow: async (sessionId) => {
+                const ps = (await promptRow.get(sessionId)).promptSuggestion;
+                if (ps === undefined || ps.status === 'off')
+                    return null;
+                const live = promptLoop.statusOf(sessionId);
+                return { ...ps, ...live };
+            },
+            // #218: the state verb calls this after serving a pull — the answer becomes the record the
+            // next mount reads from the projection. Pull-only surfaces never see it called (the caller
+            // feature-checks), so it lives on the same object that owns the push queue.
+            mirror: (sessionId, session) => { pushBar(session, sessionId); },
+            // #113: Run is a command, not a keystroke. The offer is read from the row the bar is displaying and
+            // injected as a human-authored follow-up — the same path autorun uses, so what the human clicks and what
+            // the loop arms cannot be two different behaviors. `no live agent` is the honest failure and reaches the
+            // bar as its reason.
+            runNow: async (sessionId) => {
+                const st = await promptBar.read(sessionId);
+                if (st.text === '' || st.status !== 'ready')
+                    return { ok: false, reason: 'there is no offer on screen to run' };
+                submitOffer(sessionId, st.text);
+                return { ok: true, text: st.text };
+            },
+            setAutorun: (sessionId, on, session) => {
+                const r = promptLoop.setArmed(sessionId, on);
+                pushBar(session, sessionId);
+                return r;
+            },
+            disarmHuman: (sessionId, session) => { promptLoop.disarmForHuman(sessionId); pushBar(session, sessionId); },
+            // `off` stops generation for the session without touching the model, so back-on is one action; `on`
+            // clears it and the NEXT completed turn offers again. Both write through mutate, never a snapshot.
+            setOff: async (sessionId, session) => {
+                promptLoop.setArmed(sessionId, false);
+                await promptRow.mutate(sessionId, ((row) => ({ ...row, promptSuggestion: noSuggestion })));
+                pushBar(session, sessionId);
+            },
+            // #225: the suggest verb's answer becomes the durable offer — same row shape the runner writes
+            // (status ready, this turn's seq unknown for manual suggests ⇒ turnSeq null-safe via Date.now
+            // identity), then the mirror makes it visible without any pull.
+            setSuggested: async (sessionId, text, session) => {
+                promptLoop.setArmed(sessionId, false);
+                await promptRow.mutate(sessionId, ((row) => ({ ...row, promptSuggestion: {
+                        // A manual suggest has no turn boundary of its own; `turnSeq: null` marks it as such — the
+                        // bar renders ready offers regardless, and autorun never fires on a null-turnSeq row (its
+                        // own gate refuses), so a human-requested suggestion can never start a turn by itself.
+                        status: 'ready', text: classifyOffer(text).text, turnSeq: null,
+                        error: '', at: new Date().toISOString(), intent: classifyOffer(text).intent, goalRevision: null,
+                    } })));
+                if (session !== undefined)
+                    pushBar(session, sessionId);
+            },
+            setOn: async (sessionId, session) => {
+                await promptRow.mutate(sessionId, ((row) => ({ ...row, promptSuggestion: noSuggestion })));
+                pushBar(session, sessionId);
+            },
+        };
+        const scheduler = createScheduler(store, domain, config, undefined, (cwd, ok) => {
+            enrich.rememberCwd(cwd);
+            if (ok)
+                enrich.queue.onSyncDone('afterPush');
+        }, (m) => ctx.logger?.warn?.(m));
+        // ONE assembly feeds both planes (#90 drift trap): the doors' ToolsConfig doubles as the
+        // commands' SaveSessionConfig for /chapters-remove restore — a second literal would be a
+        // second truth about thresholds.
+        const toolsConfig = {
+            artifactStoreRoot: config.artifactStoreRoot,
+            chapterTokenTarget: config.chapterTokenTarget,
+            repairReportMaxLines: config.repairReportMaxLines,
+            toolResultDeferFloorTokens: config.toolResultDeferFloorTokens,
+            continuationBudgetRatio: config.continuationBudgetRatio,
+            fallbackPreset: config.fallbackPreset,
+            mergeThreshold: config.mergeThreshold,
+            chapterLimit: config.chapterLimit,
+            chapterOversizeFactor: config.chapterOversizeFactor,
+            warningsDisplayCap: config.warningsDisplayCap,
+            segmentCandidateCapTokens: config.segmentCandidateCapTokens,
+            planInlineChars: config.planInlineChars,
+            callArgArtifactTokens: config.callArgArtifactTokens,
+            plansInNotice: config.plansInNotice,
+            retrievalHints: config.retrievalHints,
+            planSeedMode: config.planSeedMode,
+            searchMaxTokens: config.searchDefaultMaxTokens,
+            harnessId: config.harnessId,
+            coreRulesBudgetTokens: config.coreRulesBudgetTokens,
+            rulesCoreBonus: config.rulesCoreBonus,
+            // #50 §7.4 — the doors read the HOST plane; the compaction checkpoint reads
+            // the realm row (same names, same defaults). There is no cross-plane channel
+            // to inject host config into a preset row, so a profile that overrides a cap
+            // sets it in both places; leaving one unset keeps the documented default.
+            projectRulesDisplayCap: config.projectRulesDisplayCap,
+            sessionRulesDisplayCap: config.sessionRulesDisplayCap,
+            rulesRelevance: config.rulesRelevance,
+            scheduler,
+            noteRoute: (r) => {
+                hostRoute = r;
+                void store.putSetting('enrichment.route', `${r.provider}/${r.model}`).catch(() => undefined);
+            },
+            enrich,
+        };
+        registerChaptersTools(ctx, store, toolsConfig);
+        registerHostCommands(ctx, domain, {
+            artifactStoreRoot: config.artifactStoreRoot,
+            subagentAutoSave: config.subagentAutoSave,
+            harnessId: config.harnessId,
+            projectKeyOverride: config.projectKeyOverride,
+            // #255: /chapters-remove mutates through the plane's OWN store handle (one #59 section),
+            // and its print arms share the repair report cap — one knob, not two.
+            store,
+            reportMaxLines: config.repairReportMaxLines,
+            save: toolsConfig,
+            scheduler,
+            enrich,
+            // #173: discovery surface for the three model settings. The factory re-reads per
+            // invocation — settings mutate underneath (that is what the setters are for) and the
+            // catalog is a host verb, not a snapshot. `llm` is passed only when it really carries
+            // all three catalog verbs: a partial host surface must render as the clean refusal the
+            // pure core gives, never a TypeError mid-render.
+            models: () => {
+                const llm = ctx.llm;
+                const catalog = llm !== undefined
+                    && typeof llm.listProviders === 'function'
+                    && typeof llm.listModels === 'function'
+                    && typeof llm.resolveModelInfo === 'function'
+                    ? llm
+                    : undefined;
+                const setting = (key) => { try {
+                    return store.getSetting(key) ?? '';
+                }
+                catch {
+                    return '';
+                } };
+                const enrichVal = setting('enrichment.model');
+                const rulesVal = setting('rules.model');
+                const promptVal = setting(PROMPT_SETTING_KEY);
+                return {
+                    llm: catalog,
+                    current: {
+                        enrichment: enrichVal !== '' ? { value: enrichVal, source: 'settings' }
+                            : config.enrichmentModel !== '' ? { value: config.enrichmentModel, source: 'config' }
+                                : { value: setting('enrichment.route'), source: 'conversation-route' },
+                        rules: rulesVal !== '' ? { value: rulesVal, source: 'settings' }
+                            : config.rulesModel !== '' ? { value: config.rulesModel, source: 'config' }
+                                : { value: '', source: 'rides-enrichment' },
+                        prompt: promptVal !== '' ? { value: promptVal, source: 'settings' }
+                            : config.promptModel !== '' ? { value: config.promptModel, source: 'config' }
+                                : { value: '', source: 'off' },
+                    },
+                };
+            },
+            prompt: Object.assign({ ...prompt, bar: promptBar }, {
+                // #225: `/chapters-status` answers "why is there no suggestion?" without reading files.
+                planeStatus: () => {
+                    const lines = [];
+                    const { spec, source } = prompt.effective();
+                    lines.push(`Prompt plane: model ${spec !== '' ? `${spec} (${source})` : 'UNSET — the bar is absent (§28)'}`);
+                    lines.push(`  transport: ${pushWriter === null ? 'pull (this host has no appendPluginRecord — state reads are commands)' : 'push LIVE (plugin records; the bar rides the projection)'}`);
+                    lines.push(`  turn/end door: ${String(promptBoundariesSighted)} boundary event(s) sighted this process across ${String(promptVerdictSighted.size)} session(s)`);
+                    return lines;
+                },
+                sessionRow: async (sessionId) => {
+                    try {
+                        const row = await store.get(sessionId);
+                        const ps = row.promptSuggestion;
+                        if (ps === undefined)
+                            return '  this session: NO ROW YET — the runner never persisted a verdict (if the door sighted boundaries above, check server stderr for [chapters-prompt] lines)';
+                        return `  this session: status=${ps.status}, turn=${String(ps.turnSeq ?? '-')}${ps.error !== '' ? `, error=${ps.error.slice(0, 90)}` : ''}, at=${ps.at}`;
+                    }
+                    catch (error) {
+                        return `  this session: row unreadable (${String(error?.message ?? error).slice(0, 80)})`;
+                    }
+                },
+            }),
+            rules: (cwd, args, sessionId) => rulesCommand({
+                cwd: () => cwd,
+                storeRoot: config.artifactStoreRoot,
+                harnessId: config.harnessId,
+                store,
+                projectFor: (c) => projectForCwd(store.projects(), c),
+                mirrorDir: (c) => join(c, DEFAULT_CLONE_DIR),
+                syncNow: async (c) => { try {
+                    await scheduler.run(c, 'rules');
+                }
+                catch { /* status file records it */ } },
+                now: () => new Date(),
+                // #50 §7.5: the session tier activates by ancestry, so the surface needs
+                // the tree the caller is sitting on. No sessionId ⇒ `active` reports the
+                // session tier UNRESOLVED rather than guessing an empty path.
+                // #52: the SAME walk every door renders with — registry links plus the host
+                // header's delegation edge — so `active` can never describe a view the head
+                // will not show. One walk, memoized: two answers about one ancestry is how
+                // a surface starts disagreeing with itself.
+                ...(sessionId !== undefined ? (() => {
+                    const parentOf = makeHeaderParentReader((name) => { try {
+                        return ctx.get?.(name);
+                    }
+                    catch {
+                        return undefined;
+                    } });
+                    let once = null;
+                    const walk = async () => {
+                        if (once === null) {
+                            once = ruleAncestorSet({
+                                seeds: [sessionId],
+                                registryAncestors: async (id) => await ancestorSessionIds(async (s) => await store.get(s), id),
+                                ...(parentOf !== undefined ? { parentOf } : {}),
+                            });
+                        }
+                        return await once;
+                    };
+                    return {
+                        ancestors: async () => (await walk()).ancestors,
+                        ancestryTruncated: async () => (await walk()).truncated,
+                    };
+                })() : {}),
+                // §7.3/§7.4: the SAME numbers the doors render with, so `active` can never
+                // describe a view the head will not show.
+                budgetTokens: config.coreRulesBudgetTokens,
+                projectCap: config.projectRulesDisplayCap,
+                sessionCap: config.sessionRulesDisplayCap,
+                // §7.5: the review surface reads the same activation posture the ladder uses
+                // (so `active` can say whether mined rules govern on arrival), and `model`
+                // sets a dedicated mining model through the shared settings table.
+                autoActivate: config.rulesAutoActivate,
+                settings: {
+                    get: (k) => store.getSetting(k),
+                    put: async (k, v) => { await store.putSetting(k, v); },
+                },
+                // §7.7: ONE bounded call, report-only, reusing the conversation route (and
+                // therefore the conversation's own cached prefix). An explicit exception to
+                // zero-inference in the elicitedPlot family — never a mutation.
+                ask: async (prompt) => {
+                    const route = hostRoute;
+                    if (route === null)
+                        throw new Error('no conversation route yet — run a turn first');
+                    const llm = ctx.llm;
+                    if (llm?.stream === undefined)
+                        throw new Error('llm.stream absent');
+                    const assembler = new BlockAssembler();
+                    for await (const chunk of llm.stream({
+                        provider: route.provider, model: route.model,
+                        messages: [auxPromptMessage(prompt)],
+                        maxTokens: config.enrichmentMaxTokens,
+                        purpose: 'compaction',
+                    }))
+                        assembler.push(chunk);
+                    return assembler.blocks().filter((b) => b.type === 'text').map((b) => b.text ?? '').join('');
+                },
+            }, args),
+        });
+        // Door 5 (issue #47): the fifth archive moment — subagent settlement. The
+        // host publishes `subagent/end` for every settled child run (one-shot AND
+        // each residency epoch of a continuable child); the wiring reads the live
+        // child synchronously (end strictly precedes disposal — measured, spike #47)
+        // with a durable sessionQuery fallback, gates on the header the HOST stamps
+        // (`origin: subagent`, `agentPreset`), and archives through the SAME
+        // saveSession core as /chapters-save. Enrichment is never run per child.
+        // Save-only: creates no session, so the "no continuation-creating actions
+        // mid-step" rule is not engaged; a settled child's turns are all completed
+        // by construction, and the anchor is its last `turn/end`.
+        if (config.subagentAutoSave) {
+            // #113: one suggestion per completed turn, and a human prompt that suspends the loop. Registered
+            // beside the other turn/end doors rather than as a new timing of our own (AGENTS: no second automatic
+            // engine), and inert whenever the model is unset — the model IS the switch.
+            const promptRunner = makePromptRoundRunner({
+                enabled: () => prompt.effective().spec !== '',
+                eligible: (session) => session.header?.origin !== 'subagent',
+                store: store,
+                // #194: every durable row write mirrors to the push transport (order serialized per session).
+                pushRow: (session, sessionId) => { pushBar(session, sessionId); },
+                generate: async (session, turnSeq) => {
+                    // The live session object carries the events; this is the same read the archive door uses, and it
+                    // is payload-bearing. The GOAL is folded from those events so a suggestion cannot ignore the
+                    // purpose it is supposed to advance — the maintainer's rule that the two compose.
+                    void turnSeq;
+                    const events = [...(session.snapshotEvents?.() ?? [])];
+                    const goal = readActiveGoal(events);
+                    const r = await prompt.suggest({
+                        id: session.id,
+                        // #188: the workspace the chapter paths resolve against — without it the lineage walk
+                        // cannot read chapter bodies, and the plots (the trajectory) would silently vanish.
+                        cwd: session.header?.cwd ?? '',
+                        events,
+                        goalDirective: goalDirectiveOf(goal),
+                    });
+                    // Built as an object with ONLY the keys that hold a value: `exactOptionalPropertyTypes` is on, so
+                    // `quiet: undefined` is not the same as omitting `quiet`, and a spread that always writes the key
+                    // would not compile — which is the right outcome, because the runner branches on presence.
+                    if (r.ok)
+                        return { ok: true, text: r.text };
+                    return { ok: false, reason: r.reason ?? r.text, ...(r.quiet === undefined ? {} : { quiet: r.quiet }) };
+                },
+                onReady: (sessionId, state) => {
+                    // Fire only through the loop's own gate, against the LIVE goal signal: armed/idle/budget/one-per-offer
+                    // plus intent, driver precedence and revision staleness, all re-checked at the moment of firing.
+                    promptLoop.maybeFire(sessionId, state, promptLoop.goalSignal(sessionId));
+                },
+                now: () => new Date().toISOString(),
+                // The rig's legs run in a throwaway home whose `ctx.logger` output is not retained, so the prompt
+                // plane's own narration is copied to stderr — where the boot's server log keeps it. Every "why did the
+                // bar not move" answer tonight depended on lines that were being thrown away (#61).
+                log: (m) => { console.error(`[chapters-prompt] ${m}`); ctx.logger?.info?.(`dsh-chapters: ${m}`); },
+                warn: (m) => { console.error(`[chapters-prompt] WARN ${m}`); ctx.logger?.warn?.(`dsh-chapters: ${m}`); },
+            });
+            try {
+                ctx.on?.('session/event', ((session, event) => {
+                    if (session?.id === undefined)
+                        return;
+                    if (event?.type === 'user/message' && event.data?.source?.kind === 'user')
+                        promptBar.disarmHuman(session.id, session);
+                    // Sighted, not assumed. Whether this listener is invoked at all is the question that has been
+                    // unanswered for a day, and `ctx.logger` answers it only inside a home the rig deletes. stderr is
+                    // captured by the boot's server log, so the answer survives the leg (#61).
+                    if (event?.type === 'turn/end')
+                        console.error(`[chapters-prompt] turn/end sighted session=${String(session.id)} seq=${String(event.seq ?? '?')}`);
+                    if (event?.type === 'turn/end')
+                        promptBoundariesSighted += 1;
+                    // #225: the re-enable path needs a witness too. The maintainer ran `/chapters-prompt model
+                    // …` at 18:16 and NO first-boundary line ever followed — meaning either no turn ended after
+                    // it in this process, or the setting did not reach the plane. One line per enable tells
+                    // which: `enable seen` with the effective spec immediately after the write.
+                    if (event?.type === 'user/message' && event.data?.source?.kind === 'command') {
+                        const argsV = String(event.data.args ?? '');
+                        if (/^\s*model\s+\S/.test(argsV) || /^\s*suggest\b/.test(argsV)) {
+                            const specN = prompt.effective().spec;
+                            console.error(`[chapters-prompt] enable/suggest command seen for ${String(session.id)}: model now ${specN !== '' ? specN : 'STILL UNSET(→ writes landed elsewhere)'}`);
+                        }
+                    }
+                    if (event?.type === 'turn/end' && !promptVerdictSighted.has(String(session.id))) {
+                        promptVerdictSighted.add(String(session.id));
+                        const specV = prompt.effective().spec;
+                        const originV = session.header?.origin;
+                        console.error(`[chapters-prompt] first boundary for ${String(session.id)}: model=${specV !== '' ? specV : 'UNSET(→ skipped)'}, origin=${String(originV ?? '-')} (${originV === 'subagent' ? 'NOT eligible' : 'eligible'}), transport=${pushWriter === null ? 'pull' : 'push-live'}`);
+                    }
+                    // #218 BIRTH RECORD: the first event of a session gets an `idle` record, so the bar's
+                    // first mount reads a PUSHED value and the discovery pull cannot happen — the maintainer
+                    // watched a chapters-prompt node land BEFORE their first message, and that node was the
+                    // discovery. Rows only change at turn/end, so a session born before its first turn has
+                    // nothing to say — `idle` is the whole truth — and saying it through the projection costs
+                    // zero commands forever.
+                    if (pushWriter !== null && !seenBirthSessions.has(session.id)) {
+                        seenBirthSessions.add(session.id);
+                        if (prompt.effective().spec !== '')
+                            pushBar(session, session.id);
+                    }
+                    promptRunner(session, event);
+                }));
+                console.error('[chapters-prompt] turn/end door armed');
+                ctx.logger?.info?.('dsh-chapters: suggested-next-step door armed — one offer per completed turn when a prompt model is set (state: /chapters-prompt state)');
+            }
+            catch (error) {
+                console.error(`[chapters-prompt] turn/end door REFUSED: ${String(error?.message ?? error)}`);
+                ctx.logger?.warn?.(`dsh-chapters: suggested-next-step door registration REFUSED — no turn will offer a suggestion (${String(error?.message ?? error).slice(0, 160)})`);
+            }
+            const autoSaveListener = wireSubagentAutoSave(ctx, store, {
+                presetId: CHAPTERS_PRESET_ID,
+                artifactStoreRoot: config.artifactStoreRoot,
+                chapterTokenTarget: config.chapterTokenTarget,
+                toolResultDeferFloorTokens: config.toolResultDeferFloorTokens,
+                mergeThreshold: config.mergeThreshold,
+                chapterLimit: config.chapterLimit,
+                chapterOversizeFactor: config.chapterOversizeFactor,
+                planInlineChars: config.planInlineChars,
+                callArgArtifactTokens: config.callArgArtifactTokens,
+                scheduler,
+            });
+            try {
+                ctx.on?.('subagent/end', autoSaveListener);
+                ctx.logger?.info?.('dsh-chapters: subagent auto-save armed — chapters-preset children archive at settlement (reported by /chapters-status)');
+            }
+            catch (error) {
+                const message = `dsh-chapters: subagent auto-save registration REFUSED — settling subagents will NOT archive (${String(error?.message ?? error)})`;
+                ctx.logger?.warn?.(message);
+                console.error(message);
+            }
+        }
+    }
+    catch (error) {
+        // Tools are the whole user-facing surface short of the engine: a failure
+        // here is loud, never a silently missing tool. Loud means the operator
+        // actually sees it — the realm logger routes to boot stdout (r19/r35 twice
+        // burned by a warn nobody could read; the DSH_CHAPTERS_ERRORS sink env is
+        // the engine's precedent).
+        const message = `dsh-chapters: tool/command registration FAILED (${String(error)})`;
+        ctx.logger?.warn?.(message);
+        console.error(message);
+    }
+    // Honest status, because the settings surface reads "enabled and running" either way, and
+    // "mounted" never meant "the preset exists". The row logs its own delivery line; this one
+    // says what THIS plugin did, and the deferred roster check below says what the host has.
+    const mountMsg = 'dsh-chapters: mounted (tools + commands registered; preset is the `preset-chapters` row)';
+    ctx.logger?.info?.(mountMsg);
+    // Optional CodeGraph integration: lazy probe at activation. The subprocess
+    // service may not be mounted yet; resolveCodegraph caches the result so
+    // subsequent calls are free. Failure → silent no-op at every integration point.
+    if (config.codegraphEnabled !== false) {
+        const subprocess = ctx.get?.('subprocess');
+        void import("./codegraph.js").then(async (cg) => {
+            const exe = await cg.resolveCodegraph(subprocess);
+            ctx.logger?.info?.(`dsh-chapters: codegraph ${exe !== null ? 'found on PATH' : 'not found (integration inactive until installed)'}`);
+        }).catch(() => { });
+    }
+    // File presence is NOT preset existence (§ Preset delivery): the roster is the only
+    // evidence. It must be asked AFTER activation — the registry re-audits a mount by
+    // awaiting the settled loader tree, and a caller "must not run inside a Host row's
+    // own activation, which the settlement would wait on" — hence this deferred check,
+    // which also catches a registration that mounted but could not activate. One check
+    // per boot, reused by the dev witness.
+    const marker = process.env.DSH_CHAPTERS_WITNESS;
+    let roster;
+    const rosterCheck = () => roster ??= reportPresetRoster(ctx, config.fallbackPreset);
+    setTimeout(() => {
+        void rosterCheck().then((verdict) => {
+            if (marker !== undefined)
+                void witness(ctx, marker, domain, verdict);
+        });
+    }, 500).unref?.();
+}
+/**
+ * The §5 sync loop for the host plane. Auto-link (when `knowledgeRemote` is
+ * configured) happens lazily inside resolveProject: a workspace's first
+ * archive event finds a project record, so nothing network-shaped runs
+ * before anything archives.
+ */
+export function createScheduler(store, domain, config, debounceOverride, onSyncDone, warn) {
+    return createSyncScheduler({
+        storeRoot: config.artifactStoreRoot,
+        cloneDir: DEFAULT_CLONE_DIR,
+        debounceMs: debounceOverride ?? config.syncDebounceMs,
+        vocab: { apply: config.vocabApply, coMin: config.vocabCoMin, overlapMin: config.vocabOverlapMin },
+        ...(onSyncDone !== undefined ? { onSyncDone } : {}),
+        resolveProject: (cwd) => {
+            const found = projectForCwd(store.projects(), cwd);
+            if (found !== undefined)
+                return found;
+            if (config.knowledgeRemote === '')
+                return undefined;
+            try {
+                const target = parseKnowledgeRemote(config.knowledgeRemote);
+                const kind = providerKindFor(target.kind, config.knowledgeProvider);
+                const resolved = resolveProject(cwd, config.projectKeyOverride !== '' ? config.projectKeyOverride : undefined, config.knowledgeRemote);
+                const rec = {
+                    // Identity via projectKeyForTarget: §2.3 canonicalization, plus the
+                    // treedx/ namespace for TreeDX targets (keyed per-machine-stable by
+                    // construction — that is the whole point of §2.3). The override wins
+                    // exactly as before.
+                    projectKey: config.projectKeyOverride !== '' ? resolved.projectKey : projectKeyForTarget(target),
+                    slug: target.treedx?.repoName ?? (resolved.remote ?? config.knowledgeRemote).split('/').pop().replace(/\.git$/, ''),
+                    remote: config.knowledgeRemote,
+                    kind,
+                    harnessId: config.harnessId,
+                    linkedAt: new Date().toISOString(),
+                    cwd,
+                };
+                domain.table('projects').put(rec.projectKey, rec);
+                return rec;
+            }
+            catch (error) {
+                // A policy contradiction (knowledgeProvider vs the remote scheme) is
+                // LOUD in the log but never throws into the archive path (§5.3 shape).
+                warn?.(`dsh-chapters: knowledgeRemote auto-link refused: ${String(error?.message ?? error)}`);
+                return undefined;
+            }
+        },
+        tokenFor: (cwd, projectKey) => readToken(cwd, config.artifactStoreRoot, projectKey), // joins via resolveStoreRoot internally (#33)
+        collectionsFor: makeCollectionsReader(store.sessions.bind(store), config.artifactStoreRoot),
+        // #255: rehydration must not resurrect removed chapters; the guard reads the stub rows.
+        removedFor: () => removedGuard(store.sessions()),
+    });
+}
+/** Ask the host which presets exist. Tolerates both shapes the service has
+ *  offered: the bare row array (`list()`) and the remote envelope (`{presets}`). */
+export async function readRosterVerdict(presets, presetId) {
+    if (presets?.list === undefined)
+        return { state: 'unknown', error: 'agentPresets service absent' };
+    try {
+        const raw = await presets.list();
+        const rows = ((Array.isArray(raw) ? raw : raw?.presets) ?? []);
+        const mine = rows.find((r) => r?.id === presetId);
+        if (mine === undefined)
+            return { state: 'absent', rows: rows.map((r) => String(r?.id ?? '?')).sort() };
+        const broken = mine.broken;
+        return typeof broken === 'string' && broken !== '' ? { state: 'present', broken } : { state: 'present' };
+    }
+    catch (error) {
+        return { state: 'unknown', error: String(error?.message ?? error) };
+    }
+}
+/**
+ * The remedy for an absent preset. It is a configuration fact about someone else's tree —
+ * a patch layer can be overridden or disabled by a profile we do not own — so the job is to
+ * name where to look, never to retry behind the operator's back.
+ */
+export function rosterRemediation(presetId) {
+    return `the plugin ships "${presetId}" as the "preset-chapters" declaration row in its bundle patch `
+        + '(cordis.patch.yml), which is a visible Loader entry: check that row in the plugin list, whether a '
+        + 'profile patch disables or overrides it, and whether @fractalsynapse/dsh-chapters is in this profile\u2019s '
+        + 'dsh.profile.bundles at all. If the row is present but this line says absent, the host is below the '
+        + '0.2.0 support floor and cannot register preset rows.';
+}
+/** Deferred boot check: one truthful line about the preset, plus the verdict for the witness.
+ * Exported so the four arms of that line are tested without booting a host — the line IS the
+ * health signal a user reads, and an untested health signal is how the silent case survived. */
+export async function reportPresetRoster(ctx, presetId) {
+    const presets = ctx.get?.('agentPresets');
+    const verdict = await readRosterVerdict(presets, presetId);
+    // The roster says a preset is DECLARED; the inventory says whether its rows are ACTIVE.
+    // A row can resolve and still never start, and that is invisible on the roster — so the
+    // one line the operator reads carries both facts.
+    const mounted = verdict.state === 'present' ? ' — ' + await describeMountedRows(presets, presetId) : '';
+    const line = (message, warn) => {
+        if (warn) {
+            ctx.logger?.warn?.(message);
+            console.error(message);
+        }
+        else
+            ctx.logger?.info?.(message);
+    };
+    if (verdict.state === 'present' && verdict.broken === undefined) {
+        line(`dsh-chapters: preset "${presetId}" is in the host roster${mounted} — chapter-form compaction and continuations will compose`, false);
+    }
+    else if (verdict.state === 'present') {
+        line(`dsh-chapters: preset "${presetId}" is DECLARED BUT BROKEN — ${verdict.broken} — sessions choosing it will not compose. `
+            + 'A preset row whose child plugin no longer resolves fails here; the plugin drops rows this host cannot import, '
+            + `so this line means a package that resolves but will not activate — re-anchor the preset-chapters row against this host. Details: ${verdict.broken}`, true);
+    }
+    else if (verdict.state === 'absent') {
+        line(`dsh-chapters: UNHEALTHY — preset "${presetId}" is NOT in the host roster (roster: ${verdict.rows.join(', ') || 'empty'}). `
+            + `Every session whose log records it will refuse to open with agent-preset/not-found — the logs are intact; the composition is missing. `
+            + `Remedy: ${rosterRemediation(presetId)}`, true);
+    }
+    else {
+        line(`dsh-chapters: could not verify the preset roster (${verdict.error}) — treat chapter-form compaction as unconfirmed`, true);
+    }
+    return verdict;
+}
+/** One phrase describing what the host's inventory says about the preset's own rows.
+ *  Never throws: an unavailable inventory must degrade the line, not the boot check. */
+export async function describeMountedRows(presets, presetId) {
+    try {
+        const raw = await presets?.compositionInventory?.();
+        const entry = inventoryEntry(raw, presetId);
+        if (entry === undefined)
+            return 'rows not reported by this host';
+        const bad = unusableRows(entry);
+        const total = (entry.rows ?? []).length;
+        return bad.length === 0
+            ? `${total} mounted rows all active`
+            : `${bad.length} of ${total} rows NOT active (${bad.join('; ')})`;
+    }
+    catch (error) {
+        return `rows unreadable (${String(error?.message ?? error)})`;
+    }
+}
+// ---------------------------------------------------------------- dev witness
+async function witness(ctx, marker, preopened, roster) {
+    const WITNESS_SESSION = 'dsh-chapters-witness';
+    const out = { at: new Date().toISOString() };
+    try {
+        out.storageDomainPresent = ctx.get?.('storageDomain') !== undefined;
+        out.diagnostics = diagnosticStatusLine();
+        // What this host's preset mechanism IS, and what the roster says about the
+        // chapters preset. These two lines are the difference between "the preset files
+        // are installed" (true, and meaningless on a declaration-row host) and "the
+        // preset exists" — the only thing a session cares about.
+        out.registryRegisters = typeof ctx.get?.('agentPresets')?.register === 'function';
+        out.presetRoster = roster?.state ?? 'not-checked';
+        out.presetRosterLine = await describeMountedRows(ctx.get?.('agentPresets'), CHAPTERS_PRESET_ID);
+        // The roster says a preset is declared; the inventory says whether its rows are
+        // actually active. A row that resolves but will not activate leaves the preset on
+        // the menu and unusable, and only this distinction names it.
+        const invRaw = await ctx.get?.('agentPresets')?.compositionInventory?.()?.catch?.(() => undefined);
+        const inv = inventoryEntry(invRaw, CHAPTERS_PRESET_ID);
+        if (inv !== undefined) {
+            out.presetInventoryRows = (inv.rows ?? []).length;
+            out.presetUnusableRows = unusableRows(inv);
+            if (inv.broken !== undefined)
+                out.presetInventoryBroken = inv.broken;
+        }
+        if (roster?.state === 'absent')
+            out.presetRosterRows = roster.rows;
+        if (roster?.state === 'present' && roster.broken !== undefined)
+            out.presetRosterBroken = roster.broken;
+        if (roster?.state === 'unknown')
+            out.presetRosterError = roster.error;
+        const storageDomain = ctx.get?.('storageDomain');
+        const store = preopened !== undefined ? makeDomainStore(preopened) : (await acquireChapterStore(storageDomain)).store;
+        const prior = await store.get(WITNESS_SESSION);
+        out.priorChapters = prior.chapters.length;
+        if (prior.chapters.length === 0) {
+            const reserved = reserve(prior, 'witness@1', 1);
+            const record = {
+                number: reserved.numbers[0] ?? 1,
+                path: `.dsh-chapters/${WITNESS_SESSION}/chapters/001-witness.md`,
+                title: 'witness', summary: `first boot ${new Date().toISOString()}`,
+                startSeq: 0, endSeq: 0, topics: [], messages: 0, sha256: '0'.repeat(64), estimatedTokens: 0, artifacts: [],
+            };
+            await store.put(WITNESS_SESSION, appendChapters(reserved.state, [record]));
+        }
+        else {
+            await store.put(WITNESS_SESSION, prior);
+        }
+        out.storedChapters = (await store.get(WITNESS_SESSION)).chapters.length;
+    }
+    catch (error) {
+        out.error = String(error);
+    }
+    writeFileSync(marker, JSON.stringify(out, null, 2));
+}
+//# sourceMappingURL=index.js.map