@tea-agent/loop-agent 0.24.11-beta.0 → 0.25.1

package/dist/worker/observe/static/styles.css

@@ -2010,6 +2010,80 @@ body.is-resizing-dag-graph {
 .spec-evidence-section { padding-bottom: var(--space-4); border-bottom: 1px solid var(--hairline); }
 .spec-evidence-section + .spec-evidence-section { margin-top: var(--space-4); }
 .spec-evidence-section h4 { margin: 0 0 var(--space-2); color: var(--ink); font-size: 12px; font-weight: 700; }
+
+.node-input-root { display: flex; flex-direction: column; gap: var(--space-3); }
+.node-input-semantics {
+	margin: 0;
+	font-size: 12px;
+	font-weight: 600;
+	color: var(--muted);
+}
+.node-input-section {
+	padding-bottom: var(--space-3);
+	border-bottom: 1px solid var(--hairline);
+}
+.node-input-section h4 {
+	margin: 0 0 var(--space-2);
+	color: var(--ink);
+	font-size: 12px;
+	font-weight: 700;
+}
+.node-input-section h5 {
+	margin: var(--space-2) 0;
+	font-size: 12px;
+	font-weight: 600;
+}
+.node-input-summary {
+	display: grid;
+	grid-template-columns: max-content 1fr;
+	gap: 4px 12px;
+	margin: 0;
+	font-size: 12px;
+}
+.node-input-summary dt {
+	margin: 0;
+	color: var(--muted);
+	font-weight: 600;
+}
+.node-input-summary dd {
+	margin: 0;
+	color: var(--ink);
+	word-break: break-word;
+}
+.node-input-inherited {
+	display: inline-block;
+	margin-left: 4px;
+	padding: 0 6px;
+	border-radius: 999px;
+	background: var(--surface-2, #f3f1ec);
+	color: var(--muted);
+	font-size: 11px;
+	font-weight: 600;
+}
+.node-input-code-list,
+.node-input-command-list {
+	margin: var(--space-2) 0 0;
+	padding-left: 1.2rem;
+}
+.node-input-command-list pre {
+	margin: 4px 0;
+	padding: 8px;
+	overflow: auto;
+	background: var(--surface-2, #f3f1ec);
+	border-radius: 6px;
+	font-size: 12px;
+}
+.node-input-truncated,
+.node-input-warning {
+	margin: var(--space-2) 0 0;
+	font-size: 12px;
+	color: var(--muted);
+}
+.node-input-error {
+	margin: 0;
+	color: var(--danger, #b42318);
+	font-size: 13px;
+}
 .spec-evidence-summary { margin: var(--space-2) 0 0; color: var(--body); font-size: 12px; line-height: 1.6; }
 .spec-evidence-list { display: grid; gap: 6px; margin: var(--space-2) 0 0; padding: 0; list-style: none; }
 .spec-evidence-list li { display: flex; align-items: flex-start; gap: 6px; color: var(--body); font-size: 12px; line-height: 1.5; overflow-wrap: anywhere; }

package/dist/worker/observe/static/views/dag-inspector.js

@@ -10,12 +10,13 @@ import {
 	UI_TEXT,
 } from "../constants.js";
 import { clearNode, el } from "../dom.js";
-import { fetchJson, fetchSpecEvidenceFile } from "../api.js";
+import { fetchJson, fetchSpecEvidenceFile, fetchDagNodeInput } from "../api.js";
 import { badge } from "../format.js";
 import { renderMarkdown } from "../markdown-render.js";
 import {
 	uiState,
 	makeSessionEventIdentity,
+	makeDagNodeInputIdentity,
 	openSpecEvidenceDetail,
 	closeSpecEvidenceDetail,
 	updateDagTimelineViewportState,
@@ -50,9 +51,13 @@ export function selectDagNode(dagRunId, nodeId) {
 		// into node B's spec-evidence panel (AC-007 regression guard).
 		uiState.specEvidenceDetail = null;
 		uiState.specEvidenceListEvidence = null;
+		uiState.dagNodeInputData = null;
+		uiState.dagNodeInputError = null;
+		uiState.dagNodeInputLoading = false;
 		// Bump the session-event identity token so any in-flight response for the
 		// previous node is rejected before it can mutate the current node cache.
 		uiState.sessionEventIdentity = makeSessionEventIdentity(dagRunId, nodeId);
+		uiState.dagNodeInputIdentity = makeDagNodeInputIdentity(dagRunId, nodeId);
 	}
 	void import("./dag.js").then((m) => m.renderDagDetail(dagRunId, false));
 }
@@ -530,16 +535,337 @@ function renderSpecEvidenceDetail(content, dagRunId, nodeId) {
 	content.appendChild(wrapper);
 }
 
+function sourceLabel(source) {
+	if (source === "defaults") return "继承默认值";
+	if (source === "schema-default") return "schema 默认";
+	if (source === "merged") return "合并";
+	return null;
+}
+
+function appendMetaRow(dl, label, value, source) {
+	if (value == null || value === "") return;
+	const dt = el("dt", null, label);
+	const dd = el("dd", null, String(value));
+	const inherited = sourceLabel(source);
+	if (inherited) {
+		dd.appendChild(document.createTextNode(" "));
+		dd.appendChild(el("span", "node-input-inherited", inherited));
+	}
+	dl.appendChild(dt);
+	dl.appendChild(dd);
+}
+
+function appendCodeList(parent, title, values) {
+	if (!values || values.length === 0) return;
+	const section = el("section", "node-input-section");
+	section.appendChild(el("h4", null, title));
+	const list = el("ul", "node-input-code-list");
+	for (const value of values) {
+		const item = document.createElement("li");
+		const code = document.createElement("code");
+		code.textContent = String(value);
+		item.appendChild(code);
+		list.appendChild(item);
+	}
+	section.appendChild(list);
+	parent.appendChild(section);
+}
+
+function renderDagNodeInputDetail(content, data) {
+	const wrap = el("div", "node-input-root");
+	wrap.appendChild(
+		el("p", "node-input-semantics", UI_TEXT.inputFrozenLabel),
+	);
+
+	if (data.summary) {
+		const section = el("section", "node-input-section");
+		section.appendChild(el("h4", null, "摘要"));
+		const dl = el("dl", "node-input-summary");
+		appendMetaRow(
+			dl,
+			"executor",
+			data.summary.executor,
+			data.summary.executorSource,
+		);
+		appendMetaRow(dl, "role", data.summary.role, null);
+		appendMetaRow(dl, "complexity", data.summary.complexity, null);
+		appendMetaRow(
+			dl,
+			"writePolicy",
+			data.summary.writePolicy,
+			data.summary.writePolicySource,
+		);
+		appendMetaRow(dl, "toolProfile", data.summary.toolProfile, null);
+		section.appendChild(dl);
+		wrap.appendChild(section);
+	}
+
+	if (data.dependency) {
+		const section = el("section", "node-input-section");
+		section.appendChild(el("h4", null, "依赖"));
+		const dl = el("dl", "node-input-summary");
+		appendMetaRow(
+			dl,
+			"depends_on",
+			(data.dependency.dependsOn ?? []).join(", ") || "(none)",
+			null,
+		);
+		if (data.dependency.dependsPolicy) {
+			appendMetaRow(dl, "dependsPolicy", data.dependency.dependsPolicy, null);
+		}
+		if ((data.dependency.failureAwareDependsOn ?? []).length > 0) {
+			appendMetaRow(
+				dl,
+				"failureAwareDependsOn",
+				data.dependency.failureAwareDependsOn.join(", "),
+				null,
+			);
+		}
+		if (data.dependency.runIf) {
+			appendMetaRow(dl, "runIf", data.dependency.runIf, null);
+		}
+		section.appendChild(dl);
+		wrap.appendChild(section);
+	}
+
+	if (data.prompt) {
+		const section = el("section", "node-input-section");
+		section.appendChild(el("h4", null, "任务正文"));
+		if (data.prompt.source?.path) {
+			const meta = el("p", "muted");
+			meta.textContent = `source: ${data.prompt.source.path}${
+				data.prompt.source.sha256Prefix
+					? ` (sha256 ${data.prompt.source.sha256Prefix}…)`
+					: ""
+			}`;
+			section.appendChild(meta);
+		}
+		section.appendChild(renderMarkdown(data.prompt.text ?? ""));
+		if (data.prompt.truncated) {
+			section.appendChild(
+				el(
+					"p",
+					"node-input-truncated",
+					`已截断，仅显示前 ${data.prompt.maxBytes ?? 0} 字节（UTF-8）。`,
+				),
+			);
+		}
+		wrap.appendChild(section);
+	}
+
+	if (data.executorInput) {
+		const section = el("section", "node-input-section");
+		section.appendChild(el("h4", null, "执行器输入摘要"));
+		const dl = el("dl", "node-input-summary");
+		appendMetaRow(dl, "kind", data.executorInput.kind, null);
+		if (data.executorInput.modelHint) {
+			appendMetaRow(dl, "modelHint", data.executorInput.modelHint, null);
+		}
+		section.appendChild(dl);
+		appendCodeList(section, "skills", data.executorInput.skills);
+		if (data.executorInput.shell) {
+			const shell = data.executorInput.shell;
+			const shellDl = el("dl", "node-input-summary");
+			appendMetaRow(shellDl, "preset", shell.preset, null);
+			appendMetaRow(shellDl, "cwd", shell.cwd, null);
+			appendMetaRow(shellDl, "timeoutMs", shell.timeoutMs, null);
+			appendMetaRow(
+				shellDl,
+				"nonZeroExitPolicy",
+				shell.nonZeroExitPolicy,
+				null,
+			);
+			appendMetaRow(
+				shellDl,
+				"gates",
+				(shell.gates ?? []).join(", ") || "(none)",
+				null,
+			);
+			section.appendChild(shellDl);
+			if ((shell.commands ?? []).length > 0) {
+				const list = el("ol", "node-input-command-list");
+				for (const command of shell.commands) {
+					const item = document.createElement("li");
+					const pre = document.createElement("pre");
+					const code = document.createElement("code");
+					code.textContent = String(command);
+					pre.appendChild(code);
+					item.appendChild(pre);
+					list.appendChild(item);
+				}
+				section.appendChild(list);
+			}
+		}
+		if (data.executorInput.static) {
+			const staticBlock = data.executorInput.static;
+			const staticDl = el("dl", "node-input-summary");
+			appendMetaRow(staticDl, "status", staticBlock.status, null);
+			section.appendChild(staticDl);
+			section.appendChild(renderMarkdown(staticBlock.resultPreview ?? ""));
+			if (staticBlock.truncated) {
+				section.appendChild(
+					el(
+						"p",
+						"node-input-truncated",
+						`已截断，仅显示前 ${staticBlock.maxBytes ?? 0} 字节（UTF-8）。`,
+					),
+				);
+			}
+		}
+		wrap.appendChild(section);
+	}
+
+	if (data.boundaries) {
+		const section = el("section", "node-input-section");
+		section.appendChild(el("h4", null, "边界与输出契约"));
+		const dl = el("dl", "node-input-summary");
+		appendMetaRow(dl, "outputMode", data.boundaries.outputMode, null);
+		appendMetaRow(
+			dl,
+			"firstProtocolLine",
+			data.boundaries.firstProtocolLine,
+			null,
+		);
+		section.appendChild(dl);
+		if (data.boundaries.outputContract) {
+			section.appendChild(el("h5", null, "outputContract"));
+			section.appendChild(renderMarkdown(data.boundaries.outputContract));
+		}
+		appendCodeList(section, "allowedPaths", data.boundaries.allowedPaths);
+		appendCodeList(section, "forbiddenPaths", data.boundaries.forbiddenPaths);
+		appendCodeList(section, "writeSet", data.boundaries.writeSet);
+		wrap.appendChild(section);
+	}
+
+	if (data.promptFingerprint?.exists) {
+		const section = el("section", "node-input-section");
+		section.appendChild(el("h4", null, "Assembled prompt 指纹"));
+		const dl = el("dl", "node-input-summary");
+		appendMetaRow(
+			dl,
+			"sha256",
+			data.promptFingerprint.sha256Prefix ?? "(parse failed)",
+			null,
+		);
+		appendMetaRow(
+			dl,
+			"lengthChars",
+			data.promptFingerprint.lengthChars,
+			null,
+		);
+		appendMetaRow(dl, "artifact", data.promptFingerprint.artifact, null);
+		section.appendChild(dl);
+		section.appendChild(
+			el("p", "muted", UI_TEXT.inputFingerprintNote),
+		);
+		wrap.appendChild(section);
+	}
+
+	if ((data.warnings ?? []).length > 0) {
+		const section = el("section", "node-input-section");
+		section.appendChild(el("h4", null, "警告"));
+		for (const warning of data.warnings) {
+			section.appendChild(el("p", "node-input-warning", String(warning)));
+		}
+		wrap.appendChild(section);
+	}
+
+	content.appendChild(wrap);
+}
+
+function unavailableMessage(reason) {
+	if (reason === "unsupported-dynamic-node") {
+		return UI_TEXT.inputDynamicUnsupported;
+	}
+	if (reason === "run-spec-unavailable") {
+		return UI_TEXT.inputRunSpecUnavailable;
+	}
+	if (reason === "task-not-found") {
+		return UI_TEXT.inputUnavailable;
+	}
+	return UI_TEXT.noInput;
+}
+
+async function renderDagNodeInput(content, dagRunId, node) {
+	const nodeId = node.nodeId;
+	const identity = makeDagNodeInputIdentity(dagRunId, nodeId);
+	uiState.dagNodeInputIdentity = identity;
+	uiState.dagNodeInputLoading = true;
+	uiState.dagNodeInputError = null;
+
+	clearNode(content);
+	const loading = el("p", "muted", UI_TEXT.inputLoading);
+	loading.setAttribute("role", "status");
+	loading.setAttribute("aria-live", "polite");
+	content.appendChild(loading);
+
+	const result = await fetchDagNodeInput(dagRunId, nodeId);
+	if (
+		uiState.dagNodeInputIdentity !== identity ||
+		uiState.selectedDagNodeId !== nodeId ||
+		uiState.currentDagRunId !== dagRunId ||
+		uiState.dagInspectorTab !== "input" ||
+		!content.isConnected ||
+		content.dataset.dagNodeId !== String(nodeId) ||
+		content.dataset.dagRunId !== String(dagRunId)
+	) {
+		return;
+	}
+
+	uiState.dagNodeInputLoading = false;
+	clearNode(content);
+
+	if (!result.ok) {
+		const message =
+			result.body?.error ||
+			(result.status === 0
+				? UI_TEXT.inputError
+				: `${UI_TEXT.inputError}（HTTP ${result.status}）`);
+		uiState.dagNodeInputError = message;
+		uiState.dagNodeInputData = null;
+		const error = el("p", "node-input-error", message);
+		error.setAttribute("role", "alert");
+		content.appendChild(error);
+		return;
+	}
+
+	const data = result.body;
+	uiState.dagNodeInputData = data;
+	uiState.dagNodeInputError = null;
+	if (!data?.available) {
+		const empty = el(
+			"p",
+			"empty",
+			unavailableMessage(data?.availabilityReason),
+		);
+		empty.setAttribute("role", "status");
+		content.appendChild(empty);
+		if ((data?.warnings ?? []).length > 0) {
+			for (const warning of data.warnings) {
+				content.appendChild(el("p", "node-input-warning", String(warning)));
+			}
+		}
+		return;
+	}
+
+	renderDagNodeInputDetail(content, data);
+}
+
 	function fillDagInspectorContent(content, dagRunId, node) {
 		const previousRenderedNode = content.dataset.dagNodeId ?? "";
-		const nodeChanged = previousRenderedNode !== String(node.nodeId ?? "");
+		const previousRenderedRun = content.dataset.dagRunId ?? "";
+		const nodeChanged =
+			previousRenderedNode !== String(node.nodeId ?? "") ||
+			previousRenderedRun !== String(dagRunId ?? "");
 		if (nodeChanged) {
 			// Drop any open spec-evidence preview + cached list so a stale A detail
 			// cannot survive into node B (AC-007 regression guard).
 			uiState.specEvidenceDetail = null;
 			uiState.specEvidenceListEvidence = null;
+			uiState.dagNodeInputData = null;
+			uiState.dagNodeInputError = null;
 		}
-		const activeTab = ["timeline", "spec-evidence"].includes(
+		const activeTab = ["input", "timeline", "spec-evidence"].includes(
 			uiState.dagInspectorTab,
 		)
 			? uiState.dagInspectorTab
@@ -548,12 +874,15 @@ function renderSpecEvidenceDetail(content, dagRunId, nodeId) {
 		content.setAttribute("role", "tabpanel");
 		content.setAttribute("aria-labelledby", `dag-inspector-tab-${activeTab}`);
 		content.dataset.dagNodeId = String(node.nodeId ?? "");
+		content.dataset.dagRunId = String(dagRunId ?? "");
 		// Drop timeline-only classes when switching tabs so output layout stays clean.
 		content.className = "dag-inspector-content";
 		if (activeTab === "spec-evidence") {
 			void renderSpecEvidence(content, dagRunId, node.nodeId);
 		} else if (activeTab === "timeline") {
 			renderSessionTimeline(content, node.nodeId);
+		} else if (activeTab === "input") {
+			void renderDagNodeInput(content, dagRunId, node);
 		} else if (!node.outputPreview && !node.errorPreview) {
 			content.appendChild(el("p", "empty", UI_TEXT.noOutput));
 		} else {
@@ -592,6 +921,7 @@ function buildDagInspectorHeader(dagRunId, node) {
 	header.appendChild(controls);
 
 	const tabDefs = [
+		["input", "节点输入", "ri-login-box-line"],
 		["output", "节点输出", "ri-file-text-line"],
 		["timeline", "执行过程", "ri-route-line"],
 		["spec-evidence", "规范证据", "ri-book-open-line"],
@@ -660,6 +990,17 @@ function syncDagInspectorHeader(panel, dagRunId, node) {
 }
 
 function dagInspectorSignature(dagRunId, node) {
+	const inputRevision =
+		uiState.dagInspectorTab === "input"
+			? [
+					uiState.dagNodeInputIdentity,
+					uiState.dagNodeInputLoading,
+					uiState.dagNodeInputError ?? "",
+					uiState.dagNodeInputData?.availabilityReason ?? "",
+					uiState.dagNodeInputData?.promptFingerprint?.sha256Prefix ?? "",
+					node.status ?? "",
+				]
+			: null;
 	return JSON.stringify([
 		dagRunId,
 		node.nodeId,
@@ -667,6 +1008,7 @@ function dagInspectorSignature(dagRunId, node) {
 		node.outputPreview ?? "",
 		node.errorPreview ?? "",
 		uiState.dagInspectorTab === "timeline" ? uiState.sessionEventOffset : null,
+		inputRevision,
 	]);
 }
 
@@ -702,17 +1044,30 @@ export function renderDagInspector(dagRunId, node, initial = true) {
 		syncDagInspectorHeader(panel, dagRunId, node);
 		if (panel.dataset.contentSignature === nextContentSignature) return;
 		const previousNode = existingContent.dataset.dagNodeId ?? "";
-		const nodeChanged = previousNode !== String(node.nodeId ?? "");
-		const followLatest =
-			nodeChanged ||
-			computeFollowLatest(
-				existingContent.scrollTop,
-				existingContent.scrollHeight,
-				existingContent.clientHeight,
-			);
-		const regionKey = `dag:${dagRunId}:${node.nodeId}:output`;
-		uiState.dagNodeOutputViewportState = updateDagOutputViewportState(
-			uiState.dagNodeOutputViewportState,
+		const previousRun = existingContent.dataset.dagRunId ?? "";
+		const nodeChanged =
+			previousNode !== String(node.nodeId ?? "") ||
+			previousRun !== String(dagRunId ?? "");
+		const activeTab = ["input", "timeline", "spec-evidence"].includes(
+			uiState.dagInspectorTab,
+		)
+			? uiState.dagInspectorTab
+			: "output";
+		const isInputTab = activeTab === "input";
+		const followLatest = isInputTab
+			? false
+			: nodeChanged ||
+				computeFollowLatest(
+					existingContent.scrollTop,
+					existingContent.scrollHeight,
+					existingContent.clientHeight,
+				);
+		const regionKey = `dag:${dagRunId}:${node.nodeId}:${isInputTab ? "input" : "output"}`;
+		const viewportUpdater = isInputTab
+			? "dagNodeInputViewportState"
+			: "dagNodeOutputViewportState";
+		uiState[viewportUpdater] = updateDagOutputViewportState(
+			uiState[viewportUpdater],
 			regionKey,
 			existingContent.scrollLeft,
 			existingContent.scrollTop,
@@ -729,7 +1084,8 @@ export function renderDagInspector(dagRunId, node, initial = true) {
 		if (followLatest) {
 			existingContent.scrollTop = existingContent.scrollHeight;
 		} else {
-			existingContent.scrollTop = uiState.dagNodeOutputViewportState.scrollTop;
+			const saved = uiState[viewportUpdater];
+			existingContent.scrollTop = nodeChanged ? 0 : (saved?.scrollTop ?? 0);
 		}
 		for (const [index, pre] of [
 			...existingContent.querySelectorAll("pre"),

package/dist/worker/outcomes/projector.js

@@ -111,8 +111,12 @@ export async function projectOutcome(input) {
         if (artifact.sha256 && artifact.sha256 !== recomputed) {
             return contractError(`artifact sha256 mismatch for ${artifact.path}: declared=${artifact.sha256} actual=${recomputed}`);
         }
+        // Persist portable repo-relative paths only (Delivery verifyArtifactRefs rejects abs paths).
+        const relativePath = path
+            .relative(path.resolve(input.repoRoot), resolved)
+            .replace(/\\/g, "/");
         validatedArtifacts.push({
-            path: artifact.path.replace(/\\/g, "/"),
+            path: relativePath,
             sha256: recomputed,
             ...(artifact.kind ? { kind: artifact.kind } : {}),
             ...(artifact.schemaId ? { schemaId: artifact.schemaId } : {}),

package/dist/worker/run-task/run-task.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { writeTextAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { getTaskPaths } from "../../task/runtime.js";
 import { formatDuration, noopProgressReporter } from "../progress-reporter.js";
 import { redactForPreview, truncatePreview } from "../observability/events.js";
 import { controllerIdentityExpectationFailure, resolveControllerIdentity, } from "../loop-agent/loop-agent-client.js";
@@ -104,6 +106,13 @@ export async function runTaskSpec(options) {
         ], true, undefined, eventCtx);
     });
     progress.step(`dag validated in ${formatDuration(Date.now() - validateStartedAt)}`);
+    const canonicalDraftPath = getTaskPaths(options.repoRoot, materializeManifest.harnessTaskId).dagDraftPath;
+    await runObservedStep(eventCtx, "publish-canonical-dag-draft", async () => {
+        const dagBytes = await readFile(dagPath, "utf-8");
+        await writeTextAtomic(canonicalDraftPath, dagBytes, {
+            repoRoot: options.repoRoot,
+        });
+    });
     const runDagStep = "run-dag";
     const runDagStartedAt = Date.now();
     const dagEventsPath = path.join(getTaskPoolRoot(options.repoRoot), "observability", "runs", workerRunId, "dag-events.jsonl");
@@ -330,7 +339,7 @@ export function buildWorkerRunId(businessId, now) {
         .slice(0, 6);
     return `wr-${date}-${businessId}-${hash}`;
 }
-async function runRequiredCommand(repoRoot, client, artifactName, args, expectJson = true, timeoutMs, eventCtx) {
+async function runRequiredCommand(repoRoot, client, artifactName, args, expectJson = true, timeoutMs, _eventCtx) {
     const result = await client.run(args, {
         cwd: repoRoot,
         artifactName,
@@ -743,7 +752,14 @@ function strictModelsArgs(piModel) {
  */
 export async function applyPiModelOverride(dagPath, piModel) {
     const raw = await readFile(dagPath, "utf-8");
-    const spec = JSON.parse(raw);
+    let spec;
+    try {
+        spec = JSON.parse(raw);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new Error(`invalid generated DAG JSON at ${dagPath}: ${message}`);
+    }
     spec.executorModels = {
         pi: {
             LOW: piModel,

package/dist/worker/runner/run-ready.js

@@ -304,11 +304,51 @@ export async function runReadyTasks(options) {
             if (result.status !== "succeeded") {
                 await options.onTaskFinalized?.({ status: result.status, taskSpec, workerRunId: result.workerRunId, runRecordPath: result.runRecordPath });
             }
+            const recordErrorMessage = errorMessage(error);
+            // Always project a Pool run fact for record-error so operators can
+            // mark-failed / retry without hand-editing Running state.
+            try {
+                await recordTaskPoolRun({
+                    repoRoot: options.repoRoot,
+                    run: {
+                        schemaVersion: 1,
+                        batchRunId,
+                        workerRunId: result.workerRunId,
+                        taskId: result.businessId,
+                        featureId: taskSpec.feature_id,
+                        status: "run-error",
+                        recordedAt: new Date().toISOString(),
+                        error: recordErrorMessage,
+                        runRecordPath: result.runRecordPath,
+                        ...(result.workflow ? { workflow: result.workflow } : {}),
+                        ...(controllerIdentity ? { controllerIdentity } : {}),
+                        ...(retryOfWorkerRunId ? { retryOfWorkerRunId } : {}),
+                    },
+                });
+                await writeTaskPoolState(options.repoRoot, {
+                    schemaVersion: 2,
+                    featureId: taskSpec.feature_id,
+                    taskId,
+                    status: "Failed",
+                    updatedAt: new Date().toISOString(),
+                    workerRunId: result.workerRunId,
+                    lastRunRecordPath: result.runRecordPath,
+                    failure: {
+                        category: "EnvFailure",
+                        recommendedFollowUpKind: "manual-review",
+                        derivedFollowUpTaskId: `${taskId}-record-error-review`,
+                        source: "report-decision",
+                    },
+                });
+            }
+            catch {
+                // Best-effort; batch still reports record-error.
+            }
             tasks.push({
                 taskId,
                 workerRunId: result.workerRunId,
                 status: "record-error",
-                error: errorMessage(error),
+                error: recordErrorMessage,
                 runRecordPath: result.runRecordPath,
             });
             break;