ai-foreman 1.7.19 → 1.7.21

package/dist/cli/manager.js

@@ -1,16 +1,26 @@
+import { dispatchWithGraphAccess } from "../graph/session.js";
+import { createManagerGraphEvidence, parseManagerGraphRequest } from "../graph/manager.js";
+import { prepareOwnershipRepair, repairOwnership } from "../buildOwnershipRepair.js";
+import { BuildInterventionControl, parseManagerAction } from "../buildInterventions.js";
 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 { join } from "node:path";
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { ManagerEvidenceService, parseManagerEvidenceRequestV2 } from "../managerEvidence.js";
+import { buildManagerEvidencePacketV2 } from "../managerPacket.js";
 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";
+import { accent, sanitizeTerminalText } from "../terminalStyle.js";
 export function buildManagerCommand(options = {}) {
     return new Command("manager")
-        .description("Ask a read-only Manager about all retained builds in a project.")
+        .description("Inspect retained builds and enqueue explicitly scoped Builder/QA guidance.")
         .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")
@@ -19,6 +29,7 @@ export function buildManagerCommand(options = {}) {
         .option("--effort <level>", "low | medium | high | xhigh")
         .option("--fast", "use the provider fast mode")
         .option("--external <mode>", "auto | on | off", "auto")
+        .addHelpText("after", "\nHost evidence commands (also accepted by --ask):\n  /qa-work <run>\n  /qa-attempts <run> <ticket>\n  /qa-report <run> <ticket> <attempt> [occurrence]\n  /qa-timeline <run> <ticket>\n  /qa-conflicts <run>\n  /qa-instruction <run> <work> <instruction>\n  /qa-repair-plan <run> <work>\n  /qa-repair <JSON request>\n  /more <cursor>\n  /artifact <handle>\n  /qa-export <run> <ticket> <attempt> [occurrence]\n  /qa-export <handle>  Export protected raw bytes to a private local file.\nScoped controls:\n  /guide-builder <run> <work> <text>\n  /guide-qa <run> <work> <text>\n  /guide-both <run> <work> <text>\n  /pause <run> <work> [run]\n  /withdraw <run> <work> <instruction>\n  /supersede <run> <work> <instruction> <text>\n  /request-attempt <run> <work> <reason>\n  /answer-question <run> <work> <decision> <revision> <text>\n")
         .action(async (project, opts) => {
         const root = options.resolveProject ? options.resolveProject(project) : resolve(project ?? ".");
         await runManager(root, {
@@ -30,15 +41,27 @@ export function buildManagerCommand(options = {}) {
 export async function runManager(projectDir, options) {
     if (!options.ask && (!input.isTTY || !output.isTTY))
         throw new Error("non-TTY Manager use requires --ask <question>");
+    const evidence = new ManagerEvidenceService(projectDir);
+    if (options.ask && (options.ask.trim().startsWith("/") || parseManagerAction(options.ask))) {
+        try {
+            if (!executeManagerHostCommand(evidence, options.ask, text => output.write(text), true))
+                throw new Error("Unknown Manager host command; see manager --help");
+        }
+        finally {
+            evidence.close();
+        }
+        return;
+    }
     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`);
+    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`);
     if (initialReport.staleRecoveryRunIds.length)
-        output.write(`rafi manager: stale recovery state ${initialReport.staleRecoveryRunIds.join(", ")}\n`);
+        output.write(`${managerLabel("rafi manager")}: stale recovery state ${initialReport.staleRecoveryRunIds.map(sanitizeTerminalText).join(", ")}\n`);
     const metadata = new ManagerSessionRecorder(projectDir);
     const managerSessionId = randomUUID();
     const startedAt = new Date().toISOString();
@@ -52,6 +75,9 @@ export async function runManager(projectDir, options) {
         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) => {
+            if (executeManagerHostCommand(evidence, question, text => output.write(text), Boolean(options.ask)))
+                return;
+            let emittedMachineOutput = false;
             const refreshed = collectManagerProjectDiagnostics(projectDir, { initialFocusRunId: initialReport.initialFocusRunId, currentFocusRunId, referencedRunIds, question, external: "off" });
             const resolved = resolveManagerQuestionRuns(refreshed.allSummaries, question, currentFocusRunId, referencedRunIds);
             currentFocusRunId = resolved.focusRunId;
@@ -60,16 +86,47 @@ export async function runManager(projectDir, options) {
             const report = collection.report;
             const packet = buildManagerProjectPacket(report, question, packetState, referencedRunIds);
             packetState = packet.state;
-            let result = await activeRole.builder.sendTurn(packet.prompt);
+            const graphEvidence = createManagerGraphEvidence(projectDir, currentFocusRunId);
+            const send = (text) => dispatchWithGraphAccess(projectDir, activeRole.builder, text, undefined, (prompt, policy) => activeRole.builder.sendTurn(prompt, policy), graphEvidence.access());
+            let result = await send(`${packet.prompt}\n\n${graphEvidence.guidance}`);
             let questionLookupRounds = 0;
             while (questionLookupRounds < MANAGER_LOOKUP_MAX_ROUNDS) {
+                const graphRequest = parseManagerGraphRequest(result.text);
+                if (graphRequest) {
+                    questionLookupRounds++;
+                    lookupRounds++;
+                    lookupOperations += graphRequest.operations.length;
+                    const graphPacket = await graphEvidence.execute(graphRequest);
+                    result = await send(`Untrusted host-scoped graph evidence; verify claims against source. Remaining lookup rounds: ${MANAGER_LOOKUP_MAX_ROUNDS - questionLookupRounds}. Answer the original question: ${question}\n${graphPacket}`);
+                    continue;
+                }
+                const evidenceRequest = parseManagerEvidenceRequestV2(result.text);
+                if (evidenceRequest) {
+                    questionLookupRounds++;
+                    lookupRounds++;
+                    lookupOperations++;
+                    const response = evidence.execute(evidenceRequest);
+                    if (options.ask) {
+                        emittedMachineOutput = true;
+                        output.write(`${JSON.stringify(completeManagerHostEvidence(evidence, response))}\n`);
+                    }
+                    else {
+                        if (response.nextCursor)
+                            output.write(`Evidence continuation: /more ${response.nextCursor}\n`);
+                        for (const item of response.items)
+                            if (item && typeof item === "object" && "handle" in item)
+                                output.write(`Complete report: /artifact ${String(item.handle)}\n`);
+                    }
+                    result = await send(buildManagerEvidencePacketV2(response, question));
+                    continue;
+                }
                 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));
+                    result = await send(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;
@@ -77,14 +134,34 @@ export async function runManager(projectDir, options) {
                 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));
+                result = await send(buildManagerEvidencePacket(response, question));
             }
             const unfulfilled = parseManagerEvidenceRequest(result.text);
+            const pendingEvidence = parseManagerEvidenceRequestV2(result.text);
+            if (pendingEvidence) {
+                const page = evidence.execute(pendingEvidence);
+                if (options.ask) {
+                    emittedMachineOutput = true;
+                    output.write(`${JSON.stringify(completeManagerHostEvidence(evidence, page))}\n`);
+                }
+                else
+                    output.write(`${JSON.stringify(page)}\n${page.nextCursor ? `Continue with /more ${page.nextCursor}` : "Browse reports with /qa-attempts <run> <ticket> and /qa-report <run> <ticket> <attempt>"}\n`);
+            }
             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));
+                result = await send(buildManagerEvidencePacket(limitation, question));
+            }
+            if (!pendingEvidence) {
+                const answer = parseManagerEvidenceRequest(result.text) || parseManagerGraphRequest(result.text) || looksLikeEvidenceRequest(result.text)
+                    ? "Manager could not complete an answer within the bounded evidence lookup budget. Continue with /qa-attempts <run> <ticket> or /qa-report <run> <ticket> <attempt>."
+                    : result.text.trim();
+                // One-shot evidence requests can mix JSON with prose, so add the label
+                // only when this answer stream has not emitted machine-readable data.
+                // Model-provided text is sanitized only for display, never for storage.
+                if (!emittedMachineOutput)
+                    output.write(`${accent("Manager:", { stream: output, env: process.env })} `);
+                output.write(`${sanitizeTerminalText(answer)}\n`);
             }
-            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,
@@ -99,11 +176,11 @@ export async function runManager(projectDir, options) {
             readline.on("SIGINT", onInterrupt);
             try {
                 while (true) {
-                    const question = await readline.question("manager> ");
+                    const question = await readline.question(`${accent("manager>", { stream: output, env: process.env })} `);
                     if (question.trim() === "/exit")
                         break;
                     if (question.trim())
-                        await ask(question.trim());
+                        await ask(question);
                 }
             }
             catch (error) {
@@ -124,7 +201,152 @@ export async function runManager(projectDir, options) {
     finally {
         await role?.builder.close().catch(() => { });
         metadata.close();
+        evidence.close();
+    }
+}
+/** Only original user commands enter here. Model output and retained reports cannot export raw bytes. */
+export function executeManagerHostCommand(service, command, write, complete = false) {
+    if (command.trim().startsWith("/qa-repair ")) {
+        write(`${JSON.stringify(repairOwnership(service.projectDir, JSON.parse(command.trim().slice("/qa-repair ".length)), command))}\n`);
+        return true;
+    }
+    if (command.trim().startsWith("/qa-repair-plan ")) {
+        const args = command.trim().split(/\s+/);
+        if (args.length !== 3)
+            throw new Error("/qa-repair-plan requires run and work identities");
+        write(`${JSON.stringify(prepareOwnershipRepair(service.projectDir, args[1], args[2]))}\n`);
+        return true;
+    }
+    const proposed = parseManagerAction(command);
+    if (proposed) {
+        const control = new BuildInterventionControl(service.projectDir, proposed.runId, proposed.workId);
+        try {
+            const request = parseManagerAction(command, proposed.requestId, control.revision());
+            const queued = control.enqueue(request, command);
+            write(`${JSON.stringify(queued)}\n${request.action === "withdraw" ? "Withdrawn before reservation." : "Queued at the next eligible safe boundary. An active provider turn continues; a stopped owner must resume to consume this instruction."}\n`);
+        }
+        finally {
+            control.close();
+        }
+        return true;
+    }
+    if (!command.trim().startsWith("/"))
+        return false;
+    const [name, ...args] = command.trim().split(/\s+/);
+    if (name === "/artifact" || name === "/qa-export" && args.length === 1) {
+        if (args.length !== 1)
+            throw new Error(`${name} requires one host artifact handle`);
+        if (name === "/artifact")
+            write(`${JSON.stringify(service.artifacts.metadata(args[0]))}\n${service.artifacts.bytes(args[0]).toString("utf8")}\n`);
+        else {
+            const path = join(mkdtempSync(join(tmpdir(), "rafi-qa-evidence-")), "protected-evidence.txt");
+            writeFileSync(path, service.artifacts.bytes(args[0], true), { mode: 0o600 });
+            write(`Protected raw evidence exported to ${path}\n${JSON.stringify(service.artifacts.metadata(args[0]))}\n`);
+        }
+        return true;
+    }
+    if (name === "/more") {
+        if (args.length !== 1)
+            throw new Error("/more requires one cursor");
+        const page = service.more(args[0]);
+        write(`${JSON.stringify(complete ? completeManagerHostEvidence(service, page) : page)}\n`);
+        return true;
+    }
+    const requestId = randomUUID();
+    const runId = args[0] ?? "";
+    const workId = args[1] ?? "";
+    let page;
+    if (name === "/qa-work" || name === "/qa-conflicts") {
+        if (args.length !== 1)
+            throw new Error(`${name} requires a run ID`);
+        page = service.execute({ version: 2, requestId, operation: { kind: name === "/qa-work" ? "list_build_work" : "get_ownership_conflicts", runId } });
+    }
+    else if (name === "/qa-attempts" || name === "/qa-timeline") {
+        if (args.length !== 2)
+            throw new Error(`${name} requires run and ticket IDs`);
+        page = service.execute({ version: 2, requestId, operation: { kind: name === "/qa-attempts" ? "list_qa_attempts" : "get_qa_timeline", runId, workId } });
+    }
+    else if (name === "/qa-instruction") {
+        if (args.length !== 3)
+            throw new Error("/qa-instruction requires run, work and instruction identities");
+        page = service.execute({ version: 2, requestId, operation: { kind: "get_intervention_status", runId, workId, instructionId: args[2] } });
+    }
+    else if (name === "/qa-report" || name === "/qa-export") {
+        if (args.length < 3 || args.length > 4)
+            throw new Error(`${name} requires run, ticket, attempt and optional occurrence IDs`);
+        const attemptId = args[2];
+        const attempts = service.execute({ version: 2, requestId, operation: { kind: "list_qa_attempts", runId, workId } });
+        const rows = completeManagerHostEvidence(service, attempts).items;
+        const attempt = rows.find(row => row && typeof row === "object" && "attemptId" in row && row.attemptId === attemptId);
+        if (!attempt)
+            throw new Error("Attempt is not retained in this run/ticket; use /qa-attempts first");
+        if (!attempt.reports.length) {
+            write(`${JSON.stringify(rows.find(row => row && typeof row === "object" && "attemptId" in row && row.attemptId === attemptId))}\nNo retained failure report body; inspect verification or attempt status above.\n`);
+            return true;
+        }
+        const occurrenceId = args[3] ?? (attempt.reports.length === 1 ? attempt.reports[0].occurrenceId : undefined);
+        if (!occurrenceId)
+            throw new Error("Report identity is ambiguous; specify a retained occurrence ID");
+        page = service.execute({ version: 2, requestId, operation: { kind: "get_qa_report", runId, workId, attemptId, occurrenceId, snapshotId: attempts.snapshotId } });
+        const artifact = page.items[0];
+        if (artifact?.handle) {
+            if (name === "/qa-export") {
+                const path = join(mkdtempSync(join(tmpdir(), "rafi-qa-evidence-")), "protected-evidence.txt");
+                writeFileSync(path, service.artifacts.bytes(artifact.handle, true), { mode: 0o600 });
+                write(`Protected raw evidence exported to ${path}\n${JSON.stringify({ ...service.artifacts.metadata(artifact.handle), snapshotId: page.snapshotId, asOf: page.asOf })}\n`);
+            }
+            else
+                write(`${JSON.stringify({ ...service.artifacts.metadata(artifact.handle), snapshotId: page.snapshotId, asOf: page.asOf, availability: page.availability, omissions: page.omissions.filter(item => !item.startsWith("Complete host rendering:")) })}\n${service.artifacts.bytes(artifact.handle).toString("utf8")}\n`);
+            return true;
+        }
+    }
+    else
+        return false;
+    write(`${JSON.stringify(complete ? completeManagerHostEvidence(service, page) : page)}\n`);
+    if (!complete && page.nextCursor)
+        write(`Continue with /more ${page.nextCursor}\n`);
+    return true;
+}
+/** Drain one pinned snapshot and expand every referenced artifact before host close.
+ * Errors are returned as incomplete output; an expired snapshot is never refreshed.
+ * This host output is deliberately independent of bounded model packets. */
+export function completeManagerHostEvidence(service, first) {
+    const result = structuredClone(first);
+    result.redactions = service.hostRedactions(first.snapshotId);
+    result.items = [];
+    const seen = new Set();
+    let page = first;
+    while (true) {
+        for (const item of page.items) {
+            const row = item;
+            if (row?.metadataArtifact)
+                result.items.push(service.hostMetadataItem(row.metadataArtifact.handle));
+            else if (row?.handle) {
+                if (seen.has(row.handle))
+                    continue;
+                seen.add(row.handle);
+                const { handle: _, ...metadata } = service.artifacts.metadata(row.handle);
+                result.items.push({ ...metadata, body: service.artifacts.bytes(row.handle).toString("utf8") });
+            }
+            else
+                result.items.push(item);
+        }
+        if (!page.nextCursor || page.error)
+            break;
+        const next = service.more(page.nextCursor);
+        if (!next.error && next.snapshotId !== first.snapshotId)
+            throw new Error("Evidence continuation changed snapshot identity");
+        page = next;
+    }
+    delete result.nextCursor;
+    result.complete = page.complete;
+    if (page.error) {
+        result.error = page.error;
+        result.restartAction = page.restartAction;
+        result.omissions.push(...page.omissions);
     }
+    result.omissions = result.omissions.filter(item => !item.startsWith("Complete host rendering:") && !item.includes("additional redaction spans are available"));
+    return result;
 }
 function denyManagerTools() {
     return { ...readOnlyPermissionConfig(), allowBash: [], allowTools: [], escalateBash: [""], escalateTools: ["Read", "Glob", "Grep", "Edit", "Write", "MultiEdit", "NotebookEdit", "TodoWrite", "WebFetch", "WebSearch", "Bash"] };

package/dist/cli/recovery.js

@@ -1,5 +1,6 @@
 import { isLiveProcessIdentity } from "../processIdentity.js";
 import { Command } from "commander";
+import { accent, sanitizeTerminalText, success, warning } from "../terminalStyle.js";
 import { resolve } from "node:path";
 import { readBuildRuns } from "../buildRuns.js";
 import { WorkflowDb } from "../workflowDb.js";
@@ -16,8 +17,8 @@ export function buildAttachCommand() {
         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(`${accent("rafi:")} run ${sanitizeTerminalText(run.runId)}`);
+            console.log(`${accent("rafi:")} phase ${sanitizeTerminalText("phase" in run && typeof run.phase === "string" ? run.phase : run.checkpoint)}; status ${run.status === "completed" ? success(run.status) : warning(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}`);

package/dist/cli/runtimeAuthPrompt.d.ts

@@ -1,4 +1,5 @@
 import { RuntimeAuthError, type AgentRuntime } from "../runtimeAuth.js";
+import { type BuildReadinessContext } from "../runtimeReadiness.js";
 import type { RuntimeProbeResult } from "rafi-spec";
 export type RuntimeCommandRecoveryChoice = "retry" | "switch" | "cancel";
 export interface RuntimeCommandRecoveryContext {
@@ -7,6 +8,7 @@ export interface RuntimeCommandRecoveryContext {
 }
 export interface RuntimeReadyForCommandOptions {
     label: string;
+    build?: BuildReadinessContext;
     timeoutMs?: number;
     durable?: {
         projectDir: string;
@@ -27,4 +29,7 @@ export interface RuntimeReadyForCommandResult {
     fellBack: boolean;
     executable: string;
 }
+export declare function ensureBuildRuntimeReadyForCommand(projectDir: string, runtime: AgentRuntime, opts: RuntimeReadyForCommandOptions & {
+    build: BuildReadinessContext;
+}): Promise<RuntimeReadyForCommandResult>;
 export declare function ensureRuntimeReadyForCommand(projectDir: string, runtime: AgentRuntime, labelOrOptions: string | RuntimeReadyForCommandOptions): Promise<RuntimeReadyForCommandResult>;

package/dist/cli/runtimeAuthPrompt.js

@@ -1,17 +1,27 @@
 import { select, isCancel, log } from "@clack/prompts";
 import { requireClaudeSDK } from "../adapters/claude.js";
 import { checkRuntimeReady, RuntimeAuthError, runtimeCommandLabel, } from "../runtimeAuth.js";
-import { resolveExecutablePath } from "../runtimeReadiness.js";
+import { BuildOwnershipError } from "../buildAdmission.js";
+import { RuntimeCleanupError, runtimeCleanupRecoveryHelp, resolveExecutablePath } from "../runtimeReadiness.js";
 import { otherRuntime, runtimeDisplayName } from "./runtimeSelection.js";
 import { currentActivity } from "../activity.js";
 import { durableHumanDecision } from "../humanDecision.js";
 import { WorkflowDb } from "../workflowDb.js";
 import { createHash } from "node:crypto";
+export async function ensureBuildRuntimeReadyForCommand(projectDir, runtime, opts) {
+    if (!opts.build?.authority)
+        throw new BuildOwnershipError("stale-owner", "Build readiness requires original owning-project context");
+    return ensureRuntimeReadyForCommand(projectDir, runtime, opts);
+}
 export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrOptions) {
     const opts = typeof labelOrOptions === "string"
         ? { label: labelOrOptions }
         : labelOrOptions;
-    const check = opts.check ?? ((projectDir, runtime) => checkRuntimeReady(projectDir, runtime, { onTrace: opts.onTrace, timeoutMs: opts.timeoutMs }));
+    const check = opts.check ?? (async (projectDir, runtime) => {
+        if (opts.durable && !opts.build)
+            throw new BuildOwnershipError("stale-owner", "Build readiness requires its original owning-project context");
+        return checkRuntimeReady(projectDir, runtime, { build: opts.build, onTrace: opts.onTrace, timeoutMs: opts.timeoutMs });
+    });
     const checkClaudeSdk = opts.checkClaudeSdk ?? requireClaudeSDK;
     const allowSwitch = opts.allowSwitch !== false;
     const nonInteractive = !opts.choose && (Boolean(opts.yes) || !process.stdin.isTTY || !process.stdout.isTTY);
@@ -26,6 +36,8 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
             return { runtime, model: opts.model, fellBack: false, executable };
         }
         catch (err) {
+            if (err instanceof BuildOwnershipError || (err instanceof RuntimeCleanupError && opts.build))
+                throw err;
             const failure = err instanceof RuntimeAuthError
                 ? err
                 : new RuntimeAuthError({
@@ -34,20 +46,21 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
                     stderr: err instanceof Error ? err.message : String(err),
                     cause: err,
                 });
-            if (nonInteractive && !opts.durable) {
+            if (nonInteractive && !opts.durable && !(failure.cleanupUnverified && process.stdin.isTTY && process.stdout.isTTY)) {
                 throw failure;
             }
             const fallbackRuntime = otherRuntime(runtime);
+            const canSwitch = allowSwitch && !failure.cleanupUnverified;
             const choice = opts.durable && !opts.choose
-                ? await durableRuntimeRecovery(opts.durable, failure, opts.label, fallbackRuntime, allowSwitch)
+                ? await durableRuntimeRecovery(opts.durable, failure, opts.label, fallbackRuntime, canSwitch)
                 : opts.choose
-                    ? await opts.choose(failure, { otherRuntime: fallbackRuntime, allowSwitch })
-                    : await promptRuntimeRecovery(failure, opts.label, fallbackRuntime, allowSwitch);
+                    ? await opts.choose(failure, { otherRuntime: fallbackRuntime, allowSwitch: canSwitch })
+                    : await promptRuntimeRecovery(failure, opts.label, fallbackRuntime, canSwitch);
             if (choice === "retry") {
                 currentActivity()?.note(`rafi: retrying ${runtime} readiness check`);
                 continue;
             }
-            if (choice === "switch" && allowSwitch) {
+            if (choice === "switch" && canSwitch) {
                 currentActivity()?.note(`rafi: checking fallback runtime ${fallbackRuntime}`);
                 try {
                     const probe = await check(projectDir, fallbackRuntime);
@@ -64,6 +77,8 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
                     return { runtime: fallbackRuntime, model: undefined, fellBack: true, executable };
                 }
                 catch (switchErr) {
+                    if (switchErr instanceof BuildOwnershipError || (switchErr instanceof RuntimeCleanupError && opts.build))
+                        throw switchErr;
                     const switchFailure = switchErr instanceof RuntimeAuthError
                         ? switchErr
                         : new RuntimeAuthError({
@@ -116,6 +131,25 @@ async function durableRuntimeRecovery(scope, failure, label, fallbackRuntime, al
 }
 async function promptRuntimeRecovery(err, label, fallbackRuntime, allowSwitch) {
     log.error(err.message);
+    if (err.cleanupUnverified) {
+        while (true) {
+            const choice = await select({
+                message: `${label} is paused until probe cleanup is verified. Choose a resolution.`,
+                options: [
+                    { value: "retry", label: "Recheck cleanup after repairing process visibility" },
+                    { value: "help", label: "Show platform-specific resolution approaches" },
+                    { value: "cancel", label: "Cancel deliberately; keep project files" },
+                ],
+            });
+            if (isCancel(choice) || choice === "cancel")
+                return "cancel";
+            if (choice === "help") {
+                log.info(runtimeCleanupRecoveryHelp());
+                continue;
+            }
+            return "retry";
+        }
+    }
     log.info("Cancel stops this command and keeps project files in place. It does not uninstall packages, delete generated files, or change configuration.");
     if (!allowSwitch) {
         log.info("Switching runtimes is disabled while resuming because session IDs are runtime-specific.");

package/dist/cli/start.d.ts

@@ -16,6 +16,14 @@ export declare function formatResumeGuidance(executable: "rafi" | "ai-foreman",
         }>;
     }>;
 }): string[];
+/** Save parsed CLI values as argv, never as executable shell text. */
+export declare function savedStartArguments(command: Command, projectDir: string, opts: Record<string, unknown>): string[];
+/** Pure validation shared by interactive start and persisted preparation. */
+export declare function validateStartOptions(opts: Record<string, any>, requireCount: boolean): void;
+/** Validate generated established recovery before reserving execution authority. */
+export declare function validateRecoveryArguments(args: readonly string[], projectDir: string): void;
+/** Validate persisted preparation argv without executing a command or provider. */
+export declare function validatePreparationArguments(args: readonly string[], projectDir: string): string[];
 export declare function buildStartCommand(): Command;
 export declare function createQaNonconvergenceHandler(projectDir: string, noninteractive: boolean, planner?: AgentRoleDefaultsV1, observer?: () => RunObserver | undefined, activeRunId?: () => string): (context: QaNonconvergenceContext) => Promise<QaNonconvergenceDecision>;
 export declare function createQaReportRecoveryHandler(projectDir: string, noninteractive: boolean, observer?: () => RunObserver | undefined): QaReportRecoveryHandler;