@tea-agent/loop-agent 0.42.0-next.9 → 0.42.1

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

@@ -226,6 +226,7 @@ export function parseTargetSurfaceFacts(text) {
 }
 export const PLAN_LEDGER_FACT_KINDS = [
     "target-surface",
+    "state-registry",
     "component-choice",
     "state-flow",
     "data-flow",
@@ -235,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))
@@ -385,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) {
@@ -432,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)) {
@@ -484,7 +503,22 @@ export function assemblePlanPatchFromCommittedFacts(records, contractRequirement
     }
     const verificationTargets = verificationTargetOrder
         .map((id) => verificationTargetById.get(id))
-        .filter((entry) => Boolean(entry));
+        .filter((entry) => Boolean(entry))
+        .map((entry) => {
+        // Coverage precedes UX. A later state-flow fact explicitly naming
+        // this VT establishes the reverse binding without another model call.
+        // No path/name heuristics: unbound or ambiguous decisions stay subject
+        // to canonical validation. Recompute from live states after removals.
+        const boundStates = [...stateByName.values()]
+            .filter((state) => state.applicable === true &&
+            asStringArray(state.verificationTargetIds).includes(asString(entry.id)))
+            .map((state) => asString(state.name));
+        if (boundStates.length === 0)
+            return entry;
+        return { ...entry, uiStates: [...new Set([
+                    ...asStringArray(entry.uiStates), ...boundStates,
+                ])].sort() };
+    });
     if (verificationTargets.length > 0) {
         patch.verificationTargets = verificationTargets;
     }

package/dist/workflows/dag/frontend-shape-facts.js

@@ -1,4 +1,5 @@
 import { sha256OfCanonicalJson } from "../../task/contract/hash.js";
+import { FRONTEND_MAX_IMPLEMENTATION_FILES, frontendConcreteDeliveryFiles } from "./frontend-capacity.js";
 import { buildFrontendShapeTransitionCapsule, deriveFrontendRuntimeShapeFacts, evaluateFrontendShapeEscalation, parseFrontendShapeTransitionCapsule, } from "./frontend-shape.js";
 import { createTypedEventStore, readCommittedEvents, } from "./frontend-typed-event-store.js";
 import { adoptTypedEventFact, stageTypedEventFact, } from "./frontend-typed-event-transaction.js";
@@ -222,7 +223,13 @@ function extractRuntimeShapeEvidence(input) {
         !sourceText.includes(path) &&
         /(?:\.[A-Za-z0-9]+|\*\*)$/.test(path));
     const routes = canonicalStrings(text.match(/\/(?:[A-Za-z0-9_:[\]-]+\/?)+/g) ?? []);
-    const splitRequired = /["']splitRequired["']\s*:\s*true|\bsplit-required\s+shape\b/i.test(text);
+    // The frozen delivery inventory is available before Plan. Do not spend
+    // coverage/UX sessions building a contract the same capacity gate will reject.
+    // allowedPaths and text mentions are permissions/evidence, never this count.
+    const skeleton = input.tasksById.get("frontend-plan-pi")?.structuredContractOutput?.skeleton;
+    const deliveryFiles = frontendConcreteDeliveryFiles(skeleton?.targets?.files);
+    const capacitySplit = deliveryFiles.length > FRONTEND_MAX_IMPLEMENTATION_FILES;
+    const splitRequired = capacitySplit || /["']splitRequired["']\s*:\s*true|\bsplit-required\s+shape\b/i.test(text);
     return {
         sourceNodeId: input.sourceNodeId,
         sourceNodeDigest: computeFrontendShapeNodeDigest(node),
@@ -232,7 +239,10 @@ function extractRuntimeShapeEvidence(input) {
         targetPaths,
         routes,
         splitRequired,
-        evidenceRefs: [`node:${input.sourceNodeId}:stdout`],
+        evidenceRefs: [
+            ...(capacitySplit ? ["dag:frontend-plan-pi:structuredContractOutput.skeleton.targets.files"] : []),
+            `node:${input.sourceNodeId}:stdout`,
+        ],
     };
 }
 /** Commit a typed, structured runtime fact immediately after a canonical source

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

@@ -46,15 +46,22 @@ const EXECUTABLE_SHAPE_RANK = {
     high: 3,
 };
 function pathSpreadScore(paths) {
+    // Verification-only roots are routinely authorized together with the
+    // implementation root (for example `src/**` + `test/**`). They do not make
+    // a UI change cross-domain, so exclude them from the topology spread signal.
+    // Keep product packages and source roots intact: `apps/**` + `packages/**`
+    // must still count as a real spread and prevent an unsafe small topology.
+    const auxiliaryRoot = /^(?:test|tests|__tests__|e2e|cypress|spec|specs|docs|documentation)$/i;
     const tops = new Set(paths
         .map((p) => p.replace(/\\/g, "/").split("/").filter(Boolean)[0] ?? "")
+        .filter((root) => !auxiliaryRoot.test(root))
         .filter(Boolean));
     return tops.size;
 }
 function collectEscalationSignals(blob, supervised) {
     const signals = [];
     for (const pattern of SHAPE_ESCALATION_PATTERNS) {
-        if (pattern.re.test(blob))
+        if (hasAffirmativeShapeSignal(blob, pattern))
             signals.push(pattern.id);
     }
     if (supervised)
@@ -65,6 +72,42 @@ function collectEscalationSignals(blob, supervised) {
     }
     return [...new Set(signals)];
 }
+function isExplicitShapeExclusion(clause, pattern) {
+    const match = new RegExp(pattern.re.source, "i").exec(clause);
+    if (!match)
+        return false;
+    const prefix = clause.slice(0, match.index).trim();
+    const suffix = clause.slice(match.index + match[0].length).trim();
+    const actionInSignal = ["new-route", "new-dependency"].includes(pattern.id);
+    if (suffix && !(actionInSignal && /^no$/i.test(prefix) && /^is\s+(?:required|needed)$/i.test(suffix)))
+        return false;
+    if (/^(?:不涉及|不(?:修改|变更|调整|改变|新增|添加)|无需(?:修改|变更|调整|改变|新增|添加)|no\s+changes?\s+to|(?:do\s+not|don't)\s+(?:change|modify))$/i.test(prefix))
+        return true;
+    return actionInSignal && /^(?:不|禁止|无需|无须|不需要|no|without|do\s+not|don't)$/i.test(prefix);
+}
+/** Only a complete, independent scope exclusion can suppress a risk signal.
+ * Nested negation, conditions and trailing consequences remain risk evidence;
+ * an excluded occurrence never cancels another occurrence elsewhere. */
+function hasAffirmativeShapeSignal(blob, pattern) {
+    for (const sentence of blob.split(/[\n。.;；!?！？]/)) {
+        if (!pattern.re.test(sentence))
+            continue;
+        // Commas can attach a condition to an exclusion. A comma-separated list
+        // is independent only when every item is itself an explicit exclusion.
+        const clauses = sentence.split(/[，,、]/).map(part => part.trim().replace(/^(?:[-*+]|\d+\))\s+/, ""));
+        if (clauses.every(clause => SHAPE_ESCALATION_PATTERNS.some(candidate => isExplicitShapeExclusion(clause, candidate))))
+            continue;
+        return true;
+    }
+    return false;
+}
+/** Negation applies to the API mention itself, never to unrelated Mock policy. */
+function hasFrontendRemoteSignal(blob) {
+    const remaining = blob
+        .replace(/\bno\s+api\b/gi, "")
+        .replace(/无\s*(?:api\b|接口)/gi, "");
+    return /\b(api|fetch|axios|graphql|endpoint)\b|远程|接口/i.test(remaining);
+}
 function resolveBaselineFrontendTaskShape(input) {
     const blob = [
         input.requirementMarkdown ?? "",
@@ -84,9 +127,7 @@ function resolveBaselineFrontendTaskShape(input) {
     const paths = input.allowedPaths ?? [];
     const spread = pathSpreadScore(paths);
     const concentrated = spread <= 1 && paths.length <= 4;
-    const hasApiSignal = /\b(api|fetch|axios|graphql|endpoint|远程|接口)\b/i.test(blob) &&
-        !(/(?:^|[^\w])(?:no\s+api|not-needed)(?:$|[^\w])/i.test(blob) ||
-            /无\s*api|无\s*接口/i.test(blob));
+    const hasApiSignal = hasFrontendRemoteSignal(blob);
     const complexity = (input.complexity ?? "").toLowerCase();
     // split-required wins over everything: it is a termination/escalation
     // signal, not an executable topology.
@@ -266,9 +307,7 @@ export function deriveFrontendRuntimeShapeFacts(input) {
     const supervised = /\bsupervised\b/i.test(blob);
     const escalationSignals = collectEscalationSignals(blob, supervised);
     const paths = input.allowedPaths ?? [];
-    const hasApiSignal = /\b(api|fetch|axios|graphql|endpoint|远程|接口)\b/i.test(blob) &&
-        !(/(?:^|[^\w])(?:no\s+api|not-needed)(?:$|[^\w])/i.test(blob) ||
-            /无\s*api|无\s*接口/i.test(blob));
+    const hasApiSignal = hasFrontendRemoteSignal(blob);
     const requiresFull = escalationSignals.length > 0 || pathSpreadScore(paths) > 1 || hasApiSignal;
     return {
         splitRequired: input.splitRequired,

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

@@ -0,0 +1,49 @@
+import path from "node:path";
+import { readFile } from "node:fs/promises";
+import { z } from "zod";
+/** Observe supported frozen Vitest commands without changing their selection. */
+export async function withFrontendTestReporter(input) {
+    // Compound commands/wrappers need their own adapter: never append flags to
+    // a different shell command, change selection, or override a user reporter.
+    if (/[;&|<>`\n\r$]/.test(input.command) || /--(?:reporter|outputFile)/.test(input.command))
+        return undefined;
+    const direct = /^(?:(?:npx|pnpm exec|yarn exec)\s+)?vitest\s+run(?:\s|$)/.test(input.command.trim());
+    const npm = /^npm\s+(?:run\s+([\w:-]+)|(test))(?=\s|$)(.*)$/.exec(input.command.trim());
+    let separator = "";
+    if (!direct) {
+        if (!npm)
+            return undefined;
+        let manifest;
+        try {
+            manifest = JSON.parse(await readFile(path.join(input.cwd, "package.json"), "utf8"));
+        }
+        catch {
+            return undefined;
+        }
+        const script = manifest.scripts?.[npm[1] ?? "test"] ?? "";
+        if (!/^vitest\s+run(?:\s|$)/.test(script) || /[;&|<>`\n\r$]|--(?:reporter|outputFile)/.test(script))
+            return undefined;
+        if (npm[3]?.trim() && !/^--(?:\s|$)/.test(npm[3].trim()))
+            return undefined;
+        separator = npm[3]?.trim() ? "" : " --";
+    }
+    const quote = (value) => `'${value.replace(/'/g, `'"'"'`)}'`;
+    return `${input.command}${separator} --reporter=json --outputFile=${quote(input.reportPath)}`;
+}
+const resultSchema = z.object({
+    testResults: z.array(z.object({
+        name: z.string().min(1),
+        assertionResults: z.array(z.object({
+            title: z.string(), fullName: z.string().optional(),
+            ancestorTitles: z.array(z.string()).optional(), status: z.string(),
+        })),
+    })),
+});
+/** 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(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

@@ -95,6 +95,8 @@ export const CONTRACT_FACT_KINDS = [
     "open-question",
     "split-proposal",
     "openspec-selection",
+    "ui-state-declaration",
+    "required-deliverables",
     "contract-finalized",
 ];
 export const CONTRACT_TERMINAL_FACT_KINDS = ["contract-finalized"];
@@ -124,7 +126,9 @@ export const PLAN_RECORD_FACT_KINDS = [
     "plan-requirement",
     "plan-verification-target",
     "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.
@@ -156,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);
@@ -258,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) => {

package/dist/workflows/dag/frontend-verification-trace.js

@@ -152,6 +152,7 @@ export function extractFrontendTestTitles(content) {
     const tokens = lexFrontendTestSource(content);
     const titles = [];
     const configurationModifiers = new Set(["each", "runIf", "skipIf"]);
+    const nonExecutingModifiers = new Set(["skip", "todo", "fails"]);
     function closingParenIndex(openIndex) {
         let depth = 0;
         for (let cursor = openIndex; cursor < tokens.length; cursor += 1) {
@@ -177,12 +178,21 @@ export function extractFrontendTestTitles(content) {
         }
         let cursor = index + 1;
         let hasConfigurationModifier = false;
+        let hasNonExecutingModifier = false;
+        let conditionalModifier;
         while (tokens[cursor]?.type === "punctuation" &&
             tokens[cursor]?.value === "." &&
             tokens[cursor + 1]?.type === "identifier") {
             if (tokens[cursor + 1]?.type === "identifier" &&
                 configurationModifiers.has(tokens[cursor + 1].value)) {
                 hasConfigurationModifier = true;
+                if (["runIf", "skipIf"].includes(tokens[cursor + 1].value)) {
+                    conditionalModifier = tokens[cursor + 1].value;
+                }
+            }
+            if (tokens[cursor + 1]?.type === "identifier" &&
+                nonExecutingModifiers.has(tokens[cursor + 1].value)) {
+                hasNonExecutingModifier = true;
             }
             cursor += 2;
         }
@@ -191,6 +201,13 @@ export function extractFrontendTestTitles(content) {
             continue;
         }
         if (hasConfigurationModifier) {
+            if (conditionalModifier && tokens[cursor + 1]?.type === "identifier" &&
+                tokens[cursor + 2]?.value === ")") {
+                const condition = tokens[cursor + 1].value;
+                if ((conditionalModifier === "runIf" && condition === "false") ||
+                    (conditionalModifier === "skipIf" && condition === "true"))
+                    hasNonExecutingModifier = true;
+            }
             const close = closingParenIndex(cursor);
             if (close === null ||
                 tokens[close + 1]?.type !== "punctuation" ||
@@ -199,6 +216,11 @@ export function extractFrontendTestTitles(content) {
             }
             cursor = close + 1;
         }
+        if (hasNonExecutingModifier) {
+            // A skipped suite also skips every nested test title in its body.
+            index = closingParenIndex(cursor) ?? tokens.length;
+            continue;
+        }
         if (tokens[cursor + 1]?.type !== "string")
             continue;
         titles.push(tokens[cursor + 1].value);
@@ -226,7 +248,7 @@ async function evaluateTargetFileTrace(input) {
         workspaceRoot: input.workspaceRoot,
         file: input.target.file,
     });
-    if (fileIssues.length || input.target.type === "static") {
+    if (fileIssues.length || input.target.mode === "static") {
         return { issues: fileIssues };
     }
     const absolute = path.resolve(input.workspaceRoot, input.target.file);
@@ -261,10 +283,11 @@ export async function evaluateFrontendWriterTracePreflight(input) {
         }
         targets.push({
             id: target.id,
+            commandId: target.commandId,
             commandLabel: target.commandLabel,
             file: target.file,
             ...(target.symbol ? { symbol: target.symbol } : {}),
-            ...(target.type !== "static" ? { traceKey: target.id } : {}),
+            ...(target.mode !== "static" ? { traceKey: target.id } : {}),
             status: fileTrace.issues.length ? "failed" : "ok",
             matchedNodeIds: [],
             issues: fileTrace.issues,
@@ -301,15 +324,25 @@ export async function evaluateVerificationTargets(input) {
             target,
         });
         issues.push(...fileTrace.issues);
+        const executed = input.executedTests?.get(target.commandLabel);
+        if (target.mode !== "static" && executed !== undefined) {
+            // safePath permits "./" prefixes; reporter files are cwd-relative.
+            const targetFile = path.posix.normalize(target.file.replace(/\\/g, "/"));
+            const matching = executed.filter((test) => test.file === targetFile && traceKeyMatchesTitle(target.id, test.title));
+            if (matching.length === 0 || matching.some((test) => test.status !== "passed")) {
+                issues.push(`behavior target was not fully executed and passed: ${target.id} in ${target.file}`);
+            }
+        }
         const status = issues.length ? "failed" : "ok";
         if (issues.length)
             hardIssues.push(...issues.map((i) => `${target.id}: ${i}`));
         targets.push({
             id: target.id,
+            commandId: target.commandId,
             commandLabel: target.commandLabel,
             file: target.file,
             symbol: target.symbol,
-            ...(target.type !== "static" ? { traceKey: target.id } : {}),
+            ...(target.mode !== "static" ? { traceKey: target.id } : {}),
             status,
             matchedNodeIds: owners ?? [],
             issues,
@@ -383,7 +416,7 @@ export async function runFrontendVerificationTraceGate(input) {
             .join("; ")}`);
     }
     const contract = parsed.data;
-    const requiresBehaviorVerification = contract.verificationTargets.some((target) => target.type !== "static");
+    const requiresBehaviorVerification = contract.verificationTargets.some((target) => target.mode !== "static");
     // Prefer post-repair reverify nodes when present (M3); else initial verify nodes (M2).
     const staticCandidates = [
         "frontend-static-reverify-shell",
@@ -471,6 +504,7 @@ export async function runFrontendVerificationTraceGate(input) {
         contract,
         labelOwners,
         workspaceRoot: input.workspaceRoot,
+        executedTests: input.evidence?.behavior.executedTests,
     });
     if (hardIssues.length) {
         throw new Error(`trace: ${hardIssues.join("; ")}`);