@tea-agent/loop-agent 0.41.1-beta.0 → 0.42.0-next.1

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

@@ -14,19 +14,19 @@ export const FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH = ".runtime/import-manif
 /** Staging directory prefix under `active/` for in-flight child materialization. */
 export const FRONTEND_RECOVERY_STAGING_PREFIX = ".frontend-recovery-staging-";
 export function deriveFrontendRecoveryFailureSource(result) {
-    if (result.failureSource === "frontend-plan-pi" ||
-        result.failureSource === "frontend-design-policy-shell" ||
-        result.failureSource === "frontend-implement-pi" ||
-        result.failureSource === "frontend-verify-shell") {
-        return result.failureSource;
+    if (result.selectedPlanNodeId === "frontend-plan-revision-pi") {
+        return "frontend-plan-revision-pi";
     }
-    return "frontend-writer-admission-shell";
+    if (result.selectedPlanNodeId === "frontend-plan-pi") {
+        return "frontend-plan-pi";
+    }
+    return "frontend-prewrite-gate-shell";
 }
 /**
  * Compute the frontend candidate-continuation reset partition:
- * - `frontend-plan-pi` failure → reset plan + design-review + policy/admission (+ descendants);
- * - `frontend-design-policy-shell` failure → reset policy/admission (+ descendants);
- * - admission/design-review failure → reset writer admission (+ descendants);
+ * - `frontend-plan-pi` failure → reset plan + design-review + prewrite (+ descendants);
+ * - `frontend-plan-revision-pi` failure → reset revision + final-review + prewrite (+ descendants);
+ * - prewrite-only materialization → reset prewrite (+ descendants), reuse verified plan/review.
  *
  * Everything upstream of the failure source is imported as verified parent facts.
  */
@@ -55,14 +55,7 @@ export function computeFrontendWriterRecoveryPlan(input) {
     });
 }
 function computeFrontendRecoveryPlanForSource(input) {
-    // Verification failure means the implementation did not pass the frozen
-    // verification commands / trace. Resetting only verify + its descendants
-    // would re-run the same failing checks against the same implementation, so
-    // reset from implement: the recovery re-implements and re-verifies.
-    const resetRoot = input.failureSource === "frontend-verify-shell"
-        ? "frontend-implement-pi"
-        : input.failureSource;
-    const resetNodeIds = computeResetClosure(input.spec, resetRoot);
+    const resetNodeIds = computeResetClosure(input.spec, input.failureSource);
     const resetSet = new Set(resetNodeIds);
     const importedNodeIds = input.spec.tasks
         .map((task) => task.id)

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

@@ -6,7 +6,7 @@ import { FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, FRONTEND_RECOVERY_INTENT_RE
 import { dagRunDirExists, getDagRunDir, readDagRunSpec, readDagRunState, transferDagRunDir, writeDagRunState, } from "./lifecycle.js";
 import { buildDagRunId } from "./runner.js";
 import { prepareRunDir, writeNodeRecord } from "./run-store.js";
-import { FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT, readFrontendWriterAdmissionResult, } from "./scheduler.js";
+import { FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, readFrontendPrewriteResult, } from "./scheduler.js";
 import { topoSortToRanks } from "./topo.js";
 /**
  * Candidate-continuation child creation kernel (phase 3b).
@@ -19,8 +19,8 @@ import { topoSortToRanks } from "./topo.js";
  * phase=child-running. Scheduling/execution of the child is phase 3c and out
  * of scope here.
  */
-/** Canonical contract artifact default location; overridden by the design
- * policy shell's configured outputDir/artifactName when present. */
+/** Canonical contract artifact default location; overridden by the prewrite
+ * gate's configured outputDir/artifactName when present. */
 const FRONTEND_CANONICAL_CONTRACT_DEFAULT_REL_PATH = "contracts/frontend-implementation-contract.json";
 function resolveDeps(deps) {
     return {
@@ -62,9 +62,6 @@ function isValidFrontendRecoveryMarker(raw) {
  * Read + validate the activation marker. Missing or invalid markers return
  * `undefined` so the phase-3c gate and tests can treat an unmarked active
  * child as not executable (AC-2 / AC-5d).
- *
- * @deprecated Read-only/scheduler compatibility only; the runner no longer
- * uses activation markers as the authoritative recovery entry point.
  */
 export async function readFrontendRecoveryMarker(parentRunDir, requestId) {
     let raw;
@@ -82,8 +79,8 @@ export async function readFrontendRecoveryMarker(parentRunDir, requestId) {
     return raw;
 }
 function classifyFrontendFactKind(nodeId) {
-    if (/admission|design-policy|verify|policy/i.test(nodeId))
-        return "gate";
+    if (/prewrite/i.test(nodeId))
+        return "prewrite";
     if (/scout/i.test(nodeId))
         return "scout";
     if (/contract/i.test(nodeId))
@@ -94,9 +91,9 @@ function classifyFrontendFactKind(nodeId) {
 }
 function resolveCanonicalContractRelPath(spec) {
     for (const task of spec.tasks) {
-        const policy = task.shell?.frontendDesignPolicy;
-        if (policy) {
-            return path.posix.join(policy.outputDir, policy.artifactName);
+        const gate = task.shell?.frontendPrewriteGate;
+        if (gate) {
+            return path.posix.join(gate.outputDir, gate.artifactName);
         }
     }
     return FRONTEND_CANONICAL_CONTRACT_DEFAULT_REL_PATH;
@@ -289,15 +286,15 @@ async function materializeChildStaging(input) {
         });
     }
     else {
-        const admissionRead = await readFrontendWriterAdmissionResult(parentRunDir);
-        if (!admissionRead.ok) {
-            throw new Error(admissionRead.reason);
+        const prewriteRead = await readFrontendPrewriteResult(parentRunDir);
+        if (!prewriteRead.ok) {
+            throw new Error(prewriteRead.reason);
         }
         plan = computeFrontendRecoveryPlan({
             spec: parentSpec,
             parentRunId,
             requestId,
-            result: admissionRead.result,
+            result: prewriteRead.result,
         });
     }
     const { ranks } = topoSortToRanks(parentSpec);
@@ -333,17 +330,17 @@ async function materializeChildStaging(input) {
             throw new Error(`node ${task.id} missing from frontend recovery plan partition`);
         }
     }
-    // Canonical contract + writer-admission identity facts are copied alongside
+    // Canonical contract + prewrite-result identity facts are copied alongside
     // the per-node facts so reset nodes can re-read them (AC-4).
     const canonicalContract = await copyArtifactVerified({
         parentRunDir,
         newRunDir: stagingDir,
         relativePath: resolveCanonicalContractRelPath(parentSpec),
     });
-    const writerAdmissionResult = await copyArtifactVerified({
+    const prewriteResult = await copyArtifactVerified({
         parentRunDir,
         newRunDir: stagingDir,
-        relativePath: FRONTEND_WRITER_ADMISSION_RESULT_ARTIFACT,
+        relativePath: FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT,
     });
     const childState = {
         version: 1,
@@ -380,9 +377,9 @@ async function materializeChildStaging(input) {
             relativePath: canonicalContract.destinationRelativePath,
             sha256: canonicalContract.sha256,
         },
-        writerAdmissionResult: {
-            relativePath: writerAdmissionResult.destinationRelativePath,
-            sha256: writerAdmissionResult.sha256,
+        prewriteResult: {
+            relativePath: prewriteResult.destinationRelativePath,
+            sha256: prewriteResult.sha256,
         },
         importedFacts,
     };
@@ -420,9 +417,6 @@ async function verifyThreeWayConsistency(input) {
  * intent. Single-writer: the recovery coordinator is the only caller.
  * Fail-closed on revision drift, missing intent, unreadable prewrite result,
  * hash mismatch, marker-write failure, or consistency failure.
- *
- * @deprecated The M6 operation controller is the authoritative recovery loop;
- * this kernel is retained only for read-only/scheduler compatibility.
  */
 export async function stageRecoveryChild(options) {
     const { cwd, parentRunId } = options;
@@ -458,15 +452,8 @@ export async function stageRecoveryChild(options) {
         }
     }
     // Derive the childRunId exactly once; replay always reuses a reserved id.
-    // buildDagRunId is deterministic for the same task title on the same day. A
-    // recovery child must never reuse its still-active parent directory, or the
-    // staging path aliases the parent and the required import manifest is absent.
-    const childRunId = recovery.childRunId ?? await (async () => {
-        const generatedChildRunId = await (options.buildChildRunId ?? buildDagRunId)(parentSpec, cwd);
-        return generatedChildRunId === parentRunId
-            ? `${generatedChildRunId}-recovery-${requestId.slice(0, 8)}`
-            : generatedChildRunId;
-    })();
+    const childRunId = recovery.childRunId ??
+        (await (options.buildChildRunId ?? buildDagRunId)(parentSpec, cwd));
     // Orphan staging cleanup (D4.3): remove any in-flight staging dir for this id.
     const activeRootDir = getDagRunDir(cwd, "active", "");
     const stagingDir = path.join(activeRootDir, `${FRONTEND_RECOVERY_STAGING_PREFIX}${childRunId}`);

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

@@ -1,5 +1,10 @@
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
 import { z } from "zod";
-import { FRONTEND_NO_VERIFICATION_MARKER_TEXT, } from "./frontend-verification-trace.js";
+import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID, frontendImplementationContractSchema, } from "./frontend-implementation-contract.js";
+import { FRONTEND_NO_VERIFICATION_MARKER_TEXT, FRONTEND_VERIFICATION_UNAVAILABLE_MESSAGE, } from "./frontend-verification-trace.js";
+export const FRONTEND_REPAIR_ASSESSMENT_SCHEMA_ID = "frontend-repair-assessment-v1";
 export const frontendRepairFailureClassSchema = z.enum([
     "typecheck",
     "build",
@@ -24,6 +29,55 @@ export const frontendCommandCategorySchema = z.enum([
     "unit-test",
     "trace",
 ]);
+const REPAIRABLE = new Set([
+    "typecheck",
+    "build",
+    "lint",
+    "component-test",
+    "unit-test",
+    "trace",
+]);
+export function isFrontendRepairable(failureClass) {
+    return REPAIRABLE.has(failureClass);
+}
+/**
+ * Deterministic commandLabel → commandCategory mapping (AC-3).
+ * `targetType` comes from the contract verificationTargets[].type
+ * (static | unit | component | integration | mock); the literal commandLabel
+ * wins over type so a `static` typecheck target is never misread as a test.
+ */
+export function mapCommandLabelToCategory(commandLabel, targetType) {
+    const label = commandLabel.toLowerCase();
+    if (/(?:typecheck|check-types|type-check|\btsc\b)/.test(label))
+        return "typecheck";
+    if (/(?:vite\s+build|next\s+build|webpack|rollup|\bbuild\b)/.test(label))
+        return "build";
+    if (/(?:eslint|\blint\b)/.test(label))
+        return "lint";
+    if (targetType === "component")
+        return "component-test";
+    if (targetType === "unit")
+        return "unit-test";
+    if (/(?:component|testing-library|render\()/.test(label))
+        return "component-test";
+    return "unit-test";
+}
+export function isReviewRepairable(finding, implementWriteSet) {
+    const hasFile = Boolean(finding.file && finding.file.trim().length > 0);
+    const hasLocation = Boolean((finding.line !== undefined && finding.line > 0) ||
+        (finding.symbol && finding.symbol.trim().length > 0));
+    const hasRequirement = Boolean((finding.requirementId && finding.requirementId.trim().length > 0) ||
+        (finding.acceptanceCriteriaId &&
+            finding.acceptanceCriteriaId.trim().length > 0));
+    const fixScope = finding.fixScope ?? (hasFile ? [finding.file] : []);
+    const fixScopeSubset = fixScope.length > 0 &&
+        fixScope.every((entry) => isPathWithinWriteSet(entry, implementWriteSet));
+    return (hasFile &&
+        hasLocation &&
+        hasRequirement &&
+        fixScopeSubset &&
+        finding.requiresContractReplan !== true);
+}
 export function classifyFrontendFailure(input) {
     // AC-2: structured evidence takes priority over string-blob heuristics.
     if (input.failureCategory === "write-guard") {
@@ -122,3 +176,380 @@ export function classifyFrontendFailure(input) {
         return "path";
     return "unknown";
 }
+export const frontendRepairAssessmentSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    schemaId: z.literal(FRONTEND_REPAIR_ASSESSMENT_SCHEMA_ID),
+    contract: z
+        .object({
+        relativePath: z.string().min(1),
+        schemaId: z.string().min(1),
+    })
+        .strict(),
+    failedNodeIds: z.array(z.string().min(1)),
+    failureClass: frontendRepairFailureClassSchema,
+    eligible: z.boolean(),
+    reason: z.string().min(1),
+    attempt: z.number().int().min(1).max(2),
+    maxAttempts: z.literal(1),
+    allowedRepairWriteSet: z.array(z.string().min(1)),
+    evidenceRefs: z.array(z.string().min(1)),
+    browserStatus: z.literal("not-run"),
+    // AC-5 structured evidence fields (all optional so existing minimal
+    // fixtures and frontend-review-context safeParse stay compatible).
+    verificationTargetId: z.string().min(1).optional(),
+    commandLabel: z.string().min(1).optional(),
+    exitCode: z.number().int().optional(),
+    commandCategory: frontendCommandCategorySchema.optional(),
+    requirementIds: z.array(z.string().min(1)).optional(),
+    acceptanceCriteriaIds: z.array(z.string().min(1)).optional(),
+    fixScope: z.array(z.string().min(1)).optional(),
+    changedPaths: z.array(z.string().min(1)).optional(),
+    traceRef: z
+        .object({
+        relativePath: z.string().min(1),
+        schemaId: z.string().min(1),
+    })
+        .strict()
+        .optional(),
+})
+    .strict();
+function nodeHadFailure(record) {
+    if (record.status === "ERROR")
+        return true;
+    if (recordIndicatesCommandFailure(record))
+        return true;
+    const results = record.commandResults ?? [];
+    if (results.some((item) => item.ok === false))
+        return true;
+    return false;
+}
+function normalize(value) {
+    return value.replace(/\\/g, "/").replace(/^\.\//, "");
+}
+/**
+ * Whether a concrete path or glob entry is contained by the implement writeSet.
+ * Exact glob equality is the norm (repair writeSet === implement writeSet);
+ * concrete (non-glob) paths may also be covered by an implement glob.
+ */
+export function isPathWithinWriteSet(entry, implementWriteSet) {
+    const normalizedEntry = normalize(entry);
+    const normalizedImplement = implementWriteSet.map(normalize);
+    if (normalizedImplement.includes(normalizedEntry))
+        return true;
+    if (!normalizedEntry.includes("*")) {
+        return implementWriteSet.some((pattern) => pathMatchesPattern(normalizedEntry, pattern));
+    }
+    return false;
+}
+export function assertWriteSetSubset(repairWriteSet, implementWriteSet) {
+    for (const entry of repairWriteSet) {
+        if (!isPathWithinWriteSet(entry, implementWriteSet)) {
+            throw new Error(`repair writeSet entry "${entry}" is not ⊆ implement writeSet`);
+        }
+    }
+}
+async function loadImplementWriteSet(runDir, fallback) {
+    if (fallback.length > 0)
+        return fallback;
+    const candidates = ["run.json", "dag.json", "spec.json"];
+    for (const name of candidates) {
+        try {
+            const raw = JSON.parse(await readFile(path.join(runDir, name), "utf8"));
+            const tasks = raw.spec?.tasks ?? raw.tasks ?? [];
+            const implement = tasks.find((task) => task.id === "frontend-implement-pi");
+            if (implement?.writeSet?.length)
+                return implement.writeSet;
+        }
+        catch {
+            // continue
+        }
+    }
+    return fallback;
+}
+function matchVerificationTarget(contract, commandLabel, command) {
+    for (const target of contract.verificationTargets) {
+        if (commandLabel && target.commandLabel === commandLabel)
+            return target;
+        if (command &&
+            (command.includes(target.commandLabel) ||
+                target.commandLabel.includes(command))) {
+            return target;
+        }
+    }
+    return undefined;
+}
+function deriveFailureEvidence(input) {
+    const evidence = {};
+    for (const { record } of input.failed) {
+        const results = record.commandResults ?? [];
+        const failedResult = results.find((item) => item.ok === false) ?? results[0];
+        if (failedResult &&
+            evidence.exitCode === undefined &&
+            typeof failedResult.exitCode === "number") {
+            evidence.exitCode = failedResult.exitCode;
+        }
+        if (failedResult?.commandLabel && !evidence.commandLabel) {
+            evidence.commandLabel = failedResult.commandLabel;
+        }
+        // Structured trace facts passed by the verification bundle / trace gate.
+        const failedTraceTarget = (record.traceTargets ?? []).find((target) => target.status === "failed");
+        if (failedTraceTarget && !evidence.verificationTargetId) {
+            evidence.verificationTargetId = failedTraceTarget.id;
+            if (!evidence.commandLabel)
+                evidence.commandLabel = failedTraceTarget.commandLabel;
+            evidence.traceTarget = failedTraceTarget;
+            evidence.traceRef = {
+                relativePath: "contracts/frontend-verification-trace.json",
+                schemaId: "frontend-verification-trace-v1",
+            };
+        }
+        if (record.changedPaths?.length && !evidence.changedPaths) {
+            evidence.changedPaths = [...record.changedPaths];
+        }
+    }
+    // Resolve commandLabel → contract verification target → category + scope.
+    const target = matchVerificationTarget(input.contract, evidence.commandLabel);
+    if (target) {
+        if (!evidence.verificationTargetId)
+            evidence.verificationTargetId = target.id;
+        if (!evidence.commandLabel)
+            evidence.commandLabel = target.commandLabel;
+        evidence.requirementIds ??= [...target.requirementIds];
+        evidence.acceptanceCriteriaIds ??= [...target.requirementIds];
+        evidence.fixScope ??= [target.file];
+    }
+    if (evidence.commandLabel) {
+        evidence.commandCategory ??= mapCommandLabelToCategory(evidence.commandLabel, target?.type);
+    }
+    return evidence;
+}
+export async function runFrontendFailureAssessGate(input) {
+    const attempt = input.attempt ?? 1;
+    const implementWriteSet = await loadImplementWriteSet(input.runDir, input.implementWriteSet ?? []);
+    if (implementWriteSet.length === 0) {
+        throw new Error("assess: implement writeSet unavailable");
+    }
+    const contractRel = "contracts/frontend-implementation-contract.json";
+    const contractPath = path.join(input.runDir, contractRel);
+    let contractSchemaId = FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID;
+    let contract;
+    try {
+        const raw = JSON.parse(await readFile(contractPath, "utf8"));
+        const parsed = frontendImplementationContractSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new Error("invalid frontend implementation contract");
+        }
+        contract = parsed.data;
+        contractSchemaId = FRONTEND_IMPLEMENTATION_CONTRACT_SCHEMA_ID;
+    }
+    catch {
+        // still allow assessment of failures without contract? fail-closed to contract
+        throw new Error("assess: missing or invalid contracts/frontend-implementation-contract.json");
+    }
+    const candidateNodeIds = [
+        "frontend-verify-assess-shell",
+        "frontend-reverify-shell",
+        "frontend-static-verify-shell",
+        "frontend-behavior-verify-shell",
+        "frontend-verification-trace-shell",
+        "frontend-static-reverify-shell",
+        "frontend-behavior-reverify-shell",
+        "frontend-verification-retrace-shell",
+    ];
+    const failed = [
+        ...(input.failureFacts ?? []).filter(({ record }) => nodeHadFailure(record) || recordIndicatesCommandFailure(record)),
+    ];
+    for (const nodeId of candidateNodeIds) {
+        if (failed.some((item) => item.nodeId === nodeId))
+            continue;
+        const nodePath = path.join(input.runDir, `${nodeId}.json`);
+        try {
+            const record = JSON.parse(await readFile(nodePath, "utf8"));
+            if (nodeHadFailure(record) || recordIndicatesCommandFailure(record)) {
+                failed.push({ nodeId, record });
+            }
+        }
+        catch {
+            // missing optional nodes ok
+        }
+    }
+    if (failed.length === 0) {
+        const assessment = {
+            schemaVersion: 1,
+            schemaId: FRONTEND_REPAIR_ASSESSMENT_SCHEMA_ID,
+            contract: {
+                relativePath: contractRel,
+                schemaId: contractSchemaId,
+            },
+            failedNodeIds: [],
+            failureClass: "unknown",
+            eligible: false,
+            reason: "no failed frontend verify/trace nodes in current run",
+            attempt,
+            maxAttempts: 1,
+            allowedRepairWriteSet: [...implementWriteSet],
+            evidenceRefs: [contractRel],
+            browserStatus: "not-run",
+        };
+        await writeAssessment(input.runDir, assessment);
+        return assessment;
+    }
+    const primary = failed[0];
+    const evidence = deriveFailureEvidence({ contract, failed });
+    const failureClass = classifyFrontendFailure({
+        nodeId: primary.nodeId,
+        failureCategory: primary.record.failureCategory,
+        stdout: primary.record.stdout,
+        stderr: primary.record.stderr,
+        commandLabel: evidence.commandLabel,
+        commandCategory: evidence.commandCategory,
+        exitCode: evidence.exitCode,
+        traceTarget: evidence.traceTarget ?? null,
+        changedPaths: evidence.changedPaths,
+    });
+    // AC-5: repairable=true requires structured evidence (a resolved exitCode,
+    // commandCategory, or trace-bound verification target). review has its own
+    // stricter gate (AC-4) and is never unconditionally repairable.
+    const baseEligible = isFrontendRepairable(failureClass) && attempt <= 1;
+    let eligible;
+    let reason;
+    if (failureClass === "review") {
+        const finding = primary.record.reviewFinding ?? {};
+        eligible = attempt <= 1 && isReviewRepairable(finding, implementWriteSet);
+        reason = eligible
+            ? `repairable review finding on ${primary.nodeId}`
+            : `review finding lacks file/line-symbol/requirement evidence or is outside writeSet on ${primary.nodeId}`;
+    }
+    else {
+        const hasStructuredEvidence = evidence.exitCode !== undefined ||
+            evidence.commandCategory !== undefined ||
+            Boolean(evidence.verificationTargetId);
+        eligible = baseEligible && hasStructuredEvidence;
+        reason = eligible
+            ? `repairable failureClass=${failureClass} on ${primary.nodeId}`
+            : !baseEligible
+                ? `non-repairable or ineligible: failureClass=${failureClass} attempt=${attempt}`
+                : `missing structured evidence for failureClass=${failureClass} on ${primary.nodeId}`;
+        if (!eligible &&
+            `${primary.record.stderr ?? ""}`.includes(FRONTEND_NO_VERIFICATION_MARKER_TEXT)) {
+            // Surface the actionable unavailable-verification reason in the
+            // assessment (and the non-repairable gate error) instead of a
+            // generic class label.
+            reason = FRONTEND_VERIFICATION_UNAVAILABLE_MESSAGE;
+        }
+    }
+    // fixScope and changedPaths must stay inside the implement writeSet.
+    if (evidence.fixScope?.length) {
+        assertWriteSetSubset(evidence.fixScope, implementWriteSet);
+    }
+    if (evidence.changedPaths?.length) {
+        assertWriteSetSubset(evidence.changedPaths, implementWriteSet);
+    }
+    const assessment = {
+        schemaVersion: 1,
+        schemaId: FRONTEND_REPAIR_ASSESSMENT_SCHEMA_ID,
+        contract: {
+            relativePath: contractRel,
+            schemaId: contractSchemaId,
+        },
+        failedNodeIds: failed.map((item) => item.nodeId),
+        failureClass,
+        eligible,
+        reason,
+        attempt,
+        maxAttempts: 1,
+        allowedRepairWriteSet: [...implementWriteSet],
+        evidenceRefs: [contractRel, ...failed.map((item) => `${item.nodeId}.json`)],
+        browserStatus: "not-run",
+        ...(evidence.verificationTargetId
+            ? { verificationTargetId: evidence.verificationTargetId }
+            : {}),
+        ...(evidence.commandLabel ? { commandLabel: evidence.commandLabel } : {}),
+        ...(evidence.exitCode !== undefined ? { exitCode: evidence.exitCode } : {}),
+        ...(evidence.commandCategory
+            ? { commandCategory: evidence.commandCategory }
+            : {}),
+        ...(evidence.requirementIds?.length
+            ? { requirementIds: evidence.requirementIds }
+            : {}),
+        ...(evidence.acceptanceCriteriaIds?.length
+            ? { acceptanceCriteriaIds: evidence.acceptanceCriteriaIds }
+            : {}),
+        ...(evidence.fixScope?.length ? { fixScope: evidence.fixScope } : {}),
+        ...(evidence.changedPaths?.length
+            ? { changedPaths: evidence.changedPaths }
+            : {}),
+        ...(evidence.traceRef ? { traceRef: evidence.traceRef } : {}),
+    };
+    await writeAssessment(input.runDir, assessment);
+    return assessment;
+}
+function recordIndicatesCommandFailure(record) {
+    // Prefer explicit commandResults when present
+    if (record.commandResults?.some((item) => item.ok === false))
+        return true;
+    // Node may be FINISHED with nonZeroExitPolicy=record; look for harness markers
+    const stdout = record.stdout ?? "";
+    if (/nonZeroExitPolicy=record/.test(stdout) &&
+        /exitCode=[1-9]/.test(stdout)) {
+        return true;
+    }
+    if (record.failureCategory && record.failureCategory !== "success") {
+        // recorded failures may still be FINISHED
+        if (record.status === "FINISHED") {
+            return (record.failureCategory === "nonzero-exit" ||
+                record.failureCategory === "invalid-output" ||
+                record.failureCategory === "timeout");
+        }
+    }
+    return false;
+}
+async function writeAssessment(runDir, assessment) {
+    const relative = "contracts/frontend-repair-assessment.json";
+    const absolute = path.join(runDir, relative);
+    await mkdir(path.dirname(absolute), { recursive: true });
+    await writeFile(absolute, `${JSON.stringify(assessment, null, 2)}\n`, "utf8");
+    return absolute;
+}
+export async function runFrontendRepairContractGate(input) {
+    const relative = "contracts/frontend-repair-assessment.json";
+    const absolute = path.join(input.runDir, relative);
+    const raw = JSON.parse(await readFile(absolute, "utf8"));
+    const parsed = frontendRepairAssessmentSchema.safeParse(raw);
+    if (!parsed.success) {
+        throw new Error(`repair-contract: invalid assessment: ${parsed.error.issues
+            .map((i) => i.message)
+            .join("; ")}`);
+    }
+    const assessment = parsed.data;
+    const implementWriteSet = await loadImplementWriteSet(input.runDir, input.implementWriteSet ?? []);
+    assertWriteSetSubset(assessment.allowedRepairWriteSet, implementWriteSet.length
+        ? implementWriteSet
+        : assessment.allowedRepairWriteSet);
+    if (assessment.attempt > assessment.maxAttempts) {
+        throw new Error("repair-contract: attempt exceeds maxAttempts");
+    }
+    if (assessment.failedNodeIds.length === 0) {
+        return { ok: true, assessment };
+    }
+    if (!assessment.eligible) {
+        throw new Error(`repair-contract: non-repairable failure (${assessment.failureClass}): ${assessment.reason}`);
+    }
+    if (!isFrontendRepairable(assessment.failureClass) &&
+        assessment.failureClass !== "review") {
+        throw new Error(`repair-contract: failureClass ${assessment.failureClass} is not repairable`);
+    }
+    return { ok: true, assessment };
+}
+export function formatFrontendFailureAssessStdout(assessment) {
+    return JSON.stringify(assessment);
+}
+export function formatFrontendRepairContractStdout(assessment) {
+    return [
+        "Frontend repair contract: pass",
+        `eligible=${assessment.eligible}`,
+        `failureClass=${assessment.failureClass}`,
+        `writeSetSize=${assessment.allowedRepairWriteSet.length}`,
+    ].join("\n");
+}