ai-foreman 1.7.12 → 1.7.13

package/dist/qaSnapshot.d.ts

@@ -1,3 +1,22 @@
+export interface QaUntrackedCapture {
+    path: string;
+    kind: "file" | "symlink";
+    mode: number;
+    digest: string;
+    bytes: Buffer;
+}
+/** Immutable host-observable product state from which QA is constructed. */
+export interface FrozenQaSourceState {
+    head: string;
+    status: Buffer;
+    combinedDiff: Buffer;
+    stagedDiff: Buffer;
+    unstagedDiff: Buffer;
+    changeSummary: string;
+    untracked: QaUntrackedCapture[];
+    digest: string;
+    capturedAt: string;
+}
 export interface QaChangeManifest {
     diffDigest: string;
     untracked: Array<{
@@ -10,6 +29,7 @@ export interface QaChangeManifest {
 export interface DisposableQaSnapshot {
     path: string;
     manifest: QaChangeManifest;
+    frozenState: FrozenQaSourceState;
     verify(): void;
     qaChanges(): string[];
     remove(): void;
@@ -17,17 +37,23 @@ export interface DisposableQaSnapshot {
 export interface AsyncDisposableQaSnapshot {
     path: string;
     manifest: QaChangeManifest;
+    frozenState: FrozenQaSourceState;
     verify(): Promise<void>;
     qaChanges(): Promise<string[]>;
     remove(): Promise<void>;
 }
 export type QaSnapshotProgress = (state: string, detail?: string) => void;
-/** Reproduce the Builder's exact change set in a detached disposable worktree. */
+export declare class QaSourceInstabilityError extends Error {
+    readonly attempts: number;
+    constructor(attempts: number);
+}
+/** Capture twice and accept only a byte-identical source state. */
+export declare function captureFrozenQaSource(worktree: string): FrozenQaSourceState;
+export declare function captureFrozenQaSourceAsync(worktree: string, progress?: QaSnapshotProgress): Promise<FrozenQaSourceState>;
 export declare function createDisposableQaSnapshot(builderWorktree: string): DisposableQaSnapshot;
-/**
- * Async form used by the live CLI. Git and filesystem work yields to the event
- * loop so the activity reporter can keep animating during large snapshots.
- */
 export declare function createDisposableQaSnapshotAsync(builderWorktree: string, progress?: QaSnapshotProgress): Promise<AsyncDisposableQaSnapshot>;
+export declare function frozenQaStateManifest(state: FrozenQaSourceState): QaChangeManifest;
 export declare function changeManifest(worktree: string): QaChangeManifest;
 export declare function changeManifestAsync(worktree: string, progress?: QaSnapshotProgress, state?: string): Promise<QaChangeManifest>;
+export declare function deterministicChangeSummaryAsync(worktree: string): Promise<string>;
+export declare function calculateFrozenQaStateDigest(state: Omit<FrozenQaSourceState, "digest" | "capturedAt">): string;

package/dist/qaSnapshot.js

@@ -1,99 +1,80 @@
 import { createHash } from "node:crypto";
-import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
-import { cp, lstat, mkdir, mkdtemp, readFile, readlink, rm, symlink } from "node:fs/promises";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
+import { lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { lstat, mkdir, mkdtemp, readFile, readlink, rm, symlink, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { execFileSync, spawn, spawnSync } from "node:child_process";
-/** Reproduce the Builder's exact change set in a detached disposable worktree. */
+const PRODUCT_PATHSPEC = ["--", ".", ":(exclude).foreman/**", ":(exclude).rafi/cache/**"];
+const MAX_CAPTURE_ATTEMPTS = 3; // initial attempt plus two bounded retries
+export class QaSourceInstabilityError extends Error {
+    attempts;
+    constructor(attempts) {
+        super(`Builder source changed during frozen QA capture after ${attempts} attempts`);
+        this.attempts = attempts;
+        this.name = "QaSourceInstabilityError";
+    }
+}
+/** Capture twice and accept only a byte-identical source state. */
+export function captureFrozenQaSource(worktree) {
+    const cwd = resolve(worktree);
+    for (let attempt = 1; attempt <= MAX_CAPTURE_ATTEMPTS; attempt++) {
+        const first = captureOnce(cwd);
+        const second = captureOnce(cwd);
+        if (first.digest === second.digest)
+            return { ...first, capturedAt: new Date().toISOString() };
+    }
+    throw new QaSourceInstabilityError(MAX_CAPTURE_ATTEMPTS);
+}
+export async function captureFrozenQaSourceAsync(worktree, progress = () => { }) {
+    const cwd = resolve(worktree);
+    for (let attempt = 1; attempt <= MAX_CAPTURE_ATTEMPTS; attempt++) {
+        progress("freezing Builder source state", `integrity pass ${attempt}/3`);
+        const first = await captureOnceAsync(cwd, progress);
+        const second = await captureOnceAsync(cwd, progress);
+        if (first.digest === second.digest)
+            return { ...first, capturedAt: new Date().toISOString() };
+    }
+    throw new QaSourceInstabilityError(MAX_CAPTURE_ATTEMPTS);
+}
 export function createDisposableQaSnapshot(builderWorktree) {
     const source = resolve(builderWorktree);
-    const root = execFileSync("git", ["-C", source, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+    const root = gitText(source, ["rev-parse", "--show-toplevel"]);
+    const frozenState = captureFrozenQaSource(source);
     const tempRoot = mkdtempSync(join(tmpdir(), "rafi-qa-"));
     const review = join(tempRoot, "review");
-    const head = execFileSync("git", ["-C", source, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
-    const added = spawnSync("git", ["-C", root, "worktree", "add", "--detach", review, head], { encoding: "utf8" });
-    if (added.status !== 0) {
-        rmSync(tempRoot, { recursive: true, force: true });
-        throw new Error(`cannot create disposable QA worktree: ${added.stderr.trim()}`);
-    }
+    addWorktreeSync(root, review, frozenState.head);
     try {
-        const diff = execFileSync("git", ["-C", source, "diff", "--binary", "HEAD"], { encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
-        if (diff.length) {
-            const applied = spawnSync("git", ["-C", review, "apply", "--index", "--binary", "--whitespace=nowarn", "-"], { input: diff, encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
-            if (applied.status !== 0)
-                throw new Error(`cannot apply Builder diff to QA worktree: ${Buffer.from(applied.stderr).toString().trim()}`);
-        }
-        for (const path of untrackedPaths(source))
-            copyUntracked(source, review, path);
-        const manifest = changeManifest(source);
+        applyFrozenSync(review, frozenState);
+        const manifest = manifestFromFrozen(frozenState);
         const snapshot = {
-            path: review, manifest,
-            verify: () => {
-                const actual = changeManifest(review);
-                if (JSON.stringify(actual) !== JSON.stringify(manifest))
-                    throw new Error(`disposable QA snapshot does not match Builder change manifest: expected ${JSON.stringify(manifest)}, got ${JSON.stringify(actual)}`);
-            },
+            path: review, manifest, frozenState,
+            verify: () => assertSnapshotMatches(review, manifest),
             qaChanges: () => manifestDifference(manifest, changeManifest(review)),
-            remove: () => {
-                spawnSync("git", ["-C", root, "worktree", "remove", "--force", review], { encoding: "utf8" });
-                rmSync(tempRoot, { recursive: true, force: true });
-            },
+            remove: () => removeWorktreeSync(root, review, tempRoot),
         };
         snapshot.verify();
         return snapshot;
     }
     catch (error) {
-        spawnSync("git", ["-C", root, "worktree", "remove", "--force", review], { encoding: "utf8" });
-        rmSync(tempRoot, { recursive: true, force: true });
+        removeWorktreeSync(root, review, tempRoot);
         throw error;
     }
 }
-/**
- * Async form used by the live CLI. Git and filesystem work yields to the event
- * loop so the activity reporter can keep animating during large snapshots.
- */
 export async function createDisposableQaSnapshotAsync(builderWorktree, progress = () => { }) {
     const source = resolve(builderWorktree);
     progress("preparing disposable QA snapshot", "locating Builder worktree");
     const root = (await runGit(source, ["rev-parse", "--show-toplevel"])).toString().trim();
+    const frozenState = await captureFrozenQaSourceAsync(source, progress);
     const tempRoot = await mkdtemp(join(tmpdir(), "rafi-qa-"));
     const review = join(tempRoot, "review");
-    const head = (await runGit(source, ["rev-parse", "HEAD"])).toString().trim();
-    progress("preparing disposable QA snapshot", "creating detached review worktree");
-    try {
-        await runGit(root, ["worktree", "add", "--detach", review, head]);
-    }
-    catch (error) {
-        await rm(tempRoot, { recursive: true, force: true });
-        throw new Error(`cannot create disposable QA worktree: ${errorMessage(error)}`);
-    }
     try {
-        progress("preparing disposable QA snapshot", "copying tracked Builder changes");
-        const diff = await runGit(source, ["diff", "--binary", "HEAD"]);
-        if (diff.length) {
-            try {
-                await runGit(review, ["apply", "--index", "--binary", "--whitespace=nowarn", "-"], diff);
-            }
-            catch (error) {
-                throw new Error(`cannot apply Builder diff to QA worktree: ${errorMessage(error)}`);
-            }
-        }
-        const paths = await untrackedPathsAsync(source);
-        for (let index = 0; index < paths.length; index++) {
-            progress("preparing disposable QA snapshot", `copying untracked files ${index + 1}/${paths.length}`);
-            await copyUntrackedAsync(source, review, paths[index]);
-        }
-        progress("preparing disposable QA snapshot", "recording Builder change manifest");
-        const manifest = await changeManifestAsync(source, progress, "preparing disposable QA snapshot");
+        progress("preparing disposable QA snapshot", "creating detached review worktree");
+        await runGit(root, ["worktree", "add", "--detach", review, frozenState.head]);
+        await applyFrozenAsync(review, frozenState, progress);
+        const manifest = manifestFromFrozen(frozenState);
         const snapshot = {
-            path: review,
-            manifest,
-            verify: async () => {
-                const actual = await changeManifestAsync(review, progress, "preparing disposable QA snapshot");
-                if (JSON.stringify(actual) !== JSON.stringify(manifest)) {
-                    throw new Error(`disposable QA snapshot does not match Builder change manifest: expected ${JSON.stringify(manifest)}, got ${JSON.stringify(actual)}`);
-                }
-            },
+            path: review, manifest, frozenState,
+            verify: async () => assertSnapshotMatchesAsync(review, manifest, progress),
             qaChanges: async () => manifestDifference(manifest, await changeManifestAsync(review, progress)),
             remove: async () => {
                 progress("cleaning up disposable QA snapshot", "removing detached review worktree");
@@ -101,7 +82,7 @@ export async function createDisposableQaSnapshotAsync(builderWorktree, progress
                 await rm(tempRoot, { recursive: true, force: true });
             },
         };
-        progress("preparing disposable QA snapshot", "verifying review copy");
+        progress("preparing disposable QA snapshot", "verifying frozen review copy");
         await snapshot.verify();
         return snapshot;
     }
@@ -111,85 +92,156 @@ export async function createDisposableQaSnapshotAsync(builderWorktree, progress
         throw error;
     }
 }
+export function frozenQaStateManifest(state) { return manifestFromFrozen(state); }
 export function changeManifest(worktree) {
-    const diff = execFileSync("git", ["-C", worktree, "diff", "--binary", "HEAD"], { encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
-    const untracked = untrackedPaths(worktree).map((path) => {
-        const absolute = join(worktree, path);
-        const stat = lstatSync(absolute);
-        const kind = stat.isSymbolicLink() ? "symlink" : "file";
-        const bytes = kind === "symlink" ? Buffer.from(readlinkSync(absolute)) : readFileSync(absolute);
-        return { path, kind, mode: stat.mode & 0o7777, digest: createHash("sha256").update(bytes).digest("hex") };
-    });
-    return { diffDigest: createHash("sha256").update(diff).digest("hex"), untracked };
+    const diff = gitBuffer(resolve(worktree), ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
+    return { diffDigest: hash(diff), untracked: untrackedPaths(worktree).map((path) => describeUntrackedSync(worktree, path)) };
 }
 export async function changeManifestAsync(worktree, progress = () => { }, state = "checking QA file changes") {
-    const diff = await runGit(worktree, ["diff", "--binary", "HEAD"]);
+    const diff = await runGit(worktree, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
     const paths = await untrackedPathsAsync(worktree);
     const untracked = [];
     for (let index = 0; index < paths.length; index++) {
-        const path = paths[index];
         progress(state, `hashing untracked files ${index + 1}/${paths.length}`);
-        const absolute = join(worktree, path);
+        const absolute = join(worktree, paths[index]);
         const stat = await lstat(absolute);
         const kind = stat.isSymbolicLink() ? "symlink" : "file";
         const bytes = kind === "symlink" ? Buffer.from(await readlink(absolute)) : await readFile(absolute);
-        untracked.push({ path, kind, mode: stat.mode & 0o7777, digest: createHash("sha256").update(bytes).digest("hex") });
+        untracked.push({ path: paths[index], kind, mode: stat.mode & 0o7777, digest: hash(bytes) });
     }
-    return { diffDigest: createHash("sha256").update(diff).digest("hex"), untracked };
-}
-function untrackedPaths(worktree) {
-    const raw = execFileSync("git", ["-C", worktree, "ls-files", "--others", "--exclude-standard", "-z"], { encoding: "buffer" });
-    return raw.toString().split("\0").filter(Boolean).sort();
-}
-async function untrackedPathsAsync(worktree) {
-    const raw = await runGit(worktree, ["ls-files", "--others", "--exclude-standard", "-z"]);
-    return raw.toString().split("\0").filter(Boolean).sort();
-}
-function copyUntracked(source, target, path) {
-    const from = join(source, path);
-    const to = join(target, path);
-    mkdirSync(dirname(to), { recursive: true });
-    const stat = lstatSync(from);
-    if (stat.isSymbolicLink()) {
-        if (existsSync(to))
-            rmSync(to, { force: true });
-        symlinkSync(readlinkSync(from), to);
+    return { diffDigest: hash(diff), untracked };
+}
+export async function deterministicChangeSummaryAsync(worktree) {
+    const [staged, unstaged, untracked] = await Promise.all([
+        runGit(worktree, ["diff", "--cached", "--name-status", "-z", ...PRODUCT_PATHSPEC]),
+        runGit(worktree, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]),
+        runGit(worktree, ["ls-files", "--others", "--exclude-standard", "-z"]),
+    ]);
+    return renderSummary(staged, unstaged, untracked);
+}
+function captureOnce(cwd) {
+    const head = gitText(cwd, ["rev-parse", "HEAD"]);
+    const status = gitBuffer(cwd, ["status", "--porcelain=v2", "-z", "--untracked-files=all", ...PRODUCT_PATHSPEC]);
+    const combinedDiff = gitBuffer(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]);
+    const stagedDiff = gitBuffer(cwd, ["diff", "--cached", "--binary", ...PRODUCT_PATHSPEC]);
+    const unstagedDiff = gitBuffer(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]);
+    const stagedNames = gitBuffer(cwd, ["diff", "--cached", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
+    const unstagedNames = gitBuffer(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]);
+    const untrackedNames = gitBuffer(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]);
+    const untracked = untrackedPathsFrom(untrackedNames).map((path) => captureUntrackedSync(cwd, path));
+    const base = { head, status, combinedDiff, stagedDiff, unstagedDiff, changeSummary: renderSummary(stagedNames, unstagedNames, untrackedNames), untracked };
+    return { ...base, digest: calculateFrozenQaStateDigest(base), capturedAt: "" };
+}
+async function captureOnceAsync(cwd, progress) {
+    const [headBytes, status, combinedDiff, stagedDiff, unstagedDiff, stagedNames, unstagedNames, untrackedNames] = await Promise.all([
+        runGit(cwd, ["rev-parse", "HEAD"]), runGit(cwd, ["status", "--porcelain=v2", "-z", "--untracked-files=all", ...PRODUCT_PATHSPEC]),
+        runGit(cwd, ["diff", "--binary", "HEAD", ...PRODUCT_PATHSPEC]), runGit(cwd, ["diff", "--cached", "--binary", ...PRODUCT_PATHSPEC]),
+        runGit(cwd, ["diff", "--binary", ...PRODUCT_PATHSPEC]), runGit(cwd, ["diff", "--cached", "--name-status", "-z", ...PRODUCT_PATHSPEC]),
+        runGit(cwd, ["diff", "--name-status", "-z", ...PRODUCT_PATHSPEC]), runGit(cwd, ["ls-files", "--others", "--exclude-standard", "-z"]),
+    ]);
+    const paths = untrackedPathsFrom(untrackedNames);
+    const untracked = [];
+    for (let index = 0; index < paths.length; index++) {
+        progress("freezing Builder source state", `reading untracked file ${index + 1}/${paths.length}`);
+        untracked.push(await captureUntrackedAsync(cwd, paths[index]));
     }
-    else
-        cpSync(from, to, { preserveTimestamps: true });
-}
-async function copyUntrackedAsync(source, target, path) {
-    const from = join(source, path);
-    const to = join(target, path);
-    await mkdir(dirname(to), { recursive: true });
-    const stat = await lstat(from);
-    if (stat.isSymbolicLink()) {
-        await rm(to, { force: true });
-        await symlink(await readlink(from), to);
+    const base = { head: headBytes.toString().trim(), status, combinedDiff, stagedDiff, unstagedDiff, changeSummary: renderSummary(stagedNames, unstagedNames, untrackedNames), untracked };
+    return { ...base, digest: calculateFrozenQaStateDigest(base), capturedAt: "" };
+}
+export function calculateFrozenQaStateDigest(state) {
+    const h = createHash("sha256");
+    for (const [label, value] of [["head", Buffer.from(state.head)], ["status", state.status], ["combined", state.combinedDiff], ["staged", state.stagedDiff], ["unstaged", state.unstagedDiff], ["summary", Buffer.from(state.changeSummary)]]) {
+        h.update(label).update("\0").update(value).update("\0");
     }
-    else {
-        await cp(from, to, { preserveTimestamps: true });
+    for (const item of state.untracked)
+        h.update(item.path).update("\0").update(item.kind).update("\0").update(String(item.mode)).update("\0").update(item.bytes).update("\0");
+    return h.digest("hex");
+}
+function manifestFromFrozen(state) {
+    return { diffDigest: hash(state.combinedDiff), untracked: state.untracked.map(({ path, kind, mode, digest }) => ({ path, kind, mode, digest })) };
+}
+function applyFrozenSync(review, state) {
+    applyPatchSync(review, state.stagedDiff, true);
+    applyPatchSync(review, state.unstagedDiff, false);
+    for (const item of state.untracked)
+        writeCapturedUntrackedSync(review, item);
+}
+async function applyFrozenAsync(review, state, progress) {
+    progress("preparing disposable QA snapshot", "applying captured staged changes");
+    await applyPatchAsync(review, state.stagedDiff, true);
+    progress("preparing disposable QA snapshot", "applying captured unstaged changes");
+    await applyPatchAsync(review, state.unstagedDiff, false);
+    for (let index = 0; index < state.untracked.length; index++) {
+        progress("preparing disposable QA snapshot", `materializing captured untracked files ${index + 1}/${state.untracked.length}`);
+        await writeCapturedUntrackedAsync(review, state.untracked[index]);
     }
 }
-function runGit(cwd, args, input) {
-    return new Promise((resolvePromise, reject) => {
-        const child = spawn("git", ["-C", cwd, ...args], { stdio: ["pipe", "pipe", "pipe"] });
-        const stdout = [];
-        const stderr = [];
-        child.stdout.on("data", (chunk) => stdout.push(chunk));
-        child.stderr.on("data", (chunk) => stderr.push(chunk));
-        child.on("error", reject);
-        child.on("close", (code) => {
-            if (code === 0)
-                resolvePromise(Buffer.concat(stdout));
-            else
-                reject(new Error(Buffer.concat(stderr).toString().trim() || `git exited with status ${code ?? "unknown"}`));
-        });
-        child.stdin.end(input);
-    });
+function applyPatchSync(review, patch, index) {
+    if (!patch.length)
+        return;
+    const applied = spawnSync("git", ["-C", review, "apply", ...(index ? ["--index"] : []), "--binary", "--whitespace=nowarn", "-"], { input: patch, encoding: "buffer", maxBuffer: 256 * 1024 * 1024 });
+    if (applied.status !== 0)
+        throw new Error(`cannot apply frozen Builder diff to QA worktree: ${Buffer.from(applied.stderr).toString().trim()}`);
+}
+async function applyPatchAsync(review, patch, index) {
+    if (patch.length)
+        await runGit(review, ["apply", ...(index ? ["--index"] : []), "--binary", "--whitespace=nowarn", "-"], patch);
+}
+function captureUntrackedSync(cwd, path) {
+    const absolute = join(cwd, path);
+    const stat = lstatSync(absolute);
+    if (!stat.isFile() && !stat.isSymbolicLink())
+        throw new Error(`unsupported untracked path type during QA capture: ${path}`);
+    const kind = stat.isSymbolicLink() ? "symlink" : "file";
+    const bytes = kind === "symlink" ? Buffer.from(readlinkSync(absolute)) : readFileSync(absolute);
+    return { path, kind, mode: stat.mode & 0o7777, digest: hash(bytes), bytes };
+}
+async function captureUntrackedAsync(cwd, path) {
+    const absolute = join(cwd, path);
+    const stat = await lstat(absolute);
+    if (!stat.isFile() && !stat.isSymbolicLink())
+        throw new Error(`unsupported untracked path type during QA capture: ${path}`);
+    const kind = stat.isSymbolicLink() ? "symlink" : "file";
+    const bytes = kind === "symlink" ? Buffer.from(await readlink(absolute)) : await readFile(absolute);
+    return { path, kind, mode: stat.mode & 0o7777, digest: hash(bytes), bytes };
+}
+function writeCapturedUntrackedSync(review, item) {
+    const target = join(review, item.path);
+    mkdirSync(dirname(target), { recursive: true });
+    if (item.kind === "symlink")
+        symlinkSync(item.bytes.toString(), target);
+    else
+        writeFileSync(target, item.bytes, { mode: item.mode });
+}
+async function writeCapturedUntrackedAsync(review, item) {
+    const target = join(review, item.path);
+    await mkdir(dirname(target), { recursive: true });
+    if (item.kind === "symlink")
+        await symlink(item.bytes.toString(), target);
+    else
+        await writeFile(target, item.bytes, { mode: item.mode });
+}
+function describeUntrackedSync(worktree, path) {
+    const item = captureUntrackedSync(worktree, path);
+    return { path: item.path, kind: item.kind, mode: item.mode, digest: item.digest };
+}
+function untrackedPaths(worktree) { return untrackedPathsFrom(gitBuffer(resolve(worktree), ["ls-files", "--others", "--exclude-standard", "-z"])); }
+async function untrackedPathsAsync(worktree) { return untrackedPathsFrom(await runGit(worktree, ["ls-files", "--others", "--exclude-standard", "-z"])); }
+function untrackedPathsFrom(raw) { return raw.toString().split("\0").filter((path) => path && isQaProductPath(path)).sort(); }
+function isQaProductPath(path) { return path !== ".foreman" && !path.startsWith(".foreman/") && path !== ".rafi/cache" && !path.startsWith(".rafi/cache/"); }
+function renderSummary(staged, unstaged, untracked) {
+    const normalize = (value) => value.toString().split("\0").filter(Boolean).filter(isQaProductPath).sort().join("\n") || "(none)";
+    return `tracked/staged:\n${normalize(staged)}\ntracked/unstaged:\n${normalize(unstaged)}\nuntracked:\n${normalize(untracked)}`;
 }
-function errorMessage(error) {
-    return error instanceof Error ? error.message : String(error);
+function assertSnapshotMatches(review, expected) {
+    const actual = changeManifest(review);
+    if (JSON.stringify(actual) !== JSON.stringify(expected))
+        throw new Error(`disposable QA snapshot does not match frozen source manifest: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+async function assertSnapshotMatchesAsync(review, expected, progress) {
+    const actual = await changeManifestAsync(review, progress, "verifying frozen QA snapshot");
+    if (JSON.stringify(actual) !== JSON.stringify(expected))
+        throw new Error(`disposable QA snapshot does not match frozen source manifest: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
 }
 function manifestDifference(before, after) {
     const changes = [];
@@ -202,3 +254,26 @@ function manifestDifference(before, after) {
             changes.push(path);
     return changes;
 }
+function addWorktreeSync(root, review, head) {
+    const added = spawnSync("git", ["-C", root, "worktree", "add", "--detach", review, head], { encoding: "utf8" });
+    if (added.status !== 0) {
+        rmSync(dirname(review), { recursive: true, force: true });
+        throw new Error(`cannot create disposable QA worktree: ${added.stderr.trim()}`);
+    }
+}
+function removeWorktreeSync(root, review, tempRoot) { spawnSync("git", ["-C", root, "worktree", "remove", "--force", review], { encoding: "utf8" }); rmSync(tempRoot, { recursive: true, force: true }); }
+function gitText(cwd, args) { return gitBuffer(cwd, args).toString().trim(); }
+function gitBuffer(cwd, args) { return execFileSync("git", ["-C", cwd, ...args], { encoding: "buffer", maxBuffer: 256 * 1024 * 1024 }); }
+function runGit(cwd, args, input) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn("git", ["-C", cwd, ...args], { stdio: ["pipe", "pipe", "pipe"] });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", reject);
+        child.on("close", (code) => code === 0 ? resolvePromise(Buffer.concat(stdout)) : reject(new Error(Buffer.concat(stderr).toString().trim() || `git exited with status ${code ?? "unknown"}`)));
+        child.stdin.end(input);
+    });
+}
+function hash(bytes) { return createHash("sha256").update(bytes).digest("hex"); }

package/dist/recoveryPolicy.d.ts

@@ -0,0 +1,37 @@
+import type { AutonomyConfig, AutonomyProfile, InterruptionDomain, PendingHumanDecision, RecoveryDisposition, ResolvedAutonomyPolicy, StructuredInterruption, WorkflowIssueCode } from "rafi-spec";
+import { WorkflowDb } from "./workflowDb.js";
+export declare const DEFAULT_AUTONOMY_CONFIG: AutonomyConfig;
+export declare function loadProjectAutonomyConfig(projectDir: string): AutonomyConfig | undefined;
+/** QA precedence: CLI -> frozen run -> canonical project config -> legacy foreman.yaml. */
+export declare function resolveQaEnablement(input: {
+    cli?: boolean;
+    frozen?: boolean;
+    projectDir: string;
+    legacyForeman?: boolean;
+}): {
+    enabled: boolean;
+    source: "cli" | "frozen" | "project" | "legacy-foreman" | "default";
+    deprecationWarning?: string;
+};
+export declare function validateAutonomyConfig(value: unknown): AutonomyConfig;
+export declare function resolveAutonomyPolicy(config: Partial<AutonomyConfig> | undefined, profileOverride?: AutonomyProfile, now?: Date): ResolvedAutonomyPolicy;
+export declare function mapWorkflowIssueDomain(code: WorkflowIssueCode): InterruptionDomain;
+export declare function evaluateRecovery(policy: ResolvedAutonomyPolicy, interruption: StructuredInterruption, attemptsUsed: number): RecoveryDisposition;
+export declare function qaDecisionChoices(): PendingHumanDecision["choices"];
+export declare class RecoveryDispatcher {
+    private readonly db;
+    private readonly policy;
+    constructor(db: WorkflowDb, policy: ResolvedAutonomyPolicy);
+    dispatch(input: {
+        interruption: StructuredInterruption;
+        reconcile?: () => Promise<"confirmed" | "absent" | "uncertain">;
+        execute: (disposition: RecoveryDisposition) => Promise<{
+            ok: boolean;
+            detail?: string;
+        }>;
+    }): Promise<{
+        disposition: RecoveryDisposition;
+        decision?: PendingHumanDecision;
+        attemptId?: string;
+    }>;
+}