ai-foreman 1.7.11 → 1.7.13

package/dist/buildRuns.js

@@ -4,24 +4,31 @@ import { hostname } from "node:os";
 import { join, resolve } from "node:path";
 import { execFileSync } from "node:child_process";
 import Database from "better-sqlite3";
-import { WorkflowDb } from "./workflowDb.js";
+import { WorkflowDb, heartbeatCurrentWorkflowLease, readCurrentWorkflowLease } from "./workflowDb.js";
+import { WorkflowReader } from "./workflowReader.js";
 import { canonicalSessionPath, captureWorkspaceIdentity, createProviderSessionRef, latestSessionBinding, upsertSessionBinding } from "./sessionIdentity.js";
 import { resolveProviderSessionAvailability } from "./sessionAvailability.js";
 import { captureCurrentWorkflowSessionIdentity, currentWorkflowIdentityKey } from "./branch/currentGuard.js";
 import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "./tickets/config.js";
 import { loadTickets } from "./tickets/ticketLoader.js";
-export const BUILD_RUN_VERSION = 2;
+import { loadProjectAutonomyConfig, resolveAutonomyPolicy } from "./recoveryPolicy.js";
+export const BUILD_RUN_VERSION = 3;
 export const BUILD_RUN_DIRECTORY = ".foreman/runs";
 export const BUILD_HEARTBEAT_MS = 10_000;
 export const BUILD_LEASE_STALE_MS = 45_000;
 export function createBuildRun(input) {
     const now = input.now ?? new Date();
+    // Complete the one-time legacy import before the new mutable build snapshot
+    // exists, so a brand-new run is never mistaken for legacy input.
+    const migration = new WorkflowDb(input.repositoryRoot);
+    migration.close();
     const stamp = now.toISOString();
     const worktree = resolve(input.worktree ?? input.repositoryRoot);
     const snapshot = captureGitSnapshot(worktree, input);
+    const frozenPolicy = input.frozenPolicy ?? resolveAutonomyPolicy(loadProjectAutonomyConfig(input.repositoryRoot), input.autonomyProfile, now);
     const run = {
-        version: 2,
-        runId: randomUUID(),
+        version: 3,
+        runId: input.runId ?? randomUUID(),
         status: "running",
         tickets: [...input.tickets],
         deliveryUnit: input.deliveryUnit,
@@ -40,6 +47,13 @@ export function createBuildRun(input) {
             baselineComplete: Boolean(snapshot.baselineHead && snapshot.startHead && snapshot.branch),
         },
         progress: { completedTickets: [], completedOperations: [], remainingTickets: [...input.tickets], nextAction: input.tickets[0] ? `Start ${input.tickets[0]}` : "Plan next work" },
+        frozenPolicy,
+        phase: "created",
+        qaEnabled: input.qaEnabled ?? Boolean(input.qa),
+        recoveryAttempts: [],
+        supervisor: { status: frozenPolicy.supervisorEnabled ? "starting" : "disabled", generation: 0, workerGeneration: 0, checkpointRestarts: 0, runRestarts: 0 },
+        pendingDecisions: [],
+        deferredTickets: [],
         runDecisions: input.runDecisions,
         receipts: {},
         lease: currentLease(now),
@@ -95,18 +109,17 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
     validateBuildRun(run);
     const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
     mkdirSync(directory, { recursive: true });
-    const completedOperations = Object.keys(run.receipts).sort();
-    const next = {
-        ...run,
+    const upgraded = upgradeBuildRun(run, projectDir, now);
+    const completedOperations = Object.keys(upgraded.receipts).sort();
+    let next = {
+        ...upgraded,
         progress: { ...run.progress, completedOperations, remainingTickets: remainingTickets(run) },
         updatedAt: now.toISOString(),
     };
-    const target = join(directory, `${run.runId}.json`);
-    const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
-    writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
-    renameSync(temp, target);
     const workflow = new WorkflowDb(projectDir);
     try {
+        const frozenPolicy = workflow.freezeAutonomyPolicy(next.runId, next.frozenPolicy, now);
+        next = { ...next, frozenPolicy, recoveryAttempts: workflow.recoveryAttempts(next.runId), pendingDecisions: workflow.pendingHumanDecisions(next.runId), supervisor: workflow.supervisorState(next.runId) ?? next.supervisor };
         const existing = workflow.getRun(next.runId);
         if (!existing)
             workflow.createRun({
@@ -127,6 +140,10 @@ export function saveBuildRun(projectDir, run, now = new Date()) {
     finally {
         workflow.close();
     }
+    const target = join(directory, `${run.runId}.json`);
+    const temp = `${target}.${process.pid}.${randomUUID()}.tmp`;
+    writeFileSync(temp, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    renameSync(temp, target);
     return next;
 }
 export function checkpointBuildRun(projectDir, run, checkpoint, patch = {}) {
@@ -185,17 +202,11 @@ export function recordBuildReceipt(projectDir, run, operationId, detail) {
     return next;
 }
 export function heartbeatBuildRun(projectDir, run, now = new Date()) {
-    const saved = saveBuildRun(projectDir, { ...run, lease: { ...(run.lease ?? currentLease(now)), heartbeatAt: now.toISOString() } }, now);
-    const workflow = new WorkflowDb(projectDir);
-    try {
-        const lease = workflow.currentLease();
-        if (lease?.runId === run.runId)
-            workflow.heartbeatLease(lease, now);
-    }
-    finally {
-        workflow.close();
-    }
-    return saved;
+    const lease = readCurrentWorkflowLease(projectDir);
+    if (!lease || lease.runId !== run.runId)
+        throw new Error("workflow lease ownership changed");
+    const next = heartbeatCurrentWorkflowLease(projectDir, lease, now);
+    return { ...run, lease: { hostname: next.host, pid: next.pid, processStart: next.processStart, heartbeatAt: next.heartbeatAt } };
 }
 export function releaseBuildLease(projectDir, run, status = "interrupted") {
     const saved = saveBuildRun(projectDir, { ...run, status, lease: undefined });
@@ -211,21 +222,41 @@ export function readBuildRuns(projectDir) {
     const directory = join(resolve(projectDir), BUILD_RUN_DIRECTORY);
     if (!existsSync(directory))
         return [];
-    return readdirSync(directory).filter((name) => name.endsWith(".json")).flatMap((name) => {
+    const workflow = existsSync(join(resolve(projectDir), ".rafi", "recovery.sqlite3")) ? new WorkflowDb(projectDir) : undefined;
+    const runs = readdirSync(directory).filter((name) => name.endsWith(".json")).flatMap((name) => {
         try {
-            const run = JSON.parse(readFileSync(join(directory, name), "utf8"));
-            validateBuildRun(run);
-            return [upgradeBuildRun(run)];
+            const projection = JSON.parse(readFileSync(join(directory, name), "utf8"));
+            validateBuildRun(projection);
+            const authoritative = workflow?.getRun(projection.runId)?.state;
+            const run = authoritative?.runId ? authoritative : projection;
+            const upgraded = upgradeBuildRun(run, projectDir);
+            return [{ ...upgraded, frozenPolicy: workflow?.autonomyPolicy(run.runId) ?? upgraded.frozenPolicy, recoveryAttempts: workflow?.recoveryAttempts(run.runId) ?? upgraded.recoveryAttempts, pendingDecisions: workflow?.pendingHumanDecisions(run.runId) ?? upgraded.pendingDecisions, supervisor: workflow?.supervisorState(run.runId) ?? upgraded.supervisor }];
         }
         catch {
             return [];
         }
     }).sort((a, b) => b.updatedAt.localeCompare(a.updatedAt));
+    workflow?.close();
+    return runs;
 }
 export function recoverableBuildRuns(projectDir, now = new Date()) {
+    const databaseLease = readCurrentWorkflowLease(projectDir);
     return readBuildRuns(projectDir)
         .filter((run) => run.status !== "completed")
-        .map((run) => ({ ...inferLegacyRunTickets(projectDir, run), active: isLeaseActive(run, now) }));
+        .map((run) => ({ ...inferLegacyRunTickets(projectDir, run), active: databaseLease?.runId === run.runId ? workflowLeaseLooksLive(databaseLease, now) : isLeaseActive(run, now) }));
+}
+function workflowLeaseLooksLive(lease, now) {
+    if (now.getTime() - new Date(lease.heartbeatAt).getTime() > BUILD_LEASE_STALE_MS)
+        return false;
+    if (lease.host !== hostname())
+        return true;
+    try {
+        process.kill(lease.pid, 0);
+        return lease.processStart === processStartIdentity(lease.pid);
+    }
+    catch {
+        return false;
+    }
 }
 /**
  * Current-branch runs created before ticket checkpointing did not retain their
@@ -298,7 +329,7 @@ export function projectBuildRecovery(projectDir, run, now = new Date(), ticketOv
     let issues = [];
     let workflowState = {};
     if (existsSync(join(resolve(projectDir), ".rafi", "recovery.sqlite3"))) {
-        const workflow = new WorkflowDb(projectDir);
+        const workflow = new WorkflowReader(projectDir);
         try {
             operationNames = workflow.operations(run.runId).filter((operation) => operation.status === "confirmed").map((operation) => operation.kind);
             issues = workflow.issues(run.runId).map((issue) => issue.detail);
@@ -425,7 +456,7 @@ function processStartIdentity(pid) {
     }
 }
 function validateBuildRun(run) {
-    if (![1, 2].includes(run.version) || !run.runId || !run.repository?.root || !run.repository.worktree || !run.createdAt || !run.updatedAt) {
+    if (![1, 2, 3].includes(run.version) || !run.runId || !run.repository?.root || !run.repository.worktree || !run.createdAt || !run.updatedAt) {
         throw new Error("invalid build run record");
     }
 }
@@ -497,14 +528,20 @@ function relativeTime(value, now) {
         return `${Math.floor(seconds / 3600)}h ago`;
     return `${Math.floor(seconds / 86_400)}d ago`;
 }
-function upgradeBuildRun(run) {
-    if (run.version === 2)
+function upgradeBuildRun(run, projectDir = run.repository.root, now = new Date()) {
+    if (run.version === 3)
         return run;
+    const policy = resolveAutonomyPolicy(loadProjectAutonomyConfig(projectDir), undefined, new Date(run.createdAt || now));
+    if (run.version === 2)
+        return {
+            ...run, version: 3, frozenPolicy: policy, phase: run.checkpoint, qaEnabled: Boolean(run.qa), recoveryAttempts: [],
+            supervisor: { status: policy.supervisorEnabled ? "stopped" : "disabled", generation: 0, workerGeneration: 0, checkpointRestarts: 0, runRestarts: 0 }, pendingDecisions: [], deferredTickets: [], legacy: true,
+        };
     const legacy = run;
     const remaining = legacy.status === "completed" ? [] : legacy.tickets.slice(Math.max(0, legacy.currentTicket ? legacy.tickets.indexOf(legacy.currentTicket) : 0));
     return {
         ...legacy,
-        version: 2,
+        version: 3,
         legacy: true,
         repository: {
             ...legacy.repository,
@@ -524,6 +561,13 @@ function upgradeBuildRun(run) {
             lastSuccessfulAction: legacy.checkpoint,
             nextAction: remaining[0] ? `Resume ${remaining[0]}` : "Inspect legacy run",
         },
+        frozenPolicy: policy,
+        phase: legacy.checkpoint,
+        qaEnabled: Boolean(legacy.qa),
+        recoveryAttempts: [],
+        supervisor: { status: policy.supervisorEnabled ? "stopped" : "disabled", generation: 0, workerGeneration: 0, checkpointRestarts: 0, runRestarts: 0 },
+        pendingDecisions: [],
+        deferredTickets: [],
     };
 }
 function releaseWorkflowLease(projectDir, runId, now = new Date()) {

package/dist/cli/doctor.d.ts

@@ -1,2 +1,9 @@
 import { Command } from "commander";
 export declare function buildDoctorCommand(): Command;
+export declare function storageReport(projectDir: string): {
+    recoveryBytes: number;
+    observabilityBytes: number;
+    observabilityWalBytes: number;
+    logBytes: number;
+    summaryOnly: boolean;
+};

package/dist/cli/doctor.js

@@ -1,6 +1,6 @@
 import { Command } from "commander";
 import { resolve, join } from "node:path";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { loadConfig } from "../config.js";
 import { isTicketsInitialized } from "../tickets/config.js";
@@ -8,6 +8,9 @@ import { cmdValidate } from "../tickets/commands.js";
 import { checkGitHubReadiness, inspectGitHubRemote } from "../branch/github.js";
 import { requireClaudeSDK } from "../adapters/claude.js";
 import { resolveExecutablePath, sanitizeDiagnostics } from "../runtimeReadiness.js";
+import { ObservabilityReader, ObservabilityStore } from "../observability.js";
+import { WorkflowReader } from "../workflowReader.js";
+import { WorkflowDb } from "../workflowDb.js";
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))?.version;
 function commandVersion(command) {
     const result = spawnSync(command, ["--version"], {
@@ -26,8 +29,16 @@ export function buildDoctorCommand() {
         .argument("[project]", "path to the project directory", ".")
         .option("--github", "run GitHub PR readiness checks")
         .option("--live-claude", "run a bounded no-tools Claude adapter request (uses account quota)")
+        .option("--storage", "report recovery, observability, and JSONL storage without writing")
+        .option("--cleanup-storage", "prune expired observability detail and fully compact storage")
         .action(async (project, opts) => {
         const cwd = resolve(project);
+        if (opts.storage || opts.cleanupStorage) {
+            if (opts.cleanupStorage)
+                cleanupStorage(cwd);
+            reportStorage(cwd);
+            return;
+        }
         let errors = 0;
         const report = (ok, label, detail) => {
             console.log(`${ok ? "ok" : "!!"} ${label}${detail ? ` — ${detail}` : ""}`);
@@ -120,6 +131,78 @@ export function buildDoctorCommand() {
         process.exit(errors === 0 ? 0 : 1);
     });
 }
+export function storageReport(projectDir) {
+    const root = resolve(projectDir);
+    const recovery = join(root, ".rafi", "recovery.sqlite3");
+    const reader = new ObservabilityReader(root);
+    try {
+        const storage = reader.storage();
+        return { recoveryBytes: fileBytes(recovery) + fileBytes(`${recovery}-wal`) + fileBytes(`${recovery}-shm`), observabilityBytes: storage.databaseBytes, observabilityWalBytes: storage.walBytes, logBytes: directoryLogBytes(join(root, ".foreman")), summaryOnly: storage.summaryOnly };
+    }
+    finally {
+        reader.close();
+    }
+}
+function reportStorage(projectDir) {
+    const report = storageReport(projectDir);
+    console.log(`storage recovery=${report.recoveryBytes} bytes observability=${report.observabilityBytes} bytes wal=${report.observabilityWalBytes} bytes logs=${report.logBytes} bytes summary_only=${report.summaryOnly}`);
+}
+function cleanupStorage(projectDir) {
+    const workflow = new WorkflowReader(projectDir);
+    try {
+        const lease = workflow.currentLease();
+        if (lease && Date.now() - new Date(lease.heartbeatAt).getTime() <= 45_000)
+            throw new Error(`refusing storage cleanup while live lease ${lease.runId} is active`);
+    }
+    finally {
+        workflow.close();
+    }
+    const before = storageReport(projectDir);
+    const config = loadConfig(join(projectDir, "foreman.yaml"));
+    const store = new ObservabilityStore(projectDir, { config: config.observability });
+    let rows = 0;
+    let recoveryRows = 0;
+    let logs = { compressed: 0, deleted: 0, reclaimedBytes: 0 };
+    try {
+        rows = store.enforceLimits().prunedRows;
+        logs = store.maintainLogs(projectDir);
+        store.compact();
+    }
+    finally {
+        store.close();
+    }
+    const recovery = new WorkflowDb(projectDir);
+    try {
+        recoveryRows = recovery.pruneTerminalTelemetry(config.observability.detail_retention_days);
+        recovery.compactStorage();
+    }
+    finally {
+        recovery.close();
+    }
+    const after = storageReport(projectDir);
+    const reclaimed = before.observabilityBytes + before.observabilityWalBytes + before.logBytes
+        - after.observabilityBytes - after.observabilityWalBytes - after.logBytes;
+    console.log(`storage cleanup reclaimed=${Math.max(0, reclaimed)} bytes pruned_rows=${rows} recovery_pruned_rows=${recoveryRows} compressed_logs=${logs.compressed} deleted_logs=${logs.deleted}`);
+}
+function fileBytes(path) { try {
+    return statSync(path).size;
+}
+catch {
+    return 0;
+} }
+function directoryLogBytes(path) {
+    if (!existsSync(path))
+        return 0;
+    let total = 0;
+    for (const entry of readdirSync(path, { withFileTypes: true })) {
+        const child = join(path, entry.name);
+        if (entry.isDirectory())
+            total += directoryLogBytes(child);
+        else if (entry.name.endsWith(".jsonl") || entry.name.endsWith(".jsonl.gz"))
+            total += fileBytes(child);
+    }
+    return total;
+}
 async function liveClaudeSmoke(cwd, executable) {
     const abortController = new AbortController();
     const timer = setTimeout(() => abortController.abort(), 45_000);

package/dist/cli/manager.d.ts

@@ -0,0 +1,17 @@
+import { Command } from "commander";
+import type { EffortLevel } from "../adapters/types.js";
+import type { ExternalDiagnosticMode } from "../diagnostics.js";
+export interface ManagerCommandOptions {
+    resolveProject?: (project: string | undefined) => string;
+    requireProject?: boolean;
+}
+export declare function buildManagerCommand(options?: ManagerCommandOptions): Command;
+export declare function runManager(projectDir: string, options: {
+    runId?: string;
+    ask?: string;
+    agent?: string;
+    model?: string;
+    effort?: EffortLevel;
+    fast?: boolean;
+    external?: ExternalDiagnosticMode;
+}): Promise<void>;

package/dist/cli/manager.js

@@ -0,0 +1,135 @@
+import { randomUUID } from "node:crypto";
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import { resolve } from "node:path";
+import { Command } from "commander";
+import { createRoleBuilder, readOnlyPermissionConfig } from "../agentRun.js";
+import { Log } from "../log.js";
+import { buildManagerEvidencePacket, buildManagerProjectPacket } from "../managerPacket.js";
+import { ManagerSessionRecorder } from "../observability.js";
+import { collectManagerProjectDiagnostics, executeManagerEvidenceRequest, MANAGER_LOOKUP_MAX_ROUNDS, parseManagerEvidenceRequest, resolveManagerQuestionRuns } from "../projectDiagnostics.js";
+export function buildManagerCommand(options = {}) {
+    return new Command("manager")
+        .description("Ask a read-only Manager about all retained builds in a project.")
+        .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")
+        .option("--agent <runtime>", "claude | codex")
+        .option("--model <model>", "provider model ID")
+        .option("--effort <level>", "low | medium | high | xhigh")
+        .option("--fast", "use the provider fast mode")
+        .option("--external <mode>", "auto | on | off", "auto")
+        .action(async (project, opts) => {
+        const root = options.resolveProject ? options.resolveProject(project) : resolve(project ?? ".");
+        await runManager(root, {
+            runId: stringOption(opts.run), ask: stringOption(opts.ask), agent: stringOption(opts.agent), model: stringOption(opts.model),
+            effort: stringOption(opts.effort), fast: Boolean(opts.fast), external: validateExternal(opts.external),
+        });
+    });
+}
+export async function runManager(projectDir, options) {
+    if (!options.ask && (!input.isTTY || !output.isTTY))
+        throw new Error("non-TTY Manager use requires --ask <question>");
+    const initialCollection = collectManagerProjectDiagnostics(projectDir, { initialFocusRunId: options.runId, question: options.ask, external: "off" });
+    const initialReport = initialCollection.report;
+    let currentFocusRunId = initialReport.initialFocusRunId;
+    let referencedRunIds = [currentFocusRunId];
+    output.write(`rafi manager: ${initialReport.totalRunCount} retained build run${initialReport.totalRunCount === 1 ? "" : "s"}\n`);
+    output.write(`rafi manager: verified active run ${initialReport.verifiedActiveRunId ?? "none"}\n`);
+    output.write(`rafi manager: initial focus ${currentFocusRunId}\n`);
+    if (initialReport.staleRecoveryRunIds.length)
+        output.write(`rafi manager: stale recovery state ${initialReport.staleRecoveryRunIds.join(", ")}\n`);
+    const metadata = new ManagerSessionRecorder(projectDir);
+    const managerSessionId = randomUUID();
+    const startedAt = new Date().toISOString();
+    metadata.record({ sessionId: managerSessionId, runId: initialReport.initialFocusRunId, startedAt, reportDigest: initialReport.digest, scope: "project", latestFocusRunId: currentFocusRunId, projectReportDigest: initialReport.projectDigest });
+    let role;
+    let packetState;
+    let usage;
+    let lookupRounds = 0;
+    let lookupOperations = 0;
+    try {
+        const activeRole = role = await createRoleBuilder({ projectDir, role: "manager", agent: options.agent, model: options.model, effort: options.effort, fast: options.fast,
+            yes: true, allowSwitch: false, label: "Manager", log: new Log(), permissionConfig: denyManagerTools(), sandboxMode: "read-only", persistSessionBindings: false });
+        const ask = async (question) => {
+            const refreshed = collectManagerProjectDiagnostics(projectDir, { initialFocusRunId: initialReport.initialFocusRunId, currentFocusRunId, referencedRunIds, question, external: "off" });
+            const resolved = resolveManagerQuestionRuns(refreshed.allSummaries, question, currentFocusRunId, referencedRunIds);
+            currentFocusRunId = resolved.focusRunId;
+            referencedRunIds = resolved.referencedRunIds.length ? resolved.referencedRunIds : referencedRunIds;
+            const collection = collectManagerProjectDiagnostics(projectDir, { initialFocusRunId: initialReport.initialFocusRunId, currentFocusRunId, referencedRunIds, question, external: options.external });
+            const report = collection.report;
+            const packet = buildManagerProjectPacket(report, question, packetState, referencedRunIds);
+            packetState = packet.state;
+            let result = await activeRole.builder.sendTurn(packet.prompt);
+            let questionLookupRounds = 0;
+            while (questionLookupRounds < MANAGER_LOOKUP_MAX_ROUNDS) {
+                const request = parseManagerEvidenceRequest(result.text);
+                if (!request) {
+                    if (!looksLikeEvidenceRequest(result.text))
+                        break;
+                    questionLookupRounds += 1;
+                    lookupRounds += 1;
+                    result = await activeRole.builder.sendTurn(buildManagerEvidencePacket({ version: 1, requestId: "invalid-request", results: [{ kind: "list_runs", status: "invalid", limitation: "The evidence envelope was invalid. Use only the documented fixed fields and read-only operations, then answer with any remaining limitation disclosed." }], lookupRound: questionLookupRounds, remainingRounds: MANAGER_LOOKUP_MAX_ROUNDS - questionLookupRounds, digest: report.digest }, question));
+                    continue;
+                }
+                questionLookupRounds += 1;
+                lookupRounds += 1;
+                lookupOperations += Math.min(6, request.operations.length);
+                const response = executeManagerEvidenceRequest(projectDir, request, collection, questionLookupRounds);
+                packetState.lastEvidenceScope = request.operations.flatMap(operation => "runIds" in operation ? operation.runIds : []);
+                result = await activeRole.builder.sendTurn(buildManagerEvidencePacket(response, question));
+            }
+            const unfulfilled = parseManagerEvidenceRequest(result.text);
+            if (unfulfilled) {
+                const limitation = { version: 1, requestId: unfulfilled.requestId, results: unfulfilled.operations.slice(0, 6).map(operation => ({ kind: operation.kind, status: "limited", limitation: "the two-round evidence lookup budget is exhausted; answer with this limitation disclosed" })), lookupRound: MANAGER_LOOKUP_MAX_ROUNDS, remainingRounds: 0, digest: report.digest };
+                result = await activeRole.builder.sendTurn(buildManagerEvidencePacket(limitation, question));
+            }
+            output.write(`${parseManagerEvidenceRequest(result.text) || looksLikeEvidenceRequest(result.text) ? "Manager could not complete an answer within the bounded evidence lookup budget; the available project report remains partial." : result.text.trim()}\n`);
+            usage = await activeRole.builder.sessionUsage?.() ?? usage;
+            metadata.record({ sessionId: managerSessionId, runId: initialReport.initialFocusRunId, provider: activeRole.builder.agent, startedAt, reportDigest: report.digest,
+                inputTokens: usage?.inputTokens, outputTokens: usage?.outputTokens, costUsd: usage?.authoritativeCostUsd, scope: "project", latestFocusRunId: currentFocusRunId,
+                projectReportDigest: report.projectDigest, lookupRounds, lookupOperations });
+        };
+        if (options.ask)
+            await ask(options.ask);
+        else {
+            const readline = createInterface({ input, output });
+            let interrupted = false;
+            const onInterrupt = () => { interrupted = true; readline.close(); };
+            readline.on("SIGINT", onInterrupt);
+            try {
+                while (true) {
+                    const question = await readline.question("manager> ");
+                    if (question.trim() === "/exit")
+                        break;
+                    if (question.trim())
+                        await ask(question.trim());
+                }
+            }
+            catch (error) {
+                if (!interrupted && error.code !== "ABORT_ERR" && error.code !== "ERR_USE_AFTER_CLOSE")
+                    throw error;
+            }
+            finally {
+                readline.off("SIGINT", onInterrupt);
+                readline.close();
+            }
+        }
+        metadata.record({ sessionId: managerSessionId, runId: initialReport.initialFocusRunId, provider: activeRole.builder.agent, startedAt, endedAt: new Date().toISOString(), outcome: "completed", reportDigest: packetState?.digest ?? initialReport.digest, inputTokens: usage?.inputTokens, outputTokens: usage?.outputTokens, costUsd: usage?.authoritativeCostUsd, scope: "project", latestFocusRunId: currentFocusRunId, projectReportDigest: packetState?.projectDigest ?? initialReport.projectDigest, lookupRounds, lookupOperations });
+    }
+    catch (error) {
+        metadata.record({ sessionId: managerSessionId, runId: initialReport.initialFocusRunId, provider: role?.builder.agent, startedAt, endedAt: new Date().toISOString(), outcome: "error", reportDigest: packetState?.digest ?? initialReport.digest, errorCode: "manager_error", scope: "project", latestFocusRunId: currentFocusRunId, projectReportDigest: packetState?.projectDigest ?? initialReport.projectDigest, lookupRounds, lookupOperations });
+        throw error;
+    }
+    finally {
+        await role?.builder.close().catch(() => { });
+        metadata.close();
+    }
+}
+function denyManagerTools() {
+    return { ...readOnlyPermissionConfig(), allowBash: [], allowTools: [], escalateBash: [""], escalateTools: ["Read", "Glob", "Grep", "Edit", "Write", "MultiEdit", "NotebookEdit", "TodoWrite", "WebFetch", "WebSearch", "Bash"] };
+}
+function stringOption(value) { return typeof value === "string" && value.length ? value : undefined; }
+function validateExternal(value) { if (value === "auto" || value === "on" || value === "off")
+    return value; throw new Error("--external must be auto, on, or off"); }
+function looksLikeEvidenceRequest(value) { return /^\s*(?:```(?:json)?\s*)?\{[\s\S]*"(?:operations|requestId)"/i.test(value); }

package/dist/cli/recovery.d.ts

@@ -0,0 +1,4 @@
+import { Command } from "commander";
+export declare function buildAttachCommand(): Command;
+export declare function buildDecideCommand(): Command;
+export declare function buildStopCommand(): Command;

package/dist/cli/recovery.js

@@ -0,0 +1,80 @@
+import { Command } from "commander";
+import { resolve } from "node:path";
+import { readBuildRuns } from "../buildRuns.js";
+import { WorkflowDb } from "../workflowDb.js";
+export function buildAttachCommand() {
+    return new Command("build:attach")
+        .description("Attach to a supervised build and show its durable recovery state.")
+        .argument("[project]", "project directory", ".")
+        .requiredOption("--run <id>", "build run ID")
+        .action((project, opts) => {
+        const projectDir = resolve(project);
+        const run = readBuildRuns(projectDir).find((item) => item.runId === opts.run);
+        if (!run)
+            throw new Error(`build run not found: ${opts.run}`);
+        const db = new WorkflowDb(projectDir);
+        try {
+            const supervisor = db.supervisorState(run.runId);
+            console.log(`rafi: run ${run.runId}`);
+            console.log(`rafi: phase ${"phase" in run && typeof run.phase === "string" ? run.phase : run.checkpoint}; status ${run.status}`);
+            console.log(`rafi: supervisor ${supervisor?.status ?? "unavailable"}${supervisor?.pid ? ` pid=${supervisor.pid}` : ""}`);
+            const attempts = db.recoveryAttempts(run.runId);
+            console.log(`rafi: recovery attempts ${attempts.length}`);
+            for (const decision of db.pendingHumanDecisions(run.runId))
+                console.log(`rafi: decision ${decision.decisionId}: ${decision.prompt} [${decision.choices.map((choice) => choice.id).join(" | ")}]`);
+        }
+        finally {
+            db.close();
+        }
+    });
+}
+export function buildDecideCommand() {
+    return new Command("build:decide")
+        .description("Answer a durable supervised-build decision.")
+        .argument("[project]", "project directory", ".")
+        .requiredOption("--run <id>", "build run ID")
+        .requiredOption("--decision <id>", "decision ID")
+        .requiredOption("--choice <id>", "stable choice ID")
+        .action((project, opts) => {
+        const db = new WorkflowDb(resolve(project));
+        try {
+            const decision = db.answerHumanDecision(opts.run, opts.decision, opts.choice);
+            console.log(`rafi: recorded ${decision.decisionId}=${opts.choice}`);
+        }
+        finally {
+            db.close();
+        }
+    });
+}
+export function buildStopCommand() {
+    return new Command("build:stop")
+        .description("Request graceful termination of a supervised build.")
+        .argument("[project]", "project directory", ".")
+        .requiredOption("--run <id>", "build run ID")
+        .action((project, opts) => {
+        const db = new WorkflowDb(resolve(project));
+        try {
+            const state = db.supervisorState(opts.run);
+            if (!state)
+                throw new Error(`supervisor state not found for run ${opts.run}`);
+            const next = { ...state, status: "stopping", stopRequestedAt: new Date().toISOString() };
+            db.putSupervisorState(opts.run, next);
+            if (state.workerPid) {
+                try {
+                    process.kill(state.workerPid, "SIGTERM");
+                }
+                catch { /* stale worker */ }
+            }
+            if (state.pid && state.pid !== process.pid) {
+                try {
+                    process.kill(state.pid, "SIGTERM");
+                }
+                catch { /* stale supervisor */ }
+            }
+            console.log(`rafi: stop requested for ${opts.run}`);
+        }
+        finally {
+            db.close();
+        }
+    });
+}