@tea-agent/loop-agent 0.35.1-beta.3 → 0.35.1

package/dist/workflows/dag/frontend-writer-rollback.js

@@ -1,821 +0,0 @@
-import { createHash } from "node:crypto";
-import { chmod, lstat, mkdir, readFile, readdir, readlink, realpath, symlink, unlink, writeFile, } from "node:fs/promises";
-import path from "node:path";
-import { z } from "zod";
-import { writeJsonAtomic } from "../../infrastructure/harness/atomic-write.js";
-import { pathMatchesPattern } from "../../shared/git-progress.js";
-/**
- * Writer transient-failure rollback primitive (phase 4).
- *
- * Captures a content snapshot of every writeSet-matched file before an attempt,
- * then restores the baseline using per-path CAS (compare-and-swap on the
- * content hash) so a concurrent/external edit is never overwritten or deleted.
- * A journal state machine (`pending → restoring → completed | blocked`) plus a
- * crash-recovery runner make the primitive resumable and fail-closed.
- *
- * Non-goals (phase 5/6): candidate continuation, child creation, recovery
- * coordinator wiring, report/Console consumption. No git command is invoked,
- * and `git reset --hard` is intentionally absent.
- */
-export const FRONTEND_WRITER_ROLLBACK_SCHEMA_ID = "frontend-writer-rollback-v1";
-export const frontendWriterFileStateSchema = z.enum([
-    "absent", // baseline does not exist (allowed new file)
-    "present", // regular file
-    "symlink", // symbolic link
-    "untracked", // untracked file
-    "deleted", // attempt deleted the baseline
-    "renamed", // attempt renamed the baseline
-]);
-export const frontendWriterJournalStateSchema = z.enum([
-    "pending",
-    "restoring",
-    "completed",
-    "blocked",
-]);
-export const frontendWriterPathStateSchema = z.enum([
-    "pending",
-    "restoring",
-    "verified",
-    "failed",
-]);
-const safePath = z
-    .string()
-    .min(1)
-    .refine((value) => !value.startsWith("/") &&
-    !value.includes("\\") &&
-    !value.split("/").includes(".."), "must be a relative POSIX path without traversal");
-const hash64 = z.string().regex(/^[a-f0-9]{64}$/);
-/**
- * Buffer-safe SHA-256. Unlike `frontend-implementation-contract.ts`'s
- * `sha256Hex` (utf8-only), this accepts a raw Buffer so non-UTF-8 files are
- * fingerprinted by their exact bytes.
- */
-export function sha256HexBytes(input) {
-    return createHash("sha256").update(input).digest("hex");
-}
-/** Baseline hash sentinel for a path that had no baseline content. */
-export function absentBaselineSha256(relPath) {
-    return sha256HexBytes(`absent:${relPath}`);
-}
-export const frontendWriterExistingFileSchema = z
-    .object({
-    path: safePath,
-    state: frontendWriterFileStateSchema,
-    mode: z.string().regex(/^[0-7]+$/).optional(),
-    baselineSha256: hash64,
-    baselineContentBase64: z.string().nullable(),
-    symlinkTarget: z.string().optional(),
-    renameTarget: safePath.optional(),
-})
-    .strict();
-export const frontendWriterJournalFileSchema = z
-    .object({
-    state: frontendWriterPathStateSchema,
-    baselineSha256: hash64,
-    attemptSha256: hash64.nullable(),
-    restoreSha256: hash64.nullable(),
-})
-    .strict();
-export const frontendWriterRollbackV1Schema = z
-    .object({
-    schemaVersion: z.literal(1),
-    schemaId: z.literal(FRONTEND_WRITER_ROLLBACK_SCHEMA_ID),
-    capturedAt: z.string().min(1),
-    writeSet: z.array(safePath).min(1),
-    existingFiles: z.array(frontendWriterExistingFileSchema),
-    allowedNewFiles: z.array(z.object({ pathPattern: safePath }).strict()),
-    attemptChangedPaths: z.array(safePath),
-    attemptFileHashes: z.record(safePath, z.union([hash64, z.literal("absent")])),
-    journal: z
-        .object({
-        state: frontendWriterJournalStateSchema,
-        blockedReason: z.string().nullable(),
-        files: z.record(safePath, frontendWriterJournalFileSchema),
-    })
-        .strict(),
-})
-    .strict()
-    .superRefine((value, ctx) => {
-    // completed requires every journal path to be verified.
-    if (value.journal.state === "completed") {
-        for (const [filePath, file] of Object.entries(value.journal.files)) {
-            if (file.state !== "verified") {
-                ctx.addIssue({
-                    code: z.ZodIssueCode.custom,
-                    message: `journal completed but ${filePath} is not verified`,
-                    path: ["journal", "files", filePath],
-                });
-            }
-        }
-    }
-    // blocked requires an explicit reason.
-    if (value.journal.state === "blocked" && !value.journal.blockedReason) {
-        ctx.addIssue({
-            code: z.ZodIssueCode.custom,
-            message: "blocked journal requires a non-empty blockedReason",
-            path: ["journal", "blockedReason"],
-        });
-    }
-    // deleted baselines must be recorded absent after the attempt.
-    for (const file of value.existingFiles) {
-        if (file.state === "deleted" && value.attemptFileHashes[file.path] !== "absent") {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `deleted baseline ${file.path} must be absent in attemptFileHashes`,
-                path: ["attemptFileHashes", file.path],
-            });
-        }
-    }
-    // rename boundaries must be provable: old path absent, new path hashed,
-    // and the new path is recorded as an attempt-changed path.
-    const existingByPath = new Map(value.existingFiles.map((file) => [file.path, file]));
-    for (const file of value.existingFiles) {
-        if (file.state !== "renamed")
-            continue;
-        if (!file.renameTarget) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `renamed file ${file.path} requires renameTarget`,
-                path: ["existingFiles", file.path],
-            });
-            continue;
-        }
-        if (!value.attemptChangedPaths.includes(file.renameTarget)) {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `rename target ${file.renameTarget} missing from attemptChangedPaths`,
-                path: ["existingFiles", file.path],
-            });
-        }
-        if (value.attemptFileHashes[file.path] !== "absent") {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `renamed old path ${file.path} must be absent after attempt`,
-                path: ["attemptFileHashes", file.path],
-            });
-        }
-        const targetHash = value.attemptFileHashes[file.renameTarget];
-        if (targetHash === undefined || targetHash === "absent") {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `rename target ${file.renameTarget} requires a content hash`,
-                path: ["attemptFileHashes", file.renameTarget],
-            });
-        }
-        const colliding = existingByPath.get(file.renameTarget);
-        if (colliding &&
-            colliding.path !== file.path &&
-            colliding.state !== "deleted" &&
-            colliding.state !== "renamed") {
-            ctx.addIssue({
-                code: z.ZodIssueCode.custom,
-                message: `rename target ${file.renameTarget} collides with a baseline file`,
-                path: ["existingFiles", file.path],
-            });
-        }
-    }
-});
-function resolveDeps(deps) {
-    return {
-        lstat: deps?.lstat ?? lstat,
-        readFile: deps?.readFile ?? readFile,
-        writeFile: deps?.writeFile ?? ((p, d) => writeFile(p, d)),
-        unlink: deps?.unlink ?? unlink,
-        chmod: deps?.chmod ?? chmod,
-        mkdir: deps?.mkdir ?? mkdir,
-        readdir: deps?.readdir ?? ((p, o) => readdir(p, o)),
-        readlink: deps?.readlink ?? readlink,
-        realpath: deps?.realpath ?? realpath,
-        symlink: deps?.symlink ?? symlink,
-        now: deps?.now ?? (() => new Date()),
-    };
-}
-const SKIPPED_DIR_NAMES = new Set([".git", "node_modules", ".harness", "artifacts"]);
-function toAttemptSha256(attemptHash) {
-    return attemptHash !== undefined && attemptHash !== "absent"
-        ? attemptHash
-        : null;
-}
-async function isSubmoduleDirectory(absDir, deps) {
-    try {
-        const gitFile = await deps.lstat(path.join(absDir, ".git"));
-        return gitFile.isFile();
-    }
-    catch {
-        return false;
-    }
-}
-async function walkMatchingEntries(absDir, relDir, writeSet, deps, onMatch) {
-    const entries = await deps.readdir(absDir, { withFileTypes: true });
-    for (const entry of entries) {
-        if (entry.isDirectory()) {
-            if (SKIPPED_DIR_NAMES.has(entry.name))
-                continue;
-            const childRel = relDir ? `${relDir}/${entry.name}` : entry.name;
-            const childAbs = path.join(absDir, entry.name);
-            if (writeSet.some((pattern) => pathMatchesPattern(childRel, pattern)) &&
-                (await isSubmoduleDirectory(childAbs, deps))) {
-                onMatch({ relPath: childRel, kind: "dir" });
-            }
-            await walkMatchingEntries(childAbs, childRel, writeSet, deps, onMatch);
-            continue;
-        }
-        const childRel = relDir ? `${relDir}/${entry.name}` : entry.name;
-        if (!writeSet.some((pattern) => pathMatchesPattern(childRel, pattern))) {
-            continue;
-        }
-        onMatch({
-            relPath: childRel,
-            kind: entry.isSymbolicLink() ? "symlink" : "file",
-        });
-    }
-}
-/**
- * AC-2: two-segment baseline inventory. The first segment snapshots every
- * existing file/symlink/submodule matched by the writeSet globs (content +
- * mode + state); the second records concrete (non-glob) writeSet entries that
- * do not yet exist as allowed-new rules.
- */
-export async function captureWriterBaseline(repoRoot, writeSet, options) {
-    if (writeSet.length === 0) {
-        throw new Error("captureWriterBaseline requires a non-empty writeSet");
-    }
-    const deps = resolveDeps(options?.dependencies);
-    const capturedAt = (options?.now ?? deps.now()).toISOString();
-    const matches = [];
-    await walkMatchingEntries(repoRoot, "", writeSet, deps, (match) => matches.push(match));
-    matches.sort((a, b) => a.relPath.localeCompare(b.relPath));
-    const existingFiles = [];
-    for (const match of matches) {
-        const abs = path.join(repoRoot, match.relPath);
-        const st = await deps.lstat(abs);
-        const mode = (st.mode & 0o777777).toString(8);
-        if (match.kind === "symlink") {
-            const target = await deps
-                .realpath(abs)
-                .catch(async () => deps.readlink(abs));
-            existingFiles.push({
-                path: match.relPath,
-                state: "symlink",
-                mode,
-                baselineSha256: sha256HexBytes(`symlink:${match.relPath}->${target}`),
-                baselineContentBase64: null,
-                symlinkTarget: target,
-            });
-            continue;
-        }
-        if (match.kind === "dir") {
-            existingFiles.push({
-                path: match.relPath,
-                state: "present",
-                mode,
-                baselineSha256: sha256HexBytes(`dir:${match.relPath}`),
-                baselineContentBase64: null,
-            });
-            continue;
-        }
-        const bytes = await deps.readFile(abs);
-        existingFiles.push({
-            path: match.relPath,
-            state: "present",
-            mode,
-            baselineSha256: sha256HexBytes(bytes),
-            baselineContentBase64: bytes.toString("base64"),
-        });
-    }
-    const existingPaths = new Set(existingFiles.map((file) => file.path));
-    const allowedNewFiles = [];
-    for (const pattern of writeSet) {
-        if (pattern.includes("*"))
-            continue;
-        const normalized = pattern.replace(/\/+$/, "");
-        if (!normalized || existingPaths.has(normalized))
-            continue;
-        try {
-            await deps.lstat(path.join(repoRoot, normalized));
-            // Concrete path already exists (file or directory): not an allowed-new rule.
-            continue;
-        }
-        catch {
-            // Missing concrete path → allowed-new rule.
-        }
-        if (!allowedNewFiles.some((entry) => entry.pathPattern === normalized)) {
-            allowedNewFiles.push({ pathPattern: normalized });
-        }
-    }
-    allowedNewFiles.sort((a, b) => a.pathPattern.localeCompare(b.pathPattern));
-    const journalFiles = {};
-    for (const file of existingFiles) {
-        journalFiles[file.path] = {
-            state: "pending",
-            baselineSha256: file.baselineSha256,
-            attemptSha256: null,
-            restoreSha256: null,
-        };
-    }
-    return {
-        schemaVersion: 1,
-        schemaId: FRONTEND_WRITER_ROLLBACK_SCHEMA_ID,
-        capturedAt,
-        writeSet: [...writeSet].sort((a, b) => a.localeCompare(b)),
-        existingFiles,
-        allowedNewFiles,
-        attemptChangedPaths: [],
-        attemptFileHashes: {},
-        journal: { state: "pending", blockedReason: null, files: journalFiles },
-    };
-}
-export function isJournalTerminal(journal) {
-    return (journal.journal.state === "completed" ||
-        journal.journal.state === "blocked");
-}
-export async function writeJournalFile(filePath, journal) {
-    await writeJsonAtomic(filePath, journal);
-}
-export async function readJournalFile(filePath) {
-    try {
-        const raw = JSON.parse(await readFile(filePath, "utf8"));
-        const parsed = frontendWriterRollbackV1Schema.safeParse(raw);
-        return parsed.success ? parsed.data : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-async function inspectPath(repoRoot, relPath, deps) {
-    const abs = path.join(repoRoot, relPath);
-    try {
-        const st = await deps.lstat(abs);
-        const mode = (st.mode & 0o777777).toString(8);
-        if (st.isSymbolicLink()) {
-            const target = await deps
-                .realpath(abs)
-                .catch(async () => deps.readlink(abs));
-            return {
-                kind: "symlink",
-                hash: sha256HexBytes(`symlink:${relPath}->${target}`),
-                mode,
-            };
-        }
-        if (st.isDirectory()) {
-            return { kind: "dir", hash: sha256HexBytes(`dir:${relPath}`), mode };
-        }
-        const bytes = await deps.readFile(abs);
-        return { kind: "file", hash: sha256HexBytes(bytes), mode };
-    }
-    catch (error) {
-        if (error.code === "ENOENT") {
-            return { kind: "absent" };
-        }
-        throw error;
-    }
-}
-function ensureJournalFile(working, relPath, baselineSha256, attemptSha256) {
-    let file = working.journal.files[relPath];
-    if (!file) {
-        file = {
-            state: "pending",
-            baselineSha256,
-            attemptSha256,
-            restoreSha256: null,
-        };
-        working.journal.files[relPath] = file;
-    }
-    else if (attemptSha256 !== null && file.attemptSha256 === null) {
-        file.attemptSha256 = attemptSha256;
-    }
-    return file;
-}
-function markVerified(working, relPath, baselineSha256, restoreSha256) {
-    const file = ensureJournalFile(working, relPath, baselineSha256, null);
-    file.state = "verified";
-    file.restoreSha256 = restoreSha256;
-}
-function markFailed(working, relPath, baselineSha256) {
-    const file = ensureJournalFile(working, relPath, baselineSha256, null);
-    file.state = "failed";
-}
-function dedupe(values) {
-    return [...new Set(values)].sort((a, b) => a.localeCompare(b));
-}
-function collectVerifiedPaths(working) {
-    return Object.entries(working.journal.files)
-        .filter(([, file]) => file.state === "verified")
-        .map(([relPath]) => relPath)
-        .sort((a, b) => a.localeCompare(b));
-}
-/** Writes baseline bytes (or re-creates the symlink) and returns the after hash. */
-async function restoreBaselineContent(repoRoot, existing, deps) {
-    const abs = path.join(repoRoot, existing.path);
-    await deps.mkdir(path.dirname(abs), { recursive: true });
-    if (existing.state === "symlink" && existing.symlinkTarget !== undefined) {
-        await deps.unlink(abs).catch(() => { });
-        await deps.symlink(existing.symlinkTarget, abs);
-        return sha256HexBytes(`symlink:${existing.path}->${existing.symlinkTarget}`);
-    }
-    const bytes = Buffer.from(existing.baselineContentBase64 ?? "", "base64");
-    await deps.writeFile(abs, bytes);
-    if (existing.mode !== undefined) {
-        await deps.chmod(abs, parseInt(existing.mode, 8));
-    }
-    const reread = await deps.readFile(abs);
-    return sha256HexBytes(reread);
-}
-async function restoreAndVerifyBaseline(input) {
-    const { repoRoot, working, deps, existing } = input;
-    const attemptSha256 = toAttemptSha256(working.attemptFileHashes[existing.path]);
-    ensureJournalFile(working, existing.path, existing.baselineSha256, attemptSha256);
-    working.journal.files[existing.path].state = "restoring";
-    try {
-        const afterHash = await restoreBaselineContent(repoRoot, existing, deps);
-        if (afterHash !== existing.baselineSha256) {
-            working.journal.files[existing.path].state = "failed";
-            return false;
-        }
-        markVerified(working, existing.path, existing.baselineSha256, afterHash);
-        return true;
-    }
-    catch {
-        working.journal.files[existing.path].state = "failed";
-        return false;
-    }
-}
-async function deleteAndVerifyAttemptFile(input) {
-    const { repoRoot, working, deps, relPath } = input;
-    const baselineSha256 = absentBaselineSha256(relPath);
-    const attemptSha256 = toAttemptSha256(working.attemptFileHashes[relPath]);
-    ensureJournalFile(working, relPath, baselineSha256, attemptSha256);
-    working.journal.files[relPath].state = "restoring";
-    try {
-        await deps.unlink(path.join(repoRoot, relPath));
-        const after = await inspectPath(repoRoot, relPath, deps);
-        if (after.kind !== "absent") {
-            working.journal.files[relPath].state = "failed";
-            return false;
-        }
-        markVerified(working, relPath, baselineSha256, null);
-        return true;
-    }
-    catch {
-        working.journal.files[relPath].state = "failed";
-        return false;
-    }
-}
-async function restoreRenamedPath(input) {
-    const { repoRoot, working, deps, oldPath, existing, renameTarget, targetHash } = input;
-    if (targetHash === undefined || targetHash === "absent") {
-        return {
-            ok: false,
-            blockedReason: `rename target ${renameTarget} has no recorded attempt hash`,
-        };
-    }
-    const newCurrent = await inspectPath(repoRoot, renameTarget, deps);
-    if (newCurrent.kind !== "absent" && newCurrent.hash !== targetHash) {
-        return {
-            ok: false,
-            blockedReason: `auto-recovery-blocked: rename target ${renameTarget} changed externally`,
-        };
-    }
-    const oldCurrent = await inspectPath(repoRoot, oldPath, deps);
-    if (oldCurrent.kind !== "absent") {
-        return {
-            ok: false,
-            blockedReason: `cannot restore renamed baseline ${oldPath}: path is occupied`,
-        };
-    }
-    const newBaseline = absentBaselineSha256(renameTarget);
-    ensureJournalFile(working, renameTarget, newBaseline, toAttemptSha256(targetHash));
-    working.journal.files[renameTarget].state = "restoring";
-    try {
-        if (newCurrent.kind !== "absent") {
-            await deps.unlink(path.join(repoRoot, renameTarget));
-        }
-        markVerified(working, renameTarget, newBaseline, null);
-    }
-    catch {
-        working.journal.files[renameTarget].state = "failed";
-        return { ok: false, blockedReason: `failed to delete rename target ${renameTarget}` };
-    }
-    const restored = await restoreAndVerifyBaseline({
-        repoRoot,
-        working,
-        deps,
-        existing,
-    });
-    if (!restored) {
-        return {
-            ok: false,
-            blockedReason: `failed to restore renamed baseline ${oldPath}`,
-        };
-    }
-    return { ok: true, restoredPaths: [oldPath, renameTarget] };
-}
-function finishBlocked(working, blockedReason, restoredPaths) {
-    working.journal.state = "blocked";
-    working.journal.blockedReason = blockedReason;
-    return {
-        state: "blocked",
-        blockedReason,
-        restoredPaths: dedupe(restoredPaths),
-        journal: working,
-    };
-}
-/**
- * AC-3/AC-4: CAS restore matrix driven by `attemptChangedPaths` +
- * `attemptFileHashes`. Fail-closed: any path whose current hash is neither the
- * baseline nor the recorded attempt hash blocks the whole journal without
- * overwriting/deleting that file. `git reset --hard` is never used.
- */
-export async function restoreJournal(snapshot, options) {
-    const deps = resolveDeps(options.dependencies);
-    const repoRoot = options.repoRoot;
-    const working = structuredClone(snapshot);
-    const existingByPath = new Map(working.existingFiles.map((file) => [file.path, file]));
-    // Fail-closed: every attempt-changed path must stay inside the writeSet.
-    for (const changedPath of working.attemptChangedPaths) {
-        if (!working.writeSet.some((pattern) => pathMatchesPattern(changedPath, pattern))) {
-            return finishBlocked(working, `auto-recovery-blocked: attempt changed path outside writeSet: ${changedPath}`, []);
-        }
-    }
-    if (working.journal.state === "completed" || working.journal.state === "blocked") {
-        return {
-            state: working.journal.state,
-            blockedReason: working.journal.blockedReason,
-            restoredPaths: collectVerifiedPaths(working),
-            journal: working,
-        };
-    }
-    working.journal.state = "restoring";
-    // Paths requiring recovery action: attempt-changed paths plus baselines the
-    // attempt deleted or renamed.
-    const actionPaths = new Set(working.attemptChangedPaths);
-    for (const file of working.existingFiles) {
-        if (file.state === "deleted" || file.state === "renamed") {
-            actionPaths.add(file.path);
-            if (file.renameTarget)
-                actionPaths.add(file.renameTarget);
-        }
-    }
-    const restoredPaths = [];
-    const handled = new Set();
-    for (const relPath of [...actionPaths].sort((a, b) => a.localeCompare(b))) {
-        if (handled.has(relPath))
-            continue;
-        const priorFile = working.journal.files[relPath];
-        if (priorFile?.state === "verified") {
-            handled.add(relPath);
-            restoredPaths.push(relPath);
-            continue;
-        }
-        const existing = existingByPath.get(relPath);
-        const attemptHash = working.attemptFileHashes[relPath];
-        if (existing?.state === "renamed") {
-            const renameTarget = existing.renameTarget;
-            if (!renameTarget) {
-                return finishBlocked(working, `renamed baseline ${relPath} has no renameTarget`, restoredPaths);
-            }
-            const renameResult = await restoreRenamedPath({
-                repoRoot,
-                working,
-                deps,
-                oldPath: relPath,
-                existing,
-                renameTarget,
-                targetHash: working.attemptFileHashes[renameTarget],
-            });
-            handled.add(relPath);
-            handled.add(renameTarget);
-            if (!renameResult.ok) {
-                return finishBlocked(working, renameResult.blockedReason, restoredPaths);
-            }
-            restoredPaths.push(...renameResult.restoredPaths);
-            continue;
-        }
-        if (attemptHash === undefined) {
-            return finishBlocked(working, `attempt changed path ${relPath} has no recorded attempt hash`, restoredPaths);
-        }
-        const current = await inspectPath(repoRoot, relPath, deps);
-        if (existing) {
-            if (attemptHash === "absent") {
-                // Attempt deleted the baseline → restore it (CAS: path must be absent).
-                if (current.kind !== "absent") {
-                    return finishBlocked(working, `cannot restore deleted baseline ${relPath}: path exists`, restoredPaths);
-                }
-                const ok = await restoreAndVerifyBaseline({
-                    repoRoot,
-                    working,
-                    deps,
-                    existing,
-                });
-                if (!ok) {
-                    return finishBlocked(working, `failed to restore baseline content for ${relPath}`, restoredPaths);
-                }
-                handled.add(relPath);
-                restoredPaths.push(relPath);
-                continue;
-            }
-            // Attempt modified the baseline → restore only when current == attempt.
-            if (current.kind !== "absent" && current.hash === existing.baselineSha256) {
-                markVerified(working, relPath, existing.baselineSha256, existing.baselineSha256);
-                handled.add(relPath);
-                restoredPaths.push(relPath);
-                continue;
-            }
-            if (current.kind === "absent" || current.hash !== attemptHash) {
-                return finishBlocked(working, `auto-recovery-blocked: ${relPath} changed externally`, restoredPaths);
-            }
-            const ok = await restoreAndVerifyBaseline({
-                repoRoot,
-                working,
-                deps,
-                existing,
-            });
-            if (!ok) {
-                return finishBlocked(working, `failed to restore baseline content for ${relPath}`, restoredPaths);
-            }
-            handled.add(relPath);
-            restoredPaths.push(relPath);
-            continue;
-        }
-        // Baseline absent → attempt-created file → delete only when current == attempt.
-        if (attemptHash === "absent") {
-            return finishBlocked(working, `inconsistent attempt state for new path ${relPath}`, restoredPaths);
-        }
-        if (current.kind === "absent") {
-            markVerified(working, relPath, absentBaselineSha256(relPath), null);
-            handled.add(relPath);
-            restoredPaths.push(relPath);
-            continue;
-        }
-        if (current.hash !== attemptHash) {
-            return finishBlocked(working, `auto-recovery-blocked: new file ${relPath} changed externally`, restoredPaths);
-        }
-        const ok = await deleteAndVerifyAttemptFile({
-            repoRoot,
-            working,
-            deps,
-            relPath,
-        });
-        if (!ok) {
-            return finishBlocked(working, `failed to delete attempt-created file ${relPath}`, restoredPaths);
-        }
-        handled.add(relPath);
-        restoredPaths.push(relPath);
-    }
-    // Completion phase: every journal path must be verified (AC-4). Unchanged
-    // baselines are hash-verified to still equal the baseline (fail-closed).
-    for (const [relPath, jf] of Object.entries(working.journal.files)) {
-        if (jf.state === "verified")
-            continue;
-        if (jf.state === "failed") {
-            return finishBlocked(working, `path ${relPath} failed during restore`, restoredPaths);
-        }
-        const existing = existingByPath.get(relPath);
-        if (existing &&
-            existing.state !== "deleted" &&
-            existing.state !== "renamed") {
-            const current = await inspectPath(repoRoot, relPath, deps);
-            if (current.kind !== "absent" && current.hash === existing.baselineSha256) {
-                markVerified(working, relPath, existing.baselineSha256, existing.baselineSha256);
-                continue;
-            }
-            return finishBlocked(working, `auto-recovery-blocked: baseline path ${relPath} changed unexpectedly`, restoredPaths);
-        }
-        return finishBlocked(working, `unresolved journal path ${relPath}`, restoredPaths);
-    }
-    working.journal.state = "completed";
-    working.journal.blockedReason = null;
-    return {
-        state: "completed",
-        blockedReason: null,
-        restoredPaths: dedupe(restoredPaths),
-        journal: working,
-    };
-}
-/**
- * AC-5: crash-recovery decision pass over a journal stuck in `restoring`. It
- * never writes/overwrites a file; it only classifies each path by hash:
- * current == baseline → verified; current == recorded attempt hash (or the
- * recorded absent state) → continuable; anything else → blocked (unprovable
- * boundary, never overwritten).
- */
-export async function recoverRestoringJournal(snapshot, options) {
-    const deps = resolveDeps(options.dependencies);
-    const working = structuredClone(snapshot);
-    const verifiedPaths = [];
-    const continuablePaths = [];
-    for (const [relPath, file] of Object.entries(working.journal.files).sort(([a], [b]) => a.localeCompare(b))) {
-        if (file.state === "verified") {
-            verifiedPaths.push(relPath);
-            continue;
-        }
-        if (file.state === "failed") {
-            return {
-                state: "blocked",
-                blockedReason: `path ${relPath} previously failed`,
-                verifiedPaths,
-                continuablePaths,
-                journal: working,
-            };
-        }
-        if (file.state !== "restoring") {
-            continuablePaths.push(relPath);
-            continue;
-        }
-        const current = await inspectPath(options.repoRoot, relPath, deps);
-        if (current.kind !== "absent" && current.hash === file.baselineSha256) {
-            file.state = "verified";
-            file.restoreSha256 = file.baselineSha256;
-            verifiedPaths.push(relPath);
-            continue;
-        }
-        const attemptHash = working.attemptFileHashes[relPath];
-        if (attemptHash !== undefined &&
-            attemptHash !== "absent" &&
-            current.kind !== "absent" &&
-            current.hash === attemptHash) {
-            file.state = "pending";
-            continuablePaths.push(relPath);
-            continue;
-        }
-        if (attemptHash === "absent" && current.kind === "absent") {
-            file.state = "pending";
-            continuablePaths.push(relPath);
-            continue;
-        }
-        return {
-            state: "blocked",
-            blockedReason: `cannot prove restore boundary for ${relPath}`,
-            verifiedPaths,
-            continuablePaths,
-            journal: working,
-        };
-    }
-    return {
-        state: "recovered",
-        blockedReason: null,
-        verifiedPaths,
-        continuablePaths,
-        journal: working,
-    };
-}
-/**
- * AC-5: scans a journal directory for every non-terminal journal. Terminal
- * journals are never replayed. `pending` journals are restored; `restoring`
- * journals go through the read-only crash-recovery decision pass.
- */
-export async function recoverPendingJournals(journalRoot, options) {
-    const deps = resolveDeps(options.dependencies);
-    const outcomes = [];
-    let entries;
-    try {
-        entries = await deps.readdir(journalRoot, { withFileTypes: true });
-    }
-    catch (error) {
-        if (error.code === "ENOENT")
-            return outcomes;
-        throw error;
-    }
-    for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
-        if (!entry.isFile() || !entry.name.endsWith(".json"))
-            continue;
-        const journalPath = path.join(journalRoot, entry.name);
-        const snapshot = await readJournalFile(journalPath);
-        if (!snapshot) {
-            outcomes.push({
-                journalPath,
-                disposition: "blocked",
-                blockedReason: "journal unreadable or invalid",
-                result: null,
-            });
-            continue;
-        }
-        if (isJournalTerminal(snapshot)) {
-            outcomes.push({
-                journalPath,
-                disposition: "skipped-terminal",
-                blockedReason: null,
-                result: null,
-            });
-            continue;
-        }
-        if (snapshot.journal.state === "pending") {
-            const result = await restoreJournal(snapshot, options);
-            outcomes.push({
-                journalPath,
-                disposition: result.state === "completed" ? "restored" : "blocked",
-                blockedReason: result.blockedReason,
-                result,
-            });
-            continue;
-        }
-        const result = await recoverRestoringJournal(snapshot, options);
-        outcomes.push({
-            journalPath,
-            disposition: result.state === "recovered" ? "recovered" : "blocked",
-            blockedReason: result.blockedReason,
-            result,
-        });
-    }
-    return outcomes;
-}