@cortexkit/opencode-magic-context 0.41.4 → 0.42.0

package/src/config/removed-agent-config.ts

@@ -0,0 +1,45 @@
+const REMOVED_AGENT_CONFIG_KEY = "sidekick";
+
+export const REMOVED_AGENT_CONFIG_WARNING = `The "${REMOVED_AGENT_CONFIG_KEY}" configuration was removed and is ignored.`;
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/**
+ * Remove the retired agent block before profile resolution or schema parsing.
+ * The same warning array may be shared across user and project layers so one
+ * load reports the removal once while preserving every unrelated setting.
+ */
+export function stripRemovedAgentConfig(
+    rawConfig: Record<string, unknown>,
+    warnings: string[],
+): Record<string, unknown> {
+    let removed = false;
+    const patched = { ...rawConfig };
+
+    if (Object.hasOwn(patched, REMOVED_AGENT_CONFIG_KEY)) {
+        delete patched[REMOVED_AGENT_CONFIG_KEY];
+        removed = true;
+    }
+
+    if (isPlainObject(patched.profiles)) {
+        const profiles = { ...patched.profiles };
+        let profilesChanged = false;
+        for (const [name, value] of Object.entries(profiles)) {
+            if (!isPlainObject(value) || !Object.hasOwn(value, REMOVED_AGENT_CONFIG_KEY)) continue;
+            const profile = { ...value };
+            delete profile[REMOVED_AGENT_CONFIG_KEY];
+            profiles[name] = profile;
+            profilesChanged = true;
+            removed = true;
+        }
+        if (profilesChanged) patched.profiles = profiles;
+    }
+
+    if (removed && !warnings.includes(REMOVED_AGENT_CONFIG_WARNING)) {
+        warnings.push(REMOVED_AGENT_CONFIG_WARNING);
+    }
+
+    return removed ? patched : rawConfig;
+}

package/src/config/removed-agent-source-fence.test.ts

@@ -0,0 +1,56 @@
+/// <reference types="bun-types" />
+
+import { describe, expect, it } from "bun:test";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+const RETIRED_AGENT_NAME = ["side", "kick"].join("");
+const RETIRED_AGENT_PATTERN = new RegExp(RETIRED_AGENT_NAME, "gi");
+const REPO_ROOT = join(__dirname, "..", "..", "..", "..");
+const WARNING_SOURCE = join(
+    REPO_ROOT,
+    "packages",
+    "plugin",
+    "src",
+    "config",
+    "removed-agent-config.ts",
+);
+const SOURCE_ROOTS = [
+    join(REPO_ROOT, "packages", "plugin", "src"),
+    join(REPO_ROOT, "packages", "pi-plugin", "src"),
+    join(REPO_ROOT, "packages", "cli", "src"),
+    join(REPO_ROOT, "packages", "dashboard", "src"),
+    join(REPO_ROOT, "packages", "dashboard", "src-tauri", "src"),
+];
+const SOURCE_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".rs", ".json"]);
+
+function sourceFiles(directory: string, files: string[] = []): string[] {
+    for (const entry of readdirSync(directory)) {
+        if (entry === "node_modules" || entry === "dist") continue;
+        const path = join(directory, entry);
+        const stat = statSync(path);
+        if (stat.isDirectory()) {
+            sourceFiles(path, files);
+            continue;
+        }
+        const extension = entry.slice(entry.lastIndexOf("."));
+        if (stat.isFile() && SOURCE_EXTENSIONS.has(extension)) files.push(path);
+    }
+    return files;
+}
+
+describe("retired agent source fence", () => {
+    it("keeps only the removed-config warning key literal", () => {
+        const offenses: string[] = [];
+        for (const file of SOURCE_ROOTS.flatMap((root) => sourceFiles(root))) {
+            const matches = readFileSync(file, "utf8").match(RETIRED_AGENT_PATTERN) ?? [];
+            const allowed = file === WARNING_SOURCE && matches.length === 1;
+            if (!allowed && matches.length > 0) {
+                offenses.push(`${relative(REPO_ROOT, file)} (${matches.length})`);
+            }
+        }
+
+        expect(offenses).toEqual([]);
+        expect(readFileSync(WARNING_SOURCE, "utf8").match(RETIRED_AGENT_PATTERN)).toHaveLength(1);
+    });
+});

package/src/config/schema/magic-context.test.ts

@@ -23,7 +23,6 @@ describe("MagicContextConfigSchema", () => {
                 cache_ttl: "5m",
                 prompt_surface: { default: "full" },
                 execute_threshold_percentage: 65,
-                protected_tags: 20,
                 clear_reasoning_age: 50,
                 history_budget_percentage: DEFAULT_HISTORY_BUDGET_PERCENTAGE,
                 historian_timeout_ms: DEFAULT_HISTORIAN_TIMEOUT_MS,
@@ -46,7 +45,6 @@ describe("MagicContextConfigSchema", () => {
             expect(result.historian_timeout_ms).toBeGreaterThanOrEqual(10 * 60_000);
             expect(result.historian).toBeUndefined();
             expect(result.dreamer).toBeUndefined();
-            expect(result.sidekick).toBeUndefined();
             expect(result.pi).toBeUndefined();
             expect(result.mural).toEqual({ enabled: false });
         });
@@ -107,6 +105,7 @@ describe("MagicContextConfigSchema", () => {
                 },
                 temporal_awareness: false,
                 keep_subagents: false,
+                debug_rpc: false,
                 todowrite: {
                     enabled: false,
                     overlay: false,
@@ -145,15 +144,6 @@ describe("MagicContextConfigSchema", () => {
                 pi: {
                     subagent_extensions: ["@example/provider", "./extensions/local.ts"],
                 },
-                sidekick: {
-                    disable: false,
-                    model: "qwen-test",
-                    fallback_models: ["qwen-fallback"],
-                    temperature: 0.1,
-                    variant: "fast",
-                    timeout_ms: 12_000,
-                    system_prompt: "Custom prompt",
-                },
                 compaction: {
                     enabled: true,
                 },
@@ -177,19 +167,6 @@ describe("MagicContextConfigSchema", () => {
             ).toBe(false);
         });
 
-        it("applies sidekick defaults when the object is present", () => {
-            const result = MagicContextConfigSchema.parse({
-                sidekick: {
-                    model: "github-copilot/gpt-5.4",
-                },
-            });
-
-            expect(result.sidekick).toEqual({
-                model: "github-copilot/gpt-5.4",
-                timeout_ms: 30000,
-            });
-        });
-
         it("accepts disable on hidden agents and strips deprecated top-level enabled", () => {
             const result = MagicContextConfigSchema.parse({
                 historian: { disable: true },
@@ -203,14 +180,11 @@ describe("MagicContextConfigSchema", () => {
                         "maintain-docs": { schedule: "0 * * * *" },
                     },
                 },
-                sidekick: { disable: true, enabled: true },
             });
 
             expect(result.historian?.disable).toBe(true);
             expect(result.dreamer?.disable).toBe(true);
-            expect(result.sidekick?.disable).toBe(true);
             expect("enabled" in (result.dreamer as Record<string, unknown>)).toBe(false);
-            expect("enabled" in (result.sidekick as Record<string, unknown>)).toBe(false);
             expect(result.dreamer?.tasks["review-user-memories"].schedule).toBe("");
             expect(result.dreamer?.tasks["maintain-docs"].schedule).toBe("0 * * * *");
             expect(result.dreamer?.tasks["classify-memories"].schedule).toBe("0 6 * * *");
@@ -353,10 +327,6 @@ describe("MagicContextConfigSchema", () => {
                                 thinking_level: "inherit",
                             },
                         },
-                        sidekick: {
-                            model: "anthropic/work-sidekick",
-                            fallback_models: ["openai/work-sidekick-fallback"],
-                        },
                     },
                 },
             });
@@ -376,7 +346,6 @@ describe("MagicContextConfigSchema", () => {
                 { model: "opencode/work-historian-fallback", thinking_level: "inherit" },
             ]);
             expect(result.profiles?.work?.dreamer?.omp?.thinking_level).toBe("inherit");
-            expect(result.profiles?.work?.sidekick?.model).toBe("anthropic/work-sidekick");
         });
 
         it("rejects timeout_minutes in a dreamer profile", () => {
@@ -432,7 +401,7 @@ describe("MagicContextConfigSchema", () => {
                     },
                 },
                 { work: { dreamer: { tasks: { verify: { schedule: "0 3 * * *" } } } } },
-                { work: { sidekick: { timeout_ms: 60_000 } } },
+                { work: { dreamer: { timeout_ms: 60_000 } } },
             ];
 
             for (const profiles of profilesWithExcludedFields) {
@@ -667,17 +636,27 @@ describe("MagicContextConfigSchema", () => {
             ).toThrow();
         });
 
-        it("rejects protected_tags greater than 100", () => {
-            expect(() => MagicContextConfigSchema.parse({ protected_tags: 101 })).toThrow();
-        });
-
-        it("rejects protected_tags less than 1", () => {
-            expect(() => MagicContextConfigSchema.parse({ protected_tags: 0 })).toThrow();
+        it("accepts protected_tags at any value including 0 and 101 as deprecated inert key", () => {
+            expect(MagicContextConfigSchema.parse({ protected_tags: 101 }).protected_tags).toBe(
+                101,
+            );
+            expect(MagicContextConfigSchema.parse({ protected_tags: 0 }).protected_tags).toBe(0);
+            expect(MagicContextConfigSchema.parse({ protected_tags: 20 }).protected_tags).toBe(20);
         });
 
-        it("accepts protected_tags boundary values", () => {
-            expect(MagicContextConfigSchema.parse({ protected_tags: 1 }).protected_tags).toBe(1);
-            expect(MagicContextConfigSchema.parse({ protected_tags: 20 }).protected_tags).toBe(20);
+        it("enforces protected_tokens override range at both ends", () => {
+            expect(() => MagicContextConfigSchema.parse({ protected_tokens: 3999 })).toThrow();
+            expect(() => MagicContextConfigSchema.parse({ protected_tokens: 1_000_001 })).toThrow();
+            expect(() => MagicContextConfigSchema.parse({ protected_tokens: 30000.5 })).toThrow();
+            expect(
+                MagicContextConfigSchema.parse({ protected_tokens: 4000 }).protected_tokens,
+            ).toBe(4000);
+            expect(
+                MagicContextConfigSchema.parse({ protected_tokens: 1_000_000 }).protected_tokens,
+            ).toBe(1_000_000);
+            expect(
+                MagicContextConfigSchema.parse({ protected_tokens: 30000 }).protected_tokens,
+            ).toBe(30000);
         });
 
         it("rejects clear_reasoning_age below minimum", () => {

package/src/config/schema/magic-context.ts

@@ -1,7 +1,6 @@
 import { homedir } from "node:os";
 import { z } from "zod";
 import { isValidLanguageCode } from "../../agents/language-directive";
-import { DEFAULT_PROTECTED_TAGS } from "../../features/magic-context/defaults";
 import { isValidCron } from "../../features/magic-context/dreamer/cron";
 import type {
     AGENTIC_DREAM_TASKS,
@@ -446,27 +445,15 @@ const ProfileDreamerSchema = z
         omp: ProfileOmpModelBlockSchema.optional(),
     })
     .strict();
-const ProfileSidekickSchema = AgentOverrideConfigSchema.pick({
-    model: true,
-    fallback_models: true,
-    variant: true,
-})
-    .extend({
-        thinking_level: PiThinkingLevelSchema.describe(
-            "Pi thinking level for the sidekick model selection.",
-        ),
-    })
-    .strict();
 
 export const ConfigProfileSchema = z
     .object({
         historian: ProfileHistorianSchema.optional(),
         dreamer: ProfileDreamerSchema.optional(),
-        sidekick: ProfileSidekickSchema.optional(),
     })
     .strict()
     .describe(
-        "User-owned model-selection overlay. Only historian/dreamer harness model blocks and sidekick model-selection fields are allowed.",
+        "User-owned model-selection overlay. Only historian/dreamer harness model blocks are allowed.",
     );
 export type ConfigProfile = z.infer<typeof ConfigProfileSchema>;
 
@@ -626,15 +613,6 @@ export const DreamerConfigSchema = AgentMetadataSchema.extend({
 });
 export type DreamerConfig = z.infer<typeof DreamerConfigSchema>;
 
-export const SidekickConfigSchema = AgentOverrideConfigSchema.extend({
-    timeout_ms: z.number().default(30000).describe("Timeout for sidekick calls in milliseconds"),
-    system_prompt: z.string().optional().describe("Custom system prompt for sidekick"),
-    thinking_level: PiThinkingLevelSchema.describe(
-        "Pi only: explicit thinking level for sidekick subagent invocations. See historian.pi.thinking_level.",
-    ),
-}).optional();
-export type SidekickConfig = NonNullable<z.infer<typeof SidekickConfigSchema>>;
-
 /**
  * Historian metadata remains harness-independent. Only model resolution moves to
  * the strict opencode, pi, and omp blocks; two_pass and disallowed_tools stay here.
@@ -871,7 +849,8 @@ export interface MagicContextConfig {
      *  this overrides `execute_threshold_percentage` for that model. Useful for hard caps
      *  matching provider input limits. Values above 90% × context_limit are clamped with a warning. */
     execute_threshold_tokens?: { default?: number; [modelKey: string]: number | undefined };
-    protected_tags: number;
+    protected_tokens?: number;
+    protected_tags?: number;
     clear_reasoning_age: number;
     history_budget_percentage: number;
     historian_timeout_ms: number;
@@ -917,10 +896,12 @@ export interface MagicContextConfig {
      *  Graduated from `experimental.temporal_awareness`; default: true. */
     temporal_awareness: boolean;
     /** Debug: when true, keep the child sessions Magic Context spawns for its
-     *  own subagents (historian, dreamer, sidekick, memory-migration) instead
+     *  own subagents (historian, dreamer, memory-migration) instead
      *  of deleting them on success. For short-term inspection/data collection;
      *  kept sessions accumulate until manually cleared. Default false. */
     keep_subagents: boolean;
+    /** Enable loopback-only diagnostic RPCs that expose memory usage and heap snapshots. */
+    debug_rpc?: boolean;
     /**
      * When true (default), deterministic inoperability (schema fence, storage
      * open/migration failure) blocks the primary-session transform with a loud
@@ -1011,7 +992,6 @@ export interface MagicContextConfig {
             max_commits: number;
         };
     };
-    sidekick?: SidekickConfig;
 }
 
 export const MagicContextConfigSchema = z
@@ -1063,7 +1043,7 @@ export const MagicContextConfigSchema = z
             .describe(
                 "Output language for Magic Context's generated content and guidance, as a " +
                     '2-letter ISO 639-1 code (e.g. "tr", "es", "de", "ja", "pt"). When set, the ' +
-                    "historian, dreamer, sidekick, and the agent-guidance block instruct the model to " +
+                    "historian, dreamer, and the agent-guidance block instruct the model to " +
                     "write its PROSE in this language while keeping all structural tokens (XML tags, " +
                     "the five memory category names, code identifiers, file paths) in English. " +
                     "USER-LEVEL ONLY (ignored in project config for security). Unset = today's " +
@@ -1080,7 +1060,7 @@ export const MagicContextConfigSchema = z
                 "Select a named user-owned model profile. A valid project name overrides this user default; an empty string, null, or other non-string project value is ignored with a warning so the user selection still applies. Unknown names warn and use the base configuration.",
             ),
         profiles: ConfigProfilesSchema.optional().describe(
-            "User-level named model profiles. A profile may contain only historian/dreamer model, fallback_models, OpenCode variant, and Pi/OMP thinking_level fields plus sidekick model-selection fields; task execution policy (including timeout_minutes) is excluded. Project configs may select a name but cannot define profiles.",
+            "User-level named model profiles. A profile may contain only historian/dreamer model, fallback_models, OpenCode variant, and Pi/OMP thinking_level fields; task execution policy (including timeout_minutes) is excluded. Project configs may select a name but cannot define profiles.",
         ),
         historian: HistorianConfigSchema.describe(
             "Historian metadata plus independent strict OpenCode, Pi, and OMP execution blocks. Retained metadata stays at historian; model, fallback_models, variant, and thinking_level belong only in historian.opencode, historian.pi, or historian.omp.",
@@ -1153,14 +1133,22 @@ export const MagicContextConfigSchema = z
             .describe(
                 "Absolute token thresholds per model. When matched, overrides execute_threshold_percentage for that model. Accepts `default` for all models or per-model keys. Values above 90% × context_limit are clamped with a warning log. Min 5_000, max 2_000_000.",
             ),
-        protected_tags: z
+        protected_tokens: z
             .number()
-            .min(1)
-            .max(100)
+            .int()
+            .min(4000)
+            .max(1_000_000)
             .optional()
             .describe(
-                "Number of recent tags to protect from dropping (min: 1, max: 100, default: 20)",
+                "Positive integer token floor to protect from automatic reclaim (min: 4_000, max: 1_000_000). When omitted, the derived default is clamp(round(0.05 × usableSoft), min(16_000, round(0.08 × usableSoft)), 64_000).",
             ),
+        protected_tags: z
+            .unknown()
+            .optional()
+            .describe(
+                "Deprecated: number of recent tags to protect. Ignored for behaviour; use protected_tokens instead.",
+            )
+            .meta({ deprecated: true }),
         clear_reasoning_age: z
             .number()
             .min(10)
@@ -1294,7 +1282,13 @@ export const MagicContextConfigSchema = z
             .boolean()
             .default(false)
             .describe(
-                "Debug: keep the child sessions Magic Context spawns for its own subagents (historian, dreamer, sidekick, memory-migration) instead of deleting them on success. Useful for short-term inspection/data collection — their full transcript (prompt, tool calls, token usage, output) stays in the host session store. Kept sessions accumulate until manually cleared; leave false for normal use. Requires a restart to take effect.",
+                "Debug: keep the child sessions Magic Context spawns for its own subagents (historian, dreamer, memory-migration) instead of deleting them on success. Useful for short-term inspection/data collection — their full transcript (prompt, tool calls, token usage, output) stays in the host session store. Kept sessions accumulate until manually cleared; leave false for normal use. Requires a restart to take effect.",
+            ),
+        debug_rpc: z
+            .boolean()
+            .default(false)
+            .describe(
+                "Developer-only: enable authenticated loopback RPCs for memory counters and heap snapshots. Disabled by default. USER-LEVEL ONLY and requires a restart.",
             ),
         fail_closed_blocking: z
             .boolean()
@@ -1459,13 +1453,28 @@ export const MagicContextConfigSchema = z
                 git_commit_indexing: { enabled: false, since_days: 365, max_commits: 2000 },
             })
             .describe("Cross-session memory configuration"),
-        sidekick: SidekickConfigSchema.describe(
-            "Optional sidekick agent configuration for session-start memory retrieval",
-        ),
     })
     .transform((data): MagicContextConfig => {
         return {
             ...data,
-            protected_tags: data.protected_tags ?? DEFAULT_PROTECTED_TAGS,
+            protected_tags: data.protected_tags as number | undefined,
         };
     });
+
+/**
+ * Derived default protected_tokens formula:
+ * clamp(round(0.05 × usableSoft), min(16000, round(0.08 × usableSoft)), 64000)
+ *
+ * Sizing table:
+ *   100k -> 8,000
+ *   200k -> 16,000
+ *   372k -> 18,600
+ *   872k -> 43,600
+ *   1M   -> 50,000
+ */
+export function deriveDefaultProtectedTokens(usableSoft: number): number {
+    const clampedUsable = Math.max(0, usableSoft);
+    const lowerBound = Math.min(16_000, Math.round(0.08 * clampedUsable));
+    const target = Math.round(0.05 * clampedUsable);
+    return Math.min(64_000, Math.max(lowerBound, target));
+}

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*\(/,
+        );
+    });
+});