ai-foreman 1.7.18 → 1.7.19

package/dist/branch/runner.js

@@ -1,3 +1,5 @@
+import { WorkflowReader } from "../workflowReader.js";
+import { buildScopeRevision } from "../buildApproval.js";
 import { beginQaFinalization, completeQaFinalization, verifyPendingQaFinalizationSource, compactWithRetry, runIsolatedQa } from "../qaReview.js";
 import { QaFailureDeliveryService } from "../qaFailureDelivery.js";
 import { Foreman, MARKER_SPEC } from "../foreman.js";
@@ -20,7 +22,20 @@ export function readDeliveryUnitSession(projectDir, unitId) {
     if (!existsSync(path))
         return undefined;
     try {
-        return JSON.parse(readFileSync(path, "utf8"));
+        const cached = JSON.parse(readFileSync(path, "utf8"));
+        const reader = new WorkflowReader(projectDir);
+        try {
+            const known = reader.branchResumeSessions(false);
+            const active = reader.branchResumeSessions().filter(row => row.deliveryUnitId === unitId && row.worktreePath === cached.worktreePath && row.branch === cached.branch).at(-1);
+            if (active)
+                return { ...cached, sessionId: active.sessionId, sessionRef: active.sessionRef, ticket: active.ticket };
+            if (known.some(row => row.deliveryUnitId === unitId) || reader.buildRuns().length || (cached.runId && reader.getRun(cached.runId)))
+                return undefined;
+            return cached;
+        }
+        finally {
+            reader.close();
+        }
     }
     catch {
         return undefined;
@@ -108,7 +123,40 @@ export async function runBranchPlan(opts) {
     }
     if (opts.plan.issues.some((issue) => issue.blocking))
         return summaries;
-    for (const node of orderNodes(opts.plan.nodes)) {
+    const pendingNodes = orderNodes(opts.plan.nodes);
+    while (true) {
+        const decisionDb = new WorkflowDb(opts.projectDir);
+        const answered = decisionDb.answeredTicketDecisions(opts.runId, buildScopeRevision(opts.projectDir));
+        decisionDb.close();
+        for (let index = summaries.length - 1; index >= 0; index--) {
+            const summary = summaries[index];
+            if (summary.buildStatus === "done")
+                continue;
+            const candidate = opts.plan.nodes.find(item => item.ticket.id === summary.ticket);
+            if (!candidate || pendingNodes.some(item => item.ticket.id === candidate.ticket.id))
+                continue;
+            const hasAnswer = answered.some(decision => decision.interruptionId === `ticket:${candidate.ticket.id}`);
+            const dependencyDeferred = summary.detail === "deferred because a dependency or shared delivery unit is blocked";
+            const dependenciesReady = candidate.dependencies.every(id => successfulBranches.has(id));
+            const sharedReady = !summaries.some(prior => prior.ticket !== candidate.ticket.id && prior.buildStatus !== "done" && prior.detail !== "deferred because a dependency or shared delivery unit is blocked" && opts.plan.nodes.some(item => item.ticket.id === prior.ticket && item.deliveryUnitId && item.deliveryUnitId === candidate.deliveryUnitId));
+            if ((hasAnswer || dependencyDeferred) && dependenciesReady && sharedReady) {
+                summaries.splice(index, 1);
+                pendingNodes.push(candidate);
+            }
+        }
+        const node = pendingNodes.shift();
+        if (!node)
+            break;
+        const continuations = answered.filter(decision => decision.interruptionId === `ticket:${node.ticket.id}`);
+        const continuationSuffix = continuations.length ? `:answers:${continuations.map(decision => decision.decisionId).join(",")}` : "";
+        const blocked = summaries.filter(summary => summary.buildStatus !== "done");
+        if (blocked.length && opts.continueIndependentTickets === false)
+            break;
+        if (blocked.some(summary => node.dependencies.includes(summary.ticket)
+            || opts.plan.nodes.some(prior => prior.ticket.id === summary.ticket && prior.deliveryUnitId && prior.deliveryUnitId === node.deliveryUnitId))) {
+            summaries.push(summaryFor(node, "blocked", "deferred because a dependency or shared delivery unit is blocked"));
+            continue;
+        }
         const protocolDb = new WorkflowDb(opts.projectDir);
         const protocolHead = protocolDb.qaTicketHead(opts.runId, node.ticket.id);
         const finalizationRecovery = protocolHead.state === "finalizing";
@@ -229,7 +277,10 @@ export async function runBranchPlan(opts) {
             dependencies: node.dependencies,
         });
         workflowCheckpoint(opts.projectDir, opts.runId, "builder-before", node.ticket.id, { branch: node.branch, worktree: node.worktreePath });
-        const resumeSession = opts.resumeSessions?.get(node.ticket.id);
+        const continuationDb = new WorkflowDb(opts.projectDir);
+        const continuationSession = continuations.length ? continuationDb.branchResumeSession(opts.runId, node.ticket.id) : undefined;
+        continuationDb.close();
+        const resumeSession = continuationSession ?? opts.resumeSessions?.get(node.ticket.id);
         const worktreePath = resumeSession?.worktreePath
             ?? (sharedUnit ? findWorktreeForBranch(opts.projectDir, node.branch) : undefined)
             ?? await observeNode(opts, node, "git", "creating ticket worktree", () => createTicketWorktree(opts.projectDir, opts.runId, node.branch, node.baseBranch));
@@ -248,7 +299,7 @@ export async function runBranchPlan(opts) {
                 });
             }
             if (!qaOnlyRecovery)
-                journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:in-progress`, { ticket: node.ticket.id, status: "in_progress" }, () => {
+                journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:in-progress${continuationSuffix}`, { ticket: node.ticket.id, status: "in_progress" }, () => {
                     if (resumeSession)
                         cmdUnblock(opts.projectDir, node.ticket.id, { actor: "foreman", summary: `Reopened by explicit branch recovery for ${node.branch}` });
                     cmdUpdate(opts.projectDir, node.ticket.id, {
@@ -256,7 +307,9 @@ export async function runBranchPlan(opts) {
                         summary: resumeSession ? `Resuming branch ${node.branch}` : `Starting branch ${node.branch}`,
                     });
                 });
-            const ticketInstruction = resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths);
+            let ticketInstruction = resumeSession ? buildBranchTicketResumeInstruction(node, opts.trackerPaths) : buildBranchTicketInstruction(node, opts.trackerPaths);
+            if (continuations.length)
+                ticketInstruction += "\n\nScoped answers authorizing this ticket continuation:\n" + continuations.map(decision => `${decision.prompt}\nAnswer: ${decision.answer ?? decision.selectedChoiceId}`).join("\n");
             // Reattach the predecessor even for a `fresh` strategy so the host can
             // publish and validate a cumulative handoff before creating its successor.
             const sameWorktreeStream = builderStream && canonical(builderStream.worktreePath) === canonical(worktreePath) ? builderStream : undefined;
@@ -283,8 +336,26 @@ export async function runBranchPlan(opts) {
             if (!qaOnlyRecovery)
                 builderWorkSessions += 1;
             viewer = opts.observeBuilder?.(builder);
-            const foreman = new Foreman(builder, opts.log, { desktop: opts.notificationsEnabled, terminalBell: opts.terminalBellEnabled ?? true }, opts.qaEnabled, 3, undefined, undefined, undefined, opts.qaSessionStrategy ?? "compact", undefined, opts.builderSessionStrategy ?? "compact", undefined, opts.beforeBuilderTurn ? (adapter, action) => opts.beforeBuilderTurn(adapter, action, worktreePath) : undefined, undefined, undefined, undefined, async (adapter) => opts.observeBuilderNativeCompactions?.(adapter, worktreePath));
-            const turn = () => foreman.runInstruction(ticketInstruction);
+            const foreman = new Foreman(builder, opts.log, { desktop: opts.notificationsEnabled, terminalBell: opts.terminalBellEnabled ?? true }, opts.qaEnabled, 3, opts.projectDir, undefined, undefined, opts.qaSessionStrategy ?? "compact", undefined, opts.builderSessionStrategy ?? "compact", undefined, opts.beforeBuilderTurn ? (adapter, action) => opts.beforeBuilderTurn(adapter, action, worktreePath) : undefined, undefined, undefined, undefined, async (adapter) => opts.observeBuilderNativeCompactions?.(adapter, worktreePath), opts.observer, undefined, false, undefined, undefined, opts.runId, opts.continueIndependentTickets ?? true, node.ticket.id);
+            const turn = async () => {
+                const db = new WorkflowDb(opts.projectDir);
+                try {
+                    db.atomic(() => {
+                        for (const decision of continuations) {
+                            const key = `decision-continuation:${decision.decisionId}`;
+                            db.planOperation({ runId: opts.runId, idempotencyKey: key, kind: "decision-continuation", intent: { decisionId: decision.decisionId, ticketId: node.ticket.id } });
+                            db.updateOperation(key, "in_progress");
+                        }
+                    });
+                    const response = await foreman.runInstruction(ticketInstruction);
+                    for (const decision of continuations)
+                        db.updateOperation(`decision-continuation:${decision.decisionId}`, response.result.failure?.dispatchState === "unknown" ? "uncertain" : "confirmed", { result: { isError: response.result.isError } });
+                    return response;
+                }
+                finally {
+                    db.close();
+                }
+            };
             const { result, status } = qaOnlyRecovery
                 ? { result: { text: "Exact QA-only recovery; Builder work dispatch was intentionally skipped.", isError: false, numTurns: 0, costUsd: 0 }, status: { kind: "done", summary: "Resuming exact QA boundary", ticket: node.ticket.id } }
                 : opts.observer
@@ -334,7 +405,7 @@ export async function runBranchPlan(opts) {
                 if (node.deliveryUnitId) {
                     const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
                     mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
-                    writeFileSync(path, `${JSON.stringify({ unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
+                    writeFileSync(path, `${JSON.stringify({ runId: opts.runId, unitId: node.deliveryUnitId, branch: node.branch, worktreePath, sessionId, sessionRef: builder.sessionRef?.(), ticket: node.ticket.id }, null, 2)}\n`, "utf8");
                 }
             }
             opts.log.write("step", {
@@ -353,7 +424,7 @@ export async function runBranchPlan(opts) {
             }
             if (status.kind !== "done" && status.kind !== "plan_complete") {
                 const detail = status.reason ?? status.error ?? `builder emitted ${status.kind}`;
-                journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:builder-block`, { ticket: node.ticket.id, status: "blocked", detail }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: detail, actor: "foreman" }));
+                journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:builder-block${continuationSuffix}`, { ticket: node.ticket.id, status: "blocked", detail }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: detail, actor: "foreman" }));
                 summaries.push(summaryFor(node, status.kind === "blocked" ? "blocked" : "needs-human", detail));
                 continue;
             }
@@ -408,10 +479,18 @@ export async function runBranchPlan(opts) {
                                 const sessionRef = typeof session === "string" ? undefined : session;
                                 const sessionId = typeof session === "string" ? session : session.sessionId;
                                 builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
+                                const resumeDb = new WorkflowDb(opts.projectDir);
+                                try {
+                                    resumeDb.recordBranchResumeSession(opts.runId, { ticket: node.ticket.id, branch: node.branch, base: node.baseBranch, worktreePath, sessionId, sessionRef, logPath: "structured-recovery", deliveryUnitId: node.deliveryUnitId });
+                                }
+                                finally {
+                                    resumeDb.close();
+                                }
                                 opts.recordBuilderSession?.(sessionRef ?? sessionId, node.ticket.id, worktreePath);
                                 workflowCheckpoint(opts.projectDir, opts.runId, "builder-session-scoped", node.ticket.id, { sessionId, sessionRef, worktree: worktreePath, branch: node.branch });
                             },
                         });
+                        opts.log.write("qa-fix", { ticket: node.ticket.id, outcome: result.outcome, operationId: result.operationId, turnRecordId: result.turnRecordId, detail: result.detail });
                         return result;
                     },
                     onNonconvergence: opts.qaNonconvergence,
@@ -431,7 +510,7 @@ export async function runBranchPlan(opts) {
                 workflowCheckpoint(opts.projectDir, opts.runId, "qa-after", node.ticket.id, { outcome: qa.outcome, detail: qa.detail });
                 if (qa.outcome !== "passed" && qa.outcome !== "waived") {
                     const detail = qa.detail ?? "QA did not pass";
-                    journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:qa-block`, { ticket: node.ticket.id, status: "blocked", detail }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: detail, actor: "foreman" }));
+                    journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:qa-block${continuationSuffix}`, { ticket: node.ticket.id, status: "blocked", detail }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: detail, actor: "foreman" }));
                     summaries.push(summaryFor(node, qa.outcome === "blocked" ? "blocked" : "needs-human", detail));
                     continue;
                 }
@@ -696,7 +775,7 @@ export async function runBranchPlan(opts) {
                     : "builder_error";
             opts.log.write("branch-issue", { ticket: node.ticket.id, code, message, blocking: false });
             notifyIssue(opts.notificationsEnabled, `${node.ticket.id}: ${message}`);
-            journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:runtime-block`, { ticket: node.ticket.id, status: "blocked", detail: message }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: message, actor: "foreman" }));
+            journalTracker(opts.projectDir, opts.runId, `${opts.runId}:tracker-update:${node.ticket.id}:runtime-block${continuationSuffix}`, { ticket: node.ticket.id, status: "blocked", detail: message }, () => cmdBlock(opts.projectDir, node.ticket.id, { summary: message, actor: "foreman" }));
             summaries.push(summaryFor(node, "blocked", message));
         }
         finally {

package/dist/buildApproval.d.ts

@@ -0,0 +1,9 @@
+/** Reuse only source-bound approval. Ambiguous legacy provenance still asks. */
+export declare function approvedBuildScope(projectDir: string, ticketIds?: readonly string[]): {
+    approved: boolean;
+    reason: string;
+    digest?: string;
+};
+export declare function requiresBuildApproval(projectDir: string, ticketIds: readonly string[] | undefined, explicitYes: boolean, consequences?: Record<string, unknown>): boolean;
+/** Bind decisions to current files so an old answer cannot approve a changed scope. */
+export declare function buildScopeRevision(projectDir: string, consequences?: Record<string, unknown>): string;

package/dist/buildApproval.js

@@ -0,0 +1,126 @@
+import { loadDeliveryConfig, normalizeDeliveryConfig } from "./tickets/delivery.js";
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse } from "yaml";
+import { WorkflowDb } from "./workflowDb.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
+import { loadTickets } from "./tickets/ticketLoader.js";
+import { StateDb } from "./tickets/stateDb.js";
+function canonical(value) {
+    const normalize = (entry) => Array.isArray(entry) ? entry.map(normalize) : entry && typeof entry === "object"
+        ? Object.fromEntries(Object.entries(entry).sort(([a], [b]) => a.localeCompare(b)).map(([key, val]) => [key, normalize(val)])) : entry;
+    return JSON.stringify(normalize(value));
+}
+function material(ticket) {
+    return { id: ticket.id, plan_ref: ticket.plan_ref, title: ticket.title, summary: ticket.summary, acceptance: ticket.acceptance,
+        required_tests: ticket.required_tests, depends_on: ticket.depends_on, likely_files: ticket.likely_files, rollback: ticket.rollback, source_refs: ticket.source_refs };
+}
+/** Reuse only source-bound approval. Ambiguous legacy provenance still asks. */
+export function approvedBuildScope(projectDir, ticketIds) {
+    try {
+        const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+        const all = loadTickets(paths.tickets);
+        const state = new StateDb(paths.stateDb);
+        let tickets;
+        try {
+            tickets = ticketIds ? all.filter(ticket => ticketIds.includes(ticket.id)) : all.filter(ticket => !["done", "obsolete", "cancelled", "canceled"].includes(state.getState(ticket.id)?.status ?? "planned"));
+        }
+        finally {
+            state.close();
+        }
+        if (!tickets.length || (ticketIds && tickets.length !== new Set(ticketIds).size) || tickets.some(ticket => !ticket.plan_ref))
+            return { approved: false, reason: "selected tickets lack approved plan provenance" };
+        const db = new WorkflowDb(projectDir);
+        try {
+            const approvals = db.completedPlanApprovals();
+            const definitions = db.approvedPopulationDefinitions();
+            for (const ticket of tickets) {
+                const ref = ticket.plan_ref;
+                const receipt = approvals.find(item => item.planId === ref.plan_id && item.revision === ref.revision);
+                if (!receipt)
+                    return { approved: false, reason: `no stored approval for ${ticket.id}` };
+                const config = parse(readFileSync(join(projectDir, "rafi-config.yaml"), "utf8"));
+                const plan = JSON.parse(readFileSync(join(projectDir, config.docs?.root ?? "docs", "rafi-plan.json"), "utf8"));
+                const digest = createHash("sha256").update(canonical({ ...plan, content_digest: "" })).digest("hex");
+                if (plan.plan_id !== ref.plan_id || plan.revision !== ref.revision || digest !== plan.content_digest || digest !== receipt.digest)
+                    return { approved: false, reason: "approved plan revision or digest changed" };
+                const approved = definitions.find(item => item.id === ticket.id && canonical(item.plan_ref) === canonical(ref));
+                // Older populations have no immutable definition receipt. Only an exact
+                // match to the digested approved slice is safe to reuse automatically.
+                const slice = plan.slices?.find((item) => item.slice_ref === ref.slice_ref);
+                const ids = new Map(all.filter(item => item.plan_ref?.plan_id === ref.plan_id && item.plan_ref.revision === ref.revision).map(item => [item.plan_ref.slice_ref, item.id]));
+                const legacy = slice && !ticket.rollback ? { ...ticket, title: slice.title, summary: slice.summary,
+                    acceptance: slice.acceptance, required_tests: slice.required_tests, likely_files: slice.likely_files,
+                    depends_on: (slice.depends_on ?? []).map((id) => ids.get(id)),
+                    source_refs: slice.source_refs?.map((source) => ({ source: source.source_id, item: source.item ?? "document", source_id: source.source_id, fingerprint: source.fingerprint, ...(source.url !== undefined ? { url: source.url } : {}), ...(source.note !== undefined ? { note: source.note } : {}) })) } : undefined;
+                if (canonical(material(approved ?? legacy ?? {})) !== canonical(material(ticket)))
+                    return { approved: false, reason: `material ticket changes or missing immutable approval for ${ticket.id}` };
+                const actualDelivery = loadDeliveryConfig(projectDir);
+                if (actualDelivery?.units.length && !Array.isArray(plan.delivery_units))
+                    return { approved: false, reason: "delivery configuration has no approved provenance" };
+                if (Array.isArray(plan.delivery_units) && (plan.delivery_units.length || actualDelivery?.units.length)) {
+                    const ids = new Map(all.filter(item => item.plan_ref?.plan_id === ref.plan_id).map(item => [item.plan_ref.slice_ref, item.id]));
+                    const expected = normalizeDeliveryConfig({ version: 1, plan: { plan_id: plan.plan_id, revision: plan.revision },
+                        units: plan.delivery_units.map((unit) => ({ ...unit, tickets: unit.slice_refs.map(slice => ids.get(slice)) })),
+                        stacks: (plan.stacks ?? []).map((stack) => ({ id: stack.stack_id, name: stack.name, units: stack.units, status: "planned" })) });
+                    const actual = loadDeliveryConfig(projectDir);
+                    if (!actual || canonical(actual.units) !== canonical(expected.units))
+                        return { approved: false, reason: "approved delivery consequences changed" };
+                }
+                const decisions = receipt.decisionReceipt;
+                if (!decisions || decisions.planDigest !== digest || decisions.workMode !== config.tickets?.build?.branch_strategy || decisions.branchPrefix !== config.tickets?.build?.branch_prefix)
+                    return { approved: false, reason: "approved workflow consequences changed" };
+            }
+            return { approved: true, reason: "unchanged approved plan and ticket definitions", digest: createHash("sha256").update(canonical(tickets.map(material))).digest("hex") };
+        }
+        finally {
+            db.close();
+        }
+    }
+    catch {
+        return { approved: false, reason: "approval evidence unavailable" };
+    }
+}
+export function requiresBuildApproval(projectDir, ticketIds, explicitYes, consequences) {
+    const scope = approvedBuildScope(projectDir, ticketIds);
+    let changedConsequences = false;
+    if (consequences) {
+        try {
+            const saved = parse(readFileSync(join(projectDir, "rafi-config.yaml"), "utf8"))?.tickets?.build ?? {};
+            changedConsequences = Object.entries(consequences).some(([key, value]) => value !== undefined && canonical(value) !== canonical(saved[key] ?? { completion: "none", branch_strategy: "current", branch_prefix: "feature", merge_method: "squash", pr_ready: false }[key]));
+        }
+        catch {
+            changedConsequences = true;
+        }
+    }
+    if (scope.approved && !changedConsequences)
+        return false;
+    if (!explicitYes)
+        return true;
+    const db = new WorkflowDb(projectDir);
+    try {
+        return db.completedPlanApprovals().length > 0;
+    }
+    finally {
+        db.close();
+    }
+}
+/** Bind decisions to current files so an old answer cannot approve a changed scope. */
+export function buildScopeRevision(projectDir, consequences) {
+    const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+    let docsRoot = "docs";
+    try {
+        docsRoot = parse(readFileSync(join(projectDir, "rafi-config.yaml"), "utf8"))?.docs?.root ?? docsRoot;
+    }
+    catch { /* unavailable config changes the fingerprint below */ }
+    const contents = [join(projectDir, docsRoot, "rafi-plan.json"), paths.tickets, join(projectDir, "rafi-config.yaml"), join(projectDir, ".tickets/delivery.yaml")].map(path => {
+        try {
+            return readFileSync(path, "utf8");
+        }
+        catch {
+            return "unavailable";
+        }
+    });
+    return createHash("sha256").update(JSON.stringify([contents, consequences])).digest("hex");
+}

package/dist/buildRuns.js

@@ -52,7 +52,7 @@ export function createBuildRun(input) {
         phase: "created",
         qaEnabled: input.qaEnabled ?? Boolean(input.qa),
         recoveryAttempts: [],
-        supervisor: { status: frozenPolicy.supervisorEnabled ? "starting" : "disabled", generation: 0, workerGeneration: 0, checkpointRestarts: 0, runRestarts: 0 },
+        supervisor: { status: frozenPolicy.supervisorEnabled ? "stopped" : "disabled", generation: 0, workerGeneration: 0, checkpointRestarts: 0, runRestarts: 0 },
         pendingDecisions: [],
         deferredTickets: [],
         runDecisions: input.runDecisions,
@@ -75,8 +75,8 @@ export function resumeBuildRun(projectDir, runId, patch, now = new Date()) {
     let existing = readBuildRuns(projectDir).find((run) => run.runId === runId);
     if (!existing)
         throw new Error(`recoverable build run not found: ${runId}`);
-    if (existing.status === "completed")
-        throw new Error(`build run ${runId} is already complete`);
+    if (existing.status === "completed" || existing.status === "superseded")
+        throw new Error(`build run ${runId} is ${existing.status} and cannot resume`);
     const workflow = new WorkflowDb(projectDir);
     try {
         const held = workflow.currentLease();
@@ -96,7 +96,7 @@ export function resumeBuildRun(projectDir, runId, patch, now = new Date()) {
             }
         }
         existing = readBuildRuns(projectDir).find((run) => run.runId === runId);
-        if (!existing || existing.status === "completed") {
+        if (!existing || existing.status === "completed" || existing.status === "superseded") {
             const lease = workflow.currentLease();
             if (lease?.runId === runId && lease.pid === process.pid)
                 workflow.releaseLease(lease, now);
@@ -140,33 +140,50 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
         updatedAt: now.toISOString(),
     };
     const workflow = new WorkflowDb(projectDir);
+    const target = join(directory, `${run.runId}.json`);
+    let publicationId;
     try {
-        const frozenPolicy = workflow.freezeAutonomyPolicy(next.runId, next.frozenPolicy, now);
-        next = { ...next, frozenPolicy, recoveryAttempts: workflow.recoveryAttempts(next.runId), pendingDecisions: workflow.pendingHumanDecisions(next.runId), supervisor: workflow.supervisorState(next.runId) ?? next.supervisor };
-        const existing = workflow.getRun(next.runId);
-        if (!existing)
-            workflow.createRun({
-                runId: next.runId, kind: "build", checkpoint: next.checkpoint,
-                originalWork: { tickets: next.tickets, deliveryUnit: next.deliveryUnit, branchMode: next.branchMode },
-                remainingWork: { tickets: remainingTickets(next) }, state: next,
-            }, now);
-        else
-            workflow.transition(next.runId, {
-                status: workflowStatus(next.status), checkpoint: next.checkpoint,
-                remainingWork: { tickets: remainingTickets(next) }, state: next, event: "build_snapshot",
-            }, now);
-        if (next.builder?.sessionId)
-            workflow.recordSession(next.runId, "builder", "builder", latestSessionBinding(next.sessionBindings, "builder", next.builder.sessionId) ?? next.builder.sessionId, "checkpoint", next.builder.settings, now);
-        if (next.qa?.sessionId)
-            workflow.recordSession(next.runId, "qa", "qa", latestSessionBinding(next.sessionBindings, "qa", next.qa.sessionId) ?? next.qa.sessionId, "checkpoint", next.qa.settings, now);
+        workflow.atomic(() => {
+            const frozenPolicy = workflow.freezeAutonomyPolicy(next.runId, next.frozenPolicy, now);
+            next = { ...next, frozenPolicy, recoveryAttempts: workflow.recoveryAttempts(next.runId), pendingDecisions: workflow.pendingHumanDecisions(next.runId), supervisor: workflow.supervisorState(next.runId) ?? next.supervisor };
+            const existing = workflow.getRun(next.runId);
+            if (existing?.status === "superseded" && next.status !== "superseded")
+                throw new Error("cannot rewrite a superseded build run as active");
+            if (!existing)
+                workflow.createRun({
+                    runId: next.runId, kind: "build", checkpoint: next.checkpoint,
+                    originalWork: { tickets: next.tickets, deliveryUnit: next.deliveryUnit, branchMode: next.branchMode },
+                    remainingWork: { tickets: remainingTickets(next) }, state: next,
+                }, now);
+            else
+                workflow.transition(next.runId, {
+                    status: workflowStatus(next.status), checkpoint: next.checkpoint,
+                    remainingWork: { tickets: remainingTickets(next) }, state: next, event: "build_snapshot",
+                }, now);
+            if (next.builder?.sessionId)
+                workflow.recordSession(next.runId, "builder", "builder", latestSessionBinding(next.sessionBindings, "builder", next.builder.sessionId) ?? next.builder.sessionId, "checkpoint", next.builder.settings, now);
+            if (next.qa?.sessionId)
+                workflow.recordSession(next.runId, "qa", "qa", latestSessionBinding(next.sessionBindings, "qa", next.qa.sessionId) ?? next.qa.sessionId, "checkpoint", next.qa.settings, now);
+            publicationId = workflow.beginPublication(next.runId, { operation: "build-run-projection", target,
+                revision: createHash("sha256").update(JSON.stringify(next)).digest("hex"), updatedAt: next.updatedAt }, {}, now).transactionId;
+        });
+        const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+        writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+        renameSync(temp, target);
+        workflow.atomic(() => {
+            workflow.updatePublication(publicationId, "committed", now);
+            // Publishing the latest authoritative revision also reconciles any older
+            // interrupted publication of this same projection; never write old bytes.
+            for (const pending of workflow.incompletePublications()) {
+                const intent = pending.intent;
+                if (pending.runId === next.runId && intent.operation === "build-run-projection" && intent.target === target)
+                    workflow.updatePublication(pending.transactionId, "committed", now);
+            }
+        });
     }
     finally {
         workflow.close();
     }
-    const target = join(directory, `${run.runId}.json`);
-    const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
-    writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-    renameSync(temp, target);
     return next;
 }
 export function checkpointBuildRun(projectDir, run, checkpoint, patch = {}) {
@@ -251,16 +268,37 @@ export function completeBuildRun(projectDir, run, now = new Date()) {
 }
 export function readBuildRuns(projectDir) {
     const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
-    if (!existsSync(directory))
-        return [];
-    const workflow = existsSync(join(resolve(projectDir), ".rafi", "recovery.sqlite3")) ? new WorkflowDb(projectDir) : undefined;
-    const runs = readdirSync(directory).filter((name) => name.endsWith(".json")).flatMap((name) => {
+    const workflow = new WorkflowReader(projectDir);
+    const candidates = new Map();
+    if (existsSync(directory))
+        for (const name of readdirSync(directory).filter(name => name.endsWith(".json"))) {
+            try {
+                const value = JSON.parse(readFileSync(join(directory, name), "utf8"));
+                candidates.set(value.runId, value);
+            }
+            catch { /* authoritative DB state can repair an absent or partial projection */ }
+        }
+    for (const stored of workflow.buildRuns()) {
+        const value = stored.state;
+        if (value?.runId)
+            candidates.set(value.runId, value);
+    }
+    const runs = [...candidates.values()].flatMap((projection) => {
         try {
-            const projection = JSON.parse(readFileSync(join(directory, name), "utf8"));
             validateBuildRun(projection);
             const authoritative = workflow?.getRun(projection.runId)?.state;
             const run = authoritative?.runId ? authoritative : projection;
-            const upgraded = upgradeBuildRun(run, projectDir);
+            let upgraded = upgradeBuildRun(run, projectDir);
+            if (workflow?.getRun(run.runId)?.status === "superseded")
+                upgraded = { ...upgraded, status: "superseded" };
+            if (!["completed", "superseded", "cancelled"].includes(workflow?.getRun(run.runId)?.status ?? "")) {
+                for (const role of ["builder", "qa"]) {
+                    const lease = workflow?.roleMutationLease(run.runId, role);
+                    const ref = lease?.sessionRef;
+                    if (ref && lease.generation > 0 && upgraded[role])
+                        upgraded = { ...upgraded, [role]: { ...upgraded[role], sessionId: ref.sessionId }, sessionBindings: upsertSessionBinding(upgraded.sessionBindings, ref) };
+                }
+            }
             return [{ ...upgraded, frozenPolicy: workflow?.autonomyPolicy(run.runId) ?? upgraded.frozenPolicy, recoveryAttempts: workflow?.recoveryAttempts(run.runId) ?? upgraded.recoveryAttempts, pendingDecisions: workflow?.pendingHumanDecisions(run.runId) ?? upgraded.pendingDecisions, supervisor: workflow?.supervisorState(run.runId) ?? upgraded.supervisor }];
         }
         catch {

package/dist/cli/recovery.js

@@ -1,3 +1,4 @@
+import { isLiveProcessIdentity } from "../processIdentity.js";
 import { Command } from "commander";
 import { resolve } from "node:path";
 import { readBuildRuns } from "../buildRuns.js";
@@ -35,10 +36,11 @@ export function buildDecideCommand() {
         .requiredOption("--run <id>", "build run ID")
         .requiredOption("--decision <id>", "decision ID")
         .requiredOption("--choice <id>", "stable choice ID")
+        .option("--answer <text>", "actual answer to a scoped QA handback question")
         .action((project, opts) => {
         const db = new WorkflowDb(resolve(project));
         try {
-            const decision = db.answerHumanDecision(opts.run, opts.decision, opts.choice);
+            const decision = db.answerHumanDecision(opts.run, opts.decision, opts.choice, new Date(), opts.answer);
             console.log(`rafi: recorded ${decision.decisionId}=${opts.choice}`);
         }
         finally {
@@ -57,20 +59,14 @@ export function buildStopCommand() {
             const state = db.supervisorState(opts.run);
             if (!state)
                 throw new Error(`supervisor state not found for run ${opts.run}`);
+            if (!state.pid || !state.processStart || !isLiveProcessIdentity(state.pid, state.processStart))
+                throw new Error("supervisor process identity cannot be verified; refusing to signal a potentially reused PID");
             const next = { ...state, status: "stopping", stopRequestedAt: new Date().toISOString() };
             db.putSupervisorState(opts.run, next);
-            if (state.workerPid) {
-                try {
-                    process.kill(state.workerPid, "SIGTERM");
-                }
-                catch { /* stale worker */ }
-            }
-            if (state.pid && state.pid !== process.pid) {
-                try {
-                    process.kill(state.pid, "SIGTERM");
-                }
-                catch { /* stale supervisor */ }
-            }
+            // The verified parent owns child cleanup; raw persisted worker PIDs may
+            // have been reused and must never be signalled independently.
+            if (state.pid !== process.pid)
+                process.kill(state.pid, "SIGTERM");
             console.log(`rafi: stop requested for ${opts.run}`);
         }
         finally {

package/dist/cli/runtimeAuthPrompt.d.ts

@@ -7,6 +7,13 @@ export interface RuntimeCommandRecoveryContext {
 }
 export interface RuntimeReadyForCommandOptions {
     label: string;
+    timeoutMs?: number;
+    durable?: {
+        projectDir: string;
+        runId: string;
+        scopeRevision: string;
+    };
+    onTrace?: import("../runtimeReadiness.js").ProbeRuntimeOptions["onTrace"];
     yes?: boolean;
     allowSwitch?: boolean;
     model?: string | undefined;

package/dist/cli/runtimeAuthPrompt.js

@@ -4,11 +4,14 @@ import { checkRuntimeReady, RuntimeAuthError, runtimeCommandLabel, } from "../ru
 import { resolveExecutablePath } from "../runtimeReadiness.js";
 import { otherRuntime, runtimeDisplayName } from "./runtimeSelection.js";
 import { currentActivity } from "../activity.js";
+import { durableHumanDecision } from "../humanDecision.js";
+import { WorkflowDb } from "../workflowDb.js";
+import { createHash } from "node:crypto";
 export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrOptions) {
     const opts = typeof labelOrOptions === "string"
         ? { label: labelOrOptions }
         : labelOrOptions;
-    const check = opts.check ?? checkRuntimeReady;
+    const check = opts.check ?? ((projectDir, runtime) => checkRuntimeReady(projectDir, runtime, { onTrace: opts.onTrace, timeoutMs: opts.timeoutMs }));
     const checkClaudeSdk = opts.checkClaudeSdk ?? requireClaudeSDK;
     const allowSwitch = opts.allowSwitch !== false;
     const nonInteractive = !opts.choose && (Boolean(opts.yes) || !process.stdin.isTTY || !process.stdout.isTTY);
@@ -31,13 +34,15 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
                     stderr: err instanceof Error ? err.message : String(err),
                     cause: err,
                 });
-            if (nonInteractive) {
+            if (nonInteractive && !opts.durable) {
                 throw failure;
             }
             const fallbackRuntime = otherRuntime(runtime);
-            const choice = opts.choose
-                ? await opts.choose(failure, { otherRuntime: fallbackRuntime, allowSwitch })
-                : await promptRuntimeRecovery(failure, opts.label, fallbackRuntime, allowSwitch);
+            const choice = opts.durable && !opts.choose
+                ? await durableRuntimeRecovery(opts.durable, failure, opts.label, fallbackRuntime, allowSwitch)
+                : opts.choose
+                    ? await opts.choose(failure, { otherRuntime: fallbackRuntime, allowSwitch })
+                    : await promptRuntimeRecovery(failure, opts.label, fallbackRuntime, allowSwitch);
             if (choice === "retry") {
                 currentActivity()?.note(`rafi: retrying ${runtime} readiness check`);
                 continue;
@@ -72,6 +77,8 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
                 }
             }
             if (choice === "cancel") {
+                if (opts.durable)
+                    throw failure;
                 console.log("foreman: cancelled");
                 process.exit(0);
             }
@@ -79,6 +86,34 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
         }
     }
 }
+async function durableRuntimeRecovery(scope, failure, label, fallbackRuntime, allowSwitch) {
+    const db = new WorkflowDb(scope.projectDir);
+    try {
+        db.ensureRun(scope.runId);
+        const identity = createHash("sha256").update(JSON.stringify([scope.scopeRevision, failure.runtime, label, allowSwitch])).digest("hex");
+        const prefix = `runtime-recovery:${scope.runId}:${identity}:`;
+        const attempt = db.operations(scope.runId).filter(item => item.kind === "runtime-recovery-decision" && item.idempotencyKey.startsWith(prefix)).length;
+        const key = `${prefix}${attempt}`;
+        console.error(failure.message);
+        const choice = await durableHumanDecision({
+            projectDir: scope.projectDir, runId: scope.runId, key,
+            prompt: `${runtimeCommandLabel(failure.runtime)} is not ready for ${label}. Choose how to recover.`,
+            choices: [{ id: "retry", label: "Fix manually and retry" }, ...(allowSwitch ? [{ id: "switch", label: `Use ${runtimeDisplayName(fallbackRuntime)}` }] : []), { id: "cancel", label: "Stop and preserve work" }],
+            operation: () => promptRuntimeRecovery(failure, label, fallbackRuntime, allowSwitch),
+        });
+        // Spend this authorization before executing it. A later failure must never
+        // reuse an old retry answer and turn a human decision into an infinite loop.
+        db.atomic(() => {
+            db.planOperation({ runId: scope.runId, idempotencyKey: key, kind: "runtime-recovery-decision", intent: { choice } });
+            db.updateOperation(key, "in_progress");
+            db.updateOperation(key, "confirmed", { result: { choice } });
+        });
+        return choice;
+    }
+    finally {
+        db.close();
+    }
+}
 async function promptRuntimeRecovery(err, label, fallbackRuntime, allowSwitch) {
     log.error(err.message);
     log.info("Cancel stops this command and keeps project files in place. It does not uninstall packages, delete generated files, or change configuration.");