@cortexkit/opencode-magic-context 0.41.3 → 0.42.0

package/src/shared/child-session-teardown.test.ts

@@ -0,0 +1,218 @@
+/// <reference types="bun-types" />
+
+import { afterEach, describe, expect, mock, test } from "bun:test";
+import { readdirSync, readFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import ts from "typescript";
+
+import { sweepOrphanedRetrospectiveChildren } from "../features/magic-context/dreamer/retrospective-orphan-sweep";
+import { teardownChildSession } from "./child-session-teardown";
+import { _resetKeepSubagentsForTesting, setKeepSubagents } from "./keep-subagents";
+import { Database } from "./sqlite";
+import { closeQuietly } from "./sqlite-helpers";
+
+interface TeardownFixture {
+    client: {
+        session: {
+            delete: ReturnType<typeof mock>;
+            update: ReturnType<typeof mock>;
+        };
+    };
+    calls: string[];
+    deleted: string[];
+    archived: string[];
+    messages: string[];
+}
+
+function teardownFixture(): TeardownFixture {
+    const calls: string[] = [];
+    const deleted: string[] = [];
+    const archived: string[] = [];
+    const messages: string[] = [];
+    return {
+        calls,
+        deleted,
+        archived,
+        messages,
+        client: {
+            session: {
+                update: mock(async ({ path }: { path: { id: string } }) => {
+                    calls.push("archive");
+                    archived.push(path.id);
+                    return {};
+                }),
+                delete: mock(async ({ path }: { path: { id: string } }) => {
+                    calls.push("delete");
+                    deleted.push(path.id);
+                    return {};
+                }),
+            },
+        },
+    };
+}
+
+afterEach(() => {
+    _resetKeepSubagentsForTesting();
+    mock.restore();
+});
+
+describe("teardownChildSession", () => {
+    test("deletes an ordinary child only after its prompt settles", async () => {
+        const fixture = teardownFixture();
+        await teardownChildSession({
+            client: fixture.client,
+            sessionId: "settled-ordinary",
+            sessionDirectory: "/repo",
+            promptSettled: true,
+            privacySensitive: false,
+            context: "ordinary",
+            log: (message) => fixture.messages.push(message),
+        });
+
+        expect(fixture.deleted).toEqual(["settled-ordinary"]);
+        expect(fixture.archived).toEqual([]);
+    });
+
+    test("keeps a settled ordinary child but deletes a settled privacy child under keep_subagents", async () => {
+        setKeepSubagents(true);
+        const ordinary = teardownFixture();
+        await teardownChildSession({
+            client: ordinary.client,
+            sessionId: "kept-ordinary",
+            promptSettled: true,
+            privacySensitive: false,
+            context: "ordinary",
+            log: (message) => ordinary.messages.push(message),
+        });
+        expect(ordinary.deleted).toEqual([]);
+
+        const privacy = teardownFixture();
+        await teardownChildSession({
+            client: privacy.client,
+            sessionId: "deleted-private",
+            promptSettled: true,
+            privacySensitive: true,
+            context: "private",
+            log: (message) => privacy.messages.push(message),
+        });
+        expect(privacy.deleted).toEqual(["deleted-private"]);
+    });
+
+    test("archives an unsettled child before logging, leaves it intact, then the age gate reaps it", async () => {
+        const fixture = teardownFixture();
+        const db = new Database(":memory:");
+        db.exec(`
+            CREATE TABLE session (
+                id TEXT PRIMARY KEY,
+                title TEXT,
+                directory TEXT,
+                time_created INTEGER
+            );
+            INSERT INTO session VALUES (
+                'unsettled-private',
+                'magic-context-dream-map-memories',
+                '/repo',
+                1
+            );
+        `);
+        try {
+            await teardownChildSession({
+                client: fixture.client,
+                sessionId: "unsettled-private",
+                sessionDirectory: "/repo",
+                promptSettled: false,
+                privacySensitive: true,
+                context: "[dreamer] map-memories",
+                log: (message) => {
+                    fixture.calls.push("log");
+                    fixture.messages.push(message);
+                },
+            });
+
+            expect(fixture.calls).toEqual(["archive", "log"]);
+            expect(fixture.deleted).toEqual([]);
+            expect(fixture.messages).toEqual([
+                "[dreamer] map-memories: prompt unsettled — session unsettled-private left to the age-gated sweep",
+            ]);
+            expect(
+                db.prepare("SELECT id FROM session WHERE id = ?").get("unsettled-private"),
+            ).toEqual({
+                id: "unsettled-private",
+            });
+
+            const swept = await sweepOrphanedRetrospectiveChildren({
+                opencodeDb: db,
+                client: fixture.client as never,
+                sessionDirectory: "/repo",
+                staleMs: 1_000,
+                now: 1_002,
+            });
+            expect(swept).toBe(1);
+            expect(fixture.deleted).toEqual(["unsettled-private"]);
+        } finally {
+            closeQuietly(db);
+        }
+    });
+});
+
+function productionTypeScriptFiles(directory: string): string[] {
+    const files: string[] = [];
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+        const path = join(directory, entry.name);
+        if (entry.isDirectory()) files.push(...productionTypeScriptFiles(path));
+        else if (entry.name.endsWith(".ts") && !entry.name.endsWith(".test.ts")) files.push(path);
+    }
+    return files;
+}
+
+function clientSessionDeleteOffsets(path: string, source: string): number[] {
+    const sourceFile = ts.createSourceFile(path, source, ts.ScriptTarget.Latest, true);
+    const offsets: number[] = [];
+    const visit = (node: ts.Node): void => {
+        if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+            const deleteAccess = node.expression;
+            const sessionAccess = deleteAccess.expression;
+            if (
+                deleteAccess.name.text === "delete" &&
+                ts.isPropertyAccessExpression(sessionAccess) &&
+                sessionAccess.name.text === "session" &&
+                (ts.isIdentifier(sessionAccess.expression)
+                    ? sessionAccess.expression.text === "client"
+                    : ts.isPropertyAccessExpression(sessionAccess.expression) &&
+                      sessionAccess.expression.name.text === "client")
+            ) {
+                offsets.push(node.getStart(sourceFile));
+            }
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(sourceFile);
+    return offsets;
+}
+
+describe("child-session delete source fence", () => {
+    test("every client.session.delete call is the age-gated sweep or promptSettled-gated teardown", () => {
+        const sourceRoot = join(import.meta.dir, "..");
+        const sites: string[] = [];
+        for (const path of productionTypeScriptFiles(sourceRoot)) {
+            const source = readFileSync(path, "utf8");
+            for (const offset of clientSessionDeleteOffsets(path, source)) {
+                const line = source.slice(0, offset).split("\n").length;
+                sites.push(`${relative(sourceRoot, path)}:${line}`);
+            }
+        }
+
+        // Directory walk order differs between macOS and Linux; the fence is a set.
+        expect(sites.map((site) => site.replace(/:\d+$/, "")).sort()).toEqual([
+            "features/magic-context/dreamer/retrospective-orphan-sweep.ts",
+            "shared/child-session-teardown.ts",
+        ]);
+        const teardownSource = readFileSync(
+            join(sourceRoot, "shared/child-session-teardown.ts"),
+            "utf8",
+        );
+        expect(teardownSource).toMatch(
+            /if\s*\(\s*promptSettled[\s\S]{0,200}client\.session\.delete\s*\(/,
+        );
+    });
+});

package/src/shared/child-session-teardown.ts

@@ -0,0 +1,66 @@
+import { shouldKeepSubagents } from "./keep-subagents";
+
+interface ChildSessionRequest {
+    path: { id: string };
+    query?: { directory: string };
+}
+
+interface ArchiveChildSessionRequest extends ChildSessionRequest {
+    body: { time: { archived: number } };
+}
+
+export interface ChildSessionTeardownClient {
+    session: {
+        delete(request: ChildSessionRequest): Promise<unknown>;
+    };
+}
+
+export interface TeardownChildSessionArgs {
+    client: ChildSessionTeardownClient;
+    sessionId: string | null;
+    sessionDirectory?: string;
+    promptSettled: boolean;
+    privacySensitive: boolean;
+    context: string;
+    log: (message: string) => void;
+}
+
+/**
+ * Retire a child only after its prompt helper resolves. An unresolved client call
+ * can leave OpenCode's server loop writing, so that row is archived for immediate
+ * UI hiding and retained until the age-gated sweep can delete it safely.
+ *
+ * OpenCode's generated v2 SDK models archival as `session.update` with
+ * `time.archived`; the plugin's legacy path/body client reaches the same PATCH
+ * endpoint, although its generated TypeScript body type does not yet expose time.
+ */
+export async function teardownChildSession(args: TeardownChildSessionArgs): Promise<void> {
+    const { client, sessionId, sessionDirectory, promptSettled, privacySensitive, context, log } =
+        args;
+    if (!sessionId) return;
+
+    const request: ChildSessionRequest = {
+        path: { id: sessionId },
+        ...(sessionDirectory ? { query: { directory: sessionDirectory } } : {}),
+    };
+
+    if (promptSettled && (privacySensitive || !shouldKeepSubagents())) {
+        await client.session.delete(request).catch((error: unknown) => {
+            log(`${context}: session cleanup failed: ${String(error)}`);
+        });
+        return;
+    }
+
+    if (!promptSettled) {
+        const archiveSession = client.session as unknown as {
+            update?: (request: ArchiveChildSessionRequest) => Promise<unknown>;
+        };
+        await archiveSession
+            .update?.({
+                ...request,
+                body: { time: { archived: Date.now() } },
+            })
+            .catch(() => {});
+        log(`${context}: prompt unsettled — session ${sessionId} left to the age-gated sweep`);
+    }
+}

package/src/shared/config-diagnostics.test.ts

@@ -0,0 +1,29 @@
+import { beforeEach, describe, expect, it } from "bun:test";
+
+import {
+    type ConfigParseFailure,
+    claimConfigParseFailuresOnce,
+    resetClaimedConfigParseFailuresForTesting,
+} from "./config-diagnostics";
+
+const failure: ConfigParseFailure = {
+    warningClass: "file-parse",
+    source: "user",
+    path: "/tmp/magic-context.jsonc",
+    line: 1,
+    column: 1,
+    message: "invalid symbol",
+    recovered: true,
+    warning: "/tmp/magic-context.jsonc:1:1: invalid symbol",
+};
+
+describe("config parse warning notice claims", () => {
+    beforeEach(resetClaimedConfigParseFailuresForTesting);
+
+    it("emits each parse failure once per harness surface", () => {
+        expect(claimConfigParseFailuresOnce("opencode", [failure])).toEqual([failure]);
+        expect(claimConfigParseFailuresOnce("opencode", [failure])).toEqual([]);
+        expect(claimConfigParseFailuresOnce("pi", [failure])).toEqual([failure]);
+        expect(claimConfigParseFailuresOnce("pi", [failure])).toEqual([]);
+    });
+});

package/src/shared/config-diagnostics.ts

@@ -0,0 +1,64 @@
+export const CONFIG_WARNING_CLASS = {
+    FILE_PARSE: "file-parse",
+    FILE_IO: "file-io",
+    INVALID_LEAF: "invalid-leaf",
+} as const;
+
+export type ConfigWarningClass = (typeof CONFIG_WARNING_CLASS)[keyof typeof CONFIG_WARNING_CLASS];
+
+export interface ConfigParseFailure {
+    warningClass: typeof CONFIG_WARNING_CLASS.FILE_PARSE;
+    source: "user" | "project";
+    path: string;
+    line: number;
+    column: number;
+    message: string;
+    recovered: boolean;
+    warning: string;
+}
+
+export interface ConfigWarningDetail {
+    warningClass: ConfigWarningClass;
+    source?: "user" | "project";
+    path?: string;
+    line?: number;
+    column?: number;
+    message: string;
+}
+
+export function formatConfigParseStatusLine(failure: ConfigParseFailure): string {
+    const disposition = failure.recovered
+        ? "recovered values applied; fix the file"
+        : "running on defaults";
+    return `Config: PARSE FAILED (${failure.path}:${failure.line}:${failure.column}) — ${disposition}`;
+}
+
+export function formatConfigParseNotice(failures: readonly ConfigParseFailure[]): string {
+    const lines = failures.map(
+        (failure) => `${formatConfigParseStatusLine(failure)}\n${failure.message}`,
+    );
+    return ["⚠️ Magic Context config parse failure", ...lines].join("\n\n");
+}
+
+const claimedFailures = new Set<string>();
+
+function failureKey(surface: string, failure: ConfigParseFailure): string {
+    return `${surface}\0${failure.path}\0${failure.line}\0${failure.column}\0${failure.message}`;
+}
+
+/** Claim parse-failure notices once for each runtime surface in this process. */
+export function claimConfigParseFailuresOnce(
+    surface: "opencode" | "pi",
+    failures: readonly ConfigParseFailure[],
+): ConfigParseFailure[] {
+    return failures.filter((failure) => {
+        const key = failureKey(surface, failure);
+        if (claimedFailures.has(key)) return false;
+        claimedFailures.add(key);
+        return true;
+    });
+}
+
+export function resetClaimedConfigParseFailuresForTesting(): void {
+    claimedFailures.clear();
+}

package/src/shared/config-warning-surface.ts

@@ -0,0 +1,28 @@
+import type { ConfigParseFailure } from "./config-diagnostics";
+import { formatConfigParseStatusLine } from "./config-diagnostics";
+
+export function buildOpenCodeConfigWarningBanner(
+    warnings: readonly string[],
+    parseFailures: readonly ConfigParseFailure[],
+    allParseFailures: readonly ConfigParseFailure[] = parseFailures,
+): string {
+    const parseWarningStrings = new Set(allParseFailures.map((failure) => failure.warning));
+    const ordinaryWarnings = warnings.filter(
+        (warning) =>
+            ![...parseWarningStrings].some((parseWarning) => warning.includes(parseWarning)),
+    );
+    const entries = [
+        ...parseFailures.map(
+            (failure) =>
+                `- **TOP SEVERITY:** ${formatConfigParseStatusLine(failure)} — ${failure.message}`,
+        ),
+        ...ordinaryWarnings.map((warning) => `- ${warning}`),
+    ];
+    return [
+        "## ⚠️ Magic Context Config Warning",
+        "",
+        ...entries,
+        "",
+        "Fix the reported `magic-context.jsonc` file; Magic Context remains enabled.",
+    ].join("\n");
+}

package/src/shared/data-path.ts

@@ -13,16 +13,17 @@ export function getDataDir(): string {
  * Layout:
  *   - OpenCode: `${os.tmpdir()}/opencode/magic-context/`
  *   - Pi:       `${os.tmpdir()}/pi/magic-context/`
+ *   - OMP:      `${os.tmpdir()}/omp/magic-context/`
  *
  * Why a per-harness subtree of `os.tmpdir()`:
  *   1. OpenCode Desktop runs as an Electron app with a permission sandbox.
  *      Writing to arbitrary tmp paths can trigger user-visible permission
  *      prompts; the `${tmpdir}/opencode/` subtree is allow-listed by
  *      OpenCode, so anything we put under it never asks for permission.
- *   2. Splitting OpenCode from Pi keeps their logs and historian dump
- *      directories cleanly separated. `doctor --issue` for each harness
- *      reports diagnostics from the matching subtree, so an OpenCode
- *      issue report never includes Pi log noise (and vice versa).
+ *   2. Splitting harnesses keeps their logs and historian dump directories
+ *      cleanly separated. `doctor --issue` for each harness reports diagnostics
+ *      from the matching subtree, so issue reports do not include another
+ *      harness's log noise.
  *   3. Pi has no permission sandbox, so the path choice is purely
  *      cosmetic for Pi — it just keeps the layout symmetric.
  *
@@ -37,13 +38,13 @@ export function getMagicContextTempDir(harness: HarnessId = getHarness()): strin
 }
 
 /**
- * Standard log file path the plugin writes to. Pi and OpenCode write to
- * SEPARATE logs under their respective harness subtrees so a single
- * machine running both harnesses doesn't interleave session traces.
+ * Standard log file path the plugin writes to. Each harness writes to a
+ * separate log under its own subtree so a machine running multiple harnesses
+ * does not interleave session traces.
  *
  * The plugin's buffered logger calls this on every flush rather than
- * caching, so `setHarness("pi")` taking effect after module load is
- * reflected in the next flush.
+ * caching, so the boot-time `setHarness()` call is reflected in the next
+ * flush.
  */
 export function getMagicContextLogPath(harness: HarnessId = getHarness()): string {
     // An explicit override wins over the harness temp-dir default, so users on

package/src/shared/harness-provider-map.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from "bun:test";
 import {
+    canonicalModelIdentity,
     modelRefLookupOrder,
     ompModelRefToCanonical,
     piModelRefToCanonical,
@@ -8,6 +9,21 @@ import {
 } from "./harness-provider-map";
 
 describe("harness-provider-map", () => {
+    describe("canonicalModelIdentity", () => {
+        it("collapses Astra route aliases without changing unrelated Copilot models", () => {
+            for (const ref of [
+                "openai/gpt-6-astra",
+                "openai-codex/gpt-6-astra",
+                "github-copilot/gpt-6-astra",
+            ]) {
+                expect(canonicalModelIdentity(ref)).toBe("openai/gpt-6-astra");
+            }
+            expect(canonicalModelIdentity("github-copilot/claude-opus-5")).toBe(
+                "github-copilot/claude-opus-5",
+            );
+        });
+    });
+
     describe("resolveModelRefForPi (canonical -> Pi, used when spawning)", () => {
         it("maps the diverging auth-plugin providers, preserving the model id", () => {
             expect(resolveModelRefForPi("openai/gpt-5.5")).toBe("openai-codex/gpt-5.5");

package/src/shared/harness-provider-map.ts

@@ -58,6 +58,10 @@ const OMP_TO_CANONICAL_PROVIDER: Readonly<Record<string, string>> = {
     "opencode-zen": "opencode",
 };
 
+const CANONICAL_MODEL_IDENTITY_ALIASES: Readonly<Record<string, string>> = {
+    "github-copilot/gpt-6-astra": "openai/gpt-6-astra",
+};
+
 /** Remap only the provider prefix (text before the first "/"), preserving the
  *  model id verbatim. No "/", empty provider, or unmapped provider -> unchanged.
  *  Lookups are own-property only, so provider ids that collide with
@@ -72,6 +76,17 @@ function remapProviderPrefix(ref: string, map: Readonly<Record<string, string>>)
     return `${map[provider]}${ref.slice(slash)}`;
 }
 
+/**
+ * Canonicalize only for identity comparisons and cache policy; callers must not
+ * use the result as a provider spawn route. Provider-wide Pi/OMP aliases are
+ * normalized first; model-specific aliases stay explicit because GitHub Copilot
+ * also serves non-OpenAI model families.
+ */
+export function canonicalModelIdentity(ref: string): string {
+    const harnessCanonical = piModelRefToCanonical(ompModelRefToCanonical(ref));
+    return CANONICAL_MODEL_IDENTITY_ALIASES[harnessCanonical.toLowerCase()] ?? harnessCanonical;
+}
+
 /** Pi-native `provider/model` -> canonical (OpenCode). Identity when unmapped.
  *  Used by the Pi setup wizard so configs it writes stay OpenCode-readable. */
 export function piModelRefToCanonical(ref: string): string {

package/src/shared/jsonc-parser.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "bun:test";
 
-import { parseJsonc } from "./jsonc-parser";
+import { parseJsonc, parseJsoncRecovering } from "./jsonc-parser";
 
 describe("parseJsonc prototype-pollution hardening", () => {
     it("rejects dangerous keys recursively, including inside arrays", () => {
@@ -30,4 +30,17 @@ describe("parseJsonc prototype-pollution hardening", () => {
         expect(Object.getPrototypeOf(items[0])).toBe(Object.prototype);
         expect("polluted" in items[0]).toBe(false);
     });
+
+    it("preserves hardening when tolerant recovery encounters __proto__", () => {
+        const rejected: string[] = [];
+        const parsed = parseJsoncRecovering<Record<string, unknown>>(
+            '\\{\n"__proto__":{"polluted":true},"cache_ttl":"1h"}',
+            { onRejectedKey: (path) => rejected.push(path.join(".")) },
+        );
+
+        expect(parsed.value).toEqual({ cache_ttl: "1h" });
+        expect(parsed.issues[0]).toMatchObject({ line: 1, column: 1 });
+        expect(rejected).toContain("__proto__");
+        expect(({} as { polluted?: boolean }).polluted).toBeUndefined();
+    });
 });

package/src/shared/jsonc-parser.ts

@@ -1,5 +1,15 @@
 import { existsSync, readFileSync } from "node:fs";
 
+import {
+    type ParseError,
+    parse as parseJsoncDocument,
+    printParseErrorCode,
+} from "jsonc-parser/lib/esm/main.js";
+// ^ Deep ESM import on purpose, same as jsonc-edit.ts: the package's "main" is a
+// UMD bundle whose runtime-relative requires (`./impl/format`) survive bundling
+// verbatim and crash the plugin at boot. The build:dists load-probe gate exists
+// to catch exactly this; do not import the bare package name.
+
 export function stripJsonComments(content: string): string {
     let result = "";
     let inString = false;
@@ -155,6 +165,89 @@ export function sanitizeParsedJson<T>(
     return sanitized as T;
 }
 
+export interface JsoncParseIssue {
+    line: number;
+    column: number;
+    offset: number;
+    length: number;
+    message: string;
+}
+
+export interface RecoveringJsoncParseResult<T> {
+    value: T;
+    issues: JsoncParseIssue[];
+}
+
+function lineAndColumnAt(content: string, offset: number): { line: number; column: number } {
+    const before = content.slice(0, Math.max(0, offset));
+    const lines = before.split(/\r?\n/);
+    return { line: lines.length, column: (lines.at(-1)?.length ?? 0) + 1 };
+}
+
+function parseIssue(content: string, error: ParseError): JsoncParseIssue {
+    const location = lineAndColumnAt(content, error.offset);
+    const code = printParseErrorCode(error.error);
+    const message = code.replace(/([a-z])([A-Z])/g, "$1 $2").toLowerCase();
+    return {
+        ...location,
+        offset: error.offset,
+        length: error.length,
+        message,
+    };
+}
+
+/**
+ * Parse JSONC with the same recovery grammar used by the runtime config loaders.
+ * Syntax diagnostics are never discarded: callers must surface every non-empty
+ * `issues` result even when the parser recovered a usable object.
+ */
+function normalizeJsoncParserObjects(
+    value: unknown,
+    options: ParsedJsonSanitizerOptions,
+    path: string[] = [],
+): unknown {
+    if (Array.isArray(value)) {
+        return value.map((entry, index) =>
+            normalizeJsoncParserObjects(entry, options, [...path, String(index)]),
+        );
+    }
+    if (value === null || typeof value !== "object") return value;
+
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        // jsonc-parser assigns an own "__proto__" property through normal JS
+        // assignment, which changes only this parsed object's prototype. Treat
+        // that prototype as the rejected key and copy only its own safe fields.
+        options.onRejectedKey?.([...path, "__proto__"]);
+    }
+    const normalized: Record<string, unknown> = {};
+    for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+        Object.defineProperty(normalized, key, {
+            configurable: true,
+            enumerable: true,
+            writable: true,
+            value: normalizeJsoncParserObjects(entry, options, [...path, key]),
+        });
+    }
+    return normalized;
+}
+
+export function parseJsoncRecovering<T = unknown>(
+    content: string,
+    options: ParsedJsonSanitizerOptions = {},
+): RecoveringJsoncParseResult<T> {
+    const errors: ParseError[] = [];
+    const parsed = parseJsoncDocument(content, errors, {
+        allowTrailingComma: true,
+        disallowComments: false,
+        allowEmptyContent: false,
+    }) as T;
+    return {
+        value: sanitizeParsedJson(normalizeJsoncParserObjects(parsed, options) as T, options),
+        issues: errors.map((error) => parseIssue(content, error)),
+    };
+}
+
 export function parseJsonc<T = unknown>(
     content: string,
     options: ParsedJsonSanitizerOptions = {},

package/src/shared/keep-subagents.ts

@@ -1,19 +1,14 @@
 /**
- * Debug / data-collection switch: when enabled, Magic Context does NOT delete
- * the child sessions it spawns for its own subagents (historian, dreamer,
- * sidekick, memory-migration, key-files, user-memory review, recomp).
+ * Debug / data-collection switch for settled ordinary child sessions
+ * (historian and memory migration). Privacy-sensitive Dreamer and
+ * smart-note children are still deleted after their prompts settle.
  *
- * By default these child sessions are deleted on success (only FAILED ones are
- * kept for debugging). With `keep_subagents: true` ALL of them are retained, so
- * their full transcript — prompt, tool calls, token usage, model output — stays
- * inspectable in OpenCode's session store / the dashboard. Intended for
- * short-term data collection (e.g. profiling what the dreamer actually does)
- * before the dreamer v2 overhaul, NOT for steady-state use — kept sessions
- * accumulate in the host's session DB until manually cleared.
+ * Unsettled children are never deleted inline because OpenCode's server loop may
+ * still be writing after a client timeout or abort. They remain for the
+ * age-gated sweep; privacy-sensitive rows are swept even when this switch is on.
  *
- * Process-global, set once at boot from config (mirrors `harness.ts`). A
- * config change requires a restart to take effect. NEVER thread this through
- * per-call args — it's a coarse, boot-time debug toggle.
+ * Process-global, set once at boot from config (mirrors `harness.ts`). A config
+ * change requires a restart to take effect.
  */
 let keepSubagents = false;
 
@@ -22,7 +17,7 @@ export function setKeepSubagents(value: boolean): void {
     keepSubagents = value === true;
 }
 
-/** True when subagent child sessions should be retained (not deleted). */
+/** True when settled ordinary child sessions should be retained. */
 export function shouldKeepSubagents(): boolean {
     return keepSubagents;
 }