@tea-agent/loop-agent 0.41.0 → 0.42.0-next.1

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

@@ -1,23 +1,56 @@
-import { createHash } from "node:crypto";
-import { access, copyFile, mkdir, readdir, readFile } from "node:fs/promises";
+import { createHash, timingSafeEqual } from "node:crypto";
+import { access, copyFile, lstat, mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { z } from "zod";
 import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
 import { composeDagPromptOverridePrompt, isDagRerunPromptOverrideEnabled, } from "../../shared/dag-prompt-override.js";
 import { resolveRunningControllerIdentity } from "../../shared/package-metadata.js";
 import { readControllerIdentityArtifact, captureControllerIdentity } from "./controller-identity.js";
-import { DAG_RUNS_DIR, getDagRunDir, isDagNonExecutionLifecycle, locateDagRun, readDagRunSpec, readDagRunState, } from "./lifecycle.js";
+import { DAG_RUNS_DIR, getDagRunDir, isDagNonExecutionLifecycle, locateDagRun, readDagRunSpec, readDagRunState, transferDagRunDir, } from "./lifecycle.js";
 import { buildDagRunId, runDagContinuation, } from "./runner.js";
-import { computePlanHash, evaluateDagRerunPlan, evaluateLiveDagRerunBindings, } from "./rerun-plan.js";
+import { computePlanHash, evaluateArtifactOverrideRerunPlan, evaluateDagRerunPlan, evaluateLiveDagRerunBindings, } from "./rerun-plan.js";
 import { prepareActiveRunDir, writeNodeRecord, writeRunSpec, writeRunState, } from "./run-store.js";
 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 { captureWriterBaseline, readJournalFile, recordWriterAttemptFromCurrent, restoreJournal, writeJournalFile, } from "./frontend-writer-rollback.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";
+export const CONTINUATION_WRITER_ROLLBACK_REL_PATH = ".runtime/continuation-writer-rollback.json";
+export const CONTINUATION_WRITER_TRANSACTION_REL_PATH = ".runtime/continuation-writer-transaction.json";
 function sha256Hex(content) {
     return createHash("sha256").update(content).digest("hex");
 }
+function constantTimeHashEqual(left, right) {
+    if (!/^[a-f0-9]{64}$/.test(left) || !/^[a-f0-9]{64}$/.test(right))
+        return false;
+    return timingSafeEqual(Buffer.from(left, "hex"), Buffer.from(right, "hex"));
+}
+export async function snapshotDagRunManifest(runDir) {
+    const entries = [];
+    const walk = async (dir) => {
+        for (const entry of (await readdir(dir, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) {
+            const absolute = path.join(dir, entry.name);
+            const relative = normalizeRunRelativePath(path.relative(runDir, absolute));
+            if (entry.isSymbolicLink())
+                throw new Error(`symlink rejected in DAG run manifest: ${relative}`);
+            if (entry.isDirectory()) {
+                await walk(absolute);
+                continue;
+            }
+            if (!entry.isFile())
+                throw new Error(`non-regular DAG run entry: ${relative}`);
+            const stat = await lstat(absolute);
+            if (stat.nlink !== 1)
+                throw new Error(`hardlink rejected in DAG run manifest: ${relative}`);
+            const bytes = await readFile(absolute);
+            entries.push({ path: relative, sha256: sha256Hex(bytes), bytes: bytes.byteLength });
+        }
+    };
+    await walk(runDir);
+    return sha256Hex(JSON.stringify(entries));
+}
 async function fileExists(filePath) {
     try {
         await access(filePath);
@@ -30,18 +63,67 @@ async function fileExists(filePath) {
 function operatorRequestPath(cwd, requestId) {
     return path.join(cwd, DAG_RUNS_DIR, ".operator-requests", `${requestId}.json`);
 }
+/** Strict envelope for persisted operator-request replays (SF2). */
+const operatorRequestEnvelopeSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    kind: z.literal("dag-rerun-from-node-request"),
+    requestId: z.string().min(1),
+    parentRunId: z.string().min(1),
+    newRunId: z.string().min(1),
+    createdAt: z.string().min(1),
+    result: z
+        .object({
+        ok: z.boolean(),
+        plan: z
+            .object({
+            parentRunId: z.string().min(1),
+            planHash: z.string().min(1),
+        })
+            .passthrough(),
+        newRunId: z.string().min(1).optional(),
+    })
+        .passthrough(),
+})
+    .strict();
 async function readExistingOperatorRequest(cwd, requestId) {
     try {
         const raw = JSON.parse(await readFile(operatorRequestPath(cwd, requestId), "utf-8"));
-        if (raw.result && typeof raw.result === "object") {
-            return { ...raw.result, idempotentReplay: true };
-        }
+        const parsed = operatorRequestEnvelopeSchema.safeParse(raw);
+        if (!parsed.success)
+            return undefined;
+        const result = parsed.data.result;
+        return {
+            ...result,
+            plan: result.plan,
+            idempotentReplay: true,
+        };
     }
     catch {
         // not found or unreadable
     }
     return undefined;
 }
+/**
+ * Idempotent replay of a previously persisted operator request, if any.
+ * When expected context is supplied, a replay that belongs to a different
+ * parent run or plan is a request-id reuse conflict rather than a valid
+ * answer.
+ */
+export async function readOperatorRequestReplay(cwd, requestId, expected) {
+    const replay = await readExistingOperatorRequest(cwd, requestId);
+    if (!replay)
+        return undefined;
+    if (expected?.parentRunId !== undefined &&
+        replay.plan?.parentRunId !== expected.parentRunId) {
+        throw new Error("REQUEST_ID_REUSE_CONFLICT: operator request replay belongs to a different parent run");
+    }
+    if (expected?.planHash !== undefined &&
+        replay.plan?.planHash !== expected.planHash) {
+        throw new Error("REQUEST_ID_REUSE_CONFLICT: operator request replay belongs to a different plan");
+    }
+    return replay;
+}
 async function persistOperatorRequest(cwd, result, requestId) {
     await writeJsonAtomic(operatorRequestPath(cwd, requestId), {
         schemaVersion: 1,
@@ -246,6 +328,54 @@ export async function planDagRerun(input) {
         bindingStatus,
     });
 }
+export async function planDagArtifactOverride(input) {
+    const located = await locateDagRun(input.cwd, input.parentRunId);
+    if (!located)
+        throw new Error(`dag run not found: ${input.parentRunId}`);
+    if (located.lifecycle !== "completed") {
+        throw new Error(`artifact continuation requires completed parent: ${input.parentRunId}`);
+    }
+    const parentSpec = await readDagRunSpec(located.runDir);
+    const parentState = await readDagRunState(located.runDir);
+    const currentWorkspace = await captureWorkspaceCheckpoint(input.cwd).catch(() => undefined);
+    const parentTerminalWorkspace = await readWorkspaceCheckpoint(located.runDir, WORKSPACE_CHECKPOINT_TERMINAL_REL);
+    const fingerprints = await resolveControllerFingerprints(located.runDir);
+    const skillSnapshotOk = await verifyParentSkillSnapshot(located.runDir, parentState, input.parentRunId);
+    const workerHints = await detectWorkerManagedRun(located.runDir, parentState, parentSpec);
+    const liveBindings = await evaluateLiveDagRerunBindings({ cwd: input.cwd, parentSpec });
+    return evaluateArtifactOverrideRerunPlan({
+        parentRunId: input.parentRunId,
+        parentSpec,
+        parentState,
+        artifactId: input.artifactId,
+        artifactOverrides: input.artifactOverrides,
+        stagingRevisionSha256: input.stagingRevisionSha256,
+        parentLifecycle: "completed",
+        bindings: {
+            ...liveBindings,
+            controllerIdentityMatched: fingerprints.currentControllerFingerprint === undefined ||
+                fingerprints.parentControllerFingerprint === undefined ||
+                fingerprints.currentControllerFingerprint === fingerprints.parentControllerFingerprint,
+            skillSnapshotVerified: skillSnapshotOk,
+            workspaceMatched: parentTerminalWorkspace?.fingerprint !== undefined &&
+                currentWorkspace?.fingerprint !== undefined &&
+                parentTerminalWorkspace.fingerprint === currentWorkspace.fingerprint,
+        },
+        parentTerminalWorkspaceFingerprint: parentTerminalWorkspace?.fingerprint,
+        currentWorkspaceFingerprint: currentWorkspace?.fingerprint,
+        workerAssociation: workerHints.workerManaged
+            ? {
+                kind: "worker-managed",
+                ...(workerHints.featureId ? { featureId: workerHints.featureId } : {}),
+                ...(workerHints.taskId ? { taskId: workerHints.taskId } : {}),
+                ...(workerHints.workerRunId ? { workerRunId: workerHints.workerRunId } : {}),
+            }
+            : { kind: "standalone" },
+        ...(input.workerContinuationAuthority
+            ? { workerContinuationAuthority: input.workerContinuationAuthority }
+            : {}),
+    });
+}
 function normalizeRunRelativePath(relPath) {
     return relPath.replace(/\\/g, "/");
 }
@@ -359,6 +489,18 @@ function buildImportedNodeRecord(parentRecord, parentRunId, sourceNodeRecordSha2
     const { origin: _origin, ...rest } = parentRecord;
     void _origin;
     const imported = structuredClone(rest);
+    imported.declaredArtifacts = imported.declaredArtifacts?.map((artifact) => ({
+        ...artifact,
+        ...(artifact.sha256
+            ? {
+                origin: {
+                    kind: "imported",
+                    parentRunId,
+                    sourceSha256: artifact.sha256,
+                },
+            }
+            : {}),
+    }));
     imported.nodeRecordPath = path.join(newRunDir, `${parentRecord.id}.json`);
     for (const key of [
         "stdoutArtifactPath",
@@ -424,25 +566,204 @@ function applyPromptOverridesToSpec(input) {
     }
     return spec;
 }
+function collectMaterializedDynamicChildIds(spec, dynamicParentNodeIds) {
+    const parentSet = new Set(dynamicParentNodeIds);
+    const matchers = [];
+    for (const task of spec.tasks) {
+        if (!parentSet.has(task.id))
+            continue;
+        if (task.dynamicExpansion) {
+            const escaped = task.dynamicExpansion.childIdPrefix.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            matchers.push(new RegExp(`^${escaped}-\\d{4}$`));
+        }
+        if (task.dynamicLoopUntil) {
+            const escaped = task.id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+            matchers.push(new RegExp(`^${escaped}-r\\d+-`));
+        }
+    }
+    return new Set(spec.tasks
+        .map((task) => task.id)
+        .filter((nodeId) => matchers.some((matcher) => matcher.test(nodeId))));
+}
+async function applyArtifactOverrideToStagedRun(input) {
+    const override = input.plan.artifactOverrides?.overrides[0];
+    if (!override)
+        throw new Error("artifact override missing from V2 plan");
+    if (override.parentArtifact.runId !== input.parentRunId) {
+        throw new Error("artifact override parent run drift");
+    }
+    if (!constantTimeHashEqual(sha256Hex(input.candidateBytes), override.replacement.sha256)) {
+        throw new Error("ARTIFACT_REVISION_DRIFT: candidate hash mismatch");
+    }
+    if (input.candidateBytes.byteLength !== override.replacement.bytes) {
+        throw new Error("ARTIFACT_REVISION_DRIFT: candidate byte length mismatch");
+    }
+    const relativePath = assertArtifactPathWithinParentRun(input.parentRunDir, override.parentArtifact.path);
+    const parentBytes = await readFile(path.join(input.parentRunDir, ...relativePath.split("/")));
+    if (!constantTimeHashEqual(sha256Hex(parentBytes), override.parentArtifact.sha256)) {
+        throw new Error("ARTIFACT_REVISION_DRIFT: parent artifact changed");
+    }
+    const destinationPath = path.join(input.newRunDir, ...relativePath.split("/"));
+    const resolvedRun = path.resolve(input.newRunDir);
+    if (!path.resolve(destinationPath).startsWith(`${resolvedRun}${path.sep}`)) {
+        throw new Error("ARTIFACT_REVISION_PATH_INVALID");
+    }
+    await mkdir(path.dirname(destinationPath), { recursive: true });
+    await writeFile(destinationPath, input.candidateBytes, { mode: 0o600 });
+    const producer = input.nodes[override.parentArtifact.nodeId];
+    if (!producer || producer.origin?.kind !== "imported") {
+        throw new Error("artifact producer must be imported into continuation");
+    }
+    producer.structuredArtifactPath = destinationPath;
+    producer.structuredArtifactSha256 = override.replacement.sha256;
+    producer.declaredArtifacts = producer.declaredArtifacts?.map((artifact) => artifact.path === relativePath && artifact.sha256 === override.parentArtifact.sha256
+        ? {
+            ...artifact,
+            sha256: override.replacement.sha256,
+            bytes: override.replacement.bytes,
+            origin: {
+                kind: "overridden",
+                parentRunId: input.parentRunId,
+                revisionId: override.revisionId,
+                supersedes: override.supersedes,
+            },
+        }
+        : artifact);
+    await writeNodeRecord(input.newRunDir, override.parentArtifact.nodeId, producer);
+    const manifestNode = input.manifestNodes.find((entry) => entry.nodeId === override.parentArtifact.nodeId);
+    if (manifestNode) {
+        manifestNode.importedArtifacts = manifestNode.importedArtifacts.filter((artifact) => artifact.destinationRelativePath !== relativePath);
+    }
+    return {
+        revisionId: override.revisionId,
+        producerNodeId: override.parentArtifact.nodeId,
+        destinationRelativePath: relativePath,
+        parentSha256: override.parentArtifact.sha256,
+        replacementSha256: override.replacement.sha256,
+        bytes: override.replacement.bytes,
+        mediaType: override.replacement.mediaType,
+        supersedes: override.supersedes,
+    };
+}
+async function captureContinuationWriterTransaction(input) {
+    const writer = input.plan.schemaVersion === 2 ? input.plan.highRiskAuthority?.writer : undefined;
+    if (!writer)
+        return;
+    const snapshot = await captureWriterBaseline(input.cwd, writer.writeSet);
+    await writeJournalFile(path.join(input.runDir, CONTINUATION_WRITER_ROLLBACK_REL_PATH), snapshot);
+    await writeJsonAtomic(path.join(input.runDir, CONTINUATION_WRITER_TRANSACTION_REL_PATH), {
+        schemaVersion: 1,
+        state: "prepared",
+        preparedAt: new Date().toISOString(),
+        writerNodeIds: writer.nodeIds,
+        writeSet: writer.writeSet,
+        writeSetSha256: writer.writeSetSha256,
+    });
+}
+async function finalizeContinuationWriterTransaction(input) {
+    const writer = input.plan.schemaVersion === 2 ? input.plan.highRiskAuthority?.writer : undefined;
+    if (!writer)
+        return { state: "not-applicable" };
+    const transactionPath = path.join(input.runDir, CONTINUATION_WRITER_TRANSACTION_REL_PATH);
+    if (input.committed) {
+        await writeJsonAtomic(transactionPath, {
+            schemaVersion: 1,
+            state: "committed",
+            committedAt: new Date().toISOString(),
+            writerNodeIds: writer.nodeIds,
+            writeSet: writer.writeSet,
+            writeSetSha256: writer.writeSetSha256,
+        });
+        return { state: "committed" };
+    }
+    const journalPath = path.join(input.runDir, CONTINUATION_WRITER_ROLLBACK_REL_PATH);
+    const baseline = await readJournalFile(journalPath);
+    if (!baseline) {
+        const reason = "continuation writer rollback journal is missing or invalid";
+        await writeJsonAtomic(transactionPath, {
+            schemaVersion: 1,
+            state: "blocked",
+            blockedAt: new Date().toISOString(),
+            reason,
+            writerNodeIds: writer.nodeIds,
+            writeSet: writer.writeSet,
+            writeSetSha256: writer.writeSetSha256,
+        });
+        return { state: "blocked", reason };
+    }
+    const recorded = await recordWriterAttemptFromCurrent(baseline, {
+        repoRoot: input.cwd,
+    });
+    await writeJournalFile(journalPath, recorded);
+    await input.onAttemptRecorded?.();
+    const restored = await restoreJournal(recorded, { repoRoot: input.cwd });
+    await writeJournalFile(journalPath, restored.journal);
+    if (restored.state === "blocked") {
+        const reason = restored.blockedReason ?? "continuation writer rollback boundary is unprovable";
+        await writeJsonAtomic(transactionPath, {
+            schemaVersion: 1,
+            state: "blocked",
+            blockedAt: new Date().toISOString(),
+            reason,
+            restoredPaths: restored.restoredPaths,
+            writerNodeIds: writer.nodeIds,
+            writeSet: writer.writeSet,
+            writeSetSha256: writer.writeSetSha256,
+        });
+        return { state: "blocked", reason };
+    }
+    await writeJsonAtomic(transactionPath, {
+        schemaVersion: 1,
+        state: "rolled-back",
+        rolledBackAt: new Date().toISOString(),
+        restoredPaths: restored.restoredPaths,
+        writerNodeIds: writer.nodeIds,
+        writeSet: writer.writeSet,
+        writeSetSha256: writer.writeSetSha256,
+    });
+    return { state: "rolled-back" };
+}
 async function stageContinuationRun(input) {
-    const specForRun = input.promptOverrides !== undefined && input.promptOverrides.length > 0
+    const promptAdjustedSpec = input.promptOverrides !== undefined && input.promptOverrides.length > 0
         ? applyPromptOverridesToSpec({
             spec: input.parentSpec,
             plan: input.plan,
             overrides: input.promptOverrides,
         })
-        : input.parentSpec;
+        : structuredClone(input.parentSpec);
+    const dynamicParentNodeIds = input.plan.schemaVersion === 2
+        ? (input.plan.highRiskAuthority?.dynamic?.nodeIds ?? [])
+        : [];
+    const materializedDynamicChildIds = collectMaterializedDynamicChildIds(promptAdjustedSpec, dynamicParentNodeIds);
+    const specForRun = {
+        ...promptAdjustedSpec,
+        tasks: promptAdjustedSpec.tasks.filter((task) => !materializedDynamicChildIds.has(task.id)),
+    };
     const { ranks } = topoSortToRanks(specForRun);
-    const runId = await buildDagRunId(specForRun, { cwd: input.cwd });
+    const workerContinuationAuthority = input.plan.schemaVersion === 2
+        ? input.plan.workerContinuationAuthority
+        : undefined;
+    const runId = workerContinuationAuthority?.childWorkerRunId
+        ?? await buildDagRunId(specForRun, { cwd: input.cwd });
+    if (workerContinuationAuthority && await locateDagRun(input.cwd, runId)) {
+        throw new Error(`WORKER_CONTINUATION_NEEDS_RECONCILE: child DAG already exists: ${runId}`);
+    }
     const runDir = getDagRunDir(input.cwd, "active", runId);
     await prepareActiveRunDir(runDir);
     await writeRunSpec(runDir, specForRun);
+    await captureContinuationWriterTransaction({
+        cwd: input.cwd,
+        runDir,
+        plan: input.plan,
+    });
     const resetSet = new Set(input.plan.resetNodeIds);
     const importedSet = new Set(input.plan.importedNodeIds);
     const tasksById = new Map(specForRun.tasks.map((task) => [task.id, task]));
     const importManifestNodes = [];
     const nodes = {};
     for (const nodeId of input.plan.importedNodeIds) {
+        if (materializedDynamicChildIds.has(nodeId))
+            continue;
         const parentRecord = input.parentState.nodes[nodeId];
         if (!parentRecord) {
             throw new Error(`parent node record missing for imported node: ${nodeId}`);
@@ -458,6 +779,8 @@ async function stageContinuationRun(input) {
         nodes[nodeId] = importedRecord;
     }
     for (const nodeId of input.plan.resetNodeIds) {
+        if (materializedDynamicChildIds.has(nodeId))
+            continue;
         const task = tasksById.get(nodeId);
         if (!task) {
             throw new Error(`reset node missing from spec: ${nodeId}`);
@@ -465,6 +788,8 @@ async function stageContinuationRun(input) {
         nodes[nodeId] = buildPendingNodeRecord(task);
     }
     for (const task of input.parentSpec.tasks) {
+        if (materializedDynamicChildIds.has(task.id))
+            continue;
         if (!resetSet.has(task.id) && !importedSet.has(task.id)) {
             throw new Error(`node ${task.id} missing from rerun plan partition`);
         }
@@ -483,6 +808,29 @@ async function stageContinuationRun(input) {
         ...(input.plan.promptOverrides
             ? { promptOverrides: input.plan.promptOverrides }
             : {}),
+        ...(input.plan.schemaVersion === 2 && input.plan.artifactOverrides
+            ? { artifactOverrides: input.plan.artifactOverrides }
+            : {}),
+        ...(workerContinuationAuthority
+            ? { workerContinuationAuthority }
+            : {}),
+        ...(input.plan.schemaVersion === 2 && input.plan.highRiskAuthority?.budget
+            ? {
+                budgetLineage: {
+                    parentLedgerSha256: input.plan.highRiskAuthority.budget.parentLedgerSha256,
+                    inheritedAt: createdAt,
+                    inheritedConsumed: structuredClone(input.plan.highRiskAuthority.budget.inheritedConsumed),
+                },
+            }
+            : {}),
+        ...(input.plan.schemaVersion === 2 && input.plan.highRiskAuthority?.writer
+            ? {
+                writerTransaction: {
+                    writeSetSha256: input.plan.highRiskAuthority.writer.writeSetSha256,
+                    writerNodeIds: input.plan.highRiskAuthority.writer.nodeIds,
+                },
+            }
+            : {}),
         createdAt,
     };
     const state = {
@@ -504,6 +852,19 @@ async function stageContinuationRun(input) {
         ...(input.parentState.budget
             ? { budget: structuredClone(input.parentState.budget) }
             : {}),
+        ...(input.parentState.budgetLedger
+            ? { budgetLedger: structuredClone(input.parentState.budgetLedger) }
+            : {}),
+        ...(workerContinuationAuthority
+            ? {
+                workerAssociation: {
+                    schemaVersion: 1,
+                    workerRunId: workerContinuationAuthority.childWorkerRunId,
+                    featureId: workerContinuationAuthority.featureId,
+                    taskId: workerContinuationAuthority.taskId,
+                },
+            }
+            : {}),
     };
     if (!input.parentState.skillSnapshotRef) {
         throw new Error("parent run is missing skill snapshot ref");
@@ -514,30 +875,67 @@ async function stageContinuationRun(input) {
         parentRunId: input.parentRunId,
         newRunId: runId,
         newRunDir: runDir,
+        spec: specForRun,
     });
     state.controllerIdentityRef = await captureControllerIdentity({ runDir });
     try {
         const startCheckpoint = await captureWorkspaceCheckpoint(input.cwd);
+        const highRiskWorkspace = input.plan.schemaVersion === 2
+            ? input.plan.highRiskAuthority?.workspaceFingerprint
+            : undefined;
+        if (highRiskWorkspace && startCheckpoint.fingerprint !== highRiskWorkspace) {
+            throw new Error("WORKSPACE_DRIFT: continuation staging no longer matches the planned parent terminal workspace");
+        }
         await writeWorkspaceCheckpoint(runDir, WORKSPACE_CHECKPOINT_START_REL, startCheckpoint);
     }
     catch (error) {
+        if (input.plan.schemaVersion === 2 && input.plan.highRiskAuthority) {
+            throw error;
+        }
         console.warn(`[dag rerun] warning: failed to write workspace start checkpoint: ${error instanceof Error ? error.message : String(error)}`);
     }
+    const overrideManifest = input.plan.schemaVersion === 2 && input.plan.trigger === "artifact-override"
+        ? [await applyArtifactOverrideToStagedRun({
+                parentRunDir: input.parentRunDir,
+                newRunDir: runDir,
+                parentRunId: input.parentRunId,
+                plan: input.plan,
+                candidateBytes: input.artifactCandidateBytes ?? Buffer.alloc(0),
+                nodes,
+                manifestNodes: importManifestNodes,
+            })]
+        : undefined;
     const importManifest = {
         schemaVersion: 1,
         parentRunId: input.parentRunId,
         createdAt,
         nodes: importManifestNodes,
+        ...(overrideManifest ? { overrides: overrideManifest } : {}),
     };
     await writeJsonAtomic(path.join(runDir, IMPORT_MANIFEST_REL_PATH), importManifest);
     await writeJsonAtomic(path.join(runDir, RERUN_PLAN_REL_PATH), input.plan);
     await writeRunState(runDir, state);
     return { runId, runDir, state, spec: specForRun };
 }
+async function settleStagedContinuationWithoutExecution(input) {
+    input.staged.state.status = "failed";
+    input.staged.state.finishedAt = new Date().toISOString();
+    input.staged.state.failureCategory = input.failureCategory;
+    input.staged.state.terminalReason = input.terminalReason;
+    await writeRunState(input.staged.runDir, input.staged.state);
+    return transferDagRunDir(input.staged.runDir, getDagRunDir(input.cwd, "completed", input.staged.runId));
+}
 export async function executeDagRerun(input) {
-    const existing = await readExistingOperatorRequest(input.cwd, input.requestId);
-    if (existing) {
-        return existing;
+    // Replay-first with SF2 envelope validation at the core boundary (same
+    // contract as executeDagArtifactOverrideRerun): an existing operator
+    // request is only a valid idempotent answer when it matches the requested
+    // parent run and plan hash; otherwise REQUEST_ID_REUSE_CONFLICT.
+    const replay = await readOperatorRequestReplay(input.cwd, input.requestId, {
+        parentRunId: input.parentRunId,
+        planHash: input.planHash,
+    });
+    if (replay) {
+        return replay;
     }
     const plan = await planDagRerun({
         cwd: input.cwd,
@@ -545,7 +943,7 @@ export async function executeDagRerun(input) {
         selectedNodeId: input.selectedNodeId,
         promptOverrides: input.promptOverrides,
     });
-    if (plan.planHash !== input.planHash) {
+    if (!constantTimeHashEqual(plan.planHash, input.planHash)) {
         return {
             ok: false,
             plan,
@@ -602,10 +1000,198 @@ export async function executeDagRerun(input) {
         summary,
     };
     if (await fileExists(operatorRequestPath(input.cwd, input.requestId))) {
-        const replay = await readExistingOperatorRequest(input.cwd, input.requestId);
+        const replay = await readOperatorRequestReplay(input.cwd, input.requestId, {
+            parentRunId: input.parentRunId,
+            planHash: input.planHash,
+        });
         if (replay)
             return replay;
     }
     await persistOperatorRequest(input.cwd, result, input.requestId);
     return result;
 }
+export async function executeDagArtifactOverrideRerun(input) {
+    // Replay-first, but with SF2 envelope validation at the core boundary: an
+    // existing operator request is only an idempotent answer when it belongs to
+    // the same parent run AND the same plan hash. A caller that supplies a
+    // different planHash/parent (direct call or a race between CLI validation
+    // and this core) must get REQUEST_ID_REUSE_CONFLICT, never an unvalidated
+    // replay.
+    const replay = await readOperatorRequestReplay(input.cwd, input.requestId, {
+        parentRunId: input.parentRunId,
+        planHash: input.planHash,
+    });
+    if (replay)
+        return replay;
+    const plan = await planDagArtifactOverride({
+        cwd: input.cwd,
+        parentRunId: input.parentRunId,
+        artifactId: input.artifactId,
+        artifactOverrides: input.artifactOverrides,
+        stagingRevisionSha256: input.stagingRevisionSha256,
+        ...(input.workerContinuationAuthority
+            ? { workerContinuationAuthority: input.workerContinuationAuthority }
+            : {}),
+    });
+    if (!constantTimeHashEqual(plan.planHash, input.planHash)) {
+        return {
+            ok: false,
+            plan,
+            errorCode: "RERUN_PLAN_DRIFT",
+            message: "plan hash mismatch; refresh impact preview before executing",
+        };
+    }
+    if (!plan.eligible) {
+        return {
+            ok: false,
+            plan,
+            errorCode: "INELIGIBLE",
+            message: plan.blockedReasons.join(", ") || "artifact continuation is not eligible",
+        };
+    }
+    const override = plan.artifactOverrides?.overrides[0];
+    if (!override || !constantTimeHashEqual(sha256Hex(input.candidateBytes), override.replacement.sha256)) {
+        return {
+            ok: false,
+            plan,
+            errorCode: "ARTIFACT_REVISION_DRIFT",
+            message: "staged revision bytes no longer match the plan",
+        };
+    }
+    const located = await locateDagRun(input.cwd, input.parentRunId);
+    if (!located || located.lifecycle !== "completed") {
+        return {
+            ok: false,
+            plan,
+            errorCode: "PARENT_LIFECYCLE",
+            message: `parent run must be completed: ${input.parentRunId}`,
+        };
+    }
+    const parentManifestBefore = await snapshotDagRunManifest(located.runDir);
+    const parentSpec = await readDagRunSpec(located.runDir);
+    const parentState = await readDagRunState(located.runDir);
+    let staged;
+    try {
+        staged = await stageContinuationRun({
+            cwd: input.cwd,
+            parentRunDir: located.runDir,
+            parentRunId: input.parentRunId,
+            parentSpec,
+            parentState,
+            plan,
+            reason: input.reason,
+            requestId: input.requestId,
+            artifactCandidateBytes: input.candidateBytes,
+        });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        if (message.startsWith("WORKER_CONTINUATION_NEEDS_RECONCILE:")) {
+            const result = {
+                ok: false,
+                plan,
+                newRunId: input.workerContinuationAuthority?.childWorkerRunId,
+                errorCode: "WORKER_CONTINUATION_NEEDS_RECONCILE",
+                message,
+            };
+            await persistOperatorRequest(input.cwd, result, input.requestId);
+            return result;
+        }
+        throw error;
+    }
+    const parentManifestAfterStage = await snapshotDagRunManifest(located.runDir);
+    if (!constantTimeHashEqual(parentManifestBefore, parentManifestAfterStage)) {
+        const settledRunDir = await settleStagedContinuationWithoutExecution({
+            cwd: input.cwd,
+            staged,
+            failureCategory: "parent-immutability-violation",
+            terminalReason: "parent run changed while staging the continuation",
+        });
+        return {
+            ok: false,
+            plan,
+            newRunId: staged.runId,
+            runDir: settledRunDir,
+            errorCode: "PARENT_IMMUTABILITY_VIOLATION",
+            message: "parent run changed while staging the child; child execution was blocked",
+        };
+    }
+    await input.onStaged?.({ runId: staged.runId, runDir: staged.runDir });
+    const plannedWorkspace = plan.highRiskAuthority?.workspaceFingerprint;
+    if (plannedWorkspace) {
+        const beforeExecution = await captureWorkspaceCheckpoint(input.cwd).catch(() => undefined);
+        if (!beforeExecution || beforeExecution.fingerprint !== plannedWorkspace) {
+            const settledRunDir = await settleStagedContinuationWithoutExecution({
+                cwd: input.cwd,
+                staged,
+                failureCategory: "workspace-drift",
+                terminalReason: "workspace changed after continuation staging and before writer execution",
+            });
+            return {
+                ok: false,
+                plan,
+                newRunId: staged.runId,
+                runDir: settledRunDir,
+                errorCode: "WORKSPACE_DRIFT",
+                message: "workspace changed after staging; revision was not consumed and writer execution was blocked",
+            };
+        }
+    }
+    if (input.consumeRevision) {
+        await input.consumeRevision({
+            revisionId: override.revisionId,
+            expectedSha256: override.replacement.sha256,
+        });
+    }
+    const writerTransactionRef = { current: { state: "not-applicable" } };
+    const summary = await runDagContinuation({
+        cwd: input.cwd,
+        spec: staged.spec,
+        state: staged.state,
+        runDir: staged.runDir,
+        ...(input.maxConcurrent !== undefined ? { maxConcurrent: input.maxConcurrent } : {}),
+        ...(input.executeNode ? { executeNode: input.executeNode } : {}),
+        beforeTerminalArchive: async ({ runDir, state }) => {
+            writerTransactionRef.current = await finalizeContinuationWriterTransaction({
+                cwd: input.cwd,
+                runDir,
+                plan,
+                committed: state.status === "finished",
+                ...(input.onWriterAttemptRecorded
+                    ? { onAttemptRecorded: input.onWriterAttemptRecorded }
+                    : {}),
+            });
+            if (writerTransactionRef.current.state === "blocked") {
+                state.status = "failed";
+                state.failureCategory = "writer-rollback-blocked";
+                state.terminalReason = writerTransactionRef.current.reason;
+            }
+        },
+    });
+    const writerTransaction = writerTransactionRef.current;
+    const parentManifestAfterRun = await snapshotDagRunManifest(located.runDir);
+    const immutable = constantTimeHashEqual(parentManifestBefore, parentManifestAfterRun);
+    const result = immutable && writerTransaction.state !== "blocked"
+        ? {
+            ok: summary.status === "finished",
+            plan,
+            newRunId: summary.runId,
+            runDir: summary.runDir,
+            summary,
+        }
+        : {
+            ok: false,
+            plan,
+            newRunId: summary.runId,
+            runDir: summary.runDir,
+            summary,
+            errorCode: writerTransaction.state === "blocked"
+                ? "WRITER_ROLLBACK_BLOCKED"
+                : "PARENT_IMMUTABILITY_VIOLATION",
+            message: writerTransaction.state === "blocked"
+                ? writerTransaction.reason
+                : "parent run manifest changed during child execution",
+        };
+    await persistOperatorRequest(input.cwd, result, input.requestId);
+    return result;
+}