ai-foreman 1.7.24 → 1.7.26

package/dist/permissions/shellForms.js

@@ -0,0 +1,203 @@
+import { isAbsolute, relative, resolve, sep, dirname, basename } from "node:path";
+import { existsSync, readdirSync } from "node:fs";
+import { canonicalSessionPath } from "../sessionIdentity.js";
+/** Intentionally bounded shell grammar. No expansion, background jobs,
+ * conditionals, substitutions, or filesystem redirects are normalized. */
+function segments(command) {
+    const result = [];
+    let words = [], word = "", started = false;
+    let quote;
+    let followsPipe = false;
+    let hadBackslash = false;
+    const flush = () => { if (started)
+        words.push(word); word = ""; started = false; };
+    const finish = (pipe) => {
+        flush();
+        if (!words.length)
+            throw new Error("empty shell command segment");
+        result.push({ words, followsPipe, endsPipe: pipe, hadBackslash });
+        words = [];
+        followsPipe = pipe;
+        hadBackslash = false;
+    };
+    for (let i = 0; i < command.length; i++) {
+        const char = command[i];
+        if (char === "\\")
+            hadBackslash = true;
+        if (char === "\n" || char === "\r")
+            throw new Error("multiline shell syntax needs approval");
+        if (char === "\\" && quote !== "'") {
+            const next = command[++i];
+            if (!next || next === "\n" || next === "\r")
+                throw new Error("unsupported shell escape");
+            word += next;
+            started = true;
+            continue;
+        }
+        if (quote) {
+            if (char === quote)
+                quote = undefined;
+            else {
+                if (quote === '"' && (char === "$" || char === "`"))
+                    throw new Error("shell expansion needs approval");
+                word += char;
+            }
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            flush();
+            continue;
+        }
+        if (!started && command.slice(i, i + 4) === "2>&1" && (i + 4 === command.length || /\s|[&|;]/.test(command[i + 4]))) {
+            i += 3;
+            continue;
+        }
+        if (command.slice(i, i + 2) === "&&") {
+            finish(false);
+            i++;
+            continue;
+        }
+        if (char === "|" && command[i + 1] === "|")
+            throw new Error("shell conditionals need approval");
+        if (char === "|") {
+            finish(true);
+            continue;
+        }
+        if (/[&;<>$`(){}~#]/.test(char))
+            throw new Error("unsupported shell operator or expansion needs approval");
+        word += char;
+        started = true;
+    }
+    if (quote)
+        throw new Error("unterminated shell quote");
+    finish(false);
+    return result;
+}
+export function canonicalToolPath(path) {
+    let ancestor = resolve(path);
+    const missing = [];
+    while (!existsSync(ancestor) && dirname(ancestor) !== ancestor) {
+        missing.unshift(basename(ancestor));
+        ancestor = dirname(ancestor);
+    }
+    return resolve(canonicalSessionPath(ancestor), ...missing);
+}
+export function isWithinProject(root, path) {
+    const rel = relative(canonicalToolPath(root), canonicalToolPath(path));
+    return rel === "" || (!isAbsolute(rel) && rel !== ".." && !rel.startsWith(`..${sep}`));
+}
+const inside = isWithinProject;
+function validateRestrictedNodeTests(words, root, cwd) {
+    if (words[1] !== "--test")
+        return "QA permits Node's test runner, not arbitrary Node execution";
+    let files = 0, literalFiles = false;
+    for (const arg of words.slice(2)) {
+        if (!literalFiles && arg === "--") {
+            literalFiles = true;
+            continue;
+        }
+        if (!literalFiles && arg.startsWith("-")) {
+            if (/^--test-name-pattern=.+$/.test(arg) || /^--test-reporter=(?:tap|spec|dot)$/.test(arg))
+                continue;
+            if (/^--test-concurrency=\d{1,2}$/.test(arg) && Number(arg.split("=")[1]) >= 1 && Number(arg.split("=")[1]) <= 32)
+                continue;
+            return "unapproved Node test option; use local test files without eval, preload, loader or output controls";
+        }
+        if (!/\.test\.(?:mjs|cjs|js|mts|cts|ts)$/.test(arg))
+            return "use explicit worktree-local .test files";
+        const path = resolve(cwd, arg), directory = dirname(path), name = basename(path);
+        if (!inside(root, directory) || /[?\[\]{}*]/.test(dirname(arg)))
+            return "Node test path escapes the worktree or uses an unsupported directory glob";
+        if (name.includes("*")) {
+            if (/[?\[\]{}]/.test(name))
+                return "unsupported Node test glob";
+            const pattern = new RegExp(`^${name.split("*").map(part => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")).join(".*")}$`);
+            try {
+                if (existsSync(directory) && readdirSync(directory).some(entry => pattern.test(entry) && !inside(root, resolve(directory, entry))))
+                    return "Node test glob resolves outside the worktree";
+            }
+            catch {
+                return "Node test directory inventory is unavailable; inspect the local path before retrying";
+            }
+        }
+        else if (!inside(root, path))
+            return "Node test path resolves outside the worktree";
+        files++;
+    }
+    return files ? undefined : "use explicit worktree-local .test files";
+}
+export function classifySupportedShellForm(command, root, initialCwd, allowBash) {
+    if (!inside(root, initialCwd))
+        return "tool cwd is outside the worktree";
+    let cwd = initialCwd;
+    let parsed;
+    try {
+        parsed = segments(command);
+    }
+    catch (error) {
+        return error.message;
+    }
+    for (const segment of parsed) {
+        const words = [...segment.words];
+        if (words[0] === "cd") {
+            if (words.length !== 2 || segment.followsPipe || segment.endsPipe)
+                return "only a literal in-worktree cd followed by && is supported";
+            const target = resolve(cwd, words[1]);
+            if (!inside(root, target))
+                return "directory change escapes the worktree";
+            cwd = target;
+            continue;
+        }
+        while (/^[A-Za-z_]\w*=/.test(words[0] ?? "")) {
+            const assignment = words.shift();
+            const split = assignment.indexOf("=");
+            const key = assignment.slice(0, split), value = assignment.slice(split + 1);
+            const simple = /^(?:CI|NO_COLOR|FORCE_COLOR|PYTHONUNBUFFERED|PYTHONDONTWRITEBYTECODE|PYTEST_DISABLE_PLUGIN_AUTOLOAD)$/;
+            if (simple.test(key) && /^(?:0|1|true|false)$/.test(value))
+                continue;
+            if ((key === "PYTHONPATH" || key === "UV_PROJECT_ENVIRONMENT") && value && value.split(process.platform === "win32" ? ";" : ":").every(path => path && inside(root, resolve(cwd, path))))
+                continue;
+            return `environment assignment ${key} needs approval; use a literal project-local test environment`;
+        }
+        if (!words.length)
+            return "unsupported shell executable";
+        // Offline/no-sync uv is only an environment runner for an already allowed
+        // command. Ordinary uv acquisition still requires its configured policy.
+        if (words.slice(0, 4).join(" ") === "uv run --offline --no-sync")
+            words.splice(0, 4);
+        const executable = words[0] ?? "";
+        if (/(?:^|[/\\])(?:python3?|pytest)$/.test(executable) && executable.includes("/")) {
+            const path = resolve(cwd, executable);
+            // POSIX virtualenvs normally symlink their Python binary to the native
+            // interpreter. Keep the containing environment inside the worktree and
+            // allow only that interpreter alias, never a directory escape or a
+            // Python-named symlink to an unrelated executable.
+            const nativePythonAlias = /^python(?:3)?$/.test(basename(executable))
+                && /^python(?:\d+(?:\.\d+)*)?$/i.test(basename(canonicalSessionPath(path)))
+                && inside(root, dirname(path));
+            if (inside(root, path) || nativePythonAlias)
+                words[0] = executable.split(/[/\\]/).at(-1);
+        }
+        if (!words.length || /\s/.test(words[0]))
+            return "unsupported shell executable";
+        if (words[0] === "node" && allowBash.includes("node --test") && !allowBash.includes("node ") && !allowBash.includes("node")) {
+            const invalid = validateRestrictedNodeTests(words, root, cwd);
+            if (process.platform === "win32" && segment.hadBackslash)
+                return "restricted Node tests require forward-slash paths on Windows";
+            if (invalid)
+                return invalid;
+        }
+        const allowed = allowBash.some(prefix => {
+            const expected = prefix.trim().split(/\s+/);
+            return expected.every((word, index) => words[index] === word) && (words.length > expected.length || !prefix.endsWith(" "));
+        });
+        if (!allowed)
+            return `command is not allow-listed: ${words.join(" ")}; use a configured project test command`;
+    }
+    return undefined;
+}

package/dist/qaBuilderActivation.d.ts

@@ -0,0 +1,19 @@
+import type { BuildRunRecordV2, ResolvedAgentSettings } from "rafi-spec";
+import type { BuilderAdapter } from "./adapters/types.js";
+import { type HandoffRecoveryOptions, type StagedHandoff } from "./handoffs.js";
+export interface QaRecoveryBuilderActivation {
+    projectDir: string;
+    runId: string;
+    ticketId: string;
+    worktree: string;
+    adapter: BuilderAdapter;
+    settings: ResolvedAgentSettings;
+    expectedCapabilities?: BuildRunRecordV2["builderCapabilities"];
+    frozenAction: string;
+    createSuccessor: (handoff: StagedHandoff, requestedRuntime?: "claude" | "codex") => Promise<BuilderAdapter>;
+    wrap: (adapter: BuilderAdapter) => BuilderAdapter | Promise<BuilderAdapter>;
+    recovery?: HandoffRecoveryOptions;
+}
+/** QA-only startup must not replace Builder ownership. Activate a Builder only
+ * at an authorized work boundary, through the ordinary validated handoff. */
+export declare function activateQaRecoveryBuilder(input: QaRecoveryBuilderActivation): Promise<BuilderAdapter>;

package/dist/qaBuilderActivation.js

@@ -0,0 +1,112 @@
+import { execFileSync } from "node:child_process";
+import { realpathSync } from "node:fs";
+import { assertBuildAssignmentReconciled, captureBuildSource } from "./buildAssignment.js";
+import { HandoffService, HandoffRecoveryPausedError } from "./handoffs.js";
+import { qaDigest } from "./qaProtocolV2.js";
+import { providerSessionKey } from "./sessionIdentity.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
+import { loadTickets } from "./tickets/ticketLoader.js";
+import { WorkflowDb } from "./workflowDb.js";
+/** QA-only startup must not replace Builder ownership. Activate a Builder only
+ * at an authorized work boundary, through the ordinary validated handoff. */
+export async function activateQaRecoveryBuilder(input) {
+    const inspect = () => {
+        const db = new WorkflowDb(input.projectDir);
+        try {
+            const lease = db.currentLease();
+            if (lease?.runId !== input.runId || lease.pid !== process.pid)
+                throw new Error("Builder activation requires the current build execution lease");
+            const run = db.getRun(input.runId)?.state;
+            if (!run?.tickets.includes(input.ticketId) || run.progress.completedTickets.includes(input.ticketId))
+                throw new Error("QA recovery cannot activate Builder work outside unfinished approved scope");
+            const admission = db.assertAdmittedWork(input.runId, input.ticketId);
+            const definition = loadTickets(resolveTicketPaths(loadTicketsConfig(input.projectDir), input.projectDir).tickets).find(ticket => ticket.id === input.ticketId);
+            if (!definition || qaDigest("admitted-requirements", definition) !== admission.requirementsDigest)
+                throw new Error("Builder recovery requirements changed; renew scope approval before implementation");
+            if (!run.builder || qaDigest("builder-settings", run.builder.settings) !== qaDigest("builder-settings", input.settings))
+                throw new Error("QA recovery cannot replace the saved Builder settings");
+            if (input.expectedCapabilities && qaDigest("builder-capabilities", run.builderCapabilities) !== qaDigest("builder-capabilities", input.expectedCapabilities))
+                throw new Error("Builder capability approval changed before recovery activation");
+            if (db.unresolvedRoleDispatches(input.runId, "builder").length)
+                throw new Error("Reconcile unknown Builder dispatch before activating another session");
+            assertBuildAssignmentReconciled(input.projectDir, input.runId, input.worktree);
+            const owner = db.roleMutationLease(input.runId, "builder");
+            const ref = owner?.sessionRef;
+            if (!owner || !Number.isSafeInteger(owner.generation) || owner.generation < 0 || !ref || ref.version !== 1 || ref.role !== "builder" || ref.stream !== "builder"
+                || !Number.isSafeInteger(ref.generation) || ref.generation < 0 || ref.sessionId !== owner.providerSessionId
+                || ref.source !== "observed" || !ref.validatedAt || Number.isNaN(Date.parse(ref.validatedAt)) || providerSessionKey(ref) !== owner.sessionKey
+                || realpathSync(ref.cwd) !== realpathSync(input.worktree) || realpathSync(ref.configRoot) !== realpathSync(input.projectDir))
+                throw new Error("QA recovery has no validated Builder owner for this worktree");
+            const branchSession = db.branchResumeSessions(false).find(session => session.ticket === input.ticketId && realpathSync(session.worktreePath) === realpathSync(input.worktree));
+            const branch = branchSession?.branch ?? (realpathSync(run.repository.worktree) === realpathSync(input.worktree) ? run.repository.branch : undefined);
+            if (!branch || execFileSync("git", ["branch", "--show-current"], { cwd: input.worktree, encoding: "utf8" }).trim() !== branch)
+                throw new Error("Return to the approved Builder worktree branch before recovery activation");
+            const head = db.continuityHead(input.runId, "builder");
+            if (!head || head.state !== "current" || !db.latestContinuityCheckpoint(input.runId, "builder"))
+                throw new Error("Builder continuity needs reconstruction before QA can request implementation");
+            return { owner, ref, head, source: captureBuildSource(input.worktree), requirementsDigest: admission.requirementsDigest,
+                capabilitiesDigest: qaDigest("builder-capabilities", run.builderCapabilities), compactionCount: db.successfulCompactionCount(input.runId, "builder", ref) };
+        }
+        finally {
+            db.close();
+        }
+    };
+    const before = inspect();
+    const currentRef = input.adapter.sessionRef?.();
+    if (currentRef && providerSessionKey(currentRef) === before.owner.sessionKey && currentRef.generation === before.ref.generation
+        && currentRef.role === "builder" && currentRef.stream === "builder" && realpathSync(currentRef.configRoot) === realpathSync(input.projectDir)
+        && currentRef.source === "observed" && currentRef.validatedAt)
+        return input.adapter;
+    const assertPreparedState = (current) => {
+        if (current.owner.generation !== before.owner.generation || current.owner.sessionKey !== before.owner.sessionKey
+            || current.head.digest !== before.head.digest || current.source.digest !== before.source.digest || current.capabilitiesDigest !== before.capabilitiesDigest)
+            throw new Error("Builder recovery state changed while preparing its handoff; inspect and retry");
+    };
+    const transfer = await new HandoffService(input.projectDir).transfer({
+        runId: input.runId, role: "builder", reason: "Authorized Builder work after QA-only recovery requires a validated Builder owner",
+        predecessorSessionId: before.ref.sessionId, predecessorSessionRef: before.ref,
+        compactionCount: before.compactionCount, compactMaximum: input.settings.compact_maximum ?? 10,
+        roleState: { ticketId: input.ticketId, requirementsDigest: before.requirementsDigest, sourceDigest: before.source.digest,
+            capabilitiesDigest: before.capabilitiesDigest, recovery: "qa-builder-activation", providerReplayAuthorized: false },
+        resources: [{ label: "frozen-action", content: input.frozenAction, authoritative: true, purpose: "Approved QA remediation or guidance action; no replay of historical work" }],
+    }, async (handoff, runtime) => {
+        assertPreparedState(inspect());
+        const successor = await input.createSuccessor(handoff, runtime);
+        try {
+            assertPreparedState(inspect());
+        }
+        catch (error) {
+            await successor.close().catch(() => { });
+            throw error;
+        }
+        return successor;
+    }, input.recovery);
+    let owned;
+    try {
+        owned = await input.wrap(transfer.successor);
+    }
+    catch (error) {
+        let drainError;
+        try {
+            await transfer.successor.close();
+        }
+        catch (failure) {
+            drainError = failure;
+        }
+        throw new HandoffRecoveryPausedError(input.runId, transfer.manifest.generation, `Builder handoff was accepted but could not install its execution wrapper: ${String(error)}.${drainError ? ` The accepted session also needs cleanup: ${String(drainError)}.` : " The accepted session was closed without implementation."} The recorded accepted owner is preserved; inspect this build with rafi resume before continuing.`);
+    }
+    try {
+        await input.adapter.close();
+    }
+    catch (error) {
+        let drainError;
+        try {
+            await owned.close();
+        }
+        catch (failure) {
+            drainError = failure;
+        }
+        throw new HandoffRecoveryPausedError(input.runId, transfer.manifest.generation, `Builder handoff was accepted, but the unused startup session could not close: ${String(error)}.${drainError ? ` The accepted session also needs cleanup: ${String(drainError)}.` : " The accepted session was closed without implementation."} Ownership remains with the recorded accepted session; reconcile cleanup with rafi resume before continuing.`);
+    }
+    return owned;
+}

package/dist/qaFailureDelivery.js

@@ -372,7 +372,7 @@ export class QaFailureDeliveryService {
                     Object.assign(record, { providerInstructionDigest: db.putEvidence("handoff", Buffer.from(turn.providerInstruction)), providerInstructionBytes: Buffer.byteLength(turn.providerInstruction), providerInstructionAvailability: "captured" });
             }
             record.eventEvidenceDigest = db.putEvidence("qa", Buffer.from(canonicalEvidence(events)));
-            record.toolCount = events.filter(e => e.kind === "tool" || e.kind === "provider-item" && !["agentMessage", "reasoning", "userMessage", "contextCompaction"].includes(e.itemType)).length;
+            record.toolCount = events.filter(e => e.kind === "tool" || e.kind === "provider-item" && !["text", "agentMessage", "reasoning", "userMessage", "contextCompaction"].includes(e.itemType)).length;
             record.terminalCount = events.filter(e => e.kind === "turn-complete").length;
             db.recordQaDeliveryTurn(record);
             this.faults.afterResponseStored?.();

package/dist/qaRecovery.js

@@ -426,9 +426,10 @@ export function materializeQaRecoveryContext(packet, qaWorktree) {
         } };
 }
 export function renderQaRecoveryAcknowledgementInstruction(packet, relativePath) {
-    const required = packet.manifest.resources.filter((resource) => resource.requiredForRecovery).map((resource) => `- path=${resource.path} purpose=${JSON.stringify(resource.purpose)} media_type=${resource.mediaType} bytes=${resource.bytes} digest=${resource.digest}`).join("\n");
+    const required = packet.manifest.resources.filter((resource) => resource.requiredForRecovery).map((resource) => `- read_path=${join(relativePath, resource.path)} packet_path=${resource.path} purpose=${JSON.stringify(resource.purpose)} media_type=${resource.mediaType} bytes=${resource.bytes} digest=${resource.digest}`).join("\n");
     return [
         "Read and verify every required recovery resource in this exact sealed packet revision before replying.",
+        "Use each exact read_path below within the current QA working directory. The normal read-only QA permissions apply; preserve the sealed packet and source.",
         `Recovery context directory: ${relativePath}`,
         `Packet ID: ${packet.manifest.packetId}`,
         `Packet revision: ${packet.manifest.revision}`,

package/dist/qaReview.d.ts

@@ -208,6 +208,10 @@ export declare function runIsolatedQa(opts: IsolatedQaOptions): Promise<Isolated
 export declare function buildQaReviewHandoff(ticket: TicketDef, builderSummary: string, diffDigest: string, validationChecklist: string[], changeSummary?: unknown, history?: QaReportHistoryEntry[]): string;
 export declare function compactWithRetry(adapter: BuilderAdapter): Promise<CompactResult>;
 export declare const QA_REPORT_RECOVERY_MENU: readonly ["Try a complete fresh QA review.", "Manually fix saved JSON for human inspection.", "Give QA specific instructions for a fresh review.", "Pause."];
+/** Shared invariant for host staging and the actual QA boundary receipt. */
+export declare function assertQaRecoveryHandoffInventory(resources: ReadonlyArray<{
+    label: string;
+}>): void;
 export declare function beginQaFinalization(projectDir: string, sourceWorktree: string, runId: string, ticketId: string, certificateId: string, expectedSourceStateDigest: string, consumer: string, allowedProjectionPaths?: string[]): Promise<void>;
 export declare function verifyPendingQaFinalizationSource(projectDir: string, sourceWorktree: string, runId: string, ticketId: string, allowProjection?: boolean, projectionOperationId?: string): Promise<void>;
 export declare function completeQaFinalization(projectDir: string, runId: string, ticketId: string): void;

package/dist/qaReview.js

@@ -200,8 +200,10 @@ async function runIsolatedQaOwned(opts) {
         if (protocolHead.state === "source-frozen" || protocolHead.state === "review-ready") {
             protocolHead = scopeDb.transitionQa(opts.recovery.runId, opts.ticket.id, protocolHead.revision, { type: "operator-menu" });
         }
-        if (opts.resumedRecovery && protocolHead.state === "recheck-required" && opts.resumedRecovery.manifest.pendingAction !== "qa-full-review") {
+        if (opts.resumedRecovery && protocolHead.state === "recheck-required") {
             opts.resumedRecovery = updateQaRecoveryPosition(opts.resumedRecovery, "qa-full-review", opts.resumedRecovery.manifest.correctionTurns, "qa-full-review");
+            if (scopeDb.hasConfirmedQaRemediationForRecheck(opts.recovery.runId, opts.ticket.id))
+                opts.resumedRecovery = undefined;
         }
         durableReviews = scopeDb.qaReviewAttempts(opts.recovery.runId, opts.ticket.id);
         for (const interrupted of durableReviews.filter((item) => item.status === "started"))
@@ -324,6 +326,8 @@ async function runIsolatedQaOwned(opts) {
         opts.qaRemediationAuthorization = undefined;
         if (!fix.ok)
             return pauseQaProtocol(opts, "builder-remediation-failed", fix.detail ?? "Builder QA remediation failed during restart recovery", fix.outcome === "needs-input" ? "needs-human" : "blocked");
+        if (!consumeRecoveryAfterOwnedFix(opts))
+            return pauseQaProtocol(opts, "builder-remediation-unconfirmed", "Builder remediation needs durable reconciliation before a fresh review", "needs-human");
         const fixSummary = boundedBuilderSummary(fix.summary ?? fix.response ?? "Builder reported remediation complete");
         opts.state.builderResponseHistory.push({ ticketId: opts.ticket.id, cycle: durableReport.reviewNumber, kind: "remediation", response: fix.response, summary: fixSummary });
         opts.builderSummary = fix.response;
@@ -387,6 +391,8 @@ async function runIsolatedQaOwned(opts) {
             opts.qaRemediationAuthorization = undefined;
             if (!fix.ok)
                 return pauseQaProtocol(opts, "builder-remediation-failed", fix.detail ?? "Builder QA fix failed", fix.outcome === "needs-input" ? "needs-human" : "blocked");
+            if (!consumeRecoveryAfterOwnedFix(opts))
+                return pauseQaProtocol(opts, "builder-remediation-unconfirmed", "Builder remediation needs durable reconciliation before a fresh review", "needs-human");
             const fixSummary = boundedBuilderSummary(fix.summary ?? fix.response ?? fix.detail ?? "Builder reported remediation complete");
             opts.state.builderResponseHistory.push({
                 ticketId: opts.ticket.id,
@@ -1367,6 +1373,22 @@ function markQaRecoveryResolved(opts) {
         db.close();
     }
 }
+function consumeRecoveryAfterOwnedFix(opts) {
+    if (!opts.resumedRecovery)
+        return true;
+    const db = new WorkflowDb(opts.recovery.projectDir);
+    try {
+        if (!db.hasConfirmedQaRemediationForRecheck(opts.recovery.runId, opts.ticket.id))
+            return false;
+        // The validated report led to confirmed source-changing implementation.
+        // Its recovery packet remains durable history, not the next review basis.
+        opts.resumedRecovery = undefined;
+        return true;
+    }
+    finally {
+        db.close();
+    }
+}
 function markQaRecoveryPendingBuilder(opts) {
     markQaRecoveryAction(opts, "builder-remediation-pending");
 }
@@ -1542,10 +1564,7 @@ function validateBoundaryReceipt(receipt, packet, successorHandle) {
         || resource.authoritative !== true || typeof resource.requiredForRecovery !== "boolean")) {
         throw new Error("QA recovery acceptance receipt contains invalid resource metadata");
     }
-    for (const required of ["continuity-checkpoint", "authoritative-run-state", "frozen-qa-action"]) {
-        if (!receipt.resources.some((resource) => resource.label === required))
-            throw new Error(`QA recovery acceptance receipt is missing ${required}`);
-    }
+    assertQaRecoveryHandoffInventory(receipt.resources);
     if (receipt.inventoryDigest !== qaDigest("handoff-inventory", receipt.resources))
         throw new Error("QA recovery acceptance receipt inventory digest mismatch");
     const receiptDb = new WorkflowDb(packet.projectDir);
@@ -1566,6 +1585,13 @@ function validateBoundaryReceipt(receipt, packet, successorHandle) {
         }
     }
 }
+/** Shared invariant for host staging and the actual QA boundary receipt. */
+export function assertQaRecoveryHandoffInventory(resources) {
+    for (const required of ["continuity-checkpoint", "authoritative-run-state", "frozen-qa-action"]) {
+        if (!resources.some(resource => resource.label === required))
+            throw new Error(`QA recovery acceptance receipt is missing ${required}`);
+    }
+}
 function effectiveTurnText(turn) { return turn.cleanedResponse ?? turn.text; }
 const qaTurnBindings = new WeakMap();
 function beginV2Review(opts, source, reviewedSnapshotPath, instruction, handle, attempt) {
@@ -1769,8 +1795,12 @@ async function sendDurableQaTurnOwned(adapter, instruction, events, slot) {
     }
     let result;
     const providerStartedAt = Date.now();
+    // Reading the sealed QA packet is ordinary confined read-only QA work.
+    // Only formatting repair and ownership acceptance are response-only; the
+    // first resource-inspection turn cannot truthfully read with tools disabled.
+    const responseRepair = slot?.includes("correction") || (slot?.includes("acknowledgement") && slot.includes("repair"));
     try {
-        result = await adapter.sendTurn(instruction, slot === "session-initialization" ? { purpose: "initialization", responseOnly: true } : slot?.includes("acknowledgement") || slot?.includes("correction") ? { purpose: "response-repair", responseOnly: true } : undefined);
+        result = await adapter.sendTurn(instruction, slot === "session-initialization" ? { purpose: "initialization", responseOnly: true } : responseRepair ? { purpose: "response-repair", responseOnly: true } : undefined);
     }
     catch (error) {
         const failedDb = new WorkflowDb(binding.projectDir);
@@ -1827,7 +1857,7 @@ async function sendDurableQaTurnOwned(adapter, instruction, events, slot) {
         throw new Error(detail);
     }
     const completedAt = new Date().toISOString();
-    const terminalEventObserved = Boolean(result.turnId
+    const terminalEventObserved = Boolean(result.turnId && result.failure?.dispatchState !== "unknown"
         && events.some((event) => event.kind === "turn-complete" && (event.turnId ?? event.result.turnId) === result.turnId));
     const receiptDb = new WorkflowDb(binding.projectDir);
     try {

package/dist/sessionLifecycle.js

@@ -768,7 +768,7 @@ export class ThresholdCompactionController {
     handoffGeneration() {
         const db = new WorkflowDb(this.options.projectDir);
         try {
-            return db.handoffs(this.options.runId).at(-1)?.generation ?? 0;
+            return db.roleMutationLease(this.options.runId, this.options.role)?.generation ?? 0;
         }
         finally {
             db.close();

package/dist/supervisedStart.js

@@ -3,8 +3,10 @@ import { fileURLToPath } from "node:url";
 import { execFileSync, spawn } from "node:child_process";
 import { closeSync, mkdirSync, openSync } from "node:fs";
 import { join } from "node:path";
+import { hostname } from "node:os";
 import { DurableSupervisor } from "./supervisor.js";
 import { WorkflowDb } from "./workflowDb.js";
+import { processStartIdentity } from "./processIdentity.js";
 import { cancelOwnedRuntimeProbes } from "./runtimeReadiness.js";
 /** Worker IPC is created by the parent; an environment flag alone cannot bypass supervision. */
 export function supervisedRunId() {
@@ -174,6 +176,12 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                     return;
                 try {
                     db.acknowledgeBuildLaunchChild(authority, launch.token, child.pid);
+                    // Record the incarnation before acknowledging the blocked launch gate.
+                    // Any persistence failure follows the existing owned-child cleanup.
+                    db.transitionSupervisor(runId, generation, {
+                        checkpoint: db.getRun(runId)?.checkpoint ?? "preparing", event: "worker_started",
+                        payload: { workerPid: child.pid, processStart: processStartIdentity(child.pid), host: hostname(), generation },
+                    });
                     child.send("rafi-launch-ack", () => { });
                     clearTimeout(startup);
                 }
@@ -228,12 +236,18 @@ export async function superviseStart(projectDir, runId, policy, selection) {
             const result = new Promise(resolve => {
                 child.once("error", error => {
                     clearInterval(watchdog);
+                    exitCode = 1;
                     if (child.pid) {
                         stop();
                         return;
                     } // exit handler owns cleanup and settlement
-                    db.failBuildLaunch(authority, launch.token);
-                    resolve({ kind: "failed", detail: error.message });
+                    try {
+                        db.failBuildLaunch(authority, launch.token);
+                        resolve({ kind: "failed", detail: error.message });
+                    }
+                    catch (failure) {
+                        resolve({ kind: "failed", detail: `${error.message}; launch reconciliation failed: ${String(failure)}` });
+                    }
                 });
                 child.once("exit", async (code, signal) => {
                     clearInterval(watchdog);
@@ -309,7 +323,13 @@ export async function superviseStart(projectDir, runId, policy, selection) {
     process.once("SIGINT", stopInt);
     process.once("SIGTERM", stopTerm);
     try {
-        await supervisor.run();
+        const outcome = await supervisor.run();
+        if (outcome.kind === "failed") {
+            exitCode ||= 1;
+            console.error(`rafi: ${outcome.detail}`);
+        }
+        else if (outcome.kind === "waiting_for_human")
+            exitCode ||= 2;
     }
     finally {
         process.off("SIGINT", stopInt);

package/dist/supervisor.js

@@ -80,6 +80,8 @@ export class DurableSupervisor {
                 if (pending.some(decision => !this.options.policy.continueIndependentTickets || !decision.interruptionId.startsWith("ticket:"))) {
                     state = { ...state, status: "waiting_for_human", workerPid: undefined, heartbeatAt: this.now().toISOString() };
                     saveState();
+                    if (db.getRun(this.options.runId)?.status === "running")
+                        db.transitionSupervisor(this.options.runId, state.workerGeneration, { status: "paused", checkpoint: "waiting-for-human", event: "worker_waiting_for_human" });
                     return { kind: "waiting_for_human" };
                 }
                 const checkpoint = this.options.checkpoint();
@@ -94,6 +96,19 @@ export class DurableSupervisor {
                 this.active = undefined;
                 state = { ...state, workerPid: undefined, heartbeatAt: this.now().toISOString() };
                 if (outcome.kind !== "crashed") {
+                    if (outcome.kind === "failed" && db.getRun(this.options.runId)?.status === "running") {
+                        const eligibility = db.preparationEligibility(this.options.runId);
+                        db.transitionSupervisor(this.options.runId, state.workerGeneration, {
+                            status: eligibility.eligible ? "failed" : "paused",
+                            checkpoint: eligibility.eligible ? "worker-failed" : "worker-reconciliation-required",
+                            event: "worker_exit_recorded", payload: { detail: outcome.detail, reasons: eligibility.reasons },
+                        });
+                    }
+                    else if (db.getRun(this.options.runId)?.status === "running")
+                        db.transitionSupervisor(this.options.runId, state.workerGeneration, {
+                            status: "paused", checkpoint: outcome.kind === "waiting_for_human" && db.pendingHumanDecisions(this.options.runId).length ? "waiting-for-human" : "worker-exited-before-checkpoint",
+                            event: "worker_exit_recorded", payload: { outcome: outcome.kind },
+                        });
                     const status = outcome.kind === "completed" ? "stopped" : outcome.kind === "waiting_for_human" ? "waiting_for_human" : outcome.kind === "failed" ? "failed" : "stopped";
                     state = { ...state, status };
                     saveState();
@@ -111,6 +126,10 @@ export class DurableSupervisor {
                 if (state.checkpointRestarts >= checkpointLimit || state.runRestarts >= runLimit) {
                     state = { ...state, status: "failed" };
                     saveState();
+                    if (db.getRun(this.options.runId)?.status === "running")
+                        db.transitionSupervisor(this.options.runId, state.workerGeneration, {
+                            status: "failed", checkpoint: "worker-restart-budget-exhausted", event: "worker_restart_budget_exhausted", payload: { checkpoint, detail: outcome.detail },
+                        });
                     return { kind: "failed", detail: `worker restart budget exhausted at ${checkpoint}: ${outcome.detail}` };
                 }
                 state = { ...state, checkpointRestarts: state.checkpointRestarts + 1, runRestarts: state.runRestarts + 1 };
@@ -118,9 +137,23 @@ export class DurableSupervisor {
                 await this.sleep(Math.min(10_000, 250 * (2 ** Math.min(5, state.checkpointRestarts - 1))));
             }
             state = { ...state, status: "stopped", stopRequestedAt: this.now().toISOString(), workerPid: undefined };
+            if (db.getRun(this.options.runId)?.status === "running")
+                db.transitionSupervisor(this.options.runId, state.workerGeneration, { status: "paused", checkpoint: "worker-stopped", event: "supervisor_stop_recorded" });
             saveState();
             return { kind: "stopped" };
         }
+        catch (error) {
+            state = { ...state, status: "failed", workerPid: undefined, heartbeatAt: this.now().toISOString() };
+            saveState();
+            if (db.getRun(this.options.runId)?.status === "running") {
+                const eligibility = db.preparationEligibility(this.options.runId);
+                db.transitionSupervisor(this.options.runId, state.workerGeneration, { status: eligibility.eligible ? "failed" : "paused",
+                    checkpoint: eligibility.eligible ? "worker-launch-failed" : "worker-reconciliation-required", event: "worker_launch_failed",
+                    payload: { detail: String(error), reasons: eligibility.reasons },
+                });
+            }
+            throw error;
+        }
         finally {
             clearInterval(heartbeat);
             try {