ai-foreman 1.7.21 → 1.7.23

package/dist/activity.js

@@ -298,8 +298,15 @@ export function reportBuilderEvent(event) {
                 reporter.pulse();
                 break;
             case "completed":
-                reporter.completedWork();
-                if (isFailedToolCompletion(event))
+                if (event.completionKnown !== false)
+                    reporter.completedWork();
+                if (event.status === "unknown")
+                    reporter.update("tool outcome unknown", event.name, { immediate: false });
+                else if (event.status === "timed_out")
+                    reporter.update("tool timed out", event.name);
+                else if (event.status === "cancelled")
+                    reporter.update("tool cancelled", event.name);
+                else if (isFailedToolCompletion(event))
                     reporter.update("tool failed", event.name);
                 else
                     reporter.pulse();

package/dist/adapters/claude.d.ts

@@ -78,6 +78,9 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private activeProviderTurnId?;
     private activeProviderTurnSpanId?;
     private readonly toolSpans;
+    private readonly toolCalls;
+    private readonly completedToolCalls;
+    private readonly unknownToolResults;
     private pending?;
     private questionTrace?;
     private responseOnlyTurn;

package/dist/adapters/claude.js

@@ -202,6 +202,9 @@ export class ClaudeAdapter {
     activeProviderTurnId;
     activeProviderTurnSpanId;
     toolSpans = new Map();
+    toolCalls = new Map();
+    completedToolCalls = new Set();
+    unknownToolResults = new Map();
     pending;
     questionTrace;
     responseOnlyTurn = false;
@@ -396,6 +399,9 @@ export class ClaudeAdapter {
                 }
                 else if (block.type === "tool_use") {
                     const callId = block.id;
+                    this.toolCalls.set(callId, { name: block.name, input: block.input });
+                    if (this.toolCalls.size > 1000)
+                        this.toolCalls.delete(this.toolCalls.keys().next().value);
                     this.eventQueue.push({
                         kind: "tool",
                         name: block.name,
@@ -622,14 +628,35 @@ export class ClaudeAdapter {
             const callId = typeof block.tool_use_id === "string" ? block.tool_use_id : undefined;
             if (!callId)
                 continue;
+            if (this.completedToolCalls.has(callId))
+                continue;
+            const call = this.toolCalls.get(callId);
             const spanId = this.toolSpans.get(callId);
             const text = typeof block.content === "string" ? block.content : JSON.stringify(block.content ?? "");
-            const sanitized = text.replace(/\b(?:token|password|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[REDACTED]");
+            const sanitized = text.replace(/\b(token|password|secret|api[_-]?key)\s*[:=]\s*\S+/gi, "$1=[REDACTED]");
             const failed = block.is_error === true;
+            // TIME_ELAPSED alone does not establish success or failure. Preserve it as unknown.
+            const elapsedOnly = /^\s*TIME_ELAPSED\s*$/.test(text);
+            const status = failed && /timed?\s*out|timeout/i.test(text) ? "timed_out" : failed && /cancel(?:led|ed)/i.test(text) ? "cancelled" : elapsedOnly ? "unknown" : failed ? "failed" : "completed";
+            if (status !== "unknown") {
+                this.completedToolCalls.add(callId);
+                if (this.completedToolCalls.size > 1000)
+                    this.completedToolCalls.delete(this.completedToolCalls.values().next().value);
+                this.toolCalls.delete(callId);
+            }
             const outputDigest = createHash("sha256").update(text).digest("hex");
-            this.eventQueue.push({ kind: "tool", name: "tool_result", input: {}, inputCompleteness: "unavailable", lifecycle: "completed", callId, status: failed ? "failed" : "completed", outputSummary: sanitized.slice(0, 1000), outputDigest, outputCompleteness: block.is_truncated === true ? "truncated" : "complete", rawOutputBytes: Buffer.byteLength(text), completionKnown: true, providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
-            if (spanId && this.opts.observer) {
-                this.opts.observer.store.finishSpan(spanId, { outcome: failed ? "failed" : "completed", completionKnown: true, attributes: { callId, outputSummary: sanitized.slice(0, 1000), outputDigest } });
+            if (status === "unknown") {
+                if (this.unknownToolResults.get(callId) === outputDigest)
+                    continue;
+                this.unknownToolResults.set(callId, outputDigest);
+                if (this.unknownToolResults.size > 1000)
+                    this.unknownToolResults.delete(this.unknownToolResults.keys().next().value);
+            }
+            else
+                this.unknownToolResults.delete(callId);
+            this.eventQueue.push({ kind: "tool", name: call?.name ?? "unidentified tool", input: call?.input ?? {}, inputCompleteness: call ? "complete" : "unavailable", lifecycle: "completed", callId, status, outputSummary: sanitized.slice(0, 1000), outputDigest, outputCompleteness: block.is_truncated === true ? "truncated" : "complete", rawOutputBytes: Buffer.byteLength(text), completionKnown: status !== "unknown", providerTurnId: this.activeProviderTurnId, eventId: randomUUID(), observedAt: new Date().toISOString() });
+            if (spanId && this.opts.observer && status !== "unknown") {
+                this.opts.observer.store.finishSpan(spanId, { outcome: status, completionKnown: true, attributes: { callId, outputSummary: sanitized.slice(0, 1000), outputDigest } });
                 this.toolSpans.delete(callId);
             }
             this.opts.observer?.signal(true);

package/dist/branch/dirtyBaseline.d.ts

@@ -0,0 +1,5 @@
+/** Capture build input with a private index. Never stash, commit, or modify the user's index. */
+export declare function captureDirtyBaseline(projectDir: string, mode: "preserve" | "include"): {
+    base: string;
+    recordPath: string;
+};

package/dist/branch/dirtyBaseline.js

@@ -0,0 +1,69 @@
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+/** Capture build input with a private index. Never stash, commit, or modify the user's index. */
+export function captureDirtyBaseline(projectDir, mode) {
+    const git = (args, env = process.env) => execFileSync("git", args, { cwd: projectDir, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim();
+    if (git(["diff", "--name-only", "--diff-filter=U"]))
+        throw new Error("Resolve Git conflicts before starting an isolated build; Rafi has preserved your files.");
+    const head = () => { try {
+        return git(["rev-parse", "--verify", "HEAD"]);
+    }
+    catch {
+        return undefined;
+    } };
+    const parent = head();
+    if (!parent && mode === "preserve")
+        throw new Error("This repository has no committed baseline. Use --dirty-work include to capture current files privately, or make an initial commit first.");
+    const directory = join(projectDir, ".foreman/dirty-baselines");
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const recordPath = mkdtempSync(join(directory, "baseline-"));
+    const indexPath = resolve(projectDir, git(["rev-parse", "--git-path", "index"]));
+    const indexDigest = existsSync(indexPath) ? createHash("sha256").update(readFileSync(indexPath)).digest("hex") : null;
+    const status = git(["status", "--porcelain", "--untracked-files=all"]);
+    const paths = execFileSync("git", ["ls-files", "-z", "--cached", "--others", "--exclude-standard"], { cwd: projectDir }).toString().split("\0").filter(path => path && !path.startsWith(".foreman/") && !/^\.rafi\/(recovery|observability)\.sqlite3/.test(path));
+    // HEAD paths are needed too: staged deletions/rename sources no longer exist in the user's index.
+    if (parent)
+        paths.push(...execFileSync("git", ["ls-tree", "-r", "--name-only", "-z", parent], { cwd: projectDir }).toString().split("\0").filter(path => path && !path.startsWith(".foreman/") && !/^\.rafi\/(recovery|observability)\.sqlite3/.test(path)));
+    const files = [...new Set(paths)].map(path => {
+        const absolute = join(projectDir, path);
+        if (!existsSync(absolute))
+            return { path, digest: null };
+        const stat = lstatSync(absolute);
+        if (stat.isDirectory()) {
+            if (mode === "include" && execFileSync("git", ["status", "--porcelain"], { cwd: absolute, encoding: "utf8" }).trim())
+                throw new Error(`Dirty submodule ${path} cannot be included automatically. Commit its work or use --dirty-work preserve.`);
+            return { path, digest: null, kind: "submodule" };
+        }
+        return { path, digest: createHash("sha256").update(stat.isSymbolicLink() ? readlinkSync(absolute) : readFileSync(absolute)).digest("hex"), mode: stat.mode, kind: stat.isSymbolicLink() ? "symlink" : "file" };
+    });
+    const diffBase = parent ?? execFileSync("git", ["hash-object", "-w", "-t", "tree", "--stdin"], { cwd: projectDir, input: "", encoding: "utf8" }).trim();
+    const diff = execFileSync("git", ["diff", diffBase, "--binary"], { cwd: projectDir });
+    writeFileSync(join(recordPath, "working.patch"), diff, { mode: 0o600 });
+    let base = parent;
+    if (mode === "include") {
+        const env = { ...process.env, GIT_INDEX_FILE: join(recordPath, "index"), GIT_AUTHOR_NAME: "Rafi baseline", GIT_AUTHOR_EMAIL: "baseline@rafi.local", GIT_COMMITTER_NAME: "Rafi baseline", GIT_COMMITTER_EMAIL: "baseline@rafi.local" };
+        git(parent ? ["read-tree", parent] : ["read-tree", "--empty"], env);
+        if (paths.length)
+            execFileSync("git", ["add", "-A", "--pathspec-from-file=-", "--pathspec-file-nul"], { cwd: projectDir, env: { ...env, GIT_LITERAL_PATHSPECS: "1" }, input: `${paths.join("\0")}\0`, stdio: ["pipe", "pipe", "pipe"] });
+        const tree = git(["write-tree"], env);
+        base = git(["commit-tree", tree, ...(parent ? ["-p", parent] : []), "-m", "Rafi preserved dirty build input"], env);
+    }
+    const finalIndexDigest = existsSync(indexPath) ? createHash("sha256").update(readFileSync(indexPath)).digest("hex") : null;
+    const changed = head() !== parent || finalIndexDigest !== indexDigest || files.some(file => {
+        if (file.kind === "submodule")
+            return false;
+        const absolute = join(projectDir, file.path);
+        if (!existsSync(absolute))
+            return file.digest !== null;
+        if (file.digest === null)
+            return true;
+        const stat = lstatSync(absolute);
+        return createHash("sha256").update(stat.isSymbolicLink() ? readlinkSync(absolute) : readFileSync(absolute)).digest("hex") !== file.digest || stat.mode !== file.mode;
+    });
+    if (changed)
+        throw new Error("Checkout or index changed while capturing the baseline. Your work is preserved; retry after those edits finish.");
+    writeFileSync(join(recordPath, "manifest.json"), JSON.stringify({ version: 1, mode, parent, base, indexDigest, status, files, patchDigest: createHash("sha256").update(diff).digest("hex"), createdAt: new Date().toISOString(), delivery: "isolated branches; no automatic merge into dirty checkout" }, null, 2), { mode: 0o600 });
+    return { base, recordPath };
+}

package/dist/branch/resume.js

@@ -73,7 +73,7 @@ export function findResumableBranchSessions(foremanDir) {
 }
 export function formatBranchContinueCommand(projectDir, session) {
     const args = [
-        "ai-foreman",
+        "rafi",
         "start",
         shellQuote(projectDir),
         "--steps",
@@ -91,7 +91,7 @@ export function formatBranchContinueCommand(projectDir, session) {
         args.push("--model", shellQuote(session.model));
     if (session.effort)
         args.push("--effort", shellQuote(session.effort));
-    if (session.reviewProvider)
+    if (session.reviewProvider && session.completionMode !== "none" && (session.completionMode || session.createPr))
         args.push("--provider", shellQuote(session.reviewProvider));
     if (session.fast)
         args.push("--fast");

package/dist/buildWorkMigration.js

@@ -18,12 +18,21 @@ export function migrateBuildWork(db, projectDir, faults) {
     }
     const lease = db.prepare("SELECT pid,process_start,host FROM project_lease").get();
     if (lease && classifyProcess(lease.pid, lease.process_start, lease.host).state !== "dead")
-        throw new Error("Work admission upgrade requires stopped, verified writers and a consistent backup");
+        throw new Error(`Rafi cannot upgrade build storage while its writer may still be running (PID ${lease.pid}, host ${lease.host}). Run \`rafi status .\` and \`rafi doctor .\` to inspect it. Stop the build on its owning host before retrying; ticket show, validate, and queue remain available.`);
     const owner = db.prepare("SELECT record_json FROM build_admission").get();
     if (owner) {
-        const identity = JSON.parse(owner.record_json);
-        if (classifyProcess(identity.pid, identity.processStart, identity.host).state !== "dead")
-            throw new Error("Work admission upgrade requires a stopped, verified build owner");
+        let identity;
+        try {
+            identity = JSON.parse(owner.record_json);
+            if (!identity || !Number.isSafeInteger(identity.pid) || identity.pid <= 1 || typeof identity.host !== "string" || typeof identity.processStart !== "string")
+                throw new Error("invalid owner fields");
+        }
+        catch {
+            throw new Error("Rafi cannot verify the saved build owner because its record is damaged. Run `rafi doctor .` to inspect recovery state; preserve the database before repairing it. Ticket inspection remains available.");
+        }
+        const state = classifyProcess(identity.pid, identity.processStart, identity.host).state;
+        if (state !== "dead")
+            throw new Error(`Rafi cannot upgrade build storage: the saved build owner is ${state} (PID ${identity.pid}, host ${identity.host}). Run \`rafi status .\` and \`rafi doctor .\`. Verify and stop the build on its owning host before retrying. Ticket show, validate, and queue remain available; Rafi has not taken over the build.`);
     }
     const backup = db.serialize();
     // The coherent WAL-visible backup survives even a rolled-back upgrade.

package/dist/cli/doctor.js

@@ -12,6 +12,7 @@ import { ObservabilityReader, ObservabilityStore } from "../observability.js";
 import { WorkflowReader } from "../workflowReader.js";
 import { WorkflowDb } from "../workflowDb.js";
 import { error, success, warning } from "../terminalStyle.js";
+import { readInterviewRecords } from "../interviews.js";
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))?.version;
 function commandVersion(command) {
     const result = spawnSync(command, ["--version"], {
@@ -54,6 +55,9 @@ export function buildDoctorCommand() {
         report(existsSync(cwd), "project directory exists", cwd);
         if (!existsSync(cwd))
             process.exit(1);
+        const unfinishedPlanning = readInterviewRecords(cwd).records.filter(record => record.status !== "completed");
+        if (unfinishedPlanning.length)
+            warn("saved planning sessions", `${unfinishedPlanning.length} unfinished; run \`rafi plan:doctor\` to select and recover one`);
         try {
             loadConfig(join(cwd, "foreman.yaml"));
             report(true, "foreman.yaml", existsSync(join(cwd, "foreman.yaml")) ? "valid" : "not present, using defaults");

package/dist/cli/manager.js

@@ -20,7 +20,7 @@ import { collectManagerProjectDiagnostics, executeManagerEvidenceRequest, MANAGE
 import { accent, sanitizeTerminalText } from "../terminalStyle.js";
 export function buildManagerCommand(options = {}) {
     return new Command("manager")
-        .description("Inspect retained builds and enqueue explicitly scoped Builder/QA guidance.")
+        .description("Consult on setup, planning, tickets, builds, and QA, including before the first build.")
         .argument(options.requireProject ? "<project>" : "[project]", "project directory")
         .option("--run <run-id>", "set the initial focused build run")
         .option("--ask <question>", "ask one question and exit")
@@ -55,11 +55,11 @@ export async function runManager(projectDir, options) {
     const initialCollection = collectManagerProjectDiagnostics(projectDir, { initialFocusRunId: options.runId, question: options.ask, external: "off" });
     const initialReport = initialCollection.report;
     let currentFocusRunId = initialReport.initialFocusRunId;
-    let referencedRunIds = [currentFocusRunId];
+    let referencedRunIds = currentFocusRunId ? [currentFocusRunId] : [];
     const managerLabel = (text) => accent(text, { stream: output, env: process.env, machineReadable: Boolean(options.ask) });
     output.write(`${managerLabel("rafi manager")}: ${initialReport.totalRunCount} retained build run${initialReport.totalRunCount === 1 ? "" : "s"}\n`);
     output.write(`${managerLabel("rafi manager")}: verified active run ${sanitizeTerminalText(initialReport.verifiedActiveRunId ?? "none")}\n`);
-    output.write(`${managerLabel("rafi manager")}: initial focus ${sanitizeTerminalText(currentFocusRunId)}\n`);
+    output.write(`${managerLabel("rafi manager")}: initial focus ${sanitizeTerminalText(currentFocusRunId || "project setup and planning")}\n`);
     if (initialReport.staleRecoveryRunIds.length)
         output.write(`${managerLabel("rafi manager")}: stale recovery state ${initialReport.staleRecoveryRunIds.map(sanitizeTerminalText).join(", ")}\n`);
     const metadata = new ManagerSessionRecorder(projectDir);

package/dist/cli/start.js

@@ -34,6 +34,7 @@ import { loadTickets } from "../tickets/ticketLoader.js";
 import { StateDb } from "../tickets/stateDb.js";
 import { applySharedDeliveryBranch, applySizeBranchPolicy, buildBranchAuditInstruction, buildBranchPlan, parseAuditDependencies } from "../branch/planner.js";
 import { currentGitRef, ensureCleanBaseWorktree, generatedTrackerDirtyPaths } from "../branch/git.js";
+import { captureDirtyBaseline } from "../branch/dirtyBaseline.js";
 import { formatGitHubFailure, preflightGh } from "../branch/github.js";
 import { preflightGlab } from "../branch/gitlab.js";
 import { readDeliveryUnitSession, runBranchPlan } from "../branch/runner.js";
@@ -386,6 +387,8 @@ export function savedStartArguments(command, projectDir, opts) {
 }
 /** Pure validation shared by interactive start and persisted preparation. */
 export function validateStartOptions(opts, requireCount) {
+    if (opts.dirtyWork !== undefined && !["preserve", "include"].includes(opts.dirtyWork))
+        throw new Error("--dirty-work must be preserve or include");
     const recovery = Boolean(opts.resume || opts.continue || opts.recoverRun);
     const tickets = opts.ticket ?? [];
     if (!recovery && tickets.length > 1)
@@ -493,6 +496,7 @@ export function buildStartCommand() {
         .option("--builder-network", "request build-scoped builder internet access with separate explicit approval; rechecked on resume")
         .option("--builder-approvals", "allow the builder to request explicit per-operation sandbox approvals; QA stays restricted")
         .option("--keep-worktrees", "keep successful ticket worktrees for inspection")
+        .option("--dirty-work <mode>", "preserve | include: continue in isolated branches without merging into the dirty checkout")
         .option("--ticket <id>", "select one new ticket, or identify recovery tickets with --resume/--continue/--recover-run", collectTicket, [])
         .option("--skip-delivery-unit <id>", "skip one unfinished delivery unit for this run", collectTicket, [])
         .action(async (project, opts, command) => withBuildInvocation(async () => {
@@ -502,6 +506,11 @@ export function buildStartCommand() {
         catch (error) {
             fail(error.message);
         }
+        if (opts.dirtyWork) {
+            opts.branchPerTicket = true;
+            opts.completion = "none";
+            opts.keepWorktrees = true;
+        }
         const requestedTicketIds = opts.ticket ?? [];
         const recoveryIntent = Boolean(opts.resume || opts.continue || opts.recoverRun);
         if (!recoveryIntent && requestedTicketIds.length > 1)
@@ -549,6 +558,7 @@ export function buildStartCommand() {
         if (!existsSync(cwd))
             fail(`project directory not found: ${cwd}`);
         const recoveryRecord = opts.recoverRun ? readBuildRuns(cwd).find((run) => run.runId === opts.recoverRun) : undefined;
+        let dirtyWork = recoveryRecord?.runDecisions?.dirtyWork;
         if (opts.recoverRun && !recoveryRecord)
             fail(`recoverable build run not found: ${opts.recoverRun}`);
         const autonomyProfile = opts.autonomy;
@@ -745,6 +755,12 @@ export function buildStartCommand() {
                 fail("current-branch build recovery supports exactly one --ticket");
             }
             if (branchMode) {
+                if (dirtyWork) {
+                    branchDefaults.completionMode = "none";
+                    branchDefaults.createReview = false;
+                    branchDefaults.cleanupBranches = false;
+                    opts.keepWorktrees = true;
+                }
                 if (opts.resume && continueTickets.length > 1) {
                     fail("--resume <sessionId> in branch mode supports exactly one --ticket; use --continue for multiple tickets");
                 }
@@ -1682,7 +1698,7 @@ export function buildStartCommand() {
             if (branchMode) {
                 const ticketsConfig = loadTicketsConfig(cwd);
                 const allowedBaseDirtyPaths = generatedTrackerDirtyPaths(ticketsConfig.paths);
-                const baseWorktreePolicy = recoveryRecord ? "skip" : "enforce";
+                let baseWorktreePolicy = recoveryRecord ? "skip" : "enforce";
                 if (baseWorktreePolicy === "skip") {
                     const projection = recoveryRecord ? projectBuildRecovery(cwd, recoveryRecord) : undefined;
                     if (projection?.expectedChanges.length) {
@@ -1700,7 +1716,29 @@ export function buildStartCommand() {
                         ensureCleanBaseWorktree(cwd, { allowedDirtyPaths: allowedBaseDirtyPaths });
                     }
                     catch (err) {
-                        fail(err instanceof Error ? err.message : String(err));
+                        let mode = opts.dirtyWork;
+                        if (!mode && process.stdin.isTTY && process.stdout.isTTY && !opts.yes) {
+                            const choice = await select({ message: "Uncommitted work found. How should the isolated build start?", options: [
+                                    { value: "preserve", label: "Preserve changes; build from committed code (Recommended)" },
+                                    { value: "include", label: "Include current files as a private build baseline" },
+                                    { value: "stop", label: "Stop for manual commit or stash" },
+                                ] });
+                            if (isCancel(choice) || choice === "stop")
+                                return;
+                            mode = String(choice);
+                        }
+                        if (mode !== "preserve" && mode !== "include")
+                            fail(`${err instanceof Error ? err.message : String(err)}\nContinue safely with --dirty-work preserve (committed input) or --dirty-work include (current files). Both keep your checkout and index intact and retain isolated worktrees.`);
+                        const baseline = captureDirtyBaseline(cwd, mode);
+                        dirtyWork = { mode, ...baseline };
+                        opts.base = baseline.base;
+                        branchDefaults.completionMode = "none";
+                        branchDefaults.createReview = false;
+                        branchDefaults.cleanupBranches = false;
+                        branchDefaults.rootBaseBranches = false;
+                        opts.keepWorktrees = true;
+                        baseWorktreePolicy = "skip";
+                        console.log(`rafi: ${mode} dirty-work baseline ${baseline.base}; evidence ${baseline.recordPath}; results stay in isolated branches.`);
                     }
                 }
                 if (branchDefaults.createReview && branchDefaults.reviewProvider) {
@@ -1906,7 +1944,7 @@ export function buildStartCommand() {
                     builderCapabilities, tickets: plan.nodes.map((node) => node.ticket.id), deliveryUnit: selectedStacks.length ? selectedStacks.map((stack) => stack.id).join(",") : deliveryRun?.unit.id,
                     repositoryRoot: cwd, branchMode: branchPresentation.allocationMode, baseRef: plan.baseRef, builder: capturedBranchBuilder, qa: capturedBranchQa,
                     frozenPolicy, autonomyProfile, qaEnabled,
-                    runDecisions: { workMode: "branch-per-ticket", workModeSource, branchPrefix, branchPrefixSource: resolvedPrefix.source, autoCompactThresholdPercent: capturedBranchBuilder.auto_compact_threshold_percent ?? 65, thresholdSource: thresholdOverride === undefined ? "project" : "cli" },
+                    runDecisions: { dirtyWork, workMode: "branch-per-ticket", workModeSource, branchPrefix, branchPrefixSource: resolvedPrefix.source, autoCompactThresholdPercent: capturedBranchBuilder.auto_compact_threshold_percent ?? 65, thresholdSource: thresholdOverride === undefined ? "project" : "cli" },
                 });
                 activeContinuityRunId = masterRun.runId;
                 if (requiresBuildApproval(cwd, plan.nodes.map(node => node.ticket.id), autoApprovePlanUpdates, approvalConsequences) && plan.issues.every((issue) => !issue.blocking)) {

package/dist/cli/status.js

@@ -2,7 +2,7 @@ import { Command } from "commander";
 import { resolve, join } from "node:path";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { findResumableBranchSessions, formatBranchContinueCommand } from "../branch/resume.js";
-import { recoverableBuildRuns } from "../buildRuns.js";
+import { readBuildRuns, recoverableBuildRuns } from "../buildRuns.js";
 import { WORKFLOW_DB_FILE } from "../workflowDb.js";
 import { WorkflowReader } from "../workflowReader.js";
 import { formatWorkflowIssue } from "../outcomes.js";
@@ -39,7 +39,7 @@ export function runStatus(project) {
         workflow?.close();
         fail(`no foreman runs found under ${dir}`);
     }
-    const logs = readdirSync(dir)
+    const logs = (existsSync(dir) ? readdirSync(dir) : [])
         .filter((f) => f.endsWith(".jsonl"))
         .sort();
     if (logs.length === 0) {
@@ -63,6 +63,10 @@ export function runStatus(project) {
     const prEvents = records.filter((r) => ["pr-created", "pr-existing", "pr-failed"].includes(String(r.event)));
     const latestFailure = findLatestGitHubFailure(records);
     const batchEnd = [...records].reverse().find((r) => r.event === "batch-end");
+    const retainedRuns = readBuildRuns(projectDir).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    const byId = new Map(retainedRuns.map(run => [run.runId, run]));
+    const recordRunId = [...records].reverse().find(record => typeof record.runId === "string" && (byId.has(record.runId) || record.event === "step" || record.event === "batch-end" || String(record.event).startsWith("branch-")))?.runId;
+    const retainedRun = typeof recordRunId === "string" ? byId.get(recordRunId) : undefined;
     console.log(`${accent("foreman:")} latest run ${sanitizeTerminalText(logs[logs.length - 1] ?? "")}`);
     console.log(`${accent("foreman:")} ${steps.length} step record(s), ${escalations.length} escalation(s)`);
     if (branchEvents.length || prEvents.length) {
@@ -80,6 +84,9 @@ export function runStatus(project) {
         if (batchEnd.detail)
             console.log(`foreman: ${batchEnd.detail}`);
     }
+    else if (retainedRun?.status === "completed") {
+        console.log(`${accent("foreman:")} outcome — ${success("completed")} (durable build record ${sanitizeTerminalText(retainedRun.runId)})`);
+    }
     else {
         console.log(`${accent("ai-foreman:")} run is still in progress or did not finish`);
     }

package/dist/cli/tickets.d.ts

@@ -15,8 +15,10 @@ export declare function buildPopulateAgentRunOptions(opts: {
     fast?: boolean;
     yes?: boolean;
     log: Log;
+    resumeSession?: string;
 }): RoleBuilderOptions;
 interface PopulateCommandOptions {
+    interviewId?: string;
     project?: string;
     agent?: string;
     model?: string;
@@ -25,6 +27,7 @@ interface PopulateCommandOptions {
     fast?: boolean;
     yes?: boolean;
     authorizeRetire?: string[];
+    resumeSession?: string;
 }
 export declare function combineRequirementSelections(selected: string[], additions: string): string[];
 export declare function cmdPopulateCli(opts: PopulateCommandOptions): Promise<void>;
@@ -54,6 +57,7 @@ export interface TicketOwnershipReceipt {
     category: "tickets";
     origin: string;
 }
+export declare function ticketOwnershipReceipts(projectDir: string, commandName: string, _afterWrite: boolean): TicketOwnershipReceipt[];
 export declare function buildTicketsCommand(options?: {
     prepareOwnership?: (projectDir: string, receipts: TicketOwnershipReceipt[]) => void;
     recordOwnership?: (projectDir: string, receipts: TicketOwnershipReceipt[]) => void;

package/dist/cli/tickets.js

@@ -18,7 +18,7 @@ import { assertEffortLevel, createRoleBuilder, makeLogPath, readOnlyPermissionCo
 import { DEFAULT_TICKET_SETUP, configuredPlanningSources, configuredAppName, defaultAppName, detectDefaultBranch, detectPackageName, ensureRafiConfigForTicketSetup, externalSources, hasTicketSetupConfig, loadTicketSetupConfig, loadTicketSetupConfigWithDefaults, localSourcePaths, mergeTicketSetup, recommendedBuildDefaults, saveTicketSetupConfig, syncTicketLimits, ticketSourcesFromRegistry, urlSources, } from "../tickets/setupConfig.js";
 import { deactivateSource, discardStagedSourceCaptures, loadSourceRegistry, refreshSourceRegistry, registerSourceRequests, removeSource, saveSourceRegistry, } from "../sources/sourceRegistry.js";
 import { fetchAndSnapshotUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
-import { checkpointInterview, completeInterview, createInterviewRecord, failInterview, } from "../interviews.js";
+import { checkpointInterview, completeInterview, createInterviewRecord, failInterview, readInterviewRecords, resumeInterviewRecord, } from "../interviews.js";
 import { applyTicketPopulation, authorizeTicketRetirements, extractTicketPopulationProposal, materializeTicketPopulation, recoverTicketPublications, TICKET_POPULATION_PROPOSAL_END, TICKET_POPULATION_PROPOSAL_START } from "../ticketPopulation.js";
 import { loadTickets } from "../tickets/ticketLoader.js";
 import { resolveTicketPaths } from "../tickets/config.js";
@@ -164,6 +164,7 @@ export function buildPopulateAgentRunOptions(opts) {
         log: opts.log,
         permissionConfig: readOnlyPermissionConfig(),
         sandboxMode: "read-only",
+        resumeSessionId: opts.resumeSession,
     };
 }
 async function cmdSetupInitCli(opts) {
@@ -178,7 +179,7 @@ async function cmdSetupInitCli(opts) {
     let interview = beginTicketSetupInterview(dir, "tickets-setup-init", opts);
     if (hasTicketSetupConfig(dir)) {
         console.log("foreman tickets setup: existing setup found; opening setup:update");
-        await cmdSetupUpdateCli(opts);
+        await cmdSetupUpdateCli({ ...opts, interviewId: undefined });
         const existing = loadTicketSetupConfigWithDefaults(dir);
         await continueTrackerSetup(dir, opts, existing);
         if (interview)
@@ -372,6 +373,8 @@ async function cmdSetupUpdateCli(opts) {
     }
 }
 function beginTicketSetupInterview(projectDir, workflow, opts) {
+    if (opts.interviewId)
+        return checkpointInterview(projectDir, resumeInterviewRecord(projectDir, opts.interviewId, workflow), {});
     if (!shouldPrompt(opts))
         return undefined;
     const record = createInterviewRecord({
@@ -1228,6 +1231,10 @@ export async function cmdPopulateCli(opts) {
     const config = loadConfig(join(dir, "foreman.yaml"));
     let builder;
     let viewer;
+    const savedPlanning = opts.interviewId ? readInterviewRecords(dir).records.find(record => record.id === opts.interviewId && record.workflow === "tickets-populate" && record.status !== "completed") : undefined;
+    if (opts.interviewId && !savedPlanning)
+        throw new Error("Saved population session not found; run `rafi plan:doctor` to select another");
+    let planningRecord = checkpointInterview(dir, savedPlanning ?? createInterviewRecord({ workflow: "tickets-populate", invocation: { projectDir: dir, ...opts }, checkpoint: "agent-run", answers: { approvedPlanPath: approvedPlan.path, contextSources }, outputs: [approvedPlan.path, ".tickets/tickets.yaml"] }), {});
     try {
         const roleBuilder = await createRoleBuilder(buildPopulateAgentRunOptions({
             projectDir: dir,
@@ -1237,8 +1244,10 @@ export async function cmdPopulateCli(opts) {
             fast: opts.fast,
             yes: Boolean(opts.yes),
             log,
+            resumeSession: opts.resumeSession,
         }));
         builder = roleBuilder.builder;
+        planningRecord = checkpointInterview(dir, planningRecord, { runtime: { runtime: roleBuilder.runtime, model: roleBuilder.model, sessionId: builder.sessionId() } });
         viewer = printEvents(builder.events());
         const foreman = new Foreman(builder, log, { desktop: config.notifications.enabled, terminalBell: config.notifications.terminal_bell }, false, 3, dir);
         foreman.setGraphPurpose("ticket-population");
@@ -1251,6 +1260,7 @@ export async function cmdPopulateCli(opts) {
             console.log(`foreman tickets: context sources ${contextSources.join(" ")}`);
         }
         const turn = await foreman.runInstruction(buildPopulateInstruction(approvedPlan.path, contextSources, ticketsConfig.paths.progressDoc));
+        planningRecord = checkpointInterview(dir, planningRecord, { runtime: { runtime: roleBuilder.runtime, model: roleBuilder.model, sessionId: builder.sessionId() }, decisions: { ...planningRecord.decisions, proposalResponse: turn.result.text } });
         await builder.close();
         await viewer;
         log.write("ticket-populate", {
@@ -1261,7 +1271,7 @@ export async function cmdPopulateCli(opts) {
             isError: turn.result.isError,
         });
         if (turn.result.isError) {
-            fail(`builder turn errored: ${turn.result.text.slice(0, 200)}`);
+            throw new Error(`builder turn errored: ${turn.result.text.slice(0, 200)}`);
         }
         if (turn.status.kind === "blocked") {
             throw new Error(`blocked — ${turn.status.reason ?? "builder reported blocked"}`);
@@ -1291,12 +1301,14 @@ export async function cmdPopulateCli(opts) {
         }
         authorizeTicketRetirements(materialized.retirements, { interactiveConfirmed: retirementsConfirmed, authorizedIds: opts.authorizeRetire, computerRun: Boolean(opts.yes) });
         const applied = applyTicketPopulation(dir, materialized);
+        completeInterview(dir, planningRecord);
         console.log(`foreman tickets: populated atomically (run ${applied.runId}, transaction ${applied.transactionId})`);
     }
     catch (err) {
+        failInterview(dir, planningRecord, planningRecord.checkpoint, err);
         await builder?.close().catch(() => { });
         await viewer?.catch(() => { });
-        fail(String(err instanceof Error ? err.message : err));
+        fail(`${err instanceof Error ? err.message : String(err)}\nRecover with \`rafi plan:doctor\`.`);
     }
 }
 /** Resolve only the strategy. Context documents never select an import mode. */
@@ -1460,7 +1472,7 @@ function isApprovedPlanArtifact(projectDir, source, approvedDataPath) {
     return source.toLowerCase().endsWith(".md")
         && resolve(projectDir, source) === dataPath.replace(/\.json$/i, ".md");
 }
-function ticketOwnershipReceipts(projectDir, commandName, _afterWrite) {
+export function ticketOwnershipReceipts(projectDir, commandName, _afterWrite) {
     const candidates = [
         ".tickets/config.yaml", ".tickets/tickets.yaml", ".tickets/delivery.yaml", ".tickets/tracker-rules.md",
         ".tickets/schema/tickets.schema.json", ".tickets/migrations/001_init.sql", ".tickets/.gitignore",
@@ -1567,13 +1579,17 @@ export function buildTicketsCommand(options = {}) {
     tickets.hook("preAction", (_thisCommand, actionCommand) => {
         const commandOptions = actionCommand.opts();
         const projectDir = cwd(commandOptions);
+        if (["show", "validate"].includes(actionCommand.name()) || actionCommand.name() === "queue" && !commandOptions.refresh)
+            return;
         recoverTicketPublications(projectDir);
         recoverTicketResetPublications(projectDir);
-        if (options.prepareOwnership && !["show", "validate", "queue"].includes(actionCommand.name())) {
+        if (options.prepareOwnership && !["show", "validate", "queue", "plan"].includes(actionCommand.name())) {
             options.prepareOwnership(projectDir, ticketOwnershipReceipts(projectDir, actionCommand.name(), false));
         }
     });
     tickets.hook("postAction", (_thisCommand, actionCommand) => {
+        if (["show", "validate", "queue", "plan"].includes(actionCommand.name()))
+            return;
         if (!options.recordOwnership)
             return;
         const commandOptions = actionCommand.opts();
@@ -1583,6 +1599,7 @@ export function buildTicketsCommand(options = {}) {
     // ── setup:init / setup:update ─────────────────────────────────────────────
     tickets
         .command("setup:init")
+        .option("--interview-id <id>", "recover an exact saved setup interview (normally selected by plan:doctor)")
         .description("Configure ticket population, supporting context, and build defaults in rafi-config.yaml.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
         .option("--defaults", "skip prompts and use recommended ticket setup defaults")
@@ -1620,6 +1637,7 @@ export function buildTicketsCommand(options = {}) {
     });
     tickets
         .command("setup:update")
+        .option("--interview-id <id>", "recover an exact saved setup interview (normally selected by plan:doctor)")
         .description("Update ticket population, supporting context, and build settings in rafi-config.yaml.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
         .option("--defaults", "skip prompts and keep existing values unless explicit options are provided")
@@ -1716,6 +1734,8 @@ export function buildTicketsCommand(options = {}) {
         .option("--effort <level>", "reasoning effort level (low|medium|high|xhigh)")
         .option("--sources <paths...>", "supporting files, folders, URLs, or globs to check first")
         .option("--fast", "fast mode - lower latency")
+        .option("--resume-session <id>", "resume a saved Ticket Maker session (normally selected by plan:doctor)")
+        .option("--interview-id <id>", "recover an exact saved population interview (normally selected by plan:doctor)")
         .option("--authorize-retire <ids...>", "exact ticket IDs authorized to become obsolete in computer-run mode")
         .option("-y, --yes", "computer-run approval; retirements still require --authorize-retire exact IDs")
         .action(async (opts) => {
@@ -2231,6 +2251,8 @@ export function buildTicketsCommand(options = {}) {
             else {
                 for (const r of rows) {
                     console.log(`  ${r.rank}. [${r.status}] ${r.ticket}: ${r.title} (${r.priority}, blocked: ${r.blockedBy})`);
+                    if (r.status === "blocked")
+                        console.log(`     Next: ${sanitizeTerminalText(r.nextAction)}`);
                 }
             }
         }

package/dist/interviews.d.ts

@@ -1,6 +1,6 @@
 export declare const INTERVIEW_STATE_VERSION = 2;
 export declare const INTERVIEW_DIRECTORY = ".rafi/interviews";
-export type InterviewWorkflow = "create" | "plan" | "tickets-plan" | "tickets-setup-init" | "tickets-setup-update";
+export type InterviewWorkflow = "create" | "plan" | "tickets-plan" | "tickets-populate" | "tickets-setup-init" | "tickets-setup-update";
 export type InterviewStatus = "in_progress" | "paused" | "needs_review" | "completed" | "incompatible";
 export type InterviewStageStatus = "not_offered" | "offered" | "accepted" | "running" | "completed" | "skipped" | "paused" | "failed" | "cancelled";
 export interface InterviewRuntimeState {
@@ -62,6 +62,8 @@ export interface InterviewReadResult {
     problems: InterviewRecordProblem[];
 }
 export declare function interviewDirectory(projectDir: string): string;
+/** Select only an exact compatible unfinished interview; never create a replacement on a typo. */
+export declare function resumeInterviewRecord(projectDir: string, id: string, workflow: InterviewWorkflow): InterviewRecord;
 export declare function createInterviewRecord(input: {
     workflow: InterviewWorkflow;
     invocation: Record<string, unknown>;

package/dist/interviews.js

@@ -14,6 +14,13 @@ const COMPLETE_RETENTION_MS = 30 * 24 * 60 * 60 * 1_000;
 export function interviewDirectory(projectDir) {
     return join(resolve(projectDir), INTERVIEW_DIRECTORY);
 }
+/** Select only an exact compatible unfinished interview; never create a replacement on a typo. */
+export function resumeInterviewRecord(projectDir, id, workflow) {
+    const record = readInterviewRecords(projectDir).records.find(item => item.id === id && item.workflow === workflow && item.status !== "completed" && item.status !== "incompatible");
+    if (!record)
+        throw new Error(`Saved ${workflow} interview not found; run \`rafi plan:doctor\` to select another`);
+    return record;
+}
 export function createInterviewRecord(input) {
     const stamp = (input.now ?? new Date()).toISOString();
     return {

package/dist/managerPacket.js

@@ -15,7 +15,7 @@ export function buildManagerProjectPacket(report, question, previous, referenced
     const previousProject = previous && "projectDigest" in previous.report ? previous.report : undefined;
     const canDelta = Boolean(previousProject && previous?.currentFocusRunId === report.currentFocusRunId && previous.subject === subject);
     const payload = canDelta
-        ? { kind: "manager-project-update", generatedAt: report.generatedAt, projectDigest: report.projectDigest, currentFocusRunId: report.currentFocusRunId, verifiedActiveRunId: report.verifiedActiveRunId, statusDistribution: report.statusDistribution, allRuns: report.allRuns, successfulCompletedRuns: report.successfulCompletedRuns, topRuns: report.topRuns, sourceCoverage: report.sourceCoverage, focusedReports: report.focusedReports.map(boundSingleReport), changed: projectDelta(previousProject, report) }
+        ? { kind: "manager-project-update", projectState: report.projectState, generatedAt: report.generatedAt, projectDigest: report.projectDigest, currentFocusRunId: report.currentFocusRunId, verifiedActiveRunId: report.verifiedActiveRunId, statusDistribution: report.statusDistribution, allRuns: report.allRuns, successfulCompletedRuns: report.successfulCompletedRuns, topRuns: report.topRuns, sourceCoverage: report.sourceCoverage, focusedReports: report.focusedReports.map(boundSingleReport), changed: projectDelta(previousProject, report) }
         : { kind: "manager-project-diagnostic-report", report };
     const prompt = boundProjectPrompt(payload, report, question);
     return { prompt, state: { digest: report.digest, report, subject, projectDigest: report.projectDigest, runCatalogDigest: catalogDigest, perRunDigests: Object.fromEntries(report.runCatalog.map(item => [item.runId, item.digest])), detailedReportDigests: Object.fromEntries(report.focusedReports.map(item => [item.runId, item.digest])), currentFocusRunId: report.currentFocusRunId, referencedRunIds, previousAggregateResults: [report.allRuns, report.successfulCompletedRuns] } };
@@ -47,6 +47,7 @@ export function buildManagerEvidencePacketV2(response, question) {
 function instructions(question, payload) {
     return [
         "You are the Rafi Manager. The project, not one run, is the default scope. Answer only from host-calculated evidence.",
+        "Use projectState to help with create, plan, tickets, validation, dirty work, and recovery before or between builds. Zero retained builds is a valid setup state. Recommend public Rafi commands, including rafi plan:doctor for saved planning failures. Never invent a build ID or issue build controls without a real run.",
         "An accepted successor has acknowledged context; that alone does not prove implementation was dispatched. Distinguish acceptance, adoption, dispatch, completion, pending human decisions, and uncertain work. Identify the worktree when code may be outside the main checkout.",
         "Identify every run-specific claim with its run ID. Distinguish verified active, stale recovery, recoverable, completed, failed, superseded, and legacy runs.",
         "For cumulative claims, report metric coverage and exclusions. Missing data is unavailable, never zero. Performance abnormality requires at least five successful completed runs.",

package/dist/projectDiagnostics.js

@@ -1,5 +1,29 @@
 import { hostname } from "node:os";
-import { resolve } from "node:path";
+import { join, resolve } from "node:path";
+import { existsSync } from "node:fs";
+import { execFileSync } from "node:child_process";
+import { readInterviewRecords } from "./interviews.js";
+import { cmdQueue, cmdValidate } from "./tickets/commands.js";
+import { getAllTicketDetails } from "./tickets/details.js";
+function collectProjectState(root) {
+    const state = { configPresent: existsSync(join(root, "rafi-config.yaml")), dirtyPaths: [], planningSessions: [], errors: [] };
+    const sessions = readInterviewRecords(root);
+    state.planningSessions = sessions.records.map(record => ({ id: record.id, workflow: record.workflow, status: record.status, checkpoint: record.checkpoint, updatedAt: record.updatedAt, failure: record.failure?.summary }));
+    state.errors.push(...sessions.problems.map(problem => `${problem.path}: ${problem.reason}`));
+    try {
+        state.dirtyPaths = execFileSync("git", ["status", "--porcelain", "--untracked-files=all"], { cwd: root, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }).trim().split("\n").filter(Boolean).slice(0, 100);
+    }
+    catch { /* projects need not use Git */ }
+    if (existsSync(join(root, ".tickets/config.yaml"))) {
+        try {
+            state.tickets = { count: getAllTicketDetails(root).ticket_count, queue: cmdQueue(root), validationIssues: cmdValidate(root).issues };
+        }
+        catch (error) {
+            state.errors.push(String(error));
+        }
+    }
+    return state;
+}
 import { BUILD_LEASE_STALE_MS, readBuildRuns } from "./buildRuns.js";
 import { collectManagerDiagnostics } from "./diagnostics.js";
 import { diagnosticDigest, ObservabilityReader } from "./observability.js";
@@ -33,16 +57,15 @@ export function collectManagerProjectDiagnostics(projectDir, options = {}) {
         const rollupById = new Map(rollups.map(rollup => [rollup.runId, rollup]));
         const workflowById = new Map(workflowRuns.map(run => [run.runId, run]));
         const ids = new Set([...buildById.keys(), ...storedById.keys(), ...rollupById.keys(), ...workflowById.keys()]);
-        if (!ids.size)
-            throw new Error("no build runs found for this project; start one with `rafi start` before opening Manager");
+        const projectState = collectProjectState(root);
         const defaultFocus = activeRunId && ids.has(activeRunId)
             ? activeRunId
-            : [...ids].sort((a, b) => runUpdatedAt(b, buildById, storedById, workflowById, rollupById).localeCompare(runUpdatedAt(a, buildById, storedById, workflowById, rollupById)))[0];
+            : [...ids].sort((a, b) => runUpdatedAt(b, buildById, storedById, workflowById, rollupById).localeCompare(runUpdatedAt(a, buildById, storedById, workflowById, rollupById)))[0] ?? "";
         const initialFocus = options.initialFocusRunId ?? defaultFocus;
-        if (!ids.has(initialFocus))
+        if (initialFocus && !ids.has(initialFocus))
             throw new Error(`build run not found: ${initialFocus}`);
         const currentFocus = options.currentFocusRunId ?? initialFocus;
-        if (!ids.has(currentFocus))
+        if (currentFocus && !ids.has(currentFocus))
             throw new Error(`build run not found: ${currentFocus}`);
         const summaries = [...ids].map(runId => mergeSummary({ runId, build: buildById.get(runId), stored: storedById.get(runId), rollup: rollupById.get(runId), workflow: workflowById.get(runId), activeRunId, leaseRunId: lease?.runId, now, schemaVersion: observability.schemaVersion() }))
             .sort((a, b) => b.updatedAt.localeCompare(a.updatedAt) || b.createdAt.localeCompare(a.createdAt) || a.runId.localeCompare(b.runId));
@@ -74,10 +97,11 @@ export function collectManagerProjectDiagnostics(projectDir, options = {}) {
         const staleRecoveryRunIds = summaries.filter(item => item.activeState === "stale_recovery").map(item => item.runId);
         const completedDates = summaries.filter(item => item.status === "completed").map(item => item.completedAt).filter((item) => Boolean(item)).sort();
         const createdDates = summaries.map(item => item.createdAt).sort();
-        const projectBasis = { ids: summaries.map(item => [item.runId, item.digest]), activeRunId, initialFocus, currentFocus };
+        const projectBasis = { ids: summaries.map(item => [item.runId, item.digest]), activeRunId, initialFocus, currentFocus, projectState };
         const withoutDigest = {
             version: 1, generatedAt: now.toISOString(), projectDigest: diagnosticDigest(projectBasis), totalRunCount: summaries.length,
-            dateRange: { earliestCreatedAt: createdDates[0], latestCreatedAt: createdDates.at(-1), ...(completedDates.length ? { latestCompletedAt: completedDates.at(-1) } : {}) },
+            projectState,
+            ...(createdDates.length ? { dateRange: { earliestCreatedAt: createdDates[0], latestCreatedAt: createdDates.at(-1), ...(completedDates.length ? { latestCompletedAt: completedDates.at(-1) } : {}) } } : {}),
             statusDistribution, capabilityDistribution, ...(activeRunId ? { verifiedActiveRunId: activeRunId } : {}), staleRecoveryRunIds,
             initialFocusRunId: initialFocus, currentFocusRunId: currentFocus, allRuns, successfulCompletedRuns, topRuns,
             runCatalog, omittedRunCount: Math.max(0, summaries.length - runCatalog.length), focusedReports,

package/dist/recoveryPolicy.js

@@ -71,7 +71,7 @@ export function validateAutonomyConfig(value) {
     if (deadlines !== undefined) {
         if (!deadlines || typeof deadlines !== "object" || Array.isArray(deadlines))
             throw new Error("autonomy.runtime_deadlines must be an object");
-        rejectUnknown(deadlines, ["preparation_ms", "rpc_ms", "compaction_ms", "shutdown_ms", "turn_ms"], "autonomy.runtime_deadlines");
+        rejectUnknown(deadlines, ["preparation_ms", "rpc_ms", "compaction_ms", "shutdown_ms", "turn_ms", "heartbeat_ms"], "autonomy.runtime_deadlines");
         for (const [key, value] of Object.entries(deadlines))
             if (!Number.isSafeInteger(value) || Number(value) < 1 || Number(value) > (key === "compaction_ms" ? 180_000 : 86_400_000))
                 throw new Error(`invalid runtime deadline ${key}`);

package/dist/supervisedStart.js

@@ -202,10 +202,11 @@ export async function superviseStart(projectDir, runId, policy, selection) {
                 }
                 catch { /* exited */ }
             };
-            const watchdog = setInterval(() => { if (Date.now() - lastHeartbeat > 120_000) {
+            const heartbeatTimeout = policy.runtimeDeadlines?.heartbeat_ms ?? 120_000;
+            const watchdog = setInterval(() => { if (Date.now() - lastHeartbeat > heartbeatTimeout) {
                 stopRequestSource = "heartbeat-timeout";
                 stop();
-            } }, 5_000);
+            } }, Math.min(5_000, Math.max(25, heartbeatTimeout / 4)));
             watchdog.unref();
             child.on("message", message => { if (message && typeof message === "object" && "kind" in message && message.kind === "rafi-worker-heartbeat")
                 lastHeartbeat = Date.now(); });

package/dist/ticketPlanning.d.ts

@@ -64,11 +64,15 @@ export interface TicketPlanningContext {
     }>;
     existingNext: string[];
 }
+/** The tracker facts needed to validate a proposal before it is approved. */
+export interface TicketPlanValidationContext {
+    futureWorkIds?: Iterable<number>;
+}
 export declare function readTicketPlanningContext(projectDir: string): TicketPlanningContext;
 export declare function ticketPlanningFingerprint(projectDir: string): PlanningFingerprint[];
 export declare function planningFingerprintChanges(projectDir: string, expected: PlanningFingerprint[]): string[];
-export declare function extractTicketPlanProposal(output: string, existingTickets?: TicketDef[]): TicketPlanProposal;
-export declare function validateTicketPlanProposal(value: unknown, existingTickets?: TicketDef[]): string[];
+export declare function extractTicketPlanProposal(output: string, existingTickets?: TicketDef[], context?: TicketPlanValidationContext): TicketPlanProposal;
+export declare function validateTicketPlanProposal(value: unknown, existingTickets?: TicketDef[], context?: TicketPlanValidationContext): string[];
 export interface ApplyTicketPlanOptions {
     expectedFingerprint: PlanningFingerprint[];
     docsRoot: string;

package/dist/ticketPlanning.js

@@ -12,6 +12,9 @@ import { normalizeDeliveryConfig, validateDeliveryConfig } from "./tickets/deliv
 import { loadTicketSetupConfig, mergeTicketSetup, saveTicketSetupConfig } from "./tickets/setupConfig.js";
 export const PROPOSAL_START = "RAFI_PROPOSAL_START";
 export const PROPOSAL_END = "RAFI_PROPOSAL_END";
+const TICKET_STATUSES = new Set([
+    "planned", "next", "in_progress", "blocked", "done", "canceled", "obsolete",
+]);
 export function readTicketPlanningContext(projectDir) {
     const config = loadTicketsConfig(projectDir);
     const paths = resolveTicketPaths(config, projectDir);
@@ -41,7 +44,7 @@ export function ticketPlanningFingerprint(projectDir) {
 export function planningFingerprintChanges(projectDir, expected) {
     return expected.filter((item) => fileHash(join(projectDir, item.path)) !== item.sha256).map((item) => item.path);
 }
-export function extractTicketPlanProposal(output, existingTickets = []) {
+export function extractTicketPlanProposal(output, existingTickets = [], context = {}) {
     const start = output.lastIndexOf(PROPOSAL_START);
     const end = output.lastIndexOf(PROPOSAL_END);
     if (start < 0 || end <= start)
@@ -54,12 +57,12 @@ export function extractTicketPlanProposal(output, existingTickets = []) {
     catch (err) {
         throw new Error(`planner proposal is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
     }
-    const issues = validateTicketPlanProposal(parsed, existingTickets);
+    const issues = validateTicketPlanProposal(parsed, existingTickets, context);
     if (issues.length)
         throw new Error(`invalid planner proposal:\n${issues.map((issue) => `- ${issue}`).join("\n")}`);
     return parsed;
 }
-export function validateTicketPlanProposal(value, existingTickets = []) {
+export function validateTicketPlanProposal(value, existingTickets = [], context = {}) {
     const issues = [];
     if (!value || typeof value !== "object" || Array.isArray(value))
         return ["proposal must be an object"];
@@ -109,9 +112,26 @@ export function validateTicketPlanProposal(value, existingTickets = []) {
             if (!ids.has(id))
                 issues.push(`supersession references unknown ticket ${id}`);
     }
-    for (const change of p.state_changes)
-        if (!ids.has(change.id) || !change.reason?.trim())
-            issues.push(`invalid state change for ${change.id}`);
+    for (const change of p.state_changes) {
+        if (!change || typeof change !== "object" || !ids.has(change.id) || !change.reason?.trim()) {
+            issues.push(`invalid state change for ${String(change && typeof change === "object" ? change.id : undefined)}`);
+            continue;
+        }
+        if (!TICKET_STATUSES.has(change.status))
+            issues.push(`state change for ${change.id} has invalid status ${String(change.status)}`);
+    }
+    const futureWorkIds = context.futureWorkIds ? new Set(context.futureWorkIds) : undefined;
+    for (const disposition of p.future_work) {
+        if (!disposition || typeof disposition !== "object" || !Number.isInteger(disposition.id)) {
+            issues.push(`future work disposition has invalid id ${String(disposition && typeof disposition === "object" ? disposition.id : undefined)}`);
+            continue;
+        }
+        if (!["accepted", "rejected", "merged", "queued"].includes(disposition.disposition)) {
+            issues.push(`future work item ${disposition.id} has invalid disposition ${String(disposition.disposition)}`);
+        }
+        if (futureWorkIds && !futureWorkIds.has(disposition.id))
+            issues.push(`future work item ${disposition.id} does not exist`);
+    }
     for (const item of p.source_reconciliation) {
         if (!item.source?.trim() || !item.item?.trim())
             issues.push("source reconciliation needs source and item");
@@ -151,7 +171,8 @@ export function applyApprovedTicketPlan(projectDir, proposal, opts) {
     const existing = loadTickets(paths.tickets);
     if (existing.length > 0 && !existsSync(paths.stateDb))
         throw new Error("tickets exist but the ignored ticket-state database is missing; restore it before planning so completed work is not treated as new");
-    const proposalIssues = validateTicketPlanProposal(proposal, existing);
+    const currentContext = readTicketPlanningContext(root);
+    const proposalIssues = validateTicketPlanProposal(proposal, existing, { futureWorkIds: currentContext.futureWork.flatMap((item) => typeof item.id === "number" ? [item.id] : []) });
     if (proposalIssues.length)
         throw new Error(`approved proposal is invalid:\n${proposalIssues.map((issue) => `- ${issue}`).join("\n")}`);
     const lockPath = join(root, ".tickets", "planning.lock");

package/dist/tickets/commands.d.ts

@@ -11,7 +11,7 @@ export interface TicketContext {
     tickets: TicketDef[];
     db: StateDb;
 }
-export declare function openContext(projectDir: string): TicketContext;
+export declare function openContext(projectDir: string, readOnly?: boolean): TicketContext;
 export interface InitOptions {
     appName?: string;
     timezone?: string;

package/dist/tickets/commands.js

@@ -1,4 +1,4 @@
-import { mkdirSync, writeFileSync } from "node:fs";
+import { mkdirSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
 import { stringify } from "yaml";
 import { DEFAULT_TICKETS_CONFIG, initDocsRoot, loadTicketsConfig, pathExistsOrSymlink, resolveTicketPaths, isTicketsInitialized, } from "./config.js";
@@ -12,15 +12,15 @@ import { loadDeliveryConfig, saveDeliveryConfig } from "./delivery.js";
 import { checkGitHubPrMerged } from "../branch/github.js";
 import { checkGitLabMrMerged } from "../branch/gitlab.js";
 import { cmdReviewRecommendations } from "./recommendations.js";
-export function openContext(projectDir) {
+export function openContext(projectDir, readOnly = false) {
     const config = loadTicketsConfig(projectDir);
     const paths = resolveTicketPaths(config, projectDir);
     const tickets = loadTickets(paths.tickets);
-    const db = new StateDb(paths.stateDb);
+    const db = new StateDb(paths.stateDb, { readOnly });
     return { config, projectDir, paths, tickets, db };
 }
-function withContext(projectDir, fn) {
-    const ctx = openContext(projectDir);
+function withContext(projectDir, fn, readOnly = false) {
+    const ctx = openContext(projectDir, readOnly);
     try {
         return fn(ctx);
     }
@@ -472,15 +472,17 @@ export function cmdValidate(projectDir) {
     return withContext(projectDir, (ctx) => {
         const states = ctx.db.getAllStates();
         const issues = runAllValidation(ctx.config, projectDir, ctx.tickets, states, ctx.db);
+        if (ctx.tickets.length && !existsSync(ctx.paths.stateDb))
+            issues.push({ pass: 2, severity: "error", message: `[state] ticket history database is missing: ${ctx.config.paths.stateDb}. Restore it before building; inspection has not recreated history or assumed completed work is new.` });
         return { issues, clean: issues.filter((i) => i.severity === "error").length === 0 };
-    });
+    }, true);
 }
 // ── queue ─────────────────────────────────────────────────────────────────────
 export function cmdQueue(projectDir, limit) {
     return withContext(projectDir, (ctx) => {
         const states = ctx.db.getAllStates();
         return buildNextQueue(ctx.tickets, states, limit ?? ctx.config.viewLimit);
-    });
+    }, true);
 }
 export function cmdStackQueue(projectDir, refresh = false) {
     return withContext(projectDir, (ctx) => {
@@ -506,13 +508,13 @@ export function cmdStackQueue(projectDir, refresh = false) {
             saveDeliveryConfig(projectDir, delivery);
         }
         return formatStackAwareQueue(ctx.tickets, ctx.db.getAllStates(), delivery);
-    });
+    }, !refresh);
 }
 export function cmdImplementationQueue(projectDir) {
     return withContext(projectDir, (ctx) => {
         const states = ctx.db.getAllStates();
         return buildNextQueue(ctx.tickets, states, ctx.config.implementationLimit);
-    });
+    }, true);
 }
 // ── archive ───────────────────────────────────────────────────────────────────
 export function cmdArchive(projectDir, _opts) {

package/dist/tickets/details.js

@@ -13,7 +13,7 @@ export function getTicketDetails(projectDir, ticketId, now = new Date()) {
     const definition = tickets.find((ticket) => ticket.id === ticketId);
     if (!definition)
         throw new Error(`Ticket ${ticketId} not found. Run \`rafi tickets queue\` to list tickets.`);
-    const db = new StateDb(paths.stateDb);
+    const db = new StateDb(paths.stateDb, { readOnly: true });
     try {
         const states = db.getAllStates();
         const state = states.get(ticketId) ?? pristineTicketState(ticketId, now.toISOString());
@@ -32,7 +32,7 @@ export function getAllTicketDetails(projectDir, now = new Date()) {
     const definitions = loadTickets(paths.tickets)
         .sort((left, right) => left.order - right.order || left.id.localeCompare(right.id));
     const generatedAt = now.toISOString();
-    const db = new StateDb(paths.stateDb);
+    const db = new StateDb(paths.stateDb, { readOnly: true });
     try {
         const states = db.getAllStates();
         const validations = groupByTicketId(db.getValidationSnapshots(), (snapshot) => snapshot.scope);

package/dist/tickets/queue.js

@@ -31,7 +31,7 @@ export function buildNextQueue(ticketDefs, states, queueLimit) {
             blockedBy: blockedBy.length ? blockedBy.join(", ") : "None",
             size: ticket.size,
             risk: ticket.risk,
-            nextAction: state?.next_action ?? (displayStatus === "blocked" && !blockedBy.length ? `Resolve blocker: ${state?.blocker_notes ?? "external prerequisite requires recovery"}` : defaultNextAction(ticket, displayStatus, blockedBy)),
+            nextAction: state?.next_action ?? (displayStatus === "blocked" && !blockedBy.length ? state?.blocker_notes ? `Resolve blocker: ${state.blocker_notes}` : `No blocker reason was saved. Run \`rafi status .\` to inspect interrupted builds, then \`rafi build:resume .\` if recoverable; otherwise record the prerequisite before unblocking ${ticket.id}.` : defaultNextAction(ticket, displayStatus, blockedBy)),
             requiredTests: ticket.required_tests.join("; "),
             evidence: state?.evidence ?? "N/A until implemented.",
             likelyFiles: ticket.likely_files.length ? ticket.likely_files.join(", ") : "unknown",

package/dist/tickets/stateDb.d.ts

@@ -100,7 +100,10 @@ export interface TicketGroupValidationIssue {
 export declare function pristineTicketState(ticketId: string, now: string, actor?: string | null): TicketState;
 export declare class StateDb {
     private db;
-    constructor(dbPath: string);
+    readonly readOnly: boolean;
+    constructor(dbPath: string, options?: {
+        readOnly?: boolean;
+    });
     private migrateObsoleteStatus;
     close(): void;
     getState(ticketId: string): TicketState | undefined;

package/dist/tickets/stateDb.js

@@ -1,5 +1,5 @@
 import Database from "better-sqlite3";
-import { mkdirSync } from "node:fs";
+import { existsSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 import { createHash } from "node:crypto";
 /** The only valid initial/fully-reset active state for a ticket. */
@@ -174,7 +174,16 @@ CREATE INDEX IF NOT EXISTS idx_ticket_group_members_group ON ticket_group_member
 `;
 export class StateDb {
     db;
-    constructor(dbPath) {
+    readOnly;
+    constructor(dbPath, options = {}) {
+        this.readOnly = Boolean(options.readOnly);
+        if (this.readOnly) {
+            this.db = existsSync(dbPath) ? new Database(dbPath, { readonly: true, fileMustExist: true }) : new Database(":memory:");
+            if (!existsSync(dbPath))
+                this.db.exec(INIT_SQL);
+            this.db.pragma("query_only = ON");
+            return;
+        }
         mkdirSync(dirname(dbPath), { recursive: true });
         this.db = new Database(dbPath);
         this.db.pragma("journal_mode = WAL");
@@ -472,11 +481,15 @@ export class StateDb {
         return row ? this.getTicketGroupBySequence(row.sequence) : undefined;
     }
     listTicketGroups() {
+        if (this.readOnly && !this.db.prepare("SELECT 1 FROM sqlite_master WHERE name='ticket_groups'").get())
+            return [];
         const rows = this.db.prepare("SELECT sequence FROM ticket_groups ORDER BY sequence DESC").all();
         return rows.map((row) => this.getTicketGroupBySequence(row.sequence));
     }
     /** One-time migration for repositories whose complete ticket set predates groups. */
     ensureSyntheticLegacyGroup(definitions, now = new Date()) {
+        if (this.readOnly)
+            return undefined;
         if (definitions.length === 0 || this.listTicketGroups().length > 0)
             return undefined;
         return this.createTicketGroup({
@@ -503,6 +516,9 @@ export class StateDb {
     validateTicketGroups(knownTicketIds = []) {
         const issues = [];
         const groups = this.listTicketGroups();
+        // Ungrouped legacy trackers are inspected without publishing a synthetic group.
+        if (this.readOnly && groups.length === 0 && (!this.db.prepare("SELECT 1 FROM sqlite_master WHERE name='ticket_group_sequence_ledger'").get() || !(this.db.prepare("SELECT 1 FROM ticket_group_sequence_ledger LIMIT 1").get())))
+            return issues;
         const known = new Set(knownTicketIds);
         for (const group of groups) {
             if (group.members.length === 0)

package/dist/tickets/validate.js

@@ -57,7 +57,10 @@ export function runAllValidation(config, projectDir, ticketDefs, states, db) {
     }
     const blockedWithNone = queueRows.filter((r) => r.status === "blocked" && r.blockedBy === "None");
     for (const r of blockedWithNone) {
-        issues.push({ pass: 3, severity: "error", message: `[queue] ${r.ticket} is blocked but Blocked By is None` });
+        const state = states.get(r.ticket);
+        if (state?.blocker_notes?.trim())
+            continue;
+        issues.push({ pass: 3, severity: "error", message: `[queue] ${r.ticket} is blocked but no blocker or reason was saved. Inspect \`rafi status .\` for interrupted builds; recover with \`rafi build:resume .\` when appropriate, or record the prerequisite with \`rafi tickets block ${r.ticket} --summary "reason"\`.` });
     }
     // Pass 4: generated Markdown doc
     const progressDocPath = join(projectDir, config.paths.progressDoc);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.7.21",
+  "version": "1.7.23",
   "description": "An orchestrator that keeps Codex CLI / Claude Code builders moving through their step list unattended. Part of Rafi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -275,7 +275,7 @@
   "scripts": {
     "build": "tsc -p tsconfig.build.json && node scripts/copy-graph-assets.mjs",
     "dev": "tsx src/index.ts",
-    "test": "tsx --test --test-concurrency=1 test/*.test.ts test/*.test.mjs",
+    "test": "node scripts/test-offline.mjs",
     "typecheck": "tsc --noEmit",
     "test:live-providers": "RAFI_LIVE_PROVIDER_SESSIONS=1 tsx --test test/providerSmoke.test.ts",
     "prepublishOnly": "tsc -p ../spec/tsconfig.build.json && pnpm build && pnpm --filter ai-foreman test && tsc --noEmit"
@@ -307,8 +307,8 @@
     "luxon": "^3.7.2",
     "parse5": "7.2.1",
     "pdfjs-dist": "4.10.38",
-    "rafi-spec": "0.8.14",
-    "special-agents": "0.8.13",
+    "rafi-spec": "0.8.15",
+    "special-agents": "0.8.14",
     "yaml": "^2.5.1"
   },
   "devDependencies": {