ai-foreman 1.7.19 → 1.7.21

package/dist/humanDecision.js

@@ -1,12 +1,16 @@
+import { formatDecisionCommands, formatExactRunRecovery } from "./recoveryGuidance.js";
 import { createHash } from "node:crypto";
 import { isCancel } from "@clack/prompts";
 import { WorkflowDb } from "./workflowDb.js";
 import { pauseActivityForInput } from "./activity.js";
+export class HumanDecisionCancelled extends Error {
+    constructor() { super("Build cancelled at an input prompt"); this.name = "HumanDecisionCancelled"; }
+}
 export class HumanDecisionRequired extends Error {
     decisionId;
     runId;
-    constructor(decisionId, runId, prompt) {
-        super(`${prompt}\nRafi is waiting for input (${decisionId}). Answer with rafi build:decide --run ${runId} --decision ${decisionId} --choice <choice-id>. Resume with rafi build:resume --run ${runId}`);
+    constructor(decisionId, runId, prompt, projectDir = process.cwd(), choices = []) {
+        super(`${prompt}\nRafi is waiting for input (${decisionId}).\n${formatDecisionCommands(projectDir, runId, { decisionId, choices }).join("\n")}\nResume with ${formatExactRunRecovery(projectDir, runId)}`);
         this.decisionId = decisionId;
         this.runId = runId;
         this.name = "HumanDecisionRequired";
@@ -16,24 +20,70 @@ export async function durableHumanDecision(input) {
     const db = new WorkflowDb(input.projectDir);
     try {
         const key = `${input.runId}:${input.key}:${createHash("sha256").update(JSON.stringify([input.prompt, input.choices])).digest("hex")}`;
-        const decision = db.ensureHumanDecision({ decisionKey: key, runId: input.runId, interruptionId: input.ticketId ? `ticket:${input.ticketId}` : input.key, prompt: input.prompt, choices: input.choices });
-        if (decision.status === "answered")
-            return (decision.answer ?? decision.selectedChoiceId);
+        const legacy = db.pendingHumanDecisions(input.runId).find(item => item.interruptionId === (input.ticketId ? `ticket:${input.ticketId}` : input.key) && item.prompt === input.prompt && JSON.stringify(item.choices.map(choice => choice.label)) === JSON.stringify(input.choices.map(choice => choice.label)) && db.humanDecisionKey(item.decisionId)?.startsWith(`${input.runId}:${input.key}:`));
+        const decision = legacy ?? db.ensureHumanDecision({ decisionKey: key, runId: input.runId, interruptionId: input.ticketId ? `ticket:${input.ticketId}` : input.key, prompt: input.prompt, choices: input.choices });
+        if (decision.status === "answered") {
+            if (input.ticketId && !db.decisionContinuationAvailable(input.runId, decision.decisionId))
+                throw new Error("Answered ticket decision has already been dispatched or is uncertain; reconcile before reusing its answer");
+            input.onAnswered?.(decision);
+            return decisionResponse(decision);
+        }
         console.error(`rafi: input required: ${input.prompt} [decision ${decision.decisionId}]`);
         const previous = db.getRun(input.runId);
         if (!input.defer)
             db.transition(input.runId, { status: "paused", checkpoint: "waiting-for-human", state: { ...previous.state, status: "recoverable", checkpoint: "waiting-for-human", phase: "waiting-for-human", pendingDecisionId: decision.decisionId } });
         if (input.defer || !process.stdin.isTTY || !process.stdout.isTTY)
-            throw new HumanDecisionRequired(decision.decisionId, input.runId, input.prompt);
-        const wait = () => pauseActivityForInput(input.operation);
-        const answer = await (input.observer ? input.observer.span("user_wait", input.prompt, wait) : wait());
+            throw new HumanDecisionRequired(decision.decisionId, input.runId, input.prompt, input.projectDir, decision.choices);
+        const controller = new AbortController();
+        let poll;
+        let remoteAnswered = false;
+        const remote = new Promise((resolve, reject) => {
+            poll = setInterval(() => {
+                try {
+                    if (input.ticketId)
+                        db.consumeInstructionControls(input.runId, input.ticketId);
+                    if (input.ticketId && input.key.startsWith("qa-nonconvergence:"))
+                        db.consumeInstructionControls(input.runId, input.ticketId, "attempts");
+                    const current = db.humanDecision(decision.decisionId);
+                    if (current?.status === "answered") {
+                        remoteAnswered = true;
+                        resolve(decisionResponse(current));
+                        controller.abort();
+                    }
+                    else if (!current || current.status !== "pending") {
+                        controller.abort();
+                        reject(new Error("Pending decision was superseded; resume the durable scoped recovery before continuing"));
+                    }
+                }
+                catch (error) {
+                    reject(error);
+                }
+            }, 250);
+        });
+        const wait = () => pauseActivityForInput(() => Promise.race([input.operation(controller.signal), remote]));
+        let answer;
+        try {
+            answer = await (input.observer ? input.observer.span("user_wait", input.prompt, wait) : wait());
+        }
+        finally {
+            if (poll)
+                clearInterval(poll);
+            controller.abort();
+        }
+        if (remoteAnswered) {
+            input.onAnswered?.(db.humanDecision(decision.decisionId));
+            const current = db.getRun(input.runId);
+            db.transition(input.runId, { status: previous.status, checkpoint: "decision-received", state: { ...current.state, pendingDecisionId: undefined } });
+            return answer;
+        }
         if (isCancel(answer) || answer === undefined)
             return answer;
         const selected = String(answer);
-        const choice = input.choices.find(item => item.id === selected);
+        const choice = decision.choices.find(item => item.id === selected || item.label === selected);
         if (!choice && !input.choices.some(item => item.id === "custom"))
             throw new Error("answer does not match the durable decision choices");
-        db.answerHumanDecision(input.runId, decision.decisionId, choice?.id ?? "custom", undefined, choice ? undefined : selected);
+        const answered = db.answerHumanDecision(input.runId, decision.decisionId, choice?.id ?? "custom", undefined, choice ? undefined : selected);
+        input.onAnswered?.(answered);
         db.transition(input.runId, { status: previous.status, checkpoint: "decision-received", state: { ...previous.state, pendingDecisionId: undefined } });
         return answer;
     }
@@ -41,3 +91,112 @@ export async function durableHumanDecision(input) {
         db.close();
     }
 }
+/** Fixed choices deliver their meaning, rather than a generated menu identifier. */
+export function decisionResponse(decision) {
+    return decision.answer ?? (decision.selectedChoiceId?.startsWith("option-") ? decision.choices.find(choice => choice.id === decision.selectedChoiceId)?.label : decision.selectedChoiceId);
+}
+/** Returns false on safe pause/EOF. Never launches a provider or grants capabilities. */
+export async function servicePendingHumanDecisions(input) {
+    const db = new WorkflowDb(input.projectDir);
+    try {
+        if (input.scopeRevision)
+            db.refreshStaleTicketDecisions(input.runId, input.scopeRevision, input.tickets);
+        for (const work of db.workDefinitions(input.runId))
+            if (!input.tickets || input.tickets.includes(work.workId)) {
+                db.consumeInstructionControls(input.runId, work.workId);
+                db.consumeInstructionControls(input.runId, work.workId, "attempts");
+            }
+        const applicable = () => db.pendingHumanDecisions(input.runId).filter(decision => !input.tickets || !db.decisionWorkId(decision) || input.tickets.includes(db.decisionWorkId(decision)));
+        for (const decision of applicable()) {
+            if (db.humanDecision(decision.decisionId)?.status !== "pending")
+                continue;
+            const run = db.getRun(input.runId);
+            db.transition(input.runId, { status: "paused", checkpoint: "waiting-for-human", state: { ...run.state, status: "recoverable", phase: "waiting-for-human", checkpoint: "waiting-for-human", pendingDecisionId: decision.decisionId } });
+            if (!input.prompt && (!process.stdin.isTTY || !process.stdout.isTTY))
+                throw new HumanDecisionRequired(decision.decisionId, input.runId, decision.prompt, input.projectDir, decision.choices);
+            const controller = new AbortController();
+            const ask = async () => {
+                if (input.prompt)
+                    return input.prompt(decision, controller.signal);
+                const { select, text } = await import("@clack/prompts");
+                const choice = await select({ message: decision.prompt, signal: controller.signal, options: [...decision.choices.map(item => ({ value: item.id, label: item.label })), { value: "__rafi_pause__", label: "Pause safely" }, { value: "__rafi_cancel__", label: "Cancel build" }] });
+                if (isCancel(choice) || choice === "__rafi_pause__")
+                    return undefined;
+                if (choice !== "custom")
+                    return choice;
+                const answer = await text({ message: "Custom response:", signal: controller.signal, validate: value => value?.trim() ? undefined : "Enter a response" });
+                return isCancel(answer) ? undefined : String(answer);
+            };
+            let remoteAnswered = false;
+            let poll;
+            const remote = new Promise((resolve, reject) => {
+                poll = setInterval(() => {
+                    try {
+                        const workId = db.decisionWorkId(decision);
+                        if (workId)
+                            db.consumeInstructionControls(input.runId, workId);
+                        if (workId)
+                            db.consumeInstructionControls(input.runId, workId, "attempts");
+                        const current = db.humanDecision(decision.decisionId);
+                        if (current?.status === "answered") {
+                            remoteAnswered = true;
+                            resolve(decisionResponse(current));
+                            controller.abort();
+                        }
+                        else if (current?.status === "cancelled" && db.humanDecisionKey(decision.decisionId)?.startsWith(`${input.runId}:qa-nonconvergence:`)) {
+                            remoteAnswered = true;
+                            resolve(undefined);
+                            controller.abort();
+                        }
+                        else if (!current || current.status !== "pending")
+                            reject(new Error("Pending decision changed; refresh before continuing"));
+                    }
+                    catch (error) {
+                        reject(error);
+                    }
+                }, 250);
+            });
+            const wait = () => pauseActivityForInput(() => Promise.race([ask(), remote]));
+            const lease = db.currentLease();
+            const heartbeat = lease?.runId === input.runId ? setInterval(() => { try {
+                db.heartbeatLease(lease);
+            }
+            catch { /* fenced mutation rechecks authority after input */ } }, 10_000) : undefined;
+            heartbeat?.unref();
+            let answer;
+            try {
+                answer = await (input.observer ? input.observer.span("user_wait", decision.prompt, wait) : wait());
+            }
+            finally {
+                if (heartbeat)
+                    clearInterval(heartbeat);
+                if (poll)
+                    clearInterval(poll);
+                controller.abort();
+            }
+            if (remoteAnswered) {
+                const current = db.getRun(input.runId);
+                db.transition(input.runId, { status: run.status, checkpoint: "decision-received", state: { ...current.state, pendingDecisionId: undefined } });
+                continue;
+            }
+            if (answer === "__rafi_cancel__") {
+                db.atomic(() => {
+                    db.cancelPendingHumanDecisions(input.runId, "User cancelled build; pending questions superseded");
+                    const current = db.getRun(input.runId);
+                    db.transition(input.runId, { status: "cancelled", checkpoint: "cancelled", state: { ...current.state, status: "cancelled", checkpoint: "cancelled", pendingDecisionId: undefined }, event: "user_cancelled", payload: { source: "question-menu" } });
+                });
+                throw new HumanDecisionCancelled();
+            }
+            if (answer === undefined)
+                return false;
+            const choice = decision.choices.find(item => item.id === answer);
+            db.answerHumanDecision(input.runId, decision.decisionId, choice?.id ?? "custom", undefined, choice ? undefined : answer);
+            const current = db.getRun(input.runId);
+            db.transition(input.runId, { status: run.status, checkpoint: "decision-received", state: { ...current.state, pendingDecisionId: undefined } });
+        }
+        return applicable().length === 0;
+    }
+    finally {
+        db.close();
+    }
+}

package/dist/index.js

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
+import { withRecoveryCommandFamily } from "./recoveryGuidance.js";
 import { HumanDecisionRequired } from "./humanDecision.js";
 import { Command } from "commander";
+import { buildGraphCommand } from "./cli/graph.js";
 import { readFileSync } from "node:fs";
 import { buildTicketsCommand } from "./cli/tickets.js";
 import { buildStartCommand } from "./cli/start.js";
@@ -17,6 +19,7 @@ program
     .description("Keep Codex / Claude Code builders moving through their step list.")
     .version(PACKAGE_VERSION);
 program.addCommand(buildTicketsCommand());
+program.addCommand(buildGraphCommand());
 program.addCommand(buildStartCommand());
 program.addCommand(buildStatusCommand());
 program.addCommand(buildDoctorCommand());
@@ -31,7 +34,7 @@ const argv = [...process.argv];
 if (argv[2] === "--")
     argv.splice(2, 1);
 const command = argv.slice(2).filter((arg) => !arg.startsWith("-")).slice(0, 3).join(" ") || "ai-foreman";
-withActivityContext(command, () => program.parseAsync(argv)).catch((err) => {
+withActivityContext(command, () => withRecoveryCommandFamily("ai-foreman", () => program.parseAsync(argv))).catch((err) => {
     console.error(`foreman: ${String(err)}`);
     process.exit(err instanceof HumanDecisionRequired ? 2 : 1);
 });

package/dist/installOwnership.d.ts

@@ -0,0 +1,46 @@
+import type { InstallDependencyV1, InstallManifest, InstallManifestEntryV1, InstallManifestEntryV2, InstallManifestV2, InstallOwnershipCategory } from "rafi-spec";
+export declare const INSTALL_MANIFEST = ".rafi/install-manifest.json";
+export declare const OWNERSHIP_BACKUPS = ".rafi/ownership-backups";
+export declare function initializeInstallManifest(projectDir: string, dirtyChoice: InstallManifestV2["repository"]["dirtyChoice"]): InstallManifestV2;
+export declare function readInstallManifest(projectDir: string): InstallManifestV2 | undefined;
+export declare function registerOwnedFile(projectDir: string, relativePath: string, input: Omit<InstallManifestEntryV1, "path" | "sha256"> & {
+    sha256?: string | null;
+    category?: InstallOwnershipCategory;
+}): InstallManifestV2;
+export declare function prepareOwnedWrite(projectDir: string, relativePath: string, origin: string, category: InstallOwnershipCategory): InstallManifestV2;
+export declare function finalizePreparedOwnedWrite(projectDir: string, relativePath: string, origin: string, category: InstallOwnershipCategory): InstallManifestV2;
+/** Capture an exact pre-Rafi file before a managed write. */
+export declare function capturePreimage(projectDir: string, relativePath: string, origin: string, category?: InstallOwnershipCategory): InstallManifestEntryV2;
+export declare function finalizeOwnedWrite(projectDir: string, entry: InstallManifestEntryV2): InstallManifestV2;
+export declare function registerDependency(projectDir: string, dependency: InstallDependencyV1): InstallManifestV2;
+export declare function validateInstallManifest(projectDir: string, manifest: InstallManifest): void;
+export declare function validateOwnedPath(projectDir: string, value: string): string;
+export declare function listOwnedTree(projectDir: string, relativeDirectory: string): string[];
+export declare function removeOwnedPathsTransaction(projectDir: string, paths: string[]): {
+    runId: string;
+    recoveryId: string;
+    removed: string[];
+};
+export declare function restoreOwnedPreimagesTransaction(projectDir: string, entries: InstallManifestEntryV2[]): {
+    runId: string;
+    recoveryId: string;
+    restored: string[];
+};
+/** Preserve recorded pre-Rafi bytes for a file the user chose to keep today. */
+export declare function preservePreimagesForLaterRestore(projectDir: string, entries: InstallManifestEntryV2[]): {
+    recoveryId: string;
+    preserved: string[];
+} | undefined;
+export declare function removeManagedBlocksTransaction(projectDir: string, entries: InstallManifestEntryV2[]): {
+    runId: string;
+    recoveryId: string;
+    edited: string[];
+};
+export declare function restoreUninstallRecovery(projectDir: string, recoveryId: string, selectedPaths?: string[], overwrite?: boolean): {
+    restored: string[];
+    collisions: string[];
+    backupId?: string;
+};
+export declare function cleanupUninstallRecovery(projectDir: string, recoveryIds: string[]): string[];
+export declare function listUninstallRecoveries(projectDir: string): string[];
+export declare function categorizeOwnedPath(path: string, mode?: string): InstallOwnershipCategory;