@tea-agent/loop-agent 0.43.0-next.18 → 0.43.0-next.19

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

@@ -97,8 +97,6 @@ export function renderFrontendPlanMarkdown(contract) {
         "## Source Fidelity Ledger",
         sourceFidelityLedger(contract),
         "",
-        "## Implementation Steps",
-        bulletList(contract.implementationSteps) || "_(not specified)_",
         "",
         "## Target Files",
         bulletList(contract.targets.files) || "_(none)_",

package/dist/workflows/dag/frontend-prewrite-gate.js

@@ -702,10 +702,10 @@ export async function runFrontendPrewriteGate(input) {
             failureCode: "mock-strategy-outside-allowed",
         });
     }
-    // Behavior verification needs bound Mock evidence. Build-only implementation
-    // does not claim tested Mock behavior and may defer those commands.
+    // Mock command binding (main): a non-not-needed strategy can only be proven
+    // by the DAG's frozen Mock verification commands. Block before any write is
+    // authorized when none were materialized at generation time.
     if (mockStrategy !== "not-needed" &&
-        analysis.canonical.verificationTargets.some((target) => target.mode === "behavior") &&
         (input.config.mockCommandLabels?.length ?? 0) === 0) {
         return finalizePrewrite(input, {
             ...basePending,

package/dist/workflows/dag/frontend-provider-capability-matrix.js

@@ -1,8 +1,7 @@
 import { randomUUID } from "node:crypto";
 import { TYPED_EVENT_FACT_KINDS, stageTypedEventRecord, } from "./frontend-typed-event-store.js";
-import { createDagEventObserver } from "./event-observer.js";
 /**
- * M1 shadow-only provider/model capability matrix (AC-003).
+ * Provider/model capability fact matrix (AC-003).
  *
  * Records seven provider/model capability facts as read-only observations:
  *   - `terminal-commit`
@@ -13,15 +12,12 @@ import { createDagEventObserver } from "./event-observer.js";
  *   - `provider-ended-without-terminal`
  *   - `read-only-fact-channel`
  *
- * This matrix is intentionally shadow-only: `recordProviderCapabilityFact`
- * returns a record for audit, never a branch-control signal, and this module
- * must never be imported into `node-execution.ts`'s model-selection / branch
- * control path. It is deliberately distinct from `frontend-project-capability`
- * (framework / mock discovery).
+ * `recordProviderCapabilityFact` returns a staged record for audit, never a
+ * branch-control signal, and this module is deliberately distinct from
+ * `frontend-project-capability` (framework / mock discovery).
  *
- * The read-only fact channel composes the existing `createDagEventObserver`
- * (which already swallows its own write errors) so that a shadow-channel
- * failure can never affect canonical DAG execution.
+ * These facts are staged independently from the canonical DAG event stream;
+ * recording them never participates in model selection or branch control.
  */
 export const PROVIDER_CAPABILITY_FACT_KINDS = TYPED_EVENT_FACT_KINDS;
 /** Terminal finish-reason shapes, modeled after
@@ -55,8 +51,8 @@ function readExplicitFinishReason(source) {
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-/** True when an observed provider event is terminal-shaped. Shadow-only: the
- * result is a fact, not a control decision. */
+/** True when an observed provider event is terminal-shaped. The result is a
+ * fact, not a control decision. */
 export function isTerminalProviderEventShape(event) {
     const type = typeof event.type === "string" ? event.type : undefined;
     return type !== undefined && TERMINAL_FINISH_REASON_TYPES.has(type);
@@ -108,52 +104,3 @@ export function recordProviderCapabilityFact(options) {
     });
     return { eventId, record };
 }
-/**
- * Attach a shadow observer that records `read-only-fact-channel` facts while
- * delegating the canonical event JSONL to the existing `createDagEventObserver`.
- * The shadow channel never throws into the caller: any recording failure is
- * swallowed so canonical execution is unaffected.
- */
-export function createProviderCapabilityShadowObserver(options) {
-    const base = createDagEventObserver({
-        eventsJsonlPath: options.eventsJsonlPath,
-        dagRunId: options.dagRunId,
-        spec: options.spec,
-    });
-    const recordReadOnlyFact = (eventType) => {
-        try {
-            recordProviderCapabilityFact({
-                store: options.store,
-                attemptId: options.attemptId,
-                requestId: options.requestId,
-                fact: { kind: "read-only-fact-channel", eventType },
-            });
-        }
-        catch {
-            // Shadow channel must never affect canonical execution.
-        }
-    };
-    const observer = {
-        onRunStart: async (state) => {
-            recordReadOnlyFact("dag.run.started");
-            await base.observer.onRunStart?.(state);
-        },
-        onNodeStart: async (nodeId, state) => {
-            recordReadOnlyFact("dag.node.started");
-            await base.observer.onNodeStart?.(nodeId, state);
-        },
-        onNodeOutput: async (nodeId, chunk, state) => {
-            recordReadOnlyFact("dag.node.output");
-            await base.observer.onNodeOutput?.(nodeId, chunk, state);
-        },
-        onNodeFinish: async (nodeId, state) => {
-            recordReadOnlyFact("dag.node.finished");
-            await base.observer.onNodeFinish?.(nodeId, state);
-        },
-        onRunFinish: async (state) => {
-            recordReadOnlyFact("dag.run.finished");
-            await base.observer.onRunFinish?.(state);
-        },
-    };
-    return { observer, flush: base.flush };
-}

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

@@ -25,6 +25,27 @@ import { topoSortToRanks } from "./topo.js";
 /** Canonical contract artifact default location; overridden by the design
  * policy shell's configured outputDir/artifactName when present. */
 const FRONTEND_CANONICAL_CONTRACT_DEFAULT_REL_PATH = "contracts/frontend-implementation-contract.json";
+/**
+ * Run-owned artifacts a frontend node writes *outside* its own node directory.
+ *
+ * An imported node keeps its parent FINISHED record in the child run, so the
+ * child never executes the body that produced these files. Any downstream node
+ * that reads them must still find them in the child run directory: smoke r31
+ * saw a review-triggered recovery die at `frontend-review-context-shell` with
+ * `ENOENT contracts/frontend-worktree-baseline.json`, because
+ * `frontend-writer-admission-shell` is imported (its baseline capture is a side
+ * effect of the node body) while the review context requires that file.
+ *
+ * Entries listed as required fail the staging closed when the parent lacks
+ * them; optional entries (for example the lint baseline, which only exists when
+ * lint is configured) are copied when present.
+ */
+const FRONTEND_IMPORTED_NODE_RUN_ARTIFACTS = {
+    "frontend-writer-admission-shell": {
+        required: ["contracts/frontend-worktree-baseline.json"],
+        optional: ["contracts/frontend-lint-baseline.json"],
+    },
+};
 function resolveDeps(deps) {
     return {
         readParentState: deps?.readParentState ?? readDagRunState,
@@ -397,6 +418,41 @@ async function materializeChildStaging(input) {
         newRunDir: stagingDir,
         relativePath: FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT,
     });
+    // Imported nodes keep their parent FINISHED record, so the run-owned files
+    // their bodies wrote outside the node directory travel with them (smoke r31:
+    // a review-triggered recovery reached review-context with no worktree
+    // baseline and hard-failed on ENOENT).
+    const importedRunArtifacts = [];
+    for (const nodeId of plan.importedNodeIds) {
+        const artifactSpec = FRONTEND_IMPORTED_NODE_RUN_ARTIFACTS[nodeId];
+        if (!artifactSpec)
+            continue;
+        for (const relativePath of artifactSpec.required) {
+            const copied = await copyArtifactVerified({
+                parentRunDir,
+                newRunDir: stagingDir,
+                relativePath,
+            });
+            importedRunArtifacts.push({
+                sourceRelativePath: relativePath,
+                ...copied,
+            });
+        }
+        for (const relativePath of artifactSpec.optional) {
+            const sourcePath = path.join(parentRunDir, ...relativePath.split("/"));
+            if (!(await fileExists(sourcePath)))
+                continue;
+            const copied = await copyArtifactVerified({
+                parentRunDir,
+                newRunDir: stagingDir,
+                relativePath,
+            });
+            importedRunArtifacts.push({
+                sourceRelativePath: relativePath,
+                ...copied,
+            });
+        }
+    }
     // The scheduler gates every shape boundary by its committed fact once the
     // boundary's source node is FINISHED. Imported nodes stay FINISHED in the
     // child, so their boundaries must inherit the parent's committed facts or
@@ -470,6 +526,7 @@ async function materializeChildStaging(input) {
             relativePath: writerAdmissionResult.destinationRelativePath,
             sha256: writerAdmissionResult.sha256,
         },
+        importedRunArtifacts,
         importedFacts,
     };
     await writeJsonVerified(stagingDir, FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, importManifest);

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

@@ -96,74 +96,6 @@ export async function captureCumulativeDiffContext(input) {
     }
     return assembleCumulativeDiffContext({ baselineEntries, currentEntries });
 }
-const TYPED_TO_LEGACY = {
-    approve_review: "pass",
-    request_review_changes: "request-revision",
-};
-function isTypedReviewTerminalVerdict(value) {
-    return value === "approve_review" || value === "request_review_changes";
-}
-function isLegacyReviewVerdict(value) {
-    return value === "pass" || value === "request-revision";
-}
-/**
- * Deterministic, fail-closed equivalence between the typed review terminal
- * verdict(s) observed in the attempt and the legacy JSON verdict.
- *
- * Fail-closed cases (all yield `match: false` with an explicit reason):
- *   - no typed terminal fact;
- *   - more than one typed terminal fact (conflicting);
- *   - an unknown typed terminal kind;
- *   - a missing/illegal legacy JSON verdict.
- */
-export function compareTypedReviewToLegacyJsonVerdict(input) {
-    const kinds = [...input.typedKinds];
-    const legacyVerdict = isLegacyReviewVerdict(input.legacyVerdict ?? "")
-        ? input.legacyVerdict
-        : undefined;
-    if (kinds.length === 0) {
-        return {
-            typedVerdict: undefined,
-            legacyVerdict,
-            match: false,
-            reason: "typed review terminal fact missing",
-        };
-    }
-    if (kinds.length > 1) {
-        return {
-            typedVerdict: undefined,
-            legacyVerdict,
-            match: false,
-            reason: `conflicting typed review terminal facts: ${[...new Set(kinds)].join(",")}`,
-        };
-    }
-    const typedVerdict = kinds[0];
-    if (!isTypedReviewTerminalVerdict(typedVerdict)) {
-        return {
-            typedVerdict: undefined,
-            legacyVerdict,
-            match: false,
-            reason: `unknown typed review terminal fact kind: ${typedVerdict}`,
-        };
-    }
-    if (!legacyVerdict) {
-        return {
-            typedVerdict,
-            legacyVerdict: undefined,
-            match: false,
-            reason: "legacy JSON verdict missing or not pass|request-revision",
-        };
-    }
-    const expected = TYPED_TO_LEGACY[typedVerdict];
-    return {
-        typedVerdict,
-        legacyVerdict,
-        match: expected === legacyVerdict,
-        reason: expected === legacyVerdict
-            ? "typed review verdict matches legacy JSON verdict"
-            : `typed review verdict ${typedVerdict} maps to ${expected} but legacy JSON verdict is ${legacyVerdict}`,
-    };
-}
 /**
  * review-context 稳定失败枚举（AC-011 / AC-HARD-005）：v2 drift / manifest 失败返回
  * 结构化、可消费的 failure code（稳定枚举 + reason 的 envelope），既有调用方无需字符串
@@ -191,6 +123,37 @@ async function readRequiredJson(runDir, relativePath) {
         throw new FrontendReviewContextFailure("review-context-manifest-missing", `frontend review context missing or invalid ${relativePath}: ${error instanceof Error ? error.message : String(error)}`);
     }
 }
+/**
+ * Per-command verification evidence written by the verify shell.
+ *
+ * The review protocol treats shell exit status as authoritative ("typecheck,
+ * build, and test are required successful final exits"), but the verification
+ * trace only proves command/file/target-id *binding*. Smoke r31: with no exit
+ * evidence in the context, a compliant reviewer had to request changes for a
+ * missing check it could not perform. Absent the artifact the context says so
+ * explicitly instead of leaving the reviewer to guess.
+ */
+async function readVerificationEvidence(runDir) {
+    const relativePath = "contracts/frontend-verification-evidence.json";
+    try {
+        const decoded = JSON.parse(await readFile(path.join(runDir, relativePath), "utf8"));
+        if (decoded?.schemaId !== "frontend-verification-evidence-v1") {
+            return {
+                schemaId: "frontend-verification-evidence-v1",
+                status: "unavailable",
+                reason: `${relativePath} carries an unexpected schemaId`,
+            };
+        }
+        return { ...decoded, status: "available" };
+    }
+    catch (error) {
+        return {
+            schemaId: "frontend-verification-evidence-v1",
+            status: "unavailable",
+            reason: `${relativePath} unavailable: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+}
 async function readOptionalLintAssessment(runDir) {
     const relativePath = "contracts/frontend-lint-assessment.json";
     try {
@@ -246,8 +209,7 @@ function assertReviewEvidence(input) {
     const trace = input.verificationTrace;
     const expectedTargets = new Map(contract.data.verificationTargets.map((target) => [target.id, target]));
     const actualTargets = Array.isArray(trace?.targets) ? trace.targets : [];
-    const mockEvidenceBound = contract.data.verificationTargets.every((target) => target.mode === "static") ||
-        contract.data.mockApi.strategy === "not-needed" ||
+    const mockEvidenceBound = contract.data.mockApi.strategy === "not-needed" ||
         (typeof trace?.mockCommandNodeId === "string" && trace.mockCommandNodeId.length > 0 &&
             Array.isArray(trace?.mockCommandLabels) && trace.mockCommandLabels.length > 0 &&
             Array.isArray(trace?.mockCommandTexts) && trace.mockCommandTexts.length === trace.mockCommandLabels.length &&
@@ -321,6 +283,7 @@ export async function runFrontendReviewContextGate(input) {
     const repairAssessment = await readOptionalRepairAssessment(input.runDir);
     const verifyFailure = await readOptionalVerifyFailure(input.runDir);
     const lintAssessment = await readOptionalLintAssessment(input.runDir);
+    const verificationEvidence = await readVerificationEvidence(input.runDir);
     const cumulativeDiff = await captureCumulativeDiffContext({
         runDir: input.runDir,
         workspaceRoot: input.workspaceRoot,
@@ -356,6 +319,16 @@ export async function runFrontendReviewContextGate(input) {
             sections: contractReviewArtifacts.index.sections,
         },
         verificationTrace,
+        verificationEvidence,
+        // Protocol-legal lint vocabulary; `lintConfigured: false` tells the
+        // reviewer that this task declares no lint surface at all, so
+        // `unavailable` reads as "not applicable", not "missing evidence".
+        lintStatus: lintAssessment
+            ? lintAssessment.status
+            : typeof verificationEvidence.lintStatus === "string"
+                ? verificationEvidence.lintStatus
+                : "unavailable",
+        lintConfigured: verificationEvidence.lintConfigured === true,
         ...(repairAssessment ? { repairAssessment } : {}),
         ...(verifyFailure ? { verifyFailure } : {}),
         ...(lintAssessment ? { lintAssessment } : {}),

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

@@ -7,8 +7,10 @@
  * allowing its path is NOT dependency introduction by itself; the manifest
  * path check in classifyFrontendRisk requires this language to escalate.
  */
-const DEPENDENCY_INSTALL_LANGUAGE = /new\s+dependency|add\s+dependencies?|install\s+dependencies?|npm\s+(?:install|i)\b|yarn\s+(?:add|install)\b|pnpm\s+(?:add|install)\b|bun\s+(?:add|install)\b|新增依赖|添加依赖|安装依赖|引入依赖/i;
-const HIGH_RISK_PATTERNS = [
+const DEPENDENCY_INSTALL_LANGUAGE = /new\s+dependency|add\s+dependenc(?:y|ies)|install\s+dependenc(?:y|ies)|npm\s+(?:install|i)\b|yarn\s+(?:add|install)\b|pnpm\s+(?:add|install)\b|bun\s+(?:add|install)\b|新增依赖|添加依赖|安装依赖|引入依赖/i;
+/** Shared vocabulary for risk and topology routing. Keep policy-specific
+ * signals (design conflict/state infrastructure) below this list. */
+export const FRONTEND_SHARED_ESCALATION_PATTERNS = [
     {
         id: "new-route",
         re: /new\s+route|新增路由|createBrowserRouter|add\s+route|新建页面路由/i,
@@ -45,6 +47,48 @@ const HIGH_RISK_PATTERNS = [
         id: "cross-domain-paths",
         re: /多个领域|cross-module|multiple\s+packages/i,
     },
+];
+function isExplicitSharedExclusion(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. */
+export function hasAffirmativeSharedSignal(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 => FRONTEND_SHARED_ESCALATION_PATTERNS.some(candidate => isExplicitSharedExclusion(clause, candidate))))
+            continue;
+        return true;
+    }
+    return false;
+}
+/** Extract the shared escalation vocabulary once. Shape routing reuses this
+ * exact result so risk and topology cannot drift on the same input. */
+export function collectFrontendSharedSignals(blob, supervised = false) {
+    const signals = FRONTEND_SHARED_ESCALATION_PATTERNS
+        .filter((pattern) => hasAffirmativeSharedSignal(blob, pattern))
+        .map((pattern) => pattern.id);
+    if (supervised)
+        signals.push("supervised-profile");
+    return [...new Set(signals)];
+}
+const HIGH_RISK_PATTERNS = [
+    ...FRONTEND_SHARED_ESCALATION_PATTERNS,
     {
         id: "new-state-infra",
         re: /\bredux\b|\bzustand\b|\bpinia\b|\bjotai\b|\brecoil\b|新状态库|state\s+management\s+introduc/i,
@@ -77,6 +121,41 @@ function pathSpreadScore(paths) {
         .filter(Boolean));
     return tops.size;
 }
+/**
+ * Narrow-product-surface test for genuinely small topology. A task qualifies
+ * only when its non-auxiliary (product) paths are at most two and all share the
+ * same two-segment prefix — `src/components/Button.tsx` + `test/components/*`
+ * is narrow, while `src/components/**` + `src/pages/**` spans two product
+ * domains and is not. Direct source files (`src/a.tsx`) collapse to their
+ * directory so siblings stay narrow. This is the structured replacement for the
+ * fragile "single component / local style" keyword gate: it measures the actual
+ * delivery surface instead of relying on how the author worded the request.
+ */
+export function isNarrowProductSurface(paths) {
+    const auxiliaryRoot = /^(?:test|tests|__tests__|e2e|cypress|spec|specs|docs|documentation)$/i;
+    const product = paths
+        .map((raw) => raw.replace(/\\/g, "/").split("/").filter(Boolean))
+        .filter((segs) => segs.length > 0 && !auxiliaryRoot.test(segs[0] ?? ""));
+    if (product.length === 0 || product.length > 2)
+        return false;
+    // Every product path must name a concrete file or a concrete second-level
+    // directory. A top-level wide glob (`src/**`, `src/*`) covers the whole
+    // source tree and is NOT a small delivery surface.
+    for (const segs of product) {
+        const second = segs[1] ?? "";
+        if (!second || second === "*" || second === "**")
+            return false;
+    }
+    const prefixOf = (segs) => {
+        const second = segs[1] ?? "";
+        const secondIsFile = /\.[A-Za-z0-9]+$/.test(second);
+        return segs.length >= 2 && second && !secondIsFile
+            ? `${segs[0] ?? ""}/${segs[1]}`
+            : segs[0] ?? "";
+    };
+    const prefix = prefixOf(product[0] ?? []);
+    return product.every((segs) => prefixOf(segs) === prefix);
+}
 /**
  * Classify frontend task risk. High-risk signals always win over small keywords.
  * supervised / explicit high governance never selects small topology.
@@ -116,10 +195,14 @@ export function classifyFrontendRisk(input) {
         if (pattern.re.test(blob))
             smallHits.push(pattern.id);
     }
-    // small only if: no high-risk, paths concentrated, no remote API signals, not supervised
+    // small only if: no high-risk, non-empty concentrated paths, no remote API
+    // signals, not supervised, and not an explicitly large task. Keyword and
+    // explicit "small/low" complexity hints are no longer required — they were
+    // a fragile proxy for "this is genuinely a small change" and silently
+    // forced genuinely-small tasks with different wording into full gates.
     const hasApiSignal = /\b(api|fetch|axios|graphql|endpoint|远程|接口)\b/i.test(blob) &&
         !/\b(no\s+api|无接口|not-needed)\b/i.test(blob);
-    const concentrated = pathSpreadScore(paths) <= 1 && paths.length <= 4;
+    const narrowSurface = isNarrowProductSurface(paths);
     if (supervised) {
         rejectedSignals.push(...smallHits.map((id) => `small:${id}:blocked-by-supervised`));
         return {
@@ -142,19 +225,18 @@ export function classifyFrontendRisk(input) {
             forceFullGates: true,
         };
     }
-    if (smallHits.length > 0 &&
-        concentrated &&
+    if (narrowSurface &&
         !hasApiSignal &&
-        (input.complexity === "small" || smallHits.length >= 1)) {
+        (input.complexity ?? "").toLowerCase() !== "large") {
         return {
             selectedRisk: "small",
-            signals: smallHits,
+            signals: smallHits.length > 0 ? smallHits : ["structured-small"],
             rejectedSignals,
-            reason: `small signals without high-risk: ${smallHits.join(", ")}`,
+            reason: "narrow single-domain delivery surface without remote API, dependency, or escalation signals; small topology",
             forceFullGates: false,
         };
     }
-    if (smallHits.length > 0 && (hasApiSignal || !concentrated)) {
+    if (smallHits.length > 0 && (hasApiSignal || !narrowSurface)) {
         rejectedSignals.push(...smallHits.map((id) => `small:${id}:blocked-by-${hasApiSignal ? "api-signal" : "path-spread"}`));
         return {
             selectedRisk: "standard",

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

@@ -1,5 +1,5 @@
 import { createHash, randomUUID } from "node:crypto";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, readdir, rename, rm, readFile, 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";
@@ -229,7 +229,7 @@ export async function observeFrontendSession(input, execute) {
     await waitForWrite(save());
     return result;
 }
-export function summarizeFrontendSessions(receipts) {
+function uniqueFrontendSessions(receipts) {
     const byId = new Map();
     for (const receipt of receipts) {
         const previous = byId.get(receipt.identity.sessionId);
@@ -240,10 +240,124 @@ export function summarizeFrontendSessions(receipts) {
         if (!previous || difference > 0)
             byId.set(receipt.identity.sessionId, receipt);
     }
-    const unique = [...byId.values()];
+    return [...byId.values()];
+}
+export function summarizeFrontendSessions(receipts) {
+    const unique = uniqueFrontendSessions(receipts);
     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)) };
 }
+/** Read the persisted session receipts for one Plan node. This is deliberately
+ * an observation-only projection: missing or malformed receipts remain
+ * missing, never zero, so a canary cannot manufacture an improvement. */
+export async function readFrontendSessionBudgetReceipts(runDir, nodeId = "frontend-plan-pi") {
+    const root = path.join(runDir, nodeId);
+    const files = [];
+    const unreadable = [];
+    const visit = async (dir, insideBudget = false) => {
+        let entries;
+        try {
+            entries = await readdir(dir, { withFileTypes: true });
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                unreadable.push(dir);
+            return;
+        }
+        for (const entry of entries) {
+            const absolute = path.join(dir, entry.name);
+            if (entry.isDirectory() && (insideBudget || entry.name === "session-budget" || entry.name === "parallel" || /^coverage-\d+$/.test(entry.name)))
+                await visit(absolute, insideBudget || entry.name === "session-budget");
+            else if (insideBudget)
+                files.push(absolute);
+        }
+    };
+    await visit(root);
+    const receipts = [];
+    for (const file of [...files, ...unreadable].sort()) {
+        try {
+            const value = JSON.parse(await readFile(file, "utf8"));
+            if (!isCanaryReceipt(value))
+                throw new Error("Invalid session receipt");
+            receipts.push(value);
+        }
+        catch {
+            // Keep a visible incomplete receipt so canary aggregation cannot turn a
+            // truncated artifact into an apparent zero-cost improvement.
+            receipts.push({
+                schemaVersion: 1,
+                policyVersion: "frontend-session-observation-v1",
+                identity: { sessionId: `invalid:${file}`, phase: "unknown", scopeIds: [], taskId: null, runId: null, nodeId, attempt: null, sourceDigest: null, contractDigest: null },
+                startedAt: new Date(0).toISOString(), finishedAt: null, completion: "incomplete",
+                planned: { prompt: { sha256: "", chars: 0, bytes: 0, estimatedTokens: 0 }, userMessage: { sha256: "", chars: 0, bytes: 0, estimatedTokens: 0 }, toolSchemas: null, estimatorVersion: "unknown", capabilities: { ...frontendModelCapabilities(undefined), model: null }, unmeasuredComponents: [] },
+                actual: { ...collectFrontendUsage([]) }, attempts: [],
+                progress: { memoryCommittedDelta: null, durableCommittedDelta: null, failedRecords: null, duplicateRecords: null, durableSubmissions: null, durableReplacements: null, successfulReadBytes: null, duplicateReadBytes: null }, terminal: null,
+            });
+        }
+    }
+    return receipts;
+}
+export function summarizeFrontendPlanCanary(receipts) {
+    const unique = uniqueFrontendSessions(receipts);
+    const complete = unique.length > 0 && unique.every(receipt => isCanaryReceipt(receipt) && receipt.completion === "complete");
+    const known = (values, sum) => {
+        if (!complete || values.length === 0)
+            return null;
+        const present = values.filter((value) => value !== null && value !== undefined);
+        return present.length === values.length ? sum(present) : null;
+    };
+    return {
+        planModelRequests: known(unique.map((receipt) => receipt.actual.requestCount), (items) => items.reduce((total, value) => total + value, 0)),
+        planSessions: complete ? unique.length : null,
+        // Receipt envelope includes gaps and overlapping sessions only once. The
+        // run reader below replaces this with the authoritative node interval.
+        planWallClockMs: complete ? Math.max(...unique.map(r => Date.parse(r.finishedAt))) - Math.min(...unique.map(r => Date.parse(r.startedAt))) : null,
+        planTokens: known(unique.map((receipt) => receipt.actual.totalTokens), (items) => items.reduce((total, value) => total + value, 0)),
+        toolRejections: known(unique.map((receipt) => receipt.progress.failedRecords), (items) => items.reduce((total, value) => total + value, 0)),
+        retries: complete ? unique.reduce((total, receipt) => total + Math.max(0, receipt.attempts.length - 1), 0) : null,
+    };
+}
+/** Validate the fields consumed by aggregation before accessing nested values.
+ * Valid JSON with the wrong shape is missing evidence too. */
+function isCanaryReceipt(value) {
+    const r = record(value), identity = record(r.identity), actual = record(r.actual), progress = record(r.progress);
+    const nullableCount = (v) => v === null || (typeof v === "number" && Number.isFinite(v) && Number.isInteger(v) && v >= 0);
+    return r.schemaVersion === 1 && r.policyVersion === "frontend-session-observation-v1"
+        && typeof identity.sessionId === "string" && identity.sessionId.length > 0
+        && typeof r.startedAt === "string" && Number.isFinite(Date.parse(r.startedAt))
+        && (r.completion === "incomplete" || (r.completion === "complete" && typeof r.finishedAt === "string" && Date.parse(r.finishedAt) >= Date.parse(r.startedAt)))
+        && Array.isArray(r.attempts) && r.attempts.every(a => a !== null && typeof a === "object")
+        && nullableCount(actual.requestCount) && nullableCount(actual.totalTokens) && nullableCount(progress.failedRecords);
+}
+/** Read one frozen canary run. The optional artifact may add only run-level
+ * timing/review/recovery observations; Plan session counts, retries, tokens,
+ * request usage and tool rejections always come from session receipts. */
+export async function readFrontendPlanCanaryRunMetrics(runDir, nodeId = "frontend-plan-pi") {
+    const sessionMetrics = summarizeFrontendPlanCanary(await readFrontendSessionBudgetReceipts(runDir, nodeId));
+    let supplemental = {};
+    try {
+        const parsed = JSON.parse(await readFile(path.join(runDir, "frontend-plan-canary-metrics.json"), "utf8"));
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+            supplemental = parsed;
+        }
+    }
+    catch {
+        // Missing or malformed supplemental evidence remains unavailable.
+    }
+    const optionalNumber = (key) => {
+        const value = supplemental[key];
+        return typeof value === "number" && Number.isFinite(value) && value >= 0
+            ? value
+            : null;
+    };
+    return {
+        ...sessionMetrics,
+        dagWallClockMs: optionalNumber("dagWallClockMs"),
+        designReviewRejectRate: optionalNumber("designReviewRejectRate"),
+        finalReviewDefectRate: optionalNumber("finalReviewDefectRate"),
+        recoveryCount: optionalNumber("recoveryCount"),
+    };
+}