@tea-agent/loop-agent 0.35.1 → 0.35.3

package/dist/workflows/dag/frontend-recovery-root-manifest.js

@@ -0,0 +1,123 @@
+import { mkdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+/**
+ * Phase 6: frontend recovery root manifest — the single final read model for a
+ * frontend recovery chain. A "root" is the first physical run of a
+ * frontend-implementation attempt; its parent/child lineage is counted once
+ * under `recoveryRootRunId`. report/Console read the manifest for dedup and
+ * final-status display instead of scanning parent/child fields (P1-4).
+ */
+export const FRONTEND_RECOVERY_ROOT_MANIFEST_SCHEMA_ID = "frontend-recovery-root-manifest-v1";
+export const frontendRecoveryRootManifestSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    schemaId: z.literal(FRONTEND_RECOVERY_ROOT_MANIFEST_SCHEMA_ID),
+    recoveryRootRunId: z.string().min(1),
+    /** Terminal logical status for the whole chain (finished/partial_failed/failed). */
+    status: z.enum(["finished", "partial_failed", "failed"]),
+    outcome: z.enum([
+        "none",
+        "recovered",
+        "candidate-contract-invalid",
+        "prewrite-blocked",
+        "repair-exhausted",
+        "auto-recovery-blocked",
+    ]),
+    attempts: z.array(z
+        .object({
+        runId: z.string().min(1),
+        role: z.enum(["root", "child"]),
+        attemptIndex: z.number().int().min(0),
+        outcome: z.enum([
+            "none",
+            "recovered",
+            "candidate-contract-invalid",
+            "prewrite-blocked",
+            "repair-exhausted",
+            "auto-recovery-blocked",
+        ]),
+        status: z.enum(["finished", "partial_failed", "failed"]),
+    })
+        .strict()),
+    evidenceRefs: z.array(z
+        .object({
+        runId: z.string().min(1),
+        relativePath: z.string().min(1),
+        sha256: z.string().min(1),
+    })
+        .strict()),
+    createdAt: z.string().min(1),
+})
+    .strict();
+/** Relative path of the root manifest inside a run dir. */
+export const FRONTEND_RECOVERY_ROOT_MANIFEST_REL = "contracts/frontend-recovery-root-manifest.json";
+export function frontendRecoveryRootManifestAbsPath(runDir) {
+    return path.join(runDir, FRONTEND_RECOVERY_ROOT_MANIFEST_REL);
+}
+export async function writeFrontendRecoveryRootManifest(runDir, manifest) {
+    const abs = frontendRecoveryRootManifestAbsPath(runDir);
+    await mkdir(path.dirname(abs), { recursive: true });
+    await writeJsonAtomic(abs, manifest);
+    return abs;
+}
+export async function readFrontendRecoveryRootManifest(runDir) {
+    try {
+        const raw = JSON.parse(await readFile(frontendRecoveryRootManifestAbsPath(runDir), "utf8"));
+        const parsed = frontendRecoveryRootManifestSchema.safeParse(raw);
+        return parsed.success ? parsed.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Build a root manifest from a converged root run's lineage. The manifest is the
+ * single authority for final status/outcome: parent keeps its raw failure status,
+ * the chain's logical status is only `finished` when a child finished and the
+ * outcome is `recovered`.
+ */
+export function buildFrontendRecoveryRootManifest(input) {
+    const status = input.outcome === "recovered" ? "finished" : "failed";
+    return {
+        schemaVersion: 1,
+        schemaId: FRONTEND_RECOVERY_ROOT_MANIFEST_SCHEMA_ID,
+        recoveryRootRunId: input.recoveryRootRunId,
+        status,
+        outcome: input.outcome,
+        attempts: input.attempts,
+        evidenceRefs: input.evidenceRefs ?? [],
+        createdAt: input.createdAt ?? new Date().toISOString(),
+    };
+}
+/**
+ * Dedup a set of DAG runs by recovery root (P1-4): each root contributes exactly
+ * one summary; parent/child physical runs are folded into the root's attempts.
+ * A run with no `frontendRecoveryState` is its own single-attempt root.
+ */
+export function aggregateFrontendRecoveryRoots(runs) {
+    const byRoot = new Map();
+    for (const run of runs) {
+        const rootId = run.frontendRecoveryState?.recoveryRootRunId ?? run.runId;
+        const list = byRoot.get(rootId) ?? [];
+        list.push(run);
+        byRoot.set(rootId, list);
+    }
+    const result = [];
+    for (const [rootId, list] of byRoot) {
+        const sorted = [...list].sort((a, b) => (a.frontendRecoveryState?.attemptIndex ?? 0) -
+            (b.frontendRecoveryState?.attemptIndex ?? 0));
+        // The root's displayed status is the last attempt's status, unless the
+        // root run itself finished (a child recovered only surfaces `finished`
+        // via the manifest, not via the raw root run status).
+        const last = sorted[sorted.length - 1];
+        result.push({
+            recoveryRootRunId: rootId,
+            status: last.status,
+            attemptCount: sorted.length,
+            runIds: sorted.map((run) => run.runId),
+        });
+    }
+    return result;
+}

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

@@ -0,0 +1,539 @@
+import { copyFile, mkdir, readdir, readFile, rm, access } from "node:fs/promises";
+import path from "node:path";
+import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
+import { sha256Hex } from "./frontend-implementation-contract.js";
+import { FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, FRONTEND_RECOVERY_INTENT_REL_DIR, FRONTEND_RECOVERY_STAGING_PREFIX, computeFrontendRecoveryPlan, computeFrontendRecoveryPlanForSource, } from "./frontend-recovery-plan.js";
+import { dagRunDirExists, getDagRunDir, readDagRunSpec, readDagRunState, transferDagRunDir, writeDagRunState, } from "./lifecycle.js";
+import { buildDagRunId } from "./runner.js";
+import { prepareRunDir, writeNodeRecord } from "./run-store.js";
+import { FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT, readFrontendPrewriteResult, } from "./scheduler.js";
+import { topoSortToRanks } from "./topo.js";
+/**
+ * Candidate-continuation child creation kernel (phase 3b).
+ *
+ * Parent terminal convergence (phase 3a) has already persisted a recovery
+ * intent on `DagRunState.frontendRecoveryState`. This module is the single
+ * writer that stages and commits one reserved child run per requestId, with a
+ * commit-point handoff: CAS-reserve childRunId → stage files (hash-verified) →
+ * rename into active/ → activation marker → three-way consistency check → CAS
+ * phase=child-running. Scheduling/execution of the child is phase 3c and out
+ * of scope here.
+ */
+/** Canonical contract artifact default location; overridden by the prewrite
+ * gate's configured outputDir/artifactName when present. */
+const FRONTEND_CANONICAL_CONTRACT_DEFAULT_REL_PATH = "contracts/frontend-implementation-contract.json";
+function resolveDeps(deps) {
+    return {
+        readParentState: deps?.readParentState ?? readDagRunState,
+        writeParentState: deps?.writeParentState ?? writeDagRunState,
+        writeMarker: deps?.writeMarker ??
+            ((markerPath, marker) => writeJsonAtomic(markerPath, marker)),
+    };
+}
+function frontendRecoveryMarkerRelPath(parentRunDir, requestId) {
+    return path.join(parentRunDir, FRONTEND_RECOVERY_INTENT_REL_DIR, `${requestId}.json`);
+}
+async function hashFile(filePath) {
+    return sha256Hex(await readFile(filePath, "utf8"));
+}
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isValidFrontendRecoveryMarker(raw) {
+    return (raw.schemaVersion === 1 &&
+        typeof raw.recoveryRootRunId === "string" &&
+        raw.recoveryRootRunId.length > 0 &&
+        typeof raw.parentRunId === "string" &&
+        raw.parentRunId.length > 0 &&
+        typeof raw.childRunId === "string" &&
+        raw.childRunId.length > 0 &&
+        typeof raw.requestId === "string" &&
+        raw.requestId.length > 0 &&
+        typeof raw.importManifestSha256 === "string" &&
+        /^[a-f0-9]{64}$/.test(raw.importManifestSha256));
+}
+/**
+ * Read + validate the activation marker. Missing or invalid markers return
+ * `undefined` so the phase-3c gate and tests can treat an unmarked active
+ * child as not executable (AC-2 / AC-5d).
+ */
+export async function readFrontendRecoveryMarker(parentRunDir, requestId) {
+    let raw;
+    try {
+        raw = JSON.parse(await readFile(frontendRecoveryMarkerRelPath(parentRunDir, requestId), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    if (!isValidFrontendRecoveryMarker(raw)) {
+        return undefined;
+    }
+    return raw;
+}
+function classifyFrontendFactKind(nodeId) {
+    if (/prewrite/i.test(nodeId))
+        return "prewrite";
+    if (/scout/i.test(nodeId))
+        return "scout";
+    if (/contract/i.test(nodeId))
+        return "contract";
+    if (/plan/i.test(nodeId))
+        return "plan";
+    return "plan";
+}
+function resolveCanonicalContractRelPath(spec) {
+    for (const task of spec.tasks) {
+        const gate = task.shell?.frontendPrewriteGate;
+        if (gate) {
+            return path.posix.join(gate.outputDir, gate.artifactName);
+        }
+    }
+    return FRONTEND_CANONICAL_CONTRACT_DEFAULT_REL_PATH;
+}
+function normalizeRunRelativePath(relPath) {
+    return relPath.replace(/\\/g, "/");
+}
+function assertArtifactPathWithinParentRun(parentRunDir, artifactPath) {
+    if (!path.isAbsolute(artifactPath)) {
+        return normalizeRunRelativePath(artifactPath);
+    }
+    const resolved = path.resolve(artifactPath);
+    const parentResolved = path.resolve(parentRunDir);
+    if (resolved !== parentResolved &&
+        !resolved.startsWith(`${parentResolved}${path.sep}`)) {
+        throw new Error(`artifact path outside parent run directory: ${artifactPath}`);
+    }
+    return normalizeRunRelativePath(path.relative(parentResolved, resolved));
+}
+function collectNodeArtifactRelativePaths(record) {
+    const paths = new Set([`${record.id}.json`]);
+    const add = (value) => {
+        if (value?.trim())
+            paths.add(normalizeRunRelativePath(value.trim()));
+    };
+    add(record.stdoutArtifactPath);
+    add(record.assistantArtifactPath);
+    add(record.structuredArtifactPath);
+    add(record.nodeRecordPath);
+    add(record.escalationArtifactPath);
+    add(record.humanApprovalArtifactPath);
+    add(record.humanRejectionArtifactPath);
+    for (const attempt of record.attempts ?? []) {
+        add(attempt.artifactPath);
+    }
+    return [...paths];
+}
+async function listNodeDirectoryArtifacts(parentRunDir, nodeId) {
+    const nodeDir = path.join(parentRunDir, nodeId);
+    if (!(await fileExists(nodeDir)))
+        return [];
+    const entries = await readdir(nodeDir, { withFileTypes: true });
+    const artifacts = [];
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        artifacts.push(normalizeRunRelativePath(path.join(nodeId, entry.name)));
+    }
+    return artifacts;
+}
+async function copyArtifactVerified(input) {
+    const normalized = assertArtifactPathWithinParentRun(input.parentRunDir, input.relativePath);
+    const sourcePath = path.join(input.parentRunDir, ...normalized.split("/"));
+    if (!(await fileExists(sourcePath))) {
+        throw new Error(`missing imported artifact: ${normalized}`);
+    }
+    const expected = await hashFile(sourcePath);
+    const destinationPath = path.join(input.newRunDir, ...normalized.split("/"));
+    await mkdir(path.dirname(destinationPath), { recursive: true });
+    await copyFile(sourcePath, destinationPath);
+    const actual = await hashFile(destinationPath);
+    if (actual !== expected) {
+        throw new Error(`copy hash mismatch for artifact: ${normalized}`);
+    }
+    return { destinationRelativePath: normalized, sha256: actual };
+}
+function normalizeImportedArtifactPath(parentRunDir, newRunDir, artifactPath) {
+    if (!artifactPath?.trim())
+        return artifactPath;
+    const relative = assertArtifactPathWithinParentRun(parentRunDir, artifactPath);
+    return path.join(newRunDir, ...relative.split("/"));
+}
+function buildImportedNodeRecord(parentRecord, parentRunId, sourceNodeRecordSha256, parentRunDir, newRunDir) {
+    const { origin: _origin, ...rest } = parentRecord;
+    void _origin;
+    const imported = structuredClone(rest);
+    imported.nodeRecordPath = path.join(newRunDir, `${parentRecord.id}.json`);
+    for (const key of [
+        "stdoutArtifactPath",
+        "assistantArtifactPath",
+        "structuredArtifactPath",
+        "escalationArtifactPath",
+        "humanApprovalArtifactPath",
+        "humanRejectionArtifactPath",
+    ]) {
+        imported[key] = normalizeImportedArtifactPath(parentRunDir, newRunDir, imported[key]);
+    }
+    return {
+        ...imported,
+        origin: {
+            kind: "imported",
+            parentRunId,
+            sourceNodeRecordSha256,
+        },
+    };
+}
+function buildPendingNodeRecord(task) {
+    return {
+        id: task.id,
+        status: "PENDING",
+        executor: task.executor,
+        complexity: task.complexity,
+        origin: { kind: "executed" },
+        ...(task.outputMode ? { outputMode: task.outputMode } : {}),
+    };
+}
+async function importNodeFacts(input) {
+    const nodeJsonRel = `${input.nodeId}.json`;
+    const parentNodeJsonPath = path.join(input.parentRunDir, nodeJsonRel);
+    const sourceNodeRecordSha256 = (await fileExists(parentNodeJsonPath))
+        ? await hashFile(parentNodeJsonPath)
+        : sha256Hex(`${JSON.stringify(input.parentRecord, null, 2)}\n`);
+    const importedRecord = buildImportedNodeRecord(input.parentRecord, input.parentRunId, sourceNodeRecordSha256, input.parentRunDir, input.newRunDir);
+    await writeNodeRecord(input.newRunDir, input.nodeId, importedRecord);
+    const relativePaths = [
+        ...new Set([
+            ...collectNodeArtifactRelativePaths(input.parentRecord).filter((relativePath) => relativePath !== nodeJsonRel),
+            ...(await listNodeDirectoryArtifacts(input.parentRunDir, input.nodeId)),
+        ]),
+    ];
+    const artifacts = [
+        {
+            sourceRelativePath: nodeJsonRel,
+            destinationRelativePath: nodeJsonRel,
+            sha256: await hashFile(path.join(input.newRunDir, nodeJsonRel)),
+        },
+    ];
+    for (const relativePath of relativePaths.sort()) {
+        const copied = await copyArtifactVerified({
+            parentRunDir: input.parentRunDir,
+            newRunDir: input.newRunDir,
+            relativePath,
+        });
+        artifacts.push({
+            sourceRelativePath: relativePath,
+            destinationRelativePath: copied.destinationRelativePath,
+            sha256: copied.sha256,
+        });
+    }
+    return {
+        fact: {
+            nodeId: input.nodeId,
+            kind: classifyFrontendFactKind(input.nodeId),
+            artifacts,
+        },
+        importedRecord,
+    };
+}
+/** Write JSON atomically, then re-read the bytes and verify the hash matches
+ * the exact serialization we intended (AC-1 per-file hash verification). */
+async function writeJsonVerified(runDir, relPath, value) {
+    const expectedJson = `${JSON.stringify(value, null, 2)}\n`;
+    const targetPath = path.join(runDir, ...relPath.split("/"));
+    await writeJsonAtomic(targetPath, value);
+    const actual = await hashFile(targetPath);
+    const expected = sha256Hex(expectedJson);
+    if (actual !== expected) {
+        throw new Error(`hash verification failed after writing ${relPath}`);
+    }
+    return actual;
+}
+async function casUpdateFrontendRecoveryState(parentRunDir, expectedRevision, deps, mutate) {
+    const state = await deps.readParentState(parentRunDir);
+    const recovery = state.frontendRecoveryState;
+    if (!recovery) {
+        throw new Error("parent frontend recovery intent missing during CAS update");
+    }
+    if (recovery.revision !== expectedRevision) {
+        throw new Error(`frontend recovery revision drifted (expected ${expectedRevision}, found ${recovery.revision}); refuse to continue`);
+    }
+    mutate(recovery);
+    recovery.revision = expectedRevision + 1;
+    state.frontendRecoveryState = recovery;
+    await deps.writeParentState(parentRunDir, state);
+}
+async function materializeChildStaging(input) {
+    const { cwd, parentRunDir, parentRunId, parentSpec, parentState, recovery, requestId, childRunId, stagingDir, createdAt, } = input;
+    await prepareRunDir(stagingDir);
+    await writeJsonVerified(stagingDir, "run.json", parentSpec);
+    // Phase 5: writer transient partial-write recovery resets the writer subtree
+    // (frontend-implement-pi) instead of the candidate producer; everything
+    // upstream is imported as verified parent facts.
+    let plan;
+    if (recovery.failureSource) {
+        plan = computeFrontendRecoveryPlanForSource({
+            spec: parentSpec,
+            parentRunId,
+            requestId,
+            failureSource: recovery.failureSource,
+        });
+    }
+    else {
+        const prewriteRead = await readFrontendPrewriteResult(parentRunDir);
+        if (!prewriteRead.ok) {
+            throw new Error(prewriteRead.reason);
+        }
+        plan = computeFrontendRecoveryPlan({
+            spec: parentSpec,
+            parentRunId,
+            requestId,
+            result: prewriteRead.result,
+        });
+    }
+    const { ranks } = topoSortToRanks(parentSpec);
+    const resetSet = new Set(plan.resetNodeIds);
+    const importedSet = new Set(plan.importedNodeIds);
+    const tasksById = new Map(parentSpec.tasks.map((task) => [task.id, task]));
+    const nodes = {};
+    const importedFacts = [];
+    for (const nodeId of plan.importedNodeIds) {
+        const parentRecord = parentState.nodes[nodeId];
+        if (!parentRecord) {
+            throw new Error(`parent node record missing for imported node: ${nodeId}`);
+        }
+        const { fact, importedRecord } = await importNodeFacts({
+            parentRunDir,
+            newRunDir: stagingDir,
+            parentRunId,
+            nodeId,
+            parentRecord,
+        });
+        importedFacts.push(fact);
+        nodes[nodeId] = importedRecord;
+    }
+    for (const nodeId of plan.resetNodeIds) {
+        const task = tasksById.get(nodeId);
+        if (!task) {
+            throw new Error(`reset node missing from spec: ${nodeId}`);
+        }
+        nodes[nodeId] = buildPendingNodeRecord(task);
+    }
+    for (const task of parentSpec.tasks) {
+        if (!resetSet.has(task.id) && !importedSet.has(task.id)) {
+            throw new Error(`node ${task.id} missing from frontend recovery plan partition`);
+        }
+    }
+    // Canonical contract + prewrite-result identity facts are copied alongside
+    // the per-node facts so reset nodes can re-read them (AC-4).
+    const canonicalContract = await copyArtifactVerified({
+        parentRunDir,
+        newRunDir: stagingDir,
+        relativePath: resolveCanonicalContractRelPath(parentSpec),
+    });
+    const prewriteResult = await copyArtifactVerified({
+        parentRunDir,
+        newRunDir: stagingDir,
+        relativePath: FRONTEND_PREWRITE_RESULT_SOURCE_ARTIFACT,
+    });
+    const childState = {
+        version: 1,
+        title: parentSpec.title,
+        runId: childRunId,
+        cwd,
+        startedAt: createdAt,
+        status: "pending",
+        ranks,
+        nodes,
+        frontendRecoveryState: {
+            schemaVersion: 1,
+            phase: "child-running",
+            requestId,
+            recoveryRootRunId: recovery.recoveryRootRunId,
+            parentRunId,
+            childRunId,
+            attemptId: recovery.attemptId,
+            attemptIndex: 1,
+            continuationCount: 1,
+            revision: 0,
+        },
+        ...(parentState.evaluation
+            ? { evaluation: structuredClone(parentState.evaluation) }
+            : {}),
+    };
+    await writeJsonVerified(stagingDir, "state.json", childState);
+    const importManifest = {
+        schemaVersion: 1,
+        parentRunId,
+        requestId,
+        createdAt,
+        canonicalContract: {
+            relativePath: canonicalContract.destinationRelativePath,
+            sha256: canonicalContract.sha256,
+        },
+        prewriteResult: {
+            relativePath: prewriteResult.destinationRelativePath,
+            sha256: prewriteResult.sha256,
+        },
+        importedFacts,
+    };
+    await writeJsonVerified(stagingDir, FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH, importManifest);
+}
+async function verifyThreeWayConsistency(input) {
+    const parentState = await input.deps.readParentState(input.parentRunDir);
+    const childState = await readDagRunState(input.activeChildDir);
+    const parentRecovery = parentState.frontendRecoveryState;
+    if (!parentRecovery || parentRecovery.childRunId !== input.childRunId) {
+        throw new Error("three-way consistency failure: parent childRunId mismatch");
+    }
+    if (childState.runId !== input.childRunId) {
+        throw new Error("three-way consistency failure: child state runId mismatch");
+    }
+    if (input.marker.childRunId !== input.childRunId) {
+        throw new Error("three-way consistency failure: marker childRunId mismatch");
+    }
+    if (input.marker.requestId !== input.requestId) {
+        throw new Error("three-way consistency failure: marker requestId mismatch");
+    }
+    if (input.marker.parentRunId !== input.parentRunId) {
+        throw new Error("three-way consistency failure: marker parentRunId mismatch");
+    }
+    if (input.marker.recoveryRootRunId !== input.recoveryRootRunId) {
+        throw new Error("three-way consistency failure: marker recoveryRootRunId mismatch");
+    }
+    const actualManifestSha256 = await hashFile(path.join(input.activeChildDir, FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH));
+    if (actualManifestSha256 !== input.marker.importManifestSha256) {
+        throw new Error("three-way consistency failure: import manifest sha256 mismatch");
+    }
+}
+/**
+ * Stage and commit one reserved child run for a parent frontend recovery
+ * intent. Single-writer: the recovery coordinator is the only caller.
+ * Fail-closed on revision drift, missing intent, unreadable prewrite result,
+ * hash mismatch, marker-write failure, or consistency failure.
+ */
+export async function stageRecoveryChild(options) {
+    const { cwd, parentRunId } = options;
+    const now = options.now ?? new Date();
+    const createdAt = now.toISOString();
+    const deps = resolveDeps(options.dependencies);
+    const parentRunDir = getDagRunDir(cwd, "active", parentRunId);
+    const parentState = await deps.readParentState(parentRunDir);
+    const parentSpec = await readDagRunSpec(parentRunDir);
+    const recovery = parentState.frontendRecoveryState;
+    if (!recovery) {
+        throw new Error(`parent run ${parentRunId} has no frontend recovery intent`);
+    }
+    const requestId = recovery.requestId;
+    if (!requestId) {
+        throw new Error(`parent run ${parentRunId} recovery intent has no requestId`);
+    }
+    // Idempotent short-circuit (D4.2): reserved childRunId + activated marker +
+    // existing child dir means the request was already fully committed.
+    if (recovery.childRunId) {
+        const existingMarker = await readFrontendRecoveryMarker(parentRunDir, requestId);
+        if (existingMarker) {
+            const existingChildDir = getDagRunDir(cwd, "active", existingMarker.childRunId);
+            if (await dagRunDirExists(existingChildDir)) {
+                return {
+                    ok: true,
+                    childRunId: existingMarker.childRunId,
+                    childRunDir: existingChildDir,
+                    marker: existingMarker,
+                    idempotentReplay: true,
+                };
+            }
+        }
+    }
+    // Derive the childRunId exactly once; replay always reuses a reserved id.
+    const childRunId = recovery.childRunId ??
+        (await (options.buildChildRunId ?? buildDagRunId)(parentSpec, cwd));
+    // Orphan staging cleanup (D4.3): remove any in-flight staging dir for this id.
+    const activeRootDir = getDagRunDir(cwd, "active", "");
+    const stagingDir = path.join(activeRootDir, `${FRONTEND_RECOVERY_STAGING_PREFIX}${childRunId}`);
+    await rm(stagingDir, { recursive: true, force: true });
+    // CAS #1: reserve childRunId (phase stays child-staging) before any child
+    // files exist, so a crash can never produce two children for one requestId.
+    if (!recovery.childRunId) {
+        await casUpdateFrontendRecoveryState(parentRunDir, recovery.revision, deps, (rec) => {
+            rec.childRunId = childRunId;
+            rec.phase = "child-staging";
+        });
+    }
+    const parentAfterReserve = await deps.readParentState(parentRunDir);
+    const reserved = parentAfterReserve.frontendRecoveryState;
+    if (!reserved || reserved.childRunId !== childRunId) {
+        throw new Error("frontend recovery reservation drift after CAS; refuse to continue");
+    }
+    const activeChildDir = getDagRunDir(cwd, "active", childRunId);
+    const childDirExists = await dagRunDirExists(activeChildDir);
+    let importManifestSha256;
+    if (childDirExists) {
+        // Crash between rename and marker write: the child is already fully
+        // materialized. Recover by rewriting the marker instead of rebuilding.
+        importManifestSha256 = await hashFile(path.join(activeChildDir, FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH));
+    }
+    else {
+        await materializeChildStaging({
+            cwd,
+            parentRunDir,
+            parentRunId,
+            parentSpec,
+            parentState,
+            recovery,
+            requestId,
+            childRunId,
+            stagingDir,
+            createdAt,
+        });
+        await transferDagRunDir(stagingDir, activeChildDir);
+        importManifestSha256 = await hashFile(path.join(activeChildDir, FRONTEND_RECOVERY_IMPORT_MANIFEST_REL_PATH));
+    }
+    const marker = {
+        schemaVersion: 1,
+        requestId,
+        recoveryRootRunId: recovery.recoveryRootRunId,
+        parentRunId,
+        childRunId,
+        importManifestSha256,
+        createdAt,
+        activatedAt: createdAt,
+    };
+    const markerPath = frontendRecoveryMarkerRelPath(parentRunDir, requestId);
+    try {
+        await deps.writeMarker(markerPath, marker);
+        await verifyThreeWayConsistency({
+            parentRunDir,
+            activeChildDir,
+            marker,
+            parentRunId,
+            requestId,
+            recoveryRootRunId: recovery.recoveryRootRunId,
+            childRunId,
+            deps,
+        });
+        await casUpdateFrontendRecoveryState(parentRunDir, reserved.revision, deps, (rec) => {
+            rec.phase = "child-running";
+        });
+    }
+    catch (error) {
+        // Best-effort cleanup so no marker-less active child survives. If cleanup
+        // fails, the unmarked child remains non-executable (AC-2).
+        await rm(activeChildDir, { recursive: true, force: true }).catch(() => { });
+        await rm(stagingDir, { recursive: true, force: true }).catch(() => { });
+        throw error;
+    }
+    return {
+        ok: true,
+        childRunId,
+        childRunDir: activeChildDir,
+        marker,
+        idempotentReplay: false,
+    };
+}