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

package/dist/workflows/dag/node-execution.js

@@ -12,11 +12,14 @@ import { buildDagNodePromptEnvelope, formatConvergenceFeedbackBlock, } from "./p
 import { persistLongNodeOutputArtifacts } from "./upstream-artifacts.js";
 import { materializeDeclaredArtifactFacts } from "./artifact-bindings.js";
 import { buildOutputLimitRecoverySection, loadBackendTestWriterProgressForRetry, } from "./backend-test-writer-completeness.js";
-import { computeBackoffDelayMs, isCanonicalFinalVerifyShellRetryCandidate, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, VERIFY_SHELL_RETRY_POLICY, } from "./retry-policy.js";
+import { computeBackoffDelayMs, isCanonicalFinalVerifyShellRetryCandidate, isRetryablePiFailureCategory, isSafeReadOnlyPiRetryCandidate, isTargetTemplateTransientRetryNode, isWriterEmptyDiffRetryCandidate, isWriterTransportRetryCandidate, projectFrontendNodeProtocolFailureReason, resolveFrontendPlanBackupRoute, resolveFrontendPlanRetryStep, VERIFY_SHELL_RETRY_POLICY, } from "./retry-policy.js";
 import { applyNodeActivity, evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
 import { buildProtocolRetryInstruction, normalizeReviewVerdictAfterRetries, parseJsonReviewVerdict, validateOutputProtocol, } from "./output-protocol.js";
 import { getStructuredContractValidator } from "./contract-output-registry.js";
 import "./contract-validator-registrations.js";
+import { computeNormalizedFailureFingerprint } from "./frontend-recovery-lineage.js";
+import { parseLedgerJson } from "../../task/source-prepare/ledger.js";
+import { readTypedEventStoreFromJsonl } from "./frontend-typed-event-store.js";
 import { allowedRepairReadPaths, auditRepairAttemptToolUse, buildStructuredOutputRepairPrompt, freezeStructuredOutputRepairContext, hasNonEmptyStructuredCandidate, isFrontendStructuredRepairSchemaId, isStructuredRepairableFailureCategory, persistStructuredAttemptRaw, sessionEventsByteLength, GOVERNANCE_BLOCKED_CATEGORY, STRUCTURED_REPAIR_EXHAUSTED_CATEGORY, } from "./structured-output-repair.js";
 import { readFrontendCanonicalCandidate } from "./frontend-implementation-contract.js";
 import { writeDagNodeJsonArtifact } from "../../infrastructure/harness/artifact-store.js";
@@ -237,9 +240,518 @@ function frontendStructuredArtifactRetryGuidance(schemaId) {
         "The contract JSON fields are the complete implementation plan. Do not emit a separate plan document, Markdown headings, bullets, plan prose, explanations, raw JSON, or any other fenced block.",
     ];
 }
-function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics) {
+const FRONTEND_PLAN_NODE_ID = "frontend-plan-pi";
+const COMPACT_RETRY_SECTION_MAX_CHARS = 1_200;
+const COMPACT_RETRY_TASK_MAX_CHARS = 4_800;
+/** Keep alias/field-shape remediation out of the initial Plan prompt. */
+function frontendPlanValidationRetryGuidance(reason) {
+    const guidance = [];
+    if (/notApplicableReason|uiState.*reason/i.test(reason)) {
+        guidance.push("For this retry, use uiStates[].notApplicableReason for a non-applicable state; omit expectedBehavior instead of supplying an empty value.");
+    }
+    if (/interaction.*(?:\bid\b|\bname\b)|requires non-empty interaction\.name/i.test(reason)) {
+        guidance.push("For this retry, use interactions[].name with non-empty trigger and expectedBehavior.");
+    }
+    if (/verificationTargets.*uiStates|uiStates.*verificationTargets/i.test(reason)) {
+        guidance.push("For this retry, provide verificationTargets[].uiStates as an array; use [] when the target has no named UI state.");
+    }
+    return guidance;
+}
+function compactRetryText(text, maxChars) {
+    if (text.length <= maxChars)
+        return text;
+    const headChars = Math.floor(maxChars * 0.78);
+    const tailChars = Math.max(0, maxChars - headChars - 52);
+    return `${text.slice(0, headChars)}\n… [omitted after context-overflow] …\n${text.slice(-tailChars)}`;
+}
+function compactRetrySection(prompt, name, maxChars) {
+    const match = prompt.match(new RegExp(`<${name}>([\\s\\S]*?)</${name}>`));
+    return compactRetryText(match?.[1]?.trim() ?? "(not available)", maxChars);
+}
+/**
+ * A context-overflow retry must not resend the full resolved skills, governance
+ * payload, repeated source excerpts, and upstream previews that caused the
+ * previous session to overflow. Keep the immutable node contract plus bounded
+ * objective/criteria/task excerpts; canonical artifacts remain readable by
+ * pointer from the retained task instructions.
+ */
+export function buildContextOverflowRetryPrompt(task, basePrompt) {
+    return [
+        "<compact_retry_context>",
+        "This is a fresh, compact retry after provider context-overflow. The original full prompt remains audit evidence but is intentionally not resent.",
+        "Do not re-read task sources, upstream stdout, skills, or full diff artifacts that are already represented by canonical artifacts. Start from the smallest retained artifact and expand only the exact file or diff fragment needed.",
+        "</compact_retry_context>",
+        `<dag_objective>\n${compactRetrySection(basePrompt, "dag_objective", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</dag_objective>`,
+        `<success_criteria>\n${compactRetrySection(basePrompt, "success_criteria", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</success_criteria>`,
+        `<global_constraints>\n${compactRetrySection(basePrompt, "global_constraints", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</global_constraints>`,
+        `<node_contract>\n${compactRetrySection(basePrompt, "node_contract", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</node_contract>`,
+        `<upstream_context>\n${compactRetrySection(basePrompt, "upstream_context", COMPACT_RETRY_SECTION_MAX_CHARS)}\n</upstream_context>`,
+        [
+            "<task>",
+            `Original task id: ${task.id}`,
+            compactRetrySection(basePrompt, "task", COMPACT_RETRY_TASK_MAX_CHARS),
+            "</task>",
+        ].join("\n"),
+    ].join("\n\n");
+}
+function isFrontendPlanLadderTask(task) {
+    return task.id === FRONTEND_PLAN_NODE_ID;
+}
+/** Contract node consumes the compiled ledger input; local predicate avoids a
+ * dag-pi-executor import cycle. */
+function isFrontendContractTypedNode(task) {
+    return task.id === "frontend-contract-pi";
+}
+/** Resolve the source-fidelity ledger path from a v2 source binding, refusing
+ * any path that escapes the workspace root (mirrors dag-pi-executor). */
+function resolveFrontendLedgerPath(sourceBinding, cwd) {
+    if (!sourceBinding || sourceBinding.schemaVersion !== 2) {
+        throw new Error(`frontend-contract-input-unavailable: sourceBinding v2 ledger required (got ${sourceBinding?.schemaVersion ?? "none"})`);
+    }
+    const absolutePath = path.resolve(cwd, sourceBinding.ledgerPath);
+    const workspaceRoot = path.resolve(cwd);
+    if (absolutePath !== workspaceRoot &&
+        !absolutePath.startsWith(`${workspaceRoot}${path.sep}`)) {
+        throw new Error(`frontend-contract-input-unavailable: ledger path escapes workspace root: ${sourceBinding.ledgerPath}`);
+    }
+    return absolutePath;
+}
+/** record_* submissions observed for the contract node in its session events. */
+const FRONTEND_CONTRACT_RECORD_TOOL_NAMES_LOCAL = new Set([
+    "record_requirement",
+    "record_constraint",
+    "record_evidence_expectation",
+    "record_handoff_intent",
+    "record_open_question",
+    "record_split_proposal",
+]);
+async function countContractRecordSubmissions(runDir, nodeId) {
+    const eventsPath = path.join(runDir, nodeId, "session-events.jsonl");
+    let count = 0;
+    try {
+        for (const line of (await readFile(eventsPath, "utf8")).split("\n")) {
+            if (!line.trim())
+                continue;
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            if (event !== null &&
+                typeof event === "object" &&
+                event.type === "tool_execution_start" &&
+                typeof event.toolName === "string" &&
+                FRONTEND_CONTRACT_RECORD_TOOL_NAMES_LOCAL.has(event.toolName)) {
+                count += 1;
+            }
+        }
+    }
+    catch {
+        // Missing events file = zero submissions.
+    }
+    return count;
+}
+/**
+ * Read the committed plan ledger snapshot for the ladder's "no new committed
+ * fact" check. The digest is over the sorted committed payload hashes, and
+ * `hasTerminalFact` reflects a committed `finalize_plan` terminal fact.
+ */
+async function readFrontendPlanCommittedSnapshot(runDir, nodeId) {
+    const records = await readTypedEventStoreFromJsonl(path.join(runDir, nodeId, "plan-typed-facts.jsonl"));
+    const committed = records.filter((record) => record.phase === "committed");
+    const digest = createHash("sha256")
+        .update(committed
+        .map((record) => record.payloadSha256)
+        .sort()
+        .join("\n"))
+        .digest("hex");
+    const hasTerminalFact = committed.some((record) => record.fact.kind === "finalize_plan");
+    return { digest, hasTerminalFact };
+}
+function planInputRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function planInputText(value, maxChars = 240) {
+    if (typeof value !== "string" || value.trim().length === 0)
+        return undefined;
+    const normalized = value.trim();
+    return normalized.length <= maxChars
+        ? normalized
+        : `${normalized.slice(0, maxChars - 1)}…`;
+}
+function planInputStrings(value) {
+    return Array.isArray(value)
+        ? value.filter((item) => typeof item === "string")
+        : [];
+}
+/** Input bound for the planner evidence block; protects the model input budget. */
+const FRONTEND_PLAN_INPUT_MAX_CHARS = 12_000;
+const FRONTEND_PLAN_INPUT_CAP_LADDER = [
+    { text: 240, array: 40 },
+    { text: 120, array: 20 },
+    { text: 60, array: 10 },
+    { text: 24, array: 4 },
+];
+/**
+ * Frozen requirement→PRD citation map for the plan review checklist: lets the
+ * model declare sourceRequirementIds whose section/line match the component
+ * purpose, so the runtime-derived specReference survives reviewer scrutiny
+ * (r12: 4 of 9 decision=new choices cited a mismatched PRD section).
+ */
+async function resolveComponentSourceCitations(spec, cwd) {
+    const binding = spec.sourceBinding;
+    if (!binding || binding.schemaVersion !== 2 || !binding.ledgerPath)
+        return new Map();
+    const absolutePath = path.resolve(cwd, binding.ledgerPath);
+    const workspaceRoot = path.resolve(cwd);
+    if (absolutePath !== workspaceRoot &&
+        !absolutePath.startsWith(`${workspaceRoot}${path.sep}`))
+        return new Map();
+    try {
+        const ledger = JSON.parse(await readFile(absolutePath, "utf8"));
+        const fragmentsById = new Map((ledger.fragments ?? []).map((fragment) => [fragment.id, fragment]));
+        const references = new Map();
+        for (const requirement of ledger.canonicalRequirements ?? []) {
+            const id = typeof requirement.id === "string" ? requirement.id : "";
+            if (!id)
+                continue;
+            const citations = (requirement.sourceFragmentIds ?? [])
+                .map((fragmentId) => fragmentsById.get(fragmentId))
+                .filter((fragment) => fragment !== undefined)
+                .map((fragment) => ({
+                fragmentId: fragment.id,
+                path: typeof fragment.path === "string" ? fragment.path : "",
+                section: typeof fragment.headingPath === "string"
+                    ? fragment.headingPath
+                    : "",
+                line: typeof fragment.lineRange?.start === "number"
+                    ? fragment.lineRange.start
+                    : undefined,
+            }));
+            if (citations.length > 0)
+                references.set(id, citations);
+        }
+        return references;
+    }
+    catch {
+        return new Map();
+    }
+}
+/** Input bound for the contract node's compiled ledger block. */
+const FRONTEND_CONTRACT_INPUT_MAX_CHARS = 12_000;
+/**
+ * Render the contract node's complete-but-bounded ledger handoff. The
+ * source-fidelity ledger already extracted canonical requirements with source
+ * spans; the contract node confirms and commits them incrementally through
+ * record_requirement instead of re-reading the raw source (extreme-environment:
+ * a small output window cannot absorb a full source re-read).
+ *
+ * Same shape guarantees as the plan input block: always valid JSON under the
+ * char bound, ids never drop, texts degrade through the cap ladder.
+ */
+export function renderFrontendContractInputContext(input) {
+    // Fragment bindings are ids, not prose: they are the one thing the contract
+    // must never lose. r6 regression — the last-resort degradation dropped
+    // sourceFragmentIds entirely, the model (correctly refusing to invent ids)
+    // committed empty bindings, and the plan compile failed the ledger-binding
+    // gate for every requirement. Bindings therefore bypass the cap ladder and
+    // every degradation level; only requirement TEXTS and fragment CONTEXT
+    // (path/headingPath) may degrade. Fragment context is rendered only for
+    // fragments actually referenced by a requirement and shrinks first.
+    const referencedFragmentIds = new Set(input.canonicalRequirements.flatMap((requirement) => planInputStrings(requirement.sourceFragmentIds)));
+    const referencedFragments = input.fragments.filter((fragment) => referencedFragmentIds.has(fragment.id));
+    const serializeAtCap = (cap) => JSON.stringify({
+        requirements: input.canonicalRequirements.map((requirement) => ({
+            id: requirement.id,
+            text: planInputText(requirement.text, cap.text),
+            sourceFragmentIds: planInputStrings(requirement.sourceFragmentIds),
+        })),
+        fragments: referencedFragments.map((fragment) => ({
+            id: fragment.id,
+            path: planInputText(fragment.path, 200),
+            headingPath: planInputText(fragment.headingPath, 120),
+            lineRange: fragment.lineRange,
+        })),
+    });
+    let serialized = serializeAtCap(FRONTEND_PLAN_INPUT_CAP_LADDER[0]);
+    for (const cap of FRONTEND_PLAN_INPUT_CAP_LADDER.slice(1)) {
+        if (serialized.length <= FRONTEND_CONTRACT_INPUT_MAX_CHARS)
+            break;
+        serialized = serializeAtCap(cap);
+    }
+    if (serialized.length > FRONTEND_CONTRACT_INPUT_MAX_CHARS) {
+        // Last resort: keep every requirement id AND its fragment bindings,
+        // degrade texts, and shrink referenced fragment context first (halve,
+        // then drop context fields, then drop the fragment list entirely).
+        // Requirement ids and sourceFragmentIds are never dropped.
+        let fragments = referencedFragments.map((fragment) => ({
+            id: fragment.id,
+            path: planInputText(fragment.path, 120),
+        }));
+        let requirements = input.canonicalRequirements.map((requirement) => {
+            const sourceFragmentIds = planInputStrings(requirement.sourceFragmentIds);
+            return {
+                id: requirement.id,
+                text: "(truncated)",
+                // Empty bindings carry no information; omit them so the payload
+                // stays inside the char bound when no requirement is bound.
+                ...(sourceFragmentIds.length > 0 ? { sourceFragmentIds } : {}),
+            };
+        });
+        let bounded = JSON.stringify({ degraded: "requirement-texts-truncated", requirements, fragments });
+        while (bounded.length > FRONTEND_CONTRACT_INPUT_MAX_CHARS && fragments.length > 0) {
+            fragments = fragments.slice(0, Math.floor(fragments.length / 2));
+            bounded = JSON.stringify({
+                degraded: "requirement-texts-truncated",
+                requirements,
+                fragments,
+            });
+        }
+        serialized = bounded;
+    }
+    return [
+        "<frontend_contract_input>",
+        "Canonical requirements extracted by the source-fidelity ledger, compiled by the runner. Treat them as the authoritative requirement inventory: confirm and commit each requirement through record_requirement (one per tool call); the ledger already binds source fragments, so do NOT re-read the raw source files.",
+        serialized,
+        "</frontend_contract_input>",
+    ].join("\n");
+}
+export async function buildFrontendContractInputContext(input) {
+    const ledger = parseLedgerJson(await readFile(input.ledgerPath, "utf8"));
+    return renderFrontendContractInputContext({
+        canonicalRequirements: ledger.canonicalRequirements.map((requirement) => ({
+            id: requirement.id,
+            text: requirement.text,
+            sourceFragmentIds: requirement.sourceFragmentIds ?? [],
+        })),
+        fragments: ledger.fragments.map((fragment) => ({
+            id: fragment.id,
+            path: fragment.path,
+            headingPath: fragment.headingPath,
+            lineRange: fragment.lineRange,
+        })),
+    });
+}
+/**
+ * Render the planner's complete-but-bounded evidence handoff from committed
+ * typed facts. It deliberately excludes upstream response prose and artifact
+ * paths: Contract and Scout have already established these facts, so Plan
+ * should decide and commit rather than spend another model turn reading them.
+ *
+ * The block is always valid JSON under the char bound: field texts shrink
+ * through a cap ladder before any fact is dropped, and the last-resort
+ * fallback keeps every requirement id (with `text: "(truncated)"`) while
+ * declaring the degradation, so the planner records targeted evidence gaps
+ * instead of receiving a silently corrupted tail.
+ */
+export function renderFrontendPlanInputContext(input) {
+    const committedFacts = (records) => records.flatMap((record) => record.phase === "committed" && planInputRecord(record.fact)
+        ? [record.fact]
+        : []);
+    const contractFacts = committedFacts(input.contractRecords);
+    const scoutFacts = committedFacts(input.scoutRecords);
+    const requirements = contractFacts
+        .filter((fact) => fact.kind === "requirement" && fact.origin === "contract")
+        .map((fact) => ({
+        id: planInputText(fact.id, 80),
+        text: planInputText(fact.text),
+        sourceFragmentIds: planInputStrings(fact.sourceFragmentIds),
+    }))
+        .filter((fact) => fact.id !== undefined);
+    const targetSurface = scoutFacts
+        .filter((fact) => fact.kind === "target-surface" && fact.origin === "scout")
+        .map((fact) => ({
+        completeness: fact.completeness,
+        entrypoint: fact.entrypoint,
+        routeOrMount: fact.routeOrMount,
+        implementationPaths: fact.implementationPaths,
+        testPaths: fact.testPaths,
+        dataSource: fact.dataSource,
+        allowedPathConflicts: fact.allowedPathConflicts,
+        unresolvedPaths: fact.unresolvedPaths,
+    }));
+    const designEvidence = scoutFacts
+        .filter((fact) => fact.kind === "design-evidence" && fact.origin === "scout")
+        .map((fact) => ({
+        source: fact.source,
+        paths: fact.paths,
+        conflicts: fact.conflicts,
+    }));
+    // Reviewer-rubric scaffold: the design reviewer re-runs the design-policy
+    // checks on the committed facts, so publish the checklist to the producer.
+    // Requirements whose contract evidence expects behavioural verification are
+    // enumerated explicitly — those are the slots the reviewer finds missing
+    // when the plan models interactions ad hoc (r8/r9 findings).
+    const behaviorRequiredIds = requirements
+        .filter((requirement) => {
+        const fact = contractFacts.find((candidate) => candidate.kind === "requirement" &&
+            candidate.origin === "contract" &&
+            candidate.id === requirement.id);
+        const evidence = fact?.evidence;
+        return evidence?.behavior === "required";
+    })
+        .map((requirement) => requirement.id);
+    const serializeAtCap = (cap) => JSON.stringify({
+        requirements: requirements.map((requirement) => ({
+            id: requirement.id,
+            text: planInputText(requirement.text, cap.text),
+            sourceFragmentIds: planInputStrings(requirement.sourceFragmentIds).slice(0, cap.array),
+        })),
+        targetSurface: targetSurface.map((surface) => ({
+            completeness: planInputText(surface.completeness, 32),
+            entrypoint: planInputText(surface.entrypoint, cap.text),
+            routeOrMount: planInputText(surface.routeOrMount, cap.text),
+            implementationPaths: planInputStrings(surface.implementationPaths).slice(0, cap.array),
+            testPaths: planInputStrings(surface.testPaths).slice(0, cap.array),
+            dataSource: planInputText(surface.dataSource, cap.text),
+            allowedPathConflicts: planInputStrings(surface.allowedPathConflicts).slice(0, cap.array),
+            unresolvedPaths: planInputStrings(surface.unresolvedPaths).slice(0, cap.array),
+        })),
+        designEvidence: designEvidence.map((evidence) => ({
+            source: planInputText(evidence.source, cap.text),
+            paths: planInputStrings(evidence.paths).slice(0, cap.array),
+            conflicts: planInputStrings(evidence.conflicts).slice(0, cap.array),
+        })),
+    });
+    let serialized = serializeAtCap(FRONTEND_PLAN_INPUT_CAP_LADDER[0]);
+    for (const cap of FRONTEND_PLAN_INPUT_CAP_LADDER.slice(1)) {
+        if (serialized.length <= FRONTEND_PLAN_INPUT_MAX_CHARS)
+            break;
+        serialized = serializeAtCap(cap);
+    }
+    if (serialized.length > FRONTEND_PLAN_INPUT_MAX_CHARS) {
+        // Last resort: keep every requirement id (ids are short and the plan
+        // prompt separately lists them) but drop their texts, shrink scout facts
+        // to the minimum, and declare the degradation instead of corrupting JSON.
+        let fallback = {
+            degraded: "requirement-texts-truncated",
+            requirements: requirements.map((requirement) => ({
+                id: requirement.id,
+                text: "(truncated)",
+            })),
+            targetSurface: targetSurface.map((surface) => ({
+                completeness: planInputText(surface.completeness, 32),
+                implementationPaths: planInputStrings(surface.implementationPaths).slice(0, FRONTEND_PLAN_INPUT_CAP_LADDER[3].array),
+            })),
+            designEvidence: [],
+        };
+        let bounded = JSON.stringify(fallback);
+        let keep = fallback.requirements.length;
+        while (bounded.length > FRONTEND_PLAN_INPUT_MAX_CHARS &&
+            keep > 0) {
+            keep = Math.max(0, Math.floor(keep / 2));
+            fallback = { ...fallback, requirements: fallback.requirements.slice(0, keep) };
+            bounded = JSON.stringify({
+                ...fallback,
+                requirementIdsTruncated: keep < requirements.length,
+            });
+        }
+        serialized = bounded;
+    }
+    const checklistLines = [
+        "1. Every interaction you record needs a uiComponentChoices entry whose purpose equals the interaction name, or one decision=reuse-existing choice covering behavioural interactions.",
+        "2. Every applicable UI state needs a purpose-matching component choice or a stylingStrategy.",
+        "3. Every requirement marked (behavior) below needs modelled interactions plus at least one verification target that references it.",
+        "4. targets.files must name the concrete deliverable files; never leave the scope broader than the frozen requirements state.",
+        "5. Verification targets may only reference UI states and requirements you actually recorded (the record_* tools reject unknown references).",
+        `Requirements requiring behavioural coverage: ${behaviorRequiredIds.length > 0 ? behaviorRequiredIds.join(", ") : "(none)"}`,
+        "6. A decision=new component must declare sourceRequirementIds and pass sourceFragmentId for the frozen PRD fragment whose section matches the component's purpose — the runtime validates that binding and derives specReference (path/section/line); the reviewer checks purpose↔citation consistency.",
+        ...[...input.componentSourceCitations ?? []]
+            .filter(([id]) => behaviorRequiredIds.includes(id))
+            .flatMap(([id, citations]) => citations.map((citation) => `   ${id} + ${citation.fragmentId} → ${citation.section}${citation.line ? ` (line ${citation.line})` : ""}`)),
+    ];
+    return [
+        "<frontend_plan_input>",
+        "Committed Contract/Scout facts, compiled by the runner. Treat them as the complete planning evidence.",
+        serialized,
+        "Do not read upstream artifacts, task sources, or repository files. If this input cannot support a decision, record a genuine evidence gap.",
+        "</frontend_plan_input>",
+        "<plan_review_checklist>",
+        "The design reviewer re-runs these exact checks on the committed facts; satisfy every line before finalize_plan:",
+        ...checklistLines,
+        "</plan_review_checklist>",
+    ].join("\n");
+}
+export async function buildFrontendPlanInputContext(runDir, componentSourceCitations) {
+    const contractFactsPath = path.join(runDir, "frontend-contract-pi", "contract-typed-facts.jsonl");
+    const scoutFactsPath = path.join(runDir, "frontend-scout-pi", "scout-typed-facts.jsonl");
+    let contractRecords;
+    let scoutRecords;
+    try {
+        [contractRecords, scoutRecords] = await Promise.all([
+            readTypedEventStoreFromJsonl(contractFactsPath),
+            readTypedEventStoreFromJsonl(scoutFactsPath),
+        ]);
+    }
+    catch (error) {
+        // A missing/unreadable upstream store is a broken pipeline, not an
+        // evidence gap; fail before spending a model turn on a prompt that
+        // forbids reading anything.
+        throw new Error(`frontend-plan-input-unavailable: cannot read committed typed facts (${error instanceof Error ? error.message : String(error)})`);
+    }
+    const committedCount = [...contractRecords, ...scoutRecords].filter((record) => record.phase === "committed").length;
+    if (committedCount === 0) {
+        throw new Error(`frontend-plan-input-unavailable: no committed Contract/Scout facts in ${contractFactsPath} / ${scoutFactsPath}`);
+    }
+    return renderFrontendPlanInputContext({
+        contractRecords,
+        scoutRecords,
+        componentSourceCitations,
+    });
+}
+export function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics, frontendPlanRetryStep) {
     if (attemptNumber <= 1)
         return basePrompt;
+    // Context overflow is a transport/session failure, not a plan-protocol
+    // failure. It must take precedence over the plan retry ladder so every
+    // retry, including a repeated plan overflow, starts from the compact
+    // envelope rather than re-sending the original prompt.
+    if (previousFailureCategory === "context-overflow") {
+        return [
+            buildContextOverflowRetryPrompt(task, basePrompt),
+            "",
+            "<retry_instruction>",
+            "The previous attempt exceeded the provider context window. This retry starts a fresh session: keep the evidence surface narrow.",
+            "Do not re-read task sources, upstream stdout, skills, or full diff artifacts that are already represented by the canonical contract/review context. Read the smallest relevant artifact first, then only the specific source file or diff fragment needed to decide a finding.",
+            "Do not read artifacts/diff_patch.patch in full. For frontend review, read the bounded diff summary and then at most the specific per-file diff fragments it identifies, in part order.",
+            "Use concise tool calls and finish the required terminal/output protocol as soon as the evidence is sufficient.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (frontendPlanRetryStep === "compact-terminal-first") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Frontend plan retry ladder step: compact-terminal-first.",
+            "Do NOT rewrite the narrative. Only adopt already staged/quarantined fresh facts, fill the missing required facts, then call finalize_plan exactly once.",
+            "Keep the existing committed ledger intact; do not re-derive already committed facts.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (frontendPlanRetryStep === "bounded-tool-only") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Frontend plan retry ladder step: bounded-tool-only.",
+            "Reduce reasoning and wall-clock time. Use only read / fact / terminal tools and only for the necessary missing facts, then call finalize_plan exactly once.",
+            "Do not expand scope or re-derive already committed facts.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (frontendPlanRetryStep === "backup-model") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Frontend plan retry ladder step: backup-model.",
+            "A backup provider/model route was selected after repeated non-converging failures. Re-derive only the missing committed facts, then call finalize_plan exactly once; do not repeat the failed strategy.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory === "protocol-invalid" &&
         task.outputProtocol &&
         previousProtocolReason) {
@@ -249,9 +761,65 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             buildProtocolRetryInstruction(task.outputProtocol, previousProtocolReason),
         ].join("\n");
     }
+    if (previousFailureCategory === "review-terminal-missing") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "The review emitted a verdict in response text but never committed the authoritative typed terminal tool call (approve_review / request_review_changes). The response text is NOT the authority: no branch or gate reads it.",
+            "Call exactly one typed terminal tool to finish: approve_review (implementation passes, no Critical/Important findings) or request_review_changes (with typed issueCategory, at least one evidenceRef, and non-empty findings). Do not repeat the review analysis; commit the terminal tool once and stop.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
+    if (previousFailureCategory === "read-burst") {
+        if (task.id !== FRONTEND_PLAN_NODE_ID) {
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "The previous attempt exceeded its read budget. Start a fresh, evidence-minimal pass: do not re-read task sources, upstream stdout, skills, or full diff artifacts already represented by a canonical context artifact.",
+                "Read the smallest relevant summary first, then only the specific source file or diff fragment needed for the required decision. Finish the required terminal/output protocol as soon as evidence is sufficient.",
+                "</retry_instruction>",
+            ].join("\n");
+        }
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "Previous plan attempt issued too many read-only tool calls (read/grep/ls/find) and blew up the context window. Trust the upstream frontend-contract-pi typed requirement facts and frontend-scout-pi target surface already provided — do NOT re-read contract/scout stdout, PRD/source files, or component sources you already inspected.",
+            "Minimize discovery reads: only read what you genuinely need, once. Commit record_plan_requirement / record_plan_verification_target / record_* facts directly from the facts already in context (one tool call per message), then call finalize_plan exactly once.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory === "invalid-output" &&
         task.structuredContractOutput &&
         previousProtocolReason) {
+        // The frontend plan node's compile authority is the committed typed
+        // ledger, not a fenced JSON text artifact: its retry guidance must
+        // direct the model to re-commit corrected record_* facts and
+        // finalize_plan. The legacy full-contract JSON guidance below applies
+        // only to nodes whose authority is still a text contract artifact.
+        if (task.structuredContractOutput.schemaId ===
+            "frontend-implementation-contract-plan-patch-v1") {
+            const splitGuidance = /write-set-too-large|split the task/.test(previousProtocolReason ?? "")
+                ? [
+                    "",
+                    "The writeSet is too large for one implement node. Do NOT delete implementation files to squeeze under the limit — that drops required work. Split the task via record_split_proposal (or narrow targets.files to a genuine subset) so each implement node stays bounded; the full file set must remain covered across the split.",
+                ]
+                : [];
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "Previous plan ledger facts failed canonical contract validation:",
+                previousProtocolReason,
+                "Fix the reported violations by re-committing corrected record_* facts and calling finalize_plan exactly once. The committed typed ledger is the only compile authority.",
+                "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
+                ...frontendPlanValidationRetryGuidance(previousProtocolReason),
+                ...splitGuidance,
+                "</retry_instruction>",
+            ].join("\n");
+        }
         return [
             basePrompt,
             "",
@@ -263,8 +831,31 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
             "</retry_instruction>",
         ].join("\n");
     }
+    if (previousFailureCategory === "invalid-output" &&
+        task.id === "frontend-scout-pi") {
+        return [
+            basePrompt,
+            "",
+            "<retry_instruction>",
+            "The previous Scout attempt did not commit a complete, runtime-evidenced target surface.",
+            "Search the repository only as needed to establish the real entrypoint, implementation ownership, and applicable test path. Commit record_target_surface with completeness=complete and unresolvedPaths=[] only after at least one named target has fresh runtime evidence. If ownership truly cannot be established, record completeness=blocked with each unresolved path; do not make Plan discover it.",
+            "</retry_instruction>",
+        ].join("\n");
+    }
     if (previousFailureCategory === "structured-output-truncated" &&
         task.structuredContractOutput) {
+        if (task.structuredContractOutput.schemaId ===
+            "frontend-implementation-contract-plan-patch-v1") {
+            return [
+                basePrompt,
+                "",
+                "<retry_instruction>",
+                "Previous attempt was truncated by the provider (stopReason=length) before the plan facts were fully committed.",
+                "Re-commit the missing record_* facts and call finalize_plan exactly once; the committed typed ledger is the only compile authority. Do NOT re-read contract/scout outputs or source files — use the facts already in context. Commit record_* facts one tool call per message, then finalize_plan immediately.",
+                "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
+                "</retry_instruction>",
+            ].join("\n");
+        }
         return [
             basePrompt,
             "",
@@ -371,6 +962,18 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
     }
     if (task.outputMode === "structured-required") {
         if (task.structuredContractOutput) {
+            if (task.structuredContractOutput.schemaId ===
+                "frontend-implementation-contract-plan-patch-v1") {
+                return [
+                    basePrompt,
+                    "",
+                    "<retry_instruction>",
+                    "Previous attempt exceeded the structured output size limit.",
+                    "Re-commit corrected record_* facts and call finalize_plan exactly once; the committed typed ledger is the only compile authority.",
+                    "Do not emit a fenced JSON contract, protected skeleton fields, or an openspec-citations block; narrative JSON is not validated and wastes the output budget.",
+                    "</retry_instruction>",
+                ].join("\n");
+            }
             return [
                 basePrompt,
                 "",
@@ -822,9 +1425,41 @@ export async function executeDagNode(input) {
         await failSkillSnapshot(error);
         return;
     }
+    if (isFrontendPlanLadderTask(task)) {
+        let planInputContext;
+        try {
+            const componentSourceCitations = await resolveComponentSourceCitations(spec, cwd);
+            planInputContext = await buildFrontendPlanInputContext(runDir, componentSourceCitations);
+        }
+        catch (error) {
+            await failBeforePrompt(error, "frontend-plan-input-unavailable");
+            return;
+        }
+        prompt = `${prompt}\n\n${planInputContext}`;
+    }
+    if (isFrontendContractTypedNode(task)) {
+        // Extreme-environment input handoff: compile the ledger's canonical
+        // requirements into a bounded block so the contract node never re-reads
+        // the raw source (mirrors the plan node's compiled input; its tool set
+        // is record_* + finalize_contract, no read tools).
+        let contractInputContext;
+        try {
+            const ledgerPath = resolveFrontendLedgerPath(spec.sourceBinding, cwd);
+            contractInputContext = await buildFrontendContractInputContext({
+                ledgerPath,
+            });
+            prompt = `${prompt}\n\n${contractInputContext}`;
+        }
+        catch (error) {
+            // Ledger unreadable is a broken pipeline: fail before spending a
+            // model turn on a prompt that forbids reading anything.
+            await failBeforePrompt(error, "frontend-contract-input-unavailable");
+            return;
+        }
+    }
     node.resolvedSkills = resolvedSkills;
     await writeNodeSkillArtifacts(runDir, nodeId, resolvedSkills);
-    const model = resolveModelForTask(task, spec.executorModels);
+    let model = resolveModelForTask(task, spec.executorModels);
     let thinking;
     if (task.executor === "pi") {
         try {
@@ -851,6 +1486,9 @@ export async function executeDagNode(input) {
     const attempts = [];
     let totalAttemptWallDurationMs = 0;
     let totalBackoffMs = 0;
+    const frontendPlanLadderEnabled = isFrontendPlanLadderTask(task);
+    let frontendPlanRetryStep = "normal";
+    const frontendPriorFingerprints = [];
     const livenessPolicy = resolveLivenessPolicy(spec.defaults?.livenessPolicy, task.livenessPolicy);
     /**
      * Attempt-fenced, throttled activity sink. Late events from a previous
@@ -894,6 +1532,13 @@ export async function executeDagNode(input) {
         const attemptStartedAt = new Date().toISOString();
         node.currentAttempt = attemptNumber;
         node.livenessStatus = "active";
+        const beforeCommittedDigest = frontendPlanLadderEnabled
+            ? (await readFrontendPlanCommittedSnapshot(runDir, nodeId)).digest
+            : undefined;
+        if (frontendPlanLadderEnabled &&
+            frontendPlanRetryStep === "backup-model") {
+            model = resolveModelForTask(task, spec.executorModels);
+        }
         // Capture the session-events.jsonl length BEFORE the executor appends this
         // attempt's events, so the post-attempt repair tool audit can be scoped to
         // exactly this attempt's segment (B1: earlier attempts legitimately use
@@ -922,8 +1567,15 @@ export async function executeDagNode(input) {
                 (acc[i.path] ??= []).push(i.detail);
                 return acc;
             }, {});
-            let attemptPrompt = buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics);
+            let attemptPrompt = buildAttemptPrompt(task, prompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics, frontendPlanRetryStep);
             if (attemptNumber > 1 &&
+                // The plan node (frontend-plan-pi) is a typed-facts ladder task:
+                // its retry is driven by the §5.1 ladder (compact-terminal-first
+                // / backup-model) and its compile authority is the committed
+                // ledger — never the legacy frozen fenced-JSON repair. The
+                // frozen repair path below applies only to non-ladder
+                // structured nodes whose output authority is a text artifact.
+                !frontendPlanLadderEnabled &&
                 isFrontendStructuredRepairSchemaId(task.structuredContractOutput?.schemaId) &&
                 isStructuredRepairableFailureCategory(previousFailureCategory) &&
                 (await hasNonEmptyStructuredCandidate({
@@ -1103,6 +1755,28 @@ export async function executeDagNode(input) {
                 prompt: promptRestartCandidate,
             });
         }
+        // C: contract incremental-progress guard. A failed contract attempt that
+        // committed zero record_* submissions is a "no-progress" failure, not an
+        // opaque timeout/error: normalize it to empty-output so the retryPolicy
+        // retries with the incremental-commit discipline instead of burning the
+        // remaining attempts on the same stalled behavior.
+        if (isFrontendContractTypedNode(task) &&
+            !result.ok &&
+            retryPolicy !== undefined) {
+            const submissions = await countContractRecordSubmissions(runDir, nodeId);
+            if (submissions === 0) {
+                result = {
+                    ...result,
+                    failureCategory: "empty-output",
+                    stderr: [
+                        result.stderr,
+                        "contract attempt failed with zero record_* submissions; retrying with incremental-commit discipline (one record_* call per message, starting from the first tool call)",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                };
+            }
+        }
         const attemptRecord = {
             attempt: attemptNumber,
             startedAt: attemptStartedAt,
@@ -1129,6 +1803,60 @@ export async function executeDagNode(input) {
             await writeDagNodeJsonArtifact(runDir, nodeId, `attempt-${attemptNumber}.json`, attemptRecord);
             node.attempts = attempts;
         }
+        // Frontend plan retry ladder: project the 7-value protocol failure
+        // reason, detect new committed facts, and escalate instead of re-running.
+        if (frontendPlanLadderEnabled && !result.ok) {
+            const afterSnapshot = await readFrontendPlanCommittedSnapshot(runDir, nodeId);
+            const hasNewCommittedFact = beforeCommittedDigest !== undefined &&
+                afterSnapshot.digest !== beforeCommittedDigest;
+            const protocolReason = projectFrontendNodeProtocolFailureReason({
+                failureCategory: result.failureCategory,
+                stopReason: result.stopReason,
+                assistantText: result.assistantText ?? result.stdout,
+                hasTerminalFact: afterSnapshot.hasTerminalFact,
+            });
+            const fingerprint = computeNormalizedFailureFingerprint({
+                failureOwner: "plan",
+                protocolFailureReason: protocolReason ?? "",
+            });
+            const backupRoute = resolveFrontendPlanBackupRoute(protocolReason);
+            const nextStep = resolveFrontendPlanRetryStep({
+                currentStep: frontendPlanRetryStep,
+                protocolFailureReason: protocolReason,
+                hasNewCommittedFact,
+                fingerprint,
+                priorFingerprints: frontendPriorFingerprints,
+                backupRouteAvailable: backupRoute.ok,
+            });
+            frontendPriorFingerprints.push(fingerprint);
+            frontendPlanRetryStep = nextStep;
+            if (nextStep === "unsupported-provider-capability") {
+                result = {
+                    ...result,
+                    ok: false,
+                    failureCategory: "unsupported-provider-capability",
+                    stderr: [
+                        result.stderr,
+                        "frontend plan retry ladder: no compatible provider capability route for the protocol failure reason",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                };
+            }
+            else if (nextStep === "non-converging") {
+                result = {
+                    ...result,
+                    ok: false,
+                    failureCategory: "non-converging",
+                    stderr: [
+                        result.stderr,
+                        "frontend plan retry ladder: repeated failure fingerprint with no new committed fact",
+                    ]
+                        .filter(Boolean)
+                        .join("\n"),
+                };
+            }
+        }
         // Reflect the latest attempt on the node so progress is observable,
         // but keep node.status RUNNING while retry is still possible.
         node.durationMs = durationBetween(node.startedAt, attemptFinishedAt);