@mastra/factory 0.9.0 → 0.10.0-alpha.10

package/dist/rules/dispatch-errors.js

@@ -0,0 +1,77 @@
+//#region src/rules/dispatch-errors.ts
+const FAILURE_METADATA = {
+	session_unavailable: {
+		canRetry: true,
+		label: "Factory session unavailable"
+	},
+	source_control_missing: {
+		canRetry: true,
+		label: "Source-control connection unavailable"
+	},
+	source_repository_missing: {
+		canRetry: true,
+		label: "Source repository unavailable"
+	},
+	unsupported_provider_item: {
+		canRetry: false,
+		label: "Unsupported provider work item"
+	},
+	notification_delivery_failed: {
+		canRetry: true,
+		label: "Factory message delivery failed"
+	},
+	repository_git_missing: {
+		canRetry: false,
+		label: "Git is unavailable in the workspace"
+	},
+	repository_egress_blocked: {
+		canRetry: false,
+		label: "Repository network access is blocked"
+	},
+	repository_clone_failed: {
+		canRetry: true,
+		label: "Repository clone failed"
+	},
+	repository_pull_failed: {
+		canRetry: true,
+		label: "Repository update failed"
+	},
+	repository_push_failed: {
+		canRetry: true,
+		label: "Repository push failed"
+	},
+	repository_commit_failed: {
+		canRetry: true,
+		label: "Repository commit failed"
+	},
+	repository_cli_missing: {
+		canRetry: false,
+		label: "GitHub CLI is unavailable in the workspace"
+	},
+	repository_pr_failed: {
+		canRetry: true,
+		label: "Pull request creation failed"
+	},
+	unknown: {
+		canRetry: true,
+		label: "Factory automation failed"
+	}
+};
+var FactoryDispatchError = class extends Error {
+	code;
+	constructor(code, message, options) {
+		super(message, options);
+		this.code = code;
+		this.name = "FactoryDispatchError";
+	}
+};
+function factoryDispatchFailureCode(error) {
+	return error instanceof FactoryDispatchError ? error.code : "unknown";
+}
+function factoryDispatchFailureMetadata(code) {
+	return code === null ? FAILURE_METADATA.unknown : FAILURE_METADATA[code];
+}
+//#endregion
+export { FactoryDispatchError, factoryDispatchFailureCode, factoryDispatchFailureMetadata };
+
+//# sourceMappingURL=dispatch-errors.js.map

package/dist/rules/dispatch-errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dispatch-errors.js","names":[],"sources":["../../src/rules/dispatch-errors.ts"],"sourcesContent":["import type { FactoryDispatchFailureCode } from '../storage/domains/work-items/base.js';\n\ninterface FactoryDispatchFailureMetadata {\n  canRetry: boolean;\n  label: string;\n}\n\nconst FAILURE_METADATA = {\n  session_unavailable: { canRetry: true, label: 'Factory session unavailable' },\n  source_control_missing: { canRetry: true, label: 'Source-control connection unavailable' },\n  source_repository_missing: { canRetry: true, label: 'Source repository unavailable' },\n  unsupported_provider_item: { canRetry: false, label: 'Unsupported provider work item' },\n  notification_delivery_failed: { canRetry: true, label: 'Factory message delivery failed' },\n  repository_git_missing: { canRetry: false, label: 'Git is unavailable in the workspace' },\n  repository_egress_blocked: { canRetry: false, label: 'Repository network access is blocked' },\n  repository_clone_failed: { canRetry: true, label: 'Repository clone failed' },\n  repository_pull_failed: { canRetry: true, label: 'Repository update failed' },\n  repository_push_failed: { canRetry: true, label: 'Repository push failed' },\n  repository_commit_failed: { canRetry: true, label: 'Repository commit failed' },\n  repository_cli_missing: { canRetry: false, label: 'GitHub CLI is unavailable in the workspace' },\n  repository_pr_failed: { canRetry: true, label: 'Pull request creation failed' },\n  unknown: { canRetry: true, label: 'Factory automation failed' },\n} satisfies Record<FactoryDispatchFailureCode, FactoryDispatchFailureMetadata>;\n\nexport class FactoryDispatchError extends Error {\n  constructor(\n    readonly code: FactoryDispatchFailureCode,\n    message: string,\n    options?: ErrorOptions,\n  ) {\n    super(message, options);\n    this.name = 'FactoryDispatchError';\n  }\n}\n\nexport function factoryDispatchFailureCode(error: unknown): FactoryDispatchFailureCode {\n  return error instanceof FactoryDispatchError ? error.code : 'unknown';\n}\n\nexport function factoryDispatchFailureMetadata(\n  code: FactoryDispatchFailureCode | null,\n): FactoryDispatchFailureMetadata {\n  return code === null ? FAILURE_METADATA.unknown : FAILURE_METADATA[code];\n}\n"],"mappings":";AAOA,MAAM,mBAAmB;CACvB,qBAAqB;EAAE,UAAU;EAAM,OAAO;CAA8B;CAC5E,wBAAwB;EAAE,UAAU;EAAM,OAAO;CAAwC;CACzF,2BAA2B;EAAE,UAAU;EAAM,OAAO;CAAgC;CACpF,2BAA2B;EAAE,UAAU;EAAO,OAAO;CAAiC;CACtF,8BAA8B;EAAE,UAAU;EAAM,OAAO;CAAkC;CACzF,wBAAwB;EAAE,UAAU;EAAO,OAAO;CAAsC;CACxF,2BAA2B;EAAE,UAAU;EAAO,OAAO;CAAuC;CAC5F,yBAAyB;EAAE,UAAU;EAAM,OAAO;CAA0B;CAC5E,wBAAwB;EAAE,UAAU;EAAM,OAAO;CAA2B;CAC5E,wBAAwB;EAAE,UAAU;EAAM,OAAO;CAAyB;CAC1E,0BAA0B;EAAE,UAAU;EAAM,OAAO;CAA2B;CAC9E,wBAAwB;EAAE,UAAU;EAAO,OAAO;CAA6C;CAC/F,sBAAsB;EAAE,UAAU;EAAM,OAAO;CAA+B;CAC9E,SAAS;EAAE,UAAU;EAAM,OAAO;CAA4B;AAChE;AAEA,IAAa,uBAAb,cAA0C,MAAM;CAEnC;CADX,YACE,MACA,SACA,SACA;EACA,MAAM,SAAS,OAAO;EAJb,KAAA,OAAA;EAKT,KAAK,OAAO;CACd;AACF;AAEA,SAAgB,2BAA2B,OAA4C;CACrF,OAAO,iBAAiB,uBAAuB,MAAM,OAAO;AAC9D;AAEA,SAAgB,+BACd,MACgC;CAChC,OAAO,SAAS,OAAO,iBAAiB,UAAU,iBAAiB;AACrE"}

package/dist/rules/dispatcher.d.ts

@@ -2,6 +2,7 @@ import type { MastraCodeState } from '@mastra/code-sdk/schema';
 import type { AgentController } from '@mastra/core/agent-controller';
 import type { FactoryDeferredDecisionRecord, WorkItemRow, WorkItemsStorage } from '../storage/domains/work-items/base.js';
 import type { FactoryTransitionService } from './transition-service.js';
+import type { FactoryCommitDecision } from './types.js';
 type FactoryController = Pick<AgentController<MastraCodeState>, 'getSessionByResource'>;
 export interface FactoryBindingPreparationInput {
     record: FactoryDeferredDecisionRecord;
@@ -24,6 +25,12 @@ export interface FactoryDecisionDispatcherOptions {
         orgId: string;
         userId: string;
     }) => Promise<void>;
+    resolveLinkedWorkItemParentId?: (input: {
+        orgId: string;
+        decision: Extract<FactoryCommitDecision, {
+            type: 'upsertLinkedWorkItem';
+        }>;
+    }) => Promise<string | null>;
     maxInFlight?: number;
     /** How often the stale-binding sweep runs. Defaults to 10 minutes. */
     staleBindingSweepIntervalMs?: number;
@@ -31,6 +38,8 @@ export interface FactoryDecisionDispatcherOptions {
     staleBindingTtlMs?: number;
     /** How often the bound-thread reconcile walk runs. Defaults to 30 seconds. */
     reconcileIntervalMs?: number;
+    /** How long to wait for a run's terminal event before failing for retry. Defaults to 10 minutes. */
+    skillCompletionObservationTimeoutMs?: number;
 }
 export declare class FactoryDecisionDispatcher {
     #private;

package/dist/rules/dispatcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/rules/dispatcher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAgC,MAAM,+BAA+B,CAAC;AAKnG,OAAO,KAAK,EACV,6BAA6B,EAG7B,WAAW,EACX,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAE/C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AAkDxE,KAAK,iBAAiB,GAAG,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,sBAAsB,CAAC,CAAC;AAExF,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,6BAA6B,CAAC;IACtC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gCAAgC;IAC/C,UAAU,EAAE,iBAAiB,CAAC;IAC9B,iBAAiB,EAAE,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,CAAC;IAChE,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,gBAAgB,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5F,oBAAoB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,sFAAsF;IACtF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,MAAM,CAAC;CAC9B;AA0ED,qBAAa,yBAAyB;;gBAoBxB,OAAO,EAAE,gCAAgC;IAmBrD,KAAK,IAAI,IAAI;IAOP,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAOrB,OAAO,CAAC,GAAG,OAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAwnB/C;AAED,eAAO,MAAM,0BAA0B;;;;;;;;;;CAU7B,CAAC"}
+{"version":3,"file":"dispatcher.d.ts","sourceRoot":"","sources":["../../src/rules/dispatcher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAyC,MAAM,+BAA+B,CAAC;AAK5G,OAAO,KAAK,EACV,6BAA6B,EAG7B,WAAW,EACX,gBAAgB,EACjB,MAAM,uCAAuC,CAAC;AAG/C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,KAAK,EAAE,qBAAqB,EAA4C,MAAM,YAAY,CAAC;AA+DlG,KAAK,iBAAiB,GAAG,IAAI,CAAC,eAAe,CAAC,eAAe,CAAC,EAAE,sBAAsB,CAAC,CAAC;AAGxF,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,6BAA6B,CAAC;IACtC,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gCAAgC;IAC/C,UAAU,EAAE,iBAAiB,CAAC;IAC9B,iBAAiB,EAAE,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,CAAC;IAChE,OAAO,EAAE,gBAAgB,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,gBAAgB,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,gBAAgB,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5F,oBAAoB,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3C,cAAc,CAAC,EAAE,CAAC,KAAK,EAAE,8BAA8B,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1E,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAChF,6BAA6B,CAAC,EAAE,CAAC,KAAK,EAAE;QACtC,KAAK,EAAE,MAAM,CAAC;QACd,QAAQ,EAAE,OAAO,CAAC,qBAAqB,EAAE;YAAE,IAAI,EAAE,sBAAsB,CAAA;SAAE,CAAC,CAAC;KAC5E,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC7B,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sEAAsE;IACtE,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,sFAAsF;IACtF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8EAA8E;IAC9E,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,oGAAoG;IACpG,mCAAmC,CAAC,EAAE,MAAM,CAAC;CAC9C;AA+FD,qBAAa,yBAAyB;;gBAsBxB,OAAO,EAAE,gCAAgC;IAwBrD,KAAK,IAAI,IAAI;IAOP,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAOrB,OAAO,CAAC,GAAG,OAAa,GAAG,OAAO,CAAC,IAAI,CAAC;CAmuB/C;AAED,eAAO,MAAM,0BAA0B;;;;;;;;;;CAU7B,CAAC"}

package/dist/rules/dispatcher.js

@@ -1,7 +1,8 @@
 import { FACTORY_RULE_STAGES } from "./types.js";
 import { validateFactoryRuleDecision } from "./validation.js";
-import { resolvePromptInvocation, resolveSkillInvocation } from "../skills/service.js";
 import { FACTORY_RULE_MATERIALIZATION_KEY } from "../storage/domains/work-items/base.js";
+import { FactoryDispatchError, factoryDispatchFailureCode } from "./dispatch-errors.js";
+import { resolvePromptInvocation, resolveSkillInvocation } from "../skills/service.js";
 import { randomUUID } from "crypto";
 import { RequestContext } from "@mastra/core/request-context";
 //#region src/rules/dispatcher.ts
@@ -16,9 +17,9 @@ const MAX_IN_FLIGHT = 25;
 const STALE_BINDING_SWEEP_INTERVAL_MS = 10 * 6e4;
 const STALE_BINDING_TTL_MS = 1440 * 6e4;
 const RECONCILE_INTERVAL_MS = 3e4;
-function waitForAgentEndOrTimeout(agentEnd) {
+function waitForAgentEndOrTimeout(agentEnd, timeoutMs) {
 	return new Promise((resolve) => {
-		const timeout = setTimeout(() => resolve(false), SKILL_COMPLETION_OBSERVATION_TIMEOUT_MS);
+		const timeout = setTimeout(() => resolve(false), timeoutMs);
 		timeout.unref?.();
 		agentEnd.then(() => {
 			clearTimeout(timeout);
@@ -65,19 +66,26 @@ function leaseIdentity(record, ownerId) {
 		ownerId
 	};
 }
-async function awaitNotification(result, requireDelivery = false) {
-	await result.persisted;
-	if (!result.accepted) {
-		if (requireDelivery) throw new Error("Factory notification was persisted without agent delivery.");
-		return;
-	}
-	const accepted = await result.accepted;
-	if (!requireDelivery) return;
-	if (accepted.action === "wake") {
-		await accepted.output.consumeStream();
-		return;
+async function awaitNotification(send, requireDelivery = false) {
+	try {
+		const notification = await send();
+		const [, accepted] = await Promise.all([notification.persisted, notification.accepted]);
+		if (!accepted) {
+			if (requireDelivery) throw new FactoryDispatchError("notification_delivery_failed", "Factory notification was persisted without agent delivery.");
+			return;
+		}
+		if (!requireDelivery) return accepted;
+		if (accepted.action === "wake") {
+			if (!accepted.output) throw new FactoryDispatchError("notification_delivery_failed", "Factory notification wake had no output.");
+			await accepted.output.consumeStream();
+			return accepted;
+		}
+		if (accepted.action !== "deliver") throw new FactoryDispatchError("notification_delivery_failed", `Factory notification did not reach the agent (${String(accepted.action)}).`);
+		return accepted;
+	} catch (error) {
+		if (error instanceof FactoryDispatchError) throw error;
+		throw new FactoryDispatchError("notification_delivery_failed", `Factory notification delivery failed: ${sanitizeDispatchError(error)}`, { cause: error });
 	}
-	if (accepted.action !== "deliver") throw new Error(`Factory notification did not reach the agent (${String(accepted.action)}).`);
 }
 var FactoryDecisionDispatcher = class {
 	#controller;
@@ -88,11 +96,13 @@ var FactoryDecisionDispatcher = class {
 	#reconcileToolResults;
 	#prepareBinding;
 	#primeCredentials;
+	#resolveLinkedWorkItemParentId;
 	#maxInFlight;
 	#staleBindingSweepIntervalMs;
 	#staleBindingTtlMs;
 	#lastStaleBindingSweepAt;
 	#reconcileIntervalMs;
+	#skillCompletionObservationTimeoutMs;
 	#lastReconcileAt;
 	#reconcileInFlight;
 	#timer;
@@ -107,11 +117,13 @@ var FactoryDecisionDispatcher = class {
 		this.#reconcileToolResults = options.reconcileToolResults;
 		this.#prepareBinding = options.prepareBinding;
 		this.#primeCredentials = options.primeCredentials;
+		this.#resolveLinkedWorkItemParentId = options.resolveLinkedWorkItemParentId;
 		const maxInFlight = options.maxInFlight ?? MAX_IN_FLIGHT;
 		this.#maxInFlight = Number.isFinite(maxInFlight) && maxInFlight > 0 ? Math.floor(maxInFlight) : MAX_IN_FLIGHT;
 		this.#staleBindingSweepIntervalMs = positiveMs(options.staleBindingSweepIntervalMs, STALE_BINDING_SWEEP_INTERVAL_MS);
 		this.#staleBindingTtlMs = positiveMs(options.staleBindingTtlMs, STALE_BINDING_TTL_MS);
 		this.#reconcileIntervalMs = positiveMs(options.reconcileIntervalMs, RECONCILE_INTERVAL_MS);
+		this.#skillCompletionObservationTimeoutMs = positiveMs(options.skillCompletionObservationTimeoutMs, SKILL_COMPLETION_OBSERVATION_TIMEOUT_MS);
 	}
 	start() {
 		if (this.#timer) return;
@@ -213,6 +225,7 @@ var FactoryDecisionDispatcher = class {
 		}
 	}
 	async #dispatchDecision(record, now) {
+		let executionCompleted = false;
 		try {
 			const decision = validateFactoryRuleDecision(record.decision, record.causalChain.length);
 			if (decision.type === "reject") throw new Error("Deferred Factory decisions cannot reject.");
@@ -222,6 +235,7 @@ var FactoryDecisionDispatcher = class {
 			}
 			await this.#supersedeProposals(record, decision);
 			await this.#withLease(async (leaseExpiresAt) => this.#storage.renewDeferredDecisionLease(leaseIdentity(record, this.#ownerId), leaseExpiresAt), async () => this.#executeDecision(record, decision));
+			executionCompleted = true;
 			if (!await this.#storage.completeDeferredDecision(leaseIdentity(record, this.#ownerId), /* @__PURE__ */ new Date())) throw new Error("Factory decision lease was lost before completion.");
 		} catch (error) {
 			const terminal = record.attempts >= MAX_ATTEMPTS;
@@ -230,7 +244,9 @@ var FactoryDecisionDispatcher = class {
 				now: /* @__PURE__ */ new Date(),
 				availableAt: retryAt(now, record.attempts),
 				lastError: sanitizeDispatchError(error),
-				terminal
+				failureCode: factoryDispatchFailureCode(error),
+				terminal,
+				advanceDeliveryGeneration: !executionCompleted
 			});
 		}
 	}
@@ -244,12 +260,12 @@ var FactoryDecisionDispatcher = class {
 	async #supersedeProposals(record, decision) {
 		if (decision.type !== "invokeSkill" || !record.workItemId) return;
 		try {
-			await this.#storage.dismissProposalsForWorkItem({
+			await this.#storage.supersedeDecisionsForWorkItem({
 				orgId: record.orgId,
 				factoryProjectId: record.factoryProjectId,
 				workItemId: record.workItemId,
 				role: decision.role,
-				dismissedAt: /* @__PURE__ */ new Date()
+				supersededAt: /* @__PURE__ */ new Date()
 			});
 		} catch (error) {
 			console.error("Factory proposal supersede failed", sanitizeDispatchError(error));
@@ -296,8 +312,9 @@ var FactoryDecisionDispatcher = class {
 					...decision.reenter ? { reenter: true } : {}
 				});
 				if (result.status === "rejected") throw new Error(`${result.code}: ${result.reason}`);
-				if (!decision.message) return;
-				const binding = await this.#findBinding(record, decision.message.role);
+				const transitionMessage = decision.message;
+				if (!transitionMessage) return;
+				const binding = await this.#findBinding(record, transitionMessage.role);
 				if (!binding) return;
 				const startedBy = item.sessions[binding.role]?.startedBy;
 				if (!startedBy) return;
@@ -310,12 +327,14 @@ var FactoryDecisionDispatcher = class {
 					workosId: startedBy,
 					organizationId: record.orgId
 				});
-				await awaitNotification(await (await this.#requireSession(binding)).sendNotificationSignal({
+				const session = await this.#findSession(binding);
+				if (!session) return;
+				await awaitNotification(() => session.sendNotificationSignal({
 					source: "factory",
 					kind: "rule-message",
-					summary: decision.message.text,
+					summary: transitionMessage.text,
 					priority: "high",
-					payload: { message: decision.message.text },
+					payload: { message: transitionMessage.text },
 					sourceId: record.id,
 					dedupeKey: record.idempotencyKey
 				}, {
@@ -354,14 +373,16 @@ var FactoryDecisionDispatcher = class {
 				});
 				const session = resolved.session;
 				await this.#switchThread(session, binding);
-				if ((await session.thread.listActiveMessages()).some((message) => message.id === record.id)) return;
+				const deliveryId = record.deliveryGeneration === 0 ? record.id : `${record.id}:retry:${record.deliveryGeneration}`;
+				if ((await session.thread.listActiveMessages()).some((message) => message.id === deliveryId)) return;
 				if (decision.cancelInFlight) session.abort();
-				if (decision.precedingMessage) await awaitNotification(await session.sendNotificationSignal({
+				const precedingMessage = decision.precedingMessage;
+				if (precedingMessage) await awaitNotification(() => session.sendNotificationSignal({
 					source: "factory",
 					kind: "stage-transition",
-					summary: decision.precedingMessage,
+					summary: precedingMessage,
 					priority: "medium",
-					payload: { message: decision.precedingMessage },
+					payload: { message: precedingMessage },
 					sourceId: `${record.id}:stage-transition`,
 					dedupeKey: `${record.idempotencyKey}:stage-transition`
 				}, {
@@ -387,7 +408,7 @@ var FactoryDecisionDispatcher = class {
 				});
 				const sendKickoff = async () => {
 					const settled = await session.sendSignal({
-						id: record.id,
+						id: deliveryId,
 						type: "user",
 						tagName: "user",
 						contents: resolved.message
@@ -401,17 +422,14 @@ var FactoryDecisionDispatcher = class {
 				try {
 					let settled = await sendKickoff();
 					if (settled.action === "deliver") {
-						if (!(await session.thread.listActiveMessages()).some((message) => message.id === record.id)) {
-							if (!await waitForAgentEndOrTimeout(agentEnd)) throw new Error("Factory skill invocation is waiting on a run that has not ended.");
+						if (!(await session.thread.listActiveMessages()).some((message) => message.id === deliveryId)) {
+							if (!await waitForAgentEndOrTimeout(agentEnd, this.#skillCompletionObservationTimeoutMs)) throw new Error("Factory skill invocation is waiting on a run that has not ended.");
 							armAgentEnd();
 							settled = await sendKickoff();
 							if (settled.action !== "wake") throw new Error("Factory skill invocation was queued onto an ending run and never reached the agent.");
 						}
 					}
-					if (!await waitForAgentEndOrTimeout(agentEnd)) console.warn("Factory skill run terminal event was not observed before timeout", {
-						decisionId: record.id,
-						runId: settled.action === "wake" ? settled.runId : void 0
-					});
+					if (!await waitForAgentEndOrTimeout(agentEnd, this.#skillCompletionObservationTimeoutMs)) throw new Error("Factory skill run terminal event was not observed before timeout.");
 					else if (endReason === "error") throw new Error("Factory skill run ended in error.");
 					else if (endReason === "aborted") throw new Error("Factory skill run was aborted before it finished.");
 				} finally {
@@ -435,7 +453,8 @@ var FactoryDecisionDispatcher = class {
 					workosId: startedBy,
 					organizationId: record.orgId
 				});
-				await awaitNotification(await (await this.#requireSession(binding)).sendNotificationSignal({
+				const session = await this.#requireSession(binding);
+				await awaitNotification(() => session.sendNotificationSignal({
 					source: "factory",
 					kind: "rule-message",
 					summary: decision.message,
@@ -452,7 +471,8 @@ var FactoryDecisionDispatcher = class {
 			}
 			case "notify": {
 				const binding = await this.#requireBinding(record);
-				await awaitNotification(await (await this.#requireSession(binding)).sendNotificationSignal({
+				const session = await this.#requireSession(binding);
+				await awaitNotification(() => session.sendNotificationSignal({
 					source: "factory",
 					kind: "rule-notification",
 					summary: decision.title,
@@ -467,13 +487,17 @@ var FactoryDecisionDispatcher = class {
 		}
 	}
 	async #upsertLinkedItem(record, decision, causalChain) {
-		const result = await this.#storage.upsert({
+		const parentWorkItemId = record.workItemId ?? await this.#resolveLinkedWorkItemParentId?.({
+			orgId: record.orgId,
+			decision
+		}) ?? null;
+		let result = await this.#storage.upsert({
 			orgId: record.orgId,
 			userId: "factory-rule-dispatcher",
 			factoryProjectId: record.factoryProjectId,
 			input: {
 				externalSource: externalSourceForDecision(decision),
-				parentWorkItemId: record.workItemId,
+				parentWorkItemId,
 				title: decision.title,
 				stages: ["intake"],
 				sessions: {},
@@ -484,6 +508,18 @@ var FactoryDecisionDispatcher = class {
 			},
 			reuseMode: "preserve"
 		});
+		if (!result.item.parentWorkItemId && parentWorkItemId) {
+			const item = await this.#storage.setParentWorkItemIfMissing({
+				orgId: record.orgId,
+				id: result.item.id,
+				userId: "factory-rule-dispatcher",
+				parentWorkItemId
+			});
+			if (item) result = {
+				...result,
+				item
+			};
+		}
 		const materializedByDecision = result.item.metadata?.[FACTORY_RULE_MATERIALIZATION_KEY] === record.idempotencyKey;
 		if (!materializedByDecision && (decision.stage === "intake" || !result.item.stages.includes("intake"))) return;
 		const board = decision.board;
@@ -554,7 +590,7 @@ var FactoryDecisionDispatcher = class {
 	}
 	async #requireBinding(record, role) {
 		const binding = await this.#findBinding(record, role);
-		if (!binding) throw new Error(role ? `No active Factory binding for role ${role}.` : "No active Factory binding.");
+		if (!binding) throw new FactoryDispatchError("session_unavailable", role ? `No active Factory binding for role ${role}.` : "No active Factory binding.");
 		return binding;
 	}
 	async #requireOrPrepareBinding(record, role) {
@@ -562,7 +598,7 @@ var FactoryDecisionDispatcher = class {
 		if (binding) {
 			if (await this.#controller.getSessionByResource(binding.resourceId)) return binding;
 		}
-		if (!this.#prepareBinding) throw new Error(binding ? "Bound Factory session not found." : `No active Factory binding for role ${role}.`);
+		if (!this.#prepareBinding) throw new FactoryDispatchError("session_unavailable", binding ? "Bound Factory session not found." : `No active Factory binding for role ${role}.`);
 		const item = await this.#requireItem(record);
 		await this.#prepareBinding({
 			record,
@@ -571,12 +607,17 @@ var FactoryDecisionDispatcher = class {
 		});
 		return this.#requireBinding(record, role);
 	}
-	async #requireSession(binding) {
+	async #findSession(binding) {
 		const session = await this.#controller.getSessionByResource(binding.resourceId);
-		if (!session) throw new Error("Bound Factory session not found.");
+		if (!session) return void 0;
 		await this.#switchThread(session, binding);
 		return session;
 	}
+	async #requireSession(binding) {
+		const session = await this.#findSession(binding);
+		if (!session) throw new FactoryDispatchError("session_unavailable", "Bound Factory session not found.");
+		return session;
+	}
 	async #switchThread(session, binding) {
 		await session.thread.switch({ threadId: binding.threadId });
 	}
@@ -607,7 +648,7 @@ var FactoryDecisionDispatcher = class {
 			await this.#withLease(async (leaseExpiresAt) => this.#storage.renewPendingStartLease(leaseIdentity(record, this.#ownerId), leaseExpiresAt), async () => {
 				if (record.message === null) return;
 				const binding = (await this.#storage.listRunBindings(record.orgId, record.factoryProjectId)).find((candidate) => candidate.id === record.bindingId && candidate.status === "active");
-				if (!binding) throw new Error("Prepared Factory binding is unavailable or revoked.");
+				if (!binding) throw new FactoryDispatchError("session_unavailable", "Prepared Factory binding is unavailable or revoked.");
 				const startedBy = (await this.#storage.get({
 					orgId: record.orgId,
 					id: binding.workItemId
@@ -622,19 +663,50 @@ var FactoryDecisionDispatcher = class {
 					workosId: startedBy,
 					organizationId: record.orgId
 				});
-				await awaitNotification(await (await this.#requireSession(binding)).sendNotificationSignal({
+				const session = await this.#requireSession(binding);
+				let resolveAgentEnd;
+				let agentEnd;
+				let endReason;
+				const armAgentEnd = () => {
+					endReason = void 0;
+					agentEnd = new Promise((resolve) => {
+						resolveAgentEnd = resolve;
+					});
+				};
+				armAgentEnd();
+				const unsubscribe = session.subscribe((event) => {
+					if (event.type === "agent_end") {
+						endReason = event.reason;
+						resolveAgentEnd();
+					}
+				});
+				const sendKickoff = (dedupeKey) => awaitNotification(() => session.sendNotificationSignal({
 					source: "factory",
 					kind: "run-kickoff",
 					summary: record.message,
 					priority: "high",
 					payload: { message: record.message },
 					sourceId: record.id,
-					dedupeKey: `factory-kickoff:${record.kickoffKey}`
+					dedupeKey
 				}, {
 					ifActive: { behavior: "deliver" },
 					ifIdle: { behavior: "wake" },
 					requestContext
 				}), true);
+				try {
+					let settled = await sendKickoff(`factory-kickoff:${record.kickoffKey}`);
+					if (settled?.action === "deliver") {
+						if (!await waitForAgentEndOrTimeout(agentEnd, this.#skillCompletionObservationTimeoutMs)) throw new Error("Factory kickoff is waiting on a run that has not ended.");
+						armAgentEnd();
+						settled = await sendKickoff(`factory-kickoff:${record.kickoffKey}:retry:${record.attempts}`);
+						if (settled?.action !== "wake") throw new Error("Factory kickoff was queued onto an ending run and never reached the agent.");
+					}
+					if (!await waitForAgentEndOrTimeout(agentEnd, this.#skillCompletionObservationTimeoutMs)) throw new Error("Factory kickoff run terminal event was not observed before timeout.");
+					else if (endReason === "error") throw new Error("Factory kickoff run ended in error.");
+					else if (endReason === "aborted") throw new Error("Factory kickoff run was aborted before it finished.");
+				} finally {
+					unsubscribe();
+				}
 			});
 			if (!await this.#storage.completePendingStart(leaseIdentity(record, this.#ownerId), /* @__PURE__ */ new Date())) throw new Error("Factory kickoff lease was lost before completion.");
 		} catch (error) {
@@ -643,6 +715,7 @@ var FactoryDecisionDispatcher = class {
 				now: /* @__PURE__ */ new Date(),
 				availableAt: retryAt(now, record.attempts),
 				lastError: sanitizeDispatchError(error),
+				failureCode: factoryDispatchFailureCode(error),
 				terminal: record.attempts >= MAX_ATTEMPTS
 			});
 		}