@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.20

package/lib/injections.js

@@ -0,0 +1,165 @@
+/**
+ * The one boundary that decides which bytes of the durable log are CONVERSATION
+ * and which are host-injected context (knowledge-repo.md §15 amendment,
+ * "host-injected context is not conversation").
+ *
+ * Why this exists: the harness injects project context — workspace instruction
+ * files (whatever a given project's AGENTS.md holds), the runtime-context
+ * snapshot, the skill catalog — and injected events arrive in the log either as
+ * their own `user/message` (source.kind `agent-instructions`, `plugin`, …) or
+ * riding INSIDE human messages as `<system-reminder>` spans. A target project's
+ * instruction text is that project's business: it must not be archived into the
+ * shared knowledge corpus, searched by other workspaces, re-quoted into
+ * enrichment input, or bloating a child's re-archive of its own TOC notice
+ * generation after generation.
+ *
+ * Precedents this rule follows, not invents:
+ * - `signature.ts` (r28) already excluded these events from per-turn topic
+ *   signatures after measuring their poison: every signature gained the
+ *   injected filenames and drowned the real topic signal.
+ * - `tests/e2e/model-proxy.ts` (user decision 2026-09-20, AGENTS-BLIND) already
+ *   masks the same classes for tape matching, on the same reasoning:
+ *   development artifacts, every real project ships its own.
+ *
+ * What is NOT touched: the durable session log (invariant: append-only, always —
+ * the originals live on in the parent session), and genuine conversation bytes
+ * (a human typing the words "AGENTS.md" in prose is conversation and stays
+ * verbatim; only the structural injected forms are removed).
+ *
+ * Pure module: no cordis, no fs, no network.
+ */
+/** A user/message is human-authored when it carries no source, or source.kind
+ * 'user' (unlabelled keeps working for seeded fixtures — same rule the
+ * signature layer has used since r28). Everything else — 'agent-instructions',
+ * 'plugin' (the TOC notice, runtime snapshots), 'tool', 'system' — is injected
+ * context, not conversation. Exported so signature.ts imports the SAME
+ * predicate; the two layers must never drift on what counts as a turn. */
+export function isHumanAuthored(data) {
+    const source = data.source;
+    return source?.kind === undefined || source.kind === 'user';
+}
+/**
+ * The ONE targeted exception to the screen (human decision 2026-10-10): the harness's
+ * own mode-switch narration — `source: { kind: 'plugin', plugin: 'plan-mode',
+ * form: 'notice' }`, "The user switched this session to plan mode." — IS conversation.
+ *
+ * The screen exists so a project's private instruction files never travel in a shared
+ * corpus. A mode flip the human performed is not that: it is a fact about THIS session,
+ * and it is the seam that answers "was this approved before or after we started
+ * implementing?". Named by plugin AND form, so it cannot be widened by accident into
+ * the general plugin-source exemption — an instruction file or a runtime snapshot
+ * arriving with a different form still screens.
+ */
+export function isSessionStateNarration(data) {
+    const source = data.source;
+    // v4 (issue #43, measured against dsh-plan-mode/lib/index.js:395-410 on
+    // 0.2.0-rc.2): the producer owns the kind — `{ kind: 'plan-mode', form: 'notice' }`.
+    if (source?.kind === 'plan-mode' && source.form === 'notice')
+        return true;
+    // #61 Amendment B — a delegate's report is conversation about THIS session's work, not a project's
+    // private bytes. Measured shapes (0.2.x logs): `{ kind: 'agent-message', form: 'relay' }` carries
+    // "Agent <id> sent a message: <the result>", and `{ kind: 'subagent-settled', form: 'notice' }` is
+    // when that delegate finished. The old rule screened both, which cost 44 markers / 248,150 chars
+    // (~62K est tokens) in the first project built on this preset — delegated work vanished through BOTH
+    // doors meant to capture it, leaving chapters that recorded a delegation with no outcome.
+    // Named by producer AND form like the plan-mode arm above, so it cannot widen: the workspace
+    // instruction file (`{ kind: 'agent-instructions', form: 'instructions' }`) is still screened, and
+    // `isHumanAuthored` stays strict, because the topic-signature layer must not let a 2 KB report drag a
+    // signature toward the filenames it mentions (record r28).
+    if (source?.kind === 'agent-message' && source.form === 'relay')
+        return true;
+    if (source?.kind === 'subagent-settled' && source.form === 'notice')
+        return true;
+    // #113: a Suggested Next Step the human armed. It is conversation the human authorized — a chapter that
+    // records an autorun response without the prompt that produced it is unexplainable — so it is captured like
+    // the others. Deliberately NOT `kind: 'user'`: the host's goal tool decides "a direct human turn exists" by
+    // looking for exactly that (measured, dsh-tool-goal:49-65), and laundering our loop through it would let a
+    // suggestion authorize model-side goal operations. Named by producer AND form like every arm above: the TOC
+    // notice (`form: 'snapshot'`) and any other plugin's message stay screened.
+    if (source?.kind === 'plugin:dsh-chapters' && source.form === 'notice')
+        return true;
+    // v3 logs, still replayed from disk: the retired wrapper the exception was
+    // written against. Both arms stay named by producer AND form — neither widens.
+    return source?.kind === 'plugin' && source.plugin === 'plan-mode' && source.form === 'notice';
+}
+/**
+ * Does this event belong in the archive as conversation?
+ *
+ * Deliberately NARROWER than `isHumanAuthored`: the topic-signature layer keeps using
+ * the strict predicate, because the r28 lesson was that injected text poisons topic
+ * merging (every signature gained the injected filenames). A mode narration is one
+ * short sentence, so archiving it is worth more than the risk of letting it move a
+ * chapter boundary — and the two uses are separate functions on purpose.
+ */
+export function isArchivableConversation(data) {
+    return isHumanAuthored(data) || isSessionStateNarration(data);
+}
+/** Label for the omission marker: kind, plus plugin name when the source
+ * carries one (so `plugin:dsh-chapters` is recognizable in a chapter). */
+export function sourceLabel(data) {
+    const source = data.source;
+    if (source === undefined)
+        return 'unlabelled';
+    if (source.kind === 'plugin:dsh-chapters' && source.form === 'notice')
+        return 'suggested-prompt';
+    return source.kind === 'plugin' && typeof source.plugin === 'string'
+        ? `plugin:${source.plugin}`
+        : String(source.kind ?? 'unknown');
+}
+/**
+ * The structural injection span. Anchored on the exact harness tag, case
+ * sensitive (the tape's own skill-catalog rule is case sensitive for the same
+ * reason: ordinary prose quoting the tag is vanishingly rare, and the cost of a
+ * false positive is a marked, countable omission — never a silent rewrite of
+ * history, the original bytes stay in the session log). The unclosed-tail form
+ * `[\s\S]*?(</system-reminder>|$)` mirrors the tape's masking of truncated
+ * injections.
+ */
+/**
+ * The ONE predicate for "this text is host-injected context, not something the human wrote".
+ *
+ * `source.kind` remains the primary gate (`isHumanAuthored`, `screenConversation`) — but some consumers
+ * see only flattened provider text with NO source at all, first among them `deriveIdentity` choosing a
+ * chapter TITLE. Until #59 that path carried a private regex (`HARNESS_PROSE`) that had silently fallen
+ * behind the host's injected kinds, so a `time-context` snapshot became a chapter title, slug, FILENAME
+ * and a live TOC citation (`020-time-sampled-while-preparing-turn-11-step-24-202.md`, cited by a
+ * checkpoint and never written). AGENTS.md: one predicate per semantic decision, and a source-shape row
+ * fails if a second list reappears.
+ *
+ * Anchored at the START on purpose: a human quoting "time sampled while preparing" mid-sentence is
+ * conversation and stays verbatim — the same line the body screen draws.
+ *
+ * `this is an automatically generated checkpoint` joined 2026-10-23 (#87): it is the host's own
+ * in-place relief preamble — machine state that replaces earlier turns, never something a human asked.
+ * It had to join THIS list rather than get a second one, because #87's fix asks the same question
+ * ("is this a human turn?") at the compaction seam, and a parallel list is exactly the #59 drift this
+ * comment already records.
+ */
+const INJECTED_PROSE = /^\s*(<system-reminder>|<codegraph_context|system reminder\b|current runtime context\.|time sampled while preparing|browser time zone for this request|\[workspace instructions?\b|this session is running under|the following workspace instructions|agent [A-Za-z0-9_-]{8,} sent a message|background subagent [A-Za-z0-9_-]{8,} finished|this is an automatically generated checkpoint)/i;
+export function isInjectedProse(text) {
+    return INJECTED_PROSE.test(text);
+}
+const REMINDER_SPAN = /<system-reminder>[\s\S]*?(?:<\/system-reminder>|$)/g;
+/** Strip every injected span from a message's text; deterministic, idempotent
+ * (the marker we emit below cannot re-trigger this rule). */
+export function stripReminderSpans(text) {
+    const removed = text.match(REMINDER_SPAN)?.join('').length ?? 0;
+    if (removed === 0)
+        return { text, removedChars: 0 };
+    return { text: text.replace(REMINDER_SPAN, '').trim(), removedChars: removed };
+}
+/** The visible, greppable, countable marker an omission leaves behind. One
+ * shape for every class so downstream assertions (and the sentinel integration
+ * test) pin a single prefix. */
+export const omittedMarker = (what, chars) => `⟦omitted:host-injected ${what}, ${chars} chars — project state, not conversation⟧`;
+export function screenConversation(data, rawText, role) {
+    if (role === 'user' && !isArchivableConversation(data)) {
+        return { text: '', omittedEvent: true, removedChars: rawText.length, sourceKind: sourceLabel(data) };
+    }
+    // Assistant text is model output, but a runtime snapshot has been observed
+    // appended to role user|system by the harness — screening assistant spans
+    // too costs one regex and can only ever mark, never invent, text.
+    const { text, removedChars } = stripReminderSpans(rawText);
+    return { text, omittedEvent: false, removedChars, sourceKind: 'user' };
+}
+//# sourceMappingURL=injections.js.map

package/lib/injections.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"injections.js","sourceRoot":"","sources":["../src/injections.ts"],"names":[],"mappings":"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"}

package/lib/last-resort.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The last-resort deferral's arithmetic (#78 option A) — kept apart from the engine so the rule that
+ * decides WHEN an oversized node may override the operator's arrival floor is testable without a
+ * session, a meter, or a model.
+ *
+ * The number is DERIVED, never invented: a node can only make relief impossible if it cannot fit
+ * beside the content relief is obliged to keep. That obligation is the base engine's own verbatim
+ * retain tail plus its reserved completion budget, both of which it already computes — so the
+ * ceiling is `window − retainBudget − reservedCompletion`, and no new tunable appears (AGENTS: no
+ * hardcoded tunables; `cordis.yml` can only change what config declares).
+ */
+export interface LastResortInputs {
+    windowTokens: number;
+    retainRatio: number;
+    retainTokens?: number;
+    reservedCompletionTokens: number;
+}
+/**
+ * The token size above which an inline `tool/result` cannot coexist with the mandatory tail, or
+ * `null` when nothing can be concluded. Returning `null` — rather than 0, or a guess — is the point:
+ * a wrong ceiling here silently overrides an operator's configured economy knob, which is the one
+ * thing this feature must never do.
+ */
+export declare function lastResortCeilingTokens(v: LastResortInputs): number | null;

package/lib/last-resort.js

@@ -0,0 +1,27 @@
+/**
+ * The token size above which an inline `tool/result` cannot coexist with the mandatory tail, or
+ * `null` when nothing can be concluded. Returning `null` — rather than 0, or a guess — is the point:
+ * a wrong ceiling here silently overrides an operator's configured economy knob, which is the one
+ * thing this feature must never do.
+ */
+export function lastResortCeilingTokens(v) {
+    const { windowTokens, retainRatio, retainTokens, reservedCompletionTokens } = v;
+    const finite = (n) => typeof n === 'number' && Number.isFinite(n);
+    if (!finite(windowTokens) || !finite(reservedCompletionTokens))
+        return null;
+    if (windowTokens <= 0 || reservedCompletionTokens < 0)
+        return null;
+    // An explicit retainTokens wins over the ratio (both are base config the host may carry either way).
+    let retainBudget;
+    if (finite(retainTokens) && retainTokens > 0) {
+        retainBudget = retainTokens;
+    }
+    else {
+        if (!finite(retainRatio) || retainRatio <= 0 || retainRatio >= 1)
+            return null;
+        retainBudget = Math.floor(windowTokens * retainRatio);
+    }
+    const ceiling = windowTokens - retainBudget - reservedCompletionTokens;
+    return ceiling > 0 ? Math.floor(ceiling) : null;
+}
+//# sourceMappingURL=last-resort.js.map

package/lib/last-resort.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"last-resort.js","sourceRoot":"","sources":["../src/last-resort.ts"],"names":[],"mappings":"AAkBA;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CAAC,CAAmB;IACzD,MAAM,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,wBAAwB,EAAE,GAAG,CAAC,CAAA;IAC/E,MAAM,MAAM,GAAG,CAAC,CAAU,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAA;IACvF,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,IAAI,CAAC,MAAM,CAAC,wBAAwB,CAAC;QAAE,OAAO,IAAI,CAAA;IAC3E,IAAI,YAAY,IAAI,CAAC,IAAI,wBAAwB,GAAG,CAAC;QAAE,OAAO,IAAI,CAAA;IAClE,qGAAqG;IACrG,IAAI,YAAoB,CAAA;IACxB,IAAI,MAAM,CAAC,YAAY,CAAC,IAAI,YAAY,GAAG,CAAC,EAAE,CAAC;QAC7C,YAAY,GAAG,YAAY,CAAA;IAC7B,CAAC;SAAM,CAAC;QACN,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,IAAI,WAAW,IAAI,CAAC,IAAI,WAAW,IAAI,CAAC;YAAE,OAAO,IAAI,CAAA;QAC7E,YAAY,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,GAAG,WAAW,CAAC,CAAA;IACvD,CAAC;IACD,MAAM,OAAO,GAAG,YAAY,GAAG,YAAY,GAAG,wBAAwB,CAAA;IACtE,OAAO,OAAO,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;AACjD,CAAC"}

package/lib/log-shape.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Event-shape readers — the single place that knows how DSH nests payloads in
+ * the durable log.
+ *
+ * Extracted from `render.ts` (docs/plans-carriage.md § 1: the chapter renderer and the plan detector
+ * must agree on which `tool/result` answers which `tool/call`, or a plan's verdict could be read
+ * differently in two places). Shapes here were MEASURED from real logs, never guessed — see
+ * tests/unit/render.test.ts:18-22 for the fixture mirror and spikes/probe/FINDINGS.md.
+ *
+ * Pure module: no cordis, no fs, no DSH imports.
+ */
+import type { ContentBlock, SessionEventLike } from './types.ts';
+export declare const blocksOf: (value: unknown) => ContentBlock[];
+export declare const textOfBlocks: (value: unknown) => string;
+/**
+ * Flatten a tool-result payload, which nests a content array inside a tool-result block.
+ * REAL shape (measured e2e, 2026-09-19): `message.content` blocks are
+ * `{ type: 'tool-result', toolCallId, isError, content: [{ type:'text', text }] }`.
+ */
+export declare function toolResultText(data: Record<string, unknown>): string;
+/** True when the paired tool-result carries an error flag (a failed call). */
+export declare function toolResultIsError(data: Record<string, unknown>): boolean;
+/** The callId a `tool/result` answers (measured: it rides on `message.source.callId`). */
+export declare function resultCallId(ev: SessionEventLike): string | undefined;
+/** The callId a `tool/call` carries. */
+export declare const callIdOf: (ev: SessionEventLike) => string | undefined;
+/** Does this result answer this call? Both sides must name a callId — never guess by adjacency. */
+export declare function sameCall(call: SessionEventLike, result: SessionEventLike): boolean;
+/**
+ * The LAST result event for one callId, over an already-range-filtered list.
+ * Host redelivery is real (measured 2026-09-28: 25 calls carried TWO tool/result
+ * events), so the newest copy is the authoritative verdict.
+ */
+export declare function lastResultFor(results: readonly SessionEventLike[], callId: string): SessionEventLike | undefined;
+/** `tool/call` arguments as one serialized string (object or pre-serialized string both occur). */
+export declare function callArgsText(data: Record<string, unknown>): string;
+/** One named argument from either shape (string JSON or object). */
+export declare function callArg(data: Record<string, unknown>, name: string): string | undefined;

package/lib/log-shape.js

@@ -0,0 +1,93 @@
+export const blocksOf = (value) => Array.isArray(value) ? value : [];
+export const textOfBlocks = (value) => blocksOf(value)
+    .filter((b) => b.type === 'text')
+    .map((b) => b.text ?? '')
+    .join('\n');
+/**
+ * Flatten a tool-result payload, which nests a content array inside a tool-result block.
+ * REAL shape (measured e2e, 2026-09-19): `message.content` blocks are
+ * `{ type: 'tool-result', toolCallId, isError, content: [{ type:'text', text }] }`.
+ */
+export function toolResultText(data) {
+    const message = data.message;
+    const inner = blocksOf(message?.content ?? data.content);
+    const parts = [];
+    for (const block of inner) {
+        if (block.type === 'text')
+            parts.push(block.text ?? '');
+        else if (block.type === 'tool-result') {
+            const nested = block.content;
+            parts.push(typeof nested === 'string' ? nested : textOfBlocks(nested));
+        }
+    }
+    return parts.filter((p) => p.length > 0).join('\n');
+}
+/** True when the paired tool-result carries an error flag (a failed call). */
+export function toolResultIsError(data) {
+    const message = data.message;
+    const inner = blocksOf(message?.content ?? data.content);
+    return inner.some((b) => b.isError === true);
+}
+/** The callId a `tool/result` answers (measured: it rides on `message.source.callId`). */
+export function resultCallId(ev) {
+    const msg = ev.data?.message;
+    const cid = msg?.source?.callId;
+    if (typeof cid === 'string')
+        return cid;
+    const flat = ev.data?.callId;
+    return typeof flat === 'string' ? flat : undefined;
+}
+/** The callId a `tool/call` carries. */
+export const callIdOf = (ev) => {
+    const cid = ev.data?.callId;
+    return typeof cid === 'string' ? cid : undefined;
+};
+/** Does this result answer this call? Both sides must name a callId — never guess by adjacency. */
+export function sameCall(call, result) {
+    const cid = callIdOf(call);
+    const rcid = resultCallId(result);
+    return cid !== undefined && rcid !== undefined && String(cid) === String(rcid);
+}
+/**
+ * The LAST result event for one callId, over an already-range-filtered list.
+ * Host redelivery is real (measured 2026-09-28: 25 calls carried TWO tool/result
+ * events), so the newest copy is the authoritative verdict.
+ */
+export function lastResultFor(results, callId) {
+    let last;
+    for (const ev of results)
+        if (resultCallId(ev) === callId)
+            last = ev;
+    return last;
+}
+/** `tool/call` arguments as one serialized string (object or pre-serialized string both occur). */
+export function callArgsText(data) {
+    const args = data.arguments;
+    if (typeof args === 'string')
+        return args;
+    try {
+        return JSON.stringify(args ?? {});
+    }
+    catch {
+        return String(args);
+    }
+}
+/** One named argument from either shape (string JSON or object). */
+export function callArg(data, name) {
+    const args = data.arguments;
+    let obj;
+    if (typeof args === 'string') {
+        try {
+            obj = JSON.parse(args);
+        }
+        catch {
+            obj = undefined;
+        }
+    }
+    else if (args !== null && typeof args === 'object') {
+        obj = args;
+    }
+    const value = obj?.[name];
+    return typeof value === 'string' ? value : undefined;
+}
+//# sourceMappingURL=log-shape.js.map

package/lib/log-shape.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"log-shape.js","sourceRoot":"","sources":["../src/log-shape.ts"],"names":[],"mappings":"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"}

package/lib/models-command.d.ts

@@ -0,0 +1,74 @@
+/**
+ * #173 — the /chapters-models pure core: discovery for the three model settings.
+ *
+ * The three keys (`enrichment.model`, `rules.model`, the prompt model) all take a `provider/model`
+ * route, and before this command nothing in the product told a human which identifiers this host
+ * accepts — a wrong guess failed at call time as a routing error. This mirrors the host's own
+ * sanctioned discovery tool (`list_subagent_models` in
+ * examples/dsh/packages/subagent/tool-subagent/src/list-models.ts): `listProviders()` is SYNC,
+ * `listModels(provider)` is the ADVISORY catalog, and `resolveModelInfo(provider, model)` is the
+ * exact-route drill-down that adds what only the adapter knows (context window, reasoning efforts).
+ *
+ * Two honesty rules the rendering never drops: catalog membership is advisory — the host routes
+ * unlisted ids, so an empty catalog means "no selection offered", never "nothing works" — and a
+ * capability the adapter does not advertise is REPORTED ABSENT, not guessed. Like every
+ * /chapters-* command this is deterministic text: it never enters the model's context.
+ * Pure core; the thin registration lives in commands.ts and the wiring in index.ts.
+ */
+export interface ModelsProviderInfo {
+    readonly id: string;
+    readonly name: string;
+}
+/** Host-shaped `LlmModelInfo` (examples/dsh/packages/llm/llm/src/types.ts:348). */
+export interface ModelsModelInfo {
+    readonly provider: string;
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string | undefined;
+}
+/** Host-shaped `LlmResolvedModelInfo` — the fields this command consumes, no more. */
+export interface ModelsResolvedInfo extends ModelsModelInfo {
+    readonly context?: {
+        readonly contextWindow?: number;
+    } | undefined;
+    readonly reasoning?: {
+        readonly efforts?: readonly {
+            readonly id: string;
+            readonly name: string;
+            readonly description?: string;
+        }[] | undefined;
+        readonly defaultEffort?: string | undefined;
+    } | undefined;
+}
+/** The `llm` service surface this command rides — stub it in the HOST's shape, never an easier one. */
+export interface ModelsLlm {
+    listProviders(): readonly ModelsProviderInfo[];
+    listModels(provider: string): Promise<readonly ModelsModelInfo[]>;
+    resolveModelInfo(provider: string, model: string, signal?: AbortSignal): Promise<ModelsResolvedInfo>;
+}
+/** Where the value the human sees right now came from — rendered, because "set" and "fell back" differ. */
+export type CurrentSource = 'settings' | 'config' | 'conversation-route' | 'rides-enrichment' | 'off';
+export interface ModelsIo {
+    /** Absent on planes without the host llm service — the command refuses cleanly, never crashes. */
+    llm?: ModelsLlm | undefined;
+    /** The three settings' effective values, pre-resolved by the wiring (config → settings → fallback). */
+    current: {
+        enrichment: {
+            value: string;
+            source: CurrentSource;
+        };
+        rules: {
+            value: string;
+            source: CurrentSource;
+        };
+        prompt: {
+            value: string;
+            source: CurrentSource;
+        };
+    };
+}
+export interface ModelsReply {
+    kind: 'success' | 'error';
+    text: string;
+}
+export declare function modelsCommand(io: ModelsIo, args: string, signal?: AbortSignal): Promise<ModelsReply>;

package/lib/models-command.js

@@ -0,0 +1,100 @@
+/**
+ * #173 — the /chapters-models pure core: discovery for the three model settings.
+ *
+ * The three keys (`enrichment.model`, `rules.model`, the prompt model) all take a `provider/model`
+ * route, and before this command nothing in the product told a human which identifiers this host
+ * accepts — a wrong guess failed at call time as a routing error. This mirrors the host's own
+ * sanctioned discovery tool (`list_subagent_models` in
+ * examples/dsh/packages/subagent/tool-subagent/src/list-models.ts): `listProviders()` is SYNC,
+ * `listModels(provider)` is the ADVISORY catalog, and `resolveModelInfo(provider, model)` is the
+ * exact-route drill-down that adds what only the adapter knows (context window, reasoning efforts).
+ *
+ * Two honesty rules the rendering never drops: catalog membership is advisory — the host routes
+ * unlisted ids, so an empty catalog means "no selection offered", never "nothing works" — and a
+ * capability the adapter does not advertise is REPORTED ABSENT, not guessed. Like every
+ * /chapters-* command this is deterministic text: it never enters the model's context.
+ * Pure core; the thin registration lives in commands.ts and the wiring in index.ts.
+ */
+const USAGE = 'usage: /chapters-models [<provider> [<model>]] — a paste-ready provider/model id works as one arg';
+const ADVISORY = 'catalog membership is advisory: the host routes unlisted model ids too, and an empty catalog means no selection is offered — not that nothing works.';
+function currentFooter(current) {
+    const line = (label, v, unset, setter) => `  ${label.padEnd(16)} ${v.value !== '' ? `${v.value} (from ${v.source})` : unset}\n  ${''.padEnd(16)} set with: ${setter}`;
+    return 'current model settings:\n'
+        + line('enrichment.model', current.enrichment, '(unset — rides the conversation route)', '/chapters-enrich model <provider/model> | clear') + '\n'
+        + line('rules.model', current.rules, '(unset — mining rides the enrichment call)', '/chapters-rule model <provider/model> | clear') + '\n'
+        + line('prompt model', current.prompt, 'OFF — setting a model IS the enable (§28)', '/chapters-prompt model <provider/model> | off');
+}
+function modelLine(provider, m) {
+    return `  ${provider}/${m.id} — ${m.name}${m.description === undefined || m.description === '' ? '' : `: ${m.description}`}`;
+}
+export async function modelsCommand(io, args, signal) {
+    const llm = io.llm;
+    if (llm === undefined) {
+        return { kind: 'error', text: `the llm service is unavailable on this plane — cannot enumerate models.\n${currentFooter(io.current)}` };
+    }
+    const parts = args.trim().split(/\s+/).filter((p) => p.length > 0);
+    // One arg carrying a slash is a paste-ready id — this command's own output format.
+    let provider;
+    let model;
+    if (parts.length === 1 && parts[0].includes('/')) {
+        const i = parts[0].indexOf('/');
+        provider = parts[0].slice(0, i);
+        model = parts[0].slice(i + 1);
+    }
+    else if (parts.length === 1) {
+        provider = parts[0];
+    }
+    else if (parts.length === 2) {
+        provider = parts[0];
+        model = parts[1];
+    }
+    else if (parts.length > 2) {
+        return { kind: 'error', text: USAGE };
+    }
+    const providers = llm.listProviders();
+    if (provider === undefined) {
+        const sections = [];
+        for (const p of providers) {
+            const models = await llm.listModels(p.id);
+            sections.push(`provider ${p.id} — ${p.name}\n`
+                + (models.length === 0
+                    ? `  (no advertised models for ${p.id} — ${ADVISORY})`
+                    : models.map((m) => modelLine(p.id, m)).join('\n')));
+        }
+        const body = providers.length === 0
+            ? `(no LLM providers are registered on this host — ${ADVISORY})`
+            : sections.join('\n\n');
+        return { kind: 'success', text: `${body}\n\n${ADVISORY}\n\n${currentFooter(io.current)}` };
+    }
+    if (provider.length === 0 || (model !== undefined && model.length === 0)) {
+        return { kind: 'error', text: USAGE };
+    }
+    const known = providers.find((p) => p.id === provider);
+    if (known === undefined) {
+        const available = providers.map((p) => p.id).join(', ') || '(none)';
+        return { kind: 'error', text: `LLM provider "${provider}" is not registered; available providers: ${available}` };
+    }
+    if (model === undefined) {
+        const models = await llm.listModels(known.id);
+        const body = models.length === 0
+            ? `(no advertised models for ${known.id} — ${ADVISORY})`
+            : `provider ${known.id} — ${known.name}\n${models.map((m) => modelLine(known.id, m)).join('\n')}\n\n${ADVISORY}`;
+        return { kind: 'success', text: `${body}\n\n${currentFooter(io.current)}` };
+    }
+    try {
+        const info = await llm.resolveModelInfo(known.id, model, signal);
+        const efforts = info.reasoning?.efforts ?? [];
+        const lines = [
+            `${known.id}/${info.id} — ${info.name}${info.description === undefined || info.description === '' ? '' : `: ${info.description}`}`,
+            `context window: ${info.context?.contextWindow !== undefined ? `${String(info.context.contextWindow)} tokens` : 'not advertised by this adapter'}`,
+            efforts.length === 0
+                ? 'reasoning efforts: (no advertised reasoning efforts)'
+                : `reasoning efforts:\n${efforts.map((e) => `  ${e.id}${info.reasoning?.defaultEffort === e.id ? ' (default)' : ''} — ${e.name}${e.description === undefined || e.description === '' ? '' : `: ${e.description}`}`).join('\n')}`,
+        ];
+        return { kind: 'success', text: `${lines.join('\n')}\n\n${currentFooter(io.current)}` };
+    }
+    catch (error) {
+        return { kind: 'error', text: `resolveModelInfo(${known.id}, ${model}) failed: ${String(error?.message ?? error).slice(0, 200)}` };
+    }
+}
+//# sourceMappingURL=models-command.js.map

package/lib/models-command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"models-command.js","sourceRoot":"","sources":["../src/models-command.ts"],"names":[],"mappings":"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"}

package/lib/notice.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The TOC notice: the single synthetic `user/message` that seeds a continuation.
+ *
+ * This module exists because of the 66-log lesson from `dsh-session-fork`
+ * (docs/development.md § L1): a message source outside the kernel's accepted
+ * vocabulary is not a cosmetic bug — stored logs that fail replay refuse to
+ * load, retroactively. The kernel's seed validator is not published as a
+ * callable, so the vocabulary here is pinned two ways and guarded by
+ * test/notice.test.ts + the v4 admission rows in tests/unit/host-seed-contract.test.ts:
+ *
+ *  1. Behaviorally, from the Phase 0 seed probes and the 2026-10-18 v4 drift
+ *     (issue #43) — the retired forms are reproduced as refusals, not dropped:
+ *     a string `source` was rejected as `invalid source`; session format v4
+ *     rejects the bare `kind: 'plugin'` wrapper with the kernel's own words,
+ *     "format v4 message requires a producer-owned source kind"
+ *     (`@deepseek-ai/dsh-session-format-v3-to-v4/lib/index.js:126`,
+ *     `dsh-session-persistence-jsonl/lib/worker.cjs:10902` on 0.2.0-rc.2).
+ *  2. Structurally, against the installed kernel: `role: 'user'`; a non-empty
+ *     string `id`; array `content`; contiguous seed from `seq = 0`;
+ *     `source.kind` a non-empty producer-owned string; `ContextForm` values
+ *     `instructions | catalog | notice | relay | recall | snapshot`
+ *     (`dsh-llm/lib/types/message.d.ts` — verified against 0.2.0-rc.2).
+ *
+ * v4 source attribution: each producer OWNS its kind. Third-party producers
+ * use the `plugin:<id>` form — measured live, the 0.2.0-rc.2 host writes its
+ * own logs with `plugin:dsh-codegraph` + `form: 'notice'`. So the notice
+ * carries `{ kind: 'plugin:dsh-chapters', form: 'snapshot', sections: [...] }`
+ * and NO `plugin` field (the v3→v4 migration's own `rewritePluginSource`
+ * drops it: "kind is the producer's own kind and whose `plugin` field is
+ * dropped"). `sourceLabel` renders `plugin:dsh-chapters` for BOTH the retired
+ * wrapper and the colon kind — byte-identically — so omission markers in
+ * already-archived chapters keep matching.
+ * INVARIANT 2: exactly one event, at seq 0. Never a slice of the parent's log.
+ */
+import type { SessionEventLike } from './types.ts';
+/** Our producer id. Changing this orphans every already-seeded continuation. */
+export declare const NOTICE_PLUGIN = "dsh-chapters";
+/** The v4 producer-owned source kind (issue #43). `plugin:<producer>` is the
+ *  form the 0.2.x kernel itself admits for third-party producers; the bare
+ *  `plugin` wrapper it retired. */
+export declare const NOTICE_SOURCE_KIND = "plugin:dsh-chapters";
+/** The section name our TOC rides under inside the snapshot. */
+export declare const NOTICE_SECTION = "chapters:toc";
+/**
+ * The kinds this plugin may emit, pinned to what the installed v4 kernel
+ * admits (seed/load boundary + persistence row admission). The retired v3
+ * `plugin` wrapper is deliberately NOT in this list — it is refused below
+ * with the kernel's own refusal text.
+ */
+export declare const ACCEPTED_SOURCE_KINDS: readonly ["user", "plugin:dsh-chapters"];
+/** `ContextForm` values, exactly as published (semantic, never visual). */
+export declare const ACCEPTED_CONTEXT_FORMS: readonly ["instructions", "catalog", "snapshot", "notice", "relay", "recall"];
+export interface TocNoticeOptions {
+    /** Fresh unique id per notice — the kernel rejects a seed message without one. */
+    newId: () => string;
+    time?: number;
+}
+/**
+ * Build the one seed event for a continuation. Throws rather than emit an
+ * event the kernel would reject at seed time — a refusal here is cheap, a
+ * bricked log is not.
+ */
+export declare function buildTocNotice(tocText: string, opts: TocNoticeOptions): SessionEventLike;
+/**
+ * Transcription of the kernel's seed-time checks (message-shape + v4 source
+ * admission + the recorded rejections). Kept as an exported predicate so tests
+ * pin our output against the same rules the host applies, and any future
+ * notice variant fails HERE, at the boundary of authorship. The v4 rows are
+ * drift-gated against the kernel's own admission function
+ * (`dsh-session-format-v3-to-v4` `assertV4RowAdmission`) in
+ * tests/unit/host-seed-contract.test.ts — this transcription is the fast lane,
+ * the kernel is the authority.
+ */
+export declare function assertKernelAcceptedUserMessage(event: SessionEventLike): void;