@tea-agent/loop-agent 0.35.1-beta.1 → 0.35.1-beta.2

package/dist/workflows/dag/recovery-recommendation.js

@@ -269,3 +269,61 @@ export function planDagRecovery(input) {
     }
     return planByNormalizedCategory(input);
 }
+/**
+ * Phase 6: route a frontend recovery outcome to a recovery CTA (read-only; never
+ * mutates a run's status). The six outcomes map to the existing recovery actions
+ * so the Console recovery page reuses the current CTA surface.
+ */
+export function recommendFrontendRecoveryOutcome(outcome) {
+    switch (outcome) {
+        case "none":
+            return {
+                action: "none",
+                summary: "未发生前端恢复；按普通终态展示。",
+                reason: "该 frontend-implementation 根没有触发自动恢复。",
+                humanRequired: false,
+                autoRetryEligible: false,
+            };
+        case "recovered":
+            return {
+                action: "none",
+                summary: "自动恢复成功；child 已重新实现并通过验证。",
+                reason: "parent 的 transient 失败已由 child 恢复，全链按 root 计一次成功。",
+                humanRequired: false,
+                autoRetryEligible: false,
+            };
+        case "candidate-contract-invalid":
+            return {
+                action: "manual-review",
+                summary: "方案输出无效：candidate JSON 无法解析/推导，重试用尽。",
+                reason: "建议人工检查需求或重新生成方案后再跑。",
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+        case "prewrite-blocked":
+            return {
+                action: "manual-review",
+                summary: "治理门禁阻断：source stale / writeSet 越界 / Mock policy / contract 违规。",
+                reason: "需人工修正任务边界/事实后重跑，不自动重试。",
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+        case "repair-exhausted":
+            return {
+                action: "rerun-after-fix",
+                summary: "自动修复未通过：verify 失败，1 次 repair 后 reverify 仍失败。",
+                reason: "建议 `dag rerun` 或人工排查。",
+                humanRequired: true,
+                autoRetryEligible: false,
+                commandHint: "loop-agent dag rerun --run-id <runId>",
+            };
+        case "auto-recovery-blocked":
+            return {
+                action: "manual-review",
+                summary: "自动恢复被阻止：rollback 无法证明完整或存在外部/越界修改。",
+                reason: "必须人工介入，禁止自动覆盖用户文件。",
+                humanRequired: true,
+                autoRetryEligible: false,
+            };
+    }
+}

package/dist/workflows/dag/runner.js

@@ -1,4 +1,5 @@
 import { readdir, readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { hostname } from "node:os";
 import path from "node:path";
@@ -6,7 +7,7 @@ import { isHardBudgetBreached, resolveEffectiveMaxConcurrent, } from "../../appl
 import { readCandidateRecord } from "../../infrastructure/evaluation/candidate-store.js";
 import { CANONICAL_TASK_ID_PATTERN, formatLocalCompactDate, } from "../../task/runtime.js";
 import { assertFrozenBudget, initRunBudgetLedger, preflightBudgetOrBreach, recordFinishedNodeBudget, writeBudgetLedgerArtifacts, } from "./budget-enforcement.js";
-import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readHumanApprovalArtifact, requireActiveDagRun, } from "./lifecycle.js";
+import { getDagRunDir, isTerminalDagRunStatus, locateDagRun, readDagRunSpec, readDagRunState, readHumanApprovalArtifact, requireActiveDagRun, } from "./lifecycle.js";
 import { moveToCompletedRunDir, moveToPausedRunDir, prepareRunDir, writeRunSpec, writeRunState, } from "./run-store.js";
 import { evaluateNodeLiveness, resolveLivenessPolicy, } from "./liveness-policy.js";
 import { createDagNodeExecutor } from "./executor-registry.js";
@@ -21,8 +22,9 @@ import { createSkillSnapshot, prepareSkillSnapshotForContinuation, writeSkillSna
 import { captureWorkspaceCheckpoint, WORKSPACE_CHECKPOINT_START_REL, WORKSPACE_CHECKPOINT_TERMINAL_REL, writeWorkspaceCheckpoint, } from "./workspace-checkpoint.js";
 import { buildNodePrompt, buildNodePromptWithResolvedSkillInstructions, executeDagNode, } from "./node-execution.js";
 import { runConvergencePassController, } from "./convergence/controller.js";
-import { executeDagRanksOnce, FRONTEND_WRITER_NODE_IDS, isConditionSkippedReason, readFrontendPrewriteResult, } from "./scheduler.js";
+import { executeDagRanksOnce, FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, FRONTEND_WRITER_NODE_IDS, isConditionSkippedReason, readFrontendPrewriteResult, } from "./scheduler.js";
 import { topoSortToRanks } from "./topo.js";
+import { isFrontendWriterTransientPartialWrite } from "./frontend-writer-recovery.js";
 import { parseDagSpec, resolveModelForTask, } from "./types.js";
 import { executeDynamicCondition } from "./dynamic-runtime/condition.js";
 import { executeDynamicLoopUntil } from "./dynamic-runtime/loop-until.js";
@@ -629,17 +631,54 @@ async function executeDagCheckpoint(input) {
             runDir = await moveToPausedRunDir(runDir, pausedRunDir);
         }
         else {
-            await finalizeTerminalRunStatus(state, spec.tasks.length, runDir);
+            const { recoveryPending } = await finalizeTerminalRunStatus(state, spec.tasks.length, runDir, cwd);
             await persistState();
-            await notifyRunObserver(input.observer, "onRunFinish", state);
-            try {
-                const terminalCheckpoint = await captureWorkspaceCheckpoint(cwd);
-                await writeWorkspaceCheckpoint(runDir, WORKSPACE_CHECKPOINT_TERMINAL_REL, terminalCheckpoint);
+            if (recoveryPending) {
+                // Recovery coordinator (phase 3c AC-2/AC-3): materialize the reserved
+                // child and run it synchronously. Dynamic import avoids a static
+                // runner ↔ frontend-recovery-run module cycle. stageRecoveryChild
+                // locates the parent via the canonical active/ layout, so recovery
+                // only fires when this run is still the canonical active run dir
+                // (direct runDagContinuation callers using an arbitrary runDir keep
+                // the previous scheduler-layer skip semantics).
+                const canonicalActiveDir = getDagRunDir(cwd, "active", state.runId);
+                if (path.resolve(runDir) === path.resolve(canonicalActiveDir)) {
+                    const { stageRecoveryChild } = await import("./frontend-recovery-run.js");
+                    const staged = await stageRecoveryChild({
+                        cwd,
+                        parentRunId: state.runId,
+                    });
+                    // stageRecoveryChild CAS-advanced the parent's on-disk lineage
+                    // (child-staging → child-running + childRunId). Refresh the in-memory
+                    // copy so the terminal persistState below does not regress the parent
+                    // back to stale child-staging.
+                    const parentOnDisk = await readDagRunState(runDir);
+                    state.frontendRecoveryState = parentOnDisk.frontendRecoveryState;
+                    const childState = await readDagRunState(staged.childRunDir);
+                    const childSpec = await readDagRunSpec(staged.childRunDir);
+                    await runDagContinuation({
+                        cwd,
+                        spec: childSpec,
+                        state: childState,
+                        runDir: staged.childRunDir,
+                        maxConcurrent,
+                        executeNode: input.executeNode,
+                        observer: input.observer,
+                        abortSignal: input.abortSignal,
+                    });
+                }
             }
-            catch (error) {
-                console.warn(`[run-dag] warning: failed to write workspace terminal checkpoint: ${error instanceof Error ? error.message : String(error)}`);
+            await notifyRunObserver(input.observer, "onRunFinish", state);
+            if (!recoveryPending) {
+                try {
+                    const terminalCheckpoint = await captureWorkspaceCheckpoint(cwd);
+                    await writeWorkspaceCheckpoint(runDir, WORKSPACE_CHECKPOINT_TERMINAL_REL, terminalCheckpoint);
+                }
+                catch (error) {
+                    console.warn(`[run-dag] warning: failed to write workspace terminal checkpoint: ${error instanceof Error ? error.message : String(error)}`);
+                }
+                runDir = await moveToCompletedRunDir(runDir, completedRunDir);
             }
-            runDir = await moveToCompletedRunDir(runDir, completedRunDir);
         }
         await relocateRunArtifactPaths({
             runDir,
@@ -731,18 +770,151 @@ function isSuccessfulConvergenceTerminal(state) {
         return true;
     return SUCCESSFUL_CONVERGENCE_TERMINAL_REASONS.has(reason);
 }
-export async function finalizeTerminalRunStatus(state, taskCount, runDir) {
+function buildFrontendRecoveryIntent(state, failureSource) {
+    const existing = state.frontendRecoveryState;
+    const requestId = existing?.requestId ?? randomUUID();
+    return {
+        schemaVersion: 1,
+        phase: "child-staging",
+        requestId,
+        recoveryRootRunId: existing?.recoveryRootRunId ?? state.runId,
+        parentRunId: state.runId,
+        ...(existing?.childRunId ? { childRunId: existing.childRunId } : {}),
+        attemptId: existing?.attemptId ?? `recovery-${requestId}`,
+        attemptIndex: existing?.attemptIndex ?? 0,
+        continuationCount: existing?.continuationCount ?? 0,
+        ...(failureSource ? { failureSource } : {}),
+        revision: (existing?.revision ?? 0) + 1,
+    };
+}
+function buildCandidateContractInvalidResult(state, result, artifactHash) {
+    const recovery = state.frontendRecoveryState;
+    return {
+        schemaVersion: 1,
+        outcome: "candidate-contract-invalid",
+        origin: {
+            kind: "frontend-prewrite-gate",
+            parentRunId: recovery?.parentRunId ?? state.runId,
+            ...(recovery?.childRunId ? { childRunId: recovery.childRunId } : {}),
+            requestId: recovery?.requestId ?? "",
+            failedNodeId: result.selectedPlanNodeId,
+        },
+        failureClass: {
+            code: "candidate-contract-invalid",
+            classification: result.classification,
+            reason: result.failureReason ?? "candidate contract invalid",
+        },
+        evidenceRefs: [
+            {
+                runId: state.runId,
+                relativePath: FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT,
+                sha256: artifactHash,
+            },
+        ],
+    };
+}
+function buildWriterPartialWriteBlockedResult(state, failedNodeId, reason) {
+    const recovery = state.frontendRecoveryState;
+    return {
+        schemaVersion: 1,
+        outcome: "auto-recovery-blocked",
+        origin: {
+            kind: "frontend-writer",
+            parentRunId: recovery?.parentRunId ?? state.runId,
+            ...(recovery?.childRunId ? { childRunId: recovery.childRunId } : {}),
+            requestId: recovery?.requestId ?? "",
+            failedNodeId,
+        },
+        failureClass: {
+            code: "writer-transient-partial-write",
+            classification: "transient",
+            reason,
+        },
+        evidenceRefs: [],
+    };
+}
+function settleFrontendRecovery(state, outcome) {
+    const recovery = state.frontendRecoveryState;
+    if (!recovery)
+        return;
+    recovery.phase = "settled";
+    if (!state.frontendRecoveryResult) {
+        state.frontendRecoveryResult = {
+            schemaVersion: 1,
+            outcome,
+            origin: {
+                kind: "frontend-prewrite-gate",
+                parentRunId: recovery.parentRunId,
+                ...(recovery.childRunId ? { childRunId: recovery.childRunId } : {}),
+                requestId: recovery.requestId,
+                failedNodeId: "",
+            },
+            evidenceRefs: [],
+        };
+    }
+}
+export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd) {
+    const repoRoot = cwd ?? path.resolve(runDir, "..", "..", "..", "..");
     // Terminal override: a denied frontend writer must never surface as a
     // mechanical partial_failed just because prewrite FINISHED while the writer
     // was SKIPPED. Fail closed on retryable-invalid/blocked before aggregation.
+    let recoveryPending = false;
     const hasFrontendWriter = Object.keys(state.nodes).some((id) => FRONTEND_WRITER_NODE_IDS.includes(id));
     if (hasFrontendWriter) {
         const admission = await readFrontendPrewriteResult(runDir);
-        if (admission.ok &&
-            (admission.result.classification === "retryable-invalid" ||
-                admission.result.classification === "blocked")) {
-            state.status = "failed";
-            return;
+        if (admission.ok) {
+            if (admission.result.classification === "blocked") {
+                state.status = "failed";
+                return { recoveryPending: false };
+            }
+            if (admission.result.classification === "retryable-invalid") {
+                const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
+                if (continuationCount >= 1) {
+                    // Continuation quota exhausted: a second retryable-invalid candidate
+                    // is authoritative candidate-contract-invalid → forced failed.
+                    state.frontendRecoveryResult = buildCandidateContractInvalidResult(state, admission.result, admission.artifactHash);
+                    state.status = "failed";
+                    return { recoveryPending: false };
+                }
+                // Root continuation still available: record the recovery intent and let
+                // mechanical aggregation settle partial_failed/failed. The parent keeps
+                // phase != settled (recovery in progress) and no final root manifest.
+                state.frontendRecoveryState = buildFrontendRecoveryIntent(state);
+                recoveryPending = true;
+            }
+        }
+    }
+    // Phase 5: writer transient partial write → rollback + recovery intent. Only
+    // for frontend-implementation writers with a remaining root continuation, and
+    // only when the rollback journal (captured before the provider call) restores
+    // cleanly; otherwise the run stays failed with auto-recovery-blocked.
+    if (hasFrontendWriter && !recoveryPending) {
+        const writerNodeId = FRONTEND_WRITER_NODE_IDS.find((id) => {
+            const node = state.nodes[id];
+            return (node &&
+                node.status === "ERROR" &&
+                isFrontendWriterTransientPartialWrite({
+                    failureCategory: node.failureCategory,
+                }));
+        });
+        if (writerNodeId) {
+            const continuationCount = state.frontendRecoveryState?.continuationCount ?? 0;
+            if (continuationCount < 1) {
+                const { rollbackFrontendWriter } = await import("./frontend-writer-recovery.js");
+                const rollback = await rollbackFrontendWriter({
+                    cwd: repoRoot,
+                    parentRunId: state.runId,
+                });
+                if (rollback.ok) {
+                    state.frontendRecoveryState = buildFrontendRecoveryIntent(state, "frontend-implement-pi");
+                    recoveryPending = true;
+                }
+                else {
+                    state.frontendRecoveryResult = buildWriterPartialWriteBlockedResult(state, writerNodeId, rollback.reason);
+                    state.status = "failed";
+                    return { recoveryPending: false };
+                }
+            }
         }
     }
     const finishedCount = Object.values(state.nodes).filter((n) => n.status === "FINISHED").length;
@@ -768,6 +940,19 @@ export async function finalizeTerminalRunStatus(state, taskCount, runDir) {
     else {
         state.status = "failed";
     }
+    // Terminal recovery bookkeeping for a child attempt: a child that finished
+    // recovered settles its own lineage; any other child terminal settles as
+    // auto-recovery-blocked (phase 3 performs no further recovery).
+    const recovery = state.frontendRecoveryState;
+    if (recovery && recovery.attemptIndex >= 1) {
+        if (state.status === "finished") {
+            settleFrontendRecovery(state, "recovered");
+        }
+        else if (!state.frontendRecoveryResult) {
+            settleFrontendRecovery(state, "auto-recovery-blocked");
+        }
+    }
+    return { recoveryPending };
 }
 function concurrentSiblingWriteSetsForNode(rankWriterNodeIds, nodeId, tasksById) {
     if (rankWriterNodeIds.length <= 1)

package/dist/workflows/dag/scheduler.js

@@ -4,6 +4,7 @@ import { isPauseOnHumanDecisionGate } from "./decision-envelope.js";
 import { evaluateConditionExpression } from "./dynamic-runtime/condition.js";
 import { sha256Hex } from "./frontend-implementation-contract.js";
 import { frontendPrewriteResultV1Schema, FRONTEND_PREWRITE_RESULT_ARTIFACT_NAME, } from "./frontend-prewrite-gate.js";
+import { FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, FRONTEND_RECOVERY_INTENT_REL_DIR, } from "./frontend-recovery-plan.js";
 export function isConditionSkippedReason(reason) {
     return Boolean(reason?.startsWith("condition "));
 }
@@ -178,8 +179,166 @@ export function markPendingNodesControllerInterrupted(state, reason = "run abort
     }
     return affected;
 }
+/**
+ * True when this run is a candidate-continuation child: it has a recovery
+ * lineage whose attemptIndex is >= 1 and whose recovery root is another run.
+ * The root/parent keeps `recoveryRootRunId === state.runId`.
+ */
+export function isFrontendRecoveryChild(state) {
+    const recovery = state.frontendRecoveryState;
+    return Boolean(recovery &&
+        recovery.attemptIndex >= 1 &&
+        recovery.recoveryRootRunId !== state.runId);
+}
+function isValidFrontendRecoveryActivationMarker(raw) {
+    return (raw.schemaVersion === 1 &&
+        typeof raw.requestId === "string" &&
+        raw.requestId.length > 0 &&
+        typeof raw.parentRunId === "string" &&
+        raw.parentRunId.length > 0 &&
+        typeof raw.recoveryRootRunId === "string" &&
+        raw.recoveryRootRunId.length > 0 &&
+        typeof raw.childRunId === "string" &&
+        raw.childRunId.length > 0 &&
+        typeof raw.importManifestSha256 === "string" &&
+        /^[a-f0-9]{64}$/.test(raw.importManifestSha256));
+}
+/**
+ * Activation marker gate (phase 3c AC-1). Fail-closed: an active child is only
+ * executable when its parent is `child-running`, points at this child, carries
+ * a structurally valid activation marker whose lineage matches, and the marker
+ * hash matches the child's import manifest. Read-only and never throws.
+ */
+export async function checkFrontendRecoveryActivation(state, childRunDir) {
+    if (!isFrontendRecoveryChild(state)) {
+        return { applicable: false };
+    }
+    const recovery = state.frontendRecoveryState;
+    const parentRunId = recovery.parentRunId;
+    const parentRunDir = path.join(path.dirname(childRunDir), parentRunId);
+    let parentState;
+    try {
+        parentState = JSON.parse(await readFile(path.join(parentRunDir, "state.json"), "utf8"));
+    }
+    catch {
+        return { applicable: true, ok: false, reason: "parent state unreadable" };
+    }
+    const parentRecovery = parentState.frontendRecoveryState;
+    if (parentRecovery?.phase !== "child-running") {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "parent phase not child-running",
+        };
+    }
+    if (parentRecovery.childRunId !== state.runId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "parent childRunId mismatch",
+        };
+    }
+    const markerPath = path.join(parentRunDir, FRONTEND_RECOVERY_INTENT_REL_DIR, `${recovery.requestId}.json`);
+    let markerRaw;
+    try {
+        markerRaw = JSON.parse(await readFile(markerPath, "utf8"));
+    }
+    catch {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "activation marker missing",
+        };
+    }
+    if (typeof markerRaw !== "object" ||
+        markerRaw === null ||
+        !isValidFrontendRecoveryActivationMarker(markerRaw)) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "activation marker invalid",
+        };
+    }
+    const marker = markerRaw;
+    if (marker.requestId !== recovery.requestId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker requestId mismatch",
+        };
+    }
+    if (marker.parentRunId !== parentRunId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker parentRunId mismatch",
+        };
+    }
+    if (marker.recoveryRootRunId !== recovery.recoveryRootRunId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker recoveryRootRunId mismatch",
+        };
+    }
+    if (marker.childRunId !== state.runId) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "marker childRunId mismatch",
+        };
+    }
+    let manifestSha256;
+    try {
+        manifestSha256 = sha256Hex(await readFile(path.join(childRunDir, FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH), "utf8"));
+    }
+    catch {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "import manifest unreadable",
+        };
+    }
+    if (manifestSha256 !== marker.importManifestSha256) {
+        return {
+            applicable: true,
+            ok: false,
+            reason: "import manifest sha256 mismatch",
+        };
+    }
+    return {
+        applicable: true,
+        ok: true,
+        requestId: recovery.requestId,
+        childRunId: state.runId,
+    };
+}
 export async function executeDagRanksOnce(input) {
     let pausedByNodeId;
+    // Activation marker gate (phase 3c AC-1): a recovery child without a valid
+    // activation marker must never be scheduled or executed. Fail-closed before
+    // any executeScheduledNode call, so zero writer/provider invocations happen.
+    if (input.runDir) {
+        const hasPending = Object.values(input.state.nodes).some((node) => node.status === "PENDING");
+        if (hasPending) {
+            const activation = await checkFrontendRecoveryActivation(input.state, input.runDir);
+            if (activation.applicable && !activation.ok) {
+                const finishedAt = new Date().toISOString();
+                let affected = 0;
+                for (const node of Object.values(input.state.nodes)) {
+                    if (node.status !== "PENDING")
+                        continue;
+                    node.status = "SKIPPED";
+                    node.skippedReason = "frontend-recovery-child-not-activated";
+                    node.finishedAt = finishedAt;
+                    affected += 1;
+                }
+                if (affected > 0)
+                    await input.persistState();
+                return undefined;
+            }
+        }
+    }
     for (const rank of input.ranks) {
         if (input.abortSignal?.aborted) {
             const marked = markPendingNodesControllerInterrupted(input.state, input.abortSignal.reason

package/dist/workflows/dag/types.js

@@ -895,6 +895,113 @@ export const dagSpecSchema = z
         });
     }
 });
+export const FRONTEND_RECOVERY_STATE_SCHEMA_VERSION = 1;
+export const FRONTEND_RECOVERY_RESULT_SCHEMA_VERSION = 1;
+/**
+ * Frontend candidate-continuation recovery phase (decision B, phase-3 subset).
+ * Phase 3a parents converge first, so `rollback-pending` is not produced and
+ * was removed by AC-1; the phase starts at `child-staging` and ends at
+ * `settled`.
+ */
+export const frontendRecoveryPhaseSchema = z.enum([
+    "child-staging",
+    "child-activating",
+    "child-running",
+    "settled",
+]);
+/**
+ * Single-writer recovery intent/lineage stored on `DagRunState`. The parent run
+ * owns the authoritative copy and advances it via revision-guarded CAS writes;
+ * the child carries a frozen lineage snapshot so the activation gate can prove
+ * it is the reserved child of a child-running parent.
+ *
+ * Invariants: `attemptIndex ∈ {0,1}`; `continuationCount ∈ {0,1}`; a child's
+ * `recoveryRootRunId` always equals the root runId; `revision` is the CAS
+ * pre-comparison counter. `revision` monotonicity is enforced at runtime by the
+ * runner's `(existing?.revision ?? 0) + 1` CAS write (the schema only bounds it
+ * non-negative). `childRunId` may be absent through `child-activating` and must
+ * be non-empty from `child-running` onward.
+ */
+export const frontendRecoveryStateSchema = z
+    .object({
+    schemaVersion: z.literal(FRONTEND_RECOVERY_STATE_SCHEMA_VERSION),
+    phase: frontendRecoveryPhaseSchema,
+    requestId: z.string().min(1),
+    recoveryRootRunId: z.string().min(1),
+    parentRunId: z.string().min(1),
+    childRunId: z.string().min(1).optional(),
+    attemptId: z.string().min(1),
+    attemptIndex: z.number().int().min(0).max(1),
+    continuationCount: z.number().int().min(0).max(1),
+    /** Node id of the reset-closure root: frontend-plan-pi /
+     *  frontend-plan-revision-pi / frontend-prewrite-gate-shell /
+     *  frontend-implement-pi (writer partial write). */
+    failureSource: z.string().min(1).optional(),
+    revision: z.number().int().nonnegative(),
+})
+    .strict()
+    .superRefine((value, ctx) => {
+    const requiresChild = value.phase === "child-running" || value.phase === "settled";
+    if (requiresChild && !value.childRunId) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `phase ${value.phase} requires a non-empty childRunId`,
+            path: ["childRunId"],
+        });
+    }
+});
+export const frontendRecoveryOutcomeSchema = z.enum([
+    "none",
+    "recovered",
+    "candidate-contract-invalid",
+    "prewrite-blocked",
+    "repair-exhausted",
+    "auto-recovery-blocked",
+]);
+export const frontendRecoveryOriginSchema = z
+    .object({
+    kind: z.enum(["frontend-prewrite-gate", "frontend-writer"]),
+    parentRunId: z.string().min(1),
+    childRunId: z.string().min(1).optional(),
+    requestId: z.string().min(1),
+    failedNodeId: z.string(),
+})
+    .strict();
+export const frontendRecoveryFailureClassSchema = z
+    .object({
+    code: z.enum([
+        "candidate-contract-invalid",
+        "prewrite-blocked",
+        "staging-failed",
+        "writer-transient-partial-write",
+    ]),
+    classification: z.string(),
+    reason: z.string(),
+})
+    .strict();
+export const frontendRecoveryEvidenceRefSchema = z
+    .object({
+    runId: z.string().min(1),
+    relativePath: z.string().min(1),
+    sha256: z.string().min(1),
+})
+    .strict();
+/**
+ * Terminal frontend recovery result. `failureClass` is absent for `none`,
+ * `recovered` and `auto-recovery-blocked` outcomes. The schema intentionally
+ * stays permissive (failureClass optional, evidenceRefs may be empty) so it
+ * accepts the runner's actual phase-3a products, which do not always carry a
+ * failure class or evidence reference.
+ */
+export const frontendRecoveryResultSchema = z
+    .object({
+    schemaVersion: z.literal(FRONTEND_RECOVERY_RESULT_SCHEMA_VERSION),
+    outcome: frontendRecoveryOutcomeSchema,
+    origin: frontendRecoveryOriginSchema,
+    failureClass: frontendRecoveryFailureClassSchema.optional(),
+    evidenceRefs: z.array(frontendRecoveryEvidenceRefSchema),
+})
+    .strict();
 export const DEFAULT_DAG_EXECUTOR_MODELS = {
     pi: {
         LOW: "gpt-5.3-codex-spark",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tea-agent/loop-agent",
-  "version": "0.35.1-beta.1",
+  "version": "0.35.1-beta.2",
   "type": "module",
   "bin": {
     "loop-agent": "bin/loop-agent.js",