@mclawnet/swarm 0.1.13 → 0.1.15

package/dist/__tests__/introspection-source.test.js

@@ -0,0 +1,1051 @@
+// M8.2 + M8 hotfix I1/I2 — IntrospectionSource unit tests.
+//
+// Verifies opt-in gate, cooldown gate, self-suppression, fire-and-forget
+// swarm spawn, output parsing on a SECOND pick (ingest cycle), idea POST
+// cap + priority enforcement, hub-outage cooldown rewind (S1), and the
+// pending-swarm bookkeeping.
+//
+// The two-phase pick model: first pick() spawns + persists
+// `pendingIntrospectionSwarmId`; the second pick() observes the pending
+// swarm is terminal, parses the queen's output and POSTs the cohort.
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { encodeCwd } from "@mclawnet/shared";
+import { createIntrospectionSource, parseCandidatesOutput, buildIntrospectionTaskPrompt, INTROSPECTION_SOURCE_ROLE, INTROSPECTION_SOURCE_TAG, SPAWNER_COMPLETE_MTIME_GUARD_MS, SPAWNER_COMPLETE_HARD_TIMEOUT_MS, } from "../always-on/task-sources/introspection-source.js";
+const PROJECT_ROOT = "/proj-introspect";
+const PROJECT_ID = encodeCwd(PROJECT_ROOT);
+function makeIdea(over) {
+    return {
+        id: "i1",
+        userId: "u1",
+        projectId: PROJECT_ID,
+        title: "title",
+        body: "",
+        status: "idea",
+        priority: "low",
+        tags: [],
+        sourceSessionId: null,
+        sourceMessageId: null,
+        sourceSwarmId: null,
+        sourceRole: null,
+        linkedSessionId: null,
+        linkedSwarmTaskId: null,
+        researchReports: [],
+        researchKind: null,
+        createdAt: "2026-01-01T00:00:00.000Z",
+        updatedAt: "2026-01-01T00:00:00.000Z",
+        ...over,
+    };
+}
+function makeClient(hooks = {}) {
+    const creates = [];
+    const client = {
+        creates,
+        async list() {
+            return hooks.listResults ?? [];
+        },
+        async get() {
+            return null;
+        },
+        async patch(id, partial) {
+            return makeIdea({ id, ...partial });
+        },
+        async create(input) {
+            if (hooks.throwOnCreate)
+                throw new Error("hub down");
+            hooks.onCreate?.(input);
+            const created = makeIdea({
+                id: `created-${creates.length + 1}`,
+                title: input.title,
+                body: input.body ?? "",
+                priority: input.priority ?? "low",
+                status: input.status ?? "idea",
+                tags: input.tags ?? [],
+                sourceRole: input.sourceRole ?? null,
+                sourceSwarmId: input.sourceSwarmId ?? null,
+                projectId: input.projectId ?? null,
+            });
+            creates.push(created);
+            return created;
+        },
+    };
+    return client;
+}
+function makeCoord(opts = {}) {
+    // Preserve null vs undefined distinction: `null` means "gone from registry"
+    // (getSwarm returns undefined); omitted means default ("completed").
+    let currentStatus = "swarmStatus" in opts ? opts.swarmStatus : "completed";
+    const coord = {
+        create: opts.createImpl ?? (async () => { }),
+        getSwarm: (_id) => currentStatus === null ? undefined : { status: currentStatus },
+        destroy: async (id) => {
+            opts.onDestroy?.(id);
+            // Simulate real coordinator: destroy evicts the swarm from the
+            // registry so a subsequent isTerminalSwarm() returns "unknown".
+            // Without this the destroy-fallback test could only verify the
+            // method was called, not that it actually cleaned up.
+            currentStatus = null;
+        },
+        complete: async (id) => {
+            opts.onComplete?.(id);
+            if (opts.completeThrows)
+                throw new Error("coord.complete failed");
+            if (opts.mutateStatusOnComplete) {
+                // Mirror real coordinator: complete() ends with runRetroAndCleanup,
+                // whose last step is `this.swarms.delete(swarmId)`. After complete,
+                // getSwarm returns undefined and isTerminalSwarm reports "unknown",
+                // NOT "completed". Setting currentStatus to null reflects this so
+                // tests don't assert code paths that production can't reach.
+                currentStatus = null;
+            }
+        },
+        fail: async (id) => {
+            opts.onFail?.(id);
+        },
+    };
+    return coord;
+}
+function makeConfig(over = {}) {
+    return {
+        mode: "active",
+        dailyBudget: 3,
+        taskSources: { introspection: true },
+        introspectionCooldownHours: 24,
+        ...over,
+    };
+}
+// ── parseCandidatesOutput ──────────────────────────────────────────────
+describe("parseCandidatesOutput", () => {
+    it("parses a clean JSON-array file", () => {
+        const out = parseCandidatesOutput('[{"title":"a","body":"x"}]');
+        expect(out).toEqual([{ title: "a", body: "x" }]);
+    });
+    it("recovers a JSON array that follows narrative text", () => {
+        const raw = `the queen thinks:\nhere are some ideas\n[{"title":"hello","body":"world","priority":"medium"}]`;
+        const out = parseCandidatesOutput(raw);
+        expect(out).toEqual([{ title: "hello", body: "world", priority: "medium" }]);
+    });
+    it("returns [] on empty / non-array input", () => {
+        expect(parseCandidatesOutput("")).toEqual([]);
+        expect(parseCandidatesOutput("not json")).toEqual([]);
+        expect(parseCandidatesOutput('{"foo":1}')).toEqual([]);
+    });
+    it("drops entries without a title", () => {
+        const out = parseCandidatesOutput('[{"body":"oops"},{"title":"keeper"}]');
+        expect(out).toEqual([{ title: "keeper", body: "" }]);
+    });
+    it("uses the last [ in the file when multiple arrays appear", () => {
+        const raw = `[1,2,3] then\n[{"title":"newer"}]`;
+        const out = parseCandidatesOutput(raw);
+        expect(out).toEqual([{ title: "newer", body: "" }]);
+    });
+});
+describe("buildIntrospectionTaskPrompt", () => {
+    it("embeds projectRoot and absolute output path", () => {
+        const prompt = buildIntrospectionTaskPrompt("/p", "/p/.clawnet/introspection/swarm-1.json");
+        expect(prompt).toContain("/p");
+        expect(prompt).toContain("/p/.clawnet/introspection/swarm-1.json");
+        expect(prompt).toContain("at most 3 items");
+    });
+});
+// ── IntrospectionSource gating ─────────────────────────────────────────
+describe("IntrospectionSource gating", () => {
+    it("returns null when taskSources.introspection !== true", async () => {
+        const cfg = makeConfig({ taskSources: { introspection: false } });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord(),
+            getConfig: () => cfg,
+            updateConfig: async (_pr) => { },
+        });
+        expect(await source.pick(PROJECT_ROOT)).toBeNull();
+    });
+    it("defaults to off when taskSources entirely absent", async () => {
+        const cfg = makeConfig({ taskSources: undefined });
+        const created = vi.fn(async () => { });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord({ createImpl: created }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr) => { },
+        });
+        expect(await source.pick(PROJECT_ROOT)).toBeNull();
+        expect(created).not.toHaveBeenCalled();
+    });
+    it("returns null when cooldown not elapsed", async () => {
+        const cfg = makeConfig({
+            lastIntrospectionAt: new Date("2026-06-06T11:00:00Z").toISOString(),
+            introspectionCooldownHours: 24,
+        });
+        const created = vi.fn(async () => { });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord({ createImpl: created }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr) => { },
+            clock: () => new Date("2026-06-06T12:00:00Z"),
+        });
+        expect(await source.pick(PROJECT_ROOT)).toBeNull();
+        expect(created).not.toHaveBeenCalled();
+    });
+    it("suppresses next cycle when lastIntrospectionRejected=true is backed by an all-archived cohort", async () => {
+        // Setup: prior cycle ran 2 days ago and all its produced ideas are archived.
+        const lastAt = new Date("2026-06-06T00:00:00Z").toISOString();
+        const archivedCohort = [
+            makeIdea({
+                id: "i1",
+                status: "archived",
+                sourceRole: INTROSPECTION_SOURCE_ROLE,
+                tags: [INTROSPECTION_SOURCE_TAG],
+                createdAt: "2026-06-06T00:01:00Z",
+            }),
+        ];
+        const cfg = makeConfig({
+            lastIntrospectionAt: lastAt,
+            lastIntrospectionRejected: true,
+        });
+        const created = vi.fn(async () => { });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient({ listResults: archivedCohort }),
+            swarmCoordinator: makeCoord({ createImpl: created }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr) => { },
+            clock: () => new Date("2026-06-08T00:00:00Z"),
+        });
+        expect(await source.pick(PROJECT_ROOT)).toBeNull();
+        expect(created).not.toHaveBeenCalled();
+    });
+    it("clears stale lastIntrospectionRejected when there's no lastIntrospectionAt (defensive)", async () => {
+        // The flag without a cooldown breadcrumb is treated as orphaned: clear
+        // it and let the cycle proceed. Otherwise a corrupted config could lock
+        // introspection forever with no way to recover via the cohort sync.
+        const cfg = makeConfig({
+            lastIntrospectionRejected: true,
+            // No lastIntrospectionAt set.
+        });
+        const created = vi.fn(async () => { });
+        const patches = [];
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord({ createImpl: created }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+        });
+        await source.pick(PROJECT_ROOT);
+        expect(patches[0]).toEqual({ lastIntrospectionRejected: null });
+        expect(created).toHaveBeenCalledTimes(1);
+    });
+});
+// ── Fire-and-forget spawn + ingest ─────────────────────────────────────
+describe("IntrospectionSource fire-and-forget happy path", () => {
+    let tmpHome;
+    let projectRoot;
+    let outputPath;
+    beforeEach(() => {
+        tmpHome = mkdtempSync(join(tmpdir(), "introspect-"));
+        projectRoot = tmpHome; // use the temp dir as projectRoot so writes work
+        outputPath = join(projectRoot, ".clawnet", "introspection", "swarm-x.json");
+    });
+    afterEach(() => {
+        rmSync(tmpHome, { recursive: true, force: true });
+    });
+    it("spawn cycle: pick() persists pendingIntrospectionSwarmId and returns null WITHOUT awaiting swarm", async () => {
+        // No output file written yet → if pick() were awaiting the swarm we'd
+        // still see zero POSTs anyway, but we ALSO want to see the pending
+        // breadcrumb persisted as proof we didn't block on the swarm.
+        const client = makeClient();
+        // CI tsc inferred mock.calls[0] as [] (no args) and tripped TS2493 on
+        // index access below. Give the spy an explicit signature so calls[0] is
+        // [swarmId, opts].
+        const created = vi.fn(async (_swarmId, _opts) => { });
+        const patches = [];
+        const cfg = makeConfig();
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: makeCoord({ createImpl: created }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+            generateSwarmId: () => "swarm-x",
+            clock: () => new Date("2026-06-07T00:00:00Z"),
+        });
+        const result = await source.pick(projectRoot);
+        expect(result).toBeNull();
+        expect(created).toHaveBeenCalledTimes(1);
+        // PR-B D11 — introspection source stamps kind so UI / GC / shipment
+        // can tell these read-only "produce ideas" swarms apart from ordinary
+        // always-on cycles + user-driven chat swarms.
+        expect(created.mock.calls[0][1]).toMatchObject({ kind: "always-on-introspection" });
+        expect(client.creates).toHaveLength(0);
+        // Pending breadcrumb persisted along with cooldown stamp.
+        expect(patches.at(-1)).toMatchObject({
+            lastIntrospectionAt: "2026-06-07T00:00:00.000Z",
+            lastIntrospectionRejected: false,
+            pendingIntrospectionSwarmId: "swarm-x",
+        });
+    });
+    it("ingest cycle: pick() with pending swarm + terminal status reads output and POSTs", async () => {
+        mkdirSync(join(projectRoot, ".clawnet", "introspection"), { recursive: true });
+        writeFileSync(outputPath, JSON.stringify([
+            { title: "Idea A", body: "body A", priority: "high" },
+            { title: "Idea B", body: "body B" },
+        ]));
+        const client = makeClient();
+        const completedCalls = [];
+        const cfg = makeConfig({
+            // Pretend a prior spawn cycle landed a pending breadcrumb.
+            pendingIntrospectionSwarmId: "swarm-x",
+            lastIntrospectionAt: new Date("2026-06-07T00:00:00Z").toISOString(),
+        });
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: makeCoord({
+                swarmStatus: "completed",
+                onComplete: (id) => completedCalls.push(id),
+            }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                Object.assign(cfg, patch);
+                // simulate persistence by deleting the field when null
+                if ("pendingIntrospectionSwarmId" in patch && patch.pendingIntrospectionSwarmId === null) {
+                    delete cfg.pendingIntrospectionSwarmId;
+                }
+            },
+            clock: () => new Date("2026-06-07T01:00:00Z"),
+        });
+        const result = await source.pick(projectRoot);
+        expect(result).toBeNull();
+        expect(client.creates).toHaveLength(2);
+        expect(client.creates[0].priority).toBe("low");
+        expect(client.creates[0].title).toBe("Idea A");
+        expect(client.creates[0].tags).toContain(INTROSPECTION_SOURCE_TAG);
+        expect(client.creates[0].sourceRole).toBe(INTROSPECTION_SOURCE_ROLE);
+        expect(client.creates[0].sourceSwarmId).toBe("swarm-x");
+        // S2 hotfix: coordinator.complete was called on the terminal swarm.
+        expect(completedCalls).toEqual(["swarm-x"]);
+        // Pending breadcrumb cleared so next cycle can spawn fresh.
+        expect(cfg.pendingIntrospectionSwarmId).toBeUndefined();
+    });
+    it("ingest cycle: caps at 3 ideas even when swarm produced 5", async () => {
+        mkdirSync(join(projectRoot, ".clawnet", "introspection"), { recursive: true });
+        writeFileSync(outputPath, JSON.stringify(Array.from({ length: 5 }, (_, i) => ({ title: `Idea ${i + 1}`, body: "" }))));
+        const client = makeClient();
+        const cfg = makeConfig({ pendingIntrospectionSwarmId: "swarm-x" });
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: makeCoord({ swarmStatus: "completed" }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                Object.assign(cfg, patch);
+            },
+        });
+        await source.pick(projectRoot);
+        expect(client.creates).toHaveLength(3);
+        expect(client.creates.map((i) => i.title)).toEqual([
+            "Idea 1",
+            "Idea 2",
+            "Idea 3",
+        ]);
+    });
+    it("ingest cycle: pending swarm still running → returns null, leaves pending", async () => {
+        const client = makeClient();
+        const cfg = makeConfig({ pendingIntrospectionSwarmId: "swarm-x" });
+        const patches = [];
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: {
+                create: async () => { },
+                getSwarm: () => ({ status: "running" }),
+                destroy: async () => { },
+                complete: async () => { },
+            },
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+            },
+        });
+        expect(await source.pick(projectRoot)).toBeNull();
+        expect(client.creates).toHaveLength(0);
+        // No update at all — pending stays as-is.
+        expect(patches).toHaveLength(0);
+        expect(cfg.pendingIntrospectionSwarmId).toBe("swarm-x");
+    });
+    it("ingest cycle: malformed output clears pending and posts nothing", async () => {
+        mkdirSync(join(projectRoot, ".clawnet", "introspection"), { recursive: true });
+        writeFileSync(outputPath, "this is not json at all");
+        const client = makeClient();
+        const cfg = makeConfig({ pendingIntrospectionSwarmId: "swarm-x" });
+        let lastPatch = null;
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: makeCoord({ swarmStatus: "completed" }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                lastPatch = patch;
+                Object.assign(cfg, patch);
+                if (patch.pendingIntrospectionSwarmId === null) {
+                    delete cfg.pendingIntrospectionSwarmId;
+                }
+            },
+        });
+        await source.pick(projectRoot);
+        expect(client.creates).toHaveLength(0);
+        expect(lastPatch.pendingIntrospectionSwarmId).toBeNull();
+        expect(cfg.pendingIntrospectionSwarmId).toBeUndefined();
+    });
+    it("ingest cycle: missing output file clears pending and posts nothing", async () => {
+        const client = makeClient();
+        const cfg = makeConfig({ pendingIntrospectionSwarmId: "swarm-y" });
+        let lastPatch = null;
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: makeCoord({ swarmStatus: "completed" }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                lastPatch = patch;
+                Object.assign(cfg, patch);
+                if (patch.pendingIntrospectionSwarmId === null) {
+                    delete cfg.pendingIntrospectionSwarmId;
+                }
+            },
+            generateSwarmId: () => "swarm-y",
+        });
+        await source.pick(projectRoot);
+        expect(client.creates).toHaveLength(0);
+        expect(lastPatch.pendingIntrospectionSwarmId).toBeNull();
+    });
+    it("spawn failure: bumps cooldown so no retry storm; pending NOT persisted", async () => {
+        const client = makeClient();
+        const patches = [];
+        const cfg = makeConfig();
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: makeCoord({
+                createImpl: async () => {
+                    throw new Error("spawn failed");
+                },
+            }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+            clock: () => new Date("2026-06-07T03:00:00Z"),
+        });
+        await source.pick(projectRoot);
+        expect(client.creates).toHaveLength(0);
+        // Cooldown bumped; pending NOT set (the spawn was rejected by coordinator).
+        expect(patches[0]).toEqual({
+            lastIntrospectionAt: "2026-06-07T03:00:00.000Z",
+            lastIntrospectionRejected: false,
+        });
+        expect(cfg.pendingIntrospectionSwarmId).toBeUndefined();
+    });
+    it("S1 hotfix: hub outage during POSTs rewinds lastIntrospectionAt so retry comes sooner", async () => {
+        mkdirSync(join(projectRoot, ".clawnet", "introspection"), { recursive: true });
+        writeFileSync(outputPath, JSON.stringify([{ title: "Lonely Idea", body: "" }]));
+        const client = makeClient({ throwOnCreate: true });
+        const patches = [];
+        const cfg = makeConfig({
+            pendingIntrospectionSwarmId: "swarm-x",
+            lastIntrospectionAt: new Date("2026-06-07T00:00:00Z").toISOString(),
+            introspectionCooldownHours: 24,
+        });
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: makeCoord({ swarmStatus: "completed" }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+            clock: () => new Date("2026-06-08T00:00:00Z"),
+        });
+        await source.pick(projectRoot);
+        expect(client.creates).toHaveLength(0);
+        // The patch should rewind lastIntrospectionAt to (now - 23h). At
+        // clock=2026-06-08T00:00:00Z the rewound stamp is 2026-06-07T01:00:00Z.
+        expect(patches[0]).toMatchObject({
+            pendingIntrospectionSwarmId: null,
+            lastIntrospectionAt: "2026-06-07T01:00:00.000Z",
+        });
+    });
+});
+// ── R3 I-A: terminal-state cleanup covers all 4 statuses ───────────────
+describe("IntrospectionSource terminal-state cleanup (R3 I-A)", () => {
+    let tmpHome;
+    let projectRoot;
+    let outputPath;
+    beforeEach(() => {
+        tmpHome = mkdtempSync(join(tmpdir(), "introspect-r3-"));
+        projectRoot = tmpHome;
+        outputPath = join(projectRoot, ".clawnet", "introspection", "swarm-r3.json");
+        mkdirSync(join(projectRoot, ".clawnet", "introspection"), { recursive: true });
+        writeFileSync(outputPath, JSON.stringify([{ title: "x", body: "" }]));
+    });
+    afterEach(() => {
+        rmSync(tmpHome, { recursive: true, force: true });
+    });
+    it("status=completed → calls coordinator.complete (not fail)", async () => {
+        const completes = [];
+        const fails = [];
+        const cfg = makeConfig({ pendingIntrospectionSwarmId: "swarm-r3" });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord({
+                swarmStatus: "completed",
+                onComplete: (id) => completes.push(id),
+                onFail: (id) => fails.push(id),
+            }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                Object.assign(cfg, patch);
+                if ("pendingIntrospectionSwarmId" in patch && patch.pendingIntrospectionSwarmId === null) {
+                    delete cfg.pendingIntrospectionSwarmId;
+                }
+            },
+        });
+        await source.pick(projectRoot);
+        expect(completes).toEqual(["swarm-r3"]);
+        expect(fails).toEqual([]);
+        expect(cfg.pendingIntrospectionSwarmId).toBeUndefined();
+    });
+    it("status=failed → calls coordinator.fail (not complete)", async () => {
+        const completes = [];
+        const fails = [];
+        const cfg = makeConfig({ pendingIntrospectionSwarmId: "swarm-r3" });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord({
+                swarmStatus: "failed",
+                onComplete: (id) => completes.push(id),
+                onFail: (id) => fails.push(id),
+            }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                Object.assign(cfg, patch);
+                if ("pendingIntrospectionSwarmId" in patch && patch.pendingIntrospectionSwarmId === null) {
+                    delete cfg.pendingIntrospectionSwarmId;
+                }
+            },
+        });
+        await source.pick(projectRoot);
+        expect(fails).toEqual(["swarm-r3"]);
+        expect(completes).toEqual([]);
+        expect(cfg.pendingIntrospectionSwarmId).toBeUndefined();
+    });
+    it("status=cancelled → no coordinator call (already terminal externally) but pending cleared", async () => {
+        const completes = [];
+        const fails = [];
+        const cfg = makeConfig({ pendingIntrospectionSwarmId: "swarm-r3" });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord({
+                swarmStatus: "cancelled",
+                onComplete: (id) => completes.push(id),
+                onFail: (id) => fails.push(id),
+            }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                Object.assign(cfg, patch);
+                if ("pendingIntrospectionSwarmId" in patch && patch.pendingIntrospectionSwarmId === null) {
+                    delete cfg.pendingIntrospectionSwarmId;
+                }
+            },
+        });
+        await source.pick(projectRoot);
+        expect(completes).toEqual([]);
+        expect(fails).toEqual([]);
+        expect(cfg.pendingIntrospectionSwarmId).toBeUndefined();
+    });
+    it("status=unknown (gone from registry) → no coordinator call but pending cleared", async () => {
+        const completes = [];
+        const fails = [];
+        const cfg = makeConfig({ pendingIntrospectionSwarmId: "swarm-r3" });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord({
+                swarmStatus: null, // → getSwarm returns undefined → status=unknown
+                onComplete: (id) => completes.push(id),
+                onFail: (id) => fails.push(id),
+            }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                Object.assign(cfg, patch);
+                if ("pendingIntrospectionSwarmId" in patch && patch.pendingIntrospectionSwarmId === null) {
+                    delete cfg.pendingIntrospectionSwarmId;
+                }
+            },
+        });
+        await source.pick(projectRoot);
+        expect(completes).toEqual([]);
+        expect(fails).toEqual([]);
+        expect(cfg.pendingIntrospectionSwarmId).toBeUndefined();
+    });
+});
+// ── Self-suppression ───────────────────────────────────────────────────
+describe("IntrospectionSource self-suppression", () => {
+    it("sets lastIntrospectionRejected=true when all previous cohort archived", async () => {
+        const lastAt = new Date("2026-06-06T00:00:00Z").toISOString();
+        const cohort = [
+            makeIdea({
+                id: "i1",
+                status: "archived",
+                sourceRole: INTROSPECTION_SOURCE_ROLE,
+                tags: [INTROSPECTION_SOURCE_TAG],
+                createdAt: "2026-06-06T00:01:00Z",
+            }),
+            makeIdea({
+                id: "i2",
+                status: "archived",
+                sourceRole: INTROSPECTION_SOURCE_ROLE,
+                tags: [INTROSPECTION_SOURCE_TAG],
+                createdAt: "2026-06-06T00:02:00Z",
+            }),
+        ];
+        const cfg = makeConfig({
+            lastIntrospectionAt: lastAt,
+            lastIntrospectionRejected: false,
+        });
+        const patches = [];
+        const source = createIntrospectionSource({
+            ideasClient: makeClient({ listResults: cohort }),
+            swarmCoordinator: makeCoord(),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+            clock: () => new Date("2026-06-08T00:00:00Z"), // past 24h cooldown
+        });
+        const result = await source.pick(PROJECT_ROOT);
+        expect(result).toBeNull();
+        expect(patches[0]).toEqual({ lastIntrospectionRejected: true });
+    });
+    it("clears lastIntrospectionRejected when ≥1 previous idea survives", async () => {
+        const lastAt = new Date("2026-06-06T00:00:00Z").toISOString();
+        const cohort = [
+            makeIdea({
+                id: "i1",
+                status: "todo", // promoted by user
+                sourceRole: INTROSPECTION_SOURCE_ROLE,
+                tags: [INTROSPECTION_SOURCE_TAG],
+                createdAt: "2026-06-06T00:01:00Z",
+            }),
+            makeIdea({
+                id: "i2",
+                status: "archived",
+                sourceRole: INTROSPECTION_SOURCE_ROLE,
+                tags: [INTROSPECTION_SOURCE_TAG],
+                createdAt: "2026-06-06T00:02:00Z",
+            }),
+        ];
+        const cfg = makeConfig({
+            lastIntrospectionAt: lastAt,
+            lastIntrospectionRejected: true, // stale flag from prior cohort
+        });
+        const patches = [];
+        const source = createIntrospectionSource({
+            ideasClient: makeClient({ listResults: cohort }),
+            swarmCoordinator: makeCoord(),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+            clock: () => new Date("2026-06-08T00:00:00Z"),
+        });
+        await source.pick(PROJECT_ROOT);
+        // First patch clears the suppression flag.
+        expect(patches[0]).toEqual({ lastIntrospectionRejected: false });
+        // Cycle then runs to spawn → bumps the cooldown breadcrumbs +
+        // pendingIntrospectionSwarmId.
+        expect(patches.at(-1)).toMatchObject({
+            lastIntrospectionAt: expect.any(String),
+            lastIntrospectionRejected: false,
+            pendingIntrospectionSwarmId: expect.any(String),
+        });
+    });
+    it("ignores cohort entries older than lastIntrospectionAt (with epsilon)", async () => {
+        const lastAt = new Date("2026-06-06T12:00:00Z").toISOString();
+        const cohort = [
+            makeIdea({
+                id: "old-archived",
+                status: "archived",
+                sourceRole: INTROSPECTION_SOURCE_ROLE,
+                tags: [INTROSPECTION_SOURCE_TAG],
+                createdAt: "2026-06-01T00:00:00Z", // way before lastIntrospectionAt
+            }),
+            makeIdea({
+                id: "new-todo",
+                status: "todo",
+                sourceRole: INTROSPECTION_SOURCE_ROLE,
+                tags: [INTROSPECTION_SOURCE_TAG],
+                createdAt: "2026-06-06T12:00:30Z", // within epsilon of lastIntrospectionAt
+            }),
+        ];
+        const cfg = makeConfig({
+            lastIntrospectionAt: lastAt,
+        });
+        const patches = [];
+        const source = createIntrospectionSource({
+            ideasClient: makeClient({ listResults: cohort }),
+            swarmCoordinator: makeCoord(),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+            clock: () => new Date("2026-06-08T00:00:00Z"),
+        });
+        await source.pick(PROJECT_ROOT);
+        // The "new-todo" entry survives the filter and proves the cohort isn't
+        // all-archived → flag should be false, not true.
+        expect(patches[0]).toEqual({ lastIntrospectionRejected: false });
+    });
+});
+// ── B2c: spawner-owned lifecycle (Framing B) ───────────────────────────
+//
+// Verifies that IntrospectionSource declares "owned" lifecycle, exposes a
+// public isComplete() hook, and that drainPending forces the coordinator
+// into a terminal state when the spawner-side completion signal (output
+// file + mtime guard, or hard timeout) is observed — even if the swarm is
+// stuck in `paused` or `running` because the coordinator's idle-fallback
+// hasn't triggered yet.
+describe("IntrospectionSource spawner-owned lifecycle (B2c)", () => {
+    let tmpHome;
+    let projectRoot;
+    let outputPath;
+    let nowMs;
+    let spawnIso;
+    beforeEach(() => {
+        tmpHome = mkdtempSync(join(tmpdir(), "introspect-b2c-"));
+        projectRoot = tmpHome;
+        outputPath = join(projectRoot, ".clawnet", "introspection", "swarm-b2c.json");
+        mkdirSync(join(projectRoot, ".clawnet", "introspection"), { recursive: true });
+        // Anchor all time math to wall-clock now so file mtime and injected
+        // clock share the same axis. Each test sets nowMs forward as needed
+        // (e.g. +60s past mtime guard, +3h past hard timeout) using offsets
+        // relative to spawnIso.
+        nowMs = Date.now();
+        spawnIso = new Date(nowMs).toISOString();
+    });
+    afterEach(() => {
+        rmSync(tmpHome, { recursive: true, force: true });
+    });
+    it("exposes isComplete (public spawner-owned signal hook)", () => {
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord(),
+            getConfig: () => makeConfig(),
+            updateConfig: async () => { },
+        });
+        expect(typeof source.isComplete).toBe("function");
+    });
+    it("isComplete: false when no output file and within hard timeout", async () => {
+        const cfg = makeConfig({ lastIntrospectionAt: spawnIso });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord(),
+            getConfig: () => cfg,
+            updateConfig: async () => { },
+            clock: () => new Date(nowMs + SPAWNER_COMPLETE_HARD_TIMEOUT_MS / 2),
+        });
+        expect(await source.isComplete(projectRoot, "swarm-b2c")).toBe(false);
+    });
+    it("isComplete: false when output just written (mtime guard)", async () => {
+        writeFileSync(outputPath, JSON.stringify([{ title: "x" }]));
+        const cfg = makeConfig({ lastIntrospectionAt: spawnIso });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord(),
+            getConfig: () => cfg,
+            updateConfig: async () => { },
+            // clock pinned to inside the mtime guard window
+            clock: () => new Date(nowMs + Math.floor(SPAWNER_COMPLETE_MTIME_GUARD_MS / 2)),
+        });
+        expect(await source.isComplete(projectRoot, "swarm-b2c")).toBe(false);
+    });
+    it("isComplete: true when output stable beyond mtime guard", async () => {
+        writeFileSync(outputPath, JSON.stringify([{ title: "x" }]));
+        const cfg = makeConfig({ lastIntrospectionAt: spawnIso });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord(),
+            getConfig: () => cfg,
+            updateConfig: async () => { },
+            clock: () => new Date(nowMs + SPAWNER_COMPLETE_MTIME_GUARD_MS + 1_000),
+        });
+        expect(await source.isComplete(projectRoot, "swarm-b2c")).toBe(true);
+    });
+    it("isComplete: true when hard timeout elapsed even without output", async () => {
+        const cfg = makeConfig({ lastIntrospectionAt: spawnIso });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord(),
+            getConfig: () => cfg,
+            updateConfig: async () => { },
+            clock: () => new Date(nowMs + SPAWNER_COMPLETE_HARD_TIMEOUT_MS + 60_000),
+        });
+        expect(await source.isComplete(projectRoot, "swarm-b2c")).toBe(true);
+    });
+    it("drainPending: swarm=paused + isComplete=false → no force, no ingest, pendingId kept", async () => {
+        // No output file → isComplete=false even though swarm is non-terminal
+        const completes = [];
+        const cfg = makeConfig({
+            lastIntrospectionAt: spawnIso,
+            pendingIntrospectionSwarmId: "swarm-b2c",
+        });
+        const patches = [];
+        const source = createIntrospectionSource({
+            ideasClient: makeClient(),
+            swarmCoordinator: makeCoord({
+                swarmStatus: "paused",
+                onComplete: (id) => completes.push(id),
+            }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+            },
+            clock: () => new Date(nowMs + Math.floor(SPAWNER_COMPLETE_HARD_TIMEOUT_MS / 4)),
+        });
+        await source.drainPending(projectRoot);
+        expect(completes).toEqual([]); // no force
+        expect(patches).toEqual([]); // pendingId not cleared
+    });
+    it("drainPending: swarm=paused + isComplete=true → force complete + R3 I-A skips (production parity)", async () => {
+        writeFileSync(outputPath, JSON.stringify([
+            { title: "i1", body: "b1" },
+            { title: "i2", body: "b2" },
+        ]));
+        const completes = [];
+        const creates = [];
+        const cfg = makeConfig({
+            lastIntrospectionAt: spawnIso,
+            pendingIntrospectionSwarmId: "swarm-b2c",
+        });
+        const patches = [];
+        const source = createIntrospectionSource({
+            ideasClient: makeClient({ onCreate: (i) => creates.push(i) }),
+            // mutateStatusOnComplete=true: mirrors real coord which calls
+            // runRetroAndCleanup → swarms.delete after marking completed. So the
+            // post-complete isTerminalSwarm sees "unknown" (swarm gone), NOT
+            // "completed". The R3 I-A cleanup chain in processPendingSwarm
+            // then correctly skips firing a second complete() — which is the
+            // ACTUAL production behaviour. An earlier round of this test had a
+            // fake that lied about this and asserted 2 calls, masking the real
+            // single-call flow. See PR #170 Round-3 review.
+            swarmCoordinator: makeCoord({
+                swarmStatus: "paused",
+                mutateStatusOnComplete: true,
+                onComplete: (id) => completes.push(id),
+            }),
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+            clock: () => new Date(nowMs + SPAWNER_COMPLETE_MTIME_GUARD_MS + 1_000),
+        });
+        await source.drainPending(projectRoot);
+        // Exactly once: the spawner-owned force-complete. R3 I-A sees "unknown"
+        // (registry evicted) and skips its own complete/fail branches.
+        // Catches both regression directions — missing the force AND
+        // accidentally double-firing the cleanup chain.
+        expect(completes).toEqual(["swarm-b2c"]);
+        expect(creates).toHaveLength(2);
+        expect(creates.map((c) => c.title)).toEqual(["i1", "i2"]);
+        const clearPatch = patches.find((p) => "pendingIntrospectionSwarmId" in p);
+        expect(clearPatch?.pendingIntrospectionSwarmId).toBeNull();
+    });
+    it("drainPending: spawner-owned complete throws → destroy fallback + ingest still proceeds", async () => {
+        writeFileSync(outputPath, JSON.stringify([{ title: "still-ingested" }]));
+        const creates = [];
+        const destroys = [];
+        const cfg = makeConfig({
+            lastIntrospectionAt: spawnIso,
+            pendingIntrospectionSwarmId: "swarm-b2c",
+        });
+        const patches = [];
+        const coord = makeCoord({
+            swarmStatus: "paused",
+            completeThrows: true,
+            onDestroy: (id) => destroys.push(id),
+        });
+        const source = createIntrospectionSource({
+            ideasClient: makeClient({ onCreate: (i) => creates.push(i) }),
+            swarmCoordinator: coord,
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+            clock: () => new Date(nowMs + SPAWNER_COMPLETE_MTIME_GUARD_MS + 1_000),
+        });
+        // Should NOT throw — best-effort transition + destroy fallback
+        await source.drainPending(projectRoot);
+        // Registry leak prevention: destroy was called AND the registry
+        // actually evicted the swarm (fake mirrors real coord behaviour).
+        expect(destroys).toEqual(["swarm-b2c"]);
+        expect(coord.getSwarm("swarm-b2c")).toBeUndefined();
+        expect(creates).toHaveLength(1); // ingest happened anyway
+        const clearPatch = patches.find((p) => "pendingIntrospectionSwarmId" in p);
+        expect(clearPatch?.pendingIntrospectionSwarmId).toBeNull();
+    });
+});
+// ── PR-B follow-up: workspace.cwd race fix ─────────────────────────────
+//
+// After PR-B Sub-PR-B2 added the queen-driven `swarm_complete` path, the
+// coordinator deletes the swarm from its registry BEFORE the next tick's
+// `processPendingSwarm` runs. `resolveActualOutputPath` previously relied
+// on `swarmCoordinator.getSwarm(swarmId).workspace?.cwd` to find where the
+// queen wrote candidates — post-delete it returns undefined and the
+// fallback (projectRoot) finds no file → silent 0 ingest. Fix: persist
+// `workspace.cwd` to `always-on.json` alongside `pendingIntrospectionSwarmId`
+// at spawn time, and have the resolver prefer the persisted value when
+// `getSwarm()` is empty.
+describe("IntrospectionSource workspace.cwd persistence (PR-B race fix)", () => {
+    let tmpHome;
+    let projectRoot;
+    let worktreeCwd;
+    beforeEach(() => {
+        tmpHome = mkdtempSync(join(tmpdir(), "introspect-race-"));
+        projectRoot = tmpHome;
+        worktreeCwd = join(tmpHome, ".worktrees", "swarm-x");
+        mkdirSync(join(worktreeCwd, ".clawnet", "introspection"), { recursive: true });
+    });
+    afterEach(() => {
+        rmSync(tmpHome, { recursive: true, force: true });
+    });
+    it("spawn cycle persists pendingIntrospectionWorkspaceCwd when WorkspaceManager assigns a cwd", async () => {
+        const client = makeClient();
+        const created = vi.fn(async (_swarmId, _opts) => { });
+        const patches = [];
+        const cfg = makeConfig();
+        // Custom coord that returns workspace.cwd on getSwarm so the spawn
+        // path can capture it. Mirrors WorkspaceManager.create having already
+        // assigned a workspace before swarmCoordinator.create returns.
+        const coord = {
+            create: created,
+            getSwarm: (_id) => ({ status: "running", workspace: { cwd: worktreeCwd } }),
+            destroy: async () => { },
+            complete: async () => { },
+            fail: async () => { },
+        };
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: coord,
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+            },
+            generateSwarmId: () => "swarm-x",
+            clock: () => new Date("2026-06-07T00:00:00Z"),
+        });
+        await source.pick(projectRoot);
+        // Final patch carries both the swarm id and the workspace cwd.
+        expect(patches.at(-1)).toMatchObject({
+            pendingIntrospectionSwarmId: "swarm-x",
+            pendingIntrospectionWorkspaceCwd: worktreeCwd,
+        });
+    });
+    it("ingest reads candidates from persisted workspace.cwd when swarm is gone from registry (B2 path)", async () => {
+        // Queen wrote 3 candidates to the worktree; swarm_complete has already
+        // run and deleted the swarm from the registry. The pendingIntrospection
+        // breadcrumb + persisted cwd are still on disk.
+        const queenOutput = join(worktreeCwd, ".clawnet", "introspection", "swarm-x.json");
+        writeFileSync(queenOutput, JSON.stringify([
+            { title: "inFlight leak fix", body: "raise watchdog" },
+            { title: "true-release auto-pause", body: "closeSession + dispose" },
+            { title: "continuationSwarmId", body: "carry conversation across cycles" },
+        ]));
+        const client = makeClient();
+        const cfg = makeConfig({
+            pendingIntrospectionSwarmId: "swarm-x",
+            pendingIntrospectionWorkspaceCwd: worktreeCwd,
+            // Spawn far enough ago to clear isOwnerComplete mtime guard, and far
+            // enough behind the hard timeout that we don't trip the hard-timeout
+            // branch by accident.
+            lastIntrospectionAt: new Date("2026-06-07T00:00:00Z").toISOString(),
+        });
+        // Coordinator no longer has the swarm — swarm_complete already deleted
+        // it. getSwarm returns undefined; isTerminalSwarm reports "unknown".
+        const coord = makeCoord({ swarmStatus: null });
+        const patches = [];
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: coord,
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                patches.push(patch);
+                Object.assign(cfg, patch);
+                if ("pendingIntrospectionSwarmId" in patch && patch.pendingIntrospectionSwarmId === null) {
+                    delete cfg.pendingIntrospectionSwarmId;
+                }
+                if ("pendingIntrospectionWorkspaceCwd" in patch && patch.pendingIntrospectionWorkspaceCwd === null) {
+                    delete cfg.pendingIntrospectionWorkspaceCwd;
+                }
+            },
+            // Far enough past spawnAt that the mtime guard (5s) has elapsed,
+            // but well within hard timeout (2h).
+            clock: () => new Date("2026-06-07T00:00:10Z"),
+        });
+        await source.drainPending(projectRoot);
+        // ALL 3 candidates were ingested — the fix saves the cohort that
+        // would otherwise be silently lost.
+        expect(client.creates).toHaveLength(3);
+        expect(client.creates.map((c) => c.title)).toEqual([
+            "inFlight leak fix",
+            "true-release auto-pause",
+            "continuationSwarmId",
+        ]);
+        // Both breadcrumbs cleared in lockstep.
+        expect(cfg.pendingIntrospectionSwarmId).toBeUndefined();
+        expect(cfg.pendingIntrospectionWorkspaceCwd).toBeUndefined();
+        const clearPatch = patches.find((p) => "pendingIntrospectionSwarmId" in p);
+        expect(clearPatch?.pendingIntrospectionWorkspaceCwd).toBeNull();
+    });
+    it("regression: without persisted cwd, post-delete drain silently loses candidates (control)", async () => {
+        // Same setup as above EXCEPT pendingIntrospectionWorkspaceCwd is absent
+        // — this is the pre-fix state. Without persisted cwd, the resolver
+        // falls back to projectRoot/.clawnet/introspection/, where the file
+        // does NOT live, so 0 candidates are ingested. This test guards the
+        // fix by demonstrating the bug it solves.
+        const queenOutput = join(worktreeCwd, ".clawnet", "introspection", "swarm-x.json");
+        writeFileSync(queenOutput, JSON.stringify([{ title: "would-be-lost", body: "" }]));
+        const client = makeClient();
+        const cfg = makeConfig({
+            pendingIntrospectionSwarmId: "swarm-x",
+            // pendingIntrospectionWorkspaceCwd intentionally absent
+            lastIntrospectionAt: new Date("2026-06-07T00:00:00Z").toISOString(),
+        });
+        const coord = makeCoord({ swarmStatus: null });
+        const source = createIntrospectionSource({
+            ideasClient: client,
+            swarmCoordinator: coord,
+            getConfig: () => cfg,
+            updateConfig: async (_pr, patch) => {
+                Object.assign(cfg, patch);
+                if ("pendingIntrospectionSwarmId" in patch && patch.pendingIntrospectionSwarmId === null) {
+                    delete cfg.pendingIntrospectionSwarmId;
+                }
+            },
+            clock: () => new Date("2026-06-07T00:00:10Z"),
+        });
+        await source.drainPending(projectRoot);
+        // Bug-state: candidate file existed but resolver looked at wrong path
+        // → silent 0 ingest, breadcrumb still cleared. This is exactly the
+        // failure mode that the persisted cwd fix above prevents.
+        expect(client.creates).toHaveLength(0);
+        expect(cfg.pendingIntrospectionSwarmId).toBeUndefined();
+    });
+});
+//# sourceMappingURL=introspection-source.test.js.map