@vercel/factory 0.0.14 → 0.0.15

package/dist/eve/index.mjs

@@ -1,947 +1,15 @@
-import { c as signalIdSchema, h as vocabularySchema, l as taskIdSchema, n as changeIdSchema, o as repositoryIdSchema } from "../id-BLIkCVue.mjs";
-import { l as taskQuestionSchema } from "../task-CcOyOJ3k.mjs";
-import { c as findingSchema, i as requiresApproval, o as findingFingerprint, r as defaultApprovalPolicy } from "../approval-JX2Px9IC.mjs";
-import { c as dispatchTask, i as levelSchema, t as changeEvidenceSchema } from "../change-D2U6v7Ek.mjs";
-import { t as createCoordination } from "../coordination-Cq08hb1l.mjs";
-import { answerReviewComment, readPullRequestHead, readReviewComment, submitPullRequestReview } from "../github.mjs";
+import { changeIdSchema, repositoryIdsSchema, signalIdSchema, taskIdSchema } from "../schema/id.mjs";
+import { taskWork } from "../schema/work.mjs";
+import { taskQuestionSchema } from "../schema/task.mjs";
+import { receiptKindSchema, receiptStateSchema } from "../schema/receipt.mjs";
+import { conversationBinding, conversationBindingForSession, conversationHeaders, factoryReplyAddressAttribute, factoryReplyAddressHeader, factoryReplyChannelAttribute, factoryReplyChannelHeader, factoryRepositoryIdsAttribute, factoryRepositoryIdsHeader, factoryTaskAttemptAttribute, factoryTaskAttemptHeader, factoryTaskAttribute, factoryTaskHeader, hasFactoryTaskBinding, optionalTaskIdForSession, replyToForSession, repositoryIdsForSession, requireTaskIdForSession, taskBindingForSession, taskHeaders, taskSessionAuth, withFactoryTask, withOptionalFactoryTask } from "./task-session.mjs";
+import { requireTaskExecution } from "./task-execution.mjs";
+import { createEveTranscriptMaterializer } from "./transcript.mjs";
+import { cancelEveSession, forwardEveSessionRequest, readCompletedEveTurn, startEveSession } from "./session-client.mjs";
+import { createDelegateAgentTool, createInvokeAgentTool } from "./invoke.mjs";
 import { z } from "zod";
-import { createHash } from "node:crypto";
 import { defineHook } from "eve/hooks";
 import { defineTool } from "eve/tools";
-//#region src/eve/conflict.ts
-const gitShaSchema = z.string().regex(/^[0-9a-f]{40}$/);
-const gitBranchSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._/-]*$/).refine((value) => !value.includes(".."));
-const mergeConflictPayloadSchema = z.strictObject({
-	repository: z.string().regex(/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/),
-	prNumber: z.number().int().positive(),
-	prUrl: z.url(),
-	headBranch: gitBranchSchema.refine((value) => value.startsWith("factory/")),
-	headSha: gitShaSchema,
-	baseBranch: gitBranchSchema,
-	baseSha: gitShaSchema
-});
-function mergeConflictTools(stores, options) {
-	const repoPath = options.repoPath ?? "repo";
-	async function context(taskId) {
-		const task = await stores.tasks.get(taskId);
-		if (task === null) throw new Error(`task ${taskId} does not exist`);
-		if (task.kind !== "merge_conflict") throw new Error(`task ${taskId} is ${task.kind}, not merge_conflict`);
-		if (task.state !== "running") throw new Error(`task ${taskId} is ${task.state}, not running`);
-		if (task.origin.signalId === void 0) throw new Error(`task ${taskId} has no conflict signal`);
-		const signal = await stores.signals.get(task.origin.signalId);
-		if (signal === null || signal.source !== "github_merge_conflict") throw new Error(`task ${taskId} has no GitHub merge conflict signal`);
-		return {
-			task,
-			conflict: mergeConflictPayloadSchema.parse(signal.payload)
-		};
-	}
-	return {
-		fetch_merge_conflict: defineTool({
-			description: "Fetch the conflicted factory pull request and its current base, check out the PR head, and start the merge. Resolve every file returned in conflictedFiles, then test and commit the merge.",
-			inputSchema: z.object({ taskId: taskIdSchema }),
-			async execute({ taskId }, ctx) {
-				const { conflict } = await context(taskId);
-				const sandbox = await ctx.getSandbox();
-				const git = `git -C ${repoPath}`;
-				const headRef = `refs/remotes/origin/conflict-pr-${conflict.prNumber}`;
-				const baseRef = `refs/remotes/origin/conflict-base-${conflict.prNumber}`;
-				const fetch = await options.withCredential(sandbox, conflict.repository, `${git} fetch --depth 100 origin +refs/pull/${conflict.prNumber}/head:${headRef} +refs/heads/${conflict.baseBranch}:${baseRef}`);
-				if (typeof fetch.exitCode === "number" && fetch.exitCode !== 0) throw new Error(`could not fetch pull request: ${(fetch.stderr ?? "").trim()}`);
-				const [headSha, baseSha] = (await sandbox.run({ command: `${git} rev-parse ${headRef} && ${git} rev-parse ${baseRef}` })).stdout.trim().split("\n");
-				if (headSha !== conflict.headSha || baseSha !== conflict.baseSha) throw new Error("pull request or base changed while conflict resolution was starting; retry from a new task");
-				await sandbox.run({ command: `${git} checkout -B conflict-pr ${headRef}` });
-				const merge = await sandbox.run({ command: `${git} merge --no-commit --no-ff ${baseRef}` });
-				const conflictedFiles = (await sandbox.run({ command: `${git} diff --name-only --diff-filter=U` })).stdout.trim().split("\n").filter(Boolean);
-				if (conflictedFiles.length === 0) throw new Error(typeof merge.exitCode === "number" && merge.exitCode !== 0 ? `merge failed without file conflicts: ${(merge.stderr ?? "").trim()}` : "pull request no longer has merge conflicts");
-				return {
-					...conflict,
-					conflictedFiles
-				};
-			}
-		}),
-		publish_merge_resolution: defineTool({
-			description: "Publish a tested, committed conflict resolution to the existing pull request branch. Fails if the remote branch changed since this task started.",
-			inputSchema: z.object({
-				taskId: taskIdSchema,
-				summary: z.string().min(1).max(2e3)
-			}),
-			async execute({ taskId, summary }, ctx) {
-				const { conflict } = await context(taskId);
-				const sandbox = await ctx.getSandbox();
-				const git = `git -C ${repoPath}`;
-				if ((await sandbox.run({ command: `${git} status --porcelain` })).stdout.trim() !== "") throw new Error("commit the conflict resolution before publishing");
-				if ((await sandbox.run({ command: `${git} diff --name-only --diff-filter=U` })).stdout.trim() !== "") throw new Error("merge conflicts remain unresolved");
-				const push = await options.withCredential(sandbox, conflict.repository, `${git} push --force-with-lease=refs/heads/${conflict.headBranch}:${conflict.headSha} origin HEAD:refs/heads/${conflict.headBranch}`);
-				if (typeof push.exitCode === "number" && push.exitCode !== 0) throw new Error(`could not update pull request branch: ${(push.stderr ?? "").trim()}`);
-				await stores.tasks.transition(taskId, "verifying", { reason: summary });
-				await stores.tasks.transition(taskId, "succeeded", { reason: summary });
-				return {
-					updated: true,
-					prNumber: conflict.prNumber,
-					prUrl: conflict.prUrl
-				};
-			}
-		})
-	};
-}
-//#endregion
-//#region src/eve/finding.ts
-function isLostRaceError(error) {
-	return error instanceof Error && (error.name === "VersionConflictError" || error.name === "InvalidTransitionError");
-}
-/**
-* Turn one finding into a signal and a fix task. The fingerprint is the
-* signal's delivery id, so the same problem reported twice is a no-op. The
-* signal is accepted on the reporter's own verification (a human gate follows
-* when the approval policy says so), and the task carries the approval
-* decision from the moment it exists. Shared by record_finding and scanner
-* tools that record on the agent's behalf.
-*/
-async function recordFinding(stores, repositoryId, finding, options = {}) {
-	const source = options.source ?? "security_scan";
-	const policy = options.approval ?? defaultApprovalPolicy;
-	if (await stores.repositories.get(repositoryId) === null) return {
-		recorded: false,
-		reason: `repository ${repositoryId} does not exist`
-	};
-	const fingerprint = findingFingerprint(repositoryId, finding);
-	const signal = await stores.signals.create({
-		repositoryId,
-		source,
-		deliveryId: fingerprint,
-		replyTo: {
-			channel: "finding",
-			address: fingerprint
-		},
-		payload: finding
-	});
-	if (signal.outcome !== "pending") return {
-		recorded: false,
-		duplicate: true,
-		signalId: signal.id,
-		reason: `already recorded as ${signal.id}`
-	};
-	try {
-		await stores.signals.decide(signal.id, "accepted", {
-			detail: finding.priority,
-			reason: `${finding.tool ?? "scanner"} reported it, ${finding.verification.level} by ${finding.verification.method}`
-		});
-	} catch (error) {
-		if (isLostRaceError(error)) {
-			const current = await stores.signals.get(signal.id);
-			if (current !== null && current.outcome !== "pending") return {
-				recorded: false,
-				duplicate: true,
-				signalId: signal.id,
-				reason: `already recorded as ${signal.id}`
-			};
-		}
-		throw error;
-	}
-	const approval = requiresApproval(policy, {
-		source,
-		kind: "code_change",
-		priority: finding.priority
-	});
-	const task = await stores.tasks.create({
-		repositoryIds: [repositoryId],
-		kind: "code_change",
-		origin: { signalId: signal.id },
-		replyTo: signal.replyTo,
-		...approval ? { approval: "required" } : {}
-	});
-	return {
-		recorded: true,
-		signalId: signal.id,
-		taskId: task.id,
-		approval: approval ? "required" : "not_required"
-	};
-}
-/**
-* The scanner's outcome tool: turns one finding into a signal and a fix task
-* in a single deterministic step. The finding's fingerprint is the signal's
-* delivery id, so reporting the same problem twice is a no-op. The signal is
-* accepted on the reporter's own verification (a human gate follows when the
-* approval policy says so), and the task carries the approval decision from
-* the moment it exists.
-*/
-function recordFindingTool(stores, options = {}) {
-	return defineTool({
-		description: "Record one problem you found in the repository. Creates a fix task (which may wait for human approval) unless the same finding was already recorded. Report every finding separately; never batch.",
-		inputSchema: z.object({
-			repositoryId: repositoryIdSchema,
-			finding: findingSchema
-		}),
-		execute({ repositoryId, finding }) {
-			return recordFinding(stores, repositoryId, finding, options);
-		}
-	});
-}
-//#endregion
-//#region src/eve/deepsec.ts
-/** deepsec's exported finding shape, as far as we depend on it. */
-const deepsecFindingSchema = z.looseObject({
-	title: z.string().min(1),
-	description: z.string().min(1),
-	severity: z.string().min(1),
-	metadata: z.looseObject({
-		filePath: z.string().min(1).optional(),
-		lineNumbers: z.array(z.number().int().min(1)).optional(),
-		vulnSlug: z.string().min(1).optional(),
-		confidence: z.string().optional(),
-		runId: z.string().optional()
-	}).optional()
-});
-const deepsecExportSchema = z.union([z.array(deepsecFindingSchema), z.looseObject({ findings: z.array(deepsecFindingSchema) }).transform((value) => value.findings)]);
-const priorityBySeverity = {
-	CRITICAL: "P0",
-	HIGH: "P1",
-	MEDIUM: "P2",
-	HIGH_BUG: "P2",
-	BUG: "P3",
-	LOW: "P3"
-};
-/** Convert one deepsec finding into the factory's Finding. Pure; exported for tests. */
-function findingFromDeepsec(raw) {
-	const meta = raw.metadata ?? {};
-	const confidence = (meta.confidence ?? "").toLowerCase();
-	const line = meta.lineNumbers?.[0];
-	const endLine = meta.lineNumbers === void 0 ? void 0 : Math.max(...meta.lineNumbers);
-	return findingSchema.parse({
-		title: raw.title.replace(/^\[[A-Z_]+\]\s*/u, "").slice(0, 200),
-		body: raw.description.slice(0, 8e3),
-		...meta.filePath === void 0 ? {} : { path: meta.filePath.slice(0, 500) },
-		...line === void 0 ? {} : { line },
-		...endLine === void 0 || endLine === line ? {} : { endLine },
-		priority: priorityBySeverity[raw.severity.toUpperCase()] ?? "P3",
-		category: "security",
-		verification: {
-			level: confidence === "high" ? "supported" : "unverified",
-			method: "static_analysis",
-			summary: `deepsec ${meta.vulnSlug ?? "finding"} with ${confidence || "unknown"} confidence${meta.runId === void 0 ? "" : ` (run ${meta.runId})`}.`,
-			limitations: "AI-assisted static analysis of the checkout; not reproduced at runtime."
-		},
-		tool: "deepsec",
-		...meta.vulnSlug === void 0 ? {} : { ruleId: meta.vulnSlug }
-	});
-}
-const findingsPath = "/tmp/deepsec-findings.json";
-/** Parse "N file(s) with candidates" out of deepsec scan output; null when absent. */
-function candidateCount(output) {
-	const match = /(\d+)\s+file\(s\) with candidates/u.exec(output);
-	return match?.[1] === void 0 ? null : Number(match[1]);
-}
-/** The last few meaningful lines of a command's output, ANSI stripped, for a receipt. */
-function tail(output, lines = 4) {
-	return output.replaceAll(/\u001b\[[0-9;]*m/gu, "").split("\n").map((line) => line.trim()).filter((line) => line !== "").slice(-lines).join(" | ").slice(0, 600);
-}
-/**
-* Runs deepsec (vercel-labs/deepsec) against the sandbox checkout and records
-* what it finds through the same path as record_finding, so every deepsec
-* finding becomes a fix task subject to the approval policy. Trusted code
-* owns the command sequence and the credential; the agent chooses when to
-* scan and reports the outcome.
-*/
-function deepsecScanTool(stores, options) {
-	const repoPath = options.repoPath ?? "repo";
-	const workspace = options.workspacePath ?? "deepsec";
-	const version = options.version ?? "2.3.8";
-	const agent = options.agent ?? "claude";
-	const model = options.model ?? "claude-sonnet-4-6";
-	const thinkingLevel = options.thinkingLevel ?? "medium";
-	const concurrency = options.concurrency ?? 4;
-	const prefix = options.commandPrefix === void 0 ? [] : [options.commandPrefix];
-	const filesPerRun = options.filesPerRun ?? 40;
-	return defineTool({
-		description: "Run deepsec, the AI-powered vulnerability scanner, over the repository checkout and record every finding it reports as a fix task. Takes minutes. Call once per scan; then summarize the result.",
-		inputSchema: z.object({
-			repositoryId: repositoryIdSchema,
-			limit: z.number().int().min(1).max(500).optional().describe("Candidate files to investigate this run (default 40; deepsec resumes where it left off next time).")
-		}),
-		async execute({ repositoryId, limit }, ctx) {
-			const repository = await stores.repositories.get(repositoryId);
-			if (repository === null) return {
-				scanned: false,
-				reason: `repository ${repositoryId} does not exist`
-			};
-			const sandbox = await ctx.getSandbox();
-			const projectId = repository.slug.replace(/[^a-z0-9]+/gu, "-");
-			const startedAt = Date.now();
-			const phase = async (state, reason) => {
-				await stores.receipts.append({
-					repositoryIds: [repositoryId],
-					kind: "deepsec",
-					state,
-					phase: "security_scan",
-					reason: `${reason} (${Math.round((Date.now() - startedAt) / 1e3)}s in)`
-				});
-			};
-			await phase("started", `deepsec ${version} on ${repository.slug}, ${agent}/${model}`);
-			const prepare = await sandbox.run({ command: [
-				...prefix,
-				"set -e",
-				`if [ ! -f ${workspace}/deepsec.config.ts ]; then`,
-				`  npx -y deepsec@${version} init ./${workspace} ./${repoPath} --id ${projectId} --scaffold-only --headless --yes --skip-install`,
-				`  (cd ${workspace} && npm install --no-audit --no-fund --loglevel=error)`,
-				"fi",
-				`cd ${workspace}`,
-				`./node_modules/.bin/deepsec scan --project-id ${projectId}`
-			].join("\n") });
-			if (typeof prepare.exitCode === "number" && prepare.exitCode !== 0) {
-				const detail = (prepare.stderr ?? prepare.stdout).trim().slice(-1500);
-				await phase("failed", `scan phase failed: ${detail.slice(-300)}`);
-				return {
-					scanned: false,
-					reason: `deepsec scan failed: ${detail}`
-				};
-			}
-			const candidates = candidateCount(prepare.stdout);
-			await phase("scanned", `${candidates === null ? "scan output" : `${candidates} files with candidates`}: ${tail(`${prepare.stdout}\n${prepare.stderr ?? ""}`)}`);
-			const investigate = await options.withModelCredential(sandbox, [
-				...prefix,
-				"set -e",
-				`cd ${workspace}`,
-				`./node_modules/.bin/deepsec process --project-id ${projectId} --agent ${agent} --model ${model} --thinking-level ${thinkingLevel} --concurrency ${concurrency} --limit ${limit ?? filesPerRun}`,
-				`./node_modules/.bin/deepsec export --project-id ${projectId} --format json --out ${findingsPath}`
-			].join("\n"));
-			if (typeof investigate.exitCode === "number" && investigate.exitCode !== 0) {
-				const detail = (investigate.stderr ?? investigate.stdout).trim().slice(-1500);
-				await phase("failed", `process phase failed: ${detail.slice(-300)}`);
-				return {
-					scanned: false,
-					reason: `deepsec process failed: ${detail}`
-				};
-			}
-			const exported = await sandbox.run({ command: `cat ${findingsPath}` });
-			let parsed;
-			try {
-				parsed = JSON.parse(exported.stdout);
-			} catch {
-				return {
-					scanned: false,
-					reason: "deepsec export was not valid JSON"
-				};
-			}
-			const raw = deepsecExportSchema.safeParse(parsed);
-			if (!raw.success) return {
-				scanned: false,
-				reason: `deepsec export had an unexpected shape: ${raw.error.issues[0]?.message ?? "unknown"}`
-			};
-			const results = [];
-			for (const entry of raw.data) {
-				const finding = findingFromDeepsec(entry);
-				results.push({
-					finding,
-					result: await recordFinding(stores, repositoryId, finding, options)
-				});
-			}
-			const recorded = results.filter(({ result }) => result.recorded);
-			await phase("completed", `${results.length} findings, ${recorded.length} new. process output: ${tail(`${investigate.stdout}\n${investigate.stderr ?? ""}`, 6)}`);
-			return {
-				scanned: true,
-				tool: "deepsec",
-				found: results.length,
-				recorded: recorded.length,
-				duplicates: results.length - recorded.length,
-				awaitingApproval: recorded.filter(({ result }) => result.recorded && result.approval === "required").length,
-				findings: results.map(({ finding, result }) => ({
-					title: finding.title,
-					priority: finding.priority,
-					path: finding.path,
-					line: finding.line,
-					...result.recorded ? {
-						taskId: result.taskId,
-						approval: result.approval
-					} : { duplicate: true }
-				}))
-			};
-		}
-	});
-}
-//#endregion
-//#region src/eve/fetch.ts
-/**
-* The verifier's way in to the change under review. The sandbox has no
-* GitHub credential while the agent runs, so trusted code does the one fetch
-* the agent cannot: the pull request number and repository come from the
-* change record, never from the agent, and the credential is gone again
-* before control returns. Mirrors how publication reads commits out of the
-* sandbox instead of letting the agent push.
-*/
-function fetchPullRequestTool(stores, options) {
-	const repoPath = options.repoPath ?? "repo";
-	const depth = options.depth ?? 50;
-	return defineTool({
-		description: "Fetch the pull request and the repository's current default branch, then check out the pull request as local branch `pr`. Call this after get_task, before inspecting or testing the change. Returns an exact diff command based on their merge base; use it instead of origin/HEAD.",
-		inputSchema: z.object({ changeId: changeIdSchema.describe("The Change linked to your Task, returned by get_task.") }),
-		async execute({ changeId }, ctx) {
-			const boundTaskId = taskIdSchema.safeParse(ctx.session?.auth.initiator?.attributes.factoryTaskId);
-			if (boundTaskId.success) {
-				const task = await stores.tasks.get(boundTaskId.data);
-				if (task === null) return {
-					fetched: false,
-					reason: `task ${boundTaskId.data} does not exist`
-				};
-				if (task.changeId !== void 0 && task.changeId !== changeId) return {
-					fetched: false,
-					reason: `change ${changeId} is not linked to task ${boundTaskId.data}`
-				};
-			}
-			const change = await stores.changes.get(changeId);
-			if (change === null) return {
-				fetched: false,
-				reason: `change ${changeId} does not exist`
-			};
-			if (change.state !== "verifying" && change.state !== "ready") return {
-				fetched: false,
-				reason: `change is ${change.state}, not open for review; nothing to fetch`
-			};
-			const repository = await stores.repositories.get(change.repositoryId);
-			if (repository === null) return {
-				fetched: false,
-				reason: `repository ${change.repositoryId} does not exist`
-			};
-			const sandbox = await ctx.getSandbox();
-			const tracking = `refs/remotes/origin/pr-${change.prNumber}`;
-			const baseTracking = `refs/remotes/origin/${repository.defaultBranch}`;
-			const git = `git -C ${repoPath}`;
-			const result = await options.withCredential(sandbox, repository.slug, `${git} fetch --depth ${depth} origin +refs/heads/${repository.defaultBranch}:${baseTracking} +refs/pull/${change.prNumber}/head:${tracking} && ${git} checkout -B pr ${tracking}`);
-			if (typeof result.exitCode === "number" && result.exitCode !== 0) return {
-				fetched: false,
-				reason: `git fetch of pull request ${change.prNumber} failed: ${(result.stderr ?? "").trim()}`
-			};
-			const head = await sandbox.run({ command: `${git} rev-parse HEAD` });
-			const base = await sandbox.run({ command: `${git} rev-parse ${baseTracking}` });
-			const mergeBase = await sandbox.run({ command: `${git} merge-base ${baseTracking} pr` });
-			if (typeof mergeBase.exitCode === "number" && mergeBase.exitCode !== 0) return {
-				fetched: false,
-				reason: `could not determine the pull request merge base: ${(mergeBase.stderr ?? "").trim()}`
-			};
-			const mergeBaseSha = mergeBase.stdout.trim();
-			return {
-				fetched: true,
-				prNumber: change.prNumber,
-				prUrl: change.prUrl,
-				branch: "pr",
-				headSha: head.stdout.trim(),
-				baseBranch: repository.defaultBranch,
-				baseSha: base.stdout.trim(),
-				mergeBaseSha,
-				diffCommand: `${git} diff ${mergeBaseSha}..pr`
-			};
-		}
-	});
-}
-//#endregion
-//#region src/eve/invoke.ts
-/**
-* A tool that lets one agent hand work to another, NMA-style: the caller
-* decides to invoke; trusted code owns the how. The handoff is recorded as a
-* factory task (single-winner dispatch, receipts), then a fresh session is
-* started on the target agent carrying only the task id — never the caller's
-* context. The session start is create-once on the task id, so a retried
-* tool call cannot start a second session.
-*/
-function invokeAgentTool(stores, options) {
-	const doFetch = options.fetch ?? fetch;
-	return defineTool({
-		description: `${options.description} Hands the work to a separate agent in a fresh session; you will not see its reasoning. Returns the handoff task id.`,
-		inputSchema: z.object({
-			repositoryIds: z.array(repositoryIdSchema).min(1),
-			parentTaskId: taskIdSchema.optional().describe("Your own task, when this work continues it."),
-			changeId: changeIdSchema.optional().describe("The change the target agent should work on."),
-			channel: z.string().min(1).describe("Reply connector, e.g. github."),
-			address: z.string().min(1).describe("Reply address, e.g. acme/web#41."),
-			brief: z.string().min(1).max(4e3).describe("What the target agent needs to know. Facts and references only, not your reasoning.")
-		}),
-		async execute(input) {
-			const task = await stores.tasks.create({
-				repositoryIds: input.repositoryIds,
-				kind: options.kind,
-				origin: input.parentTaskId === void 0 ? { operator: "factory" } : { parentTaskId: input.parentTaskId },
-				replyTo: {
-					channel: input.channel,
-					address: input.address
-				}
-			});
-			const running = await dispatchTask(stores, task.id, {
-				maxLaunchAttempts: 1,
-				budget: options.budget?.(),
-				launch: async (dispatched) => {
-					const headers = {
-						"content-type": "application/json",
-						...await options.headers?.(dispatched)
-					};
-					const token = await options.token?.();
-					if (token !== void 0) headers.authorization = `Bearer ${token}`;
-					const message = [
-						`You are assigned factory task ${dispatched.id}.`,
-						input.changeId === void 0 ? null : `Change under review: ${input.changeId}.`,
-						`Reply address: ${input.channel} ${input.address}.`,
-						"",
-						input.brief,
-						"",
-						"Read the task with get_task first, do the work, and record the outcome with your factory tools."
-					].filter((line) => line !== null).join("\n");
-					const response = await doFetch(`${options.targetUrl()}/eve/v1/session`, {
-						method: "POST",
-						headers,
-						body: JSON.stringify({
-							message,
-							operationId: `factory-task:${dispatched.id}`
-						})
-					});
-					if (!response.ok) throw new Error(`target agent refused the session: ${response.status}`);
-				}
-			});
-			return {
-				taskId: running.id,
-				kind: running.kind,
-				state: running.state
-			};
-		}
-	});
-}
-/**
-* Give a conversational agent one bounded delegation surface backed by the
-* application's route registry. The caller selects a declared route; trusted
-* code owns task creation, budget enforcement, and the fresh target session.
-*/
-function delegateAgentTool(stores, options) {
-	const doFetch = options.fetch ?? fetch;
-	const routeSummary = options.routes.routes.map((route) => `${route.id}: ${route.description}`).join("\n");
-	return defineTool({
-		description: "Delegate durable work to one registered specialist. Select only a listed route; the specialist runs independently and reports its result through Factory.\n" + routeSummary,
-		inputSchema: z.object({
-			routeId: z.string().min(1).describe("One route id listed in this tool's description."),
-			repositoryIds: z.array(repositoryIdSchema).min(1),
-			signalId: signalIdSchema.optional().describe("Pending external signal this delegation accepts."),
-			parentTaskId: taskIdSchema.optional().describe("Existing task this work continues."),
-			changeId: changeIdSchema.optional().describe("Existing change the specialist should inspect."),
-			channel: z.string().min(1).describe("Originating conversation channel."),
-			address: z.string().min(1).describe("Originating conversation reply address."),
-			brief: z.string().min(1).max(4e3).describe("Facts and desired outcome, without hidden reasoning.")
-		}),
-		async execute(input, ctx) {
-			const route = options.routes.get(input.routeId);
-			if (route === void 0) throw new Error(`Unknown agent route ${input.routeId}.`);
-			const replyTo = {
-				channel: input.channel,
-				address: input.address
-			};
-			const attributes = ctx.session.auth.initiator?.attributes;
-			const repositoryAttribute = attributes?.factoryRepositoryIds;
-			const boundRepositoryIds = typeof repositoryAttribute === "string" ? repositoryAttribute.split(",").filter(Boolean) : repositoryAttribute;
-			if (boundRepositoryIds !== void 0 && (boundRepositoryIds.length !== input.repositoryIds.length || boundRepositoryIds.some((id) => !input.repositoryIds.includes(id)))) throw new Error("Delegation repositories do not match the connector-authenticated context.");
-			if (attributes?.factoryReplyChannel !== void 0 && attributes.factoryReplyChannel !== replyTo.channel || attributes?.factoryReplyAddress !== void 0 && attributes.factoryReplyAddress !== replyTo.address) throw new Error("Delegation reply address does not match the authenticated conversation.");
-			for (const repositoryId of input.repositoryIds) {
-				const repository = await stores.repositories.get(repositoryId);
-				if (repository === null || !repository.enabled) throw new Error(`Repository ${repositoryId} is not enabled in this factory.`);
-			}
-			const boundChange = changeIdSchema.safeParse(attributes?.factoryChangeId);
-			if (attributes?.factoryChangeId !== void 0 && !boundChange.success) throw new Error("Connector-authenticated change context is invalid.");
-			if (input.changeId !== void 0 && boundChange.success && input.changeId !== boundChange.data) throw new Error("Delegated change does not match the connector-authenticated context.");
-			const changeId = input.changeId ?? (boundChange.success ? boundChange.data : void 0);
-			if (changeId !== void 0) {
-				if (input.repositoryIds.length !== 1) throw new Error("Delegating work on an existing Change requires exactly one repository.");
-				const change = await stores.changes.get(changeId);
-				if (change === null || change.repositoryId !== input.repositoryIds[0] || change.state !== "verifying" && change.state !== "ready") throw new Error(`Change ${changeId} is not an open pull request in the selected repository.`);
-			}
-			if (input.signalId !== void 0) {
-				const signal = await stores.signals.get(input.signalId);
-				if (signal === null) throw new Error(`Signal ${input.signalId} does not exist.`);
-				if (!input.repositoryIds.includes(signal.repositoryId) || signal.replyTo.channel !== replyTo.channel || signal.replyTo.address !== replyTo.address) throw new Error("Delegation does not match the signal's authenticated repository and reply address.");
-				if (signal.outcome === "pending") await stores.signals.decide(signal.id, "accepted", { reason: `Foreman selected ${route.id}.` });
-				else if (signal.outcome !== "accepted") throw new Error(`Signal ${signal.id} is already ${signal.outcome}.`);
-			}
-			const operator = ctx.session.auth.initiator?.principalId ?? "foreman";
-			if (route.taskKind === "code_change" && input.repositoryIds.length > 1) {
-				const [first, second, ...rest] = input.repositoryIds;
-				if (first === void 0 || second === void 0) throw new Error("Coordination requires two repositories.");
-				const coordination = await createCoordination(stores, {
-					repositoryIds: [
-						first,
-						second,
-						...rest
-					],
-					replyTo,
-					...input.signalId === void 0 ? {} : { dedupeKey: `route:${input.signalId}:${route.id}` },
-					...input.signalId === void 0 ? { operator } : { signalId: input.signalId }
-				});
-				await Promise.all(coordination.children.filter((child) => child.state === "queued").map((child) => dispatchRouteTask(stores, options, doFetch, route, child, changeId, input.brief)));
-				return {
-					taskId: coordination.parent.id,
-					childTaskIds: coordination.children.map(({ id }) => id),
-					routeId: route.id,
-					agent: route.agent,
-					state: coordination.parent.state
-				};
-			}
-			const task = await stores.tasks.create({
-				repositoryIds: input.repositoryIds,
-				kind: route.taskKind,
-				origin: input.signalId !== void 0 ? { signalId: input.signalId } : input.parentTaskId !== void 0 ? { parentTaskId: input.parentTaskId } : { operator },
-				replyTo,
-				changeId,
-				...input.signalId === void 0 ? {} : { dedupeKey: `route:${input.signalId}:${route.id}` }
-			});
-			const running = task.state === "queued" ? await dispatchRouteTask(stores, options, doFetch, route, task, changeId, input.brief) : task;
-			return {
-				taskId: running.id,
-				routeId: route.id,
-				agent: route.agent,
-				state: running.state
-			};
-		}
-	});
-}
-async function dispatchRouteTask(stores, options, doFetch, route, task, changeId, brief) {
-	return dispatchTask(stores, task.id, {
-		maxLaunchAttempts: 1,
-		budget: options.budget?.(route),
-		launch: async (dispatched) => {
-			const headers = {
-				"content-type": "application/json",
-				...await options.headers?.(dispatched, route)
-			};
-			const token = await options.token?.(route);
-			if (token !== void 0) headers.authorization = `Bearer ${token}`;
-			const message = [
-				`You are assigned factory task ${dispatched.id} through route ${route.id}.`,
-				changeId === void 0 ? null : `Change under review: ${changeId}.`,
-				brief,
-				"Read the task first and return exactly one bounded Factory outcome."
-			].filter((line) => line !== null).join("\n\n");
-			const response = await doFetch(`${options.targetUrl(route)}/eve/v1/session`, {
-				method: "POST",
-				headers,
-				body: JSON.stringify({
-					message,
-					operationId: `factory-task:${dispatched.id}`
-				})
-			});
-			if (!response.ok) throw new Error(`${route.agent} refused the session: ${response.status}`);
-		}
-	});
-}
-//#endregion
-//#region src/eve/post-review.ts
-const reviewCommentSchema = z.strictObject({
-	key: z.string().min(1).max(80).regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/).optional().describe("Stable kebab-case identity for this defect and cause; keep it unchanged across reruns."),
-	title: z.string().min(1).max(200).optional().describe("Short finding title."),
-	path: z.string().min(1).max(500).describe("Repository-relative file path."),
-	line: z.number().int().min(1).describe("Line in the pull request's new version."),
-	body: z.string().min(1).max(5e3).describe("Markdown explaining the finding and a concrete fix.")
-});
-const reviewCommentsSchema = z.array(reviewCommentSchema).max(50).default([]).superRefine((comments, context) => {
-	const seen = /* @__PURE__ */ new Set();
-	comments.forEach((comment, index) => {
-		if (comment.key === void 0) return;
-		if (seen.has(comment.key)) context.addIssue({
-			code: "custom",
-			message: `duplicate finding key: ${comment.key}`,
-			path: [index, "key"]
-		});
-		seen.add(comment.key);
-	});
-});
-/**
-* Publish an independent review of an existing pull request and finish the
-* review task without changing the pull request's factory lifecycle.
-*/
-function postReviewTool(stores, options) {
-	return defineTool({
-		description: "Record a completed code review and finish your code_review task. Results may be reported through completion callbacks instead of a GitHub review; use request_changes only for blocking findings.",
-		inputSchema: z.object({
-			taskId: taskIdSchema.describe("Your code_review task."),
-			changeId: changeIdSchema.describe("The pull request change from your starting message."),
-			verdict: z.enum([
-				"approve",
-				"request_changes",
-				"comment"
-			]),
-			headSha: z.string().regex(/^[0-9a-f]{40}$/).describe("Commit returned by fetch_pull_request."),
-			summary: z.string().min(1).max(5e3).describe("Markdown summary of what you reviewed and found."),
-			comments: reviewCommentsSchema
-		}),
-		async execute({ taskId, changeId, verdict, headSha, summary, comments }) {
-			const task = await stores.tasks.get(taskId);
-			if (task === null || task.kind !== "code_review") return {
-				recorded: false,
-				reason: `${taskId} is not a code_review task`
-			};
-			if (task.state !== "running") return {
-				recorded: false,
-				reason: `task is ${task.state}, not running`
-			};
-			const change = await stores.changes.get(changeId);
-			if (change === null) return {
-				recorded: false,
-				reason: `change ${changeId} does not exist`
-			};
-			if (change.state !== "verifying" && change.state !== "ready") return {
-				recorded: false,
-				reason: `change is ${change.state}, not open for review`
-			};
-			const repository = await stores.repositories.get(change.repositoryId);
-			if (repository === null) return {
-				recorded: false,
-				reason: `repository ${change.repositoryId} does not exist`
-			};
-			const token = await options.tokenForRepository(repository.slug);
-			const completedComments = comments.map((comment) => {
-				const key = comment.key ?? legacyFindingKey(comment);
-				return {
-					...comment,
-					key,
-					title: comment.title ?? "Review finding",
-					fingerprint: createHash("sha256").update(`${repository.slug.toLowerCase()}#${change.prNumber}:${key}`).digest("hex")
-				};
-			});
-			const completed = {
-				taskId,
-				changeId,
-				repository: repository.slug,
-				pullRequestNumber: change.prNumber,
-				headSha,
-				verdict,
-				summary,
-				comments: completedComments
-			};
-			const publish = options.publishReviews !== false;
-			let review;
-			if (publish) {
-				review = await submitPullRequestReview({
-					repository: repository.slug,
-					token,
-					fetch: options.fetch,
-					pullRequestNumber: change.prNumber,
-					commitId: headSha,
-					event: verdict === "approve" ? "APPROVE" : verdict === "request_changes" ? "REQUEST_CHANGES" : "COMMENT",
-					body: summary,
-					comments: completedComments
-				});
-				await options.onPublished?.({
-					...completed,
-					review
-				});
-			} else {
-				const head = await readPullRequestHead({
-					repository: repository.slug,
-					token,
-					fetch: options.fetch,
-					pullRequestNumber: change.prNumber
-				});
-				if (head.sha !== headSha) throw new Error(`pull request changed after review: expected ${headSha}, found ${head.sha}`);
-			}
-			await options.onCompleted?.(completed);
-			await stores.tasks.transition(taskId, "verifying", { reason: summary });
-			const finished = await stores.tasks.transition(taskId, "succeeded");
-			return {
-				recorded: true,
-				verdict,
-				published: review !== void 0,
-				...review === void 0 ? {} : { review },
-				taskState: finished.state
-			};
-		}
-	});
-}
-function legacyFindingKey(comment) {
-	return `legacy-${createHash("sha256").update(`${comment.path}:${comment.line}:${comment.body}`).digest("hex").slice(0, 24)}`;
-}
-//#endregion
-//#region src/eve/review.ts
-function reviewCommentTools(stores, options) {
-	const repoPath = options.repoPath ?? "repo";
-	const commentInputSchema = z.object({
-		changeId: changeIdSchema.describe("The change under review, from your starting message."),
-		commentId: z.number().int().positive().describe("The GitHub review comment id.")
-	});
-	return {
-		read_review_comment: defineTool({
-			description: "Read an inline review comment on a change under verification or ready for human review. By default this refuses to return comments from people without write access to the repository.",
-			inputSchema: commentInputSchema,
-			async execute({ changeId, commentId }) {
-				const change = await stores.changes.get(changeId);
-				if (change === null) throw new Error(`change ${changeId} does not exist`);
-				if (change.state !== "verifying" && change.state !== "ready") throw new Error(`change is ${change.state}, not open for review`);
-				const repository = await stores.repositories.get(change.repositoryId);
-				if (repository === null) throw new Error(`repository ${change.repositoryId} does not exist`);
-				return readReviewComment({
-					repository: repository.slug,
-					token: await options.tokenForRepository(repository.slug),
-					fetch: options.fetch,
-					commentId
-				});
-			}
-		}),
-		answer_review_comment: defineTool({
-			description: "Reply to an inline review comment on a change under verification or ready for human review. Use for findings and low-confidence responses, not for a concrete medium- or high-confidence fix.",
-			inputSchema: commentInputSchema.extend({ body: z.string().min(1).max(5e3).describe("The Markdown reply to post.") }),
-			async execute({ changeId, commentId, body }) {
-				const change = await stores.changes.get(changeId);
-				if (change === null) throw new Error(`change ${changeId} does not exist`);
-				if (change.state !== "verifying" && change.state !== "ready") throw new Error(`change is ${change.state}, not open for review`);
-				const repository = await stores.repositories.get(change.repositoryId);
-				if (repository === null) throw new Error(`repository ${change.repositoryId} does not exist`);
-				return answerReviewComment({
-					repository: repository.slug,
-					token: await options.tokenForRepository(repository.slug),
-					fetch: options.fetch,
-					pullRequestNumber: change.prNumber,
-					commentId,
-					body
-				});
-			}
-		}),
-		suggest_review_fix: defineTool({
-			description: "Post a concrete, apply-able GitHub suggested change for a medium-confidence fix. The replacement must cover exactly the lines attached to the inline review comment.",
-			inputSchema: commentInputSchema.extend({
-				confidence: z.literal("medium"),
-				replacement: z.string().min(1).max(5e3).describe("Exact replacement text for the commented lines."),
-				summary: z.string().min(1).max(1e3).describe("A brief explanation of the suggested fix.")
-			}),
-			async execute({ changeId, commentId, replacement, summary }) {
-				const change = await stores.changes.get(changeId);
-				if (change === null) throw new Error(`change ${changeId} does not exist`);
-				if (change.state !== "verifying" && change.state !== "ready") throw new Error(`change is ${change.state}, not open for review`);
-				const repository = await stores.repositories.get(change.repositoryId);
-				if (repository === null) throw new Error(`repository ${change.repositoryId} does not exist`);
-				return answerReviewComment({
-					repository: repository.slug,
-					token: await options.tokenForRepository(repository.slug),
-					fetch: options.fetch,
-					pullRequestNumber: change.prNumber,
-					commentId,
-					body: `${summary}\n\n\`\`\`suggestion\n${replacement}\n\`\`\``
-				});
-			}
-		}),
-		apply_review_fix: defineTool({
-			description: "Publish a tested, committed high-confidence fix to the existing same-repository pull request branch. Fails if the checkout is dirty, the PR changed, or the PR comes from a fork.",
-			inputSchema: commentInputSchema.extend({
-				confidence: z.literal("high"),
-				summary: z.string().min(1).max(1e3).describe("What was fixed and verified.")
-			}),
-			async execute({ changeId, commentId, summary }, ctx) {
-				const change = await stores.changes.get(changeId);
-				if (change === null) throw new Error(`change ${changeId} does not exist`);
-				if (change.state !== "verifying" && change.state !== "ready") throw new Error(`change is ${change.state}, not open for review`);
-				const repository = await stores.repositories.get(change.repositoryId);
-				if (repository === null) throw new Error(`repository ${change.repositoryId} does not exist`);
-				if (options.withCredential === void 0) throw new Error("applying review fixes is not configured");
-				const token = await options.tokenForRepository(repository.slug);
-				await readReviewComment({
-					repository: repository.slug,
-					token,
-					fetch: options.fetch,
-					commentId
-				});
-				const head = await readPullRequestHead({
-					repository: repository.slug,
-					token,
-					fetch: options.fetch,
-					pullRequestNumber: change.prNumber
-				});
-				if (head.repository !== repository.slug.toLowerCase()) throw new Error("cannot apply a fix to a pull request from a fork");
-				const sandbox = await ctx.getSandbox();
-				const git = `git -C ${repoPath}`;
-				if ((await sandbox.run({ command: `${git} status --porcelain` })).stdout.trim() !== "") throw new Error("commit the review fix before publishing");
-				if ((await sandbox.run({ command: `${git} merge-base --is-ancestor ${head.sha} HEAD` })).exitCode !== 0) throw new Error("pull request changed after it was fetched; fetch it again before applying the fix");
-				if ((await sandbox.run({ command: `${git} rev-parse HEAD` })).stdout.trim() === head.sha) throw new Error("no committed review fix to publish");
-				const push = await options.withCredential(sandbox, repository.slug, `${git} push --force-with-lease=refs/heads/${head.branch}:${head.sha} origin HEAD:refs/heads/${head.branch}`);
-				if (typeof push.exitCode === "number" && push.exitCode !== 0) throw new Error(`could not update pull request branch: ${(push.stderr ?? "").trim()}`);
-				const reply = await answerReviewComment({
-					repository: repository.slug,
-					token,
-					fetch: options.fetch,
-					pullRequestNumber: change.prNumber,
-					commentId,
-					body: summary
-				});
-				return {
-					updated: true,
-					prNumber: change.prNumber,
-					prUrl: change.prUrl,
-					reply
-				};
-			}
-		})
-	};
-}
-//#endregion
-//#region src/eve/verification.ts
-/**
-* The verifier's outcome tool. Writes evidence onto the change and moves it
-* to ready only when the verdict is pass; a failed verdict leaves the change
-* verifying with the evidence recorded, and the verification task itself
-* ends with a receipt either way. The change's own code_change task follows
-* the verdict too: succeeded on pass, failed on fail with the verifier's
-* summary as the reason, so the ledger never shows a verified-and-rejected fix
-* as still in progress. Fail closed: the agent cannot mark a change ready
-* without supplying every evidence field.
-*/
-function recordVerificationTool(stores, options = {}) {
-	return defineTool({
-		description: "Record the outcome of a verification task: the evidence you gathered and whether the change passed. Pass moves the change to ready for human review; fail keeps it out of review.",
-		inputSchema: z.object({
-			taskId: taskIdSchema.describe("Your verification task."),
-			changeId: changeIdSchema.describe("The change you verified."),
-			verdict: z.enum(["pass", "fail"]),
-			evidence: changeEvidenceSchema,
-			confidence: levelSchema.describe("How certain you are in the verdict."),
-			summary: z.string().min(1).max(2e3).describe("What you checked and what you found.")
-		}),
-		async execute({ taskId, changeId, verdict, evidence, confidence, summary }) {
-			const change = await stores.changes.get(changeId);
-			if (change === null) return {
-				recorded: false,
-				reason: `change ${changeId} does not exist`
-			};
-			if (change.state !== "verifying" && change.state !== "ready") return {
-				recorded: false,
-				reason: `change is ${change.state}, not open for verification; nothing to record`
-			};
-			const task = await stores.tasks.get(taskId);
-			if (task === null || task.kind !== "verification") return {
-				recorded: false,
-				reason: `${taskId} is not a verification task`
-			};
-			let updatedChange = change;
-			if (verdict === "pass" && change.state === "verifying") updatedChange = await stores.changes.transition(changeId, "ready", {
-				patch: {
-					evidence,
-					confidence
-				},
-				reason: summary
-			});
-			else if (verdict === "fail" && change.state === "ready") updatedChange = await stores.changes.transition(changeId, "verifying", { reason: summary });
-			let finished;
-			if (verdict === "pass") {
-				await stores.tasks.transition(taskId, "verifying", { reason: summary });
-				finished = await stores.tasks.transition(taskId, "succeeded");
-			} else finished = await stores.tasks.transition(taskId, "failed", { reason: summary });
-			const sourceTaskId = task.origin.parentTaskId ?? change.taskId;
-			if (sourceTaskId !== void 0) {
-				if ((await stores.tasks.get(sourceTaskId))?.state === "verifying") await stores.tasks.transition(sourceTaskId, verdict === "pass" ? "succeeded" : "failed", verdict === "pass" ? {} : { reason: `verification failed: ${summary}` }).catch(() => void 0);
-			}
-			await options.presentResult?.({
-				taskId,
-				changeId,
-				verdict,
-				summary
-			});
-			return {
-				recorded: true,
-				verdict,
-				changeState: updatedChange.state,
-				taskState: finished.state
-			};
-		}
-	});
-}
-//#endregion
 //#region src/eve/index.ts
 const decidedOutcomeSchema = z.enum([
 	"accepted",
@@ -950,46 +18,62 @@ const decidedOutcomeSchema = z.enum([
 	"low_confidence",
 	"ignored"
 ]);
-const recordChangeInputSchema = z.object({
-	taskId: taskIdSchema,
-	repositoryId: repositoryIdSchema,
-	prNumber: z.number().int().min(1),
-	prUrl: z.url(),
-	risk: levelSchema.describe("Blast radius of the change if it is wrong."),
-	confidence: levelSchema.describe("How certain you are the change is correct."),
-	summary: z.string().min(1).describe("One-sentence description of the change.")
-});
 async function createAndPresentQuestion(stores, parent, question, presentQuestion) {
+	const needsHumanAction = question.text.trim();
+	if (needsHumanAction === "") throw new Error("A human question must contain non-blank text.");
 	const task = await stores.tasks.create({
 		repositoryIds: parent.repositoryIds,
 		kind: "question",
-		origin: { parentTaskId: parent.id },
+		work: taskWork({
+			title: needsHumanAction.slice(0, 256),
+			input: { question }
+		}),
+		parentTaskId: parent.id,
+		parentTaskAttempt: parent.attempt,
+		origin: {},
 		replyTo: parent.replyTo,
 		question
 	});
-	const waiting = await stores.tasks.transition(task.id, "needs_human");
 	try {
+		const waiting = await stores.tasks.transition(task.id, "needs_human", { needsHumanAction });
 		if (parent.state === "running") await stores.tasks.transition(parent.id, "needs_human", {
+			expectFrom: "running",
+			expectAttempt: parent.attempt,
 			reason: `waiting for answer to question ${waiting.id}`,
-			questionTaskId: waiting.id
+			questionTaskId: waiting.id,
+			needsHumanAction
 		});
 		await presentQuestion(waiting);
+		return waiting;
 	} catch (error) {
-		if ((await stores.tasks.get(parent.id))?.state === "needs_human") await stores.tasks.transition(parent.id, "queued", { reason: `delivery of question ${waiting.id} failed` });
-		if ((await stores.tasks.get(waiting.id))?.state === "needs_human") await stores.tasks.transition(waiting.id, "cancelled", { reason: "question delivery failed" });
+		const currentParent = await stores.tasks.get(parent.id);
+		if (currentParent?.state === "needs_human" && currentParent.attempt === parent.attempt && currentParent.questionTaskId === task.id) try {
+			await stores.tasks.transition(parent.id, "queued", {
+				expectFrom: "needs_human",
+				expectAttempt: currentParent.attempt,
+				expectQuestionTaskId: task.id,
+				reason: `delivery of question ${task.id} failed`
+			});
+		} catch (cleanupError) {
+			const latest = await stores.tasks.get(parent.id);
+			if (latest?.state === "needs_human" && latest.attempt === currentParent.attempt && latest.questionTaskId === task.id) throw cleanupError;
+		}
+		const currentQuestion = await stores.tasks.get(task.id);
+		if (currentQuestion?.state === "needs_human" || currentQuestion?.state === "queued") await stores.tasks.transition(task.id, "cancelled", {
+			expectFrom: currentQuestion.state,
+			expectAttempt: currentQuestion.attempt,
+			reason: "question delivery failed"
+		});
 		throw error;
 	}
-	return waiting;
 }
 /**
-* The factory's store operations wrapped as eve tools. Expose a tool to an
+* The factory's provider-neutral store operations wrapped as Eve tools. Expose a tool to an
 * agent by re-exporting it from a file under agent/tools/, e.g.
-* `export default factoryTools(stores).get_task;`. Every write goes through
+* `export default createTaskTools(stores).get_task;`. Every write goes through
 * the engine, so agents inherit transition legality and receipts.
 */
-function factoryTools(stores, options = {}) {
-	const recordChangeGate = options.recordChangeGate;
-	const verification = options.verification ?? "required";
+function createTaskTools(stores, options = {}) {
 	return {
 		get_task: defineTool({
 			description: "Read one factory task by id: its kind, state, repositories, origin, and results.",
@@ -1010,105 +94,45 @@ function factoryTools(stores, options = {}) {
 				detail: z.string().min(1).optional().describe("Severity if accepted, or the duplicate-of signal id.")
 			}),
 			execute({ signalId, outcome, reason, detail }) {
-				return stores.signals.decide(signalId, outcome, {
+				return stores.signals.decide(signalId, {
+					outcome,
 					reason,
 					detail
 				});
 			}
 		}),
-		record_change: defineTool({
-			description: verification === "required" ? "Record the pull request produced for a code_change task. Creates the change, links it to the task, and moves the task to verifying." : "Record the pull request produced for a code_change task. Creates the change and marks it ready for human review without independent verification.",
-			inputSchema: recordChangeInputSchema,
-			...recordChangeGate === void 0 ? {} : { approval: async ({ toolInput }) => {
-				const parsed = recordChangeInputSchema.safeParse(toolInput);
-				if (!parsed.success) return {
-					type: "denied",
-					reason: "record_change input is malformed; fix the arguments and retry"
-				};
-				const verdict = await recordChangeGate(parsed.data);
-				return verdict.ok ? "not-applicable" : {
-					type: "denied",
-					reason: verdict.reason
-				};
-			} },
-			async execute({ taskId, repositoryId, prNumber, prUrl, risk, confidence, summary }) {
-				const currentTask = await stores.tasks.get(taskId);
-				if (currentTask === null) throw new Error(`task ${taskId} does not exist`);
-				if (currentTask.state !== "running" && currentTask.state !== "verifying" && currentTask.state !== "succeeded") throw new Error(`task ${taskId} is ${currentTask.state}, not running`);
-				const linkedChange = currentTask.changeId === void 0 ? void 0 : await stores.changes.get(currentTask.changeId);
-				if (currentTask.changeId !== void 0 && linkedChange === null) throw new Error(`change ${currentTask.changeId} does not exist`);
-				let change = linkedChange ?? (await stores.changes.list()).find((candidate) => candidate.taskId === taskId);
-				if (change === void 0) {
-					if (currentTask.state !== "running") throw new Error(`task ${taskId} has no recorded change`);
-					change = await stores.changes.create({
-						repositoryId,
-						taskId,
-						prNumber,
-						prUrl,
-						author: "factory",
-						risk,
-						confidence,
-						evidence: {
-							reproVerified: false,
-							testsAdded: 0,
-							checksGreen: false,
-							attackPassed: false,
-							scopeMatches: false
-						}
-					});
-				}
-				if (currentTask.state === "running") await options.presentChange?.({
-					taskId,
-					changeId: change.id,
-					verification,
-					summary
-				});
-				let task = currentTask;
-				if (task.state === "running") task = await stores.tasks.transition(taskId, "verifying", {
-					patch: { changeId: change.id },
-					reason: summary
-				});
-				if (verification === "required") return {
-					change,
-					task
-				};
-				if (change.state === "verifying") change = await stores.changes.transition(change.id, "ready", { reason: "independent verification is not configured" });
-				if (task.state === "verifying") task = await stores.tasks.transition(taskId, "succeeded", { reason: "change recorded for human review without independent verification" });
-				return {
-					change,
-					task
-				};
-			}
-		}),
 		finish_task: defineTool({
-			description: "Mark your task finished with a summary, for task kinds that have no other outcome tool (for example a security_scan). Not for code_change or verification tasks: those end with record_change and record_verification.",
+			description: "Mark your running task finished with a summary. The configured workflow policy may require a more specific outcome tool.",
 			inputSchema: z.object({
 				taskId: taskIdSchema,
 				summary: z.string().min(1).max(4e3).describe("What you did and found, for the ledger.")
 			}),
-			async execute({ taskId, summary }) {
-				const task = await stores.tasks.get(taskId);
-				if (task === null) return {
-					finished: false,
-					reason: `${taskId} does not exist`
-				};
-				if (task.kind === "code_change" || task.kind === "verification") return {
+			async execute({ taskId, summary }, ctx) {
+				const task = await requireTaskExecution(stores, ctx, taskId);
+				const refusal = await options.finishTaskPolicy?.(task);
+				if (refusal !== void 0 && refusal !== null) return {
 					finished: false,
-					reason: `${task.kind} tasks end with their own outcome tool`
+					reason: refusal
 				};
 				if (task.state !== "running") return {
 					finished: false,
 					reason: `task is ${task.state}, not running`
 				};
-				await stores.tasks.transition(taskId, "verifying", { reason: summary });
+				await stores.tasks.transition(taskId, "succeeded", {
+					expectFrom: "running",
+					expectAttempt: task.attempt,
+					expectExecution: task.execution,
+					reason: summary,
+					output: { summary }
+				});
 				return {
 					finished: true,
-					taskState: (await stores.tasks.transition(taskId, "succeeded", { reason: summary })).state
+					taskState: "succeeded"
 				};
 			}
 		}),
 		request_human_input: defineTool({
-			description: "Request human input or action and pause your task until the human replies. The parent task determines the repositories and reply destination.",
+			description: "Request one human input or action and pause your currently running task until the human replies. A paused task cannot request another question; wait for the answer and replacement execution. The parent task determines the repositories and reply destination. Name any suggested reply in question.closingOptions when that exact answer means no further attempt can help (for example \"nothing to do, close it\"); Factory resolves the task instead of requeuing an identical retry when the human picks one.",
 			inputSchema: z.object({
 				parentTaskId: taskIdSchema.describe("Your running task, which the answer will unblock."),
 				question: taskQuestionSchema.omit({
@@ -1116,16 +140,13 @@ function factoryTools(stores, options = {}) {
 					answeredBy: true
 				})
 			}),
-			async execute({ parentTaskId, question }) {
+			async execute({ parentTaskId, question }, ctx) {
 				if (options.presentQuestion === void 0) throw new Error("request_human_input requires a configured question presenter.");
-				const parent = await stores.tasks.get(parentTaskId);
-				if (parent === null) throw new Error(`Parent task ${parentTaskId} does not exist.`);
-				if (parent.state !== "running" && parent.state !== "needs_human") throw new Error(`Parent task ${parentTaskId} is ${parent.state}, not running.`);
-				return createAndPresentQuestion(stores, parent, question, options.presentQuestion);
+				return createAndPresentQuestion(stores, await requireTaskExecution(stores, ctx, parentTaskId), question, options.presentQuestion);
 			}
 		}),
 		answer_question: defineTool({
-			description: "Record the authenticated user's answer to a waiting question and requeue the parent specialist task. A blocked parent task id is also accepted and resolves its persisted QuestionTask id.",
+			description: "Record the authenticated user's answer to a waiting question and requeue the parent specialist task, unless the answer matches one of the question's closingOptions, which resolves the parent task instead. A blocked parent task id is also accepted and resolves its persisted QuestionTask id.",
 			inputSchema: z.object({
 				questionTaskId: taskIdSchema,
 				answer: z.string().min(1).max(4e3)
@@ -1135,9 +156,9 @@ function factoryTools(stores, options = {}) {
 				const resolvedQuestionTaskId = requestedTask?.kind === "question" ? requestedTask.id : requestedTask?.questionTaskId;
 				const questionTask = resolvedQuestionTaskId === void 0 ? null : await stores.tasks.get(resolvedQuestionTaskId);
 				if (questionTask === null || questionTask.kind !== "question" || questionTask.question === void 0) throw new Error(`Question task ${questionTaskId} does not exist.`);
-				const attributes = ctx.session.auth.initiator?.attributes;
-				if (attributes?.factoryReplyChannel !== questionTask.replyTo.channel || attributes.factoryReplyAddress !== questionTask.replyTo.address) throw new Error("Question reply does not match the authenticated conversation.");
-				const answeredBy = ctx.session.auth.initiator?.principalId ?? "operator";
+				const { initiator, current } = ctx.session.auth;
+				if (!initiator || !current || [initiator, current].some(({ attributes }) => attributes.factoryReplyChannel !== questionTask.replyTo.channel || attributes.factoryReplyAddress !== questionTask.replyTo.address)) throw new Error("Question reply does not match the authenticated conversation.");
+				const answeredBy = current.principalId;
 				return stores.tasks.answerQuestion({
 					questionTaskId: questionTask.id,
 					answer,
@@ -1148,11 +169,11 @@ function factoryTools(stores, options = {}) {
 		append_receipt: defineTool({
 			description: "Append one immutable audit receipt for an event worth remembering. Receipts can never be edited or deleted.",
 			inputSchema: z.object({
-				repositoryIds: z.array(repositoryIdSchema).min(1),
+				repositoryIds: repositoryIdsSchema,
 				taskId: taskIdSchema.optional(),
 				changeId: changeIdSchema.optional(),
-				kind: vocabularySchema.describe("What the receipt is about, e.g. investigation."),
-				state: vocabularySchema.describe("What happened, e.g. flag_ramped."),
+				kind: receiptKindSchema.describe("What the receipt is about, e.g. investigation."),
+				state: receiptStateSchema.describe("What happened, e.g. flag_ramped."),
 				reason: z.string().min(1).max(2e3).optional(),
 				dedupeKey: z.string().min(1).optional().describe("Same key twice records one receipt instead of two.")
 			}),
@@ -1162,62 +183,209 @@ function factoryTools(stores, options = {}) {
 		})
 	};
 }
+function materializationInput(ctx) {
+	return {
+		agent: ctx.agent.name,
+		execution: {
+			provider: "eve",
+			sessionId: ctx.session.id
+		},
+		attributes: ctx.session.auth.initiator?.attributes ?? {}
+	};
+}
+/** Observe-only hook for agents that do not use the Factory task-lifecycle hook. */
+function createTranscriptSnapshotHook(materialize) {
+	const snapshot = (_event, ctx) => materialize(materializationInput(ctx)).catch(() => void 0);
+	return defineHook({ events: {
+		"session.waiting": snapshot,
+		"session.completed": snapshot,
+		"session.failed": snapshot
+	} });
+}
 const terminalTaskStates = /* @__PURE__ */ new Set([
 	"succeeded",
 	"failed",
 	"cancelled"
 ]);
 /**
+* The turn contract's escalation question: a specialist turn ended cleanly
+* (eve durably recorded `turn.completed`) but the bound task is still
+* `running`, so no transition was recorded. That is never a "worker died
+* mid-turn" situation -- eve confirms the turn finished -- so retrying the
+* identical brief cannot succeed any differently. Escalating straight to
+* `needs_human` instead of waiting for the stall window (up to 45 minutes,
+* times `maxAttempts`) surfaces the dead end immediately. "Close the task"
+* is a declared closingOptions entry: answering with it resolves the task
+* instead of requeuing an identical retry.
+*/
+const UNRESOLVED_TURN_QUESTION = {
+	text: "The specialist ended its turn without recording a result for this task. Reply to retry it, or close it if the work no longer applies (for example, a newer attempt already superseded it).",
+	options: ["Retry the task", "Close the task"],
+	closingOptions: ["Close the task"]
+};
+/**
 * Observe-only eve hooks that keep the ledger honest about session outcomes.
 * Mount by re-exporting from agent/hooks/, e.g.
-* `export default factoryHooks(stores, { presentQuestion }).factory;`.
+* `export default createFactoryHooks(stores, { presentQuestion }).factory;`.
 *
 * step.completed: records the step's tokens and AI Gateway cost on the bound
 * task. Delivery is at least once; recordUsage dedupes by (turnId, stepIndex).
 *
+* turn.failed/session.failed: immediately re-queues the current attempt, or
+* fails it when its configured attempts are exhausted. turn.cancelled marks
+* the current Task cancelled. Late events from prior attempts are ignored.
+*
 * turn.completed: settles the bound task's recorded usage if the task is
-* already terminal (the sweep handles tasks that end later), then moves any
-* still-running task at this session's reply address behind a surfaced human
-* question, because the agent finished talking without recording an outcome.
+* already terminal, and enforces the turn contract otherwise: a still-running
+* bound task (or a still-running task at this session's reply address, for
+* conversational continuations that never got their own bound session)
+* escalates immediately to a surfaced human question instead of waiting out
+* the stall window, because the agent finished without recording an outcome.
 *
 * Every store call is swallowed: a hook throw fails the turn.
+* Transcript projection writes at session response boundaries are likewise
+* best-effort; the API can rebuild a missing projection from durable events.
 */
-function factoryHooks(stores, options) {
+function createFactoryHooks(stores, options) {
 	const taskIdAttribute = options.taskIdAttribute ?? "factoryTaskId";
+	const taskAttemptAttribute = options.taskAttemptAttribute ?? "factoryTaskAttempt";
+	const maxAttempts = z.number().int().min(1).parse(options.maxAttempts ?? 3);
 	function boundTaskId(ctx) {
 		const parsed = taskIdSchema.safeParse(ctx.session.auth.initiator?.attributes[taskIdAttribute]);
 		return parsed.success ? parsed.data : void 0;
 	}
+	function boundExecution(ctx) {
+		const attributes = ctx.session.auth.initiator?.attributes;
+		const taskId = boundTaskId(ctx);
+		const attempt = z.coerce.number().int().min(1).safeParse(attributes?.[taskAttemptAttribute]);
+		return taskId !== void 0 && attempt.success ? {
+			taskId,
+			attempt: attempt.data
+		} : void 0;
+	}
+	async function recoverFailedAttempt(binding, failure) {
+		const task = await stores.tasks.get(binding.taskId);
+		if (task?.state !== "running" || task.attempt !== binding.attempt) return;
+		const exhausted = task.attempt >= maxAttempts;
+		await stores.tasks.transition(task.id, exhausted ? "failed" : "queued", {
+			expectFrom: "running",
+			expectAttempt: binding.attempt,
+			phase: "retry",
+			reason: exhausted ? `${failure} on attempt ${task.attempt} of ${maxAttempts}; attempts exhausted` : `${failure} on attempt ${task.attempt} of ${maxAttempts}; replacement queued`
+		});
+	}
+	async function cancelAttempt(binding, reason) {
+		const task = await stores.tasks.get(binding.taskId);
+		if (task?.state !== "running" || task.attempt !== binding.attempt) return;
+		await stores.tasks.transition(task.id, "cancelled", {
+			expectFrom: "running",
+			expectAttempt: binding.attempt,
+			phase: "execution",
+			reason
+		});
+	}
+	async function isConversation(task) {
+		try {
+			return await options.isConversation?.(task) ?? false;
+		} catch {
+			return false;
+		}
+	}
 	async function settleIfTerminal(taskId) {
 		const task = await stores.tasks.get(taskId);
 		if (task?.usage === void 0 || task.settledUsd !== void 0 || !terminalTaskStates.has(task.state)) return;
-		await stores.tasks.settle(task.id, { totalUsd: task.usage.costUsd }, { reason: "measured usage settled at turn end" });
+		await stores.tasks.settle(task.id, {
+			cost: { totalUsd: task.usage.costUsd },
+			reason: "measured usage settled at turn end"
+		});
+	}
+	async function escalateUnresolvedTurn(task) {
+		await createAndPresentQuestion(stores, task, UNRESOLVED_TURN_QUESTION, options.presentQuestion).catch(() => void 0);
 	}
 	return { factory: defineHook({ events: {
 		async "step.completed"(event, ctx) {
 			const taskId = boundTaskId(ctx);
 			const usage = event.data.usage;
 			if (taskId === void 0 || usage === void 0) return;
-			await stores.tasks.recordUsage(taskId, {
+			const binding = boundExecution(ctx);
+			if (binding !== void 0) {
+				if ((await stores.tasks.get(taskId).catch(() => null))?.attempt !== binding.attempt) return;
+			}
+			await stores.tasks.recordUsage(taskId, { step: {
 				turnId: event.data.turnId,
 				stepIndex: event.data.stepIndex,
 				...usage
-			}).catch(() => void 0);
+			} }).catch(() => void 0);
+		},
+		async "turn.failed"(event, ctx) {
+			const binding = boundExecution(ctx);
+			if (binding !== void 0) {
+				await recoverFailedAttempt(binding, `provider turn failed (${event.data.code}): ${event.data.message}`).catch(() => void 0);
+				return;
+			}
+			const taskId = boundTaskId(ctx);
+			const task = taskId ? await stores.tasks.get(taskId).catch(() => null) : null;
+			if (task?.state === "running" && await isConversation(task)) {
+				await stores.tasks.transition(task.id, "failed", {
+					expectFrom: "running",
+					reason: "Conversation turn failed"
+				}).catch(() => void 0);
+				await settleIfTerminal(task.id).catch(() => void 0);
+			}
+		},
+		async "session.failed"(event, ctx) {
+			const binding = boundExecution(ctx);
+			if (binding !== void 0) await recoverFailedAttempt(binding, `provider session failed (${event.data.code}): ${event.data.message}`).catch(() => void 0);
+			await options.materializeTranscript?.(materializationInput(ctx)).catch(() => void 0);
+		},
+		async "session.waiting"(_event, ctx) {
+			await options.materializeTranscript?.(materializationInput(ctx)).catch(() => void 0);
+		},
+		async "session.completed"(_event, ctx) {
+			await options.materializeTranscript?.(materializationInput(ctx)).catch(() => void 0);
+		},
+		async "turn.cancelled"(_event, ctx) {
+			const binding = boundExecution(ctx);
+			if (binding !== void 0) {
+				await cancelAttempt(binding, `provider turn cancelled on attempt ${binding.attempt}`).catch(() => void 0);
+				return;
+			}
+			const taskId = boundTaskId(ctx);
+			const task = taskId ? await stores.tasks.get(taskId).catch(() => null) : null;
+			if (task && await isConversation(task)) {
+				if (task.state === "running") await stores.tasks.transition(task.id, "cancelled", {
+					expectFrom: "running",
+					reason: "Conversation turn interrupted"
+				}).catch(() => void 0);
+				await settleIfTerminal(task.id).catch(() => void 0);
+			}
 		},
 		async "turn.completed"(_event, ctx) {
 			const taskId = boundTaskId(ctx);
-			if (taskId !== void 0) await settleIfTerminal(taskId).catch(() => void 0);
+			const binding = boundExecution(ctx);
+			if (taskId !== void 0) {
+				const task = await stores.tasks.get(taskId).catch(() => null);
+				if (binding !== void 0 && task?.attempt !== binding.attempt) return;
+				if (task?.state === "running" && !task.waitingForMessages) {
+					const completion = await options.completeConversation?.(task).catch(() => false);
+					if (completion) await stores.tasks.transition(taskId, "succeeded", {
+						expectFrom: "running",
+						expectAttempt: task.attempt,
+						reason: "Conversation turn completed",
+						output: completion.output
+					}).catch(() => void 0);
+					else await escalateUnresolvedTurn(task);
+				}
+				await settleIfTerminal(taskId).catch(() => void 0);
+			}
 			const address = ctx.channel.continuationToken;
 			if (address === void 0) return;
-			const abandoned = (await stores.tasks.list().catch(() => [])).filter((task) => task.state === "running" && task.replyTo.address === address);
-			for (const task of abandoned) await createAndPresentQuestion(stores, task, {
-				text: "The worker stopped without recording an outcome. Please review the task and reply when Factory should retry it.",
-				options: ["Retry the task"]
-			}, options.presentQuestion).catch(() => void 0);
+			const abandoned = (await stores.tasks.list().catch(() => [])).filter((task) => task.id !== taskId && task.state === "running" && !task.waitingForMessages && task.replyTo.address === address);
+			for (const task of abandoned) await escalateUnresolvedTurn(task);
 		}
 	} }) };
 }
 //#endregion
-export { deepsecScanTool, delegateAgentTool, factoryHooks, factoryTools, fetchPullRequestTool, findingFromDeepsec, invokeAgentTool, mergeConflictPayloadSchema, mergeConflictTools, postReviewTool, recordFinding, recordFindingTool, recordVerificationTool, reviewCommentTools };
+export { cancelEveSession, conversationBinding, conversationBindingForSession, conversationHeaders, createDelegateAgentTool, createEveTranscriptMaterializer, createFactoryHooks, createInvokeAgentTool, createTaskTools, createTranscriptSnapshotHook, factoryReplyAddressAttribute, factoryReplyAddressHeader, factoryReplyChannelAttribute, factoryReplyChannelHeader, factoryRepositoryIdsAttribute, factoryRepositoryIdsHeader, factoryTaskAttemptAttribute, factoryTaskAttemptHeader, factoryTaskAttribute, factoryTaskHeader, forwardEveSessionRequest, hasFactoryTaskBinding, optionalTaskIdForSession, readCompletedEveTurn, replyToForSession, repositoryIdsForSession, requireTaskIdForSession, startEveSession, taskBindingForSession, taskHeaders, taskSessionAuth, withFactoryTask, withOptionalFactoryTask };
 
 //# sourceMappingURL=index.mjs.map