@fractalsynapse/dsh-chapters 0.0.0-stage → 0.2.21

package/lib/artifact-query.js

@@ -0,0 +1,187 @@
+/**
+ * Artifact query surface (arrival-time artifacting plan, Phase 3): pure,
+ * bounded readers over content-addressed artifact files. The point of this
+ * module is that a stored blob is USEFUL without ever being loaded whole —
+ * toc/search/read are the small-block windows the RLM result calls an
+ * 'external environment', implemented with files and line numbers instead
+ * of a code sandbox. Every function is deterministic and refuses rather
+ * than silently clipping (bounds reported, never applied by truncation
+ * without a flag).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+/** Rough token estimate consistent with the est-token convention elsewhere (chars/4). */
+const estTokens = (s) => Math.ceil(s.length / 4);
+/**
+ * Resolve a user/model-supplied reference to an absolute artifact path INSIDE
+ * the store. Accepts a 64-hex sha, 'artifacts/xx/<sha>.txt', or an absolute
+ * path. Throws on anything escaping the store — this tool is read-only, the
+ * containment is the whole security story.
+ */
+export function resolveArtifactPath(storeDir, ref) {
+    const clean = ref.trim();
+    if (/^[0-9a-f]{64}$/.test(clean))
+        return path.join(storeDir, 'artifacts', clean.slice(0, 2), `${clean}.txt`);
+    const abs = path.isAbsolute(clean) ? path.normalize(clean) : path.normalize(path.join(storeDir, clean));
+    const root = path.resolve(storeDir);
+    if (abs !== root && !abs.startsWith(root + path.sep))
+        throw new Error(`artifact reference escapes the store: ${ref}`);
+    return abs;
+}
+/**
+ * Markdown heading map with 1-based line numbers — a 300-page book arrives
+ * with its own table of contents (fenced code blocks are skipped so '#
+ * comments' inside them never masquerade as headings).
+ */
+export function buildToc(text, maxEntries = 400) {
+    const entries = [];
+    let inFence = false;
+    let fenceMarker = '';
+    let lineNo = 0;
+    for (const line of text.split('\n')) {
+        lineNo++;
+        const fence = /^\s{0,3}(`{3,}|~{3,})/.test(line);
+        if (fence) {
+            const marker = line.trim().slice(0, 3);
+            if (!inFence) {
+                inFence = true;
+                fenceMarker = marker[0];
+            }
+            else if (marker[0] === fenceMarker) {
+                inFence = false;
+            }
+            continue;
+        }
+        if (inFence)
+            continue;
+        const m = /^(#{1,6})\s+(.*)$/.exec(line);
+        if (m === null)
+            continue;
+        if (entries.length >= maxEntries)
+            return { entries, truncated: true };
+        entries.push({ line: lineNo, depth: m[1].length, title: m[2].trim().slice(0, 120) });
+    }
+    return { entries, truncated: false };
+}
+/**
+ * Case-insensitive query over lines: regex when it compiles, literal phrase
+ * otherwise. Matches expand to ±context lines and overlapping windows merge;
+ * the pack stops at maxTokens and REPORTS what it left behind.
+ */
+export function searchArtifact(text, query, opts = {}) {
+    const maxTokens = opts.maxTokens ?? 400;
+    const context = opts.contextLines ?? 2;
+    const lines = text.split('\n');
+    let re = null;
+    try {
+        re = new RegExp(query, 'i');
+    }
+    catch {
+        re = null;
+    }
+    const hit = (l) => re !== null ? re.test(l) : l.toLowerCase().includes(query.trim().toLowerCase());
+    const matched = [];
+    for (let i = 0; i < lines.length; i++)
+        if (hit(lines[i]))
+            matched.push(i);
+    const blocks = [];
+    let used = 0;
+    for (const idx of matched) {
+        const start = Math.max(0, idx - context);
+        const end = Math.min(lines.length - 1, idx + context);
+        const last = blocks[blocks.length - 1];
+        if (last !== undefined && start <= last.end + 1) {
+            if (end > last.end) {
+                const add = lines.slice(last.end + 1, end + 1).map((l, k) => `${last.end + 2 + k}: ${l.slice(0, 400)}`).join('\n');
+                const addTokens = estTokens(add);
+                if (used + addTokens > maxTokens)
+                    break;
+                last.lines.push(...lines.slice(last.end + 1, end + 1).map((l, k) => `${last.end + 2 + k}: ${l.slice(0, 400)}`));
+                last.end = end;
+                used += addTokens;
+            }
+            continue;
+        }
+        const chunk = lines.slice(start, end + 1).map((l, k) => `${start + k + 1}: ${l.slice(0, 400)}`);
+        const tokens = estTokens(chunk.join('\n'));
+        if (used + tokens > maxTokens)
+            break;
+        blocks.push({ start: start + 1, end: end + 1, lines: chunk });
+        used += tokens;
+    }
+    const lastIncluded = blocks.length === 0 ? -1 : blocks[blocks.length - 1].end - 1;
+    const remaining = matched.filter((i) => i > lastIncluded).length;
+    return { total: matched.length, blocks, truncated: remaining > 0, remaining };
+}
+/** Exact line window (1-based inclusive), capped per call; bounds reported. */
+export function readLines(text, offset, limit, hardCap = 400) {
+    const lines = text.split('\n');
+    const start = Math.max(1, Math.floor(offset));
+    const want = Math.max(1, Math.floor(limit));
+    const take = Math.min(want, hardCap);
+    const end = Math.min(lines.length, start + take - 1);
+    return { start, end, of: lines.length, lines: lines.slice(start - 1, end).map((l, k) => `${start + k}: ${l.slice(0, 1000)}`) };
+}
+/** Load an artifact with a size guard; returns text + totals for the pack. */
+export function loadArtifact(absPath) {
+    const st = fs.statSync(absPath);
+    return { text: fs.readFileSync(absPath, 'utf8'), bytes: st.size, lines: 0 };
+}
+/**
+ * Store-first, mirror-second resolution (measured 2026-09-28, treeseed pool
+ * audit): chapters cite 'artifacts/aa/<sha>.txt' — on another machine the blob
+ * lives in the knowledge MIRROR (artifacts/<projectKey>/aa/<sha>.txt, one dir
+ * per linked project), not the local store. Returns the absolute path of the
+ * first existing match, or null. Containment holds on BOTH roots; '..' can
+ * never escape.
+ */
+export function resolveArtifactWithMirror(storeDir, ref, mirrorDir) {
+    const primary = resolveArtifactPath(storeDir, ref); // still throws on escapes
+    if (fs.existsSync(primary))
+        return primary;
+    const clean = ref.trim();
+    // tail = the aa/<sha>.txt portion under artifacts/, whatever the ref form
+    const tail = /^[0-9a-f]{64}$/.test(clean)
+        ? path.join(clean.slice(0, 2), `${clean}.txt`)
+        : (() => {
+            const m = clean.replace(/^\.\//, '').match(/artifacts[/\\](.+\.txt)$/);
+            return m?.[1] ?? null;
+        })();
+    if (tail === null || tail.split(/[\\/]/).includes('..'))
+        return null;
+    // Session trees FIRST (measured 2026-10-09, plans-carriage): a chapter defers a
+    // result — or a plan's full text — to `artifacts/<aa>/<sha>.txt`, and
+    // archive.writeArchive writes it under the ANCESTRY TREE directory
+    // (<storeRoot>/<rootSession>/artifacts/…), not the store root where arrival
+    // stubs live. Before this, every such citation pointed at a path
+    // chapters_artifact could not resolve, so 'every byte remains retrievable'
+    // held only on the machine and directory layout that happened to match.
+    if (fs.existsSync(storeDir)) {
+        for (const entry of fs.readdirSync(storeDir, { withFileTypes: true })) {
+            if (!entry.isDirectory() || entry.name.startsWith('.'))
+                continue;
+            const cand = path.join(storeDir, entry.name, 'artifacts', tail);
+            const root = path.resolve(storeDir);
+            const resolved = path.resolve(cand);
+            if (resolved !== root && !resolved.startsWith(root + path.sep))
+                continue;
+            if (fs.existsSync(cand))
+                return cand;
+        }
+    }
+    const artRoot = path.join(mirrorDir, 'artifacts');
+    if (!fs.existsSync(artRoot))
+        return null;
+    for (const key of fs.readdirSync(artRoot, { withFileTypes: true })) {
+        if (!key.isDirectory())
+            continue;
+        const cand = path.join(artRoot, key.name, tail);
+        const root = path.resolve(artRoot);
+        if (path.resolve(cand) !== root && !path.resolve(cand).startsWith(root + path.sep))
+            continue;
+        if (fs.existsSync(cand))
+            return cand;
+    }
+    return null;
+}
+//# sourceMappingURL=artifact-query.js.map

package/lib/artifact-query.js.map

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

package/lib/attach.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Attaching a created child to the workspace — the loud version (#54).
+ *
+ * One step, five ways it can fail, and only one of them silent. AGENTS records that
+ * `workspaceRegistry.createCanonical(cwd)` → `attachSession(id)` is precisely what makes a
+ * programmatic session APPEAR in the UI ("an unattached session was the whole explanation
+ * for round 6's 'not listed'"), yet the door called it through two optional chains inside a
+ * `catch` that only warned the profile logger. On host 0.2.0-rc.2 the result is a child that
+ * is created, durable, present in `session_projcache` — and absent from the sidebar after a
+ * reload, while the door reports success. Silence in a required step is the bug; this module
+ * is the fix.
+ *
+ * The rule it encodes: **verify the user-visible fact, not the absence of a throw.** A
+ * successful `attachSession()` proves the method exists, not that the session is listed —
+ * so the check is "does this child appear in `sessionQuery.listSessions()`", polled briefly
+ * because the workspace catches up asynchronously.
+ */
+export interface AttachPorts {
+    /** the host's `workspaceRegistry` service, as far as it was resolved */
+    workspaceRegistry: unknown;
+    /** the host's `sessionQuery` service; absent ⇒ listing cannot be verified, said out loud */
+    sessionQuery: unknown;
+    /** the host's `sessionController` service; its `list()` is the surface the BROWSER reads.
+     *  Absent ⇒ the gateway half of the verification is UNVERIFIED, said out loud. */
+    sessionController?: unknown;
+    /** the diagnostics seam (`src/diag.ts`): sink + logger, never throws */
+    diagnostic(where: string, message: string, error?: unknown): void;
+    childId: string;
+    cwd: string;
+    /** test seams; production uses the defaults */
+    pollIntervalMs?: number;
+    pollBudgetMs?: number;
+}
+export interface AttachOutcome {
+    /** the workspace actually took the session */
+    attached: boolean;
+    /** it appears in the session list. `undefined` = UNVERIFIABLE, which is NOT `true`. */
+    listed: boolean | undefined;
+    /** it appears in the GATEWAY list the browser renders and opens from. `undefined` = unverified.
+     *  Written as `| undefined` deliberately: this repo compiles with
+     *  `exactOptionalPropertyTypes`, where `?: boolean` forbids assigning undefined. */
+    gatewayListed?: boolean | undefined;
+    /** user-visible words for anything short of attached+listed — these reach the door result */
+    warnings: string[];
+}
+export declare function attachCreatedChild(ports: AttachPorts): Promise<AttachOutcome>;

package/lib/attach.js

@@ -0,0 +1,120 @@
+/**
+ * Attaching a created child to the workspace — the loud version (#54).
+ *
+ * One step, five ways it can fail, and only one of them silent. AGENTS records that
+ * `workspaceRegistry.createCanonical(cwd)` → `attachSession(id)` is precisely what makes a
+ * programmatic session APPEAR in the UI ("an unattached session was the whole explanation
+ * for round 6's 'not listed'"), yet the door called it through two optional chains inside a
+ * `catch` that only warned the profile logger. On host 0.2.0-rc.2 the result is a child that
+ * is created, durable, present in `session_projcache` — and absent from the sidebar after a
+ * reload, while the door reports success. Silence in a required step is the bug; this module
+ * is the fix.
+ *
+ * The rule it encodes: **verify the user-visible fact, not the absence of a throw.** A
+ * successful `attachSession()` proves the method exists, not that the session is listed —
+ * so the check is "does this child appear in `sessionQuery.listSessions()`", polled briefly
+ * because the workspace catches up asynchronously.
+ */
+const shape = (v) => {
+    if (v === null)
+        return 'null';
+    if (v === undefined)
+        return 'undefined';
+    if (typeof v !== 'object')
+        return typeof v;
+    const keys = Object.keys(v).slice(0, 6);
+    return `${Array.isArray(v) ? 'array' : 'object'}{${keys.join(',')}}`;
+};
+export async function attachCreatedChild(ports) {
+    const warnings = [];
+    const registry = ports.workspaceRegistry;
+    if (typeof registry?.createCanonical !== 'function') {
+        const reason = `child ${ports.childId} could NOT be attached to the workspace: no "workspaceRegistry" service (or it exposes no createCanonical) — it may never appear in the sidebar`;
+        ports.diagnostic('attach:workspaceRegistry', reason, `resolved=${shape(ports.workspaceRegistry)}`);
+        return { attached: false, listed: undefined, warnings: [reason] };
+    }
+    let workspace;
+    try {
+        workspace = await registry.createCanonical(ports.cwd);
+    }
+    catch (error) {
+        const reason = `child ${ports.childId} could NOT be attached: createCanonical("${ports.cwd}") failed: ${String(error?.message ?? error)}`;
+        ports.diagnostic('attach:createCanonical', reason, error);
+        return { attached: false, listed: undefined, warnings: [reason] };
+    }
+    if (typeof workspace?.attachSession !== 'function') {
+        // THE 0.2.x hypothesis: the host reshaped this return. Before this module the optional
+        // chain made it a no-op with no word said; now it is a named, diagnosable mismatch.
+        const reason = `child ${ports.childId} could NOT be attached: createCanonical returned no "attachSession" method (got ${shape(workspace)}) — the host workspace API changed shape; the child is durable but may not appear in the sidebar`;
+        ports.diagnostic('attach:attachSession', reason, `workspace=${shape(workspace)}`);
+        return { attached: false, listed: undefined, warnings: [reason] };
+    }
+    try {
+        await workspace.attachSession(ports.childId);
+    }
+    catch (error) {
+        const reason = `child ${ports.childId} attach was refused: ${String(error?.message ?? error)}`;
+        ports.diagnostic('attach:attachSession', reason, error);
+        return { attached: false, listed: undefined, warnings: [reason] };
+    }
+    // Attached. Now the part the throw can't tell us: is it actually LISTED?
+    const sq = ports.sessionQuery;
+    if (typeof sq?.listSessions !== 'function') {
+        return {
+            attached: true,
+            listed: undefined,
+            warnings: [`child ${ports.childId} attached, but its listing is UNVERIFIED — no sessionQuery service to ask`],
+        };
+    }
+    const intervalMs = ports.pollIntervalMs ?? 150;
+    const budgetMs = ports.pollBudgetMs ?? 1500;
+    const deadline = Date.now() + budgetMs;
+    for (;;) {
+        let ids = [];
+        try {
+            ids = (await sq.listSessions() ?? []).map((r) => r?.header?.id ?? '');
+        }
+        catch (error) {
+            // a failed LOOKUP is not a failed session — say which one happened
+            const reason = `child ${ports.childId} attached, but its listing could not be verified: sessionQuery.listSessions failed: ${String(error?.message ?? error)}`;
+            ports.diagnostic('attach:verify', reason, error);
+            return { attached: true, listed: undefined, warnings: [reason] };
+        }
+        if (ids.includes(ports.childId)) {
+            // Listed by PERSISTENCE is not the same claim as listed to the BROWSER. The gateway's
+            // `sessionController.list()` is the surface the client renders and can `open()` against,
+            // and on 0.2.0-rc.2 a plugin-created child was present in one and absent from the other
+            // (measured: the door's roster note said `MISSING, 1 sessions` while `listSessions`
+            // listed it) — so a single boolean would have called that a success.
+            const sc = ports.sessionController;
+            if (typeof sc?.list !== 'function') {
+                // Silence here is what cost a round of the 0.2.x hunt: "no warning" got read as "the
+                // gateway lists it". An unverified surface is a STATE and must be delivered as one.
+                const reason = `child ${ports.childId} is listed in the durable session corpus, but its presence in the gateway (browser) session list could not be verified — no "sessionController" service to ask`;
+                ports.diagnostic('attach:gatewayList', reason, `resolved=${shape(ports.sessionController)}`);
+                return { attached: true, listed: true, gatewayListed: undefined, warnings: [reason] };
+            }
+            let gids = [];
+            try {
+                gids = (await sc.list() ?? []).map((r) => r?.sessionId ?? r?.header?.id ?? '');
+            }
+            catch (error) {
+                const reason = `child ${ports.childId} is listed, but the gateway session list could not be verified: ${String(error?.message ?? error)}`;
+                ports.diagnostic('attach:gatewayList', reason, error);
+                return { attached: true, listed: true, gatewayListed: undefined, warnings: [reason] };
+            }
+            if (gids.includes(ports.childId))
+                return { attached: true, listed: true, gatewayListed: true, warnings: [] };
+            const reason = `child ${ports.childId} is in the durable session list but NOT in the gateway's session list (sessionController.list returned ${String(gids.length)} sessions) — the browser cannot show or open it, so the door will not be able to switch`;
+            ports.diagnostic('attach:gatewayList', reason, `gateway=${gids.slice(0, 4).join(',')}`);
+            return { attached: true, listed: true, gatewayListed: false, warnings: [reason] };
+        }
+        if (Date.now() + intervalMs > deadline) {
+            const reason = `child ${ports.childId} was attached but does not appear in the session list within ${String(budgetMs)}ms (${String(ids.length)} sessions listed) — the archive is durable; the sidebar may not show it`;
+            ports.diagnostic('attach:verify', reason, `listed=${ids.slice(0, 4).join(',')}`);
+            return { attached: true, listed: false, warnings: [reason] };
+        }
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+//# sourceMappingURL=attach.js.map

package/lib/attach.js.map

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

package/lib/auto-save.d.ts

@@ -0,0 +1,145 @@
+import { type SaveSessionConfig } from './save-core.ts';
+import { type SessionEventLike } from './types.ts';
+import type { RegistryStore } from './store.ts';
+/** What `subagent/end` carries — the published `SubagentRunEndInfo` subset we read. */
+export interface SubagentEndInfoLike {
+    /** The child agent's id — a durable session id for local (in-process) runs. */
+    id?: string;
+    runId?: string;
+    provider?: string;
+    stopReason?: string;
+}
+export interface AutoSaveChildHeader {
+    id?: string;
+    cwd?: string;
+    parentSession?: string;
+    origin?: string;
+    agentPreset?: string;
+}
+export interface AutoSaveChildView {
+    events: SessionEventLike[];
+    header: AutoSaveChildHeader;
+}
+export interface AutoSaveDeps {
+    /** The preset id a child must carry to be archived (CHAPTERS_PRESET_ID in production). */
+    presetId: string;
+    /** Synchronous live read at emit time (host `agents.get(id)`); undefined when gone. */
+    liveChild: (sessionId: string) => AutoSaveChildView | undefined;
+    /** Durable fallback when the live handle is gone; undefined when unreadable. */
+    durableChild?: ((sessionId: string) => Promise<AutoSaveChildView | undefined>) | undefined;
+    /** The archive itself — saveSession in production, injected for containment tests. */
+    save: (child: AutoSaveChildView) => Promise<{
+        archived: number;
+        skipped: string | null;
+        warnings: string[];
+    }>;
+    warn: (message: string) => void;
+    /** Observability seam: what each settlement decided. Outcome vocabulary pinned by tests. */
+    onSettled?: ((sessionId: string, outcome: string) => void) | undefined;
+}
+/**
+ * The listener factory. Pure against injected reads — the real pipeline is wired
+ * by `wireSubagentAutoSave` below, and both are covered by
+ * tests/{unit,integration} rows. The callback itself is SYNCHRONOUS on the
+ * snapshot (that is the race-avoidance), chained asynchronously per child.
+ */
+export declare function makeSubagentEndListener(deps: AutoSaveDeps): (info: SubagentEndInfoLike) => void;
+/** A minimal slice of the host ctx the wiring reads (structural, cordis-free). */
+export interface AutoSaveCtx {
+    get?(name: string): unknown;
+    logger?: {
+        info?(m: string): void;
+        warn?(m: string): void;
+    };
+}
+export interface AutoSaveWiring extends SaveSessionConfig {
+    presetId: string;
+    /** §5 sync scheduler: every archive is a push point. */
+    scheduler?: {
+        schedule(cwd: string, reason: string): void;
+    } | undefined;
+}
+/**
+ * Bind the listener to the host-plane services: `agents` for the live read,
+ * `sessionQuery` for the durable fallback, `saveSession` for the archive.
+ * Returns the callback to register with `ctx.on('subagent/end', …)`.
+ *
+ * ENRICHMENT DELIBERATELY ABSENT: settlement never runs the annotator — a
+ * ten-child fanout must not fire ten LLM drains; new chapters are pending work
+ * for the idle/afterPush ladders exactly like a `/chapters-save` that skipped
+ * the manual nudge. A test pins that nothing here calls runNow.
+ */
+/**
+ * The ONE payload-bearing durable read (docs/contract.md § Durable reads, issue #58).
+ *
+ * Door 5 needs it because a continuable child is disposed before `subagent/end`; the repair door
+ * (`/chapters-repair`, #60) needs the same thing because re-deriving a chapter is worthless if the read
+ * returns metadata rows. Two copies of "read the log" is how 12 children were archived as empty shells
+ * and the seam still looked alive: `listEvents` succeeds, returns 10 correctly-typed
+ * `SessionEventRecord`s, and none of them has `data`. So this function is exported and pinned by a
+ * source-shape row that fails if a door starts reading the log by hand again.
+ */
+export declare function readDurableSession(get: (name: string) => unknown, sessionId: string, onError?: (message: string) => void): Promise<AutoSaveChildView | undefined>;
+/**
+ * The seventh archive moment (#61, Amendment A): **a rooted child that has never archived.**
+ *
+ * Door 5 is keyed on `origin: 'subagent'`. A `ch-*` continuation child is NOT a subagent — its header
+ * says `origin: user` with a `parentSession` — so no moment was watching it at all. The field case was
+ * `ch-dc3be3ab`: 2,363 events, 414 tool calls, 2 completed turns, `chapters: []`, `reservations: {}`.
+ * Not a failed archive: one never attempted. Its knowledge sits in the log and is invisible to every
+ * search on the machine, which is precisely what this plugin exists to prevent.
+ *
+ * This is the PURE gate — the listener below only does I/O, so the decision is testable (and reviewable)
+ * without a host.
+ */
+export declare function shouldForceChildArchive(input: {
+    header: {
+        origin?: string;
+        agentPreset?: string;
+        parentSession?: string;
+    };
+    /**
+     * Lineage, from ANY of its three real sources — measured 2026-10-22, because the first version of
+     * this gate asked the KERNEL HEADER and silently missed the field case: `ch-dc3be3ab` carries
+     * `parentSession: NONE, origin: undefined`. Lineage lives in (a) the registry row, which
+     * `chapters_continue` writes via `linkChild` at continue-core.ts:520, (b) the header, when the host
+     * sets one, and (c) the id itself — `ch-${newId()}` is minted by continue-core.ts:501, so the prefix
+     * is OUR OWN durable claim that this session is a continuation child. A row that never archived can
+     * still carry the link, and a session with no row at all still carries the prefix.
+     */
+    lineageParent?: string | null | undefined;
+    chapterCount: number;
+    lastArchivedSeq: number;
+    anchor: number;
+    completedTurnsAboveWatermark: number;
+    minTurns: number;
+    enabled: boolean;
+}): {
+    fire: boolean;
+    reason: string;
+};
+export interface ChildArchiveCtx {
+    logger?: {
+        warn?: (m: string) => void;
+        info?: (m: string) => void;
+    };
+}
+export interface ChildArchiveDeps {
+    ctx: ChildArchiveCtx;
+    /** A getter, not a value: the realm's store opens asynchronously and once (#61). */
+    store: () => Promise<RegistryStore>;
+    wiring: AutoSaveWiring;
+    /** config `childAutoArchive`, default true — the operator can close this door. */
+    enabled: boolean;
+    /** config `childAutoArchiveMinTurns`, default 4 — the lag that re-arms it after the first save. */
+    minTurns: number;
+    onArchived?: (id: string, records: number) => void;
+}
+/**
+ * The listener. Save-only — creates NO session and compacts NO surface, so the "no
+ * continuation-creating actions mid-step" rule is not engaged (the same reasoning that let door 5
+ * exist). Fires only on `turn/end`, reads the LIVE session's own payload-bearing events, and is
+ * watermark-idempotent: a re-run finds `nothing-new` and writes nothing.
+ */
+export declare function makeChildArchiveListener(deps: ChildArchiveDeps): (session: unknown, event: unknown) => void;
+export declare function wireSubagentAutoSave(ctx: AutoSaveCtx, store: RegistryStore, wiring: AutoSaveWiring): (info: SubagentEndInfoLike) => void;