@tea-agent/loop-agent 0.42.0 → 0.43.0-next.2

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-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) {

package/dist/workflows/dag/frontend-input-projection.js

@@ -0,0 +1,76 @@
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+/** An execution packing target, not a claim about any model's context limit. */
+export const FRONTEND_SCOPE_TARGET_BYTES = 24_000;
+export function packFrontendInputUnits(units, options = {}) {
+    const target = options.targetBytes ?? FRONTEND_SCOPE_TARGET_BYTES;
+    const maxUnits = options.maxUnits ?? 4;
+    if (!Number.isFinite(target) || target <= 0 || !Number.isInteger(maxUnits) || maxUnits < 1)
+        throw Error("FRONTEND_INPUT_POLICY_INVALID");
+    const batches = [];
+    let batch = [];
+    let bytes = 2;
+    let cost = 0;
+    const ids = new Set();
+    for (const unit of units) {
+        if (!unit.id || ids.has(unit.id))
+            throw Error(`FRONTEND_INPUT_ID_CONFLICT: ${unit.id}`);
+        ids.add(unit.id);
+        const size = Buffer.byteLength(JSON.stringify(unit), "utf8") + 1;
+        if (options.maxUnitBytes !== undefined && size > options.maxUnitBytes)
+            throw Error(`FRONTEND_INPUT_UNIT_TOO_LARGE: ${unit.id} requires ${size} bytes; split the source obligation without dropping conditions`);
+        const unitCost = options.cost?.(unit) ?? 1;
+        if (batch.length && (batch.length >= maxUnits || bytes + size > target || cost + unitCost > (options.maxCost ?? Infinity))) {
+            batches.push(batch);
+            batch = [];
+            bytes = 2;
+            cost = 0;
+        }
+        batch.push(unit);
+        bytes += size;
+        cost += unitCost;
+    }
+    if (batch.length)
+        batches.push(batch);
+    return batches;
+}
+/** Select whole obligations before serialization; never clip identities or text. */
+export function projectFrontendInputScope(payload, scopeIds) {
+    const byId = new Map(payload.requirements.map(r => [r.id, r]));
+    const requirements = [...new Set(scopeIds)].map(id => {
+        const unit = byId.get(id);
+        if (!unit)
+            throw Error(`FRONTEND_INPUT_SCOPE_MISSING: ${id}`);
+        return unit;
+    });
+    const fragments = new Set(requirements.flatMap(r => Array.isArray(r.sourceFragmentIds) ? r.sourceFragmentIds : []));
+    const inScope = (fact) => {
+        const ids = typeof fact.requirementId === "string" ? [fact.requirementId] : Array.isArray(fact.requirementIds) ? fact.requirementIds : [];
+        return !ids.length || ids.some(id => scopeIds.includes(String(id)));
+    };
+    return {
+        ...payload, requirements,
+        ...(Array.isArray(payload.sharedFacts) ? { sharedFacts: payload.sharedFacts.filter(f => f && typeof f === "object" && inScope(f)).map(f => f.kind === "required-deliverables" && Array.isArray(f.items) ? { ...f, items: f.items.filter((item) => inScope(item)) } : f) } : {}),
+        ...(Array.isArray(payload.fragments) ? { fragments: payload.fragments.filter(f => f && typeof f === "object" && fragments.has(f.id)) } : {}),
+        inputManifest: { schemaVersion: 1, semantics: "full", sourceSha256: sha256OfCanonicalJson(payload), scopeIds: requirements.map(r => r.id), excludedIds: payload.requirements.filter(r => !scopeIds.includes(r.id)).map(r => r.id) },
+    };
+}
+export function parseFrontendInputBlock(prompt, phase) {
+    const block = new RegExp(`<frontend_${phase}_input>[\\s\\S]*?<\\/frontend_${phase}_input>`).exec(prompt)?.[0];
+    if (!block)
+        return undefined;
+    for (const line of block.split(/\r?\n/)) {
+        try {
+            const payload = JSON.parse(line);
+            if (Array.isArray(payload.requirements))
+                return { block, payload };
+        }
+        catch { /* wrapper prose is not JSON */ }
+    }
+    throw Error(`FRONTEND_INPUT_INVALID: ${phase} compiled inventory is not parseable`);
+}
+export function projectFrontendContractPrompt(prompt, scopeIds) {
+    const input = parseFrontendInputBlock(prompt, "contract");
+    if (!input)
+        throw Error("FRONTEND_INPUT_MISSING: contract compiled inventory unavailable");
+    return prompt.replace(input.block, ["<frontend_contract_input>", "Complete canonical obligations for this session only. Confirm each id with record_requirement; preserve all independent conditions.", JSON.stringify(projectFrontendInputScope(input.payload, scopeIds)), "</frontend_contract_input>"].join("\n"));
+}