ai-foreman 1.7.25 → 1.7.26

package/dist/adapters/fastMode.js

@@ -0,0 +1,9 @@
+/** Only explicit speed-option rejection permits a same-session retry. Auth,
+ * generic model failures, timeouts, and uncertain transport failures do not. */
+export function isFastModeUnavailable(detail) {
+    return /(?:fast(?:[ _-]mode)?|service[ _-]tier|speed\s*[=:]\s*["']?fast)[\s\S]{0,160}(?:not supported|unsupported|not available|unavailable|not enabled|disabled|not allowed|requires|invalid|unrecognized|unknown)|(?:not supported|unsupported|not available|unavailable|invalid|unrecognized|unknown)[\s\S]{0,100}(?:--fast|fast[ _-]mode|service[ _-]tier)/i.test(detail);
+}
+export function reportFastModeUnavailable(model) {
+    const label = (model ?? "the selected model").replace(/[\x00-\x1f\x7f-\x9f]/g, "").slice(0, 200);
+    console.error(`rafi: Fast mode not available with ${label}; continuing at standard speed.`);
+}

package/dist/adapters/types.d.ts

@@ -6,6 +6,8 @@ import type { ConfigurableAgentRole, ProviderSessionRefV1, RuntimeProbeCategory,
 import type { RunObserver } from "../observability.js";
 /** A permission request surfaced by a builder before it runs a tool. */
 export interface PermissionRequest {
+    /** Provider-observed tool cwd, distinct from immutable session launch scope. */
+    executionCwd?: string;
     toolName: string;
     input: Record<string, unknown>;
     /** Human-readable prompt from the agent, when available. */

package/dist/agentRun.js

@@ -54,6 +54,7 @@ export function readOnlyPermissionConfig() {
             "npm run typecheck",
             "npm run lint",
             "npm run check",
+            "node --test",
             "pnpm test",
             "pnpm run test",
             "pnpm typecheck",

package/dist/branch/runner.js

@@ -304,7 +304,7 @@ export async function runBranchPlan(opts) {
             base: node.baseBranch,
             dependencies: node.dependencies,
         });
-        workflowCheckpoint(opts.projectDir, opts.runId, "builder-before", node.ticket.id, { branch: node.branch, worktree: node.worktreePath });
+        workflowCheckpoint(opts.projectDir, opts.runId, qaOnlyRecovery ? "qa-recovery-before" : "builder-before", node.ticket.id, { branch: node.branch, worktree: node.worktreePath });
         const continuationDb = new WorkflowDb(opts.projectDir);
         const continuationSession = continuations.length ? continuationDb.branchResumeSession(opts.runId, node.ticket.id) : undefined;
         continuationDb.close();
@@ -391,50 +391,52 @@ export async function runBranchPlan(opts) {
                     ? await opts.observer.withContext({ role: "builder", stream: "builder", ticketId: node.ticket.id, deliveryUnitId: node.deliveryUnitId }, turn)
                     : await turn();
             builder = foreman.builderAdapter();
-            workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
-            const sessionId = builder.sessionId();
-            const sessionRef = builder.sessionRef?.();
-            if (sessionId)
-                builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
-            if (sessionId) {
-                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 });
-            }
-            if (sessionId) {
-                const resumeSession = {
-                    ticket: node.ticket.id,
-                    branch: node.branch,
-                    base: node.baseBranch,
-                    worktreePath,
-                    sessionId,
-                    sessionRef: builder.sessionRef?.(),
-                    agent: opts.agent,
-                    model: opts.model,
-                    effort: opts.effort,
-                    fast: opts.fast,
-                    qaEnabled: opts.qaEnabled,
-                    createPr: createsReview,
-                    completionMode,
-                    reviewProvider,
-                    prReady: opts.prReady,
-                    keepWorktrees: opts.keepWorktrees,
-                    deliveryUnitId: node.deliveryUnitId,
-                    deliveryUnitFinal: node.deliveryUnitFinal,
-                    logPath: "structured-recovery",
-                    ts: new Date().toISOString(),
-                };
-                opts.log.write("branch-session", resumeSession);
-                const resumeDb = new WorkflowDb(opts.projectDir);
-                try {
-                    resumeDb.recordBranchResumeSession(opts.runId, resumeSession);
-                }
-                finally {
-                    resumeDb.close();
+            if (!qaOnlyRecovery) {
+                workflowCheckpoint(opts.projectDir, opts.runId, "builder-after", node.ticket.id, { status: status.kind, sessionId: builder.sessionId(), worktree: worktreePath });
+                const sessionId = builder.sessionId();
+                const sessionRef = builder.sessionRef?.();
+                if (sessionId)
+                    builderStream = { sessionId, ...(sessionRef ? { sessionRef } : {}), worktreePath };
+                if (sessionId) {
+                    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 });
                 }
-                if (node.deliveryUnitId) {
-                    const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
-                    mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
-                    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");
+                if (sessionId) {
+                    const resumeSession = {
+                        ticket: node.ticket.id,
+                        branch: node.branch,
+                        base: node.baseBranch,
+                        worktreePath,
+                        sessionId,
+                        sessionRef: builder.sessionRef?.(),
+                        agent: opts.agent,
+                        model: opts.model,
+                        effort: opts.effort,
+                        fast: opts.fast,
+                        qaEnabled: opts.qaEnabled,
+                        createPr: createsReview,
+                        completionMode,
+                        reviewProvider,
+                        prReady: opts.prReady,
+                        keepWorktrees: opts.keepWorktrees,
+                        deliveryUnitId: node.deliveryUnitId,
+                        deliveryUnitFinal: node.deliveryUnitFinal,
+                        logPath: "structured-recovery",
+                        ts: new Date().toISOString(),
+                    };
+                    opts.log.write("branch-session", resumeSession);
+                    const resumeDb = new WorkflowDb(opts.projectDir);
+                    try {
+                        resumeDb.recordBranchResumeSession(opts.runId, resumeSession);
+                    }
+                    finally {
+                        resumeDb.close();
+                    }
+                    if (node.deliveryUnitId) {
+                        const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
+                        mkdirSync(join(opts.projectDir, ".foreman", "delivery-sessions"), { recursive: true });
+                        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", {

package/dist/buildAssignment.d.ts

@@ -22,6 +22,21 @@ export declare class BuildAssignmentRejected extends Error {
 }
 /** A frozen exact-session Builder decision may defer unrelated pending QA. */
 export declare function isInterruptedBuilderRecovery(run: BuildRunRecordV2 | undefined): boolean;
+/** Recovery requires current source, assignment and admission proofs.
+ * A V3 or migrated record alone never grants continuation authority;
+ * full eligibility is verified before any unknown receipt is reconciled. */
+export declare function canReconcileInterruptedBuilderSource(projectDir: string, runId: string): boolean;
+/** Resume the existing approved build from observed local source, never replay
+ * the interrupted instruction or pretend its unknown outcome was successful.
+ * The caller must own recovery admission and the original run's workflow lease. */
+export declare function prepareInterruptedBuilderSourceContinuation(projectDir: string, runId: string): {
+    ticketIds: string[];
+    reconciliationId: string;
+    sourceDigest: string;
+    contentDigest: string;
+};
+/** A launch may not consume a recovery snapshot after product source changes. */
+export declare function assertInterruptedSourceSnapshot(projectDir: string, run: BuildRunRecordV2): void;
 /**
  * Retire only the host-side records for a Builder turn that was interrupted
  * before Rafi received a durable response.  The next turn is sent to the

package/dist/buildAssignment.js

@@ -10,6 +10,11 @@ import { spawnSync } from "node:child_process";
 import { captureFrozenQaSource } from "./qaSnapshot.js";
 import { WorkflowDb } from "./workflowDb.js";
 import { WorkflowReader } from "./workflowReader.js";
+import { classifyProcess, processGroupQuiescent } from "./processIdentity.js";
+import { loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
+import { loadTickets } from "./tickets/ticketLoader.js";
+import { qaDigest } from "./qaProtocolV2.js";
+import { providerSessionKey } from "./sessionIdentity.js";
 /** Work responses confirm an assignment; they never select the next ticket. */
 export function validateBuildAssignment(ticketId, status, responseText = "") {
     // An unmarked response may receive the existing bounded response-only repair.
@@ -32,12 +37,134 @@ export function isInterruptedBuilderRecovery(run) {
         return false;
     const decision = run.recoveryDecision;
     const continuation = run.interruptedBuilderContinuation;
+    if (continuation?.recovery === "source-reconciled" && continuation.reconciliationId) {
+        return decision?.runId === run.runId && decision.role === "builder" && decision.mode === "fresh-with-handoff"
+            && Boolean(continuation.ticketIds?.length === 1 && decision.executionTickets?.includes(continuation.ticketIds[0])
+                && run.tickets.includes(continuation.ticketIds[0]));
+    }
     return decision?.runId === run.runId && decision.role === "builder" && decision.mode === "exact-session"
-        && decision.executionTickets?.length === 1
-        && run.tickets.includes(decision.executionTickets[0])
-        && Boolean(continuation?.ticketIds?.includes(decision.executionTickets[0]))
+        && Boolean(decision.executionTickets?.length && decision.executionTickets.every(id => run.tickets.includes(id)))
+        && Boolean(continuation?.ticketIds?.length === 1 && decision.executionTickets?.includes(continuation.ticketIds[0]))
         && Boolean(continuation?.sessionRef && decision.predecessorSessionRef && sameSession(continuation.sessionRef, decision.predecessorSessionRef));
 }
+/** Recovery requires current source, assignment and admission proofs.
+ * A V3 or migrated record alone never grants continuation authority;
+ * full eligibility is verified before any unknown receipt is reconciled. */
+export function canReconcileInterruptedBuilderSource(projectDir, runId) {
+    const db = new WorkflowReader(projectDir);
+    try {
+        const state = db.getRun(runId)?.state;
+        const assignments = db.operations(runId, true).filter(op => op.kind === "build-assignment" && ["in_progress", "uncertain"].includes(op.status));
+        if (state?.version !== 3 || state.branchMode !== "current" || assignments.length !== 1)
+            return false;
+        const intent = assignments[0].intent;
+        return Boolean(intent.ticketId && state.tickets.includes(intent.ticketId) && intent.before?.digest && intent.requirementsDigest && intent.instructionDigest
+            && db.events(runId).some(event => event.type === "worker_started"));
+    }
+    finally {
+        db.close();
+    }
+}
+/** Resume the existing approved build from observed local source, never replay
+ * the interrupted instruction or pretend its unknown outcome was successful.
+ * The caller must own recovery admission and the original run's workflow lease. */
+export function prepareInterruptedBuilderSourceContinuation(projectDir, runId) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        const lease = db.currentLease();
+        if (lease?.runId !== runId || lease.pid !== process.pid)
+            throw new BuildAssignmentRejected("Source recovery requires the original run's current recovery lease");
+        if (!canReconcileInterruptedBuilderSource(projectDir, runId))
+            throw new BuildAssignmentRejected("Interrupted work lacks current source-bound assignment authority; use guided recovery or preserve files and restart");
+        const run = db.getRun(runId).state;
+        if (run.builderCapabilities?.grantedNetwork)
+            throw new BuildAssignmentRejected("Interrupted network-enabled work requires explicit side-effect reconciliation; source inspection cannot establish remote outcomes");
+        if (db.readinessProcesses().length || db.unresolvedRoleDispatches(runId, "qa").length)
+            throw new BuildAssignmentRejected("Owned processes or a separate QA dispatch must be reconciled before Builder source recovery");
+        if (db.incompletePublications().some(item => item.runId === runId && item.intent.operation !== "build-run-projection"))
+            throw new BuildAssignmentRejected("A pending source/tracker publication must be reconciled before Builder source recovery");
+        const worker = db.events(runId).filter(event => event.type === "worker_started").at(-1)?.payload;
+        if (!worker?.workerPid || classifyProcess(worker.workerPid, worker.processStart, worker.host).state !== "dead" || !processGroupQuiescent(worker.workerPid)) {
+            throw new BuildAssignmentRejected("The interrupted worker and its owned process group must be verified stopped before source recovery");
+        }
+        const assignment = db.operations(runId).find(op => op.kind === "build-assignment" && ["in_progress", "uncertain"].includes(op.status));
+        const intent = assignment.intent;
+        if (realpathSync(intent.worktree) !== realpathSync(projectDir) || realpathSync(run.repository.worktree) !== realpathSync(projectDir))
+            throw new BuildAssignmentRejected("Interrupted source belongs to another worktree");
+        if (run.progress.completedTickets.includes(intent.ticketId) || ["completed", "waived"].includes(db.qaTicketHead(runId, intent.ticketId).state))
+            throw new BuildAssignmentRejected("A completed ticket cannot be reopened by interrupted source recovery");
+        const admission = db.assertAdmittedWork(runId, intent.ticketId);
+        const definition = loadTickets(resolveTicketPaths(loadTicketsConfig(projectDir), projectDir).tickets).find(ticket => ticket.id === intent.ticketId);
+        if (!definition || admission.requirementsDigest !== intent.requirementsDigest || qaDigest("admitted-requirements", definition) !== intent.requirementsDigest)
+            throw new BuildAssignmentRejected("Interrupted ticket requirements changed; current scope needs approval before recovery");
+        const dispatches = db.unresolvedRoleDispatches(runId, "builder");
+        const owner = db.roleMutationLease(runId, "builder");
+        if (!dispatches.length || !owner?.sessionRef || !owner.sessionKey || owner.sessionRef.source !== "observed" || !owner.sessionRef.validatedAt
+            || Number.isNaN(Date.parse(owner.sessionRef.validatedAt)) || dispatches.some(op => {
+            const ref = op.intent.sessionRef;
+            return !sameSession(ref, owner.sessionRef) || providerSessionKey(ref) !== owner.sessionKey;
+        }))
+            throw new BuildAssignmentRejected("Interrupted dispatch is not bound to the recorded Builder owner");
+        const source = captureBuildSource(projectDir);
+        if (run.repository.branch && sourceBranch(projectDir) !== run.repository.branch)
+            throw new BuildAssignmentRejected("The current branch changed; return to the interrupted build's owning branch before source recovery");
+        const reconciliationId = `source-resume:${runId}:${randomUUID()}`;
+        db.atomic(() => {
+            if (captureBuildSource(projectDir).digest !== source.digest)
+                throw new BuildAssignmentRejected("Preserved source changed during recovery inspection; retry from the current files");
+            const retained = retainSource(db, source);
+            const receipt = { recovery: "source-reconciled", reconciliationId, outcomeUnknown: true, providerReplayAuthorized: false, source: retained, ticketId: intent.ticketId, requirementsDigest: intent.requirementsDigest, worker, at: new Date().toISOString() };
+            for (const dispatch of dispatches)
+                db.updateOperation(dispatch.idempotencyKey, "failed", { result: { ...receipt, priorResult: dispatch.result }, error: "Interrupted provider outcome remains unknown; verified stopped local execution is replaced by source inspection and fresh QA, without replay" });
+            db.updateOperation(assignment.idempotencyKey, "failed", { result: { ...receipt, priorResult: assignment.result }, error: "Interrupted assignment preserved for source-bound continuation; completion is not established" });
+            const event = db.appendContinuityEvent({ runId, role: "host", kind: "interrupted_source_reconciled", payload: { ...receipt, dispatchIds: dispatches.map(op => op.idempotencyKey), assignmentId: assignment.idempotencyKey }, authoritativeStateRevision: db.continuityHead(runId, "run")?.authoritativeStateRevision ?? 0 });
+            db.publishContinuityCheckpoint({ runId, role: "builder", state: "current", authoritativeStateRevision: event.authoritativeStateRevision, delta: {
+                    version: 1, decisions: [`Continue already-approved ticket ${intent.ticketId} in the SAME build from preserved source; this host reconciliation is not a successful provider turn.`],
+                    constraints: ["Never replay the interrupted provider instruction or assume its side effects did not happen. Inspect current files first, implement only missing approved work, and require independent QA. Preserve all completed tickets and accepted QA.", "The predecessor session's compaction history remains unknown; use a validated fresh handoff before any new implementation."],
+                    discoveries: [], completedActions: [], evidence: [`Host-observed source digest ${source.digest}; interrupted assignment ${assignment.idempotencyKey}; reconciliation ${reconciliationId}`],
+                    failures: ["The interrupted provider outcome is unknown and remains preserved in the historical receipt."], blockers: [], openWork: [`Inspect preserved implementation of ${intent.ticketId}; complete remaining criteria and obtain fresh QA.`], nextAction: `Accept a fresh source-bound handoff, inspect ${intent.ticketId}, then continue all remaining approved tickets.`,
+                } });
+            const current = db.getRun(runId);
+            db.transition(runId, { checkpoint: "builder-source-reconciled", state: { ...current.state, interruptedBuilderContinuation: { recovery: "source-reconciled", ticketIds: [intent.ticketId], reconciliationId, sourceDigest: source.digest, contentDigest: source.contentDigest, productDigest: interruptedProductDigest(projectDir, source) } }, event: "builder_source_continuation_authorized", payload: receipt });
+        });
+        return { ticketIds: [intent.ticketId], reconciliationId, sourceDigest: source.digest, contentDigest: source.contentDigest };
+    }
+    finally {
+        db.close();
+    }
+}
+/** A launch may not consume a recovery snapshot after product source changes. */
+export function assertInterruptedSourceSnapshot(projectDir, run) {
+    const continuation = run.interruptedBuilderContinuation;
+    if (continuation?.recovery !== "source-reconciled" || continuation.firstAssignmentId || !continuation.ticketIds?.some(id => !run.progress.completedTickets.includes(id)))
+        return;
+    const reader = new WorkflowReader(projectDir);
+    try {
+        // A stale in-memory snapshot can lag the atomic consumption marker. The
+        // source-bound assignment journal is durable and cannot be overwritten by
+        // the next ordinary run projection.
+        const reconciliationId = continuation.reconciliationId;
+        if (reconciliationId && reader.operations(run.runId, true).some(op => op.kind === "build-assignment" && op.intent.sourceRecoveryId === reconciliationId))
+            return;
+    }
+    finally {
+        reader.close();
+    }
+    const source = captureBuildSource(projectDir);
+    if (continuation.productDigest ? interruptedProductDigest(projectDir, source) !== continuation.productDigest : source.contentDigest !== continuation.contentDigest)
+        throw new BuildAssignmentRejected("Preserved implementation changed after recovery preparation; inspect the current files with rafi resume before launching new work");
+}
+function interruptedProductDigest(projectDir, source) {
+    const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+    // Ticket status/rendering is host bookkeeping, not product mutation. Ticket
+    // definitions and other documents remain bound, including unrelated docs.
+    const bookkeeping = new Set([paths.stateDb, `${paths.stateDb}-wal`, `${paths.stateDb}-shm`, paths.progressDoc, paths.archiveDoc].map(path => relative(projectDir, path).replace(/\\/g, "/")));
+    return createHash("sha256").update(JSON.stringify({ head: source.head, branch: sourceBranch(projectDir), paths: source.pathInventory.filter(path => !bookkeeping.has(path.path)) })).digest("hex");
+}
+function sourceBranch(projectDir) {
+    const result = spawnSync("git", ["branch", "--show-current"], { cwd: projectDir, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    return result.status === 0 ? result.stdout.trim() : undefined;
+}
 /**
  * Retire only the host-side records for a Builder turn that was interrupted
  * before Rafi received a durable response.  The next turn is sent to the
@@ -210,6 +337,12 @@ export function beginBuildAssignment(projectDir, runId, ticketId, worktree, inst
         db.atomic(() => {
             db.ensureRun(runId);
             const admission = db.assertAdmittedWork(runId, ticketId);
+            const continuationState = db.getRun(runId);
+            const sourceContinuation = continuationState.state.interruptedBuilderContinuation;
+            if (sourceContinuation?.recovery === "source-reconciled" && sourceContinuation.ticketIds?.includes(ticketId) && !sourceContinuation.firstAssignmentId) {
+                assertInterruptedSourceSnapshot(projectDir, continuationState.state);
+                db.transition(runId, { checkpoint: continuationState.checkpoint, state: { ...continuationState.state, interruptedBuilderContinuation: { ...sourceContinuation, firstAssignmentId: operationId } }, event: "builder_source_continuation_consumed", payload: { ticketId, operationId, sourceDigest: before.digest } });
+            }
             let contractBinding;
             if (db.qaPreparationStore().policy(runId)?.mode === "enforce") {
                 const contract = assertContractReceipt(db.qaPreparationStore(), runId, ticketId, admission.requirementsDigest, adapter ? actualContractSession(adapter, worktree, projectDir) : undefined, adapter);
@@ -221,7 +354,11 @@ export function beginBuildAssignment(projectDir, runId, ticketId, worktree, inst
                 if (contract.inputs.find(input => input.kind === "rules")?.digest !== current.digest || contract.inputs.find(input => input.kind === "checklist")?.digest !== contractDigest("input-checklist", current.checklist))
                     throw new BuildAssignmentRejected("Canonical QA rules, skills or checklist changed after delivery; reconcile the contract before implementation");
             }
-            guidance = db.reserveGuidance(runId, ticketId, "builder", operationId, before.digest, instruction);
+            const continuation = db.getRun(runId)?.state.interruptedBuilderContinuation;
+            const recoveredInstruction = continuation?.recovery === "source-reconciled" && continuation.ticketIds?.includes(ticketId)
+                ? `${instruction}\n\nHost recovery ${continuation.reconciliationId}: an earlier assignment was interrupted with an unknown result. Inspect the preserved files before acting. Do not replay the old instruction, repeat completed side effects, or redo completed tickets. Implement only missing acceptance criteria for this ticket, validate the current implementation and return truthful evidence for independent fresh QA.`
+                : instruction;
+            guidance = db.reserveGuidance(runId, ticketId, "builder", operationId, before.digest, recoveredInstruction);
             if (followup) {
                 if (admission.requirementsDigest !== followup.requirementsDigest)
                     throw new BuildAssignmentRejected("Ticket requirements changed; renewed scope approval is required before the Builder follow-up");
@@ -236,7 +373,7 @@ export function beginBuildAssignment(projectDir, runId, ticketId, worktree, inst
                 db.transitionQa(runId, ticketId, head.revision, { type: "builder-guidance-followup-intended" });
             }
             const instructionDigest = db.putEvidence("qa", Buffer.from(guidance.text));
-            db.planOperation({ runId, idempotencyKey: operationId, kind: "build-assignment", intent: { ticketId, worktree, admissionId: admission.assignmentId, requirementsDigest: admission.requirementsDigest, instructionDigest, ...(contractBinding ? { contractBinding } : {}), before: retainSource(db, before), ...(followup ? { managerFollowup: followup } : {}) } });
+            db.planOperation({ runId, idempotencyKey: operationId, kind: "build-assignment", intent: { ticketId, worktree, admissionId: admission.assignmentId, requirementsDigest: admission.requirementsDigest, instructionDigest, ...(continuation?.recovery === "source-reconciled" && continuation.ticketIds?.includes(ticketId) ? { sourceRecoveryId: continuation.reconciliationId } : {}), ...(contractBinding ? { contractBinding } : {}), before: retainSource(db, before), ...(followup ? { managerFollowup: followup } : {}) } });
             db.recordWorkAssignment(runId, ticketId, operationId, { requirementsDigest: admission.requirementsDigest, worktree, sourceDigest: before.digest, ownerGeneration: db.currentLease()?.generation, instructionDigest });
             db.updateOperation(operationId, "in_progress");
         });

package/dist/buildRuns.d.ts

@@ -39,6 +39,9 @@ export declare function resumeBuildRun(projectDir: string, runId: string, patch:
 type LegacyResolvedAgentSettings = Omit<ResolvedAgentSettings, "session_strategy" | "settings_revision" | "display_session_cost" | "auto_compact_threshold_percent" | "compact_maximum"> & Partial<Pick<ResolvedAgentSettings, "session_strategy" | "settings_revision" | "display_session_cost" | "auto_compact_threshold_percent" | "compact_maximum">>;
 export declare function saveBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
 export declare function checkpointBuildRun(projectDir: string, run: BuildRunRecordV2, checkpoint: string, patch?: Partial<BuildRunRecordV2>): BuildRunRecordV2;
+/** Refresh a publication from durable state while retaining only the caller's
+ * original execution authority. A read-only projection never grants authority. */
+export declare function persistCurrentBuildSession(projectDir: string, authorizedRun: BuildRunRecordV2, role: "builder" | "qa", session: ProviderSessionRefV1): BuildRunRecordV2;
 export declare function persistBuildSession(projectDir: string, run: BuildRunRecordV2, role: "builder" | "qa", session: string | ProviderSessionRefV1): BuildRunRecordV2;
 /** Latest scoped binding, with the narrow legacy Builder inference allowed by the recovery protocol. */
 export declare function buildRunSessionBinding(run: BuildRunRecordV2, role: "builder" | "qa", sessionId?: string): ProviderSessionRefV1 | undefined;
@@ -51,6 +54,8 @@ export declare function releaseBuildLease(projectDir: string, run: BuildRunRecor
 export declare function completeBuildRun(projectDir: string, run: BuildRunRecordV2, now?: Date): BuildRunRecordV2;
 /** A recovered ticket boundary is complete only when the saved run scope is done. */
 export declare function finishRecoveredTicketScope(projectDir: string, run: BuildRunRecordV2, checkpoint: string): BuildRunRecordV2;
+/** A recovered boundary cannot authorize work on a still-blocked remainder. */
+export declare function hasRunnableBuildRemainder(projectDir: string, run: BuildRunRecordV2): boolean;
 export declare function readBuildRuns(projectDir: string): BuildRunRecordV2[];
 export declare function recoverableBuildRuns(projectDir: string, now?: Date): Array<BuildRunRecordV2 & {
     active: boolean;
@@ -71,6 +76,7 @@ export interface BuildRecoveryProjection {
     compactLabel: string;
     compactHint: string;
     completed: string[];
+    completedOperations?: string[];
     remaining: string[];
     lastSuccess: string;
     interruption: string;

package/dist/buildRuns.js

@@ -16,6 +16,7 @@ import { loadTickets } from "./tickets/ticketLoader.js";
 import { loadProjectAutonomyConfig, resolveAutonomyPolicy } from "./recoveryPolicy.js";
 import { classifyProcess, processStartIdentity } from "./processIdentity.js";
 import { assertBuildAssignmentReconciled } from "./buildAssignment.js";
+import { computeDisplayStatus, resolveBlockers } from "./tickets/blockers.js";
 export const BUILD_RUN_VERSION = 3;
 export const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export const BUILD_HEARTBEAT_MS = 10_000;
@@ -176,6 +177,11 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
             const existing = workflow.getRun(next.runId);
             const priorProgress = existing?.state.progress;
             next = { ...next, progress: { ...next.progress, completedTickets: [...new Set([...next.progress.completedTickets, ...(priorProgress?.completedTickets ?? [])])] } };
+            const newlyCompleted = next.progress.completedTickets.filter(ticket => !priorProgress?.completedTickets?.includes(ticket));
+            if (newlyCompleted.length || next.status === "completed")
+                next = { ...next, progress: { ...next.progress,
+                        lastSuccessfulAction: next.status === "completed" ? "Build completed" : `Recorded completion of ${newlyCompleted.join(", ")}`,
+                    } };
             if (existing && ["completed", "cancelled", "superseded"].includes(existing.status) && workflowStatus(next.status) !== existing.status)
                 throw new Error(`cannot rewrite a ${existing.status} build run`);
             if (!existing)
@@ -228,6 +234,21 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
 export function checkpointBuildRun(projectDir, run, checkpoint, patch = {}) {
     return saveBuildRun(projectDir, { ...run, ...patch, checkpoint, receipts: patch.receipts ?? run.receipts });
 }
+/** Refresh a publication from durable state while retaining only the caller's
+ * original execution authority. A read-only projection never grants authority. */
+export function persistCurrentBuildSession(projectDir, authorizedRun, role, session) {
+    const db = new WorkflowDb(projectDir);
+    try {
+        assertBuildAuthority(db, authorizedRun);
+    }
+    finally {
+        db.close();
+    }
+    const latest = readBuildRuns(projectDir).find(run => run.runId === authorizedRun.runId);
+    if (!latest)
+        throw new Error("The authorized build no longer exists; inspect recovery before publishing a session");
+    return persistBuildSession(projectDir, { ...authorizedRun, ...latest }, role, session);
+}
 export function persistBuildSession(projectDir, run, role, session) {
     const current = run[role];
     if (!current)
@@ -329,6 +350,28 @@ export function finishRecoveredTicketScope(projectDir, run, checkpoint) {
         progress: { ...run.progress, completedTickets: completed, remainingTickets: remaining, nextAction: `Resume ${remaining[0]}` },
     }), "recoverable");
 }
+/** A recovered boundary cannot authorize work on a still-blocked remainder. */
+export function hasRunnableBuildRemainder(projectDir, run) {
+    if (run.authorizedBatch && run.progress.completedTickets.length >= run.authorizedBatch.requestedSteps)
+        return false;
+    if (!isTicketsInitialized(projectDir))
+        return false;
+    const paths = resolveTicketPaths(loadTicketsConfig(projectDir), projectDir);
+    const db = new Database(paths.stateDb, { readonly: true, fileMustExist: true });
+    try {
+        const states = new Map(db.prepare("SELECT * FROM ticket_state").all().map(state => [state.ticket_id, state]));
+        return loadTickets(paths.tickets).some(ticket => {
+            if (!run.progress.remainingTickets.includes(ticket.id))
+                return false;
+            const blockedBy = resolveBlockers(ticket, states);
+            const status = computeDisplayStatus(states.get(ticket.id)?.status ?? "planned", blockedBy);
+            return blockedBy.length === 0 && ["next", "in_progress"].includes(status);
+        });
+    }
+    finally {
+        db.close();
+    }
+}
 export function readBuildRuns(projectDir) {
     const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
     const workflow = new WorkflowReader(projectDir);
@@ -363,9 +406,13 @@ export function readBuildRuns(projectDir) {
             const authoritative = workflow?.getRun(projection.runId)?.state;
             const run = authoritative?.runId ? authoritative : projection;
             let upgraded = upgradeBuildRun(run, projectDir);
-            const dbStatus = workflow.getRun(run.runId)?.status;
+            const storedRun = workflow.getRun(run.runId);
+            const dbStatus = storedRun?.status;
             if (dbStatus === "superseded" || dbStatus === "completed" || dbStatus === "cancelled")
                 upgraded = { ...upgraded, status: dbStatus };
+            else if (storedRun && (dbStatus === "failed" || dbStatus === "paused" || dbStatus === "blocked")) {
+                upgraded = { ...upgraded, status: dbStatus === "failed" ? "failed" : "recoverable", checkpoint: storedRun.checkpoint, updatedAt: storedRun.updatedAt };
+            }
             if (!["completed", "superseded", "cancelled"].includes(workflow?.getRun(run.runId)?.status ?? "")) {
                 for (const role of ["builder", "qa"]) {
                     const lease = workflow?.roleMutationLease(run.runId, role);
@@ -563,7 +610,8 @@ export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOv
         unexpectedChanges.push({ path: recoveryWorktree, risk: "preserved worktree identity changed" });
     if (branchChanged)
         unexpectedChanges.push({ path: recoveryWorktree, risk: `branch changed from ${expectedBranch} to ${branchNow}` });
-    const completed = [...new Set([...(progress?.completed ?? run.progress.completedTickets), ...run.progress.completedOperations, ...operationNames])];
+    const completed = [...new Set(progress?.completed ?? run.progress.completedTickets)];
+    const completedOperations = [...new Set([...run.progress.completedOperations, ...operationNames])];
     const remaining = progress?.remaining ?? (run.progress.remainingTickets.length ? run.progress.remainingTickets : remainingTickets(run));
     const interruption = run.interruption?.lastError ?? run.interruption?.summary ?? run.failure?.summary ?? issues.at(-1) ?? run.status;
     const validation = run.progress.validation
@@ -580,8 +628,8 @@ export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOv
         run, ticketId, ticketTitle,
         compactLabel: `${primary} — ${run.status}`,
         compactHint: `${run.builder?.settings.make ?? "runtime unavailable"}; ${stateBranch ?? branchNow ?? run.repository.branch ?? "current branch"}; updated ${relativeTime(run.updatedAt, now)}`,
-        completed, remaining,
-        lastSuccess: run.progress.lastSuccessfulAction ?? run.checkpoint,
+        completed, completedOperations, remaining,
+        lastSuccess: run.progress.lastSuccessfulAction ?? "none recorded",
         interruption,
         validation,
         expectedChanges,
@@ -623,6 +671,7 @@ export function formatBuildRecoveryProjection(projection) {
         `ticket ${projection.ticketId ?? "unavailable"}${projection.ticketTitle ? `: ${projection.ticketTitle}` : ""}`,
         `status ${run.status}; checkpoint ${run.checkpoint}`,
         `completed ${projection.completed.join(", ") || "none recorded"}`,
+        ...(projection.completedOperations?.length ? [`verified operation receipts ${projection.completedOperations.join(", ")}`] : []),
         `current ${run.progress.currentStep ?? projection.ticketId ?? "not recorded"}`,
         `remaining ${projection.remaining.join(", ") || "none"}`,
         `last successful action ${projection.lastSuccess}`,
@@ -680,7 +729,7 @@ function captureGitSnapshot(worktree, input) {
             return undefined;
         }
     };
-    const statusPaths = (git(["status", "--porcelain=v1", "-z"]) ?? "").split("\0").filter(Boolean).map((line) => line.slice(3)).sort();
+    const statusPaths = gitStatusPaths(worktree);
     const head = input.startHead ?? git(["rev-parse", "HEAD"]);
     const branch = input.branch ?? git(["branch", "--show-current"]);
     return {
@@ -710,7 +759,24 @@ function gitValue(cwd, args) {
     }
 }
 function gitStatusPaths(cwd) {
-    return (gitValue(cwd, ["status", "--porcelain=v1", "-z"]) ?? "").split("\0").filter(Boolean).map((line) => line.slice(3)).sort();
+    try {
+        // Porcelain status columns and pathname whitespace are significant. In -z
+        // mode a rename/copy has a second raw pathname, without status columns.
+        const records = execFileSync("git", ["status", "--porcelain=v1", "-z"], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).split("\0");
+        const paths = [];
+        for (let i = 0; i < records.length; i++) {
+            const record = records[i];
+            if (!record)
+                continue;
+            paths.push(record.slice(3));
+            if (/[RC]/.test(record.slice(0, 2)) && records[i + 1])
+                paths.push(records[++i]);
+        }
+        return [...new Set(paths.filter(Boolean))].sort();
+    }
+    catch {
+        return [];
+    }
 }
 function relativeTime(value, now) {
     const seconds = Math.max(0, Math.floor((now.getTime() - new Date(value).getTime()) / 1000));
@@ -752,7 +818,7 @@ function upgradeBuildRun(run, projectDir = run.repository.root, now = new Date()
             completedTickets: legacy.status === "completed" ? [...legacy.tickets] : [],
             completedOperations: Object.keys(legacy.receipts).sort(),
             remainingTickets: remaining,
-            lastSuccessfulAction: legacy.checkpoint,
+            ...(legacy.status === "completed" ? { lastSuccessfulAction: "build completed" } : {}),
             nextAction: remaining[0] ? `Resume ${remaining[0]}` : "Inspect legacy run",
         },
         frozenPolicy: policy,

package/dist/cli/start.d.ts

@@ -29,5 +29,10 @@ export declare function buildStartCommand(options?: {
 }): Command;
 export declare function createQaNonconvergenceHandler(projectDir: string, noninteractive: boolean, planner?: AgentRoleDefaultsV1, observer?: () => RunObserver | undefined, activeRunId?: () => string): (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
 export declare function createQaReportRecoveryHandler(projectDir: string, noninteractive: boolean, observer?: () => RunObserver | undefined): QaReportRecoveryHandler;
+export declare function recoveryCompactionHistoryUncertain(projectDir: string, recovery: {
+    legacy?: boolean;
+    version?: number;
+    runDecisions?: unknown;
+} | undefined, runId: string | undefined, role: "builder" | "qa"): boolean;
 /** Make the executable branch plan exactly match each explicit root-to-tip stack. */
 export declare function applyExplicitStackTopology(plan: BranchPlan, stacks: DeliveryStack[], delivery: DeliveryConfig, branchPrefix: string): BranchPlan;