@tea-agent/loop-agent 0.43.0-next.1 → 0.43.0-next.11

package/dist/worker/observe/static/views/task.js

@@ -1,3 +1,5 @@
+import { inspectRouteStates } from "../state.js";
+import { mergeTaskHistoryPage } from "../task-history.js";
 /** Observe UI view module (R5). */
 import {
 	UI_TEXT,
@@ -16,7 +18,7 @@ import {
 	DAG_EFFECTIVE_STATUS_LABELS,
 	STATUS_LABELS,
 } from "../constants.js";
-import { clearNode, el, metaGrid, buildTable } from "../dom.js";
+import { clearNode, el, metaGrid, buildTable, reconcileKeyed } from "../dom.js";
 import {
 	badge,
 	badgeClass,
@@ -45,6 +47,7 @@ import {
 import {
 	fetchJson,
 	fetchJsonResult,
+	summarizeFetchError,
 	artifactUrl,
 	parseArtifactPreviewResponse,
 } from "../api.js";
@@ -66,7 +69,7 @@ import {
 	renderViewState,
 	mountViewState,
 } from "../state.js";
-import { uiState } from "../state.js";
+import { uiState, taskHistoryStates, workspaceScope } from "../state.js";
 import { sortPoolTasks } from "../format-pool.js";
 import {
 	dagMetaVisibility,
@@ -75,7 +78,7 @@ import {
 	findDagForRun,
 } from "../dag-model.js";
 import { layoutDag } from "../dag-layout.js";
-import { showView, setBreadcrumb, updateHeaderRefresh, mountRelationBar } from "../shell-chrome.js";
+import { showView, setBreadcrumb, updateHeaderRefresh, mountRelationBar, bindManualViewRefresh } from "../shell-chrome.js";
 import { artifactLink } from "../kpi.js";
 import { findBatchRunIdForTask, taskRunHistoryRow } from "../run-processing.js";
 
@@ -91,7 +94,7 @@ export async function renderTaskDetail(featureId, taskId) {
 	showView("task");
 	setBreadcrumb([
 		{ label: UI_TEXT.dashboard, href: "#/" },
-		{ label: "资源池", href: "/#/inspect/pool" },
+		{ label: "资源池", href: inspectRouteStates.get("return-list") ?? "/#/inspect/pool" },
 		{ label: displayLabel },
 	]);
 
@@ -103,13 +106,29 @@ export async function renderTaskDetail(featureId, taskId) {
 	const ledgerEl = document.getElementById("task-ledger");
 	if (!metaEl || !linksEl || !evidenceEl || !runsEl) return false;
 	if (titleEl) titleEl.textContent = displayLabel;
-	mountViewState(metaEl, "loading", "加载 Task…");
+	const identity = `${workspaceScope() ?? ""}:${featureId ?? ""}:${taskId}`;
+	const requestGeneration = uiState.pollingGeneration;
+	if (metaEl.dataset.taskIdentity !== identity) {
+		metaEl.dataset.taskIdentity = identity;
+		mountViewState(metaEl, "loading", "加载 Task…");
+		clearNode(runsEl);
+		for (const element of [linksEl, evidenceEl, ledgerEl]) if (element) clearNode(element);
+	}
+	if (!taskHistoryStates.has(identity)) taskHistoryStates.set(identity, { runs: [], nextBefore: null, loadedOlder: false, loadingOlder: false });
+	const historyState = taskHistoryStates.get(identity);
 
 	const [taskResult, historyResult, snapshot] = await Promise.all([
 		fetchJsonResult(taskApi),
 		fetchJsonResult(`${taskApi}/runs?limit=20`),
 		fetchJson("/api/snapshot"),
 	]);
+	if (requestGeneration !== uiState.pollingGeneration || metaEl.dataset.taskIdentity !== identity) return false;
+	if (!taskResult.ok && ![404, 409].includes(taskResult.status)) {
+		let error = metaEl.querySelector(".task-refresh-error");
+		if (!error) { error = el("p", "task-refresh-error node-input-error"); metaEl.appendChild(error); }
+		error.textContent = `更新失败，保留上次内容。${summarizeFetchError(taskResult)}`;
+		return true;
+	}
 	const task = taskResult.ok ? taskResult.body : null;
 	const history = historyResult.ok ? historyResult.body : null;
 	if (snapshot) {
@@ -120,7 +139,6 @@ export async function renderTaskDetail(featureId, taskId) {
 	clearNode(metaEl);
 	clearNode(linksEl);
 	clearNode(evidenceEl);
-	clearNode(runsEl);
 
 	if (!task) {
 		if (taskResult.status === 409) {
@@ -234,27 +252,9 @@ export async function renderTaskDetail(featureId, taskId) {
 		evidenceEl.appendChild(evidenceLinks);
 	}
 
-	runsEl.appendChild(el("h3", "section-heading", "运行历史"));
-	const runs = history?.runs ?? [];
-	if (runs.length === 0) {
-		mountViewState(runsEl, "empty", "暂无 ledger 运行记录。");
-	} else {
-		const rows = runs.map(taskRunHistoryRow);
-		runsEl.appendChild(
-			buildTable(
-				["worker run", "状态", "时间", "batch", "retryOf", "失败分类"],
-				rows,
-			),
-		);
-		if (history?.nextBefore) {
-			const more = el("button", "link-button", "加载更早的运行");
-			more.type = "button";
-			more.addEventListener("click", () => {
-				void loadOlderTaskRuns(featureId, taskId, history.nextBefore, runsEl);
-			});
-			runsEl.appendChild(more);
-		}
-	}
+	if (history) mergeTaskHistoryPage(historyState, history);
+	else historyState.error = summarizeFetchError(historyResult);
+	renderTaskHistory(runsEl, historyState, featureId, taskId, identity);
 
 	const active = ["running", "pending", "blocked", "stale"].includes(
 		(task.status ?? "").toLowerCase(),
@@ -262,6 +262,8 @@ export async function renderTaskDetail(featureId, taskId) {
 	if (ledgerEl) {
 		void renderTaskLedger(ledgerEl, taskId);
 	}
+	updateHeaderRefresh(snapshot?.generatedAt ?? uiState.lastSnapshot?.generatedAt, { mode: active ? "auto" : "ended" });
+	bindManualViewRefresh("task", () => renderTaskDetail(featureId, taskId));
 	return active;
 }
 
@@ -315,42 +317,59 @@ async function renderTaskLedger(ledgerEl, taskId) {
 	ledgerEl.appendChild(pre);
 }
 
-export async function loadOlderTaskRuns(featureId, taskId, before, runsEl) {
-	if (runsEl === undefined) {
-		runsEl = before;
-		before = taskId;
-		taskId = featureId;
-		featureId = undefined;
+function renderTaskHistory(runsEl, state, featureId, taskId, identity) {
+	if (runsEl.dataset.historyIdentity !== identity) { clearNode(runsEl); runsEl.dataset.historyIdentity = identity; }
+	let table = runsEl.querySelector("table");
+	if (!table) {
+		runsEl.appendChild(el("h3", "section-heading", "运行历史"));
+		table = buildTable(["worker run", "状态", "时间", "batch", "retryOf", "失败分类"], []);
+		runsEl.appendChild(table);
+		const status = el("p", "muted task-history-status");
+		status.setAttribute("role", "status");
+		runsEl.appendChild(status);
+		const more = el("button", "link-button", "加载更早的运行");
+		more.type = "button";
+		more.addEventListener("click", () => { void loadOlderTaskRuns(featureId, taskId, state.nextBefore, runsEl); });
+		runsEl.appendChild(more);
 	}
-	const taskApi = featureId
-		? `/api/features/${encodeURIComponent(featureId)}/tasks/${encodeURIComponent(taskId)}`
-		: `/api/tasks/${encodeURIComponent(taskId)}`;
-	const page = await fetchJson(
-		`${taskApi}/runs?limit=20&before=${encodeURIComponent(before)}`,
-	);
-	if (!page?.runs?.length) return;
-	const table = runsEl.querySelector("table");
-	if (!table) return;
-	const tbody = table.querySelector("tbody") || table;
-	for (const run of page.runs) {
-		const tr = document.createElement("tr");
-		for (const cell of taskRunHistoryRow(run).cells) {
-			const td = document.createElement("td");
-			if (cell instanceof Node) td.appendChild(cell);
-			else td.textContent = cell;
-			tr.appendChild(td);
-		}
-		tbody.appendChild(tr);
-	}
-	const btn = runsEl.querySelector("button.link-button");
-	if (btn) {
-		if (page.nextBefore) {
-			btn.onclick = () => {
-				void loadOlderTaskRuns(featureId, taskId, page.nextBefore, runsEl);
-			};
-		} else {
-			btn.remove();
-		}
+	reconcileKeyed(table.querySelector("tbody"), state.runs, {
+		getKey: (run) => run.workerRunId,
+		create: () => el("tr"),
+		update: (row, run) => {
+			const signature = JSON.stringify(run);
+			if (row.dataset.signature === signature) return;
+			clearNode(row);
+			for (const cell of taskRunHistoryRow(run).cells) {
+				const td = el("td");
+				if (cell instanceof Node) td.appendChild(cell); else td.textContent = cell ?? "—";
+				row.appendChild(td);
+			}
+			row.dataset.signature = signature;
+		},
+	});
+	const status = runsEl.querySelector(".task-history-status");
+	status.textContent = state.error ? `历史加载失败：${state.error}` : state.runs.length ? `已加载 ${state.runs.length} 次运行` : "暂无 ledger 运行记录。";
+	const more = runsEl.querySelector("button.link-button");
+	more.hidden = !state.nextBefore && !state.error;
+	more.disabled = state.loadingOlder;
+	more.textContent = state.loadingOlder ? "正在加载…" : state.error ? "重试加载" : "加载更早的运行";
+}
+
+export async function loadOlderTaskRuns(featureId, taskId, before, runsEl) {
+	const identity = `${workspaceScope() ?? ""}:${featureId ?? ""}:${taskId}`;
+	const state = taskHistoryStates.get(identity);
+	if (!state || state.loadingOlder) return;
+	state.loadingOlder = true;
+	renderTaskHistory(runsEl, state, featureId, taskId, identity);
+	const taskApi = featureId ? `/api/features/${encodeURIComponent(featureId)}/tasks/${encodeURIComponent(taskId)}` : `/api/tasks/${encodeURIComponent(taskId)}`;
+	try {
+		const result = await fetchJsonResult(`${taskApi}/runs?limit=20${state.nextBefore ? `&before=${encodeURIComponent(state.nextBefore)}` : ""}`);
+		if (taskHistoryStates.get(identity) !== state) return;
+		if (result.ok && result.body) mergeTaskHistoryPage(state, result.body, Boolean(state.nextBefore));
+		else state.error = summarizeFetchError(result);
+	} finally {
+		state.loadingOlder = false;
+		if (runsEl.dataset.historyIdentity === identity && taskHistoryStates.get(identity) === state) renderTaskHistory(runsEl, state, featureId, taskId, identity);
 	}
 }
 

package/dist/workflows/dag/budget-enforcement.js

@@ -1,6 +1,56 @@
 import { writeFile } from "node:fs/promises";
 import path from "node:path";
-import { checkBudgetPreNode, createBudgetLedger, formatBudgetReportMarkdown, isHardBudgetBreached, recordNodeBudgetSample, skipPendingNodesForBudgetBreach, } from "../../application/evaluation/budget.js";
+import { checkBudgetPreNode, createBudgetLedger, formatBudgetReportMarkdown, isHardBudgetBreached, recordNodeBudgetSample, reserveProviderBudget, skipPendingNodesForBudgetBreach, } from "../../application/evaluation/budget.js";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+/** A continuation already contains its ancestors' consumption. Never sum both. */
+export function validateCumulativeBudgetSuccessor(parent, child) {
+    const lineage = child.continuation?.budgetLineage ?? child.frontendRecoveryState?.budgetLineage;
+    const previous = parent.budgetLedger;
+    const next = child.budgetLedger;
+    if (!previous || !next || !lineage || (child.continuation?.parentRunId ?? child.frontendRecoveryState?.parentRunId) !== parent.runId || lineage.parentLedgerSha256 !== sha256OfCanonicalJson(previous) || sha256OfCanonicalJson(lineage.inheritedConsumed) !== sha256OfCanonicalJson(previous.consumed) || sha256OfCanonicalJson(parent.budget ?? null) !== sha256OfCanonicalJson(child.budget ?? null))
+        throw Error("FRONTEND_PROVIDER_BUDGET_LINEAGE_INVALID: unbound cumulative continuation");
+    for (const key of ["executorCalls", "providerRequests", "wallTimeMs", "repairPasses", "peakContextChars"])
+        if ((next.consumed[key] ?? 0) < (previous.consumed[key] ?? 0))
+            throw Error("FRONTEND_PROVIDER_BUDGET_LINEAGE_INVALID: consumption decreased");
+    return next;
+}
+const requestQueues = new WeakMap();
+/** One shared, attempt-fenced, durable admission queue for every request in a run. */
+export async function reserveDagProviderRequest(input) {
+    const ledger = input.state.budgetLedger;
+    if (!ledger || ledger.limits.maxProviderRequests === undefined)
+        throw Error("FRONTEND_PROVIDER_BUDGET_INVALID: frozen request budget unavailable");
+    const previous = requestQueues.get(ledger) ?? Promise.resolve();
+    const current = previous.catch(() => { }).then(async () => {
+        const active = () => input.state.status === "running" && input.state.nodes[input.nodeId]?.status === "RUNNING" && input.state.nodes[input.nodeId]?.currentAttempt === input.attempt;
+        if (!active())
+            throw Error("FRONTEND_PROVIDER_BUDGET_STALE: request belongs to an inactive attempt");
+        if (isHardBudgetBreached(ledger))
+            throw Error("FRONTEND_PROVIDER_BUDGET_EXHAUSTED: run budget already breached");
+        const breach = reserveProviderBudget(ledger, input.nodeId);
+        if (breach)
+            applyHardBudgetBreach(input.state, breach);
+        try {
+            await input.persist();
+        }
+        catch (error) {
+            ledger.status = "breached";
+            throw Error(`FRONTEND_PROVIDER_BUDGET_PERSIST_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (breach)
+            throw Error("FRONTEND_PROVIDER_BUDGET_EXHAUSTED: request quota reached");
+        if (!active())
+            throw Error("FRONTEND_PROVIDER_BUDGET_STALE: attempt stopped while reserving request");
+    });
+    requestQueues.set(ledger, current);
+    try {
+        await current;
+    }
+    finally {
+        if (requestQueues.get(ledger) === current)
+            requestQueues.delete(ledger);
+    }
+}
 export function initRunBudgetLedger(state, budget) {
     if (!budget)
         return;
@@ -8,7 +58,7 @@ export function initRunBudgetLedger(state, budget) {
     state.budgetLedger = createBudgetLedger(budget);
 }
 function wallTimeMs(state, now = Date.now()) {
-    const lineage = state.continuation?.budgetLineage;
+    const lineage = state.continuation?.budgetLineage ?? state.frontendRecoveryState?.budgetLineage;
     if (lineage) {
         return (lineage.inheritedConsumed.wallTimeMs +
             Math.max(0, now - new Date(lineage.inheritedAt).getTime()));
@@ -16,7 +66,7 @@ function wallTimeMs(state, now = Date.now()) {
     return Math.max(0, now - new Date(state.startedAt).getTime());
 }
 function repairPasses(state) {
-    const lineage = state.continuation?.budgetLineage;
+    const lineage = state.continuation?.budgetLineage ?? state.frontendRecoveryState?.budgetLineage;
     if (lineage) {
         return (lineage.inheritedConsumed.repairPasses +
             Math.max(0, (state.convergence?.currentPass ?? 1) - 1));

package/dist/workflows/dag/frontend-capacity.js

@@ -0,0 +1,9 @@
+/** Shared Contract/Plan bound. Permissions and directory globs are not files. */
+export const FRONTEND_MAX_IMPLEMENTATION_FILES = 15;
+export function frontendConcreteDeliveryFiles(files) {
+    if (!Array.isArray(files))
+        return [];
+    return [...new Set(files.filter((file) => typeof file === "string")
+            .map(file => file.trim().replace(/\\/g, "/").replace(/^(\.\/)+/, ""))
+            .filter(file => file.length > 0 && !/[*?{}]/.test(file) && !file.endsWith("/")))];
+}

package/dist/workflows/dag/frontend-closeout.js

@@ -114,7 +114,7 @@ export function buildFrontendTestHandoff(input) {
  * required verification evidence. Anything else downgrades to pending.
  */
 export function deriveFrontendIntegrationFacts(input) {
-    const requiredEvidenceSatisfied = input.verificationTargets.length > 0 &&
+    const requiredEvidenceSatisfied = input.verificationTargets.some((target) => target.mode === "behavior") &&
         input.verificationTargets.every((target) => target.status === "ok");
     if (input.realApiEvidence.present &&
         input.realApiEvidence.passed &&

package/dist/workflows/dag/frontend-design-policy.js

@@ -1,11 +1,12 @@
 import { deterministicSha256, } from "./frontend-implementation-contract.js";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { FRONTEND_MAX_IMPLEMENTATION_FILES } from "./frontend-capacity.js";
 const SHA256_HEX = /^[a-f0-9]{64}$/;
 const NPM_PACKAGE_NAME = /^(?:@[a-zA-Z0-9_.-]+\/)?[a-zA-Z0-9][a-zA-Z0-9_.-]*$/;
 /** Max concrete implementation files a single writeSet may carry before the
  * plan is asked to split. Kept at 15: beyond this, a single implement node's
  * read/edit loop inflates provider context toward overflow. */
-const MAX_WRITE_SET_FILES = 15;
+const MAX_WRITE_SET_FILES = FRONTEND_MAX_IMPLEMENTATION_FILES;
 function normalizeRelativePath(value) {
     return value.replace(/\\/g, "/").replace(/^\.\//, "");
 }

package/dist/workflows/dag/frontend-durable-tools.js

@@ -0,0 +1,193 @@
+import { mkdir, open, rename, rm } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { Check, Errors } from "typebox/value";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+import { assertHarnessWriteAllowed } from "../../infrastructure/harness/completed-facts-guard.js";
+import { readTypedEventStoreFromJsonl, typedEventPayloadSha256, hasCommittedTerminalEvent } from "./frontend-typed-event-store.js";
+const queues = new Map();
+const progressByTool = new WeakMap();
+/** Process-local telemetry only; durable facts remain the authority. */
+export function readFrontendToolProgress(tools) {
+    const counters = [...new Set((tools ?? []).flatMap(tool => tool && typeof tool === "object" && progressByTool.has(tool) ? [progressByTool.get(tool)] : []))];
+    if (!counters.length)
+        return undefined;
+    return counters.reduce((sum, item) => ({ failedRecords: sum.failedRecords + item.failedRecords, duplicateRecords: sum.duplicateRecords + item.duplicateRecords, durableSubmissions: sum.durableSubmissions + item.durableSubmissions, durableReplacements: sum.durableReplacements + item.durableReplacements }), { failedRecords: 0, duplicateRecords: 0, durableSubmissions: 0, durableReplacements: 0 });
+}
+async function exclusive(key, work) {
+    const previous = queues.get(key) ?? Promise.resolve();
+    const current = previous.catch(() => { }).then(work);
+    queues.set(key, current);
+    try {
+        return await current;
+    }
+    finally {
+        if (queues.get(key) === current)
+            queues.delete(key);
+    }
+}
+const hash = (value) => sha256OfCanonicalJson(JSON.parse(JSON.stringify(value, (_key, v) => v instanceof Map ? [...v.entries()].sort(([a], [b]) => String(a).localeCompare(String(b))) : v)));
+const ledgerError = (code, message) => Object.assign(new Error(message), { code });
+const failure = (code, error) => ({ content: [{ type: "text", text: JSON.stringify({ ok: false, code, error }) }], details: { ok: false, code, error } });
+/** A failed rename must never fall back to copying over a live ledger. */
+async function persist(file, records) {
+    assertHarnessWriteAllowed(file);
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        const handle = await open(temporary, "wx", 0o600);
+        try {
+            await handle.writeFile(records.map(r => JSON.stringify(r)).join("\n") + (records.length ? "\n" : ""));
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        await rename(temporary, file);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => { });
+    }
+}
+/** One queue covers schema checks, semantic checks, all facts in a tool call,
+ * atomic persistence, and acknowledgement. The model never sees a draft as saved. */
+export async function createDurableFrontendTools(input) {
+    const file = path.resolve(input.file);
+    const tools = input.tools.map(tool => {
+        const schema = tool.parameters;
+        return { ...tool, parameters: { ...schema, properties: { ...schema.properties, replace: { type: "boolean", description: "Explicitly revise the current fact with the same identity. Omit for new facts or identical replay." } } } };
+    });
+    const bindingSha256 = hash({ version: 1, attemptId: input.attemptId, binding: input.binding, schemas: tools.map(t => ({ name: t.name, parameters: t.parameters })) });
+    const publish = (store) => { input.store.records = store.records; input.store.revision = store.revision; input.setWorkingStore(input.store); };
+    const validate = async (records) => {
+        let revision = 0;
+        let terminal = false;
+        const ids = new Set();
+        const requests = new Set();
+        for (const r of records) {
+            if (r.attemptId !== input.attemptId || r.submission?.bindingSha256 !== bindingSha256)
+                throw ledgerError("FRONTEND_LEDGER_BINDING_MISMATCH", "frontend ledger binding/scope mismatch; preserve evidence and restart its owning phase");
+            if (r.phase !== "committed" || r.payloadSha256 !== typedEventPayloadSha256(r.fact) || r.revision <= revision || ids.has(r.eventId) || requests.has(r.requestId) || terminal)
+                throw ledgerError("FRONTEND_LEDGER_INTEGRITY_INVALID", "frontend ledger integrity/revision mismatch");
+            ids.add(r.eventId);
+            requests.add(r.requestId);
+            revision = r.revision;
+            terminal = hasCommittedTerminalEvent({ records: [r], revision }, input.attemptId);
+        }
+        await input.validateRestored?.(records);
+    };
+    const restore = async () => {
+        const records = await readTypedEventStoreFromJsonl(file);
+        if (records.length) {
+            await validate(records);
+            publish({ records, revision: records.at(-1).revision });
+        }
+        else if (input.store.records.some(r => r.submission))
+            throw ledgerError("FRONTEND_LEDGER_MISSING", "frontend durable ledger disappeared or became empty; refusing an unproven acknowledgement");
+    };
+    await exclusive(file, restore);
+    const progress = { failedRecords: 0, duplicateRecords: 0, durableSubmissions: 0, durableReplacements: 0 };
+    const replay = (receipt) => { progress.duplicateRecords++; return receipt; };
+    const wrapped = tools.map(tool => ({ ...tool, execute: (...args) => exclusive(file, async () => {
+            const [callId, params] = args;
+            const valid = Check(tool.parameters, params);
+            if (!valid) {
+                const errors = [...Errors(tool.parameters, params)];
+                return failure("TOOL_SCHEMA_INVALID", `${tool.name}: ${errors.slice(0, 8).map(e => `${e.instancePath || "/"}: ${e.message}`).join("; ")}${errors.length > 8 ? `; ${errors.length - 8} more fields` : ""}`);
+            }
+            try {
+                await restore();
+                const paramsSha256 = hash(params);
+                const singleton = new Set(["record_route_selection", "record_state_registry", "record_mock_api", "record_data_flow", "record_dependency", "record_design_deviation", "record_required_deliverables", "record_target_surface", "finalize_contract", "finalize_plan"]);
+                const naturalId = params?.id ?? params?.scopeId ?? params?.entry?.id ?? params?.requirementId ?? params?.choice?.purpose ?? (tool.name === "record_openspec_selection" ? params?.path : undefined) ?? (params?.endpoint ? `${params.endpoint.method}:${params.endpoint.path}` : undefined) ?? (singleton.has(tool.name) ? "singleton" : undefined);
+                const identity = `${tool.name}:${typeof naturalId === "string" ? naturalId : "incremental"}`;
+                const submissions = input.store.records.flatMap(r => r.submission?.receipt ? [r.submission] : []);
+                const previousCall = submissions.find(s => s.callId === callId);
+                if (previousCall)
+                    return previousCall.tool === tool.name && previousCall.paramsSha256 === paramsSha256 ? replay(previousCall.receipt) : failure("REQUEST_ID_REUSE_CONFLICT", `${tool.name}: call id already acknowledged with different parameters`);
+                const previousFact = submissions.filter(s => s.identity === identity).at(-1);
+                if (tool.name !== "record_plan_group_coverage" && previousFact?.paramsSha256 === paramsSha256)
+                    return replay(previousFact.receipt);
+                if (previousFact && naturalId !== undefined && params?.replace !== true && !["record_evidence_expectation", "record_required_deliverables", "record_data_flow"].includes(tool.name))
+                    return failure("FACT_IDENTITY_CONFLICT", `${identity}: changing a saved fact requires explicit replacement (replace:true)`);
+                if (input.store.records.some(r => ["contract-finalized", "finalize_plan", "approve_review", "request_review_changes", "approve_design", "request_design_changes"].includes(String(r.fact.kind))))
+                    return failure("TERMINAL_CONFLICT", "A successful terminal is already durable; only identical acknowledged submissions may be replayed");
+                const draft = structuredClone(input.store);
+                input.setWorkingStore(draft);
+                let result;
+                try {
+                    // Protocol controls must not be spread into domain facts by permissive callers.
+                    const original = input.tools.find(t => t.name === tool.name);
+                    const domainParams = { ...params };
+                    if (!original.parameters.properties?.replace)
+                        delete domainParams.replace;
+                    result = await tool.execute(args[0], domainParams, ...args.slice(2));
+                }
+                finally {
+                    input.setWorkingStore(input.store);
+                }
+                if (result.details?.ok !== true)
+                    return result;
+                const newRecords = draft.records.filter(r => r.phase === "committed" && r.revision > input.store.revision);
+                if (!newRecords.length)
+                    return replay(result);
+                for (const record of draft.records) {
+                    record.submission ??= { version: 1, bindingSha256, tool: "bootstrap", callId: record.requestId, identity: record.eventId, paramsSha256: record.payloadSha256 };
+                }
+                for (const record of newRecords)
+                    record.submission = { version: 1, bindingSha256, tool: tool.name, callId, identity, paramsSha256 };
+                newRecords.at(-1).submission.receipt = JSON.parse(JSON.stringify(result));
+                const committed = draft.records.filter(r => r.phase === "committed");
+                await validate(committed);
+                await persist(file, committed);
+                publish(draft);
+                progress.durableSubmissions++;
+                if (previousFact)
+                    progress.durableReplacements++;
+                return result;
+            }
+            catch (error) {
+                input.setWorkingStore(input.store);
+                return failure(typeof error?.code === "string" ? error.code : "FRONTEND_COMMIT_FAILED", error instanceof Error ? error.message : String(error));
+            }
+        }).then(result => { if (result.details?.ok !== true)
+            progress.failedRecords++; return result; }) }));
+    for (const tool of wrapped)
+        progressByTool.set(tool, progress);
+    return {
+        customTools: wrapped,
+        commitExternal: (work) => exclusive(file, async () => {
+            await restore();
+            const draft = structuredClone(input.store);
+            input.setWorkingStore(draft);
+            try {
+                await work();
+                const newRecords = draft.records.filter(r => r.phase === "committed" && r.revision > input.store.revision);
+                for (const record of draft.records) {
+                    record.submission ??= {
+                        version: 1,
+                        bindingSha256,
+                        tool: "external-adoption",
+                        callId: record.requestId,
+                        identity: record.eventId,
+                        paramsSha256: record.payloadSha256,
+                    };
+                }
+                const committed = draft.records.filter(r => r.phase === "committed");
+                await validate(committed);
+                await persist(file, committed);
+                publish(draft);
+                progress.durableSubmissions += newRecords.length;
+            }
+            finally {
+                input.setWorkingStore(input.store);
+            }
+        }),
+        flush: () => exclusive(file, async () => {
+            await restore();
+            const committed = input.store.records.filter(r => r.phase === "committed");
+            await validate(committed);
+            await persist(file, committed);
+        }),
+    };
+}

package/dist/workflows/dag/frontend-execution-groups.js

@@ -0,0 +1,24 @@
+import { z } from "zod";
+/** Model-authored execution ownership; never replaces a source obligation. */
+export const frontendExecutionSchema = z.object({
+    groupId: z.string().trim().min(1),
+    kind: z.enum(["behavior", "constraint", "exclusion"]),
+    summary: z.string().trim().min(1),
+}).strict();
+/** Latest canonical member wins; joining a group requires consistent metadata.
+ * No lexical/semantic similarity heuristic can erase a source ID or condition. */
+export function collectFrontendExecutionGroups(units) {
+    const groups = new Map();
+    for (const unit of new Map(units.map(unit => [unit.id, unit])).values()) {
+        const execution = unit.execution === undefined ? undefined : frontendExecutionSchema.parse(unit.execution);
+        const key = execution ? `group:${execution.groupId}` : `requirement:${unit.id}`;
+        const previous = groups.get(key);
+        if (previous && execution && (previous.kind !== execution.kind || previous.summary !== execution.summary))
+            throw Error(`EXECUTION_GROUP_CONFLICT: ${execution.groupId}; preserve differing permissions, thresholds and error paths as separate obligations/groups`);
+        if (previous)
+            previous.requirementIds.push(unit.id);
+        else
+            groups.set(key, { id: execution?.groupId ?? unit.id, kind: execution?.kind ?? "unclassified", summary: execution?.summary ?? `Independent requirement ${unit.id}`, requirementIds: [unit.id] });
+    }
+    return [...groups.values()];
+}

package/dist/workflows/dag/frontend-implementation-contract.js

@@ -1,3 +1,4 @@
+import { frontendExecutionSchema, collectFrontendExecutionGroups } from "./frontend-execution-groups.js";
 import { createHash } from "node:crypto";
 import { readFileSync } from "node:fs";
 import { readFile, stat } from "node:fs/promises";
@@ -711,6 +712,7 @@ export const frontendImplementationContractSchema = z
         .object({
         id,
         expectedOutcome: z.string().min(1),
+        execution: frontendExecutionSchema.optional(),
         implementationTargets: z.array(safePath),
         verificationTargetIds: z.array(z.string().min(1)),
         evidenceGap: gap.optional(),
@@ -806,6 +808,12 @@ export const frontendImplementationContractSchema = z
 })
     .strict()
     .superRefine((value, ctx) => {
+    try {
+        collectFrontendExecutionGroups(value.requirements);
+    }
+    catch (error) {
+        ctx.addIssue({ code: "custom", path: ["requirements"], message: String(error) });
+    }
     const stableIdentities = [
         {
             path: "requirements",
@@ -2063,6 +2071,7 @@ export function coerceFrontendImplementationContractInput(value, canonicalBindin
                 ? { sourceFragmentIds: req.sourceFragmentIds }
                 : {}),
             ...(Array.isArray(req.sourceRefs) ? { sourceRefs: req.sourceRefs } : {}),
+            ...(req.execution !== undefined ? { execution: req.execution } : {}),
         };
         // Do not mark free-form realIntegrationGap as blocking; defer to FE-TEST/FINAL-VERIFY.
         if (gapText) {
@@ -2500,6 +2509,10 @@ function splitFrontendContractReviewGroup(canonical, fields) {
         if (!Object.hasOwn(canonical, field))
             continue;
         const fieldValue = canonical[field];
+        // JSON omits undefined object properties; the index must describe the
+        // persisted contract, not phantom keys retained by normalization.
+        if (fieldValue === undefined)
+            continue;
         if (!Array.isArray(fieldValue)) {
             const candidate = { ...data, [field]: fieldValue };
             if (Object.keys(data).length > 0 &&