ai-foreman 1.7.13 → 1.7.14

package/dist/qaRecovery.js

@@ -1,6 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { execFileSync } from "node:child_process";
-import { chmodSync, copyFileSync, cpSync, existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, readdirSync, realpathSync, renameSync, writeFileSync, } from "node:fs";
+import { chmodSync, closeSync, cpSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readlinkSync, readdirSync, realpathSync, renameSync, writeFileSync, } from "node:fs";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { parseQaFailureReport } from "rafi-spec";
 import { calculateFrozenQaStateDigest, captureFrozenQaSource } from "./qaSnapshot.js";
@@ -22,11 +22,13 @@ export function loadQaRecoveryPacket(directory) {
     if (!existsSync(root) || realpathSync(root) !== root)
         throw new Error(`symlink is not allowed in recovery path: ${root}`);
     assertNoSymlinkComponents(root, root);
-    let raw = JSON.parse(readFileSync(join(root, "manifest.json"), "utf8"));
+    const manifestPath = join(root, "manifest.json");
+    if (!existsSync(manifestPath) || lstatSync(manifestPath).isSymbolicLink())
+        throw new Error("missing or unsafe QA recovery manifest");
+    let raw = JSON.parse(readFileSync(manifestPath, "utf8"));
     if (raw.version === 1)
         throw new LegacyQaRecoveryPacketError(root, raw);
-    const publishedRevision = raw.revision;
-    raw = recoverInterruptedPublication(root, raw);
+    assertPrivateTree(root);
     assertManifestShape(raw);
     for (const resource of raw.resources)
         validateResource(root, resource);
@@ -54,32 +56,7 @@ export function loadQaRecoveryPacket(directory) {
         parent = item;
     }
     const projectDir = recoveryProjectRoot(root);
-    const packet = { directory: root, projectDir, manifest: raw };
-    if (raw.revision !== publishedRevision)
-        persistPendingState(packet);
-    return packet;
-}
-function recoverInterruptedPublication(root, initial) {
-    let current = initial;
-    while (existsSync(join(root, "manifests", revisionName(current.revision + 1)))) {
-        const path = join(root, "manifests", revisionName(current.revision + 1));
-        const candidate = JSON.parse(readFileSync(path, "utf8"));
-        assertManifestShape(candidate);
-        if (candidate.packetId !== current.packetId || candidate.revision !== current.revision + 1 || candidate.parentPacketDigest !== current.packetDigest) {
-            throw new Error(`invalid interrupted QA recovery publication at revision ${current.revision + 1}`);
-        }
-        for (const resource of candidate.resources)
-            validateResource(root, resource);
-        validateReviewedStates(root, candidate);
-        if (calculatePacketDigest(root, candidate) !== candidate.packetDigest)
-            throw new Error(`invalid interrupted QA recovery digest at revision ${candidate.revision}`);
-        // All referenced objects and projections are durable. Completing the one
-        // missing atomic pointer replacement is safe and preserves append-only
-        // lineage after a process interruption.
-        atomicWrite(join(root, "manifest.json"), readFileSync(path));
-        current = candidate;
-    }
-    return current;
+    return { directory: root, projectDir, manifest: raw };
 }
 export function inspectLegacyQaRecoveryPacket(directory) {
     const root = resolve(directory);
@@ -130,7 +107,7 @@ export function materializeLegacyQaHistoricalContext(projectDir, legacy) {
 }
 export function compareQaRecoveryReviewedState(packet, source) {
     const current = typeof source === "string" ? captureFrozenQaSource(source) : source;
-    const originalInventory = sourceInventory(packet, "reviewed-state/original");
+    const originalInventory = sourceInventory(packet, currentReviewedStatePrefix(packet));
     const currentInventory = inventoryFromFrozen(current);
     const drift = deterministicDrift(originalInventory, currentInventory);
     return {
@@ -141,18 +118,55 @@ export function compareQaRecoveryReviewedState(packet, source) {
         frozenState: current,
     };
 }
+function currentReviewedStatePrefix(packet) {
+    const matches = packet.manifest.resources.filter((resource) => resource.path.endsWith("/integrity.json") && resource.objectPath).filter((resource) => {
+        try {
+            const declared = JSON.parse(readFileSync(join(packet.directory, resource.objectPath), "utf8"));
+            return declared.digest === packet.manifest.currentReviewedStateDigest;
+        }
+        catch {
+            return false;
+        }
+    });
+    const selected = matches.at(-1);
+    if (!selected)
+        throw new Error("current reviewed-state inventory is missing");
+    return selected.path.slice(0, -"/integrity.json".length);
+}
 /** Create a unique owner-only V2 packet from the immutable state QA reviewed. */
 export function createQaRecoveryPacket(input) {
     ensureQaRecoveryExcluded(input.projectDir);
     const frozen = input.frozenState ?? captureFrozenQaSource(input.reviewedWorktree ?? input.projectDir);
     const reviewAttemptId = input.reviewAttemptId ?? randomUUID();
     const root = containedRecoveryDirectory(input.projectDir, input.runId, input.ticketId, reviewAttemptId);
-    if (existsSync(root))
-        throw new Error(`QA recovery packet directory already exists: ${root}`);
-    mkdirSync(root, { recursive: true, mode: 0o700 });
+    if (existsSync(root)) {
+        assertPrivatePath(root, true);
+        const db = new WorkflowDb(input.projectDir);
+        let durableProjections;
+        try {
+            durableProjections = db.qaPacketProjectionsAtPath(root);
+        }
+        finally {
+            db.close();
+        }
+        if (durableProjections.length > 0) {
+            throw new Error(`QA recovery packet directory has a durable publication record and must be reconciled, not replaced: ${root}`);
+        }
+        const manifests = join(root, "manifests");
+        if (existsSync(join(root, "manifest.json")) || (existsSync(manifests) && readdirSync(manifests).some((name) => name.endsWith(".json")))) {
+            throw new Error(`QA recovery packet directory already exists with published content: ${root}`);
+        }
+        // A crash before publication intent may leave only staged objects. Keep
+        // those bytes for forensics, but move them out of the deterministic retry
+        // path so the same durable review attempt can be packetized safely.
+        const abandoned = `${root}.abandoned-${randomUUID()}`;
+        renameSync(root, abandoned);
+        fsyncDirectory(dirname(root));
+    }
+    durableMkdir(root);
     chmodRecoveryDirectoryChain(input.projectDir, root);
-    mkdirSync(join(root, "objects"), { mode: 0o700 });
-    mkdirSync(join(root, "manifests"), { mode: 0o700 });
+    durableMkdir(join(root, "objects"));
+    durableMkdir(join(root, "manifests"));
     const resources = [];
     for (const [name, resource] of Object.entries(input.resources)) {
         const path = join("context", `${safeSlug(name)}.${resource.exactText ? "txt" : "json"}`).replaceAll("\\", "/");
@@ -185,11 +199,153 @@ export function createQaRecoveryPacket(input) {
     };
     return publish(root, resolve(input.projectDir), draft);
 }
+/**
+ * Finish a packet publication whose immutable files reached disk before the
+ * authoritative SQLite head was advanced. This is deliberately explicit:
+ * ordinary packet loading remains a read-only integrity check.
+ */
+export function reconcileQaRecoveryPacketPublication(packet) {
+    const loaded = loadQaRecoveryPacket(packet.directory);
+    const db = new WorkflowDb(loaded.projectDir);
+    try {
+        const projection = db.qaPacketProjection(loaded.manifest.packetDigest);
+        if (!projection || resolve(projection.path) !== loaded.directory || projection.runId !== loaded.manifest.runId
+            || projection.ticketId !== loaded.manifest.ticketId || projection.packetRevision !== loaded.manifest.revision) {
+            throw new Error("QA recovery packet has no matching durable publication intent");
+        }
+        const head = db.qaRecoveryHead(loaded.manifest.runId, loaded.manifest.ticketId);
+        if (head?.packetDigest === loaded.manifest.packetDigest && head.revision === loaded.manifest.revision) {
+            if (projection.status === "intended")
+                db.finishQaPacketProjection(loaded.manifest.runId, loaded.manifest.ticketId, loaded.manifest.packetDigest);
+            return loaded;
+        }
+        if (projection.status !== "intended")
+            throw new Error("published QA recovery projection disagrees with its durable recovery head");
+        if (head) {
+            if (head.packetId !== loaded.manifest.packetId || loaded.manifest.revision !== head.revision + 1
+                || loaded.manifest.parentPacketDigest !== head.packetDigest) {
+                throw new Error("QA recovery packet cannot be reconciled across a non-contiguous durable head");
+            }
+        }
+        else if (loaded.manifest.revision !== 1 || loaded.manifest.parentPacketDigest !== undefined) {
+            throw new Error("initial QA recovery packet publication is not revision one");
+        }
+    }
+    finally {
+        db.close();
+    }
+    persistPendingState(loaded);
+    const completed = new WorkflowDb(loaded.projectDir);
+    try {
+        completed.finishQaPacketProjection(loaded.manifest.runId, loaded.manifest.ticketId, loaded.manifest.packetDigest);
+    }
+    finally {
+        completed.close();
+    }
+    return loaded;
+}
+/** Recover only packet files named by an existing SQLite publication intent. */
+export function recoverPendingQaRecoveryPublications(projectDir, runId) {
+    const root = realpathSync(resolve(projectDir));
+    const db = new WorkflowDb(root);
+    let pending;
+    try {
+        pending = db.pendingQaPacketProjections(runId);
+    }
+    finally {
+        db.close();
+    }
+    const recovered = [];
+    for (const projection of pending) {
+        const directory = resolve(projection.path);
+        if (!directory.startsWith(`${root}${sep}`))
+            throw new Error("QA packet publication intent escapes the project root");
+        assertPublicationTree(root, directory);
+        const manifestPath = join(directory, "manifest.json");
+        if (!existsSync(manifestPath)) {
+            restoreIntendedRevision(directory, projection);
+            promoteIntendedRevision(directory, projection.packetRevision, projection.packetDigest);
+        }
+        else {
+            const current = loadQaRecoveryPacket(directory);
+            if (current.manifest.packetDigest !== projection.packetDigest) {
+                if (projection.packetRevision !== current.manifest.revision + 1)
+                    throw new Error("pending QA packet revision is not contiguous with its current manifest");
+                restoreIntendedRevision(directory, projection, current.manifest);
+                promoteIntendedRevision(directory, projection.packetRevision, projection.packetDigest, current.manifest);
+            }
+        }
+        recovered.push(reconcileQaRecoveryPacketPublication(loadQaRecoveryPacket(directory)));
+    }
+    // A new review is committed after its frozen source/intent reaches the
+    // packet, and before the packet's review identity advances. Reconcile only
+    // that exact, still-undispatched allocation; never infer a successor merely
+    // because its review number is adjacent.
+    const reviewDb = new WorkflowDb(root);
+    try {
+        for (const pendingHead of reviewDb.pendingQaRecoveryHeads(runId)) {
+            const head = reviewDb.qaTicketHead(runId, pendingHead.ticketId);
+            if (head.state !== "review-ready")
+                continue;
+            const packet = loadQaRecoveryPacket(pendingHead.packetPath);
+            if (head.reviewNumber !== packet.manifest.reviewAttempt + 1 || head.sourceStateDigest !== packet.manifest.reviewedStateDigest)
+                continue;
+            const attempt = reviewDb.qaReviewAttempts(runId, pendingHead.ticketId).find((item) => item.reviewNumber === head.reviewNumber);
+            if (!attempt || attempt.status !== "started" || attempt.sourceDigest !== head.sourceStateDigest)
+                continue;
+            const resource = packet.manifest.resources.find((item) => item.path === `review-transitions/${attempt.attemptId}.json`);
+            if (!resource?.objectPath || resource.integrityPolicy !== "sealed")
+                continue;
+            const intent = JSON.parse(readFileSync(join(packet.directory, resource.objectPath), "utf8"));
+            if (intent.runId !== runId || intent.ticketId !== pendingHead.ticketId
+                || intent.predecessorReviewNumber !== packet.manifest.reviewAttempt || intent.predecessorAttemptId !== packet.manifest.reviewAttemptId
+                || intent.reviewNumber !== head.reviewNumber || intent.reviewAttemptId !== attempt.attemptId
+                || intent.sourceStateDigest !== head.sourceStateDigest || intent.cycle !== attempt.cycle) {
+                throw new Error("QA packet next-review intent does not match its committed successor");
+            }
+            recovered.push(updateQaRecoveryReviewIdentity(packet, head.reviewNumber, attempt.attemptId, attempt.cycle));
+        }
+    }
+    finally {
+        reviewDb.close();
+    }
+    // A pass/waiver is committed in SQLite before the derived packet projection
+    // is marked resolved. Complete that one-way projection after a crash so a
+    // terminal QA decision can never leave a resumable packet behind.
+    const terminalDb = new WorkflowDb(root);
+    let terminalPackets = [];
+    try {
+        terminalPackets = terminalDb.pendingQaRecoveryHeads(runId)
+            .filter((head) => ["passed", "waived", "finalizing", "completed"].includes(terminalDb.qaTicketHead(runId, head.ticketId).state))
+            .map((head) => ({ packetPath: head.packetPath, correctionTurns: head.correctionTurns }));
+    }
+    finally {
+        terminalDb.close();
+    }
+    for (const terminal of terminalPackets) {
+        const resolved = updateQaRecoveryPosition(loadQaRecoveryPacket(terminal.packetPath), "resolved", terminal.correctionTurns, "resolved");
+        recovered.push(resolved);
+    }
+    return recovered;
+}
 export function appendQaRecoveryResource(packet, relativePath, value, options) {
     const requested = safeRelative(relativePath);
-    const path = uniqueResourcePath(packet.manifest.resources, requested);
     const bytes = Buffer.isBuffer(value) ? value : encodeValue(value, Boolean(options.exact));
-    const resource = storeSealed(packet.directory, path, bytes, options.purpose, options.mediaType ?? (options.exact ? "text/plain" : "application/json"), options.requiredForRecovery ?? true);
+    const mediaType = options.mediaType ?? (options.exact ? "text/plain" : "application/json");
+    const requiredForRecovery = options.requiredForRecovery ?? true;
+    const interruptedPath = join(packet.directory, "manifests", revisionName(packet.manifest.revision + 1));
+    if (existsSync(interruptedPath)) {
+        const candidate = readAndValidateRevision(packet.directory, packet.manifest.revision + 1, packet.manifest);
+        const added = candidate.resources.filter((resource) => !packet.manifest.resources.some((prior) => prior.path === resource.path));
+        const resource = added.length === 1 ? added[0] : undefined;
+        if (!resource || resource.path !== requested || resource.digest !== hash(bytes) || resource.bytes !== bytes.length
+            || resource.purpose !== options.purpose || resource.mediaType !== mediaType || resource.requiredForRecovery !== requiredForRecovery) {
+            throw new Error(`QA recovery revision already exists with different content: ${candidate.revision}`);
+        }
+        return recoverInterruptedRevision(packet, { resources: candidate.resources });
+    }
+    const path = uniqueResourcePath(packet.manifest.resources, requested, packet.directory);
+    const resource = storeSealed(packet.directory, path, bytes, options.purpose, mediaType, requiredForRecovery);
     return revise(packet, { resources: [...packet.manifest.resources, resource].sort(resourceOrder) });
 }
 export function appendQaRecoveryReviewedState(packet, source, prefix = "current-state") {
@@ -205,6 +361,33 @@ export function appendQaRecoveryReviewedState(packet, source, prefix = "current-
 export function updateQaRecoveryPosition(packet, stage, correctionTurns, pendingAction = "automatic-recovery") {
     return revise(packet, { recoveryStage: stage, correctionTurns, pendingAction });
 }
+export function updateQaRecoveryReviewIdentity(packet, reviewAttempt, reviewAttemptId, cycle = packet.manifest.cycle) {
+    if (!Number.isSafeInteger(reviewAttempt) || reviewAttempt < 1 || !reviewAttemptId)
+        throw new Error("invalid QA recovery review identity");
+    return revise(packet, { reviewAttempt, attempt: reviewAttempt, reviewAttemptId, cycle });
+}
+/** Keep one unresolved packet and append the next malformed review's exact evidence. */
+export function appendQaRecoveryAttempt(packet, input) {
+    if (packet.manifest.runId !== input.runId || packet.manifest.ticketId !== input.ticketId
+        || packet.manifest.reviewAttempt !== input.reviewAttempt || packet.manifest.reviewAttemptId !== input.reviewAttemptId
+        || !input.frozenState || packet.manifest.reviewedStateDigest !== input.frozenState.digest) {
+        throw new Error("QA recovery attempt does not match the active packet review/source identity");
+    }
+    let next = packet;
+    for (const [name, resource] of Object.entries(input.resources)) {
+        const path = `reviews/r${input.reviewAttempt}/context/${safeSlug(name)}.${resource.exactText ? "txt" : "json"}`;
+        next = appendQaRecoveryResource(next, path, resource.value, {
+            purpose: resource.purpose, mediaType: resource.mediaType, requiredForRecovery: resource.requiredForRecovery,
+            exact: Boolean(resource.exactText),
+        });
+    }
+    if (input.reportJson !== undefined) {
+        const report = writeEditableReport(packet.directory, Buffer.from(input.reportJson));
+        next = revise(next, { resources: [...next.manifest.resources.filter((resource) => resource.path !== "report.json"), report].sort(resourceOrder) });
+    }
+    return revise(next, { cycle: input.cycle, recoveryStage: input.recoveryStage,
+        correctionTurns: input.correctionTurns ?? 0, pendingAction: input.pendingAction ?? "automatic-recovery" });
+}
 export function readManualQaReport(packetDirectory) { return JSON.parse(readFileSync(join(resolve(packetDirectory), "report.json"), "utf8")); }
 export function validateManualQaReport(packet) {
     const path = join(packet.directory, "report.json");
@@ -273,17 +456,29 @@ export function validateQaRecoveryAcknowledgement(text, packet, options = {}) {
 export function qaRecoveryInventory(packet) {
     return packet.manifest.resources.map((resource) => `${resource.path}\t${resource.purpose}\t${resource.mediaType}\t${resource.bytes}\t${resource.digest}\t${resource.integrityPolicy}`).join("\n");
 }
-export function qaReportDigest(report) { return hash(Buffer.from(JSON.stringify(report))); }
+export function qaReportDigest(report) { return hash(Buffer.from(canonicalJson(report))); }
+function canonicalJson(value) {
+    if (value === null || typeof value !== "object")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(canonicalJson).join(",")}]`;
+    const object = value;
+    return `{${Object.keys(object).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(object[key])}`).join(",")}}`;
+}
 export function ensureQaRecoveryExcluded(projectDir) {
     let exclude;
+    let common;
     try {
-        exclude = execFileSync("git", ["-C", resolve(projectDir), "rev-parse", "--git-path", "info/exclude"], { encoding: "utf8" }).trim();
+        exclude = execFileSync("git", ["-C", resolve(projectDir), "rev-parse", "--path-format=absolute", "--git-path", "info/exclude"], { encoding: "utf8" }).trim();
+        common = execFileSync("git", ["-C", resolve(projectDir), "rev-parse", "--path-format=absolute", "--git-common-dir"], { encoding: "utf8" }).trim();
     }
     catch {
         return;
     }
-    if (!resolve(exclude).startsWith(sep))
-        exclude = resolve(projectDir, exclude);
+    exclude = resolve(exclude);
+    common = resolve(common);
+    if (exclude !== common && !exclude.startsWith(`${common}${sep}`))
+        throw new Error(`git exclude path escapes the target repository: ${exclude}`);
     const entries = [`/${QA_RECOVERY_ROOT}/`, `/${QA_CONTEXT_ROOT}/`];
     const current = existsSync(exclude) ? readFileSync(exclude, "utf8") : "";
     const missing = entries.filter((entry) => !current.split(/\r?\n/).includes(entry));
@@ -301,31 +496,29 @@ function storeFrozenState(root, state, prefix) {
         [`${prefix}/staged.diff`, state.stagedDiff, "application/octet-stream", "Exact staged tracked binary diff"],
         [`${prefix}/unstaged.diff`, state.unstagedDiff, "application/octet-stream", "Exact unstaged tracked binary diff"],
         [`${prefix}/change-summary.txt`, Buffer.from(`${state.changeSummary}\n`), "text/plain", "Deterministic path-level source summary"],
-        [`${prefix}/integrity.json`, Buffer.from(`${stableJson({ digest: state.digest, capturedAt: state.capturedAt })}\n`), "application/json", "Reviewed-state integrity manifest"],
+        [`${prefix}/path-inventory.json`, Buffer.from(`${stableJson(state.pathInventory)}\n`), "application/json", "Structured staged, unstaged, and untracked source paths"],
+        [`${prefix}/repository.json`, Buffer.from(`${stableJson(state.repository)}\n`), "application/json", "Repository identity, refs, configuration, sparse-checkout, submodule, and index metadata"],
+        [`${prefix}/integrity.json`, Buffer.from(`${stableJson({ digest: state.digest, originDigest: state.originDigest, contentDigest: state.contentDigest, capturedAt: state.capturedAt })}\n`), "application/json", "Reviewed-state integrity manifest"],
         [`${prefix}/untracked-manifest.json`, Buffer.from(`${stableJson(inventory)}\n`), "application/json", "Untracked path, type, mode, digest, and object mapping"],
     ];
     state.untracked.forEach((item, index) => values.push([`${prefix}/untracked/${String(index).padStart(6, "0")}.bin`, item.bytes, "application/octet-stream", `Exact untracked ${item.kind} bytes for ${item.path}`]));
     return values.map(([path, bytes, mediaType, purpose]) => storeSealed(root, safeRelative(path), bytes, purpose, mediaType, true));
 }
 function sourceInventory(packet, prefix) {
-    const resource = packet.manifest.resources.find((candidate) => candidate.path === `${prefix}/untracked-manifest.json`);
     const rows = new Map();
-    for (const candidate of packet.manifest.resources.filter((item) => item.path.startsWith(`${prefix}/`) && !item.path.includes("/untracked/")))
-        rows.set(candidate.path.slice(prefix.length + 1), candidate.digest);
-    if (resource?.objectPath) {
-        const inventory = JSON.parse(readFileSync(join(packet.directory, resource.objectPath), "utf8"));
-        for (const item of inventory)
-            rows.set(`untracked:${item.path}`, `${item.kind}:${item.mode}:${item.digest}`);
-    }
+    const head = packet.manifest.resources.find((candidate) => candidate.path === `${prefix}/head.txt`);
+    if (head)
+        rows.set("HEAD", head.digest);
+    const resource = packet.manifest.resources.find((candidate) => candidate.path === `${prefix}/path-inventory.json`);
+    if (resource?.objectPath)
+        for (const item of JSON.parse(readFileSync(join(packet.directory, resource.objectPath), "utf8")))
+            rows.set(item.path, stableJson(item));
     return rows;
 }
 function inventoryFromFrozen(state) {
-    const rows = new Map([
-        ["head.txt", hash(Buffer.from(`${state.head}\n`))], ["status.bin", hash(state.status)], ["tracked-head.diff", hash(state.combinedDiff)],
-        ["staged.diff", hash(state.stagedDiff)], ["unstaged.diff", hash(state.unstagedDiff)], ["change-summary.txt", hash(Buffer.from(`${state.changeSummary}\n`))],
-    ]);
-    for (const item of state.untracked)
-        rows.set(`untracked:${item.path}`, `${item.kind}:${item.mode}:${item.digest}`);
+    const rows = new Map([["HEAD", hash(Buffer.from(`${state.head}\n`))]]);
+    for (const item of state.pathInventory)
+        rows.set(item.path, stableJson(item));
     return rows;
 }
 function deterministicDrift(before, after) {
@@ -334,17 +527,30 @@ function deterministicDrift(before, after) {
 function storeSealed(root, path, bytes, purpose, mediaType, requiredForRecovery) {
     const digest = hash(bytes);
     const objectPath = `objects/${digest}`;
+    // SQLite is authoritative. Persist the exact bytes before writing either
+    // the content-addressed cache object or its human-readable projection.
+    const evidenceDb = new WorkflowDb(recoveryProjectRoot(root));
+    try {
+        const durableDigest = evidenceDb.putEvidence("qa", bytes);
+        if (durableDigest !== digest)
+            throw new Error(`durable QA resource digest mismatch: ${path}`);
+    }
+    finally {
+        evidenceDb.close();
+    }
     const absolute = join(root, objectPath);
     if (!existsSync(absolute))
         atomicWrite(absolute, bytes);
     else if (hash(readFileSync(absolute)) !== digest)
         throw new Error(`content-addressed QA recovery object collision: ${digest}`);
     const projection = join(root, path);
-    if (existsSync(projection))
-        throw new Error(`QA recovery resource path already exists: ${path}`);
-    mkdirSync(dirname(projection), { recursive: true, mode: 0o700 });
-    copyFileSync(absolute, projection);
-    chmodSync(projection, 0o600);
+    if (existsSync(projection)) {
+        const existing = readFileSync(projection);
+        if (existing.length !== bytes.length || hash(existing) !== digest)
+            throw new Error(`QA recovery resource path already exists with different content: ${path}`);
+    }
+    else
+        atomicWrite(projection, bytes);
     return { path, purpose, mediaType, bytes: bytes.length, digest, requiredForRecovery, integrityPolicy: "sealed", objectPath };
 }
 function writeEditableReport(root, bytes) {
@@ -361,6 +567,7 @@ function validateResource(root, resource) {
         const path = join(root, "report.json");
         if (!existsSync(path) || lstatSync(path).isSymbolicLink())
             throw new Error("missing or unsafe operator-editable report.json");
+        assertPrivatePath(path, false);
         return;
     }
     if (resource.integrityPolicy !== "sealed" || !resource.objectPath)
@@ -369,6 +576,7 @@ function validateResource(root, resource) {
     if (!objectPath.startsWith(`${root}${sep}`) || !existsSync(objectPath))
         throw new Error(`missing or unsafe QA recovery object: ${resource.path}`);
     assertNoSymlinkComponents(root, objectPath);
+    assertPrivatePath(objectPath, false);
     const bytes = readFileSync(objectPath);
     if (bytes.length !== resource.bytes || hash(bytes) !== resource.digest)
         throw new Error(`QA recovery resource digest mismatch: ${resource.path}`);
@@ -376,6 +584,7 @@ function validateResource(root, resource) {
     if (!projection.startsWith(`${root}${sep}`) || !existsSync(projection))
         throw new Error(`missing QA recovery resource projection: ${resource.path}`);
     assertNoSymlinkComponents(root, projection);
+    assertPrivatePath(projection, false);
     const projected = readFileSync(projection);
     if (projected.length !== resource.bytes || hash(projected) !== resource.digest)
         throw new Error(`QA recovery resource projection mismatch: ${resource.path}`);
@@ -394,7 +603,7 @@ function validateReviewedStates(root, manifest) {
     }
 }
 function validateReviewedState(root, manifest, prefix) {
-    const required = ["head.txt", "status.bin", "tracked-head.diff", "staged.diff", "unstaged.diff", "change-summary.txt", "integrity.json", "untracked-manifest.json"];
+    const required = ["head.txt", "status.bin", "tracked-head.diff", "staged.diff", "unstaged.diff", "change-summary.txt", "path-inventory.json", "repository.json", "integrity.json", "untracked-manifest.json"];
     const byPath = new Map(manifest.resources.map((resource) => [resource.path, resource]));
     const bytes = (suffix) => {
         const resource = byPath.get(`${prefix}/${suffix}`);
@@ -420,6 +629,10 @@ function validateReviewedState(root, manifest, prefix) {
         return { path: item.path, kind: item.kind, mode, digest: item.digest, bytes: value };
     });
     const declared = JSON.parse(bytes("integrity.json").toString());
+    const repository = JSON.parse(bytes("repository.json").toString());
+    const pathInventory = JSON.parse(bytes("path-inventory.json").toString());
+    if (!Array.isArray(pathInventory) || pathInventory.some((item) => !item || typeof item.path !== "string" || !Array.isArray(item.staged) || !Array.isArray(item.unstaged)))
+        throw new Error(`invalid reviewed-state path inventory: ${prefix}`);
     const state = {
         head: bytes("head.txt").toString().trimEnd(),
         status: bytes("status.bin"),
@@ -427,7 +640,11 @@ function validateReviewedState(root, manifest, prefix) {
         stagedDiff: bytes("staged.diff"),
         unstagedDiff: bytes("unstaged.diff"),
         changeSummary: bytes("change-summary.txt").toString().replace(/\n$/, ""),
+        pathInventory,
         untracked,
+        repository,
+        originDigest: String(declared.originDigest ?? ""),
+        contentDigest: String(declared.contentDigest ?? ""),
     };
     const digest = calculateFrozenQaStateDigest(state);
     if (declared.digest !== digest)
@@ -438,6 +655,9 @@ function revise(packet, changes) {
     const current = loadQaRecoveryPacket(packet.directory);
     if (current.manifest.packetDigest !== packet.manifest.packetDigest)
         throw new Error("stale QA recovery packet revision cannot be appended");
+    const interrupted = recoverInterruptedRevision(current, changes);
+    if (interrupted)
+        return interrupted;
     const { packetDigest: _digest, ...base } = current.manifest;
     const draft = {
         ...base, ...changes,
@@ -447,18 +667,119 @@ function revise(packet, changes) {
     };
     return publish(packet.directory, packet.projectDir, draft);
 }
+function recoverInterruptedRevision(packet, changes) {
+    const revision = packet.manifest.revision + 1;
+    const path = join(packet.directory, "manifests", revisionName(revision));
+    if (!existsSync(path))
+        return undefined;
+    const candidate = readAndValidateRevision(packet.directory, revision, packet.manifest);
+    const { packetDigest: _currentDigest, updatedAt: _currentUpdated, ...currentBase } = packet.manifest;
+    const { packetDigest: _candidateDigest, updatedAt: _candidateUpdated, ...candidateBase } = candidate;
+    const expected = { ...currentBase, ...changes, revision, parentPacketDigest: packet.manifest.packetDigest };
+    if (stableJson(candidateBase) !== stableJson(expected))
+        throw new Error(`QA recovery revision already exists with different content: ${revision}`);
+    promoteIntendedRevision(packet.directory, revision, candidate.packetDigest, packet.manifest);
+    return reconcileQaRecoveryPacketPublication(loadQaRecoveryPacket(packet.directory));
+}
+function promoteIntendedRevision(root, revision, expectedDigest, parent) {
+    assertPublicationTree(recoveryProjectRoot(root), root);
+    const candidate = readAndValidateRevision(root, revision, parent);
+    if (candidate.packetDigest !== expectedDigest)
+        throw new Error("QA recovery revision does not match its durable publication intent");
+    const projectDir = recoveryProjectRoot(root);
+    const db = new WorkflowDb(projectDir);
+    try {
+        const projection = db.qaPacketProjection(expectedDigest);
+        if (!projection || projection.status !== "intended" || resolve(projection.path) !== resolve(root)
+            || projection.runId !== candidate.runId || projection.ticketId !== candidate.ticketId || projection.packetRevision !== revision) {
+            throw new Error("QA recovery revision promotion lacks a matching durable publication intent");
+        }
+    }
+    finally {
+        db.close();
+    }
+    atomicWrite(join(root, "manifest.json"), readFileSync(join(root, "manifests", revisionName(revision))));
+    chmodTreeOwnerOnly(root);
+}
+/** Recreate a revision that was durably intended in SQLite but not yet fsynced to the packet tree. */
+function restoreIntendedRevision(root, projection, parent) {
+    assertPublicationTree(recoveryProjectRoot(root), root);
+    const path = join(root, "manifests", revisionName(projection.packetRevision));
+    if (existsSync(path))
+        return;
+    if (!projection.manifestJson)
+        throw new Error("QA packet publication intent does not contain recoverable manifest bytes");
+    const candidate = JSON.parse(projection.manifestJson);
+    assertManifestShape(candidate);
+    if (candidate.packetDigest !== projection.packetDigest || candidate.revision !== projection.packetRevision
+        || candidate.runId !== projection.runId || candidate.ticketId !== projection.ticketId
+        || (parent ? candidate.packetId !== parent.packetId || candidate.parentPacketDigest !== parent.packetDigest
+            : candidate.revision !== 1 || candidate.parentPacketDigest !== undefined)) {
+        throw new Error("QA packet publication intent contains mismatched manifest bytes");
+    }
+    for (const resource of candidate.resources)
+        validateResource(root, resource);
+    validateReviewedStates(root, candidate);
+    if (calculatePacketDigest(root, candidate) !== candidate.packetDigest)
+        throw new Error("QA packet publication intent manifest digest mismatch");
+    atomicWrite(path, Buffer.from(projection.manifestJson));
+}
+function readAndValidateRevision(root, revision, parent) {
+    assertPrivateTree(root);
+    const path = join(root, "manifests", revisionName(revision));
+    if (!existsSync(path) || lstatSync(path).isSymbolicLink())
+        throw new Error(`QA recovery revision ${revision} is missing or unsafe`);
+    const candidate = JSON.parse(readFileSync(path, "utf8"));
+    assertManifestShape(candidate);
+    if (candidate.revision !== revision || (parent && candidate.packetId !== parent.packetId)
+        || (revision === 1 ? candidate.parentPacketDigest !== undefined : candidate.parentPacketDigest !== parent?.packetDigest)) {
+        throw new Error(`QA recovery revision lineage mismatch at revision ${revision}`);
+    }
+    for (const resource of candidate.resources)
+        validateResource(root, resource);
+    validateReviewedStates(root, candidate);
+    if (calculatePacketDigest(root, candidate) !== candidate.packetDigest)
+        throw new Error(`QA recovery revision digest mismatch at revision ${revision}`);
+    return candidate;
+}
+/** Validate ancestors before crash recovery writes into a persisted path. */
+function assertPublicationTree(projectDir, directory) {
+    const project = realpathSync(resolve(projectDir));
+    const root = resolve(directory);
+    if (!root.startsWith(`${project}${sep}`) || !existsSync(root) || realpathSync(root) !== root)
+        throw new Error("unsafe or symlinked QA packet publication path");
+    assertNoSymlinkComponents(project, root);
+    assertPrivateTree(root);
+}
 function publish(root, projectDir, draft) {
     const manifest = { ...draft, resources: draft.resources.slice().sort(resourceOrder), packetDigest: "" };
     manifest.packetDigest = calculatePacketDigest(root, manifest);
     const bytes = Buffer.from(`${stableJson(manifest)}\n`);
     const revisionPath = join(root, "manifests", revisionName(manifest.revision));
-    if (existsSync(revisionPath))
-        throw new Error(`QA recovery revision already exists: ${manifest.revision}`);
-    atomicWrite(revisionPath, bytes);
+    const db = new WorkflowDb(projectDir);
+    try {
+        db.planQaPacketProjection({ runId: manifest.runId, ticketId: manifest.ticketId, qaRevision: manifest.revision, packetDigest: manifest.packetDigest, path: root, manifestJson: bytes.toString() });
+    }
+    finally {
+        db.close();
+    }
+    if (existsSync(revisionPath)) {
+        if (!readFileSync(revisionPath).equals(bytes))
+            throw new Error(`QA recovery revision already exists with different content: ${manifest.revision}`);
+    }
+    else
+        atomicWrite(revisionPath, bytes);
     atomicWrite(join(root, "manifest.json"), bytes);
     chmodTreeOwnerOnly(root);
     const packet = { directory: root, projectDir, manifest };
     persistPendingState(packet);
+    const completed = new WorkflowDb(projectDir);
+    try {
+        completed.finishQaPacketProjection(manifest.runId, manifest.ticketId, manifest.packetDigest);
+    }
+    finally {
+        completed.close();
+    }
     return packet;
 }
 function calculatePacketDigest(root, manifest) {
@@ -477,21 +798,20 @@ function persistPendingState(packet) {
         const run = db.getRun(packet.manifest.runId);
         if (!run)
             return;
-        const qaReportRecovery = {
-            packetPath: packet.directory,
-            packetDigest: packet.manifest.packetDigest,
-            reviewedStateDigest: packet.manifest.reviewedStateDigest,
-            revision: packet.manifest.revision,
-            ladderPosition: packet.manifest.correctionTurns,
-            pendingAction: packet.manifest.pendingAction,
-            ticketId: packet.manifest.ticketId,
-            packetId: packet.manifest.packetId,
-            retentionProtected: true,
-        };
+        db.putQaRecoveryHead({
+            runId: packet.manifest.runId, ticketId: packet.manifest.ticketId, packetId: packet.manifest.packetId,
+            packetPath: packet.directory, packetDigest: packet.manifest.packetDigest, reviewedStateDigest: packet.manifest.reviewedStateDigest,
+            revision: packet.manifest.revision, correctionTurns: packet.manifest.correctionTurns, pendingAction: packet.manifest.pendingAction,
+        });
+        // Compatibility projection only. Readers that make recovery decisions use
+        // qa_recovery_heads, so saveBuildRun cannot destroy authoritative state.
         db.transition(packet.manifest.runId, {
             status: run.status, checkpoint: run.checkpoint, remainingWork: run.remainingWork,
-            state: { ...run.state, qaReportRecovery }, event: "qa_recovery_packet_revision",
-            payload: { packetDigest: packet.manifest.packetDigest, revision: packet.manifest.revision, pendingAction: packet.manifest.pendingAction, ticketId: packet.manifest.ticketId },
+            state: { ...run.state, qaReportRecovery: { packetPath: packet.directory, packetDigest: packet.manifest.packetDigest,
+                    reviewedStateDigest: packet.manifest.reviewedStateDigest, revision: packet.manifest.revision,
+                    ladderPosition: packet.manifest.correctionTurns, pendingAction: packet.manifest.pendingAction,
+                    ticketId: packet.manifest.ticketId, packetId: packet.manifest.packetId, retentionProtected: true } },
+            event: "qa_recovery_packet_revision", payload: { ticketId: packet.manifest.ticketId, revision: packet.manifest.revision, packetDigest: packet.manifest.packetDigest, pendingAction: packet.manifest.pendingAction },
         });
     }
     finally {
@@ -507,6 +827,7 @@ function assertManifestShape(value) {
         || !Number.isSafeInteger(value.correctionTurns) || value.correctionTurns < 0
         || !/^[a-f0-9]{64}$/.test(value.packetDigest)
         || !value.packetId || !value.reviewAttemptId || !value.runId || !value.ticketId
+        || !["automatic-recovery", "successor-acknowledgement", "qa-correction", "qa-full-review", "operator-menu", "validated-report", "builder-remediation-pending", "builder-remediation-in-flight", "resolved"].includes(value.pendingAction)
         || !/^[a-f0-9]{64}$/.test(value.originalReviewedStateDigest)
         || !/^[a-f0-9]{64}$/.test(value.currentReviewedStateDigest)
         || !/^[a-f0-9]{64}$/.test(value.reviewedStateDigest))
@@ -537,14 +858,15 @@ function chmodRecoveryDirectoryChain(projectDir, target) {
             chmodSync(cursor, 0o700);
     }
 }
-function uniqueResourcePath(resources, requested) {
-    if (!resources.some((resource) => resource.path === requested))
+function uniqueResourcePath(resources, requested, root) {
+    const occupied = (candidate) => resources.some((resource) => resource.path === candidate) || Boolean(root && existsSync(join(root, candidate)));
+    if (!occupied(requested))
         return requested;
     const dot = requested.lastIndexOf(".");
     const stem = dot > requested.lastIndexOf("/") ? requested.slice(0, dot) : requested;
     const extension = dot > requested.lastIndexOf("/") ? requested.slice(dot) : "";
     let sequence = 2;
-    while (resources.some((resource) => resource.path === `${stem}.seq-${String(sequence).padStart(4, "0")}${extension}`))
+    while (occupied(`${stem}.seq-${String(sequence).padStart(4, "0")}${extension}`))
         sequence++;
     return `${stem}.seq-${String(sequence).padStart(4, "0")}${extension}`;
 }
@@ -559,7 +881,79 @@ function slugWithHash(value) { return `${safeSlug(value)}-${hash(Buffer.from(val
 function revisionName(revision) { return `revision-${String(revision).padStart(8, "0")}.json`; }
 function resourceOrder(a, b) { return a.path.localeCompare(b.path); }
 function encodeValue(value, exact) { return exact ? Buffer.from(typeof value === "string" ? value : String(value)) : Buffer.from(`${stableJson(value)}\n`); }
-function atomicWrite(path, bytes, mode = 0o600) { mkdirSync(dirname(path), { recursive: true, mode: 0o700 }); const temp = join(dirname(path), `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`); writeFileSync(temp, bytes, { mode }); chmodSync(temp, mode); renameSync(temp, path); chmodSync(path, mode); }
+function atomicWrite(path, bytes, mode = 0o600) {
+    const parent = dirname(path);
+    durableMkdir(parent);
+    const temp = join(parent, `.${basename(path)}.${process.pid}.${randomUUID()}.tmp`);
+    writeFileSync(temp, bytes, { mode });
+    chmodSync(temp, mode);
+    const fd = openSync(temp, "r");
+    try {
+        fsyncSync(fd);
+    }
+    finally {
+        closeSync(fd);
+    }
+    renameSync(temp, path);
+    chmodSync(path, mode);
+    fsyncDirectory(parent);
+}
+function durableMkdir(path) {
+    const target = resolve(path);
+    let existing = target;
+    while (!existsSync(existing)) {
+        const parent = dirname(existing);
+        if (parent === existing)
+            break;
+        existing = parent;
+    }
+    mkdirSync(target, { recursive: true, mode: 0o700 });
+    chmodSync(target, 0o700);
+    let cursor = target;
+    fsyncDirectory(cursor);
+    while (cursor !== existing) {
+        cursor = dirname(cursor);
+        fsyncDirectory(cursor);
+    }
+}
+function fsyncDirectory(path) {
+    let fd;
+    try {
+        fd = openSync(path, "r");
+        fsyncSync(fd);
+    }
+    catch (error) {
+        const code = error.code;
+        if (code !== "EINVAL" && code !== "ENOTSUP" && code !== "EPERM")
+            throw error;
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+function assertPrivatePath(path, directory) {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile()))
+        throw new Error(`unsafe QA recovery ${directory ? "directory" : "file"}: ${path}`);
+    if (typeof process.getuid === "function" && stat.uid !== process.getuid())
+        throw new Error(`QA recovery path is not owned by the current operator: ${path}`);
+    if (process.platform !== "win32") {
+        const expected = directory ? 0o700 : 0o600;
+        if ((stat.mode & 0o777) !== expected)
+            throw new Error(`QA recovery path has unsafe permissions: ${path}`);
+    }
+}
+function assertPrivateTree(root) {
+    assertPrivatePath(root, true);
+    for (const name of readdirSync(root)) {
+        const path = join(root, name);
+        const stat = lstatSync(path);
+        assertPrivatePath(path, stat.isDirectory());
+        if (stat.isDirectory())
+            assertPrivateTree(path);
+    }
+}
 function hash(bytes) { return createHash("sha256").update(bytes).digest("hex"); }
 function statOwner(path) { return lstatSync(path).uid; }
 function stableJson(value) { if (Array.isArray(value))