@mclawnet/swarm 0.1.12 → 0.1.14

package/dist/always-on/task-sources/introspection-source.js

@@ -0,0 +1,695 @@
+// M8.2 — IntrospectionSource: L3 fallback in the task-source cascade.
+//
+// Unlike L1/L2a/L2b, this source NEVER returns an executable TaskRef. Its
+// `pick(projectRoot)` side-effectfully drives the agent's self-introspection
+// loop and always returns null — the cascade short-circuits, the cycle "does
+// nothing" from the runner's perspective, and the user wakes up to new
+// auto-discovered idea suggestions on the next visit.
+//
+// M8 hotfix I1+I2 — fire-and-forget. Previously pick() spawned the swarm
+// and awaited it inline (up to 10 min), which:
+//   (a) blocked the always-on scheduler from firing anything else for the
+//       entire wait window (I2), and
+//   (b) burned a dailyBudget tick on a cycle that produced no in-cycle work
+//       (I1, because runner returned status="skipped" but ticksToday still
+//       incremented).
+// The fix is a two-phase handshake:
+//   1. spawn cycle — pick() creates the swarm, persists
+//      `pendingIntrospectionSwarmId` + bumps `lastIntrospectionAt`, returns
+//      null without awaiting the swarm. The scheduler is free to fire other
+//      sources on the next tick.
+//   2. ingest cycle (next pick after terminal) — pick() observes the
+//      pending swarm has finished, reads the output file, POSTs the cohort
+//      to /api/ideas, clears the pending breadcrumb, and returns null. The
+//      ingest never blocks; if the swarm is still running, we just return
+//      null again and try the next tick.
+// An agent restart between spawn and ingest is safe: the pending swarmId is
+// persisted to always-on.json and the recovery.json on disk lets the
+// SwarmCoordinator re-attach.
+//
+// Guard-rails (per design doc D4):
+//   - Opt-in (default off). `config.taskSources?.introspection === true`.
+//   - Independent 24h cooldown via `introspectionCooldownHours`.
+//   - Self-suppression: if the previous introspection's ideas were all
+//     archived by the user, skip this one (`lastIntrospectionRejected`).
+//   - Cap at 3 ideas/cycle regardless of how many the queen produced.
+//   - Priority is always forced to "low" — agent suggestions never compete
+//     with user-written ideas for top slots (Q4=A enforcement).
+//
+// Output format (mirrors the introspection.md template):
+//   The queen writes a JSON array to a path provided in the task prompt:
+//     <projectRoot>/.clawnet/introspection/<swarmId>.json
+//   The ingest phase reads + parses + POSTs the file. Failure modes (no
+//   file / malformed JSON / empty array) clear the pending breadcrumb and
+//   move on — the cooldown gates the next spawn so a broken swarm can't
+//   spin in a tight loop.
+import { existsSync, mkdirSync, readFileSync, statSync } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { dirname, join } from "node:path";
+import { encodeCwd } from "@mclawnet/shared";
+import { DEFAULT_INTROSPECTION_COOLDOWN_HOURS, resolveTaskSources, } from "../config.js";
+import { appendToIndex, buildDedupeIndex, findDuplicate, } from "./idea-dedupe.js";
+export const INTROSPECTION_TEMPLATE_NAME = "introspection";
+export const INTROSPECTION_SOURCE_TAG = "auto-discovered";
+export const INTROSPECTION_SOURCE_ROLE = "queen-introspection";
+/** Hard cap per design doc D4 — no more than 3 ideas per introspection. */
+export const INTROSPECTION_MAX_IDEAS = 3;
+/**
+ * M8.2c — write-race guard for the spawner-owned completion signal. The
+ * queen's `cat > <output> <<'EOF' ... EOF` lands as several syscalls; we
+ * require N ms of mtime stillness before declaring "queen finished writing".
+ */
+export const SPAWNER_COMPLETE_MTIME_GUARD_MS = 5_000;
+/**
+ * M8.2c — absolute spawn-to-ingest cap. Even if the output file never lands
+ * (queen crashed / token exhausted / coordinator lost the swarm), the
+ * spawner stops waiting after this. `processPendingSwarm` then takes the
+ * "missing output" path: clears the pending breadcrumb and the next cycle
+ * (subject to cooldown) gets to retry. Set high enough that a normal
+ * introspection cycle (~30s of read+grep+write) is never near the cap.
+ */
+export const SPAWNER_COMPLETE_HARD_TIMEOUT_MS = 2 * 60 * 60 * 1000;
+/**
+ * Parse the queen's output file into a candidate array. Accepts either:
+ *   (a) a clean JSON file whose root is an array, or
+ *   (b) a file that contains other text and ends with a JSON array — we
+ *       scan for the *last* `[` and try JSON.parse from there.
+ *
+ * Returns [] on any failure. Callers treat [] as "queen produced nothing
+ * useful" — they still bump lastIntrospectionAt so cooldown holds.
+ */
+export function parseCandidatesOutput(raw) {
+    if (!raw || raw.trim().length === 0)
+        return [];
+    // Strategy 1: parse the entire file.
+    try {
+        const parsed = JSON.parse(raw);
+        if (Array.isArray(parsed))
+            return coerceCandidates(parsed);
+    }
+    catch {
+        // fall through to strategy 2
+    }
+    // Strategy 2: locate the last `[` and parse a balanced slice from there.
+    const lastOpen = raw.lastIndexOf("[");
+    if (lastOpen < 0)
+        return [];
+    // Find a matching close. Walk forward counting brackets; bail on first
+    // balanced match. This is good enough for queen-produced JSON which is
+    // never going to have stringly-embedded brackets at our cap of 3 items.
+    let depth = 0;
+    let end = -1;
+    let inString = false;
+    let escape = false;
+    for (let i = lastOpen; i < raw.length; i++) {
+        const ch = raw[i];
+        if (inString) {
+            if (escape) {
+                escape = false;
+            }
+            else if (ch === "\\") {
+                escape = true;
+            }
+            else if (ch === '"') {
+                inString = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            continue;
+        }
+        if (ch === "[")
+            depth++;
+        else if (ch === "]") {
+            depth--;
+            if (depth === 0) {
+                end = i;
+                break;
+            }
+        }
+    }
+    if (end < 0)
+        return [];
+    const slice = raw.slice(lastOpen, end + 1);
+    try {
+        const parsed = JSON.parse(slice);
+        if (Array.isArray(parsed))
+            return coerceCandidates(parsed);
+    }
+    catch {
+        /* fall through */
+    }
+    return [];
+}
+function coerceCandidates(arr) {
+    const out = [];
+    for (const raw of arr) {
+        if (!raw || typeof raw !== "object")
+            continue;
+        const r = raw;
+        const title = typeof r.title === "string" ? r.title.trim() : "";
+        if (!title)
+            continue;
+        const body = typeof r.body === "string" ? r.body : "";
+        const priority = typeof r.priority === "string" ? r.priority : undefined;
+        out.push({ title, body, ...(priority ? { priority } : {}) });
+    }
+    return out;
+}
+/**
+ * Build the task prompt handed to the introspection swarm. Embeds a
+ * workspace-RELATIVE output path so the queen writes inside whatever cwd
+ * her role process is given (workspace.cwd when worktree isolation is on,
+ * or projectRoot when it falls through to no workspace). Spawner reads it
+ * back by resolving the same relative path against the actual workspace
+ * cwd at drain time.
+ *
+ * Pre-B4: this used to embed `<projectRoot>/.clawnet/introspection/<id>.json`
+ * absolute and the queen would `cat >` straight to projectRoot, bypassing
+ * the worktree. PR-B Suspect B fix.
+ */
+export function buildIntrospectionTaskPrompt(projectRoot, relativeOutputPath) {
+    return [
+        `You are running an introspection cycle on the project rooted at: ${projectRoot}`,
+        "",
+        "Goal: produce 1-3 NEW idea candidates that aren't already tracked.",
+        "Tools you may use: Read, Grep, Bash (read-only: ls / cat / git log / git status / git diff --stat / git show).",
+        "Tools you must NOT use: Write, Edit, NotebookEdit, or any state-mutating command (git apply, git commit, package install, etc.).",
+        "",
+        `Output: write a JSON array to this path RELATIVE to your current working directory:`,
+        `  ${relativeOutputPath}`,
+        "(your cwd is the swarm workspace — write the file there, do NOT use an absolute path)",
+        "",
+        "Schema of each array element:",
+        '  { "title": "short title", "body": "why it matters + scope", "priority": "low" }',
+        "",
+        "Hard limits: at most 3 items. Priority is overridden to 'low' downstream — you can omit it.",
+        "When you have written the file, call `swarm_complete` to end the cycle. The spawner will pick up the candidates next tick and release coordinator resources immediately. If you skip the call, the spawner-owned fallback (output-file detection or paused-state detection) will reap the cycle eventually, but explicit completion is faster and avoids holding the backend session.",
+    ].join("\n");
+}
+/** Internal: returns true when the swarm is in a terminal state (or gone from registry). */
+function isTerminalSwarm(coord, swarmId) {
+    const swarm = coord.getSwarm(swarmId);
+    if (!swarm) {
+        // Gone from registry — could mean cleanup already ran, or the agent
+        // restarted and we didn't re-recover this swarm. Treat as "unknown
+        // terminal" so the ingest phase still tries to read the output file
+        // (it's the source of truth) and clears the pending breadcrumb.
+        return { terminal: true, status: "unknown" };
+    }
+    if (swarm.status === "completed")
+        return { terminal: true, status: "completed" };
+    if (swarm.status === "failed")
+        return { terminal: true, status: "failed" };
+    if (swarm.status === "cancelled")
+        return { terminal: true, status: "cancelled" };
+    return { terminal: false, status: "running" };
+}
+export function createIntrospectionSource(opts) {
+    const { ideasClient, swarmCoordinator, getConfig, updateConfig, introspectionTemplateName = INTROSPECTION_TEMPLATE_NAME, clock = () => new Date(), warn, info, generateSwarmId = () => `m8-introspect-${randomUUID()}`, resolveOutputPath = (projectRoot, swarmId) => join(projectRoot, ".clawnet", "introspection", `${swarmId}.json`), } = opts;
+    /**
+     * PR-B Suspect B fix — workspace-aware output path resolver.
+     * Prefer the swarm's actual workspace.cwd (set when WorkspaceManager
+     * prepared a worktree / snapshot copy) so we read where the queen
+     * actually wrote. Falls back to projectRoot via the (now historical)
+     * `resolveOutputPath` opt — preserves existing tests that fake the
+     * coordinator without a workspace.
+     *
+     * PR-B follow-up — after `swarm_complete` deletes the swarm from the
+     * registry, `swarmCoordinator.getSwarm()` returns undefined and the
+     * spawner loses the workspace handle. Pass the persisted
+     * `pendingIntrospectionWorkspaceCwd` (captured at spawn time) so the
+     * resolver still lands inside the worktree even when the live handle is
+     * gone. Without this, B2 (queen-driven swarm_complete) silently loses
+     * every cohort: lookup → undefined → projectRoot fallback → file-not-
+     * found warn → 0 ingest → breadcrumb cleared.
+     */
+    function resolveActualOutputPath(projectRoot, swarmId, persistedCwd) {
+        const swarm = swarmCoordinator.getSwarm(swarmId);
+        const base = swarm?.workspace?.cwd ?? persistedCwd ?? projectRoot;
+        // Keep the well-known relative tail so an injected resolveOutputPath
+        // override (tests) still wins when base === projectRoot.
+        if (base === projectRoot)
+            return resolveOutputPath(projectRoot, swarmId);
+        return join(base, ".clawnet", "introspection", `${swarmId}.json`);
+    }
+    /**
+     * PR-B — the prompt embeds this RELATIVE path; the queen's role process
+     * is given workspace.cwd as its cwd, so writing to a relative path lands
+     * inside the workspace. Pre-B4 we embedded an absolute projectRoot path,
+     * which made the queen escape the worktree.
+     */
+    function relativeOutputPath(swarmId) {
+        return join(".", ".clawnet", "introspection", `${swarmId}.json`);
+    }
+    /**
+     * M8.2c — spawner-owned completion signal. Returns true when the queen
+     * appears to have finished (output file exists and has been stable for the
+     * mtime guard window) OR the hard timeout has elapsed. Pure inspection —
+     * never mutates state. Used by `processPendingSwarm` to decide whether to
+     * force the swarm into a terminal state when the coordinator's idle
+     * fallback would otherwise leave it in `paused`. Pulled out as a helper
+     * so the public `isComplete` source hook can share the same logic.
+     */
+    function isOwnerComplete(projectRoot, pendingId, cfg) {
+        const now = clock().getTime();
+        // Hard timeout: spawn-to-give-up cap. Uses lastIntrospectionAt which is
+        // set to `clock().toISOString()` at spawn time. (The S1 hub-outage rewind
+        // only fires AFTER ingest has cleared pendingId, so it never overlaps
+        // with the hard-timeout path here.)
+        if (cfg.lastIntrospectionAt) {
+            const spawnedAt = new Date(cfg.lastIntrospectionAt).getTime();
+            if (Number.isFinite(spawnedAt) && now - spawnedAt > SPAWNER_COMPLETE_HARD_TIMEOUT_MS) {
+                return true;
+            }
+        }
+        const outputPath = resolveActualOutputPath(projectRoot, pendingId, cfg.pendingIntrospectionWorkspaceCwd);
+        if (!existsSync(outputPath))
+            return false;
+        try {
+            const st = statSync(outputPath);
+            return now - st.mtimeMs > SPAWNER_COMPLETE_MTIME_GUARD_MS;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Ingest phase — read the pending swarm's output, POST ideas, clear
+     * pending. Always-clears the pending breadcrumb (terminal swarm) so a
+     * malformed/missing output doesn't wedge the source forever; the
+     * cooldown (set at spawn) gates the next attempt.
+     *
+     * S1 hotfix: when the swarm produced candidates but every POST failed
+     * (likely hub outage), rewind `lastIntrospectionAt` so the cooldown
+     * shortens to ~1 hour instead of carrying the full 24h cooldown for an
+     * effectively-empty cycle.
+     *
+     * M8.2c: when the coordinator hasn't transitioned to a terminal state yet
+     * (single-queen introspection swarms get stuck in `paused` because the
+     * idle-fallback in startQueenCheck never sees an "active worker"), the
+     * spawner-owned completion signal (output file + mtime guard, or hard
+     * timeout) lets us force `coord.complete(swarmId)` ourselves and proceed
+     * to ingest in the same tick. Without this the cycle would have to wait
+     * for the coordinator's 100-min auto-pause AND a follow-up B2a-style
+     * tolerance path that doesn't exist.
+     */
+    async function processPendingSwarm(projectRoot, pendingId, cfg) {
+        let state = isTerminalSwarm(swarmCoordinator, pendingId);
+        // M8.2c follow-up — read the output BEFORE any coordinator transition.
+        // The destroy fallback below disposes the swarm's workspace
+        // (workspaceManager.dispose deletes it from disk). Today the
+        // introspection swarm doesn't run inside an isolated worktree so the
+        // output lives in the project's main `.clawnet/introspection/` dir and
+        // survives. Once B4 lands worktree isolation for always-on cycles, the
+        // output will land inside the disposable workspace and a destroy-before-
+        // read would silently lose the 3 candidates. Caching candidates here
+        // makes the ingest order-independent of the coordinator transition.
+        const outputPath = resolveActualOutputPath(projectRoot, pendingId, cfg.pendingIntrospectionWorkspaceCwd);
+        let candidates = [];
+        let outputExisted = false;
+        if (existsSync(outputPath)) {
+            outputExisted = true;
+            try {
+                const raw = readFileSync(outputPath, "utf-8");
+                candidates = parseCandidatesOutput(raw);
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), outputPath, pendingId }, "introspection-source: failed to read pending output (clearing pending)");
+            }
+        }
+        if (!state.terminal) {
+            if (!isOwnerComplete(projectRoot, pendingId, cfg)) {
+                info?.({ pendingId, projectRoot }, "introspection-source: pending swarm still running — will check next tick");
+                return;
+            }
+            // Spawner observed its own completion signal (output file written, or
+            // hard timeout elapsed). Force the coordinator to transition out of
+            // paused/running so the rest of the ingest path runs against a stable
+            // terminal state and downstream UI shows "completed" not "paused".
+            try {
+                await swarmCoordinator.complete(pendingId);
+                info?.({ pendingId, projectRoot }, "introspection-source: spawner-owned complete (forced terminal transition)");
+            }
+            catch (err) {
+                // Non-fatal: the output file's already been cached above and the
+                // pending breadcrumb is always cleared at the end. Try `destroy` as
+                // a last-resort cleanup so the swarm doesn't leak in the
+                // coordinator registry when `complete` was the wrong transition —
+                // the R3 I-A chain below keys off `state.status` and would skip
+                // both `completed` and `failed` branches when state is still
+                // "paused"/"running", leaving the registry entry alive forever.
+                warn?.({ err: err instanceof Error ? err.message : String(err), pendingId }, "introspection-source: spawner-owned complete failed (trying destroy fallback)");
+                try {
+                    await swarmCoordinator.destroy(pendingId);
+                }
+                catch {
+                    /* best-effort — output is already cached above */
+                }
+            }
+            state = isTerminalSwarm(swarmCoordinator, pendingId);
+        }
+        if (!outputExisted) {
+            warn?.({ pendingId, outputPath, swarmStatus: state.status }, "introspection-source: pending swarm output missing (clearing pending)");
+        }
+        const cohort = candidates.slice(0, INTROSPECTION_MAX_IDEAS);
+        let projectId = null;
+        try {
+            projectId = encodeCwd(projectRoot);
+        }
+        catch {
+            projectId = null;
+        }
+        // M8.2 dedupe pre-fetch: pull existing same-project intro ideas so we can
+        // skip candidates the queen has already proposed in a prior cycle. Failure
+        // here is non-fatal: we set `dedupeAvailable=false` and fall through to
+        // the insert loop unchanged. The hub-side `listIdeasSchema` caps `limit`
+        // at 100; that's plenty for the typical introspection corpus (a few months
+        // of 3-ideas-per-cycle still fits comfortably).
+        let dedupeIndex = [];
+        let dedupeAvailable = false;
+        if (projectId && cohort.length > 0) {
+            try {
+                const existing = await ideasClient.list({
+                    projectId,
+                    tag: INTROSPECTION_SOURCE_TAG,
+                    limit: 100,
+                });
+                // Defensive client-side filter — at the time of writing `list` returns
+                // every status, but if that ever changes to "active-only" this filter
+                // is still safe (archived rows we don't want to dedupe against either
+                // way — the user explicitly archived them).
+                const active = existing.filter((i) => i.status !== "archived");
+                dedupeIndex = buildDedupeIndex(active.map((i) => ({ id: i.id, title: i.title, body: i.body ?? "" })));
+                dedupeAvailable = true;
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), projectId }, "introspection-source: dedupe pre-fetch failed (fail-open, proceeding with insert)");
+            }
+        }
+        const posted = [];
+        let suppressedDuplicates = 0;
+        for (const c of cohort) {
+            if (dedupeAvailable) {
+                const match = findDuplicate({ title: c.title, body: c.body ?? "" }, dedupeIndex);
+                if (match) {
+                    suppressedDuplicates++;
+                    info?.({
+                        title: c.title,
+                        matchedIdeaId: match.matchedIdeaId,
+                        projectId,
+                        reason: match.reason,
+                        ...(match.score !== undefined ? { jaccard: match.score } : {}),
+                    }, "introspection-source: duplicate-suppressed");
+                    continue;
+                }
+            }
+            const input = {
+                title: c.title.slice(0, 500),
+                body: (c.body ?? "").slice(0, 50_000),
+                status: "idea",
+                priority: "low",
+                tags: [INTROSPECTION_SOURCE_TAG],
+                sourceRole: INTROSPECTION_SOURCE_ROLE,
+                sourceSwarmId: pendingId,
+                ...(projectId ? { projectId } : {}),
+            };
+            try {
+                const created = await ideasClient.create(input);
+                posted.push(created);
+                // Extend the index with the freshly-created idea so any subsequent
+                // candidate in this same cohort is checked against it too. Prevents
+                // the queen accidentally smuggling two near-identical ideas through
+                // in one cycle.
+                if (dedupeAvailable) {
+                    appendToIndex(dedupeIndex, {
+                        id: created.id,
+                        title: c.title,
+                        body: c.body ?? "",
+                    });
+                }
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), title: c.title }, "introspection-source: ideas.create failed");
+            }
+        }
+        // S2 hotfix + R3 I-A: release the swarm from the coordinator registry
+        // for EVERY terminal state, not just "completed". Mirrors
+        // WorkCycleRunner.waitForTerminalState (workcycle-runner.ts:340-376):
+        //   completed → coord.complete(swarmId) (idempotent — also runs cleanup)
+        //   failed    → coord.fail(swarmId)
+        //   cancelled → no-op (already terminal externally; the coordinator
+        //               cancel path is what put it there and already cleaned up)
+        //   unknown   → no-op (gone from registry — nothing to release)
+        // Pre-R3, only `completed` ran cleanup, so a swarm that returned
+        // `failed`/`cancelled`/`unknown` stayed in the registry forever and
+        // leaked across cycles.
+        if (state.status === "completed") {
+            try {
+                await swarmCoordinator.complete(pendingId);
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), pendingId }, "introspection-source: coordinator.complete failed (best-effort)");
+            }
+        }
+        else if (state.status === "failed") {
+            try {
+                await swarmCoordinator.fail(pendingId);
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), pendingId }, "introspection-source: coordinator.fail failed (best-effort)");
+            }
+        }
+        // "cancelled" and "unknown" need no coordinator call: cancelled is
+        // already terminal in the coordinator (whoever cancelled it cleaned up),
+        // and unknown means the swarm is no longer in the registry at all.
+        info?.({
+            pendingId,
+            swarmStatus: state.status,
+            produced: candidates.length,
+            posted: posted.length,
+            skippedOverflow: Math.max(0, candidates.length - INTROSPECTION_MAX_IDEAS),
+            suppressedDuplicates,
+        }, "introspection-source: ingest complete");
+        // S1 hotfix: hub outage triage. If the queen produced candidates but
+        // every POST failed, rewind the cooldown so we retry in ~1h instead of
+        // waiting the full window. Only triggers when there *were* candidates
+        // (no candidates = nothing to retry, no point shortening cooldown).
+        //
+        // M8.2 dedupe note: subtract `suppressedDuplicates` so a cohort where
+        // every idea was a known duplicate (legitimate zero-POST outcome) does
+        // not falsely trip the hub-outage path.
+        const patch = {
+            pendingIntrospectionSwarmId: null,
+            pendingIntrospectionWorkspaceCwd: null,
+        };
+        const attempted = cohort.length - suppressedDuplicates;
+        if (attempted > 0 && posted.length === 0) {
+            const cooldownHours = cfg.introspectionCooldownHours ?? DEFAULT_INTROSPECTION_COOLDOWN_HOURS;
+            const rewindMs = Math.max(0, cooldownHours - 1) * 3600_000;
+            patch.lastIntrospectionAt = new Date(clock().getTime() - rewindMs).toISOString();
+            info?.({ pendingId, candidates: cohort.length, attempted, posted: 0, rewindMs }, "introspection-source: hub outage triage — rewinding lastIntrospectionAt");
+        }
+        await updateConfig(projectRoot, patch);
+    }
+    return {
+        name: "queen-introspection",
+        kind: "queen-introspection",
+        /**
+         * M8.2c — spawner-owned completion signal exposed publicly. Introspection
+         * swarms are single-queen fire-and-forget cycles: there's never an active
+         * non-queen worker, so the coordinator's idle-check would otherwise stall
+         * them in `paused` after ~100 min, and `processPendingSwarm` (which keys
+         * off swarm status) would never ingest. The source's own `drainPending`
+         * calls `coordinator.complete()` once this returns true.
+         */
+        async isComplete(projectRoot, swarmId) {
+            return isOwnerComplete(projectRoot, swarmId, getConfig(projectRoot));
+        },
+        /**
+         * R3 I-B — pre-cascade drain hook. Runs every tick BEFORE the cascade
+         * picker, regardless of whether `taskSources.introspection` is on.
+         * Without this hook, the scenario "user enables introspection → swarm
+         * spawned → user toggles introspection OFF before the swarm reaches
+         * terminal state" leaks `pendingIntrospectionSwarmId` (the source's
+         * own pick() is skipped while disabled, so its Step-0 drain never
+         * fires) AND the swarm stays in the coordinator registry forever
+         * (only re-enabling the toggle ever reaps it). The drain is opt-in
+         * (skips when no pending breadcrumb), independent of the toggle, and
+         * best-effort — internal failures are swallowed by processPendingSwarm.
+         */
+        async drainPending(projectRoot) {
+            const cfg = getConfig(projectRoot);
+            if (!cfg.pendingIntrospectionSwarmId)
+                return;
+            await processPendingSwarm(projectRoot, cfg.pendingIntrospectionSwarmId, cfg);
+        },
+        async pick(projectRoot) {
+            const cfg = getConfig(projectRoot);
+            const sources = resolveTaskSources(cfg.taskSources);
+            if (!sources.introspection) {
+                // Default path: introspection is opt-in. Silent (debug-level) — no
+                // log spam when the user simply hasn't turned it on.
+                return null;
+            }
+            // ── Step 0: drain any pending swarm spawned on a prior tick ──────
+            // Fire-and-forget design (hotfix I1/I2). If a spawn cycle left a
+            // breadcrumb, we ingest the result here without ever blocking the
+            // scheduler. Always returns null after — the cascade falls through
+            // and the runner skips this cycle. We deliberately do NOT proceed to
+            // step 1+ even when the ingest completed; one cycle does one thing
+            // (ingest OR spawn), never both. This keeps reasoning simple and
+            // avoids surprising the user with two POSTs in one tick.
+            //
+            // R3 I-B note: in the on-toggle path, `AlwaysOnManager.drainPending`
+            // has already attempted the drain before this pick() runs, so by the
+            // time we get here the breadcrumb is usually cleared. The defensive
+            // re-check still matters because (a) the swarm may still be running
+            // (drainPending leaves the breadcrumb in place when not terminal),
+            // and (b) when `taskSources` is wired without an AlwaysOnManager
+            // (tests, ad-hoc usage) the manager-level drain doesn't run.
+            if (cfg.pendingIntrospectionSwarmId) {
+                await processPendingSwarm(projectRoot, cfg.pendingIntrospectionSwarmId, cfg);
+                return null;
+            }
+            // ── Step 1: self-suppression pre-check ──────────────────────────
+            // If the previous introspection ran, evaluate whether all of its
+            // produced ideas got archived. We do this BEFORE the cooldown gate so
+            // a user who actually kept some ideas clears the suppression sooner
+            // (and so a stuck suppression flag doesn't outlast the cooldown).
+            if (cfg.lastIntrospectionAt) {
+                try {
+                    const projectId = encodeCwd(projectRoot);
+                    // Pull a generous slice — we filter further in-memory by
+                    // lastIntrospectionAt and tag/source. Limit 100 covers up to ~33
+                    // introspections at 3 ideas each.
+                    const recent = await ideasClient.list({
+                        projectId,
+                        tag: INTROSPECTION_SOURCE_TAG,
+                        limit: 100,
+                    });
+                    const epsilonMs = 60_000; // 1-minute slack for clock skew
+                    // N2 hotfix: use the injected clock + Date.getTime() consistently
+                    // instead of mixing Date.parse with the wall clock. Tests
+                    // injecting `clock` were observing the wall-clock now() during
+                    // the cohort filter, which made deterministic fixtures flaky.
+                    const since = new Date(cfg.lastIntrospectionAt).getTime();
+                    const cohort = recent.filter((i) => i.sourceRole === INTROSPECTION_SOURCE_ROLE &&
+                        new Date(i.createdAt).getTime() >= since - epsilonMs);
+                    if (cohort.length > 0) {
+                        const allArchived = cohort.every((i) => i.status === "archived");
+                        const desired = allArchived;
+                        if (cfg.lastIntrospectionRejected !== desired) {
+                            await updateConfig(projectRoot, { lastIntrospectionRejected: desired });
+                        }
+                        if (allArchived) {
+                            info?.({ cohortSize: cohort.length, projectId }, "introspection-source: previous cohort all archived — suppressing");
+                            return null;
+                        }
+                    }
+                }
+                catch (err) {
+                    // Best-effort: a hub outage shouldn't permanently break introspection.
+                    warn?.({ err: err instanceof Error ? err.message : String(err) }, "introspection-source: self-suppression check failed (continuing)");
+                }
+            }
+            else if (cfg.lastIntrospectionRejected) {
+                // Defensive: cooldown got cleared but the rejected flag persisted.
+                // Don't trust it without a cohort to back it up.
+                await updateConfig(projectRoot, { lastIntrospectionRejected: null });
+            }
+            // After the pre-check, the flag may still be set (skipped the cohort
+            // sync above due to no lastIntrospectionAt). Honour it.
+            const cfg2 = getConfig(projectRoot);
+            if (cfg2.lastIntrospectionRejected === true) {
+                info?.({ projectRoot }, "introspection-source: lastIntrospectionRejected=true — skipping");
+                return null;
+            }
+            // ── Step 2: cooldown gate ────────────────────────────────────────
+            const cooldownHours = cfg2.introspectionCooldownHours ?? DEFAULT_INTROSPECTION_COOLDOWN_HOURS;
+            const cooldownMs = Math.max(0, cooldownHours) * 3600_000;
+            if (cfg2.lastIntrospectionAt && cooldownMs > 0) {
+                // N2 hotfix: same Date.getTime() consistency as the cohort filter.
+                const sinceMs = clock().getTime() - new Date(cfg2.lastIntrospectionAt).getTime();
+                if (sinceMs < cooldownMs) {
+                    info?.({ sinceMs, cooldownMs, lastIntrospectionAt: cfg2.lastIntrospectionAt }, "introspection-source: cooldown not elapsed — skipping");
+                    return null;
+                }
+            }
+            // ── Step 3: spawn the introspection swarm (fire-and-forget) ──────
+            const swarmId = generateSwarmId();
+            // Pre-create the output directory in projectRoot so a fallback (no
+            // workspace) write succeeds without queen having to mkdir herself.
+            // With workspace isolation the queen's cwd will be workspace.cwd
+            // and she creates the directory there as needed; the projectRoot
+            // pre-mkdir is harmless in that case.
+            const fallbackOutputPath = resolveOutputPath(projectRoot, swarmId);
+            try {
+                mkdirSync(dirname(fallbackOutputPath), { recursive: true });
+            }
+            catch {
+                /* best-effort */
+            }
+            // PR-B Suspect B fix: prompt embeds a RELATIVE path. Queen's cwd is
+            // workspace.cwd (set by spawnRole → sessionAdapter.createSession with
+            // `workDir: swarm.workspace?.cwd ?? swarm.workDir`), so a relative
+            // write lands inside the workspace. Spawner reads back via
+            // `resolveActualOutputPath` which checks workspace.cwd first.
+            const taskPrompt = buildIntrospectionTaskPrompt(projectRoot, relativeOutputPath(swarmId));
+            // We await coordinator.create — it's the *registration* call (fast)
+            // and we need to know it succeeded before persisting the pending
+            // breadcrumb. The swarm itself runs in the background after create()
+            // returns; this is the fire-and-forget edge.
+            try {
+                await swarmCoordinator.create(swarmId, {
+                    workDir: projectRoot,
+                    templateName: introspectionTemplateName,
+                    task: taskPrompt,
+                    kind: "always-on-introspection",
+                });
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), swarmId }, "introspection-source: coordinator.create failed — bumping cooldown to avoid retry storm");
+                await updateConfig(projectRoot, {
+                    lastIntrospectionAt: clock().toISOString(),
+                    lastIntrospectionRejected: false,
+                });
+                return null;
+            }
+            // ── Step 4: persist pending breadcrumb + cooldown ────────────────
+            // This is the entire side-effect of a spawn cycle. The ingest cycle
+            // (next pick after swarm reaches terminal state) handles the rest.
+            //
+            // PR-B follow-up — capture the workspace.cwd assigned by
+            // WorkspaceManager.create so `processPendingSwarm` can still resolve
+            // the candidates file after `swarm_complete` deletes the swarm from
+            // the registry (B2 path). `getSwarm()` is the only reliable way to
+            // read workspace.cwd post-create; we snapshot it here and let the
+            // persisted value carry through restart + post-delete reads.
+            const spawned = swarmCoordinator.getSwarm(swarmId);
+            const workspaceCwd = spawned?.workspace?.cwd;
+            await updateConfig(projectRoot, {
+                lastIntrospectionAt: clock().toISOString(),
+                lastIntrospectionRejected: false,
+                pendingIntrospectionSwarmId: swarmId,
+                ...(workspaceCwd ? { pendingIntrospectionWorkspaceCwd: workspaceCwd } : {}),
+            });
+            info?.({ swarmId, projectRoot, templateName: introspectionTemplateName }, "introspection-source: swarm spawned (fire-and-forget) — ingest on next tick after terminal");
+            return null;
+        },
+        // Source-driven flow — runner never claims an introspection task because
+        // pick() always returns null. These hooks satisfy the interface but are
+        // no-ops by design.
+        async onClaim() {
+            /* no-op */
+        },
+        async onSuccess() {
+            /* no-op */
+        },
+        async onFailure() {
+            /* no-op */
+        },
+    };
+}
+//# sourceMappingURL=introspection-source.js.map