@tea-agent/loop-agent 0.39.0-beta.8 → 0.39.0-beta.9

package/dist/workflows/dag/interrupt-request.js

@@ -410,6 +410,13 @@ export function startInterruptWatcher(input) {
     let watcher;
     try {
         watcher = watch(path.join(input.runDir, ".runtime"), () => tick());
+        // fs.watch can report EMFILE/ENOSPC asynchronously after watch() returns.
+        // Polling below is the reliable path, so watcher errors must never escape
+        // as an unhandled EventEmitter error and orphan the DAG runner.
+        watcher.on("error", () => {
+            watcher?.close();
+            watcher = undefined;
+        });
         watcher.unref?.();
     }
     catch {

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

@@ -3,6 +3,7 @@ import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { pathMatchesPattern } from "../../shared/git-progress.js";
+import { redactSecrets, truncateUtf8Preview } from "../../shared/preview.js";
 import { recordDecisionEnvelopeForNode, shouldPauseOnHumanEscalation, writeHumanEscalationArtifacts, } from "./decision-envelope.js";
 import { FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, FRONTEND_WRITER_NODE_IDS, isFrontendWriterAuthorized, readFrontendPrewriteResult, } from "./scheduler.js";
 import { writeNodeRecord, writeNodeSkillArtifacts } from "./run-store.js";
@@ -164,6 +165,45 @@ function frontendStructuredArtifactRetryGuidance(schemaId) {
     ];
 }
 const FRONTEND_PLAN_NODE_ID = "frontend-plan-pi";
+const COMPACT_RETRY_SECTION_MAX_CHARS = 1_200;
+const COMPACT_RETRY_TASK_MAX_CHARS = 4_800;
+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;
 }
@@ -184,9 +224,25 @@ async function readFrontendPlanCommittedSnapshot(runDir, nodeId) {
     const hasTerminalFact = committed.some((record) => record.fact.kind === "finalize_plan");
     return { digest, hasTerminalFact };
 }
-function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCategory, previousProtocolReason, recoveryTargetPaths, recoveryDiagnostics, frontendPlanRetryStep) {
+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,
@@ -239,6 +295,16 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
         ].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,
             "",
@@ -430,6 +496,35 @@ function buildAttemptPrompt(task, basePrompt, attemptNumber, previousFailureCate
         "</retry_instruction>",
     ].join("\n");
 }
+const PROMPT_RESTART_CANDIDATE_MAX_BYTES = 64 * 1024;
+function promptRestartCandidateForAttempt(input) {
+    if (input.attemptPrompt === input.baseRuntimePrompt) {
+        return input.taskPrompt;
+    }
+    const appendedPrefix = `${input.baseRuntimePrompt}\n\n`;
+    if (input.attemptPrompt.startsWith(appendedPrefix)) {
+        return [
+            input.taskPrompt,
+            input.attemptPrompt.slice(appendedPrefix.length),
+        ]
+            .filter(Boolean)
+            .join("\n\n");
+    }
+    return input.attemptPrompt;
+}
+async function persistFailedPromptRestartCandidate(input) {
+    const redacted = redactSecrets(input.prompt);
+    const preview = truncateUtf8Preview(redacted, PROMPT_RESTART_CANDIDATE_MAX_BYTES);
+    await writeDagNodeJsonArtifact(input.runDir, input.nodeId, `prompt-candidate-attempt-${input.attempt}.json`, {
+        schemaVersion: 1,
+        attempt: input.attempt,
+        failureCategory: input.failureCategory ?? "unknown",
+        prompt: preview,
+        truncated: preview !== redacted,
+        maxBytes: PROMPT_RESTART_CANDIDATE_MAX_BYTES,
+        sha256: createHash("sha256").update(redacted).digest("hex"),
+    });
+}
 export async function buildNodePromptWithResolvedSkillInstructions(spec, task, upstream, cwd, options) {
     const policy = resolveContextPolicy(spec);
     const skillNames = policy.resolveSkills(spec, task);
@@ -904,6 +999,7 @@ export async function executeDagNode(input) {
         // exactly this attempt's segment (B1: earlier attempts legitimately use
         // ls/find and must not be attributed to the repair attempt).
         const attemptSessionEventsOffset = await sessionEventsByteLength(runDir, nodeId);
+        let promptRestartCandidate = task.subtask_prompt;
         let result;
         try {
             validateRepairArtifactGateBeforeShell({
@@ -974,6 +1070,11 @@ export async function executeDagNode(input) {
                     previousReason: previousProtocolReason,
                 });
             }
+            promptRestartCandidate = promptRestartCandidateForAttempt({
+                taskPrompt: task.subtask_prompt,
+                baseRuntimePrompt: prompt,
+                attemptPrompt,
+            });
             result = await executeNode({
                 task,
                 cwd,
@@ -1101,6 +1202,15 @@ export async function executeDagNode(input) {
         const attemptWallDurationMs = durationBetween(attemptStartedAt, attemptFinishedAt);
         totalAttemptWallDurationMs += attemptWallDurationMs;
         const rawFailureCategory = result.rawFailureCategory ?? result.failureCategory;
+        if (task.executor === "pi" && !result.ok) {
+            await persistFailedPromptRestartCandidate({
+                runDir,
+                nodeId,
+                attempt: attemptNumber,
+                failureCategory: result.failureCategory,
+                prompt: promptRestartCandidate,
+            });
+        }
         const attemptRecord = {
             attempt: attemptNumber,
             startedAt: attemptStartedAt,

package/dist/workflows/dag/prompt.js

@@ -45,9 +45,42 @@ function formatResolvedSkillInstructions(instructions) {
     if (!instructions || instructions.length === 0)
         return "(none)";
     return instructions
-        .map((instruction) => instruction.promptText)
+        .map((instruction) => formatSkillChecklist(instruction))
         .join("\n\n---\n\n");
 }
+/** Keep skill provenance, but turn bounded inline manuals into a small action list. */
+function formatSkillChecklist(instruction) {
+    const metadata = [
+        `Skill: ${instruction.name}`,
+        `Resolution: ${instruction.resolution}`,
+        ...(instruction.path ? [`Path: ${instruction.path}`] : []),
+        ...(instruction.sha256 ? [`Sha256: ${instruction.sha256}`] : []),
+        "Injection mode: checklist",
+    ];
+    if (instruction.resolution !== "resolved")
+        return [...metadata, instruction.promptText].join("\n");
+    const source = instruction.promptText.split("Instructions:\n")[1] ?? "";
+    const candidates = source
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => /^(?:#{1,3}\s+|[-*]\s+|\d+[.)]\s+)/.test(line) || line.length > 0)
+        .map((line) => line.replace(/^#{1,3}\s+/, "").replace(/^[-*]\s+/, "").replace(/^\d+[.)]\s+/, ""))
+        .filter((line) => line.length > 0);
+    const checklist = [];
+    let chars = 0;
+    for (const item of candidates) {
+        const bounded = item.slice(0, 240);
+        if (checklist.length >= 10 || chars + bounded.length > 1_600)
+            break;
+        checklist.push(`- ${bounded}`);
+        chars += bounded.length;
+    }
+    return [
+        ...metadata,
+        "Checklist (apply these actions; consult the immutable resolved file only when a listed action requires detail):",
+        ...(checklist.length > 0 ? checklist : ["- Follow the resolved skill's declared workflow."]),
+    ].join("\n");
+}
 export function formatOutputLanguageBlock(language = DEFAULT_DAG_OUTPUT_LANGUAGE) {
     if (language === "en") {
         return [

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

@@ -0,0 +1,80 @@
+import { createHash, randomBytes } from "node:crypto";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { DAG_RUNS_DIR } from "./lifecycle.js";
+function recoveryLeasePath(cwd, parentRunId) {
+    // Never derive a filesystem name directly from an externally supplied legacy
+    // run id. The content remains auditable while the filename is traversal-safe.
+    const key = createHash("sha256").update(parentRunId).digest("hex");
+    return path.join(cwd, DAG_RUNS_DIR, ".recovery-leases", `${key}.json`);
+}
+function parseLease(raw, parentRunId) {
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error("invalid dag recovery lease: expected object");
+    }
+    const record = raw;
+    if (record.schemaVersion !== 1 ||
+        record.parentRunId !== parentRunId ||
+        typeof record.requestId !== "string" ||
+        record.requestId.length === 0 ||
+        (record.kind !== "auto-frontend-recovery" &&
+            record.kind !== "rerun-from-node" &&
+            record.kind !== "standalone-task-rerun") ||
+        typeof record.leaseToken !== "string" ||
+        record.leaseToken.length === 0 ||
+        typeof record.acquiredAt !== "string" ||
+        typeof record.executionRef !== "undefined" &&
+            typeof record.executionRef !== "string") {
+        throw new Error("invalid dag recovery lease: schema mismatch");
+    }
+    return record;
+}
+export async function acquireDagRecoveryLease(input) {
+    const leasePath = recoveryLeasePath(input.cwd, input.parentRunId);
+    const lease = {
+        schemaVersion: 1,
+        parentRunId: input.parentRunId,
+        requestId: input.requestId,
+        kind: input.kind,
+        leaseToken: randomBytes(16).toString("hex"),
+        acquiredAt: (input.now ?? (() => new Date()))().toISOString(),
+    };
+    await mkdir(path.dirname(leasePath), { recursive: true });
+    try {
+        // `wx` is the cross-process compare-and-create primitive. The lease is
+        // deliberately immutable for a parent run: a later recovery must follow
+        // the committed child lineage rather than fork another DAG.
+        await writeFile(leasePath, `${JSON.stringify(lease, null, 2)}\n`, {
+            encoding: "utf8",
+            flag: "wx",
+        });
+        return { kind: "acquired", leasePath, lease };
+    }
+    catch (error) {
+        if (!(error && typeof error === "object" && "code" in error && error.code === "EEXIST")) {
+            throw error;
+        }
+        const existing = parseLease(JSON.parse(await readFile(leasePath, "utf8")), input.parentRunId);
+        return { kind: "held", leasePath, lease: existing };
+    }
+}
+/** Persist the operation/run identity before the caller is allowed to execute it. */
+export async function bindDagRecoveryLeaseExecution(input) {
+    if (!input.executionRef.trim()) {
+        throw new Error("dag recovery lease executionRef is required");
+    }
+    const existing = parseLease(JSON.parse(await readFile(input.leasePath, "utf8")), input.lease.parentRunId);
+    if (existing.leaseToken !== input.lease.leaseToken) {
+        throw new Error("dag recovery lease ownership drift");
+    }
+    if (existing.executionRef && existing.executionRef !== input.executionRef) {
+        throw new Error("dag recovery lease execution identity drift");
+    }
+    const bound = {
+        ...existing,
+        executionRef: input.executionRef,
+    };
+    await writeJsonAtomic(input.leasePath, bound);
+    return bound;
+}

package/dist/workflows/dag/rerun-run.js

@@ -12,6 +12,7 @@ import { prepareActiveRunDir, writeNodeRecord, writeRunSpec, writeRunState, } fr
 import { cloneParentSkillSnapshotForContinuation, readSkillSnapshot, } from "./skill-snapshot.js";
 import { topoSortToRanks } from "./topo.js";
 import { captureWorkspaceCheckpoint, readWorkspaceCheckpoint, WORKSPACE_CHECKPOINT_START_REL, WORKSPACE_CHECKPOINT_TERMINAL_REL, writeWorkspaceCheckpoint, } from "./workspace-checkpoint.js";
+import { acquireDagRecoveryLease, bindDagRecoveryLeaseExecution, } from "./recovery-lease.js";
 export const RERUN_PLAN_REL_PATH = ".runtime/rerun-plan.json";
 export const IMPORT_MANIFEST_REL_PATH = ".runtime/import-manifest.json";
 export const WORKER_ASSOCIATION_REL_PATH = ".runtime/worker-association.json";
@@ -572,6 +573,20 @@ export async function executeDagRerun(input) {
     }
     const parentSpec = await readDagRunSpec(located.runDir);
     const parentState = await readDagRunState(located.runDir);
+    const recoveryLease = await acquireDagRecoveryLease({
+        cwd: input.cwd,
+        parentRunId: input.parentRunId,
+        requestId: input.requestId,
+        kind: "rerun-from-node",
+    });
+    if (recoveryLease.kind === "held") {
+        return {
+            ok: false,
+            plan,
+            errorCode: "RECOVERY_LEASE_HELD",
+            message: `parent run recovery is already claimed by ${recoveryLease.lease.kind} request ${recoveryLease.lease.requestId}`,
+        };
+    }
     const staged = await stageContinuationRun({
         cwd: input.cwd,
         parentRunDir: located.runDir,
@@ -583,6 +598,14 @@ export async function executeDagRerun(input) {
         requestId: input.requestId,
         promptOverrides: input.promptOverrides,
     });
+    // Stage is non-executing; bind the child identity immediately before handing
+    // it to the runner so no recovery DAG can start without durable parent
+    // lineage ownership.
+    await bindDagRecoveryLeaseExecution({
+        leasePath: recoveryLease.leasePath,
+        lease: recoveryLease.lease,
+        executionRef: staged.state.runId,
+    });
     const continuationOptions = {
         cwd: input.cwd,
         spec: staged.spec,

package/dist/workflows/dag/rerun-task.js

@@ -4,6 +4,7 @@ import { generateTaskDagUseCase } from "../../application/dag/generate-task-dag.
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { DAG_RUNS_DIR, isTerminalDagRunStatus, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
 import { deriveDagRerunFeedback } from "./rerun-feedback.js";
+import { acquireDagRecoveryLease, bindDagRecoveryLeaseExecution, } from "./recovery-lease.js";
 import { parseDagSpec, } from "./types.js";
 export const RERUN_TASK_LINEAGE_REL_PATH = ".runtime/rerun-task-lineage.json";
 export function parseDagRerunTaskArgs(args) {
@@ -369,6 +370,34 @@ export async function rerunStandaloneTask(input) {
             }
         }
     }
+    const recoveryLease = execute
+        ? await acquireDagRecoveryLease({
+            cwd: input.cwd,
+            parentRunId: input.parentRunId,
+            requestId: input.requestId,
+            kind: "standalone-task-rerun",
+        })
+        : undefined;
+    if (recoveryLease?.kind === "held") {
+        return blockedResult({
+            parentRunId: input.parentRunId,
+            reason: input.reason,
+            requestId: input.requestId,
+            blockedReason: "recovery-lease-held",
+            note: `parent run recovery is already claimed by ${recoveryLease.lease.kind} request ${recoveryLease.lease.requestId}`,
+            taskId: taskResolution.taskId,
+        });
+    }
+    if (recoveryLease?.kind === "acquired") {
+        // Persist a non-empty execution identity before generateTaskDagUseCase can
+        // execute its new DAG. The generated run id is not available yet, so the
+        // request id is the stable lineage handle for this entry point.
+        await bindDagRecoveryLeaseExecution({
+            leasePath: recoveryLease.leasePath,
+            lease: recoveryLease.lease,
+            executionRef: `standalone-task-rerun:${input.requestId}`,
+        });
+    }
     const generateResult = await generateTaskDagUseCase({
         repoRoot: input.cwd,
         taskId: taskResolution.taskId,

package/dist/workflows/dag/retry-policy.js

@@ -132,13 +132,24 @@ export const dagRetryPolicySchema = z
 /**
  * The default retry policy applied to safe generated read-only Pi nodes.
  * Total attempts: 3, exponential backoff with cap.
+ *
+ * Includes `context-overflow`: a read-only node that blew the context window
+ * (400 request too large, e.g. a review node accumulating too many reads) is a
+ * transient, safe-to-retry failure — the retry re-runs the node with a
+ * compact-context instruction instead of failing the whole run. Previously
+ * only writer transport policies had context-overflow; contract/scout/
+ * design-review/review fell straight to ERROR without a retry attempt.
  */
 export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
     maxAttempts: 3,
     backoff: "exponential",
     initialDelayMs: 2000,
     maxDelayMs: 30000,
-    retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES],
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Structured planner nodes may retry with a compact-output instruction
@@ -148,7 +159,11 @@ export const DEFAULT_READ_ONLY_PI_RETRY_POLICY = {
  */
 export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
-    retryCategories: [...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES],
+    retryCategories: [
+        ...STRUCTURED_REQUIRED_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Planner read-only nodes (standard DAG contract-pi / plan-pi) may retry with
@@ -159,7 +174,12 @@ export const STRUCTURED_REQUIRED_PI_RETRY_POLICY = {
  */
 export const PLANNER_OUTPUT_LIMIT_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
-    retryCategories: [...DEFAULT_DAG_RETRY_CATEGORIES, STRUCTURED_OUTPUT_RETRY_CATEGORY],
+    retryCategories: [
+        ...DEFAULT_DAG_RETRY_CATEGORIES,
+        STRUCTURED_OUTPUT_RETRY_CATEGORY,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
+    ],
 };
 /**
  * Default retry for reviewer / recovery nodes that declare outputProtocol.
@@ -180,6 +200,8 @@ export const FRONTEND_REVIEW_TERMINAL_RETRY_POLICY = {
     ...DEFAULT_READ_ONLY_PI_RETRY_POLICY,
     retryCategories: [
         ...DEFAULT_DAG_RETRY_CATEGORIES,
+        READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
         REVIEW_TERMINAL_MISSING_RETRY_CATEGORY,
     ],
 };
@@ -553,5 +575,6 @@ export const FRONTEND_PLAN_LADDER_RETRY_POLICY = {
         ...DEFAULT_DAG_RETRY_CATEGORIES,
         STRUCTURED_ARTIFACT_INVALID_RETRY_CATEGORY,
         READ_BURST_RETRY_CATEGORY,
+        CONTEXT_OVERFLOW_RETRY_CATEGORY,
     ],
 };

package/dist/workflows/dag/runner.js

@@ -31,6 +31,7 @@ import { bindFrontendShapeStateToRunTopology, commitFrontendShapeTransitionCas,
 import { assertFrontendTopologyBinding, buildFrontendTopologyBinding, computeFrontendShapeSourceDigest, } from "./frontend-shape.js";
 import { ensureFrontendShapeCapsuleRecord } from "./frontend-shape-capsule-store.js";
 import { parseDagSpec, resolveModelForTask, } from "./types.js";
+import { acquireDagRecoveryLease, bindDagRecoveryLeaseExecution, } from "./recovery-lease.js";
 import { executeDynamicCondition } from "./dynamic-runtime/condition.js";
 import { executeDynamicLoopUntil } from "./dynamic-runtime/loop-until.js";
 import { executeDynamicMapExpansion } from "./dynamic-runtime/map.js";
@@ -822,6 +823,15 @@ async function executeDagCheckpoint(input) {
                         "frontend recovery request-id reuse conflict";
                     state.frontendRecoveryResult = buildRecoveryResultForTrigger(state, recoveryTrigger, "auto-recovery-blocked");
                 }
+                else if (created.kind === "lease-held") {
+                    // A different recovery entrance has already durably claimed this
+                    // parent. Do not "help" by running its operation: that would reopen
+                    // the exact two-child-DAG race the lease prevents.
+                    state.status = "failed";
+                    state.terminalReason =
+                        "frontend recovery parent lease already held";
+                    state.frontendRecoveryResult = buildRecoveryResultForTrigger(state, recoveryTrigger, "auto-recovery-blocked");
+                }
                 else {
                     const { runRecoveryOperationController } = await import("./frontend-recovery-controller.js");
                     const result = await runRecoveryOperationController({
@@ -1263,16 +1273,25 @@ export async function finalizeTerminalRunStatus(state, taskCount, runDir, cwd, f
 /**
  * Construct (or reuse) the recovery operation for a failed frontend run.
  *
- * The operation is keyed by a deterministic `clientRequestId`
- * (`dag-recovery-<parentRunId>`), so repeated wakeups of the same parent hit
- * `OperationStore.create`'s idempotent short-circuit instead of creating a
- * second recovery run (AC-004). The continuation DagSpec/reset partition is
- * frozen via `computeFrontendRecoveryPlanForSource` and serialized under the
- * run dir's bounded `.runtime/` namespace — never the repo root or `.harness`
- * siblings. `planHash` is the second idempotency dimension of `actionParams`.
+ * A parent-run atomic lease is acquired before `OperationStore.create`, then
+ * its operation id is persisted into that lease before the controller may run.
+ * `clientRequestId` remains a useful store-level replay key, but is not a
+ * cross-process recovery admission boundary. The continuation DagSpec/reset
+ * partition is frozen via `computeFrontendRecoveryPlanForSource` and
+ * serialized under the run dir's bounded `.runtime/` namespace. `planHash` is
+ * the second idempotency dimension of `actionParams`.
  */
 async function createRecoveryOperation(input) {
     const { cwd, runDir, spec, state, trigger } = input;
+    const recoveryLease = await acquireDagRecoveryLease({
+        cwd,
+        parentRunId: state.runId,
+        requestId: trigger.requestId,
+        kind: "auto-frontend-recovery",
+    });
+    if (recoveryLease.kind === "held") {
+        return { kind: "lease-held", lease: recoveryLease.lease };
+    }
     const { computeFrontendRecoveryPlanForSource } = await import("./frontend-recovery-plan.js");
     const plan = computeFrontendRecoveryPlanForSource({
         spec,
@@ -1292,7 +1311,7 @@ async function createRecoveryOperation(input) {
         recoveryMode: trigger.recoveryMode,
         plan,
     });
-    return input.deps.store.create({
+    const created = await input.deps.store.create({
         clientRequestId: `dag-recovery-${state.runId}`,
         action: "dagRunTask",
         actionParams: {
@@ -1314,6 +1333,17 @@ async function createRecoveryOperation(input) {
             "--json",
         ],
     });
+    if (created.kind !== "conflict") {
+        // The durable lease must name the operation before controller execution.
+        // A crash in this narrow window leaves a safely blocked reservation rather
+        // than a second process that can launch another recovery DAG.
+        await bindDagRecoveryLeaseExecution({
+            leasePath: recoveryLease.leasePath,
+            lease: recoveryLease.lease,
+            executionRef: created.operation.operationId,
+        });
+    }
+    return created;
 }
 function concurrentSiblingWriteSetsForNode(rankWriterNodeIds, nodeId, tasksById) {
     if (rankWriterNodeIds.length <= 1)

package/dist/workflows/dag/types.js

@@ -946,6 +946,15 @@ export const dagTaskSchema = z.object({ id: z.string().regex(/^[a-z][a-z0-9-]*$/
     role: dagRoleSchema.optional(),
     skills: z.array(z.string()).optional(),
     toolProfile: dagToolProfileSchema.optional(),
+    /** Bounded read-only discovery budget for nodes that inspect a repository. */
+    readBudget: z
+        .object({
+        maxFiles: z.number().int().positive(),
+        maxBytes: z.number().int().positive(),
+        maxMs: z.number().int().positive().optional(),
+    })
+        .strict()
+        .optional(),
     /**
      * Explicit Pi extension allowlist (backend implementation DAGs only):
      * frozen short ids resolved at run time against the Pi settings package
@@ -1071,20 +1080,51 @@ export const dagEvaluationBindingSchema = z
     .strict();
 /** Eval Lab Campaign Budget (W3.4); enforced by runner ledger when mode=hard. */
 export const dagBudgetSchema = campaignBudgetSchema;
-export const dagSourceBindingSchema = z.object({
+export const dagSourceBindingSourceSchema = z.object({
+    kind: z.enum(["requirement", "constraint", "reference"]),
+    path: z.string().min(1),
+    sha256: z
+        .string()
+        .regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
+});
+/**
+ * DagSourceBinding v1：无 ledger 字段（schemaVersion=1，.strict() 拒绝 ledger
+ * 字段混入，不得以 v1+optional 冒充 v2）。非 frontend task / 无可解析引用时使用。
+ */
+export const dagSourceBindingV1Schema = z
+    .object({
     schemaVersion: z.literal(1),
     taskId: z.string().min(1),
-    sources: z
-        .array(z.object({
-        kind: z.enum(["requirement", "constraint", "reference"]),
-        path: z.string().min(1),
-        sha256: z
-            .string()
-            .regex(/^[a-f0-9]{64}$/, "sha256 must be lowercase hex"),
-    }))
-        .min(1),
+    sources: z.array(dagSourceBindingSourceSchema).min(1),
     requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
-});
+})
+    .strict();
+/**
+ * DagSourceBinding v2（20260824-frontend-source-fidelity-ledger-v1）：仅
+ * frontend-implementation 且存在可解析 requirement/acceptance 引用时产出；
+ * ledgerPath/ledgerSha256/inputDigest/requirementToFragments 全部必填且完整，
+ * 伪造或缺失任一字段被 schema/prewrite 拒绝（AC-002 / AC-FIDELITY-REPAIR-002）。
+ */
+export const dagSourceBindingV2Schema = z
+    .object({
+    schemaVersion: z.literal(2),
+    taskId: z.string().min(1),
+    sources: z.array(dagSourceBindingSourceSchema).min(1),
+    requirementIds: z.array(z.string().regex(/^(?:REQ|BR|AC)-[A-Z0-9]+(?:-[A-Z0-9]+)*$/)),
+    /** 受管 requirement-ledger.json 的 DAG 可解析路径（.harness/tasks/…/source/…）。 */
+    ledgerPath: z.string().min(1),
+    ledgerSha256: z.string().regex(/^[a-f0-9]{64}$/),
+    inputDigest: z.string().regex(/^[a-f0-9]{64}$/),
+    requirementToFragments: z.record(z.string(), z.array(z.string())),
+})
+    .strict();
+export const dagSourceBindingSchema = z.discriminatedUnion("schemaVersion", [
+    dagSourceBindingV1Schema,
+    dagSourceBindingV2Schema,
+]);
+export function isDagSourceBindingV2(binding) {
+    return binding.schemaVersion === 2;
+}
 const dagRerunFeedbackEvidencePathSchema = z
     .string()
     .min(1)

package/docs/README.md

@@ -27,6 +27,7 @@
 | 选择快速、标准或完整验证命令 | `governance/verification-matrix.md` |
 | 理解 CLI、runtime 和初始化能力边界 | `runtime/loop-agent-harness.md` |
 | 运行 DAG、查看报告或处理失败 | `runtime/agent-dag-runner.md`、`runtime/agent-dag-recovery-playbook.md`；Operator Chat P0 closeout 见 `reports/feature/2026-08-14-operator-chat-dag-recovery-p0.md` |
+| 理解前端实现 DAG 与需求保真账本 | `runtime/frontend-implementation-workflow.md`（含 source fidelity ledger v2 绑定、顺序 reconciliation、独立 reviewer、human resolution 与 prewrite fail-closed）；init-evolution 审查见 `reports/init-evolution/2026-08-24-frontend-source-fidelity-ledger-init-evolution-review.md` |
 | 按 TDD、验证和调试纪律推进修复 | `governance/harness-methodology-tdd.md`、`governance/harness-methodology-verification.md`、`governance/harness-methodology-debugging.md` |
 | 执行真实 backend-test provider 验证 | `runtime/backend-test-live-campaign.md` |
 | 判断单任务 loop-agent Production Readiness | `operations/production-readiness.md` |