@vercel/factory 0.0.11 → 0.0.13

package/dist/index.mjs

@@ -1,10 +1,44 @@
 import { a as repositoryIdsSchema, c as SCHEMA_VERSION, d as schemaVersionSchema, f as usdSchema, i as repositoryIdSchema, l as isoDateTimeSchema, n as factoryIdSchema, o as signalIdSchema, p as vocabularySchema, r as receiptIdSchema, s as taskIdSchema, t as changeIdSchema, u as replyToSchema } from "./id-DwCihQr4.mjs";
-import { a as findingCategorySchema, c as findingSchema, d as findingVerificationSchema, i as requiresApproval, l as findingVerificationLevelSchema, n as approvalRuleSchema, o as findingFingerprint, r as defaultApprovalPolicy, s as findingPrioritySchema, t as approvalPolicySchema, u as findingVerificationMethodSchema } from "./approval-DdvEKLiE.mjs";
+import { C as taskUsageSchema, S as taskStateSchema, _ as taskExecutionRepositoryIdsSchema, a as findingCategorySchema, b as taskQuestionSchema, c as findingSchema, d as findingVerificationSchema, f as coordinationRepositoryIdsSchema, g as taskApprovalSchema, h as standardTaskKinds, i as requiresApproval, l as findingVerificationLevelSchema, m as harnessSchema, n as approvalRuleSchema, o as findingFingerprint, p as executionReferenceSchema, r as defaultApprovalPolicy, s as findingPrioritySchema, t as approvalPolicySchema, u as findingVerificationMethodSchema, v as taskKindSchema, x as taskSchema, y as taskOriginSchema } from "./approval-CwhTP1XB.mjs";
+import { C as budgetStatus, D as sweepBudget, E as deriveFactoryId, O as sweepSettlements, S as budgetMonthOf, T as computeMonthSpendUsd, _ as taskInitialState, a as BudgetExhaustedError, b as createCoordination, c as dispatchTask, d as changeInitialState, f as changeTransitions, g as signalOutcomeTransitions, h as signalInitialOutcome, i as levelSchema, l as InvalidTransitionError, m as legalNextStates, n as changeSchema, o as DEFAULT_MAX_LAUNCH_ATTEMPTS, p as isTransitionAllowed, r as changeStateSchema, s as DispatchRefusedError, t as changeEvidenceSchema, u as assertTransition, v as taskTransitions, w as canReserve, x as reconcileCoordination, y as terminalStates } from "./change-CzEAoFVE.mjs";
 import { n as RecordNotFoundError, r as VersionConflictError, t as RecordExistsError } from "./driver-Bbd25rNM.mjs";
-import { _ as taskSchema, a as DEFAULT_MAX_LAUNCH_ATTEMPTS, c as coordinationRepositoryIdsSchema, d as taskApprovalSchema, f as taskDevboxSchema, g as taskQuestionSchema, h as taskOriginSchema, i as levelSchema, l as harnessSchema, m as taskKindSchema, n as changeSchema, o as DispatchRefusedError, p as taskExecutionRepositoryIdsSchema, r as changeStateSchema, s as dispatchTask, t as changeEvidenceSchema, u as standardTaskKinds, v as taskStateSchema } from "./change-BPYhWKuL.mjs";
-import { a as repositorySlugSchema, i as repositorySchema, n as factoryConfigRepositorySchema, r as factoryConfigSchema, t as defineFactory } from "./factory-config-ifd3JxiU.mjs";
+import { a as factoryConfigSchema, c as budgetSchema, i as factoryConfigRepositorySchema, l as repositorySchema, n as defineFactory, o as budgetLimitsSchema, r as executionPolicySchema, s as budgetMonthSchema, t as defaultExecutionPolicy, u as repositorySlugSchema } from "./factory-config-BJcjsPKl.mjs";
 import { z } from "zod";
 import { createHash, randomUUID } from "node:crypto";
+//#region src/agent-routes.ts
+const agentRouteSchema = z.strictObject({
+	id: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/u).describe("Stable route selected by a conversational agent or workflow."),
+	agent: z.string().regex(/^[a-z][a-z0-9-]{0,31}$/u).describe("Internally addressable Eve agent that executes this route."),
+	taskKind: taskKindSchema.describe("Factory task kind created for this route."),
+	description: z.string().min(1).max(500).describe("Model-facing guidance for when this route is appropriate."),
+	permissions: z.array(z.string().min(1)).default([]).describe("Inspectable capabilities granted to the target agent.")
+});
+/**
+* Define the application-owned routes an agent or workflow may select. Route
+* descriptions inform judgment; this validated registry remains the authority.
+*/
+function defineAgentRoutes(inputs) {
+	const routes = inputs.map((input) => agentRouteSchema.parse(input));
+	const byId = /* @__PURE__ */ new Map();
+	const byTaskKind = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		if (byId.has(route.id)) throw new Error(`Agent route ${route.id} is registered more than once.`);
+		if (byTaskKind.has(route.taskKind)) throw new Error(`Task kind ${route.taskKind} is handled by more than one agent route.`);
+		byId.set(route.id, route);
+		byTaskKind.set(route.taskKind, route);
+	}
+	const frozen = Object.freeze(routes.map((route) => Object.freeze(route)));
+	return Object.freeze({
+		routes: frozen,
+		get(id) {
+			return byId.get(id);
+		},
+		forTaskKind(kind) {
+			return byTaskKind.get(kind);
+		}
+	});
+}
+//#endregion
 //#region src/briefs.ts
 /** The finding behind a task, when its signal carries one. */
 async function findingForTask(stores, task) {
@@ -37,6 +71,14 @@ function scanBrief(task, repository) {
 		"You never fix anything. When you are done, summarize what deepsec found and what you added, by priority, and what you could not scan."
 	].join("\n");
 }
+/** The verifier's starting message for a recorded pull request. */
+function verificationBrief(task, repository, change) {
+	return [
+		`You are assigned factory verification task ${task.id} in repository ${repository.slug}.`,
+		`Change under review: ${change.id} (${change.prUrl}).`,
+		"Read the task with get_task, independently inspect and test the change, then call record_verification with every evidence field."
+	].join("\n");
+}
 //#endregion
 //#region src/changes.ts
 async function adoptPullRequest(stores, input) {
@@ -56,76 +98,6 @@ async function adoptPullRequest(stores, input) {
 	});
 }
 //#endregion
-//#region src/coordination.ts
-/** Create one non-executable parent and one independently executable child per repository. */
-async function createCoordination(stores, input) {
-	const repositoryIds = [...new Set(input.repositoryIds)];
-	if (repositoryIds.length < 2) throw new Error("coordination requires at least two distinct repositories");
-	const parent = await stores.tasks.create({
-		repositoryIds,
-		kind: "coordination",
-		origin: { signalId: input.signalId },
-		replyTo: input.replyTo
-	});
-	return {
-		parent: await stores.tasks.transition(parent.id, "running", { reason: "repository-scoped child tasks created" }),
-		children: await Promise.all(repositoryIds.map((repositoryId) => stores.tasks.create({
-			repositoryIds: [repositoryId],
-			kind: "code_change",
-			origin: { parentTaskId: parent.id },
-			replyTo: input.replyTo
-		})))
-	};
-}
-/** Reconcile a coordination parent from its direct children without ever dispatching the parent. */
-async function reconcileCoordination(stores, parentTaskId, options) {
-	const parent = await stores.tasks.get(parentTaskId);
-	if (parent === null) throw new RecordNotFoundError("tasks", parentTaskId);
-	if (parent.kind !== "coordination") throw new Error(`task ${parentTaskId} is ${parent.kind}, not coordination`);
-	const children = (await stores.tasks.list()).filter((task) => task.origin.parentTaskId === parentTaskId);
-	if (children.length !== parent.repositoryIds.length) return {
-		status: "pending",
-		parent,
-		children
-	};
-	if (parent.state === "succeeded" || parent.state === "failed") return {
-		status: parent.state,
-		transitioned: false,
-		parent,
-		children
-	};
-	if (children.some((child) => child.state === "failed" || child.state === "cancelled")) {
-		await options.present({
-			status: "failed",
-			parent,
-			children
-		});
-		return {
-			status: "failed",
-			transitioned: true,
-			parent: await stores.tasks.transition(parent.id, "failed", { reason: "one or more repository tasks failed" }),
-			children
-		};
-	}
-	if (!children.every((child) => child.state === "succeeded")) return {
-		status: "pending",
-		parent,
-		children
-	};
-	await options.present({
-		status: "succeeded",
-		parent,
-		children
-	});
-	await stores.tasks.transition(parent.id, "verifying", { reason: "all repository tasks succeeded" });
-	return {
-		status: "succeeded",
-		transitioned: true,
-		parent: await stores.tasks.transition(parent.id, "succeeded", { reason: "aggregate multi-repository handoff is ready" }),
-		children
-	};
-}
-//#endregion
 //#region src/metrics.ts
 const bucketTable = {
 	low: {
@@ -250,9 +222,10 @@ function computeLedgerMetrics(rows, options = {}) {
 }
 const openChangeStates = /* @__PURE__ */ new Set(["verifying", "ready"]);
 /**
-* Green, yellow, or red from rows, never from a model. Budget and onboarding
-* signals are not evaluated yet: budgets do not settle and onboarding
-* investigations are not recorded, so those spec rules have no rows to read.
+* Green, yellow, or red from rows, never from a model. Budget threshold and
+* onboarding rules are not evaluated here yet: budget notices live on the
+* budgets collection (not in these rows), and onboarding investigations are
+* not recorded.
 */
 function computeRepositoryHealth(rows, options = {}) {
 	const now = (options.now ?? /* @__PURE__ */ new Date()).getTime();
@@ -288,31 +261,13 @@ function computeRepositoryHealth(rows, options = {}) {
 	};
 }
 //#endregion
-//#region src/schema/budget.ts
-const budgetMonthSchema = z.string().regex(/^\d{4}-(0[1-9]|1[0-2])$/);
-const budgetSchema = z.strictObject({
-	schemaVersion: schemaVersionSchema,
-	factoryId: factoryIdSchema,
-	month: budgetMonthSchema,
-	limits: z.strictObject({
-		totalUsd: usdSchema,
-		investigationUsd: usdSchema,
-		perTaskReservationUsd: usdSchema,
-		warningPercent: z.number().int().min(1).max(100),
-		perRepositoryUsd: z.record(repositorySlugSchema, usdSchema).optional()
-	}),
-	notices: z.strictObject({
-		warningAt: isoDateTimeSchema.optional(),
-		exhaustedAt: isoDateTimeSchema.optional()
-	})
-});
-//#endregion
 //#region src/schema/receipt.ts
 /** States the engine writes on transitions. Any vocabulary value is valid. */
 const standardReceiptStates = [
 	"approved",
 	"rejected",
 	"dispatched",
+	"stalled",
 	"succeeded",
 	"failed",
 	"needs_human",
@@ -421,232 +376,6 @@ const signalSchema = z.strictObject({
 	});
 });
 //#endregion
-//#region src/schema/transitions.ts
-const taskInitialState = "queued";
-const taskTransitions = [
-	{
-		from: "queued",
-		to: "running",
-		trigger: "dependencies have a change, reservation succeeded, devbox created",
-		actor: "reconciler"
-	},
-	{
-		from: "queued",
-		to: "failed",
-		trigger: "reservation refused",
-		actor: "reconciler"
-	},
-	{
-		from: "queued",
-		to: "needs_human",
-		trigger: "kind is question",
-		actor: "system"
-	},
-	{
-		from: "queued",
-		to: "cancelled",
-		trigger: "cancel or kill",
-		actor: "operator"
-	},
-	{
-		from: "running",
-		to: "verifying",
-		trigger: "devbox task reported complete",
-		actor: "reconciler"
-	},
-	{
-		from: "running",
-		to: "queued",
-		trigger: "launch failed below attempt limit",
-		actor: "reconciler"
-	},
-	{
-		from: "running",
-		to: "failed",
-		trigger: "devbox task errored, deadline exceeded, or launch failed at attempt limit",
-		actor: "reconciler"
-	},
-	{
-		from: "running",
-		to: "needs_human",
-		trigger: "devbox task requires attention",
-		actor: "reconciler"
-	},
-	{
-		from: "running",
-		to: "cancelled",
-		trigger: "cancel or kill",
-		actor: "operator"
-	},
-	{
-		from: "verifying",
-		to: "succeeded",
-		trigger: "kind criterion true",
-		actor: "reconciler"
-	},
-	{
-		from: "verifying",
-		to: "running",
-		trigger: "verification failed below attempt limit",
-		actor: "reconciler"
-	},
-	{
-		from: "verifying",
-		to: "failed",
-		trigger: "verification failed at attempt limit",
-		actor: "reconciler"
-	},
-	{
-		from: "verifying",
-		to: "cancelled",
-		trigger: "cancel or kill",
-		actor: "operator"
-	},
-	{
-		from: "needs_human",
-		to: "succeeded",
-		trigger: "question answered",
-		actor: "operator"
-	},
-	{
-		from: "needs_human",
-		to: "queued",
-		trigger: "operator retry",
-		actor: "operator"
-	},
-	{
-		from: "needs_human",
-		to: "cancelled",
-		trigger: "cancel or kill",
-		actor: "operator"
-	},
-	{
-		from: "failed",
-		to: "queued",
-		trigger: "operator retry",
-		actor: "operator"
-	}
-];
-const changeInitialState = "verifying";
-const changeTransitions = [
-	{
-		from: "verifying",
-		to: "ready",
-		trigger: "verification task succeeded, risk and confidence written",
-		actor: "reconciler"
-	},
-	{
-		from: "verifying",
-		to: "closed",
-		trigger: "verification failed at attempt limit or pr closed upstream",
-		actor: "reconciler"
-	},
-	{
-		from: "ready",
-		to: "merged",
-		trigger: "pr merged on github",
-		actor: "webhook"
-	},
-	{
-		from: "ready",
-		to: "closed",
-		trigger: "pr closed without merge",
-		actor: "webhook"
-	},
-	{
-		from: "merged",
-		to: "deployed",
-		trigger: "production deployment ready containing the merge sha",
-		actor: "webhook"
-	},
-	{
-		from: "deployed",
-		to: "rolled_out",
-		trigger: "no flag, or flag ramped to full and held",
-		actor: "foreman"
-	},
-	{
-		from: "deployed",
-		to: "rolled_back",
-		trigger: "rollback rule crossed",
-		actor: "foreman"
-	},
-	{
-		from: "rolled_out",
-		to: "rolled_back",
-		trigger: "rollback rule crossed or flag flipped off",
-		actor: "foreman"
-	},
-	{
-		from: "rolled_back",
-		to: "deployed",
-		trigger: "human retried the ramp",
-		actor: "human"
-	}
-];
-const signalInitialOutcome = "pending";
-const signalOutcomeTransitions = [
-	{
-		from: "pending",
-		to: "accepted",
-		trigger: "classified as actionable",
-		actor: "reconciler"
-	},
-	{
-		from: "pending",
-		to: "duplicate",
-		trigger: "classified as duplicate",
-		actor: "reconciler"
-	},
-	{
-		from: "pending",
-		to: "unactionable",
-		trigger: "classified as unactionable",
-		actor: "reconciler"
-	},
-	{
-		from: "pending",
-		to: "low_confidence",
-		trigger: "classified below confidence threshold",
-		actor: "reconciler"
-	},
-	{
-		from: "pending",
-		to: "ignored",
-		trigger: "classified as ignorable",
-		actor: "reconciler"
-	}
-];
-function isTransitionAllowed(transitions, from, to) {
-	return transitions.some((transition) => transition.from === from && transition.to === to);
-}
-function legalNextStates(transitions, from) {
-	return [...new Set(transitions.filter((transition) => transition.from === from).map((t) => t.to))];
-}
-var InvalidTransitionError = class extends Error {
-	from;
-	to;
-	legalNextStates;
-	constructor(from, to, legal) {
-		super(legal.length > 0 ? `invalid transition from "${from}" to "${to}"; legal next states: ${legal.map((state) => `"${state}"`).join(", ")}` : `invalid transition from "${from}" to "${to}"; "${from}" is terminal`);
-		this.name = "InvalidTransitionError";
-		this.from = from;
-		this.to = to;
-		this.legalNextStates = legal;
-	}
-};
-function assertTransition(transitions, from, to) {
-	if (!isTransitionAllowed(transitions, from, to)) throw new InvalidTransitionError(from, to, legalNextStates(transitions, from));
-}
-function terminalStates(transitions) {
-	const states = /* @__PURE__ */ new Set();
-	for (const transition of transitions) {
-		states.add(transition.from);
-		states.add(transition.to);
-	}
-	return [...states].filter((state) => !transitions.some((transition) => transition.from === state));
-}
-//#endregion
 //#region src/signals.ts
 /**
 * Bind normalized intake to signal creation alone. Connectors and API routes
@@ -659,6 +388,64 @@ function createSignalCreator(stores) {
 	} };
 }
 //#endregion
+//#region src/stall.ts
+function stallWindowMinutes(policy, kind) {
+	return policy.stallMinutesByKind[kind] ?? policy.stallMinutes;
+}
+/**
+* The reconciler's stall pass. A running task whose execution has not
+* progressed within its stall window is marked stalled; a stalled task is
+* re-queued for a replacement attempt while attempts remain, and failed once
+* they are exhausted. Only `running` tasks can stall: a task whose result has
+* already been recorded (verifying, or terminal) is never retried by this
+* pass. Coordination parents run only through their children and are skipped.
+*/
+async function sweepStalled(stores, options) {
+	const nowMs = (options.now ?? (() => /* @__PURE__ */ new Date()))().getTime();
+	const result = {
+		stalled: [],
+		requeued: [],
+		failed: []
+	};
+	const tasks = await stores.tasks.list();
+	for (const task of tasks) {
+		if (task.state !== "running" || task.kind === "coordination") continue;
+		const minutes = stallWindowMinutes(options.policy, task.kind);
+		const sinceProgress = nowMs - Date.parse(task.lastProgressAt ?? task.updatedAt);
+		if (sinceProgress < minutes * 6e4) continue;
+		try {
+			await stores.tasks.transition(task.id, "stalled", {
+				reason: `no progress for ${Math.floor(sinceProgress / 6e4)} minutes (window ${minutes})`,
+				expectFrom: "running"
+			});
+			result.stalled.push(task.id);
+		} catch {
+			continue;
+		}
+	}
+	for (const task of await stores.tasks.list()) {
+		if (task.state !== "stalled") continue;
+		try {
+			if (task.attempt < options.policy.maxAttempts) {
+				await stores.tasks.transition(task.id, "queued", {
+					reason: `stalled on attempt ${task.attempt} of ${options.policy.maxAttempts}; replacing`,
+					expectFrom: "stalled"
+				});
+				result.requeued.push(task.id);
+			} else {
+				await stores.tasks.transition(task.id, "failed", {
+					reason: `stalled on attempt ${task.attempt} of ${options.policy.maxAttempts}; attempts exhausted`,
+					expectFrom: "stalled"
+				});
+				result.failed.push(task.id);
+			}
+		} catch {
+			continue;
+		}
+	}
+	return result;
+}
+//#endregion
 //#region src/store/engine.ts
 /** An approval decision that does not apply to the task's current approval or state. */
 var ApprovalError = class extends Error {
@@ -671,6 +458,17 @@ var ApprovalError = class extends Error {
 		this.reason = reason;
 	}
 };
+/** A settlement that does not apply to the task's current state. */
+var SettlementError = class extends Error {
+	taskId;
+	reason;
+	constructor(taskId, reason) {
+		super(`settlement on "${taskId}" refused: ${reason}`);
+		this.name = "SettlementError";
+		this.taskId = taskId;
+		this.reason = reason;
+	}
+};
 var ChangeAssociationError = class extends Error {
 	taskId;
 	repositoryId;
@@ -685,6 +483,7 @@ var ChangeAssociationError = class extends Error {
 };
 const taskReceiptStates = {
 	running: "dispatched",
+	stalled: "stalled",
 	succeeded: "succeeded",
 	failed: "failed",
 	needs_human: "needs_human",
@@ -706,6 +505,17 @@ function derivedId(prefix, key) {
 function bumpsAttempt(from, to) {
 	return to === "queued" || from === "verifying" && to === "running";
 }
+const emptyUsage = {
+	costUsd: 0,
+	inputTokens: 0,
+	outputTokens: 0,
+	cacheReadTokens: 0,
+	cacheWriteTokens: 0,
+	steps: {}
+};
+function addUsd(a, b) {
+	return (Math.round(a * 1e6) + Math.round(b * 1e6)) / 1e6;
+}
 function createStores(options) {
 	const { driver } = options;
 	const now = options.now ?? (() => (/* @__PURE__ */ new Date()).toISOString());
@@ -741,7 +551,7 @@ function createStores(options) {
 		}
 	}
 	async function appendReceipt(key, receipt) {
-		await insertReceipt(derivedId("rcpt", key), receipt);
+		return insertReceipt(derivedId("rcpt", key), receipt);
 	}
 	return {
 		driverName: driver.name,
@@ -807,9 +617,10 @@ function createStores(options) {
 		tasks: {
 			async create(input) {
 				const timestamp = now();
+				const id = input.dedupeKey === void 0 ? randomId("task") : derivedId("task", input.dedupeKey);
 				const task = taskSchema.parse({
 					schemaVersion: 1,
-					id: randomId("task"),
+					id,
 					repositoryIds: input.repositoryIds,
 					kind: input.kind,
 					area: input.area,
@@ -820,11 +631,17 @@ function createStores(options) {
 					replyTo: input.replyTo,
 					attempt: 1,
 					question: input.question,
+					changeId: input.changeId,
 					createdAt: timestamp,
 					updatedAt: timestamp
 				});
-				await driver.insert("tasks", task.id, task);
-				return task;
+				try {
+					await driver.insert("tasks", task.id, task);
+					return task;
+				} catch (error) {
+					if (input.dedupeKey !== void 0 && error instanceof RecordExistsError) return (await mustRead("tasks", task.id, taskSchema)).value;
+					throw error;
+				}
 			},
 			async approve(id, decision) {
 				const existing = await mustRead("tasks", id, taskSchema);
@@ -883,30 +700,124 @@ function createStores(options) {
 				await driver.update("tasks", id, next, existing.version);
 				return next;
 			},
+			async recordExecution(id, execution) {
+				const existing = await mustRead("tasks", id, taskSchema);
+				const task = existing.value;
+				if (task.state !== "running") throw new InvalidTransitionError(task.state, "running", legalNextStates(taskTransitions, task.state));
+				const timestamp = now();
+				const next = taskSchema.parse({
+					...task,
+					execution,
+					lastProgressAt: timestamp,
+					updatedAt: timestamp
+				});
+				await driver.update("tasks", id, next, existing.version);
+				return next;
+			},
+			async recordUsage(id, step) {
+				for (;;) {
+					const existing = await mustRead("tasks", id, taskSchema);
+					const task = existing.value;
+					const usage = task.usage ?? emptyUsage;
+					const recordedIndex = usage.steps[step.turnId];
+					if (recordedIndex !== void 0 && step.stepIndex <= recordedIndex) return task;
+					const timestamp = now();
+					const next = taskSchema.parse({
+						...task,
+						lastProgressAt: timestamp,
+						usage: {
+							costUsd: addUsd(usage.costUsd, step.costUsd ?? 0),
+							inputTokens: usage.inputTokens + (step.inputTokens ?? 0),
+							outputTokens: usage.outputTokens + (step.outputTokens ?? 0),
+							cacheReadTokens: usage.cacheReadTokens + (step.cacheReadTokens ?? 0),
+							cacheWriteTokens: usage.cacheWriteTokens + (step.cacheWriteTokens ?? 0),
+							steps: {
+								...usage.steps,
+								[step.turnId]: step.stepIndex
+							}
+						},
+						updatedAt: timestamp
+					});
+					try {
+						await driver.update("tasks", id, next, existing.version);
+						return next;
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			},
+			async settle(id, cost, settleOptions = {}) {
+				const existing = await mustRead("tasks", id, taskSchema);
+				const task = existing.value;
+				if (task.settledUsd !== void 0) return task;
+				if (task.state !== "succeeded" && task.state !== "failed" && task.state !== "cancelled") throw new SettlementError(id, `task is ${task.state}, not terminal`);
+				const validated = costSchema.parse(cost);
+				const normalized = { totalUsd: Math.round(validated.totalUsd * 1e6) / 1e6 };
+				let recorded = normalized;
+				if (task.repositoryIds !== void 0) recorded = (await appendReceipt(`task:${id}:settled:${task.attempt}`, {
+					repositoryIds: task.repositoryIds,
+					taskId: id,
+					changeId: task.changeId,
+					kind: task.kind,
+					state: "settled",
+					phase: "budget",
+					reason: settleOptions.reason,
+					attempt: task.attempt,
+					cost: normalized
+				})).cost ?? normalized;
+				const next = taskSchema.parse({
+					...task,
+					settledUsd: recorded.totalUsd,
+					updatedAt: now()
+				});
+				await driver.update("tasks", id, next, existing.version);
+				return next;
+			},
 			async get(id) {
 				const record = await read("tasks", id, taskSchema);
 				return record === null ? null : record.value;
 			},
 			async transition(id, to, transitionOptions = {}) {
+				if (transitionOptions.patch !== void 0 && "settledUsd" in transitionOptions.patch) throw new SettlementError(id, "settledUsd is set only by settle, not a transition");
+				if (transitionOptions.patch !== void 0 && "usage" in transitionOptions.patch) throw new SettlementError(id, "usage is set only by recordUsage, not a transition");
 				const existing = await mustRead("tasks", id, taskSchema);
+				if (transitionOptions.expectFrom !== void 0 && existing.value.state !== transitionOptions.expectFrom) throw new InvalidTransitionError(existing.value.state, to, legalNextStates(taskTransitions, existing.value.state));
 				assertTransition(taskTransitions, existing.value.state, to);
-				const attempt = bumpsAttempt(existing.value.state, to) ? existing.value.attempt + 1 : existing.value.attempt;
+				if (to === "needs_human" && existing.value.kind !== "question") {
+					if (!(await listAll("tasks", taskSchema)).some((task) => task.kind === "question" && task.state === "needs_human" && task.origin.parentTaskId === id)) throw new Error(`task ${id} cannot enter needs_human without an open QuestionTask`);
+				}
+				const bumps = bumpsAttempt(existing.value.state, to);
+				const timestamp = now();
+				const { stalledAt: _stalledAt, stalledReason: _stalledReason, ...cleared } = existing.value;
 				const next = taskSchema.parse({
-					...existing.value,
+					...cleared,
+					...bumps ? { execution: void 0 } : {},
 					...transitionOptions.patch,
+					...to === "stalled" ? {
+						stalledAt: timestamp,
+						stalledReason: transitionOptions.reason
+					} : {},
+					...to === "running" ? { lastProgressAt: timestamp } : {},
 					state: to,
-					attempt,
-					updatedAt: now()
+					attempt: bumps ? existing.value.attempt + 1 : existing.value.attempt,
+					updatedAt: timestamp
 				});
 				const receiptState = taskReceiptStates[to];
-				if (receiptState !== void 0 && next.repositoryIds !== void 0) await appendReceipt(`task:${id}:${receiptState}:${attempt}`, {
+				if (receiptState !== void 0 && next.repositoryIds !== void 0) await appendReceipt(JSON.stringify([
+					"task",
+					id,
+					receiptState,
+					next.attempt,
+					next.changeId ?? null,
+					transitionOptions.reason ?? null
+				]), {
 					repositoryIds: next.repositoryIds,
 					taskId: id,
 					changeId: next.changeId,
 					kind: next.kind,
 					state: receiptState,
 					reason: transitionOptions.reason,
-					attempt
+					attempt: next.attempt
 				});
 				await driver.update("tasks", id, next, existing.version);
 				return next;
@@ -990,6 +901,66 @@ function createStores(options) {
 			list() {
 				return listAll("receipts", receiptSchema);
 			}
+		},
+		budgets: {
+			async ensure(input) {
+				const budget = budgetSchema.parse({
+					schemaVersion: 1,
+					factoryId: input.factoryId,
+					month: input.month,
+					limits: input.limits,
+					notices: {}
+				});
+				try {
+					await driver.insert("budgets", input.month, budget);
+					return budget;
+				} catch (error) {
+					if (!(error instanceof RecordExistsError)) throw error;
+				}
+				const existing = await mustRead("budgets", input.month, budgetSchema);
+				const refreshed = budgetSchema.parse({
+					...existing.value,
+					limits: input.limits
+				});
+				if (JSON.stringify(refreshed) === JSON.stringify(existing.value)) return existing.value;
+				try {
+					await driver.update("budgets", input.month, refreshed, existing.version);
+					return refreshed;
+				} catch (error) {
+					if (error instanceof VersionConflictError) return (await mustRead("budgets", input.month, budgetSchema)).value;
+					throw error;
+				}
+			},
+			async get(month) {
+				const record = await read("budgets", month, budgetSchema);
+				return record === null ? null : record.value;
+			},
+			async stampNotice(month, notice) {
+				const field = notice === "warning" ? "warningAt" : "exhaustedAt";
+				for (;;) {
+					const existing = await mustRead("budgets", month, budgetSchema);
+					if (existing.value.notices[field] !== void 0) return {
+						budget: existing.value,
+						stamped: false
+					};
+					const next = budgetSchema.parse({
+						...existing.value,
+						notices: {
+							...existing.value.notices,
+							[field]: now()
+						}
+					});
+					try {
+						await driver.update("budgets", month, next, existing.version);
+						return {
+							budget: next,
+							stamped: true
+						};
+					} catch (error) {
+						if (!(error instanceof VersionConflictError)) throw error;
+					}
+				}
+			}
 		}
 	};
 }
@@ -1097,7 +1068,10 @@ async function sweepQueued(stores, options) {
 			continue;
 		}
 		try {
-			await dispatchTask(stores, task.id, { launch: (dispatched) => launcher(dispatched, repository) });
+			await dispatchTask(stores, task.id, {
+				launch: (dispatched) => launcher(dispatched, repository),
+				budget: options.budget
+			});
 			result.dispatched.push(task.id);
 		} catch (error) {
 			if (error instanceof DispatchRefusedError) {
@@ -1116,6 +1090,35 @@ async function sweepQueued(stores, options) {
 	return result;
 }
 //#endregion
-export { ApprovalError, ChangeAssociationError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchRefusedError, InvalidTransitionError, RecordExistsError, RecordNotFoundError, SCHEMA_VERSION, VersionConflictError, adoptPullRequest, approvalPolicySchema, approvalRuleSchema, assertTransition, budgetMonthSchema, budgetSchema, changeEvidenceSchema, changeIdSchema, changeInitialState, changeSchema, changeStateSchema, changeTransitions, computeLedgerMetrics, computeRepositoryHealth, coordinationRepositoryIdsSchema, costSchema, createCoordination, createInMemoryDriver, createSignalCreator, createStores, defaultApprovalPolicy, defineFactory, dispatchTask, factoryConfigRepositorySchema, factoryConfigSchema, factoryIdSchema, findingCategorySchema, findingFingerprint, findingForTask, findingPrioritySchema, findingSchema, findingVerificationLevelSchema, findingVerificationMethodSchema, findingVerificationSchema, fixBrief, harnessSchema, isTransitionAllowed, isoDateTimeSchema, legalNextStates, levelSchema, receiptIdSchema, receiptKindSchema, receiptPhaseSchema, receiptSchema, receiptStateSchema, reconcileCoordination, replyToSchema, repositoryIdSchema, repositoryIdsSchema, repositorySchema, repositorySlugSchema, requiresApproval, reviewBucket, scanBrief, schemaVersionSchema, signalIdSchema, signalInitialOutcome, signalOutcomeSchema, signalOutcomeTransitions, signalSchema, signalSourceSchema, standardReceiptKinds, standardReceiptPhases, standardReceiptStates, standardSignalSources, standardTaskKinds, sweepQueued, taskApprovalSchema, taskDevboxSchema, taskExecutionRepositoryIdsSchema, taskIdSchema, taskInitialState, taskKindSchema, taskOriginSchema, taskQuestionSchema, taskSchema, taskStateSchema, taskTransitions, terminalStates, usdSchema, vocabularySchema };
+//#region src/verification-dispatch.ts
+/** Ensure every recorded code change has exactly one durable verification task. */
+async function ensureVerificationTasks(stores) {
+	const tasks = await stores.tasks.list();
+	const existingIds = new Set(tasks.map((task) => task.id));
+	const result = {
+		created: [],
+		existing: []
+	};
+	const sources = tasks.filter((task) => task.kind === "code_change" && task.state === "verifying" && task.changeId !== void 0);
+	for (const source of sources) {
+		const existing = tasks.find((task) => task.kind === "verification" && task.origin.parentTaskId === source.id);
+		if (existing !== void 0) {
+			result.existing.push(existing.id);
+			continue;
+		}
+		const verification = await stores.tasks.create({
+			repositoryIds: source.repositoryIds,
+			kind: "verification",
+			origin: { parentTaskId: source.id },
+			replyTo: source.replyTo,
+			changeId: source.changeId,
+			dedupeKey: `verification:${source.id}:${source.changeId}`
+		});
+		(existingIds.has(verification.id) ? result.existing : result.created).push(verification.id);
+	}
+	return result;
+}
+//#endregion
+export { ApprovalError, BudgetExhaustedError, ChangeAssociationError, DEFAULT_MAX_LAUNCH_ATTEMPTS, DispatchRefusedError, InvalidTransitionError, RecordExistsError, RecordNotFoundError, SCHEMA_VERSION, SettlementError, VersionConflictError, adoptPullRequest, agentRouteSchema, approvalPolicySchema, approvalRuleSchema, assertTransition, budgetLimitsSchema, budgetMonthOf, budgetMonthSchema, budgetSchema, budgetStatus, canReserve, changeEvidenceSchema, changeIdSchema, changeInitialState, changeSchema, changeStateSchema, changeTransitions, computeLedgerMetrics, computeMonthSpendUsd, computeRepositoryHealth, coordinationRepositoryIdsSchema, costSchema, createCoordination, createInMemoryDriver, createSignalCreator, createStores, defaultApprovalPolicy, defaultExecutionPolicy, defineAgentRoutes, defineFactory, deriveFactoryId, dispatchTask, ensureVerificationTasks, executionPolicySchema, executionReferenceSchema, factoryConfigRepositorySchema, factoryConfigSchema, factoryIdSchema, findingCategorySchema, findingFingerprint, findingForTask, findingPrioritySchema, findingSchema, findingVerificationLevelSchema, findingVerificationMethodSchema, findingVerificationSchema, fixBrief, harnessSchema, isTransitionAllowed, isoDateTimeSchema, legalNextStates, levelSchema, receiptIdSchema, receiptKindSchema, receiptPhaseSchema, receiptSchema, receiptStateSchema, reconcileCoordination, replyToSchema, repositoryIdSchema, repositoryIdsSchema, repositorySchema, repositorySlugSchema, requiresApproval, reviewBucket, scanBrief, schemaVersionSchema, signalIdSchema, signalInitialOutcome, signalOutcomeSchema, signalOutcomeTransitions, signalSchema, signalSourceSchema, stallWindowMinutes, standardReceiptKinds, standardReceiptPhases, standardReceiptStates, standardSignalSources, standardTaskKinds, sweepBudget, sweepQueued, sweepSettlements, sweepStalled, taskApprovalSchema, taskExecutionRepositoryIdsSchema, taskIdSchema, taskInitialState, taskKindSchema, taskOriginSchema, taskQuestionSchema, taskSchema, taskStateSchema, taskTransitions, taskUsageSchema, terminalStates, usdSchema, verificationBrief, vocabularySchema };
 
 //# sourceMappingURL=index.mjs.map