ai-foreman 1.7.4 → 1.7.6

package/dist/foreman.d.ts

@@ -1,5 +1,6 @@
-import type { BuilderAdapter, PermissionHandler, TurnResult } from "./adapters/types.js";
+import type { BuilderAdapter, PermissionHandler, PermissionRequest, TurnResult } from "./adapters/types.js";
 import type { PermissionPolicy } from "./permissions/policy.js";
+import { type AnsweredProviderQuestion } from "./providerQuestions.js";
 import type { Log } from "./log.js";
 import { type QaNonconvergenceContext, type QaNonconvergenceDecision } from "./qaReview.js";
 import type { SessionStrategy } from "rafi-spec";
@@ -26,7 +27,7 @@ export declare function looksLikeQuestion(text: string): boolean;
 export { MARKER_SPEC } from "./markers.js";
 export { QA_MARKER_SPEC } from "./markers.js";
 /** Instruction sent on the first turn of a batch. */
-export declare function buildPrimer(n: number, trackerPath?: string, ticketsEnabled?: boolean): string;
+export declare function buildPrimer(n: number, trackerPath?: string, ticketsEnabled?: boolean, preferredTicketId?: string): string;
 /** Instruction sent on turns 2–N. */
 export declare function buildNextStepInstruction(i: number, n: number): string;
 /** QA review turn: ask the builder to triple-check the ticket or step it just completed. */
@@ -34,10 +35,12 @@ export declare function buildQaInstruction(): string;
 /** Follow-up turn after qa_fail: have the builder implement the listed fixes. */
 export declare function buildQaFixInstruction(issues: string): string;
 /** Pre-flight planning turn: ask the builder to list its next N steps without implementing anything. */
-export declare function buildPlanningTurn(n: number, ticketsContent?: string): string;
+export declare function buildPlanningTurn(n: number, ticketsContent?: string, preferredTicketId?: string): string;
 /** Builds the permission callback: classify, log, allow or escalate. */
 export declare function createPermissionHandler(policy: PermissionPolicy, log: Log, opts?: {
     interactive?: boolean;
+    onAnsweredQuestion?: (event: AnsweredProviderQuestion) => void;
+    onProviderQuestion?: (request: PermissionRequest) => void;
 }): PermissionHandler;
 export interface BatchResult {
     completed: number;
@@ -71,7 +74,7 @@ export declare class Foreman {
     private prepareBuilderBoundary;
     private doTurnWith;
     /** Send a planning turn and return the builder's response text. Does not count toward steps. */
-    runPreflight(n: number, ticketsContent?: string): Promise<string>;
+    runPreflight(n: number, ticketsContent?: string, preferredTicketId?: string): Promise<string>;
     /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */
     sendPreflightFeedback(feedback: string): Promise<void>;
     /** Send one custom instruction through the same needs_input loop as a batch turn. */
@@ -95,5 +98,5 @@ export declare class Foreman {
     builderAdapter(): BuilderAdapter;
     close(): Promise<void>;
     private ticketForQa;
-    runBatch(n: number, trackerPath?: string): Promise<BatchResult>;
+    runBatch(n: number, trackerPath?: string, onTicketStart?: (ticketId: string) => void | Promise<void>, preferredTicketId?: string): Promise<BatchResult>;
 }

package/dist/foreman.js

@@ -107,7 +107,7 @@ export function looksLikeQuestion(text) {
 export { MARKER_SPEC } from "./markers.js";
 export { QA_MARKER_SPEC } from "./markers.js";
 /** Instruction sent on the first turn of a batch. */
-export function buildPrimer(n, trackerPath, ticketsEnabled = false) {
+export function buildPrimer(n, trackerPath, ticketsEnabled = false, preferredTicketId) {
     let trackerRule;
     if (ticketsEnabled) {
         const progressDoc = trackerPath ?? "docs/ticket-progress.md";
@@ -122,12 +122,15 @@ export function buildPrimer(n, trackerPath, ticketsEnabled = false) {
     else {
         trackerRule = "";
     }
+    const preferredTicketRule = preferredTicketId
+        ? `\n- Resume and finish ticket ${preferredTicketId} first. Do not substitute a different queued ticket.`
+        : "";
     return `You are being run by an automated foreman. We will work through your next ${n} tickets or implementation steps, one per turn.
 
 Rules:
 - Do exactly ONE ticket or step this turn, then stop.
 - ${MARKER_SPEC}
-- If a tool action is denied by foreman policy, do not retry it; report it via the blocked marker.${trackerRule}
+- If a tool action is denied by foreman policy, do not retry it; report it via the blocked marker.${trackerRule}${preferredTicketRule}
 
 This is step 1 of ${n}. Implement the next ticket or step now.`;
 }
@@ -160,17 +163,23 @@ ${issues}
 Fix every one of them now. Then end with STEP_STATUS: done so foreman can re-run QA on the fixes. Triple-check that your fixes actually resolve the issues before emitting done.`;
 }
 /** Pre-flight planning turn: ask the builder to list its next N steps without implementing anything. */
-export function buildPlanningTurn(n, ticketsContent) {
+export function buildPlanningTurn(n, ticketsContent, preferredTicketId) {
     const header = ticketsContent
         ? `Here is the project's ticket list:\n\n${ticketsContent}\n\n`
         : "";
-    return `${header}Before we begin, list the next ${n} ticket(s) or step(s) you plan to implement, in order. Be specific — reference ticket IDs or titles where applicable. Do not implement anything yet; output the numbered list only. Do not emit a STEP_STATUS marker on this turn.`;
+    const preferred = preferredTicketId
+        ? ` The first item must be ticket ${preferredTicketId}; this is an interrupted ticket being resumed.`
+        : "";
+    return `${header}Before we begin, list the next ${n} ticket(s) or step(s) you plan to implement, in order.${preferred} Be specific — reference ticket IDs or titles where applicable. Do not implement anything yet; output the numbered list only. Do not emit a STEP_STATUS marker on this turn.`;
 }
 /** Builds the permission callback: classify, log, allow or escalate. */
 export function createPermissionHandler(policy, log, opts = {}) {
     return async (req) => {
+        if (req.toolName === "AskUserQuestion")
+            opts.onProviderQuestion?.(req);
         const providerQuestion = await handleProviderQuestionTool(req, {
             interactive: opts.interactive ?? true,
+            onAnsweredQuestion: opts.onAnsweredQuestion,
         });
         if (providerQuestion) {
             log.write("permission", {
@@ -315,8 +324,8 @@ export class Foreman {
         return { result, status };
     }
     /** Send a planning turn and return the builder's response text. Does not count toward steps. */
-    async runPreflight(n, ticketsContent) {
-        const instruction = buildPlanningTurn(n, ticketsContent);
+    async runPreflight(n, ticketsContent, preferredTicketId) {
+        const instruction = buildPlanningTurn(n, ticketsContent, preferredTicketId);
         const result = await this.builder.sendTurn(instruction);
         this.log.write("preflight", {
             ticketsProvided: ticketsContent !== undefined,
@@ -343,10 +352,10 @@ export class Foreman {
      * Loops on qa_fail → fix → re-QA until qa_pass or the cycle cap is reached.
      * QA turns are free — they do not advance the step counter.
      */
-    async runQa(stepIndex) {
+    async runQa(stepIndex, ticketId) {
         if (this.projectDir && this.qaFactory) {
             const review = await runIsolatedQa({
-                ticket: this.ticketForQa(stepIndex),
+                ticket: this.ticketForQa(stepIndex, ticketId),
                 builderWorktree: this.projectDir,
                 builderSummary: `Builder completed step ${stepIndex}`,
                 qaStrategy: this.qaSessionStrategy,
@@ -436,10 +445,12 @@ export class Foreman {
     builderSessionId() { return this.builder.sessionId(); }
     builderAdapter() { return this.builder; }
     async close() { await this.builder.close(); }
-    ticketForQa(stepIndex) {
+    ticketForQa(stepIndex, ticketId) {
         if (this.projectDir && this.ticketsEnabled) {
             const config = loadTicketsConfig(this.projectDir);
-            const active = cmdImplementationQueue(this.projectDir).find((row) => row.status === "next" || row.status === "in_progress");
+            const active = ticketId
+                ? { ticket: ticketId }
+                : cmdImplementationQueue(this.projectDir).find((row) => row.status === "next" || row.status === "in_progress");
             const ticket = loadTickets(join(this.projectDir, config.paths.tickets)).find((candidate) => candidate.id === active?.ticket);
             if (ticket)
                 return ticket;
@@ -450,7 +461,7 @@ export class Foreman {
             acceptance: ["The requested implementation step is complete"], required_tests: ["Run the relevant project validation"], likely_files: [],
         };
     }
-    async runBatch(n, trackerPath) {
+    async runBatch(n, trackerPath, onTicketStart, preferredTicketId) {
         this.log.write("batch-start", { requested: n, agent: this.builder.agent });
         let completed = 0;
         let outcome = "all-done";
@@ -461,9 +472,22 @@ export class Foreman {
             if (this.ticketsEnabled && this.projectDir) {
                 try {
                     const queue = cmdImplementationQueue(this.projectDir);
-                    const next = queue.find((r) => r.status === "next");
+                    const next = i === 1 && preferredTicketId
+                        ? queue.find((row) => row.ticket === preferredTicketId)
+                        : queue.find((row) => row.status === "next");
+                    if (i === 1 && preferredTicketId && !next) {
+                        outcome = "needs-human";
+                        detail = `recovery ticket ${preferredTicketId} is no longer available in the implementation queue`;
+                        break;
+                    }
+                    if (i === 1 && preferredTicketId && next && next.status !== "next" && next.status !== "in_progress") {
+                        outcome = "needs-human";
+                        detail = `recovery ticket ${preferredTicketId} cannot resume while its status is ${next.status}`;
+                        break;
+                    }
                     if (next) {
                         pendingTicketId = next.ticket;
+                        await onTicketStart?.(next.ticket);
                         cmdUpdate(this.projectDir, next.ticket, {
                             status: "in_progress",
                             actor: "foreman",
@@ -478,7 +502,7 @@ export class Foreman {
                 }
             }
             const instruction = i === 1
-                ? buildPrimer(n, trackerPath, this.ticketsEnabled)
+                ? buildPrimer(n, trackerPath, this.ticketsEnabled, preferredTicketId)
                 : buildNextStepInstruction(i, n);
             if (i > 1)
                 await this.prepareBuilderBoundary();
@@ -503,7 +527,7 @@ export class Foreman {
                 let qaSummary;
                 let qaWaived = false;
                 if (this.qaEnabled) {
-                    const qa = await this.runQa(i);
+                    const qa = await this.runQa(i, status.ticket ?? pendingTicketId);
                     if (qa.outcome === "blocked") {
                         outcome = "blocked";
                         detail = qa.detail;

package/dist/index.js

@@ -5,6 +5,7 @@ import { buildTicketsCommand } from "./cli/tickets.js";
 import { buildStartCommand } from "./cli/start.js";
 import { buildStatusCommand } from "./cli/status.js";
 import { buildDoctorCommand } from "./cli/doctor.js";
+import { withActivityContext } from "./activity.js";
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"))?.version;
 const program = new Command();
 program
@@ -20,7 +21,8 @@ program.addCommand(buildDoctorCommand());
 const argv = [...process.argv];
 if (argv[2] === "--")
     argv.splice(2, 1);
-program.parseAsync(argv).catch((err) => {
+const command = argv.slice(2).filter((arg) => !arg.startsWith("-")).slice(0, 3).join(" ") || "ai-foreman";
+withActivityContext(command, () => program.parseAsync(argv)).catch((err) => {
     console.error(`foreman: ${String(err)}`);
     process.exit(1);
 });

package/dist/providerQuestions.d.ts

@@ -1,5 +1,16 @@
 import { isCancel, multiselect, select, text } from "@clack/prompts";
 import type { PermissionDecision, PermissionRequest } from "./adapters/types.js";
+export interface PromptOption {
+    label: string;
+    description?: string;
+    preview?: string;
+}
+export interface ProviderQuestion {
+    question: string;
+    header?: string;
+    options: PromptOption[];
+    multiSelect: boolean;
+}
 export interface ProviderQuestionPromptDeps {
     select: typeof select;
     multiselect: typeof multiselect;
@@ -9,6 +20,18 @@ export interface ProviderQuestionPromptDeps {
 export interface ProviderQuestionOptions {
     interactive: boolean;
     prompts?: ProviderQuestionPromptDeps;
+    /** Called only after a non-empty answer has been successfully collected. */
+    onAnsweredQuestion?: (event: AnsweredProviderQuestion) => void;
+}
+export interface AnsweredProviderQuestion {
+    toolName: "AskUserQuestion";
+    question: ProviderQuestion;
+    /** Number of readable questions presented by this provider tool call. */
+    questionCount: number;
+    answer: string;
 }
+export declare const GRILL_ME_STOP_CHOICE = "Stop questions and make the plan now";
 export declare function handleProviderQuestionTool(req: PermissionRequest, opts: ProviderQuestionOptions): Promise<PermissionDecision | undefined>;
+/** Machine-recognizable native grill-me question shape. */
+export declare function isGrillMeProviderQuestion(event: AnsweredProviderQuestion): boolean;
 export declare function countProviderQuestions(input: Record<string, unknown>): number;

package/dist/providerQuestions.js

@@ -1,6 +1,7 @@
 import { isCancel, multiselect, select, text } from "@clack/prompts";
 const ASK_USER_QUESTION_TOOL = "AskUserQuestion";
 const CUSTOM_VALUE = "__rafi_custom_response__";
+export const GRILL_ME_STOP_CHOICE = "Stop questions and make the plan now";
 export async function handleProviderQuestionTool(req, opts) {
     if (req.toolName !== ASK_USER_QUESTION_TOOL)
         return undefined;
@@ -34,6 +35,14 @@ export async function handleProviderQuestionTool(req, opts) {
         answers[question.question] = answered.answer;
         if (answered.annotation)
             annotations[question.question] = answered.annotation;
+        if (answered.answer.trim()) {
+            opts.onAnsweredQuestion?.({
+                toolName: ASK_USER_QUESTION_TOOL,
+                question,
+                questionCount: questions.length,
+                answer: answered.answer,
+            });
+        }
     }
     const updatedInput = {
         ...req.input,
@@ -43,6 +52,21 @@ export async function handleProviderQuestionTool(req, opts) {
         updatedInput.annotations = annotations;
     return { behavior: "allow", updatedInput };
 }
+/** Machine-recognizable native grill-me question shape. */
+export function isGrillMeProviderQuestion(event) {
+    const { question } = event;
+    if (event.questionCount !== 1 || question.multiSelect)
+        return false;
+    if (!/^grill-me\b/i.test(question.header ?? ""))
+        return false;
+    const labels = question.options.map((option) => option.label.trim());
+    if (labels.length < 3 || !labels[0]?.endsWith("(Recommended)"))
+        return false;
+    const stopIndex = labels.indexOf(GRILL_ME_STOP_CHOICE);
+    if (stopIndex < 0)
+        return false;
+    return labels.some((label, index) => index > 0 && index !== stopIndex && label.length > 0);
+}
 export function countProviderQuestions(input) {
     const questions = input.questions;
     return Array.isArray(questions) ? questions.length : 0;

package/dist/qaReview.d.ts

@@ -45,6 +45,7 @@ export interface IsolatedQaResult {
     summary?: string;
 }
 export declare function runIsolatedQa(opts: IsolatedQaOptions): Promise<IsolatedQaResult>;
+export declare function buildQaReviewHandoff(ticket: TicketDef, builderSummary: string, diffDigest: string, validationChecklist: string[]): string;
 export declare function compactWithRetry(adapter: BuilderAdapter): Promise<{
     ok: boolean;
     error?: string;

package/dist/qaReview.js

@@ -1,9 +1,11 @@
+import { currentActivity, withActivityPhase } from "./activity.js";
 import { buildQaFixInstruction, buildQaInstruction, parseStepStatus } from "./foreman.js";
-import { createDisposableQaSnapshot } from "./qaSnapshot.js";
+import { createDisposableQaSnapshotAsync } from "./qaSnapshot.js";
+import { loadTicketSetupConfigWithDefaults } from "./tickets/setupConfig.js";
 export async function runIsolatedQa(opts) {
     const history = [];
     for (let cycle = 1; cycle <= opts.maxCycles; cycle++) {
-        const review = await oneReview(opts, cycle);
+        const review = await withActivityPhase(`running QA cycle ${cycle}/${opts.maxCycles}`, () => oneReview(opts, cycle));
         if (review.outcome === "retry-modification") {
             cycle -= 1;
             continue;
@@ -15,7 +17,7 @@ export async function runIsolatedQa(opts) {
         history.push({ cycle, outcome: "qa_fail", detail: review.detail });
         if (cycle === opts.maxCycles)
             break;
-        const fix = await opts.fix(review.detail ?? "QA reported unspecified issues");
+        const fix = await withActivityPhase("applying QA fixes", () => opts.fix(review.detail ?? "QA reported unspecified issues"));
         if (!fix.ok)
             return { outcome: "blocked", detail: fix.detail ?? "Builder QA fix failed" };
     }
@@ -30,36 +32,32 @@ export async function runIsolatedQa(opts) {
     const issues = decision.action === "remediate" ? decision.remediation : history.at(-1)?.detail;
     if (!issues)
         return { outcome: "nonconverged", detail: "Planner remediation did not produce approved fix instructions" };
-    const fix = await opts.fix(issues);
+    const fix = await withActivityPhase("applying QA remediation", () => opts.fix(issues));
     if (!fix.ok)
         return { outcome: "blocked", detail: fix.detail ?? "Builder QA fix failed" };
     return runIsolatedQa(opts);
 }
 async function oneReview(opts, cycle) {
-    const snapshot = createDisposableQaSnapshot(opts.builderWorktree);
+    const progress = (state, detail) => currentActivity()?.update(state, detail);
+    const snapshot = await withActivityPhase("preparing disposable QA snapshot", () => createDisposableQaSnapshotAsync(opts.builderWorktree, progress));
     let qa;
     try {
         const resume = opts.qaStrategy === "compact" && opts.state.modificationViolations === 0 ? opts.state.sessionId : undefined;
         qa = await opts.createQa(snapshot.path, resume);
         if (opts.qaStrategy === "compact" && opts.state.reviews > 0 && resume) {
-            const compacted = await compactWithRetry(qa);
+            const compacted = await withActivityPhase("compacting QA session", () => compactWithRetry(qa));
             if (!compacted.ok) {
                 await qa.close();
                 qa = await opts.createQa(snapshot.path);
                 opts.state.sessionId = undefined;
             }
         }
-        const handoff = [
-            buildQaInstruction(), "", "QA handoff:", `Ticket: ${opts.ticket.id} — ${opts.ticket.title}`,
-            `Acceptance: ${opts.ticket.acceptance.join("; ")}`, `Builder summary: ${opts.builderSummary}`,
-            `Changed files/diff digest: ${snapshot.manifest.diffDigest}`, `Required tests: ${opts.ticket.required_tests.join("; ")}`,
-            "Do not change source, configuration, documentation, tickets, or control files. Only ignored cache, coverage, and build output is allowed.",
-        ].join("\n");
+        const handoff = buildQaReviewHandoff(opts.ticket, opts.builderSummary, snapshot.manifest.diffDigest, loadTicketSetupConfigWithDefaults(opts.builderWorktree).build.validation_checklist);
         const turn = await qa.sendTurn(handoff);
         const status = parseStepStatus(turn.text);
         opts.state.reviews += 1;
         opts.state.sessionId = qa.sessionId();
-        const changes = snapshot.qaChanges();
+        const changes = await withActivityPhase("checking QA file changes", () => snapshot.qaChanges());
         if (changes.length) {
             opts.state.modificationViolations += 1;
             opts.evidence?.({ cycle, outcome: "qa_file_modification", detail: "QA modified the disposable review copy", qaDiff: changes });
@@ -82,10 +80,20 @@ async function oneReview(opts, cycle) {
         return { outcome: "needs-human", detail: status.error ?? `QA returned ${status.kind}` };
     }
     finally {
-        await qa?.close().catch(() => { });
-        snapshot.remove();
+        if (qa)
+            await withActivityPhase("closing QA session", () => qa.close().catch(() => { }));
+        await withActivityPhase("cleaning up disposable QA snapshot", () => snapshot.remove());
     }
 }
+export function buildQaReviewHandoff(ticket, builderSummary, diffDigest, validationChecklist) {
+    return [
+        buildQaInstruction(), "", "QA handoff:", `Ticket: ${ticket.id} — ${ticket.title}`,
+        `Acceptance: ${ticket.acceptance.join("; ")}`, `Builder summary: ${builderSummary}`,
+        `Changed files/diff digest: ${diffDigest}`, `Required tests: ${ticket.required_tests.join("; ")}`,
+        `Project validation checklist: ${validationChecklist.join("; ")}`,
+        "Do not change source, configuration, documentation, tickets, or control files. Only ignored cache, coverage, and build output is allowed.",
+    ].join("\n");
+}
 export async function compactWithRetry(adapter) {
     if (!adapter.compact)
         return { ok: false, error: "native compaction unavailable" };

package/dist/qaSnapshot.d.ts

@@ -14,6 +14,20 @@ export interface DisposableQaSnapshot {
     qaChanges(): string[];
     remove(): void;
 }
+export interface AsyncDisposableQaSnapshot {
+    path: string;
+    manifest: QaChangeManifest;
+    verify(): Promise<void>;
+    qaChanges(): Promise<string[]>;
+    remove(): Promise<void>;
+}
+export type QaSnapshotProgress = (state: string, detail?: string) => void;
 /** Reproduce the Builder's exact change set in a detached disposable worktree. */
 export declare function createDisposableQaSnapshot(builderWorktree: string): DisposableQaSnapshot;
+/**
+ * Async form used by the live CLI. Git and filesystem work yields to the event
+ * loop so the activity reporter can keep animating during large snapshots.
+ */
+export declare function createDisposableQaSnapshotAsync(builderWorktree: string, progress?: QaSnapshotProgress): Promise<AsyncDisposableQaSnapshot>;
 export declare function changeManifest(worktree: string): QaChangeManifest;
+export declare function changeManifestAsync(worktree: string, progress?: QaSnapshotProgress, state?: string): Promise<QaChangeManifest>;

package/dist/qaSnapshot.js

@@ -1,8 +1,9 @@
 import { createHash } from "node:crypto";
 import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readlinkSync, rmSync, symlinkSync } from "node:fs";
+import { cp, lstat, mkdir, mkdtemp, readFile, readlink, rm, symlink } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { execFileSync, spawnSync } from "node:child_process";
+import { execFileSync, spawn, spawnSync } from "node:child_process";
 /** Reproduce the Builder's exact change set in a detached disposable worktree. */
 export function createDisposableQaSnapshot(builderWorktree) {
     const source = resolve(builderWorktree);
@@ -47,6 +48,69 @@ export function createDisposableQaSnapshot(builderWorktree) {
         throw error;
     }
 }
+/**
+ * Async form used by the live CLI. Git and filesystem work yields to the event
+ * loop so the activity reporter can keep animating during large snapshots.
+ */
+export async function createDisposableQaSnapshotAsync(builderWorktree, progress = () => { }) {
+    const source = resolve(builderWorktree);
+    progress("preparing disposable QA snapshot", "locating Builder worktree");
+    const root = (await runGit(source, ["rev-parse", "--show-toplevel"])).toString().trim();
+    const tempRoot = await mkdtemp(join(tmpdir(), "rafi-qa-"));
+    const review = join(tempRoot, "review");
+    const head = (await runGit(source, ["rev-parse", "HEAD"])).toString().trim();
+    progress("preparing disposable QA snapshot", "creating detached review worktree");
+    try {
+        await runGit(root, ["worktree", "add", "--detach", review, head]);
+    }
+    catch (error) {
+        await rm(tempRoot, { recursive: true, force: true });
+        throw new Error(`cannot create disposable QA worktree: ${errorMessage(error)}`);
+    }
+    try {
+        progress("preparing disposable QA snapshot", "copying tracked Builder changes");
+        const diff = await runGit(source, ["diff", "--binary", "HEAD"]);
+        if (diff.length) {
+            try {
+                await runGit(review, ["apply", "--index", "--binary", "--whitespace=nowarn", "-"], diff);
+            }
+            catch (error) {
+                throw new Error(`cannot apply Builder diff to QA worktree: ${errorMessage(error)}`);
+            }
+        }
+        const paths = await untrackedPathsAsync(source);
+        for (let index = 0; index < paths.length; index++) {
+            progress("preparing disposable QA snapshot", `copying untracked files ${index + 1}/${paths.length}`);
+            await copyUntrackedAsync(source, review, paths[index]);
+        }
+        progress("preparing disposable QA snapshot", "recording Builder change manifest");
+        const manifest = await changeManifestAsync(source, progress, "preparing disposable QA snapshot");
+        const snapshot = {
+            path: review,
+            manifest,
+            verify: async () => {
+                const actual = await changeManifestAsync(review, progress, "preparing disposable QA snapshot");
+                if (JSON.stringify(actual) !== JSON.stringify(manifest)) {
+                    throw new Error(`disposable QA snapshot does not match Builder change manifest: expected ${JSON.stringify(manifest)}, got ${JSON.stringify(actual)}`);
+                }
+            },
+            qaChanges: async () => manifestDifference(manifest, await changeManifestAsync(review, progress)),
+            remove: async () => {
+                progress("cleaning up disposable QA snapshot", "removing detached review worktree");
+                await runGit(root, ["worktree", "remove", "--force", review]).catch(() => { });
+                await rm(tempRoot, { recursive: true, force: true });
+            },
+        };
+        progress("preparing disposable QA snapshot", "verifying review copy");
+        await snapshot.verify();
+        return snapshot;
+    }
+    catch (error) {
+        await runGit(root, ["worktree", "remove", "--force", review]).catch(() => { });
+        await rm(tempRoot, { recursive: true, force: true });
+        throw error;
+    }
+}
 export function changeManifest(worktree) {
     const diff = execFileSync("git", ["-C", worktree, "diff", "--binary", "HEAD"], { encoding: "buffer", maxBuffer: 128 * 1024 * 1024 });
     const untracked = untrackedPaths(worktree).map((path) => {
@@ -58,10 +122,29 @@ export function changeManifest(worktree) {
     });
     return { diffDigest: createHash("sha256").update(diff).digest("hex"), untracked };
 }
+export async function changeManifestAsync(worktree, progress = () => { }, state = "checking QA file changes") {
+    const diff = await runGit(worktree, ["diff", "--binary", "HEAD"]);
+    const paths = await untrackedPathsAsync(worktree);
+    const untracked = [];
+    for (let index = 0; index < paths.length; index++) {
+        const path = paths[index];
+        progress(state, `hashing untracked files ${index + 1}/${paths.length}`);
+        const absolute = join(worktree, path);
+        const stat = await lstat(absolute);
+        const kind = stat.isSymbolicLink() ? "symlink" : "file";
+        const bytes = kind === "symlink" ? Buffer.from(await readlink(absolute)) : await readFile(absolute);
+        untracked.push({ path, kind, mode: stat.mode & 0o7777, digest: createHash("sha256").update(bytes).digest("hex") });
+    }
+    return { diffDigest: createHash("sha256").update(diff).digest("hex"), untracked };
+}
 function untrackedPaths(worktree) {
     const raw = execFileSync("git", ["-C", worktree, "ls-files", "--others", "--exclude-standard", "-z"], { encoding: "buffer" });
     return raw.toString().split("\0").filter(Boolean).sort();
 }
+async function untrackedPathsAsync(worktree) {
+    const raw = await runGit(worktree, ["ls-files", "--others", "--exclude-standard", "-z"]);
+    return raw.toString().split("\0").filter(Boolean).sort();
+}
 function copyUntracked(source, target, path) {
     const from = join(source, path);
     const to = join(target, path);
@@ -75,6 +158,39 @@ function copyUntracked(source, target, path) {
     else
         cpSync(from, to, { preserveTimestamps: true });
 }
+async function copyUntrackedAsync(source, target, path) {
+    const from = join(source, path);
+    const to = join(target, path);
+    await mkdir(dirname(to), { recursive: true });
+    const stat = await lstat(from);
+    if (stat.isSymbolicLink()) {
+        await rm(to, { force: true });
+        await symlink(await readlink(from), to);
+    }
+    else {
+        await cp(from, to, { preserveTimestamps: true });
+    }
+}
+function runGit(cwd, args, input) {
+    return new Promise((resolvePromise, reject) => {
+        const child = spawn("git", ["-C", cwd, ...args], { stdio: ["pipe", "pipe", "pipe"] });
+        const stdout = [];
+        const stderr = [];
+        child.stdout.on("data", (chunk) => stdout.push(chunk));
+        child.stderr.on("data", (chunk) => stderr.push(chunk));
+        child.on("error", reject);
+        child.on("close", (code) => {
+            if (code === 0)
+                resolvePromise(Buffer.concat(stdout));
+            else
+                reject(new Error(Buffer.concat(stderr).toString().trim() || `git exited with status ${code ?? "unknown"}`));
+        });
+        child.stdin.end(input);
+    });
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
 function manifestDifference(before, after) {
     const changes = [];
     if (before.diffDigest !== after.diffDigest)

package/dist/runtimeReadiness.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { accessSync, constants, statSync } from "node:fs";
 import { delimiter, isAbsolute, resolve } from "node:path";
+import { currentActivity, withActivityPhase } from "./activity.js";
 export const RUNTIME_PROBE_TIMEOUT_MS = 30_000;
 export const RUNTIME_DIAGNOSTIC_LIMIT = 8 * 1024;
 const RELEVANT_ENV = /^(ANTHROPIC|CLAUDE|CODEX|OPENAI|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|SSL_CERT_FILE|NODE_EXTRA_CA_CERTS)(_|$)/i;
@@ -52,6 +53,9 @@ function isRunnableFile(path, platform) {
     }
 }
 export async function probeRuntime(cwd, runtime, opts = {}) {
+    return withActivityPhase(`checking ${runtime} runtime`, () => probeRuntimeInternal(cwd, runtime, opts));
+}
+async function probeRuntimeInternal(cwd, runtime, opts) {
     const env = opts.env ?? process.env;
     const command = runtime === "claude" ? "claude" : "codex";
     const executable = resolveExecutablePath(command, env) ?? command;
@@ -68,6 +72,7 @@ export async function probeRuntime(cwd, runtime, opts = {}) {
         const spawnOpts = { cwd, env, stdio: ["ignore", "pipe", "pipe"] };
         const child = spawn(executable, args, spawnOpts);
         const append = (chunk) => {
+            currentActivity()?.pulse(`${runtime} runtime responded`);
             if (output.length >= limit)
                 return;
             const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);

package/dist/sources/sourceRegistry.js

@@ -1,10 +1,13 @@
-import { execFileSync } from "node:child_process";
+import { execFile, execFileSync } from "node:child_process";
+import { promisify } from "node:util";
 import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { basename, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parse, stringify } from "yaml";
 import { fetchAndSnapshotUrl, normalizePublicHttpUrl, snapshotExternalLocalFile } from "../tickets/sourceFetch.js";
 import { fetchJiraIssues, fetchLinearIssues } from "../tickets/importer.js";
+import { withActivityPhase } from "../activity.js";
+const execFileAsync = promisify(execFile);
 export const SOURCE_REQUEST_START = "RAFI_SOURCE_REQUEST_START";
 export const SOURCE_REQUEST_END = "RAFI_SOURCE_REQUEST_END";
 const CONFIG_FILE = "rafi-config.yaml";
@@ -148,9 +151,12 @@ export function sourceRequestFromAnswer(answer, projectDir) {
     if (/^https?:\/\/\S+$/i.test(value))
         return requestFromUrl(value);
     const candidate = resolve(projectDir, value);
-    if (value && existsSync(candidate))
-        return { type: "local", label: basename(candidate), locator: { path: normalizeLocalPath(projectDir, candidate) } };
-    if (hasGlobMagic(value) || /^(?:\.{0,2}\/|\/)/.test(value) || /[\\/][^\\/]+\.[A-Za-z0-9]{1,12}$/.test(value))
+    if (value && existsSync(candidate)) {
+        const rel = relative(resolve(projectDir), candidate);
+        const path = !rel.startsWith(`..${sep}`) && rel !== ".." && !isAbsolute(rel) ? rel || "." : candidate;
+        return { type: "local", label: basename(candidate), locator: { path } };
+    }
+    if (hasGlobMagic(value) || /^(?:\.{0,2}\/|\/)/.test(value) || /^[^\s]+[\\/][^\\/]+\.[A-Za-z0-9]{1,12}$/.test(value))
         return { type: "local", label: basename(value), locator: { path: value } };
     if (/^(?:open\s+)?issues\s+for\s+(?:this|the)\s+repo(?:sitory)?$/i.test(value))
         return { type: inferOriginProvider(projectDir), label: "Open repository issues", locator: { repository: inferOriginRepository(projectDir), mode: "issues", filters: { state: "open" } } };
@@ -272,7 +278,7 @@ async function captureUrl(projectDir, entry, storage) {
     rmSync(resolve(projectDir, fetched.metadataPath), { force: true });
     return version;
 }
-function captureCliProvider(projectDir, entry, storage) {
+async function captureCliProvider(projectDir, entry, storage) {
     const repository = entry.locator.repository || inferOriginRepository(projectDir);
     const mode = entry.locator.mode ?? "issues";
     let command;
@@ -309,7 +315,8 @@ function captureCliProvider(projectDir, entry, storage) {
     }
     let text;
     try {
-        text = execFileSync(command, args, { cwd: projectDir, encoding: "utf8", maxBuffer: 20 * 1024 * 1024 });
+        const result = await withActivityPhase(`fetching ${entry.type} source`, () => execFileAsync(command, args, { cwd: projectDir, encoding: "utf8", maxBuffer: 20 * 1024 * 1024 }));
+        text = result.stdout;
     }
     catch (error) {
         throw new Error(`${entry.type} source ${entry.label} could not be retrieved with authenticated ${command}: ${error instanceof Error ? error.message : String(error)}`);

package/dist/tickets/details.d.ts

@@ -0,0 +1,17 @@
+import { type DeliveryStack, type DeliveryUnit } from "./delivery.js";
+import { type TicketEvent, type TicketState, type ValidationSnapshot } from "./stateDb.js";
+import type { TicketDef } from "./ticketSchema.js";
+export interface TicketDeliveryDetails {
+    units: DeliveryUnit[];
+    stacks: DeliveryStack[];
+}
+export interface TicketDetails {
+    definition: TicketDef & Record<string, unknown>;
+    state: TicketState;
+    effective_blockers: string[];
+    validation_history: ValidationSnapshot[];
+    events: TicketEvent[];
+    delivery: TicketDeliveryDetails;
+}
+export declare function getTicketDetails(projectDir: string, ticketId: string, now?: Date): TicketDetails;
+export declare function formatTicketDetails(details: TicketDetails): string[];