@mastra/factory 0.12.1-alpha.1 → 0.13.0-alpha.2

package/dist/supervisor/health-worker.d.ts

@@ -0,0 +1,17 @@
+import { MastraWorker } from '@mastra/core/worker';
+import type { FactoryProjectsStorage } from '../storage/domains/projects/base.js';
+import type { WorkItemsStorage } from '../storage/domains/work-items/base.js';
+export declare const DEFAULT_SUPERVISOR_HEALTH_INTERVAL_MS: number;
+export declare class FactorySupervisorHealthWorker extends MastraWorker {
+    #private;
+    readonly name = "factory-supervisor-health";
+    constructor(input: {
+        projects: FactoryProjectsStorage;
+        workItems: WorkItemsStorage;
+        intervalMs?: number;
+    });
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    get isRunning(): boolean;
+}
+//# sourceMappingURL=health-worker.d.ts.map

package/dist/supervisor/health-worker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-worker.d.ts","sourceRoot":"","sources":["../../src/supervisor/health-worker.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAEnD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAC;AAClF,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAG9E,eAAO,MAAM,qCAAqC,QAAa,CAAC;AAEhE,qBAAa,6BAA8B,SAAQ,YAAY;;IAC7D,QAAQ,CAAC,IAAI,+BAA+B;gBAShC,KAAK,EAAE;QAAE,QAAQ,EAAE,sBAAsB,CAAC;QAAC,SAAS,EAAE,gBAAgB,CAAC;QAAC,UAAU,CAAC,EAAE,MAAM,CAAA;KAAE;IAOnG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAOtB,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAO3B,IAAI,SAAS,IAAI,OAAO,CAEvB;CA2CF"}

package/dist/supervisor/health-worker.js

@@ -0,0 +1,72 @@
+import { runFactoryHealthCheck } from "./health.js";
+import { MastraWorker } from "@mastra/core/worker";
+//#region src/supervisor/health-worker.ts
+const DEFAULT_SUPERVISOR_HEALTH_INTERVAL_MS = 5 * 6e4;
+var FactorySupervisorHealthWorker = class extends MastraWorker {
+	name = "factory-supervisor-health";
+	#projects;
+	#workItems;
+	#intervalMs;
+	#running = false;
+	#timer;
+	#inFlight;
+	constructor(input) {
+		super();
+		this.#projects = input.projects;
+		this.#workItems = input.workItems;
+		this.#intervalMs = input.intervalMs ?? 3e5;
+	}
+	async start() {
+		if (this.#running) return;
+		if (!this.deps) throw new Error("FactorySupervisorHealthWorker: call init() before start()");
+		this.#running = true;
+		this.#schedule(0);
+	}
+	async stop() {
+		this.#running = false;
+		if (this.#timer) clearTimeout(this.#timer);
+		this.#timer = void 0;
+		await this.#inFlight;
+	}
+	get isRunning() {
+		return this.#running;
+	}
+	#schedule(delayMs) {
+		if (!this.#running) return;
+		this.#timer = setTimeout(() => {
+			this.#timer = void 0;
+			this.#inFlight = this.#tick().catch((error) => this.deps?.logger.error("Factory supervisor health sweep failed", { error })).finally(() => {
+				this.#inFlight = void 0;
+				this.#schedule(this.#intervalMs);
+			});
+		}, delayMs);
+		this.#timer.unref?.();
+	}
+	async #tick() {
+		const now = /* @__PURE__ */ new Date();
+		const projects = await this.#projects.listAll();
+		const concurrency = 4;
+		let nextIndex = 0;
+		const failure = (await Promise.allSettled(Array.from({ length: Math.min(concurrency, projects.length) }, async () => {
+			while (nextIndex < projects.length) {
+				const project = projects[nextIndex++];
+				if (!project) return;
+				const report = await runFactoryHealthCheck(this.#workItems, {
+					orgId: project.orgId,
+					factoryProjectId: project.id
+				}, { now });
+				await this.#workItems.syncSupervisorFindings({
+					orgId: project.orgId,
+					factoryProjectId: project.id,
+					findings: report.findings,
+					now
+				});
+			}
+		}))).find((result) => result.status === "rejected");
+		if (failure) throw failure.reason;
+	}
+};
+//#endregion
+export { DEFAULT_SUPERVISOR_HEALTH_INTERVAL_MS, FactorySupervisorHealthWorker };
+
+//# sourceMappingURL=health-worker.js.map

package/dist/supervisor/health-worker.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health-worker.js","names":["#projects","#workItems","#intervalMs","#running","#schedule","#timer","#inFlight","#tick"],"sources":["../../src/supervisor/health-worker.ts"],"sourcesContent":["import { MastraWorker } from '@mastra/core/worker';\n\nimport type { FactoryProjectsStorage } from '../storage/domains/projects/base.js';\nimport type { WorkItemsStorage } from '../storage/domains/work-items/base.js';\nimport { runFactoryHealthCheck } from './health.js';\n\nexport const DEFAULT_SUPERVISOR_HEALTH_INTERVAL_MS = 5 * 60_000;\n\nexport class FactorySupervisorHealthWorker extends MastraWorker {\n  readonly name = 'factory-supervisor-health';\n\n  readonly #projects: FactoryProjectsStorage;\n  readonly #workItems: WorkItemsStorage;\n  readonly #intervalMs: number;\n  #running = false;\n  #timer: ReturnType<typeof setTimeout> | undefined;\n  #inFlight: Promise<void> | undefined;\n\n  constructor(input: { projects: FactoryProjectsStorage; workItems: WorkItemsStorage; intervalMs?: number }) {\n    super();\n    this.#projects = input.projects;\n    this.#workItems = input.workItems;\n    this.#intervalMs = input.intervalMs ?? DEFAULT_SUPERVISOR_HEALTH_INTERVAL_MS;\n  }\n\n  async start(): Promise<void> {\n    if (this.#running) return;\n    if (!this.deps) throw new Error('FactorySupervisorHealthWorker: call init() before start()');\n    this.#running = true;\n    this.#schedule(0);\n  }\n\n  async stop(): Promise<void> {\n    this.#running = false;\n    if (this.#timer) clearTimeout(this.#timer);\n    this.#timer = undefined;\n    await this.#inFlight;\n  }\n\n  get isRunning(): boolean {\n    return this.#running;\n  }\n\n  #schedule(delayMs: number): void {\n    if (!this.#running) return;\n    this.#timer = setTimeout(() => {\n      this.#timer = undefined;\n      this.#inFlight = this.#tick()\n        .catch(error => this.deps?.logger.error('Factory supervisor health sweep failed', { error }))\n        .finally(() => {\n          this.#inFlight = undefined;\n          this.#schedule(this.#intervalMs);\n        });\n    }, delayMs);\n    this.#timer.unref?.();\n  }\n\n  async #tick(): Promise<void> {\n    const now = new Date();\n    const projects = await this.#projects.listAll();\n    const concurrency = 4;\n    let nextIndex = 0;\n    const results = await Promise.allSettled(\n      Array.from({ length: Math.min(concurrency, projects.length) }, async () => {\n        while (nextIndex < projects.length) {\n          const project = projects[nextIndex++];\n          if (!project) return;\n          const report = await runFactoryHealthCheck(\n            this.#workItems,\n            { orgId: project.orgId, factoryProjectId: project.id },\n            { now },\n          );\n          await this.#workItems.syncSupervisorFindings({\n            orgId: project.orgId,\n            factoryProjectId: project.id,\n            findings: report.findings,\n            now,\n          });\n        }\n      }),\n    );\n    const failure = results.find((result): result is PromiseRejectedResult => result.status === 'rejected');\n    if (failure) throw failure.reason;\n  }\n}\n"],"mappings":";;;AAMA,MAAa,wCAAwC,IAAI;AAEzD,IAAa,gCAAb,cAAmD,aAAa;CAC9D,OAAgB;CAEhB;CACA;CACA;CACA,WAAW;CACX;CACA;CAEA,YAAY,OAA+F;EACzG,MAAM;EACN,KAAKA,YAAY,MAAM;EACvB,KAAKC,aAAa,MAAM;EACxB,KAAKC,cAAc,MAAM,cAAA;CAC3B;CAEA,MAAM,QAAuB;EAC3B,IAAI,KAAKC,UAAU;EACnB,IAAI,CAAC,KAAK,MAAM,MAAM,IAAI,MAAM,2DAA2D;EAC3F,KAAKA,WAAW;EAChB,KAAKC,UAAU,CAAC;CAClB;CAEA,MAAM,OAAsB;EAC1B,KAAKD,WAAW;EAChB,IAAI,KAAKE,QAAQ,aAAa,KAAKA,MAAM;EACzC,KAAKA,SAAS,KAAA;EACd,MAAM,KAAKC;CACb;CAEA,IAAI,YAAqB;EACvB,OAAO,KAAKH;CACd;CAEA,UAAU,SAAuB;EAC/B,IAAI,CAAC,KAAKA,UAAU;EACpB,KAAKE,SAAS,iBAAiB;GAC7B,KAAKA,SAAS,KAAA;GACd,KAAKC,YAAY,KAAKC,MAAM,CAAC,CAC1B,OAAM,UAAS,KAAK,MAAM,OAAO,MAAM,0CAA0C,EAAE,MAAM,CAAC,CAAC,CAAC,CAC5F,cAAc;IACb,KAAKD,YAAY,KAAA;IACjB,KAAKF,UAAU,KAAKF,WAAW;GACjC,CAAC;EACL,GAAG,OAAO;EACV,KAAKG,OAAO,QAAQ;CACtB;CAEA,MAAME,QAAuB;EAC3B,MAAM,sBAAM,IAAI,KAAK;EACrB,MAAM,WAAW,MAAM,KAAKP,UAAU,QAAQ;EAC9C,MAAM,cAAc;EACpB,IAAI,YAAY;EAoBhB,MAAM,WAAU,MAnBM,QAAQ,WAC5B,MAAM,KAAK,EAAE,QAAQ,KAAK,IAAI,aAAa,SAAS,MAAM,EAAE,GAAG,YAAY;GACzE,OAAO,YAAY,SAAS,QAAQ;IAClC,MAAM,UAAU,SAAS;IACzB,IAAI,CAAC,SAAS;IACd,MAAM,SAAS,MAAM,sBACnB,KAAKC,YACL;KAAE,OAAO,QAAQ;KAAO,kBAAkB,QAAQ;IAAG,GACrD,EAAE,IAAI,CACR;IACA,MAAM,KAAKA,WAAW,uBAAuB;KAC3C,OAAO,QAAQ;KACf,kBAAkB,QAAQ;KAC1B,UAAU,OAAO;KACjB;IACF,CAAC;GACH;EACF,CAAC,CACH,EAAA,CACwB,MAAM,WAA4C,OAAO,WAAW,UAAU;EACtG,IAAI,SAAS,MAAM,QAAQ;CAC7B;AACF"}

package/dist/supervisor/health.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Deterministic Factory health check.
+ *
+ * Every finding is computed from storage rows alone — no model, no controller —
+ * so the supervisor agent explains findings rather than inventing them, and the
+ * same list can be rendered by the UI or polled by a timer. Each finding names
+ * the row it came from and the standard repair a person (or the supervisor's
+ * write tools) would apply.
+ */
+import type { FactoryDeferredDecisionRecord, FactoryPendingStartRecord, FactoryRunBindingRecord, WorkItemRow, WorkItemsStorage } from '../storage/domains/work-items/base.js';
+export type FactoryHealthFindingKind = 'decision-failed' | 'decision-stuck' | 'start-stalled' | 'seat-orphaned' | 'seat-missing' | 'proposal-waiting' | 'held-waiting' | 'label-drift';
+export type FactoryHealthRepair = {
+    action: 'retry-decision';
+    decisionId: string;
+} | {
+    action: 'dismiss-decision';
+    decisionId: string;
+} | {
+    action: 'resolve-proposal';
+    decisionId: string;
+} | {
+    action: 'revoke-binding';
+    bindingId: string;
+} | {
+    action: 'accept-work-item';
+    workItemId: string;
+} | {
+    action: 'start-run';
+    workItemId: string;
+    role: string;
+} | {
+    action: 'reconcile-labels';
+    workItemId: string;
+};
+export interface FactoryHealthFinding {
+    kind: FactoryHealthFindingKind;
+    /** Stable per (kind, subject) so the UI and attention inbox can dedupe. */
+    id: string;
+    workItemId: string | null;
+    /** Card number as shown on the board, when the row carries one. */
+    workItemNumber: number | null;
+    title: string;
+    /** One sentence of grounded evidence: ids, timestamps, error text. */
+    evidence: string;
+    /** How long the condition has held, in ms, when it is age-based. */
+    ageMs: number | null;
+    suggestedRepair: FactoryHealthRepair | null;
+}
+export interface FactoryHealthReport {
+    checkedAt: string;
+    findings: FactoryHealthFinding[];
+    counts: Record<FactoryHealthFindingKind, number>;
+}
+export interface FactoryHealthThresholds {
+    /** A retry/pending decision whose `availableAt` is this far in the past never got picked up. */
+    stuckDecisionMs: number;
+    /** A lease this far past its expiry belongs to a worker that died mid-dispatch. */
+    expiredLeaseMs: number;
+    /** A pending start this old is not "booting", it is stalled. */
+    stalledStartMs: number;
+    /** Proposals and held cards older than this are worth nudging a person about. */
+    waitingOnPersonMs: number;
+}
+export declare const DEFAULT_HEALTH_THRESHOLDS: FactoryHealthThresholds;
+interface HealthInputs {
+    items: WorkItemRow[];
+    decisions: FactoryDeferredDecisionRecord[];
+    bindings: FactoryRunBindingRecord[];
+    pendingStarts: FactoryPendingStartRecord[];
+}
+/** Pure: findings from rows. Exported so tests can feed fixtures directly. */
+export declare function computeFactoryHealth(inputs: HealthInputs, now: Date, thresholds?: FactoryHealthThresholds): FactoryHealthReport;
+export declare function runFactoryHealthCheck(workItems: WorkItemsStorage, scope: {
+    orgId: string;
+    factoryProjectId: string;
+}, options?: {
+    now?: Date;
+    thresholds?: FactoryHealthThresholds;
+}): Promise<FactoryHealthReport>;
+export {};
+//# sourceMappingURL=health.d.ts.map

package/dist/supervisor/health.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.d.ts","sourceRoot":"","sources":["../../src/supervisor/health.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAIH,OAAO,KAAK,EACV,6BAA6B,EAC7B,yBAAyB,EACzB,uBAAuB,EACvB,WAAW,EACX,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAE/C,MAAM,MAAM,wBAAwB,GAChC,iBAAiB,GACjB,gBAAgB,GAChB,eAAe,GACf,eAAe,GACf,cAAc,GACd,kBAAkB,GAClB,cAAc,GACd,aAAa,CAAC;AAElB,MAAM,MAAM,mBAAmB,GAC3B;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,MAAM,EAAE,gBAAgB,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAClD;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,MAAM,EAAE,kBAAkB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC,IAAI,EAAE,wBAAwB,CAAC;IAC/B,2EAA2E;IAC3E,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,mEAAmE;IACnE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,sEAAsE;IACtE,QAAQ,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,eAAe,EAAE,mBAAmB,GAAG,IAAI,CAAC;CAC7C;AAED,MAAM,WAAW,mBAAmB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,oBAAoB,EAAE,CAAC;IACjC,MAAM,EAAE,MAAM,CAAC,wBAAwB,EAAE,MAAM,CAAC,CAAC;CAClD;AAED,MAAM,WAAW,uBAAuB;IACtC,gGAAgG;IAChG,eAAe,EAAE,MAAM,CAAC;IACxB,mFAAmF;IACnF,cAAc,EAAE,MAAM,CAAC;IACvB,gEAAgE;IAChE,cAAc,EAAE,MAAM,CAAC;IACvB,iFAAiF;IACjF,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,eAAO,MAAM,yBAAyB,EAAE,uBAKvC,CAAC;AAqDF,UAAU,YAAY;IACpB,KAAK,EAAE,WAAW,EAAE,CAAC;IACrB,SAAS,EAAE,6BAA6B,EAAE,CAAC;IAC3C,QAAQ,EAAE,uBAAuB,EAAE,CAAC;IACpC,aAAa,EAAE,yBAAyB,EAAE,CAAC;CAC5C;AAED,8EAA8E;AAC9E,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,YAAY,EACpB,GAAG,EAAE,IAAI,EACT,UAAU,GAAE,uBAAmD,GAC9D,mBAAmB,CA2JrB;AAED,wBAAsB,qBAAqB,CACzC,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,gBAAgB,EAAE,MAAM,CAAA;CAAE,EAClD,OAAO,GAAE;IAAE,GAAG,CAAC,EAAE,IAAI,CAAC;IAAC,UAAU,CAAC,EAAE,uBAAuB,CAAA;CAAO,GACjE,OAAO,CAAC,mBAAmB,CAAC,CAY9B"}

package/dist/supervisor/health.js

@@ -0,0 +1,245 @@
+import { NEEDS_APPROVAL_LABEL } from "../integrations/github/acceptance-labels.js";
+import { FACTORY_ROLE_STAGES, factoryRuleStage, isTerminalFactoryRuleStage } from "../rules/types.js";
+//#region src/supervisor/health.ts
+/**
+* Deterministic Factory health check.
+*
+* Every finding is computed from storage rows alone — no model, no controller —
+* so the supervisor agent explains findings rather than inventing them, and the
+* same list can be rendered by the UI or polled by a timer. Each finding names
+* the row it came from and the standard repair a person (or the supervisor's
+* write tools) would apply.
+*/
+const DEFAULT_HEALTH_THRESHOLDS = {
+	stuckDecisionMs: 10 * 6e4,
+	expiredLeaseMs: 5 * 6e4,
+	stalledStartMs: 10 * 6e4,
+	waitingOnPersonMs: 1440 * 6e4
+};
+const FINDING_KINDS = [
+	"decision-failed",
+	"decision-stuck",
+	"start-stalled",
+	"seat-orphaned",
+	"seat-missing",
+	"proposal-waiting",
+	"held-waiting",
+	"label-drift"
+];
+const IN_FLIGHT_DECISION_STATUSES = /* @__PURE__ */ new Set([
+	"pending",
+	"retry",
+	"leased",
+	"proposed"
+]);
+/** Working lane → the role whose seat carries a card through it. */
+const ROLE_FOR_LANE = new Map(Object.entries(FACTORY_ROLE_STAGES).map(([role, lane]) => [lane, role]));
+function itemNumber(item) {
+	const number = item?.metadata?.number ?? item?.metadata?.githubIssueNumber ?? item?.metadata?.githubPullRequestNumber;
+	return typeof number === "number" ? number : null;
+}
+function itemLabels(item) {
+	const labels = item.metadata?.labels;
+	return Array.isArray(labels) ? labels.filter((label) => typeof label === "string") : [];
+}
+function decisionType(decision) {
+	const type = decision.decision.type;
+	return typeof type === "string" ? type : "decision";
+}
+function decisionRole(decision) {
+	const role = decision.decision.role;
+	return typeof role === "string" ? role : null;
+}
+function describeDecision(decision) {
+	const role = decisionRole(decision);
+	return role ? `${decisionType(decision)} (${role})` : decisionType(decision);
+}
+function truncate(text, max = 200) {
+	return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+function stageEnteredAt(item) {
+	const open = [...item.stageHistory].reverse().find((entry) => !entry.exitedAt);
+	const at = open ? Date.parse(open.enteredAt) : NaN;
+	return Number.isFinite(at) ? new Date(at) : null;
+}
+/** Pure: findings from rows. Exported so tests can feed fixtures directly. */
+function computeFactoryHealth(inputs, now, thresholds = DEFAULT_HEALTH_THRESHOLDS) {
+	const itemsById = new Map(inputs.items.map((item) => [item.id, item]));
+	const findings = [];
+	const subject = (workItemId) => {
+		const item = workItemId ? itemsById.get(workItemId) : void 0;
+		return {
+			workItemId,
+			workItemNumber: itemNumber(item),
+			title: item?.title ?? ""
+		};
+	};
+	for (const decision of inputs.decisions) {
+		const base = subject(decision.workItemId);
+		if (decision.status === "failed") {
+			findings.push({
+				kind: "decision-failed",
+				id: `decision-failed:${decision.id}`,
+				...base,
+				evidence: `Decision ${decision.id} (${describeDecision(decision)}) failed after ${decision.attempts} attempt(s) at ${decision.updatedAt.toISOString()}${decision.failureCode ? ` [${decision.failureCode}]` : ""}: ${truncate(decision.lastError ?? "no error recorded")}`,
+				ageMs: now.getTime() - decision.updatedAt.getTime(),
+				suggestedRepair: {
+					action: "retry-decision",
+					decisionId: decision.id
+				}
+			});
+			continue;
+		}
+		if (decision.status === "retry" || decision.status === "pending") {
+			const overdue = now.getTime() - decision.availableAt.getTime();
+			if (overdue > thresholds.stuckDecisionMs) findings.push({
+				kind: "decision-stuck",
+				id: `decision-stuck:${decision.id}`,
+				...base,
+				evidence: `Decision ${decision.id} (${describeDecision(decision)}) has been ${decision.status} since ${decision.availableAt.toISOString()} with ${decision.attempts} attempt(s) and was never leased; is the dispatcher running?`,
+				ageMs: overdue,
+				suggestedRepair: null
+			});
+			continue;
+		}
+		if (decision.status === "leased" && decision.leaseExpiresAt) {
+			const expired = now.getTime() - decision.leaseExpiresAt.getTime();
+			if (expired > thresholds.expiredLeaseMs) findings.push({
+				kind: "decision-stuck",
+				id: `decision-stuck:${decision.id}`,
+				...base,
+				evidence: `Decision ${decision.id} (${describeDecision(decision)}) is still leased by ${decision.leaseOwner ?? "unknown"} though the lease expired at ${decision.leaseExpiresAt.toISOString()}; the worker likely died mid-dispatch.`,
+				ageMs: expired,
+				suggestedRepair: null
+			});
+			continue;
+		}
+		if (decision.status === "proposed") {
+			const waiting = now.getTime() - decision.createdAt.getTime();
+			if (waiting > thresholds.waitingOnPersonMs) findings.push({
+				kind: "proposal-waiting",
+				id: `proposal-waiting:${decision.id}`,
+				...base,
+				evidence: `Proposed run ${decision.id} (${describeDecision(decision)}) has waited for a person since ${decision.createdAt.toISOString()}.`,
+				ageMs: waiting,
+				suggestedRepair: {
+					action: "resolve-proposal",
+					decisionId: decision.id
+				}
+			});
+		}
+	}
+	const bindingsById = new Map(inputs.bindings.map((binding) => [binding.id, binding]));
+	for (const start of inputs.pendingStarts) {
+		if (start.status === "sent") continue;
+		const binding = bindingsById.get(start.bindingId);
+		const base = subject(binding?.workItemId ?? null);
+		const age = now.getTime() - start.createdAt.getTime();
+		if (start.status === "failed" || age > thresholds.stalledStartMs) findings.push({
+			kind: "start-stalled",
+			id: `start-stalled:${start.id}`,
+			...base,
+			evidence: `Pending start ${start.id}${binding ? ` for the ${binding.role} seat` : ""} is ${start.status} since ${start.createdAt.toISOString()} after ${start.attempts} attempt(s)${start.lastError ? `: ${truncate(start.lastError)}` : "."}`,
+			ageMs: age,
+			suggestedRepair: binding ? {
+				action: "revoke-binding",
+				bindingId: binding.id
+			} : null
+		});
+	}
+	const activeSeatsByItem = /* @__PURE__ */ new Map();
+	for (const binding of inputs.bindings) {
+		if (binding.status !== "active") continue;
+		const item = itemsById.get(binding.workItemId);
+		const stage = item ? factoryRuleStage(item.stages) : void 0;
+		if (!item || !stage || isTerminalFactoryRuleStage([stage])) {
+			findings.push({
+				kind: "seat-orphaned",
+				id: `seat-orphaned:${binding.id}`,
+				...subject(item ? item.id : null),
+				evidence: item ? `Binding ${binding.id} (${binding.role}) is still active though the card is in ${stage ?? item.stages.join("+")}.` : `Binding ${binding.id} (${binding.role}) is active for work item ${binding.workItemId}, which no longer exists.`,
+				ageMs: now.getTime() - binding.createdAt.getTime(),
+				suggestedRepair: {
+					action: "revoke-binding",
+					bindingId: binding.id
+				}
+			});
+			continue;
+		}
+		const seats = activeSeatsByItem.get(item.id) ?? [];
+		seats.push(binding);
+		activeSeatsByItem.set(item.id, seats);
+	}
+	const inFlightByItem = new Set(inputs.decisions.filter((d) => d.workItemId && IN_FLIGHT_DECISION_STATUSES.has(d.status)).map((d) => d.workItemId));
+	for (const item of inputs.items) {
+		const stage = factoryRuleStage(item.stages);
+		if (!stage || stage === "intake" || isTerminalFactoryRuleStage([stage])) continue;
+		const base = subject(item.id);
+		const enteredAt = stageEnteredAt(item);
+		const inStageMs = enteredAt ? now.getTime() - enteredAt.getTime() : null;
+		if (stage === "triage" && item.triageType !== null && item.triageType !== "bug" && !item.acceptedAt) {
+			if (inStageMs !== null && inStageMs > thresholds.waitingOnPersonMs) findings.push({
+				kind: "held-waiting",
+				id: `held-waiting:${item.id}`,
+				...base,
+				evidence: `Triaged as "${item.triageType}" and waiting for a maintainer's decision since ${enteredAt.toISOString()}.`,
+				ageMs: inStageMs,
+				suggestedRepair: {
+					action: "accept-work-item",
+					workItemId: item.id
+				}
+			});
+		} else if (!activeSeatsByItem.has(item.id) && !inFlightByItem.has(item.id)) {
+			const role = ROLE_FOR_LANE.get(stage);
+			findings.push({
+				kind: "seat-missing",
+				id: `seat-missing:${item.id}`,
+				...base,
+				evidence: `In ${stage} since ${enteredAt?.toISOString() ?? "unknown"} with no active seat and no decision in flight; nothing will move it.`,
+				ageMs: inStageMs,
+				suggestedRepair: role ? {
+					action: "start-run",
+					workItemId: item.id,
+					role
+				} : null
+			});
+		}
+		if (item.acceptedAt && itemLabels(item).includes("status: needs approval")) findings.push({
+			kind: "label-drift",
+			id: `label-drift:${item.id}`,
+			...base,
+			evidence: `Accepted at ${item.acceptedAt.toISOString()} but the last observed labels still include "${NEEDS_APPROVAL_LABEL}".`,
+			ageMs: now.getTime() - item.acceptedAt.getTime(),
+			suggestedRepair: {
+				action: "reconcile-labels",
+				workItemId: item.id
+			}
+		});
+	}
+	findings.sort((a, b) => (b.ageMs ?? 0) - (a.ageMs ?? 0));
+	const counts = Object.fromEntries(FINDING_KINDS.map((kind) => [kind, 0]));
+	for (const finding of findings) counts[finding.kind] += 1;
+	return {
+		checkedAt: now.toISOString(),
+		findings,
+		counts
+	};
+}
+async function runFactoryHealthCheck(workItems, scope, options = {}) {
+	const [items, decisions, bindings, pendingStarts] = await Promise.all([
+		workItems.list(scope),
+		workItems.listDeferredDecisions(scope.orgId, scope.factoryProjectId),
+		workItems.listRunBindings(scope.orgId, scope.factoryProjectId),
+		workItems.listPendingStarts(scope.orgId, scope.factoryProjectId)
+	]);
+	return computeFactoryHealth({
+		items,
+		decisions,
+		bindings,
+		pendingStarts
+	}, options.now ?? /* @__PURE__ */ new Date(), options.thresholds);
+}
+//#endregion
+export { DEFAULT_HEALTH_THRESHOLDS, computeFactoryHealth, runFactoryHealthCheck };
+
+//# sourceMappingURL=health.js.map

package/dist/supervisor/health.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"health.js","names":[],"sources":["../../src/supervisor/health.ts"],"sourcesContent":["/**\n * Deterministic Factory health check.\n *\n * Every finding is computed from storage rows alone — no model, no controller —\n * so the supervisor agent explains findings rather than inventing them, and the\n * same list can be rendered by the UI or polled by a timer. Each finding names\n * the row it came from and the standard repair a person (or the supervisor's\n * write tools) would apply.\n */\n\nimport { NEEDS_APPROVAL_LABEL } from '../integrations/github/acceptance-labels.js';\nimport { FACTORY_ROLE_STAGES, factoryRuleStage, isTerminalFactoryRuleStage } from '../rules/types.js';\nimport type {\n  FactoryDeferredDecisionRecord,\n  FactoryPendingStartRecord,\n  FactoryRunBindingRecord,\n  WorkItemRow,\n  WorkItemsStorage,\n} from '../storage/domains/work-items/base.js';\n\nexport type FactoryHealthFindingKind =\n  | 'decision-failed'\n  | 'decision-stuck'\n  | 'start-stalled'\n  | 'seat-orphaned'\n  | 'seat-missing'\n  | 'proposal-waiting'\n  | 'held-waiting'\n  | 'label-drift';\n\nexport type FactoryHealthRepair =\n  | { action: 'retry-decision'; decisionId: string }\n  | { action: 'dismiss-decision'; decisionId: string }\n  | { action: 'resolve-proposal'; decisionId: string }\n  | { action: 'revoke-binding'; bindingId: string }\n  | { action: 'accept-work-item'; workItemId: string }\n  | { action: 'start-run'; workItemId: string; role: string }\n  | { action: 'reconcile-labels'; workItemId: string };\n\nexport interface FactoryHealthFinding {\n  kind: FactoryHealthFindingKind;\n  /** Stable per (kind, subject) so the UI and attention inbox can dedupe. */\n  id: string;\n  workItemId: string | null;\n  /** Card number as shown on the board, when the row carries one. */\n  workItemNumber: number | null;\n  title: string;\n  /** One sentence of grounded evidence: ids, timestamps, error text. */\n  evidence: string;\n  /** How long the condition has held, in ms, when it is age-based. */\n  ageMs: number | null;\n  suggestedRepair: FactoryHealthRepair | null;\n}\n\nexport interface FactoryHealthReport {\n  checkedAt: string;\n  findings: FactoryHealthFinding[];\n  counts: Record<FactoryHealthFindingKind, number>;\n}\n\nexport interface FactoryHealthThresholds {\n  /** A retry/pending decision whose `availableAt` is this far in the past never got picked up. */\n  stuckDecisionMs: number;\n  /** A lease this far past its expiry belongs to a worker that died mid-dispatch. */\n  expiredLeaseMs: number;\n  /** A pending start this old is not \"booting\", it is stalled. */\n  stalledStartMs: number;\n  /** Proposals and held cards older than this are worth nudging a person about. */\n  waitingOnPersonMs: number;\n}\n\nexport const DEFAULT_HEALTH_THRESHOLDS: FactoryHealthThresholds = {\n  stuckDecisionMs: 10 * 60_000,\n  expiredLeaseMs: 5 * 60_000,\n  stalledStartMs: 10 * 60_000,\n  waitingOnPersonMs: 24 * 60 * 60_000,\n};\n\nconst FINDING_KINDS: FactoryHealthFindingKind[] = [\n  'decision-failed',\n  'decision-stuck',\n  'start-stalled',\n  'seat-orphaned',\n  'seat-missing',\n  'proposal-waiting',\n  'held-waiting',\n  'label-drift',\n];\n\nconst IN_FLIGHT_DECISION_STATUSES = new Set(['pending', 'retry', 'leased', 'proposed']);\n\n/** Working lane → the role whose seat carries a card through it. */\nconst ROLE_FOR_LANE = new Map<string, string>(Object.entries(FACTORY_ROLE_STAGES).map(([role, lane]) => [lane, role]));\n\nfunction itemNumber(item: WorkItemRow | undefined): number | null {\n  const number = item?.metadata?.number ?? item?.metadata?.githubIssueNumber ?? item?.metadata?.githubPullRequestNumber;\n  return typeof number === 'number' ? number : null;\n}\n\nfunction itemLabels(item: WorkItemRow): string[] {\n  const labels = item.metadata?.labels;\n  return Array.isArray(labels) ? labels.filter((label): label is string => typeof label === 'string') : [];\n}\n\nfunction decisionType(decision: FactoryDeferredDecisionRecord): string {\n  const type = decision.decision.type;\n  return typeof type === 'string' ? type : 'decision';\n}\n\nfunction decisionRole(decision: FactoryDeferredDecisionRecord): string | null {\n  const role = decision.decision.role;\n  return typeof role === 'string' ? role : null;\n}\n\nfunction describeDecision(decision: FactoryDeferredDecisionRecord): string {\n  const role = decisionRole(decision);\n  return role ? `${decisionType(decision)} (${role})` : decisionType(decision);\n}\n\nfunction truncate(text: string, max = 200): string {\n  return text.length > max ? `${text.slice(0, max - 1)}…` : text;\n}\n\nfunction stageEnteredAt(item: WorkItemRow): Date | null {\n  const open = [...item.stageHistory].reverse().find(entry => !entry.exitedAt);\n  const at = open ? Date.parse(open.enteredAt) : Number.NaN;\n  return Number.isFinite(at) ? new Date(at) : null;\n}\n\ninterface HealthInputs {\n  items: WorkItemRow[];\n  decisions: FactoryDeferredDecisionRecord[];\n  bindings: FactoryRunBindingRecord[];\n  pendingStarts: FactoryPendingStartRecord[];\n}\n\n/** Pure: findings from rows. Exported so tests can feed fixtures directly. */\nexport function computeFactoryHealth(\n  inputs: HealthInputs,\n  now: Date,\n  thresholds: FactoryHealthThresholds = DEFAULT_HEALTH_THRESHOLDS,\n): FactoryHealthReport {\n  const itemsById = new Map(inputs.items.map(item => [item.id, item]));\n  const findings: FactoryHealthFinding[] = [];\n  const subject = (workItemId: string | null) => {\n    const item = workItemId ? itemsById.get(workItemId) : undefined;\n    return { workItemId, workItemNumber: itemNumber(item), title: item?.title ?? '' };\n  };\n\n  for (const decision of inputs.decisions) {\n    const base = subject(decision.workItemId);\n    if (decision.status === 'failed') {\n      findings.push({\n        kind: 'decision-failed',\n        id: `decision-failed:${decision.id}`,\n        ...base,\n        evidence: `Decision ${decision.id} (${describeDecision(decision)}) failed after ${decision.attempts} attempt(s) at ${decision.updatedAt.toISOString()}${decision.failureCode ? ` [${decision.failureCode}]` : ''}: ${truncate(decision.lastError ?? 'no error recorded')}`,\n        ageMs: now.getTime() - decision.updatedAt.getTime(),\n        suggestedRepair: { action: 'retry-decision', decisionId: decision.id },\n      });\n      continue;\n    }\n    if (decision.status === 'retry' || decision.status === 'pending') {\n      const overdue = now.getTime() - decision.availableAt.getTime();\n      if (overdue > thresholds.stuckDecisionMs) {\n        findings.push({\n          kind: 'decision-stuck',\n          id: `decision-stuck:${decision.id}`,\n          ...base,\n          evidence: `Decision ${decision.id} (${describeDecision(decision)}) has been ${decision.status} since ${decision.availableAt.toISOString()} with ${decision.attempts} attempt(s) and was never leased; is the dispatcher running?`,\n          ageMs: overdue,\n          suggestedRepair: null,\n        });\n      }\n      continue;\n    }\n    if (decision.status === 'leased' && decision.leaseExpiresAt) {\n      const expired = now.getTime() - decision.leaseExpiresAt.getTime();\n      if (expired > thresholds.expiredLeaseMs) {\n        findings.push({\n          kind: 'decision-stuck',\n          id: `decision-stuck:${decision.id}`,\n          ...base,\n          evidence: `Decision ${decision.id} (${describeDecision(decision)}) is still leased by ${decision.leaseOwner ?? 'unknown'} though the lease expired at ${decision.leaseExpiresAt.toISOString()}; the worker likely died mid-dispatch.`,\n          ageMs: expired,\n          suggestedRepair: null,\n        });\n      }\n      continue;\n    }\n    if (decision.status === 'proposed') {\n      const waiting = now.getTime() - decision.createdAt.getTime();\n      if (waiting > thresholds.waitingOnPersonMs) {\n        findings.push({\n          kind: 'proposal-waiting',\n          id: `proposal-waiting:${decision.id}`,\n          ...base,\n          evidence: `Proposed run ${decision.id} (${describeDecision(decision)}) has waited for a person since ${decision.createdAt.toISOString()}.`,\n          ageMs: waiting,\n          suggestedRepair: { action: 'resolve-proposal', decisionId: decision.id },\n        });\n      }\n    }\n  }\n\n  const bindingsById = new Map(inputs.bindings.map(binding => [binding.id, binding]));\n  for (const start of inputs.pendingStarts) {\n    if (start.status === 'sent') continue;\n    const binding = bindingsById.get(start.bindingId);\n    const base = subject(binding?.workItemId ?? null);\n    const age = now.getTime() - start.createdAt.getTime();\n    if (start.status === 'failed' || age > thresholds.stalledStartMs) {\n      findings.push({\n        kind: 'start-stalled',\n        id: `start-stalled:${start.id}`,\n        ...base,\n        evidence: `Pending start ${start.id}${binding ? ` for the ${binding.role} seat` : ''} is ${start.status} since ${start.createdAt.toISOString()} after ${start.attempts} attempt(s)${start.lastError ? `: ${truncate(start.lastError)}` : '.'}`,\n        ageMs: age,\n        suggestedRepair: binding ? { action: 'revoke-binding', bindingId: binding.id } : null,\n      });\n    }\n  }\n\n  const activeSeatsByItem = new Map<string, FactoryRunBindingRecord[]>();\n  for (const binding of inputs.bindings) {\n    if (binding.status !== 'active') continue;\n    const item = itemsById.get(binding.workItemId);\n    const stage = item ? factoryRuleStage(item.stages) : undefined;\n    if (!item || !stage || isTerminalFactoryRuleStage([stage])) {\n      findings.push({\n        kind: 'seat-orphaned',\n        id: `seat-orphaned:${binding.id}`,\n        ...subject(item ? item.id : null),\n        evidence: item\n          ? `Binding ${binding.id} (${binding.role}) is still active though the card is in ${stage ?? item.stages.join('+')}.`\n          : `Binding ${binding.id} (${binding.role}) is active for work item ${binding.workItemId}, which no longer exists.`,\n        ageMs: now.getTime() - binding.createdAt.getTime(),\n        suggestedRepair: { action: 'revoke-binding', bindingId: binding.id },\n      });\n      continue;\n    }\n    const seats = activeSeatsByItem.get(item.id) ?? [];\n    seats.push(binding);\n    activeSeatsByItem.set(item.id, seats);\n  }\n\n  const inFlightByItem = new Set(\n    inputs.decisions.filter(d => d.workItemId && IN_FLIGHT_DECISION_STATUSES.has(d.status)).map(d => d.workItemId!),\n  );\n  for (const item of inputs.items) {\n    const stage = factoryRuleStage(item.stages);\n    if (!stage || stage === 'intake' || isTerminalFactoryRuleStage([stage])) continue;\n    const base = subject(item.id);\n    const enteredAt = stageEnteredAt(item);\n    const inStageMs = enteredAt ? now.getTime() - enteredAt.getTime() : null;\n\n    const held = stage === 'triage' && item.triageType !== null && item.triageType !== 'bug' && !item.acceptedAt;\n    if (held) {\n      if (inStageMs !== null && inStageMs > thresholds.waitingOnPersonMs) {\n        findings.push({\n          kind: 'held-waiting',\n          id: `held-waiting:${item.id}`,\n          ...base,\n          evidence: `Triaged as \"${item.triageType}\" and waiting for a maintainer's decision since ${enteredAt!.toISOString()}.`,\n          ageMs: inStageMs,\n          suggestedRepair: { action: 'accept-work-item', workItemId: item.id },\n        });\n      }\n    } else if (!activeSeatsByItem.has(item.id) && !inFlightByItem.has(item.id)) {\n      const role = ROLE_FOR_LANE.get(stage);\n      findings.push({\n        kind: 'seat-missing',\n        id: `seat-missing:${item.id}`,\n        ...base,\n        evidence: `In ${stage} since ${enteredAt?.toISOString() ?? 'unknown'} with no active seat and no decision in flight; nothing will move it.`,\n        ageMs: inStageMs,\n        suggestedRepair: role ? { action: 'start-run', workItemId: item.id, role } : null,\n      });\n    }\n\n    if (item.acceptedAt && itemLabels(item).includes(NEEDS_APPROVAL_LABEL)) {\n      findings.push({\n        kind: 'label-drift',\n        id: `label-drift:${item.id}`,\n        ...base,\n        evidence: `Accepted at ${item.acceptedAt.toISOString()} but the last observed labels still include \"${NEEDS_APPROVAL_LABEL}\".`,\n        ageMs: now.getTime() - item.acceptedAt.getTime(),\n        suggestedRepair: { action: 'reconcile-labels', workItemId: item.id },\n      });\n    }\n  }\n\n  findings.sort((a, b) => (b.ageMs ?? 0) - (a.ageMs ?? 0));\n  const counts = Object.fromEntries(FINDING_KINDS.map(kind => [kind, 0])) as Record<FactoryHealthFindingKind, number>;\n  for (const finding of findings) counts[finding.kind] += 1;\n  return { checkedAt: now.toISOString(), findings, counts };\n}\n\nexport async function runFactoryHealthCheck(\n  workItems: WorkItemsStorage,\n  scope: { orgId: string; factoryProjectId: string },\n  options: { now?: Date; thresholds?: FactoryHealthThresholds } = {},\n): Promise<FactoryHealthReport> {\n  const [items, decisions, bindings, pendingStarts] = await Promise.all([\n    workItems.list(scope),\n    workItems.listDeferredDecisions(scope.orgId, scope.factoryProjectId),\n    workItems.listRunBindings(scope.orgId, scope.factoryProjectId),\n    workItems.listPendingStarts(scope.orgId, scope.factoryProjectId),\n  ]);\n  return computeFactoryHealth(\n    { items, decisions, bindings, pendingStarts },\n    options.now ?? new Date(),\n    options.thresholds,\n  );\n}\n"],"mappings":"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"}

package/dist/supervisor/instructions.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The supervisor's playbook. Lives in code (not a workspace skill) because
+ * the supervisor session has no checkout to load skills from.
+ */
+export declare const SUPERVISOR_INSTRUCTIONS = "# Factory supervisor\n\nYou supervise one Software Factory: a pipeline of cards (work items) that move\nintake \u2192 triage \u2192 planning \u2192 execute \u2192 review \u2192 done|canceled. Four agent roles\n(triage, plan, work, review) each hold a *seat* (run binding) on a card while\nthey act on it; every role on a card shares one session thread. Typed rules\nemit *decisions* (invoke a skill, send a message, sync a linked card, \u2026) that a\ndispatcher executes with retries; a decision that exhausts its retries is\n*failed* and shows the card red. Some decisions are *proposals* parked for a\nperson to approve. Non-bug cards are *held* in triage until a maintainer\naccepts them.\n\nYou have no repository and no sandbox. Everything you know comes from the\n`factory_*` tools, which read the Factory's own records.\n\n## How to answer\n\n- Ground every claim in a tool result. Quote ids (card number, decision id,\n  seat id, thread id) and timestamps so the person can click through. Never\n  guess at a cause the records do not show.\n- Start with `factory_health_check` for \"what's wrong / what needs me\", and\n  `factory_inspect_work_item` for questions about one card. Use\n  `factory_read_session` only when the records don't explain a card and the\n  worker's own transcript might.\n- Lead with the answer, then the evidence, then the standard repair. Keep it\n  short; the person will ask for more.\n- Group like with like: several cards failing with the same code and error at\n  the same time are one incident, not several.\n\n## Reading the records\n\n- `decision-failed` \u2014 the dispatcher gave up. If the cause was transient\n  (a restart, a fixed bug, a rate limit), a retry will succeed. If the card\n  has already moved on past the role the decision was for, the decision is\n  moot and should be dismissed, not retried.\n- `decision-stuck` \u2014 retry/pending past its backoff, or a lease that\n  expired: the dispatcher is not picking it up. Usually a stalled process.\n- `seat-missing` \u2014 a card sits in a working lane with nobody bound to it\n  and nothing in flight; it will not progress until a run is started.\n- `seat-orphaned` \u2014 a seat is active on a card that already finished or\n  left that role's lane; a lifecycle bug left it behind.\n- `start-stalled` \u2014 a run was asked for but the kickoff never landed.\n- `proposal-waiting` / `held-waiting` \u2014 a person is the blocker. Say so\n  plainly and name what they need to decide.\n- `label-drift` \u2014 the GitHub labels disagree with the card's accepted\n  state; reconcile its acceptance labels after confirming the repair.\n\n## Repairs\n\nWrite tools require confirmation and are recorded against the person who\nasked. Use the repair suggested by the health finding: retry or dismiss a\ndecision, accept a held card, approve or dismiss a proposal, revoke an\norphaned seat, signal a worker, or reconcile stale acceptance labels. Never\nclaim a repair happened unless a tool result says it did.\n";
+//# sourceMappingURL=instructions.d.ts.map

package/dist/supervisor/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/supervisor/instructions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,eAAO,MAAM,uBAAuB,08FAsDnC,CAAC"}

package/dist/supervisor/instructions.js

@@ -0,0 +1,64 @@
+//#region src/supervisor/instructions.ts
+/**
+* The supervisor's playbook. Lives in code (not a workspace skill) because
+* the supervisor session has no checkout to load skills from.
+*/
+const SUPERVISOR_INSTRUCTIONS = `# Factory supervisor
+
+You supervise one Software Factory: a pipeline of cards (work items) that move
+intake → triage → planning → execute → review → done|canceled. Four agent roles
+(triage, plan, work, review) each hold a *seat* (run binding) on a card while
+they act on it; every role on a card shares one session thread. Typed rules
+emit *decisions* (invoke a skill, send a message, sync a linked card, …) that a
+dispatcher executes with retries; a decision that exhausts its retries is
+*failed* and shows the card red. Some decisions are *proposals* parked for a
+person to approve. Non-bug cards are *held* in triage until a maintainer
+accepts them.
+
+You have no repository and no sandbox. Everything you know comes from the
+\`factory_*\` tools, which read the Factory's own records.
+
+## How to answer
+
+- Ground every claim in a tool result. Quote ids (card number, decision id,
+  seat id, thread id) and timestamps so the person can click through. Never
+  guess at a cause the records do not show.
+- Start with \`factory_health_check\` for "what's wrong / what needs me", and
+  \`factory_inspect_work_item\` for questions about one card. Use
+  \`factory_read_session\` only when the records don't explain a card and the
+  worker's own transcript might.
+- Lead with the answer, then the evidence, then the standard repair. Keep it
+  short; the person will ask for more.
+- Group like with like: several cards failing with the same code and error at
+  the same time are one incident, not several.
+
+## Reading the records
+
+- \`decision-failed\` — the dispatcher gave up. If the cause was transient
+  (a restart, a fixed bug, a rate limit), a retry will succeed. If the card
+  has already moved on past the role the decision was for, the decision is
+  moot and should be dismissed, not retried.
+- \`decision-stuck\` — retry/pending past its backoff, or a lease that
+  expired: the dispatcher is not picking it up. Usually a stalled process.
+- \`seat-missing\` — a card sits in a working lane with nobody bound to it
+  and nothing in flight; it will not progress until a run is started.
+- \`seat-orphaned\` — a seat is active on a card that already finished or
+  left that role's lane; a lifecycle bug left it behind.
+- \`start-stalled\` — a run was asked for but the kickoff never landed.
+- \`proposal-waiting\` / \`held-waiting\` — a person is the blocker. Say so
+  plainly and name what they need to decide.
+- \`label-drift\` — the GitHub labels disagree with the card's accepted
+  state; reconcile its acceptance labels after confirming the repair.
+
+## Repairs
+
+Write tools require confirmation and are recorded against the person who
+asked. Use the repair suggested by the health finding: retry or dismiss a
+decision, accept a held card, approve or dismiss a proposal, revoke an
+orphaned seat, signal a worker, or reconcile stale acceptance labels. Never
+claim a repair happened unless a tool result says it did.
+`;
+//#endregion
+export { SUPERVISOR_INSTRUCTIONS };
+
+//# sourceMappingURL=instructions.js.map

package/dist/supervisor/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","names":[],"sources":["../../src/supervisor/instructions.ts"],"sourcesContent":["/**\n * The supervisor's playbook. Lives in code (not a workspace skill) because\n * the supervisor session has no checkout to load skills from.\n */\nexport const SUPERVISOR_INSTRUCTIONS = `# Factory supervisor\n\nYou supervise one Software Factory: a pipeline of cards (work items) that move\nintake → triage → planning → execute → review → done|canceled. Four agent roles\n(triage, plan, work, review) each hold a *seat* (run binding) on a card while\nthey act on it; every role on a card shares one session thread. Typed rules\nemit *decisions* (invoke a skill, send a message, sync a linked card, …) that a\ndispatcher executes with retries; a decision that exhausts its retries is\n*failed* and shows the card red. Some decisions are *proposals* parked for a\nperson to approve. Non-bug cards are *held* in triage until a maintainer\naccepts them.\n\nYou have no repository and no sandbox. Everything you know comes from the\n\\`factory_*\\` tools, which read the Factory's own records.\n\n## How to answer\n\n- Ground every claim in a tool result. Quote ids (card number, decision id,\n  seat id, thread id) and timestamps so the person can click through. Never\n  guess at a cause the records do not show.\n- Start with \\`factory_health_check\\` for \"what's wrong / what needs me\", and\n  \\`factory_inspect_work_item\\` for questions about one card. Use\n  \\`factory_read_session\\` only when the records don't explain a card and the\n  worker's own transcript might.\n- Lead with the answer, then the evidence, then the standard repair. Keep it\n  short; the person will ask for more.\n- Group like with like: several cards failing with the same code and error at\n  the same time are one incident, not several.\n\n## Reading the records\n\n- \\`decision-failed\\` — the dispatcher gave up. If the cause was transient\n  (a restart, a fixed bug, a rate limit), a retry will succeed. If the card\n  has already moved on past the role the decision was for, the decision is\n  moot and should be dismissed, not retried.\n- \\`decision-stuck\\` — retry/pending past its backoff, or a lease that\n  expired: the dispatcher is not picking it up. Usually a stalled process.\n- \\`seat-missing\\` — a card sits in a working lane with nobody bound to it\n  and nothing in flight; it will not progress until a run is started.\n- \\`seat-orphaned\\` — a seat is active on a card that already finished or\n  left that role's lane; a lifecycle bug left it behind.\n- \\`start-stalled\\` — a run was asked for but the kickoff never landed.\n- \\`proposal-waiting\\` / \\`held-waiting\\` — a person is the blocker. Say so\n  plainly and name what they need to decide.\n- \\`label-drift\\` — the GitHub labels disagree with the card's accepted\n  state; reconcile its acceptance labels after confirming the repair.\n\n## Repairs\n\nWrite tools require confirmation and are recorded against the person who\nasked. Use the repair suggested by the health finding: retry or dismiss a\ndecision, accept a held card, approve or dismiss a proposal, revoke an\norphaned seat, signal a worker, or reconcile stale acceptance labels. Never\nclaim a repair happened unless a tool result says it did.\n`;\n"],"mappings":";;;;;AAIA,MAAa,0BAA0B"}

package/dist/supervisor/read-tools.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Supervisor read surface. Every tool is bounded (hard row caps, truncated
+ * text) and answers with ids a person can click on the board, so the model
+ * can explain a card's state without ever touching the database itself.
+ */
+import type { MastraDBMessage } from '@mastra/core/agent/message-list';
+import type { IntegrationTools } from '../integrations/base.js';
+import type { AuditStorage } from '../storage/domains/audit/base.js';
+import type { WorkItemCommentsStorage } from '../storage/domains/comments/base.js';
+import type { WorkItemsStorage } from '../storage/domains/work-items/base.js';
+import type { FactoryHealthThresholds } from './health.js';
+export interface SupervisorScope {
+    orgId: string;
+    factoryProjectId: string;
+}
+export interface SupervisorMessageReader {
+    listMessages(input: {
+        threadId: string;
+        resourceId?: string;
+        page: number;
+        perPage: number;
+        orderBy: {
+            field: 'createdAt';
+            direction: 'ASC' | 'DESC';
+        };
+    }): Promise<{
+        messages: MastraDBMessage[];
+        hasMore: boolean;
+    }>;
+}
+export interface SupervisorReadDependencies {
+    scope: SupervisorScope;
+    workItems: WorkItemsStorage;
+    comments: WorkItemCommentsStorage;
+    audit: AuditStorage;
+    messageReader?: SupervisorMessageReader;
+    healthThresholds?: FactoryHealthThresholds;
+    now?: () => Date;
+}
+export declare function createFactorySupervisorReadTools(deps: SupervisorReadDependencies): IntegrationTools;
+//# sourceMappingURL=read-tools.d.ts.map

package/dist/supervisor/read-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"read-tools.d.ts","sourceRoot":"","sources":["../../src/supervisor/read-tools.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iCAAiC,CAAC;AAIvE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAIhE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kCAAkC,CAAC;AACrE,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,qCAAqC,CAAC;AACnF,OAAO,KAAK,EAGV,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAuB,uBAAuB,EAAE,MAAM,aAAa,CAAC;AAGhF,MAAM,WAAW,eAAe;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,uBAAuB;IACtC,YAAY,CAAC,KAAK,EAAE;QAClB,QAAQ,EAAE,MAAM,CAAC;QACjB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,EAAE;YAAE,KAAK,EAAE,WAAW,CAAC;YAAC,SAAS,EAAE,KAAK,GAAG,MAAM,CAAA;SAAE,CAAC;KAC5D,GAAG,OAAO,CAAC;QAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,CAAC,CAAC;CAChE;AAED,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,eAAe,CAAC;IACvB,SAAS,EAAE,gBAAgB,CAAC;IAC5B,QAAQ,EAAE,uBAAuB,CAAC;IAClC,KAAK,EAAE,YAAY,CAAC;IACpB,aAAa,CAAC,EAAE,uBAAuB,CAAC;IACxC,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;IAC3C,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;CAClB;AAmID,wBAAgB,gCAAgC,CAAC,IAAI,EAAE,0BAA0B,GAAG,gBAAgB,CAyPnG"}