@mclawnet/swarm 0.1.13 → 0.1.15

package/dist/always-on/task-sources/idea-todo-source.d.ts

@@ -0,0 +1,48 @@
+import type { IdeasClient } from "../ideas-client.js";
+import { sortIdeasByPriorityThenAge } from "./idea-sort.js";
+import type { TaskSource } from "./types.js";
+export interface IdeaTodoSourceOptions {
+    ideasClient: IdeasClient;
+    /**
+     * Per-cycle list cap forwarded to the ideas API. Default 50 is plenty —
+     * we only consume the head after sorting.
+     */
+    listLimit?: number;
+    /** Optional warn logger; defaults to silent. */
+    warn?: (obj: Record<string, unknown>, msg?: string) => void;
+    /** Optional info logger; defaults to silent. */
+    info?: (obj: Record<string, unknown>, msg?: string) => void;
+}
+/**
+ * Re-export the shared sort under the original name for back-compat with
+ * tests that imported `sortIdeasForPicking` from this module. S5 hotfix
+ * consolidates the implementation into `./idea-sort` so both sources stay
+ * in lockstep.
+ */
+export declare const sortIdeasForPicking: typeof sortIdeasByPriorityThenAge;
+export declare function createIdeaTodoSource(opts: IdeaTodoSourceOptions): TaskSource;
+/**
+ * Helper exposed for callers that want to manually PATCH the idea to
+ * researching + linkedSwarmTaskId outside the cascade flow. Internally the
+ * IdeaTodoSource calls the same logic via its `onClaim` hook.
+ */
+export declare function markIdeaResearching(ideasClient: IdeasClient, ideaId: string, swarmId: string, log?: {
+    warn?: (o: Record<string, unknown>, m?: string) => void;
+}): Promise<void>;
+/**
+ * PR-B Sub-PR-B3 — classify a swarm failure error into one of 4 categories
+ * used by `shipFailureReason`. The taxonomy intentionally collapses noisy
+ * variants:
+ *   - "network": ENOTFOUND / ETIMEDOUT / ECONNRESET / "network" anywhere
+ *     in the message — pick() applies a 5min cooldown before retry
+ *   - "rate-limit": "rate limit" / HTTP 429 — same 5min cooldown
+ *   - "auth": "401" / "403" / "auth" / "token" — NOT cooldowned (user
+ *     likely fixed the token between cycles)
+ *   - "other": anything else, no cooldown (retry immediately so we can
+ *     refresh the diagnosis)
+ *
+ * Exported for unit tests; callers should use `IdeaTodoSource.onFailure`
+ * which delegates here.
+ */
+export declare function classifyShipFailure(error?: string): string;
+//# sourceMappingURL=idea-todo-source.d.ts.map

package/dist/always-on/task-sources/idea-todo-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"idea-todo-source.d.ts","sourceRoot":"","sources":["../../../src/always-on/task-sources/idea-todo-source.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAQ,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,KAAK,EAAW,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtD,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,WAAW,CAAC;IACzB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,gDAAgD;IAChD,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;CAC7D;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,mCAA6B,CAAC;AAE9D,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,qBAAqB,GAAG,UAAU,CAkL5E;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CACvC,WAAW,EAAE,WAAW,EACxB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,GAAG,CAAC,EAAE;IAAE,IAAI,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAA;CAAE,GAChE,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAmB1D"}

package/dist/always-on/task-sources/idea-todo-source.js

@@ -0,0 +1,226 @@
+// M8.0 — IdeaTodoSource: consumes ideas with status="todo" and drives them
+// through researching → developed (success) or back to todo (failure).
+//
+// Flow (D1 in design doc):
+//   idea.status="todo" → pick → PATCH status=researching, linkedSwarmTaskId
+//     → swarm runs
+//        on success: PATCH status=developed
+//        on failure: PATCH status=todo (revert)
+//
+// `researching` is treated as "in flight" by M8.0; M8.1 will introduce a
+// separate research-cycle flow that also uses `researching` but disambiguates
+// via the presence of a research report. The status enum only has 5 values
+// (idea/todo/researching/developed/archived) so we accept the overload.
+import { encodeCwd } from "@mclawnet/shared";
+import { sortIdeasByPriorityThenAge } from "./idea-sort.js";
+/**
+ * Re-export the shared sort under the original name for back-compat with
+ * tests that imported `sortIdeasForPicking` from this module. S5 hotfix
+ * consolidates the implementation into `./idea-sort` so both sources stay
+ * in lockstep.
+ */
+export const sortIdeasForPicking = sortIdeasByPriorityThenAge;
+export function createIdeaTodoSource(opts) {
+    const { ideasClient, listLimit = 50, warn, info } = opts;
+    /**
+     * PR-B Sub-PR-B3 — cooldown duration for retryable shipFailureReason
+     * categories. 5min is short enough that transient outages don't strand
+     * the idea for hours, long enough that we don't burn budget retrying
+     * during an actual ongoing GH outage. Non-retryable reasons (auth /
+     * other) don't get a cooldown — they get retried immediately so the
+     * next cycle's onFailure can refresh the diagnosis (auth token may have
+     * been renewed; "other" may have resolved itself).
+     */
+    const RETRY_COOLDOWN_MS = 5 * 60 * 1000;
+    const RETRYABLE_REASONS = new Set(["network", "rate-limit"]);
+    return {
+        name: "idea-todo",
+        kind: "idea-todo",
+        async pick(projectRoot) {
+            let projectId;
+            try {
+                projectId = encodeCwd(projectRoot);
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), projectRoot }, "idea-todo-source: encodeCwd failed");
+                return null;
+            }
+            let ideas;
+            try {
+                ideas = await ideasClient.list({
+                    status: "todo",
+                    projectId,
+                    limit: listLimit,
+                });
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), projectId }, "idea-todo-source: list failed");
+                return null;
+            }
+            // Defensive filter: skip ideas without a projectId (the design says
+            // project-less ideas are not consumed) and double-check status in case
+            // the server returned a wider set.
+            // PR-B Sub-PR-B3: also skip ideas in retry cooldown — their previous
+            // ship failed with a transient reason (network/rate-limit) less than
+            // 5 min ago, so picking them now will just hit the same wall.
+            const nowMs = Date.now();
+            const matching = ideas.filter((i) => {
+                if (i.status !== "todo" || i.projectId !== projectId)
+                    return false;
+                const reason = i.shipFailureReason;
+                if (reason && RETRYABLE_REASONS.has(reason)) {
+                    const updatedAt = Date.parse(i.updatedAt);
+                    if (Number.isFinite(updatedAt) && nowMs - updatedAt < RETRY_COOLDOWN_MS) {
+                        info?.({ ideaId: i.id, reason, msSinceFailure: nowMs - updatedAt }, "idea-todo-source: skipping idea in ship-failure cooldown");
+                        return false;
+                    }
+                }
+                return true;
+            });
+            if (matching.length === 0)
+                return null;
+            const sorted = sortIdeasByPriorityThenAge(matching);
+            const head = sorted[0];
+            const description = head.body && head.body.trim().length > 0 ? head.body : undefined;
+            const taskRef = {
+                // The synthetic cycle TaskRef.id is the idea id — there's no other
+                // backing record. Downstream code that needs to disambiguate uses
+                // sourceKind + sourceId.
+                id: head.id,
+                title: head.title,
+                ...(description ? { description } : {}),
+                sourceKind: "idea-todo",
+                sourceId: head.id,
+            };
+            info?.({ ideaId: head.id, priority: head.priority, projectId }, "idea-todo-source: picked");
+            return taskRef;
+        },
+        async onClaim(taskRef, swarmId) {
+            const ideaId = taskRef.sourceId ?? taskRef.id;
+            try {
+                // M8.1: also stamp researchKind="execute" so this idea is
+                // distinguishable from a status=researching idea that was claimed by
+                // the M8.1 IdeaResearchSource (which sets researchKind="investigate").
+                //
+                // S3 hotfix note (M8 holistic review): the field is named
+                // `linkedSwarmTaskId` for back-compat (DB column shipped that way in
+                // migration 0014) but it actually stores a swarmId, not a taskId.
+                // Renaming would require a destructive migration; treat the name as
+                // historical until a future major bump consolidates the schema.
+                // S9 note: there's a known TOCTOU window between this PATCH and the
+                // hub-side write — if two agents race to claim the same idea, both
+                // can flip it to researching. M8 ships single-agent only; M9+ may
+                // add optimistic locking (If-Match etag or version field).
+                await ideasClient.patch(ideaId, {
+                    status: "researching",
+                    researchKind: "execute",
+                    linkedSwarmTaskId: swarmId,
+                    // PR-B Sub-PR-B3: clear stale failure reason on new claim — this
+                    // is a fresh attempt, the cooldown check above already gated us
+                    // through, and the UI shouldn't show "last ship failed: network"
+                    // on an idea that's currently in flight.
+                    shipFailureReason: null,
+                });
+                info?.({ ideaId, swarmId }, "idea-todo-source: claimed → researching (execute)");
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), ideaId, swarmId }, "idea-todo-source: onClaim patch failed");
+            }
+        },
+        async onSuccess(taskRef, swarmId) {
+            const ideaId = taskRef.sourceId ?? taskRef.id;
+            try {
+                // M8.1: clear researchKind on terminal transition — the idea is no
+                // longer in any researching flow.
+                // PR-B Sub-PR-B3: also clear shipFailureReason on success.
+                await ideasClient.patch(ideaId, {
+                    status: "developed",
+                    researchKind: null,
+                    shipFailureReason: null,
+                });
+                info?.({ ideaId, swarmId }, "idea-todo-source: marked developed");
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), ideaId, swarmId }, "idea-todo-source: onSuccess patch failed");
+            }
+        },
+        async onFailure(taskRef, swarmId, error) {
+            const ideaId = taskRef.sourceId ?? taskRef.id;
+            const reason = classifyShipFailure(error);
+            try {
+                // Revert to todo so the next cycle can pick it up again. Also clear
+                // linkedSwarmTaskId — B3: leaving it pointed at a destroyed swarm
+                // surfaces a dead deep-link in the UI and confuses cascade observers
+                // ("which swarm is this idea bound to?"). The breadcrumb was useful
+                // for in-flight debugging but stale once the cycle has failed.
+                // researchKind is also cleared so the idea is no longer in any
+                // researching flow on the UI.
+                // PR-B Sub-PR-B3: classify the error and persist as
+                // shipFailureReason so pick() can apply a 5-min cooldown on
+                // transient categories (network / rate-limit).
+                await ideasClient.patch(ideaId, {
+                    status: "todo",
+                    researchKind: null,
+                    linkedSwarmTaskId: null,
+                    shipFailureReason: reason,
+                });
+                info?.({ ideaId, swarmId, error: error ?? null, shipFailureReason: reason }, "idea-todo-source: reverted to todo after failure");
+            }
+            catch (err) {
+                warn?.({ err: err instanceof Error ? err.message : String(err), ideaId, swarmId, originalError: error }, "idea-todo-source: onFailure revert failed");
+            }
+        },
+    };
+}
+/**
+ * Helper exposed for callers that want to manually PATCH the idea to
+ * researching + linkedSwarmTaskId outside the cascade flow. Internally the
+ * IdeaTodoSource calls the same logic via its `onClaim` hook.
+ */
+export async function markIdeaResearching(ideasClient, ideaId, swarmId, log) {
+    try {
+        await ideasClient.patch(ideaId, {
+            status: "researching",
+            researchKind: "execute",
+            linkedSwarmTaskId: swarmId,
+        });
+    }
+    catch (err) {
+        log?.warn?.({ err: err instanceof Error ? err.message : String(err), ideaId, swarmId }, "idea-todo-source: markIdeaResearching failed");
+    }
+}
+/**
+ * PR-B Sub-PR-B3 — classify a swarm failure error into one of 4 categories
+ * used by `shipFailureReason`. The taxonomy intentionally collapses noisy
+ * variants:
+ *   - "network": ENOTFOUND / ETIMEDOUT / ECONNRESET / "network" anywhere
+ *     in the message — pick() applies a 5min cooldown before retry
+ *   - "rate-limit": "rate limit" / HTTP 429 — same 5min cooldown
+ *   - "auth": "401" / "403" / "auth" / "token" — NOT cooldowned (user
+ *     likely fixed the token between cycles)
+ *   - "other": anything else, no cooldown (retry immediately so we can
+ *     refresh the diagnosis)
+ *
+ * Exported for unit tests; callers should use `IdeaTodoSource.onFailure`
+ * which delegates here.
+ */
+export function classifyShipFailure(error) {
+    if (!error)
+        return "other";
+    const lower = error.toLowerCase();
+    if (lower.includes("enotfound") ||
+        lower.includes("etimedout") ||
+        lower.includes("econnreset") ||
+        lower.includes("econnrefused") ||
+        lower.includes("network")) {
+        return "network";
+    }
+    if (lower.includes("rate limit") || lower.includes("rate-limit") || lower.includes("429")) {
+        return "rate-limit";
+    }
+    if (lower.includes("401") || lower.includes("403") || lower.includes("auth") || lower.includes("token")) {
+        return "auth";
+    }
+    return "other";
+}
+//# sourceMappingURL=idea-todo-source.js.map

package/dist/always-on/task-sources/idea-todo-source.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idea-todo-source.js","sourceRoot":"","sources":["../../../src/always-on/task-sources/idea-todo-source.ts"],"names":[],"mappings":"AAAA,2EAA2E;AAC3E,uEAAuE;AACvE,EAAE;AACF,2BAA2B;AAC3B,4EAA4E;AAC5E,mBAAmB;AACnB,4CAA4C;AAC5C,gDAAgD;AAChD,EAAE;AACF,yEAAyE;AACzE,8EAA8E;AAC9E,2EAA2E;AAC3E,wEAAwE;AAExE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAE7C,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAgB5D;;;;;GAKG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,0BAA0B,CAAC;AAE9D,MAAM,UAAU,oBAAoB,CAAC,IAA2B;IAC9D,MAAM,EAAE,WAAW,EAAE,SAAS,GAAG,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,IAAI,CAAC;IAEzD;;;;;;;;OAQG;IACH,MAAM,iBAAiB,GAAG,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC;IACxC,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC,CAAC,SAAS,EAAE,YAAY,CAAC,CAAC,CAAC;IAE7D,OAAO;QACL,IAAI,EAAE,WAAW;QACjB,IAAI,EAAE,WAAW;QACjB,KAAK,CAAC,IAAI,CAAC,WAAmB;YAC5B,IAAI,SAAiB,CAAC;YACtB,IAAI,CAAC;gBACH,SAAS,GAAG,SAAS,CAAC,WAAW,CAAC,CAAC;YACrC,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,EAAE,CACJ,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,WAAW,EAAE,EACtE,oCAAoC,CACrC,CAAC;gBACF,OAAO,IAAI,CAAC;YACd,CAAC;YAED,IAAI,KAAa,CAAC;YAClB,IAAI,CAAC;gBACH,KAAK,GAAG,MAAM,WAAW,CAAC,IAAI,CAAC;oBAC7B,MAAM,EAAE,MAAM;oBACd,SAAS;oBACT,KAAK,EAAE,SAAS;iBACjB,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,EAAE,CACJ,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,SAAS,EAAE,EACpE,+BAA+B,CAChC,CAAC;gBACF,OAAO,IAAI,CAAC;YACd,CAAC;YAED,oEAAoE;YACpE,uEAAuE;YACvE,mCAAmC;YACnC,qEAAqE;YACrE,qEAAqE;YACrE,8DAA8D;YAC9D,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;YACzB,MAAM,QAAQ,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE;gBAClC,IAAI,CAAC,CAAC,MAAM,KAAK,MAAM,IAAI,CAAC,CAAC,SAAS,KAAK,SAAS;oBAAE,OAAO,KAAK,CAAC;gBACnE,MAAM,MAAM,GAAI,CAA2C,CAAC,iBAAiB,CAAC;gBAC9E,IAAI,MAAM,IAAI,iBAAiB,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;oBAC5C,MAAM,SAAS,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;oBAC1C,IAAI,MAAM,CAAC,QAAQ,CAAC,SAAS,CAAC,IAAI,KAAK,GAAG,SAAS,GAAG,iBAAiB,EAAE,CAAC;wBACxE,IAAI,EAAE,CACJ,EAAE,MAAM,EAAE,CAAC,CAAC,EAAE,EAAE,MAAM,EAAE,cAAc,EAAE,KAAK,GAAG,SAAS,EAAE,EAC3D,0DAA0D,CAC3D,CAAC;wBACF,OAAO,KAAK,CAAC;oBACf,CAAC;gBACH,CAAC;gBACD,OAAO,IAAI,CAAC;YACd,CAAC,CAAC,CAAC;YACH,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO,IAAI,CAAC;YAEvC,MAAM,MAAM,GAAG,0BAA0B,CAAC,QAAQ,CAAC,CAAC;YACpD,MAAM,IAAI,GAAG,MAAM,CAAC,CAAC,CAAC,CAAC;YAEvB,MAAM,WAAW,GAAG,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;YACrF,MAAM,OAAO,GAAY;gBACvB,mEAAmE;gBACnE,kEAAkE;gBAClE,yBAAyB;gBACzB,EAAE,EAAE,IAAI,CAAC,EAAE;gBACX,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvC,UAAU,EAAE,WAAW;gBACvB,QAAQ,EAAE,IAAI,CAAC,EAAE;aAClB,CAAC;YAEF,IAAI,EAAE,CACJ,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,EAAE,SAAS,EAAE,EACvD,0BAA0B,CAC3B,CAAC;YACF,OAAO,OAAO,CAAC;QACjB,CAAC;QAED,KAAK,CAAC,OAAO,CAAC,OAAgB,EAAE,OAAe;YAC7C,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC;gBACH,0DAA0D;gBAC1D,qEAAqE;gBACrE,uEAAuE;gBACvE,EAAE;gBACF,0DAA0D;gBAC1D,qEAAqE;gBACrE,kEAAkE;gBAClE,oEAAoE;gBACpE,gEAAgE;gBAChE,oEAAoE;gBACpE,mEAAmE;gBACnE,kEAAkE;gBAClE,2DAA2D;gBAC3D,MAAM,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE;oBAC9B,MAAM,EAAE,aAAa;oBACrB,YAAY,EAAE,SAAS;oBACvB,iBAAiB,EAAE,OAAO;oBAC1B,iEAAiE;oBACjE,gEAAgE;oBAChE,iEAAiE;oBACjE,yCAAyC;oBACzC,iBAAiB,EAAE,IAAI;iBACxB,CAAC,CAAC;gBACH,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,mDAAmD,CAAC,CAAC;YACnF,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,EAAE,CACJ,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAC1E,wCAAwC,CACzC,CAAC;YACJ,CAAC;QACH,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,OAAgB,EAAE,OAAe;YAC/C,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,EAAE,CAAC;YAC9C,IAAI,CAAC;gBACH,mEAAmE;gBACnE,kCAAkC;gBAClC,2DAA2D;gBAC3D,MAAM,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE;oBAC9B,MAAM,EAAE,WAAW;oBACnB,YAAY,EAAE,IAAI;oBAClB,iBAAiB,EAAE,IAAI;iBACxB,CAAC,CAAC;gBACH,IAAI,EAAE,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,oCAAoC,CAAC,CAAC;YACpE,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,EAAE,CACJ,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAC1E,0CAA0C,CAC3C,CAAC;YACJ,CAAC;QACH,CAAC;QAED,KAAK,CAAC,SAAS,CAAC,OAAgB,EAAE,OAAe,EAAE,KAAc;YAC/D,MAAM,MAAM,GAAG,OAAO,CAAC,QAAQ,IAAI,OAAO,CAAC,EAAE,CAAC;YAC9C,MAAM,MAAM,GAAG,mBAAmB,CAAC,KAAK,CAAC,CAAC;YAC1C,IAAI,CAAC;gBACH,oEAAoE;gBACpE,kEAAkE;gBAClE,qEAAqE;gBACrE,oEAAoE;gBACpE,+DAA+D;gBAC/D,+DAA+D;gBAC/D,8BAA8B;gBAC9B,oDAAoD;gBACpD,4DAA4D;gBAC5D,+CAA+C;gBAC/C,MAAM,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE;oBAC9B,MAAM,EAAE,MAAM;oBACd,YAAY,EAAE,IAAI;oBAClB,iBAAiB,EAAE,IAAI;oBACvB,iBAAiB,EAAE,MAAM;iBAC1B,CAAC,CAAC;gBACH,IAAI,EAAE,CACJ,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,KAAK,IAAI,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,EACpE,kDAAkD,CACnD,CAAC;YACJ,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,EAAE,CACJ,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,EAAE,KAAK,EAAE,EAChG,2CAA2C,CAC5C,CAAC;YACJ,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,WAAwB,EACxB,MAAc,EACd,OAAe,EACf,GAAiE;IAEjE,IAAI,CAAC;QACH,MAAM,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE;YAC9B,MAAM,EAAE,aAAa;YACrB,YAAY,EAAE,SAAS;YACvB,iBAAiB,EAAE,OAAO;SAC3B,CAAC,CAAC;IACL,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,GAAG,EAAE,IAAI,EAAE,CACT,EAAE,GAAG,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,EAC1E,8CAA8C,CAC/C,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,mBAAmB,CAAC,KAAc;IAChD,IAAI,CAAC,KAAK;QAAE,OAAO,OAAO,CAAC;IAC3B,MAAM,KAAK,GAAG,KAAK,CAAC,WAAW,EAAE,CAAC;IAClC,IACE,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC3B,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC;QAC3B,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC;QAC5B,KAAK,CAAC,QAAQ,CAAC,cAAc,CAAC;QAC9B,KAAK,CAAC,QAAQ,CAAC,SAAS,CAAC,EACzB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,YAAY,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1F,OAAO,YAAY,CAAC;IACtB,CAAC;IACD,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QACxG,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/always-on/task-sources/introspection-source.d.ts

@@ -0,0 +1,101 @@
+import type { SwarmCoordinator } from "../../swarm-coordinator.js";
+import type { AlwaysOnConfig, AlwaysOnPersistedConfig } from "../config.js";
+import type { IdeasClient } from "../ideas-client.js";
+import type { TaskSource } from "./types.js";
+export declare const INTROSPECTION_TEMPLATE_NAME = "introspection";
+export declare const INTROSPECTION_SOURCE_TAG = "auto-discovered";
+export declare const INTROSPECTION_SOURCE_ROLE = "queen-introspection";
+/** Hard cap per design doc D4 — no more than 3 ideas per introspection. */
+export declare 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 declare const SPAWNER_COMPLETE_MTIME_GUARD_MS = 5000;
+/**
+ * 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 declare const SPAWNER_COMPLETE_HARD_TIMEOUT_MS: number;
+/**
+ * Loose shape of one candidate JSON object the queen produces. Anything the
+ * queen wrote that isn't a string is dropped / coerced; priority is always
+ * overridden to "low" downstream.
+ */
+export interface IntrospectionCandidate {
+    title: string;
+    body?: string;
+    /** Recorded but overridden to "low" before POST. */
+    priority?: string;
+}
+export interface IntrospectionSourceOptions {
+    ideasClient: IdeasClient;
+    swarmCoordinator: SwarmCoordinator;
+    /**
+     * Read the persisted always-on config for a project. Called fresh on every
+     * pick() so the source sees the latest disk state without holding stale
+     * references. One IntrospectionSource serves N projects in the AlwaysOnManager
+     * cascade — that's why this is keyed by projectRoot.
+     */
+    getConfig: (projectRoot: string) => AlwaysOnPersistedConfig;
+    /**
+     * Apply a partial config patch for a project (lastIntrospectionAt /
+     * lastIntrospectionRejected / pendingIntrospectionSwarmId). Implementation
+     * persists via mergeAlwaysOnConfig + saveAlwaysOnConfig under the hood —
+     * the source treats this as opaque.
+     */
+    updateConfig: (projectRoot: string, patch: Omit<Partial<AlwaysOnConfig>, "lastIntrospectionAt" | "lastIntrospectionRejected" | "pendingIntrospectionSwarmId" | "pendingIntrospectionWorkspaceCwd"> & {
+        lastIntrospectionAt?: string | null;
+        lastIntrospectionRejected?: boolean | null;
+        pendingIntrospectionSwarmId?: string | null;
+        pendingIntrospectionWorkspaceCwd?: string | null;
+    }) => Promise<void>;
+    /** Override template name (tests + future custom flows). Defaults to "introspection". */
+    introspectionTemplateName?: string;
+    /** Test seam: clock. */
+    clock?: () => Date;
+    /** Optional logger. */
+    warn?: (obj: Record<string, unknown>, msg?: string) => void;
+    info?: (obj: Record<string, unknown>, msg?: string) => void;
+    /**
+     * Test seam: synthesise the swarm id used for the introspection cycle.
+     * Defaults to `m8-introspect-<uuid>` (prefix lets ops grep these out of
+     * regular work cycles in the always-on log).
+     */
+    generateSwarmId?: () => string;
+    /**
+     * Test seam: resolve the absolute output path the queen will write to.
+     * Defaults to `<projectRoot>/.clawnet/introspection/<swarmId>.json`.
+     */
+    resolveOutputPath?: (projectRoot: string, swarmId: string) => string;
+}
+/**
+ * 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 declare function parseCandidatesOutput(raw: string): IntrospectionCandidate[];
+/**
+ * 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 declare function buildIntrospectionTaskPrompt(projectRoot: string, relativeOutputPath: string): string;
+export declare function createIntrospectionSource(opts: IntrospectionSourceOptions): TaskSource;
+//# sourceMappingURL=introspection-source.d.ts.map

package/dist/always-on/task-sources/introspection-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"introspection-source.d.ts","sourceRoot":"","sources":["../../../src/always-on/task-sources/introspection-source.ts"],"names":[],"mappings":"AAkDA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,KAAK,EACV,cAAc,EACd,uBAAuB,EACxB,MAAM,cAAc,CAAC;AAKtB,OAAO,KAAK,EAAyB,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAO7E,OAAO,KAAK,EAAW,UAAU,EAAE,MAAM,YAAY,CAAC;AAEtD,eAAO,MAAM,2BAA2B,kBAAkB,CAAC;AAC3D,eAAO,MAAM,wBAAwB,oBAAoB,CAAC;AAC1D,eAAO,MAAM,yBAAyB,wBAAwB,CAAC;AAE/D,2EAA2E;AAC3E,eAAO,MAAM,uBAAuB,IAAI,CAAC;AAEzC;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,OAAQ,CAAC;AACrD;;;;;;;GAOG;AACH,eAAO,MAAM,gCAAgC,QAAqB,CAAC;AAEnE;;;;GAIG;AACH,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,WAAW,CAAC;IACzB,gBAAgB,EAAE,gBAAgB,CAAC;IACnC;;;;;OAKG;IACH,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,uBAAuB,CAAC;IAC5D;;;;;OAKG;IACH,YAAY,EAAE,CACZ,WAAW,EAAE,MAAM,EACnB,KAAK,EAAE,IAAI,CACT,OAAO,CAAC,cAAc,CAAC,EACvB,qBAAqB,GAAG,2BAA2B,GAAG,6BAA6B,GAAG,kCAAkC,CACzH,GAAG;QACF,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACpC,yBAAyB,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;QAC3C,2BAA2B,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5C,gCAAgC,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAClD,KACE,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,yFAAyF;IACzF,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,wBAAwB;IACxB,KAAK,CAAC,EAAE,MAAM,IAAI,CAAC;IACnB,uBAAuB;IACvB,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5D;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,MAAM,CAAC;IAC/B;;;OAGG;IACH,iBAAiB,CAAC,EAAE,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,KAAK,MAAM,CAAC;CACtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,sBAAsB,EAAE,CAqD3E;AAgBD;;;;;;;;;;;GAWG;AACH,wBAAgB,4BAA4B,CAC1C,WAAW,EAAE,MAAM,EACnB,kBAAkB,EAAE,MAAM,GACzB,MAAM,CAkBR;AAqBD,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,UAAU,CAqkBZ"}