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

package/dist/workflows/dag/frontend-plan-render.js

@@ -1,3 +1,4 @@
+import { collectFrontendExecutionGroups } from "./frontend-execution-groups.js";
 /**
  * Deterministic Markdown renderer for a canonical frontend implementation
  * contract. The prewrite gate materializes this as `contracts/frontend-plan.md`
@@ -17,13 +18,19 @@ function bulletList(items) {
  * prose — the renderer must never present it as requirement content. */
 const IMPLIED_OUTCOME_PREFIX = "implied by contract:";
 function requirementsCoverage(contract) {
-    const lines = contract.requirements.map((requirement) => {
+    const renderRequirement = (requirement, includeOutcome = true) => {
         const targets = requirement.implementationTargets.join(", ");
         const verificationTargets = requirement.verificationTargetIds.join(", ");
-        const authoredOutcome = requirement.expectedOutcome.startsWith(IMPLIED_OUTCOME_PREFIX)
+        const authoredOutcome = !includeOutcome || requirement.expectedOutcome.startsWith(IMPLIED_OUTCOME_PREFIX)
             ? ""
             : ` — ${requirement.expectedOutcome}`;
         return `- ${requirement.id} → ${targets || "(no targets)"} [${verificationTargets || "no VT"}]${authoredOutcome}`;
+    };
+    const lines = collectFrontendExecutionGroups(contract.requirements).flatMap(group => {
+        const members = contract.requirements.filter(r => group.requirementIds.includes(r.id));
+        if (group.kind === "unclassified")
+            return members.map(r => renderRequirement(r));
+        return [`### ${group.id} (${group.kind})`, group.summary, ...members.map(r => renderRequirement(r, false)), "Full independent acceptance conditions remain in contracts/frontend-implementation-contract.json."];
     });
     return lines.length > 0 ? lines.join("\n") : "_(no requirements)_";
 }
@@ -72,7 +79,7 @@ function sourceFidelityLedger(contract) {
         `- ledger: ${binding.ledgerPath}`,
         `- ledgerSha256: ${binding.ledgerSha256 ?? "(missing)"}`,
         `- inputDigest: ${binding.inputDigest ?? "(missing)"}`,
-        "- 语义权威：原始 requirement/acceptance 文档与 requirement-ledger.json；本计划只消费派生摘要与 bound ledger 指针，长原文不内联。",
+        "- 语义权威：原始 requirement/acceptance 文档与 requirement-ledger.json；本计划按执行组展示共享方案；独立验收全文保留在 canonical contract，执行输入按完整义务分批。",
     ];
     const boundCount = Object.keys(binding.requirementToFragments ?? {}).length;
     if (boundCount > 0) {

package/dist/workflows/dag/frontend-recovery-controller.js

@@ -96,13 +96,13 @@ export async function runRecoveryOperationController(input) {
             };
         }
         // Total budget fold + hard stop (resource protection, fail-closed).
-        const ledgers = await readLedgers();
-        if (deps.budget) {
-            budgetAggregate = foldOperationBudgets({
-                ledgers,
-                budget: deps.budget,
-                now,
-            });
+        try {
+            const ledgers = await readLedgers();
+            if (deps.budget)
+                budgetAggregate = foldOperationBudgets({ ledgers, budget: deps.budget, now });
+        }
+        catch (error) {
+            return { terminalReason: "needs-attention", attempts: attempt, budgetAggregate, fingerprints, detail: `Recovery budget evidence unavailable: ${error instanceof Error ? error.message : String(error)}` };
         }
         if (budgetAggregate?.status === "breached") {
             return {

package/dist/workflows/dag/frontend-recovery-lineage.js

@@ -87,6 +87,7 @@ export function foldOperationBudgets(input) {
         limits: { ...input.budget.limits },
         consumed: {
             executorCalls: 0,
+            ...(input.budget.limits.maxProviderRequests !== undefined ? { providerRequests: 0 } : {}),
             wallTimeMs: 0,
             tokens: null,
             repairPasses: 0,
@@ -100,6 +101,15 @@ export function foldOperationBudgets(input) {
     let knownTokenSum = 0;
     const missing = new Set();
     for (const ledger of input.ledgers) {
+        if (input.budget.limits.maxProviderRequests !== undefined) {
+            if (ledger.consumed.providerRequests === undefined) {
+                if (input.budget.mode === "hard")
+                    throw Error("FRONTEND_PROVIDER_BUDGET_INVALID: missing operation request consumption");
+                delete aggregate.consumed.providerRequests;
+            }
+            else if (aggregate.consumed.providerRequests !== undefined)
+                aggregate.consumed.providerRequests += ledger.consumed.providerRequests;
+        }
         aggregate.consumed.executorCalls += ledger.consumed.executorCalls;
         aggregate.consumed.wallTimeMs += ledger.consumed.wallTimeMs;
         aggregate.consumed.repairPasses += ledger.consumed.repairPasses;
@@ -119,6 +129,9 @@ export function foldOperationBudgets(input) {
     aggregate.consumed.missingTokenNodeIds = [...missing].sort((a, b) => a.localeCompare(b));
     if (aggregate.mode === "hard") {
         const limits = aggregate.limits;
+        pushAggregateBreach(aggregate, "providerRequests", aggregate.consumed.providerRequests ?? 0, limits.maxProviderRequests, now);
+        if (aggregate.breaches.length)
+            aggregate.status = "breached";
         pushAggregateBreach(aggregate, "executorCalls", aggregate.consumed.executorCalls, limits.maxExecutorCalls, now);
         pushAggregateBreach(aggregate, "wallTimeMs", aggregate.consumed.wallTimeMs, limits.maxWallTimeMs, now);
         pushAggregateBreach(aggregate, "repairPasses", aggregate.consumed.repairPasses, limits.maxRepairPasses, now);

package/dist/workflows/dag/frontend-recovery-run.js

@@ -1,5 +1,6 @@
 import { copyFile, mkdir, readdir, readFile, rm, access } from "node:fs/promises";
 import path from "node:path";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { sha256Hex } from "./frontend-implementation-contract.js";
 import { FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, FRONTEND_RECOVERY_INTENT_REL_DIR, FRONTEND_RECOVERY_STAGING_PREFIX, computeFrontendRecoveryPlan, computeFrontendRecoveryPlanForSource, } from "./frontend-recovery-plan.js";
@@ -413,6 +414,8 @@ async function materializeChildStaging(input) {
         }
     }
     const childState = {
+        ...(parentState.budget ? { budget: structuredClone(parentState.budget) } : {}),
+        ...(parentState.budgetLedger ? { budgetLedger: structuredClone(parentState.budgetLedger) } : {}),
         version: 1,
         title: parentSpec.title,
         runId: childRunId,
@@ -434,6 +437,7 @@ async function materializeChildStaging(input) {
             }
             : {}),
         frontendRecoveryState: {
+            ...(parentState.budgetLedger ? { budgetLineage: { parentLedgerSha256: sha256OfCanonicalJson(parentState.budgetLedger), inheritedAt: createdAt, inheritedConsumed: structuredClone(parentState.budgetLedger.consumed) } } : {}),
             schemaVersion: 1,
             phase: "child-running",
             requestId,

package/dist/workflows/dag/frontend-review-scopes.js

@@ -0,0 +1,117 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readFile, realpath, lstat } from "node:fs/promises";
+import path from "node:path";
+import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+import { readCommittedEvents } from "./frontend-typed-event-store.js";
+import { stageTypedEventFact, adoptTypedEventFact } from "./frontend-typed-event-transaction.js";
+const hash = (text) => createHash("sha256").update(text).digest("hex");
+/** The section index is navigation; reconstruct coverage against the canonical source before using it. */
+export async function loadFrontendReviewScopes(runDir, phase, targetBytes) {
+    const root = await realpath(runDir);
+    const files = new Map();
+    async function read(relative, expected) {
+        const absolute = path.resolve(root, relative);
+        if (!absolute.startsWith(root + path.sep) || (await lstat(absolute)).isSymbolicLink() || !(await realpath(absolute)).startsWith(root + path.sep))
+            throw Error("FRONTEND_REVIEW_SCOPE_INVALID: artifact escaped run");
+        const text = await readFile(absolute, "utf8");
+        const sha256 = hash(text);
+        if (expected && sha256 !== expected)
+            throw Error(`FRONTEND_REVIEW_SCOPE_DRIFT: ${relative}`);
+        files.set(relative, sha256);
+        return { id: relative, text, sha256 };
+    }
+    let indexArtifact;
+    try {
+        indexArtifact = await read("contracts/frontend-implementation-contract.index.json");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    const index = JSON.parse(indexArtifact.text);
+    const canonicalArtifact = await read(index.contract.path, index.contract.sha256);
+    const canonical = JSON.parse(canonicalArtifact.text);
+    const covered = new Map();
+    const sections = [];
+    const ids = new Set();
+    for (const entry of index.sections) {
+        if (ids.has(entry.path))
+            throw Error("FRONTEND_REVIEW_SCOPE_INVALID: duplicate section identity");
+        ids.add(entry.path);
+        const section = await read(entry.path, entry.sha256);
+        const payload = JSON.parse(section.text);
+        if (payload.contractSha256 !== canonicalArtifact.sha256 || sha256OfCanonicalJson(payload.slices) !== sha256OfCanonicalJson(entry.slices))
+            throw Error("FRONTEND_REVIEW_SCOPE_INVALID: unbound section");
+        for (const slice of payload.slices) {
+            const value = canonical[slice.field];
+            const range = Array.isArray(value) ? value.slice(slice.start, slice.end) : value;
+            if (sha256OfCanonicalJson(range) !== sha256OfCanonicalJson(payload.data[slice.field]))
+                throw Error("FRONTEND_REVIEW_SCOPE_INVALID: section differs from canonical obligation");
+            const positions = covered.get(slice.field) ?? new Set();
+            if (Array.isArray(value)) {
+                if (!Number.isInteger(slice.start) || !Number.isInteger(slice.end) || slice.start < 0 || slice.end < slice.start || slice.end > value.length || slice.total !== value.length)
+                    throw Error("FRONTEND_REVIEW_SCOPE_INVALID: invalid array coverage");
+                for (let i = slice.start; i < slice.end; i++) {
+                    if (positions.has(i))
+                        throw Error("FRONTEND_REVIEW_SCOPE_INVALID: overlapping coverage");
+                    positions.add(i);
+                }
+            }
+            else {
+                if (positions.size)
+                    throw Error("FRONTEND_REVIEW_SCOPE_INVALID: duplicate field");
+                positions.add(0);
+            }
+            covered.set(slice.field, positions);
+        }
+        sections.push(section);
+    }
+    if (Object.keys(canonical).some(field => !covered.has(field) || covered.get(field).size !== (Array.isArray(canonical[field]) ? canonical[field].length : 1)))
+        throw Error("FRONTEND_REVIEW_SCOPE_INVALID: canonical field coverage incomplete");
+    const scopes = Buffer.byteLength(canonicalArtifact.text) <= targetBytes ? [canonicalArtifact] : sections;
+    if (phase === "review") {
+        const context = await read("contracts/frontend-review-context.json");
+        const payload = JSON.parse(context.text);
+        if (payload.contractRef.sha256 !== canonicalArtifact.sha256 || payload.contractRef.indexSha256 !== indexArtifact.sha256)
+            throw Error("FRONTEND_REVIEW_SCOPE_DRIFT: review context contract binding");
+        const diff = await read(payload.diff.reviewIndexPath);
+        const diffIndex = JSON.parse(diff.text);
+        await read(payload.diff.patchPath, payload.diff.patchSha256);
+        if (diffIndex.patchSha256 !== payload.diff.patchSha256)
+            throw Error("FRONTEND_REVIEW_SCOPE_DRIFT: review diff binding");
+        scopes.push(context);
+        for (const hunk of diffIndex.hunks)
+            scopes.push(await read(hunk.patchPath, hunk.sha256));
+    }
+    return { scopes, digest: sha256OfCanonicalJson([...files]), validate: async () => { for (const [relative, expected] of files)
+            await read(relative, expected); } };
+}
+/** Checkpoints attest explicit model completion of already supplied, hash-bound scopes. */
+export function createFrontendReviewScopeProtocol(input) {
+    const kind = input.phase === "design" ? "design-scope-completed" : "review-scope-completed";
+    let active = new Set();
+    const completedScopeIds = () => new Set(readCommittedEvents(input.getStore(), input.attemptId).filter(r => r.fact.kind === kind).map(r => String(r.fact.id)));
+    const receipt = (details) => ({ content: [{ type: "text", text: JSON.stringify(details) }], details });
+    return {
+        setActiveScope(ids) { active = new Set(ids); },
+        completedScopeIds,
+        committedFacts: () => readCommittedEvents(input.getStore(), input.attemptId),
+        assertComplete() { const missing = input.inventory?.scopes.filter(s => !completedScopeIds().has(s.id)) ?? []; if (missing.length)
+            throw Object.assign(Error(`FRONTEND_REVIEW_SCOPE_INCOMPLETE: ${missing.map(s => s.id).join(", ")}`), { code: "FRONTEND_REVIEW_SCOPE_INCOMPLETE" }); },
+        customTools: !input.inventory ? [] : [{ name: "complete_review_scope", label: "complete_review_scope", description: "After reviewing the supplied complete scope and saving its findings, checkpoint its exact runtime id. This does not approve the implementation or design.", parameters: { type: "object", properties: { id: { type: "string", minLength: 1 } }, required: ["id"], additionalProperties: false },
+                async execute(callId, params) {
+                    const scope = input.inventory.scopes.find(s => s.id === params.id);
+                    if (!scope || !active.has(params.id))
+                        return receipt({ ok: false, code: "FRONTEND_INPUT_SCOPE_VIOLATION", error: "Only the supplied active review scope may be completed" });
+                    await input.inventory.validate();
+                    const store = input.getStore();
+                    const requestId = `${input.attemptId}:${callId}:${randomUUID()}`;
+                    const fact = { kind, id: scope.id, sha256: scope.sha256 };
+                    const staged = stageTypedEventFact({ store, requestId, attemptId: input.attemptId, fact });
+                    const committed = await adoptTypedEventFact({ store, requestId, attemptId: input.attemptId, fact, eventId: staged.eventId, expectedRevision: store.revision });
+                    return receipt({ ok: true, kind, revision: committed.revision });
+                },
+            }],
+    };
+}

package/dist/workflows/dag/frontend-session-budget.js

@@ -0,0 +1,249 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { readFrontendToolProgress } from "./frontend-durable-tools.js";
+import { frontendModelCapabilities } from "../../shared/frontend-execution-policy.js";
+/** Count returned text only after a successful native read. No filesystem reads or raw content retention. */
+export function createFrontendReadObservation() {
+    const pending = new Map();
+    const finished = new Set();
+    const seen = new Set();
+    let bytes = 0, duplicates = 0, complete = 0, rejected = 0, unknown = false;
+    return {
+        observe(raw) {
+            const event = record(raw);
+            const id = event.toolCallId;
+            if (typeof id !== "string")
+                return;
+            if (event.type === "tool_execution_start" && event.toolName === "read")
+                pending.set(id, record(event.args ?? event.input));
+            if (event.type !== "tool_execution_end" || !pending.has(id) || finished.has(id))
+                return;
+            const args = pending.get(id);
+            pending.delete(id);
+            finished.add(id);
+            const result = record(event.result);
+            if (event.isError === true || result.isError === true || result.ok === false || result.error || record(result.details).ok === false) {
+                rejected++;
+                return;
+            }
+            const content = result.content;
+            if (!Array.isArray(content) || content.some(item => record(item).type !== "text" || typeof record(item).text !== "string") || typeof args.path !== "string") {
+                unknown = true;
+                return;
+            }
+            const text = content.map(item => record(item).text).join("\n");
+            const size = Buffer.byteLength(text);
+            const key = createHash("sha256").update(JSON.stringify([args.path.replaceAll("\\", "/").replace(/^\.\//, ""), args.offset ?? null, args.limit ?? null, text])).digest("hex");
+            bytes += size;
+            complete++;
+            if (seen.has(key))
+                duplicates += size;
+            seen.add(key);
+        },
+        snapshot() { return { successfulReadBytes: unknown ? null : bytes, duplicateReadBytes: unknown ? null : duplicates, completedReads: complete, rejectedReads: rejected, incompleteReads: pending.size }; },
+    };
+}
+export function classifyFrontendSessionFailure(result) {
+    const errorCode = /\b(?:FRONTEND_[A-Z_]+|TOOL_SCHEMA_INVALID|FACT_IDENTITY_CONFLICT|REQUEST_ID_REUSE_CONFLICT|TERMINAL_CONFLICT|[A-Z_]+_INCOMPLETE|[A-Z_]+_EXHAUSTED)\b/.exec(result.stderr)?.[0] ?? null;
+    const category = result.failureCategory;
+    const failureLayer = result.stopReason === "length" || /context|budget-exhausted/.test(category) ? "capacity"
+        : result.ok ? "none"
+            : errorCode?.includes("LEDGER") || errorCode === "FRONTEND_COMMIT_FAILED" ? "persistence"
+                : errorCode === "TOOL_SCHEMA_INVALID" ? "schema"
+                    : /binding|source|permission|write-guard|tool-policy/.test(category) ? "governance"
+                        : /timeout|rate-limit|provider|transport|network|auth/.test(category) ? "provider"
+                            : /invalid-output|structured-output/.test(category) ? "protocol-or-coverage"
+                                : "unknown";
+    return { failureLayer, errorCode };
+}
+const fields = ["inputTokens", "outputTokens", "reasoningTokens", "cacheReadTokens", "cacheWriteTokens", "totalTokens", "peakRequestContextTokens"];
+const record = (v) => v !== null && typeof v === "object" ? v : {};
+const number = (r, ...keys) => {
+    for (const key of keys)
+        if (typeof r[key] === "number" && Number.isFinite(r[key]) && r[key] >= 0)
+            return r[key];
+    return null;
+};
+const sumKnown = (values) => values.length && values.every(v => v !== null) ? values.reduce((s, v) => s + v, 0) : null;
+/** Observation only. Never feed this projection into the SDK execution guard. */
+export function collectFrontendUsage(events) {
+    const samples = new Map();
+    const aliases = new Map();
+    let anonymous = false;
+    let observed = false;
+    for (const raw of events) {
+        const event = record(raw);
+        const message = record(event.message);
+        if (typeof message.role === "string" && message.role !== "assistant")
+            continue;
+        const usage = record(event.usage ?? message.usage ?? event.tokenUsage);
+        if (!Object.keys(usage).length)
+            continue;
+        observed = true;
+        const ids = [event.responseId, event.messageId, message.responseId, message.id].filter((v) => typeof v === "string" && v.length > 0);
+        const roots = [...new Set(ids.map(id => aliases.get(id) ?? id))];
+        const key = roots[0];
+        if (!key) {
+            anonymous = true;
+            continue;
+        }
+        const input = number(usage, "input", "input_tokens", "inputTokens", "prompt_tokens", "promptTokens");
+        const output = number(usage, "output", "output_tokens", "outputTokens", "completion_tokens", "completionTokens");
+        const cacheRead = number(usage, "cacheRead", "cache_read_input_tokens");
+        const cacheWrite = number(usage, "cacheWrite", "cache_creation_input_tokens");
+        // Pi's native input excludes cache tokens; OpenAI-compatible input includes them.
+        const context = input === null ? null : "input" in usage ? sumKnown([input, cacheRead, cacheWrite]) : input;
+        const sample = {
+            inputTokens: input, outputTokens: output,
+            reasoningTokens: number(usage, "reasoning", "reasoning_tokens", "reasoningTokens") ?? number(record(usage.completion_tokens_details ?? usage.output_tokens_details), "reasoning_tokens"),
+            cacheReadTokens: cacheRead, cacheWriteTokens: cacheWrite,
+            totalTokens: number(usage, "total_tokens", "totalTokens") ?? sumKnown([context, output]),
+            peakRequestContextTokens: context,
+        };
+        for (const root of roots) {
+            const previous = samples.get(root);
+            if (previous)
+                for (const field of fields)
+                    sample[field] = previous[field] === null ? sample[field] : sample[field] === null ? previous[field] : Math.max(previous[field], sample[field]);
+            samples.delete(root);
+        }
+        for (const [alias, root] of aliases)
+            if (roots.includes(root))
+                aliases.set(alias, key);
+        for (const id of ids)
+            aliases.set(id, key);
+        samples.set(key, sample);
+    }
+    const result = Object.fromEntries(fields.map(field => [field, anonymous ? null : field === "peakRequestContextTokens" ? (samples.size && [...samples.values()].every(s => s[field] !== null) ? Math.max(...[...samples.values()].map(s => s[field])) : null) : sumKnown([...samples.values()].map(s => s[field]))]));
+    return { ...result, requestCount: anonymous || !observed ? null : samples.size,
+        completeness: !observed ? "unknown" : !anonymous && result.inputTokens !== null && result.outputTokens !== null && result.totalTokens !== null ? "complete" : "partial" };
+}
+function aggregateAttempts(attempts) {
+    const usages = attempts.map(a => a.actual ?? collectFrontendUsage([]));
+    const totals = Object.fromEntries(fields.map(field => [field, field === "peakRequestContextTokens"
+            ? usages.every(u => u[field] !== null) ? Math.max(...usages.map(u => u[field])) : null
+            : sumKnown(usages.map(u => u[field]))]));
+    return { ...totals, requestCount: sumKnown(usages.map(u => u.requestCount)), completeness: usages.every(u => u.completeness === "complete") ? "complete" : usages.every(u => u.completeness === "unknown") ? "unknown" : "partial" };
+}
+/** Captures every transport attempt, including an SDK failure before CLI fallback. */
+export async function observeFrontendAttempt(input, execute) {
+    const event = { id: randomUUID(), backend: input.backend, model: input.model, startedAt: new Date().toISOString(), completion: "incomplete" };
+    const notify = () => { try {
+        input.observer?.(structuredClone(event));
+    }
+    catch { /* observation cannot change execution */ } };
+    notify();
+    const result = await execute();
+    event.completion = "complete";
+    event.actual = result.usageObservation ?? collectFrontendUsage([]);
+    event.reads = result.readObservation;
+    event.capabilities = result.capabilitiesObservation;
+    event.requestEnvelope = result.requestEnvelopeObservation;
+    event.terminal = { ok: result.ok, failureCategory: result.failureCategory, stopReason: result.stopReason ?? null, durationMs: result.durationMs };
+    notify();
+    return result;
+}
+const measure = (text) => ({ sha256: createHash("sha256").update(text).digest("hex"), chars: text.length, bytes: Buffer.byteLength(text), estimatedTokens: Math.ceil(Buffer.byteLength(text) / 3) });
+function safeObservation(read, fallback) { try {
+    return read();
+}
+catch {
+    return fallback;
+} }
+/** One logical dispatch and its real transport attempts; no raw prompt or tool output is stored. */
+export async function observeFrontendSession(input, execute) {
+    const durableBefore = safeObservation(() => input.durableCommittedCount?.(), undefined);
+    const before = safeObservation(() => input.committedCount?.(), undefined);
+    const toolsBefore = readFrontendToolProgress(input.customTools);
+    const receipt = {
+        schemaVersion: 1, policyVersion: "frontend-session-observation-v1",
+        identity: { sessionId: randomUUID(), phase: input.phase, scopeIds: input.scopeIds ?? [], taskId: input.taskId ?? null, runId: input.runId ?? null, nodeId: input.nodeId ?? null, attempt: input.attempt ?? null, sourceDigest: input.sourceDigest ?? null, contractDigest: input.contractDigest ?? null },
+        startedAt: new Date().toISOString(), finishedAt: null, completion: "incomplete",
+        planned: { prompt: measure(input.prompt), userMessage: measure(input.userMessage ?? ""), toolSchemas: input.customTools ? safeObservation(() => measure(JSON.stringify(input.customTools.map(t => { const tool = record(t); return { name: tool.name, description: tool.description, parameters: tool.parameters }; }))), null) : null,
+            estimatorVersion: "utf8-bytes-div3-v1-estimate", capabilities: { ...frontendModelCapabilities(undefined), model: input.model ?? null }, unmeasuredComponents: ["sdk-system-overhead", "built-in-tools", "history", "tool-results", "attachments"] },
+        actual: collectFrontendUsage([]), attempts: [],
+        progress: { memoryCommittedDelta: null, durableCommittedDelta: null, failedRecords: null, duplicateRecords: null, durableSubmissions: null, durableReplacements: null, successfulReadBytes: null, duplicateReadBytes: null }, terminal: null,
+    };
+    let writes = Promise.resolve();
+    let abandoned = false;
+    const writeObservation = async (file, snapshot) => {
+        // Never recreate a run that the runner has already archived.
+        await mkdir(path.dirname(file)).catch(error => { if (error.code !== "EEXIST")
+            throw error; });
+        const temporary = `${file}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify(snapshot), { flag: "wx" });
+            await rename(temporary, file);
+        }
+        finally {
+            await rm(temporary, { force: true }).catch(() => { });
+        }
+    };
+    const save = () => {
+        const snapshot = structuredClone(receipt);
+        writes = writes.then(async () => {
+            if (abandoned)
+                return;
+            if (input.sink)
+                await input.sink(snapshot);
+            else if (input.artifactPath)
+                await writeObservation(input.artifactPath, snapshot);
+        }).catch(() => { });
+        return writes;
+    };
+    const waitForWrite = async (pending) => {
+        let timer;
+        try {
+            await Promise.race([pending, new Promise(resolve => { timer = setTimeout(() => { abandoned = true; resolve(); }, 100); })]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+    await waitForWrite(save());
+    const result = await execute(event => {
+        const index = receipt.attempts.findIndex(a => a.id === event.id);
+        if (index < 0)
+            receipt.attempts.push(event);
+        else
+            receipt.attempts[index] = event;
+        void save();
+    });
+    receipt.finishedAt = new Date().toISOString();
+    receipt.completion = "complete";
+    receipt.actual = receipt.attempts.length ? aggregateAttempts(receipt.attempts) : result.usageObservation ?? collectFrontendUsage([]);
+    receipt.planned.capabilities = receipt.attempts[0]?.capabilities ?? result.capabilitiesObservation ?? receipt.planned.capabilities;
+    receipt.progress.memoryCommittedDelta = before !== undefined && input.committedCount ? safeObservation(() => Math.max(0, input.committedCount() - before), null) : null;
+    const durableAfter = safeObservation(() => input.durableCommittedCount?.(), undefined);
+    receipt.progress.durableCommittedDelta = durableBefore !== undefined && durableAfter !== undefined ? Math.max(0, durableAfter - durableBefore) : null;
+    const toolsAfter = readFrontendToolProgress(input.customTools);
+    if (toolsBefore && toolsAfter)
+        for (const key of ["failedRecords", "duplicateRecords", "durableSubmissions", "durableReplacements"])
+            receipt.progress[key] = Math.max(0, toolsAfter[key] - toolsBefore[key]);
+    const reads = receipt.attempts.length ? receipt.attempts.map(a => a.reads) : [result.readObservation];
+    for (const key of ["successfulReadBytes", "duplicateReadBytes"])
+        receipt.progress[key] = sumKnown(reads.map(r => r?.[key] ?? null));
+    receipt.terminal = { ok: result.ok, failureCategory: result.failureCategory, stopReason: result.stopReason ?? null, durationMs: Date.parse(receipt.finishedAt) - Date.parse(receipt.startedAt), ...classifyFrontendSessionFailure(result) };
+    await waitForWrite(save());
+    return result;
+}
+export function summarizeFrontendSessions(receipts) {
+    const byId = new Map();
+    for (const receipt of receipts) {
+        const previous = byId.get(receipt.identity.sessionId);
+        const rank = (r) => [r.completion === "complete" ? 1 : 0, Date.parse(r.finishedAt ?? r.startedAt), r.attempts.filter(a => a.completion === "complete").length, r.attempts.length];
+        const candidateRank = rank(receipt);
+        const previousRank = previous ? rank(previous) : [];
+        const difference = candidateRank.map((v, i) => v - (previousRank[i] ?? 0)).find(v => v !== 0) ?? 0;
+        if (!previous || difference > 0)
+            byId.set(receipt.identity.sessionId, receipt);
+    }
+    const unique = [...byId.values()];
+    return { sessions: unique.length, failedSessions: unique.filter(r => r.terminal?.ok === false).length, incompleteSessions: unique.filter(r => r.completion === "incomplete").length,
+        failureLayers: Object.fromEntries([...new Set(unique.flatMap(r => r.terminal && r.terminal.failureLayer !== "none" ? [r.terminal.failureLayer] : []))].sort().map(layer => [layer, unique.filter(r => r.terminal?.failureLayer === layer).length])),
+        progress: Object.fromEntries(["durableCommittedDelta", "durableSubmissions", "durableReplacements", "failedRecords", "duplicateRecords", "successfulReadBytes", "duplicateReadBytes"].map(key => [key, sumKnown(unique.map(r => r.progress[key]))])),
+        totalTokens: sumKnown(unique.flatMap(r => r.attempts.length ? r.attempts.map(a => a.actual?.totalTokens ?? null) : [r.actual.totalTokens])),
+        sessionDurationSumMs: sumKnown(unique.map(r => r.terminal?.durationMs ?? null)) };
+}

package/dist/workflows/dag/frontend-shadow-dual-write.js

@@ -236,6 +236,7 @@ export const PLAN_LEDGER_FACT_KINDS = [
     "plan-requirement",
     "plan-verification-target",
     "plan-evidence-gap",
+    "mock-endpoint",
 ];
 function skeletonTargetFiles(skeleton) {
     if (!isRecord(skeleton))
@@ -386,8 +387,25 @@ export function assemblePlanPatchFromCommittedFacts(records, contractRequirement
         patch.interactions = [...interactionByName.values(), ...unnamedInteractions];
     }
     const mockApi = lastByKind("mock-api");
+    if (!mockApi && facts.some(f => f.kind === "mock-endpoint" && f.removed !== true))
+        throw Error("MOCK_POLICY_MISSING: endpoint has no policy");
     if (mockApi && isRecord(mockApi.mockApi)) {
-        patch.mockApi = mockApi.mockApi;
+        const endpoints = new Map();
+        for (const endpoint of Array.isArray(mockApi.mockApi.endpoints) ? mockApi.mockApi.endpoints : []) {
+            if (isRecord(endpoint))
+                endpoints.set(`${endpoint.method}:${endpoint.path}`, endpoint);
+        }
+        for (const fact of facts)
+            if (fact.kind === "mock-endpoint" && isRecord(fact.endpoint)) {
+                const key = `${fact.endpoint.method}:${fact.endpoint.path}`;
+                if (fact.removed === true)
+                    endpoints.delete(key);
+                else
+                    endpoints.set(key, fact.endpoint);
+            }
+        if (mockApi.mockApi.strategy === "not-needed" && endpoints.size)
+            throw Error("MOCK_POLICY_CONFLICT: withdraw endpoints before declaring Mock/API not needed");
+        patch.mockApi = { ...mockApi.mockApi, endpoints: [...endpoints.values()] };
     }
     const deviation = lastByKind("design-deviation");
     if (deviation) {
@@ -433,7 +451,7 @@ export function assemblePlanPatchFromCommittedFacts(records, contractRequirement
         const inherited = contractRequirements.get(id);
         if (!inherited)
             return entry;
-        const merged = { ...entry };
+        const merged = { ...entry, ...(inherited.text ? { expectedOutcome: inherited.text } : {}), ...(inherited.execution ? { execution: inherited.execution } : {}) };
         // Inherit the contract-declared provenance only when the plan did
         // not already declare it (model override wins; missing inherits).
         if (!Array.isArray(entry.sourceFragmentIds)) {

package/dist/workflows/dag/frontend-test-execution-evidence.js

@@ -39,9 +39,10 @@ const resultSchema = z.object({
         })),
     })),
 });
-export function parseFrontendTestExecutionReport(raw, cwd) {
+/** Resolve runner paths against its cwd, then use the contract workspace coordinates. */
+export function parseFrontendTestExecutionReport(raw, cwd, workspaceRoot = cwd) {
     return resultSchema.parse(raw).testResults.flatMap((suite) => suite.assertionResults.map((test) => ({
-        file: path.relative(cwd, path.resolve(cwd, suite.name)).replace(/\\/g, "/"),
+        file: path.relative(workspaceRoot, path.resolve(cwd, suite.name)).replace(/\\/g, "/"),
         title: test.fullName ?? [...(test.ancestorTitles ?? []), test.title].join(" "),
         status: test.status,
     })));

package/dist/workflows/dag/frontend-typed-event-store.js

@@ -128,6 +128,7 @@ export const PLAN_RECORD_FACT_KINDS = [
     "plan-evidence-gap",
     "state-registry",
 ];
+export const INCREMENTAL_DETAIL_FACT_KINDS = ["mock-endpoint", "review-finding", "design-finding", "contract-scope-completed", "plan-group-coverage", "scout-scope", "review-scope-completed", "design-scope-completed"];
 /**
  * A+B (AC-009): typed issue category shared by review and design change
  * requests. The five-value enum replaces free-form issueCategory strings.
@@ -159,6 +160,7 @@ const ALL_TYPED_EVENT_FACT_KIND_VALUES = [
         ...CONTRACT_FACT_KINDS,
         ...PLAN_TERMINAL_FACT_KINDS,
         ...PLAN_RECORD_FACT_KINDS,
+        ...INCREMENTAL_DETAIL_FACT_KINDS,
     ]),
 ];
 export const typedEventFactKindSchema = z.enum(ALL_TYPED_EVENT_FACT_KIND_VALUES);
@@ -261,6 +263,15 @@ export const typedEventRecordSchema = z
     revision: z.number().int().nonnegative(),
     recordedAt: z.string().min(1),
     quarantineReason: z.string().min(1).optional(),
+    submission: z.object({
+        version: z.literal(1),
+        bindingSha256: z.string().regex(/^[a-f0-9]{64}$/),
+        tool: z.string(),
+        callId: z.string(),
+        identity: z.string(),
+        paramsSha256: z.string().regex(/^[a-f0-9]{64}$/),
+        receipt: z.record(z.unknown()).optional(),
+    }).strict().optional(),
 })
     .strict()
     .superRefine((value, ctx) => {