ai-foreman 1.7.4 → 1.7.6

package/README.md

@@ -15,6 +15,9 @@ Loop Claude Code or Codex through tickets.
 - **Rich ticket system** — tickets carry acceptance criteria, required tests, dependencies, priority, size, and risk level. The agent reads the full context before starting each step.
 - **Future work tracking** — when the builder discovers out-of-scope work during a run, `ai-foreman tickets discover` captures it without derailing the current ticket. Discovered items live in a separate inbox until you promote them.
 - **QA that actually gates** — QA runs after every completed ticket and checks code quality, test passing, and regression protection. The ticket only closes after QA passes. QA turns do not count against `--steps`.
+- **Visible long-running work** — one elapsed-time activity line identifies provider, phase, tools, retries, and quiet periods; redirected output receives timestamped heartbeats instead of ANSI animation.
+
+Provider-managed retries are reported immediately as durable lines. A quiet-provider warning appears after 60 seconds without a signal, but Foreman does not add retries, abort the provider, or change provider retry limits. Non-TTY output receives a heartbeat every 30 seconds while work remains pending.
 
 ## Install
 
@@ -109,7 +112,7 @@ What each part does:
 | `--keep-worktrees` | flag | remove successful worktrees | Keeps successful ticket worktrees for inspection. Blocked worktrees are kept automatically. |
 | `--ticket <id>` | `T001` | none | Selects a branch-mode ticket to continue. Repeatable with `--continue`. |
 | `--base <ref>` | `main` / `origin/main` / `HEAD` | current branch or `HEAD` | Base ref for root ticket branches. |
-| `--branch-prefix <prefix>` | `rafi` / `feature` | `rafi` | Prefix for generated ticket branches. |
+| `--branch-prefix <prefix>` | `feature` / `rafi` / another valid Git prefix | `feature` | Prefix for generated ticket branches. Explicit prefixes are preserved verbatim. |
 | `--max-branch-depth <n>` | positive integer | `5` | Maximum selected branch/PR stack depth (root PR is depth 1). |
 
 Auto-detected tracker files:
@@ -523,6 +526,8 @@ STEP_STATUS: plan_complete | ticket="T001" summary="all requested work is comple
 STEP_STATUS: needs_input | question="Which storage backend?" choices="SQLite|Postgres"
 ```
 
+Provider-native `AskUserQuestion` prompts preserve their existing input/output behavior. Hosts may also observe a question only after the user successfully supplies a non-empty answer; cancelled, denied, malformed, and empty prompts do not emit answered-question telemetry. Rafi uses this boundary to recognize machine-shaped exhaustive-planning exchanges without treating generic questions as grill-me coverage.
+
 When QA is enabled, Foreman asks the builder to review its own work:
 
 ```txt

package/dist/activity.d.ts

@@ -0,0 +1,63 @@
+import type { BuilderEvent } from "./adapters/types.js";
+import { AsyncQueue } from "./util/asyncQueue.js";
+export interface ActivityOutput {
+    write(text: string): void;
+    readonly isTTY: boolean;
+}
+export interface ActivityReporterOptions {
+    output?: ActivityOutput;
+    now?: () => number;
+    displayDelayMs?: number;
+    tickMs?: number;
+    heartbeatMs?: number;
+    quietWarningMs?: number;
+}
+/** One process-local live view shared by nested RAFI operations. */
+export declare class ActivityReporter {
+    readonly command: string;
+    private readonly output;
+    private readonly now;
+    private readonly displayDelayMs;
+    private readonly tickMs;
+    private readonly heartbeatMs;
+    private readonly quietWarningMs;
+    private readonly commandStartedAt;
+    private readonly phases;
+    private nextPhaseId;
+    private frame;
+    private timer?;
+    private detail?;
+    private provider?;
+    private model?;
+    private lastSignalAt;
+    private quietWarningPrinted;
+    private lastHeartbeatAt;
+    private lineVisible;
+    private paused;
+    constructor(command: string, options?: ActivityReporterOptions);
+    begin(label: string): () => void;
+    update(state: string, detail?: string, metadata?: {
+        provider?: string;
+        model?: string;
+        immediate?: boolean;
+    }): void;
+    pulse(detail?: string): void;
+    note(message: string): void;
+    writePersistent(text: string): void;
+    pause(): () => void;
+    dispose(): void;
+    private startTimer;
+    private idle;
+    private currentPhase;
+    private render;
+    private clearLine;
+}
+export declare function currentActivity(): ActivityReporter | undefined;
+export declare function withActivityContext<T>(command: string, operation: () => Promise<T>, options?: ActivityReporterOptions): Promise<T>;
+export declare function withActivityPhase<T>(label: string, operation: () => Promise<T>): Promise<T>;
+export declare function pauseActivityForInput<T>(operation: () => Promise<T>): Promise<T>;
+export declare function reportBuilderEvent(event: BuilderEvent): void;
+/** Async event queue that also feeds the active CLI reporter without consuming the stream. */
+export declare class BuilderEventQueue extends AsyncQueue<BuilderEvent> {
+    push(event: BuilderEvent): void;
+}

package/dist/activity.js

@@ -0,0 +1,244 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { AsyncQueue } from "./util/asyncQueue.js";
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+/** One process-local live view shared by nested RAFI operations. */
+export class ActivityReporter {
+    command;
+    output;
+    now;
+    displayDelayMs;
+    tickMs;
+    heartbeatMs;
+    quietWarningMs;
+    commandStartedAt;
+    phases = new Map();
+    nextPhaseId = 1;
+    frame = 0;
+    timer;
+    detail;
+    provider;
+    model;
+    lastSignalAt = 0;
+    quietWarningPrinted = false;
+    lastHeartbeatAt = 0;
+    lineVisible = false;
+    paused = 0;
+    constructor(command, options = {}) {
+        this.command = command;
+        this.output = options.output ?? {
+            isTTY: Boolean(process.stdout.isTTY),
+            write: (text) => process.stdout.write(text),
+        };
+        this.now = options.now ?? Date.now;
+        this.displayDelayMs = options.displayDelayMs ?? 250;
+        this.tickMs = options.tickMs ?? 1_000;
+        this.heartbeatMs = options.heartbeatMs ?? 30_000;
+        this.quietWarningMs = options.quietWarningMs ?? 60_000;
+        this.commandStartedAt = this.now();
+    }
+    begin(label) {
+        const phase = { id: this.nextPhaseId++, label: clean(label, 100), startedAt: this.now() };
+        this.phases.set(phase.id, phase);
+        if (this.phases.size === 1) {
+            this.lastSignalAt = phase.startedAt;
+            this.lastHeartbeatAt = phase.startedAt;
+            this.quietWarningPrinted = false;
+            this.startTimer();
+        }
+        this.render(!this.output.isTTY);
+        let ended = false;
+        return () => {
+            if (ended)
+                return;
+            ended = true;
+            this.phases.delete(phase.id);
+            if (this.phases.size === 0)
+                this.idle();
+            else
+                this.render(true);
+        };
+    }
+    update(state, detail, metadata = {}) {
+        const phase = this.currentPhase();
+        if (phase && state)
+            phase.label = clean(state, 100);
+        this.detail = detail ? clean(detail, 120) : undefined;
+        this.provider = metadata.provider ?? this.provider;
+        this.model = metadata.model ?? this.model;
+        this.lastSignalAt = this.now();
+        this.quietWarningPrinted = false;
+        this.render(metadata.immediate !== false || this.output.isTTY);
+    }
+    pulse(detail) {
+        if (detail)
+            this.detail = clean(detail, 120);
+        this.lastSignalAt = this.now();
+        this.quietWarningPrinted = false;
+        this.render(this.output.isTTY);
+    }
+    note(message) {
+        this.clearLine();
+        this.output.write(`${clean(message, 500)}\n`);
+        this.render(true);
+    }
+    writePersistent(text) {
+        if (!text)
+            return;
+        this.clearLine();
+        this.output.write(text);
+        if (!text.endsWith("\n"))
+            this.output.write("\n");
+        this.render(true);
+    }
+    pause() {
+        this.paused++;
+        this.clearLine();
+        let resumed = false;
+        return () => {
+            if (resumed)
+                return;
+            resumed = true;
+            this.paused = Math.max(0, this.paused - 1);
+            this.render(true);
+        };
+    }
+    dispose() {
+        this.phases.clear();
+        this.idle();
+    }
+    startTimer() {
+        if (this.timer)
+            return;
+        this.timer = setInterval(() => this.render(false), this.tickMs);
+        this.timer.unref();
+    }
+    idle() {
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = undefined;
+        this.clearLine();
+        this.detail = undefined;
+        this.provider = undefined;
+        this.model = undefined;
+    }
+    currentPhase() {
+        return [...this.phases.values()].at(-1);
+    }
+    render(force) {
+        const phase = this.currentPhase();
+        if (!phase || this.paused > 0)
+            return;
+        const now = this.now();
+        const elapsed = now - phase.startedAt;
+        if (!force && elapsed < this.displayDelayMs)
+            return;
+        const quietFor = now - this.lastSignalAt;
+        if (quietFor >= this.quietWarningMs && !this.quietWarningPrinted) {
+            this.quietWarningPrinted = true;
+            this.note(`rafi: ${this.provider ?? "provider"} has been quiet for ${formatDuration(quietFor)}; RAFI is still responsive and will keep waiting`);
+            return;
+        }
+        const provider = [this.provider, this.model].filter(Boolean).join("/");
+        const quiet = quietFor >= this.quietWarningMs ? `provider quiet ${formatDuration(quietFor)}; RAFI is responsive` : this.detail;
+        const body = [phase.label, provider || undefined, quiet].filter(Boolean).join(" — ");
+        if (this.output.isTTY) {
+            const line = `${FRAMES[this.frame++ % FRAMES.length]} RAFI working: ${body} (${formatDuration(now - this.commandStartedAt)})`;
+            this.output.write(`\r\x1b[2K${line}`);
+            this.lineVisible = true;
+            return;
+        }
+        if (force || now - this.lastHeartbeatAt >= this.heartbeatMs) {
+            this.lastHeartbeatAt = now;
+            this.output.write(`[${new Date(now).toISOString()}] rafi working: ${body} (${formatDuration(now - this.commandStartedAt)})\n`);
+        }
+    }
+    clearLine() {
+        if (!this.lineVisible || !this.output.isTTY)
+            return;
+        this.output.write("\r\x1b[2K");
+        this.lineVisible = false;
+    }
+}
+const activityContext = new AsyncLocalStorage();
+export function currentActivity() { return activityContext.getStore(); }
+export async function withActivityContext(command, operation, options = {}) {
+    const existing = currentActivity();
+    if (existing)
+        return operation();
+    const reporter = new ActivityReporter(command, options);
+    return activityContext.run(reporter, async () => {
+        try {
+            return await operation();
+        }
+        finally {
+            reporter.dispose();
+        }
+    });
+}
+export async function withActivityPhase(label, operation) {
+    const end = currentActivity()?.begin(label);
+    try {
+        return await operation();
+    }
+    finally {
+        end?.();
+    }
+}
+export async function pauseActivityForInput(operation) {
+    const resume = currentActivity()?.pause();
+    try {
+        return await operation();
+    }
+    finally {
+        resume?.();
+    }
+}
+export function reportBuilderEvent(event) {
+    const reporter = currentActivity();
+    if (!reporter)
+        return;
+    if (event.kind === "activity")
+        reporter.update(event.state, event.detail, { provider: event.provider, model: event.model, immediate: !event.transient });
+    else if (event.kind === "retry") {
+        const attempt = event.attempt ? ` (${event.attempt}${event.maximum ? `/${event.maximum}` : ""})` : "";
+        const delay = event.delayMs ? ` in ${formatDuration(event.delayMs)}` : "";
+        reporter.note(`rafi: ${event.provider} ${clean(event.reason, 300)}; retrying${attempt}${delay}`);
+        reporter.update(`retrying ${event.provider}`, event.reason, { provider: event.provider });
+    }
+    else if (event.kind === "tool")
+        reporter.update(`running ${event.name}`, briefInput(event.input));
+    else if (event.kind === "text")
+        reporter.update("processing agent response");
+    else if (event.kind === "session-transition")
+        reporter.update(`session ${event.transition}`, event.detail);
+    else if (event.kind === "context-usage")
+        reporter.pulse(event.percentage === undefined ? undefined : `context ${event.percentage.toFixed(0)}%`);
+    else if (event.kind === "turn-complete")
+        reporter.update(event.result.isError ? "agent turn failed" : "agent turn complete");
+    else if (event.kind === "error")
+        reporter.update("provider error", event.message);
+}
+/** Async event queue that also feeds the active CLI reporter without consuming the stream. */
+export class BuilderEventQueue extends AsyncQueue {
+    push(event) {
+        reportBuilderEvent(event);
+        super.push(event);
+    }
+}
+function briefInput(input) {
+    if (!input || typeof input !== "object")
+        return undefined;
+    const value = input;
+    const detail = value.command ?? value.file_path ?? value.path ?? value.pattern ?? value.query;
+    return detail === undefined ? undefined : clean(String(detail), 100);
+}
+function clean(value, maximum) {
+    return value.replace(/[\r\n\t]+/g, " ").replace(/\s+/g, " ").trim().slice(0, maximum);
+}
+function formatDuration(milliseconds) {
+    const seconds = Math.max(0, Math.floor(milliseconds / 1_000));
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    return `${minutes}m${String(seconds % 60).padStart(2, "0")}s`;
+}

package/dist/adapters/claude.d.ts

@@ -9,6 +9,12 @@ import type { BuilderAdapter, BuilderAdapterOptions, BuilderEvent, CompactResult
  */
 export declare function buildClaudeQueryOptions(opts: Omit<BuilderAdapterOptions, "permission">): Record<string, unknown>;
 export declare function permissionDecisionToClaudeResult(decision: PermissionDecision, toolUseID?: string): PermissionResult;
+export declare function claudeApiRetryEvent(message: {
+    error: string;
+    attempt: number;
+    max_retries: number;
+    retry_delay_ms: number;
+}): BuilderEvent;
 /**
  * Drives Claude Code through the Claude Agent SDK in streaming-input mode:
  * one persistent session, follow-up turns pushed as user messages, permission
@@ -36,6 +42,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private pump;
     private handle;
     sendTurn(text: string): Promise<TurnResult>;
+    private sendTurnInternal;
     private captureStderr;
     sessionId(): string | undefined;
     compact(): Promise<CompactResult>;

package/dist/adapters/claude.js

@@ -10,6 +10,7 @@ export async function requireClaudeSDK() {
     }
 }
 import { AsyncQueue } from "../util/asyncQueue.js";
+import { BuilderEventQueue, withActivityPhase } from "../activity.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 import { classifyClaudeSdkFailure, resolveExecutablePath, sanitizeDiagnostics, } from "../runtimeReadiness.js";
 /**
@@ -53,6 +54,17 @@ export function permissionDecisionToClaudeResult(decision, toolUseID) {
         toolUseID,
     };
 }
+export function claudeApiRetryEvent(message) {
+    return {
+        kind: "retry",
+        provider: "claude",
+        reason: message.error,
+        attempt: message.attempt,
+        maximum: message.max_retries,
+        delayMs: message.retry_delay_ms,
+        managedBy: "provider",
+    };
+}
 /**
  * Drives Claude Code through the Claude Agent SDK in streaming-input mode:
  * one persistent session, follow-up turns pushed as user messages, permission
@@ -62,7 +74,7 @@ export class ClaudeAdapter {
     opts;
     agent = "claude";
     inbox = new AsyncQueue();
-    eventQueue = new AsyncQueue();
+    eventQueue = new BuilderEventQueue();
     query;
     abort = new AbortController();
     pumpDone;
@@ -182,6 +194,19 @@ export class ClaudeAdapter {
             this.structuredError = msg.error;
             this.apiErrorStatus = msg.error_status;
             this.turnSignals.push(`API retry ${msg.attempt}/${msg.max_retries}: ${msg.error}${msg.error_status === null ? "" : ` (HTTP ${msg.error_status})`}`);
+            this.eventQueue.push(claudeApiRetryEvent(msg));
+        }
+        else if (msg.type === "tool_progress") {
+            this.eventQueue.push({ kind: "activity", provider: "claude", state: "running tool", detail: `${msg.tool_name} (${Math.floor(msg.elapsed_time_seconds)}s)`, transient: true });
+        }
+        else if (msg.type === "system") {
+            const system = msg;
+            if (system.subtype === "task_started" || system.subtype === "task_progress" || system.subtype === "task_updated") {
+                this.eventQueue.push({ kind: "activity", provider: "claude", state: "working on task", detail: typeof system.summary === "string" ? system.summary : undefined, transient: system.subtype === "task_progress" });
+            }
+            else if (system.subtype === "session_state_changed") {
+                this.eventQueue.push({ kind: "activity", provider: "claude", state: "provider working", detail: typeof system.state === "string" ? system.state : undefined });
+            }
         }
         else if (msg.type === "result") {
             if ("api_error_status" in msg)
@@ -221,12 +246,16 @@ export class ClaudeAdapter {
         }
     }
     sendTurn(text) {
+        return withActivityPhase(`Claude ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(text));
+    }
+    sendTurnInternal(text) {
         if (this.closed)
             return Promise.reject(new Error("builder is closed"));
         if (this.pending) {
             return Promise.reject(new Error("a turn is already in progress"));
         }
         return new Promise((resolve, reject) => {
+            this.eventQueue.push({ kind: "activity", state: "starting Claude turn", provider: "claude", model: this.opts.model });
             this.turnSignals = [];
             this.structuredError = undefined;
             this.apiErrorStatus = undefined;
@@ -293,6 +322,17 @@ export class ClaudeAdapter {
         await this.pumpDone.catch(() => { });
     }
 }
+function activityPhase(phase) {
+    if (phase === "planning")
+        return "planning";
+    if (phase === "ticket-population")
+        return "populating tickets";
+    if (phase === "qa")
+        return "reviewing with QA";
+    if (phase === "uninstaller")
+        return "planning uninstall";
+    return "building";
+}
 function formatClaudeFailure(failure) {
     const environmentNames = Object.keys(process.env)
         .filter((name) => /^(ANTHROPIC|CLAUDE|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|SSL_CERT_FILE|NODE_EXTRA_CA_CERTS)(_|$)/i.test(name))

package/dist/adapters/codex.d.ts

@@ -27,6 +27,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     /** Deprecated fixture helper. Runtime execution uses only app-server. */
     buildArgs(instruction: string): string[];
     sendTurn(instruction: string): Promise<TurnResult>;
+    private sendTurnInternal;
     compact(): Promise<CompactResult>;
     contextUsage(): Promise<ContextUsage | undefined>;
     switchSettings(settings: ProviderSettingSwitch): Promise<CompactResult>;

package/dist/adapters/codex.js

@@ -3,7 +3,7 @@ import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { createInterface } from "node:readline";
 import { loadSkill } from "special-agents";
-import { AsyncQueue } from "../util/asyncQueue.js";
+import { BuilderEventQueue, withActivityPhase } from "../activity.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 /** Compatibility parser for recorded pre-app-server JSONL fixtures. */
 export function parseCodexLine(raw) {
@@ -25,7 +25,7 @@ export function parseCodexLine(raw) {
 export class CodexAdapter {
     opts;
     agent = "codex";
-    eventQueue = new AsyncQueue();
+    eventQueue = new BuilderEventQueue();
     process;
     nextId = 1;
     pending = new Map();
@@ -60,8 +60,12 @@ export class CodexAdapter {
         return args;
     }
     async sendTurn(instruction) {
+        return withActivityPhase(`Codex ${activityPhase(this.opts.runtimePhase)}`, () => this.sendTurnInternal(instruction));
+    }
+    async sendTurnInternal(instruction) {
         if (this.closed)
             throw new Error("builder is closed");
+        this.eventQueue.push({ kind: "activity", state: "starting Codex turn", provider: "codex", model: this.opts.model });
         try {
             await this.ensureThread();
             this.activeText = [];
@@ -198,7 +202,13 @@ export class CodexAdapter {
         if (!message.method)
             return;
         const params = message.params ?? {};
-        if (message.method === "item/completed") {
+        if (message.method === "item/started") {
+            const item = params.item;
+            const activity = codexItemActivity(item);
+            if (activity)
+                this.eventQueue.push({ kind: "activity", provider: "codex", ...activity });
+        }
+        else if (message.method === "item/completed") {
             const item = params.item;
             if (item?.type === "agentMessage" && typeof item.text === "string") {
                 this.activeText.push(item.text);
@@ -206,6 +216,19 @@ export class CodexAdapter {
             }
             else if (item?.type === "commandExecution")
                 this.eventQueue.push({ kind: "tool", name: "command_execution", input: { command: item.command } });
+            else {
+                const activity = codexItemActivity(item, true);
+                if (activity)
+                    this.eventQueue.push({ kind: "activity", provider: "codex", ...activity });
+            }
+        }
+        else if (message.method === "turn/plan/updated") {
+            const plan = params.plan;
+            const active = plan?.find((step) => step.status === "inProgress") ?? plan?.at(-1);
+            this.eventQueue.push({ kind: "activity", provider: "codex", state: "following plan", detail: typeof active?.step === "string" ? active.step : undefined });
+        }
+        else if (message.method.includes("reasoning") || message.method === "thread/status/changed") {
+            this.eventQueue.push({ kind: "activity", provider: "codex", state: message.method.includes("reasoning") ? "reasoning" : "provider working", transient: message.method.includes("Delta") });
         }
         else if (message.method === "thread/tokenUsage/updated") {
             const tokenUsage = params.tokenUsage;
@@ -215,8 +238,14 @@ export class CodexAdapter {
             this.usage = { used, maximum, ...(maximum ? { percentage: used / maximum * 100 } : {}) };
             this.eventQueue.push({ kind: "context-usage", ...this.usage });
         }
-        else if (message.method === "error")
-            this.eventQueue.push({ kind: "error", message: String(params.message ?? "Codex app-server error") });
+        else if (message.method === "error") {
+            const error = params.error;
+            const reason = String(error?.message ?? params.message ?? "Codex app-server error");
+            if (params.willRetry === true)
+                this.eventQueue.push({ kind: "retry", provider: "codex", reason, managedBy: "provider" });
+            else
+                this.eventQueue.push({ kind: "error", message: reason });
+        }
         const waiters = this.notificationWaiters.get(message.method) ?? [];
         const remaining = [];
         for (const waiter of waiters)
@@ -248,6 +277,37 @@ export class CodexAdapter {
         return blocks.length ? ["# Preloaded Skills", "Use the following skills for this run.", ...blocks].join("\n\n") : undefined;
     }
 }
+function activityPhase(phase) {
+    if (phase === "planning")
+        return "planning";
+    if (phase === "ticket-population")
+        return "populating tickets";
+    if (phase === "qa")
+        return "reviewing with QA";
+    if (phase === "uninstaller")
+        return "planning uninstall";
+    return "building";
+}
+function codexItemActivity(item, completed = false) {
+    if (!item)
+        return undefined;
+    const state = completed ? "completed" : "running";
+    if (item.type === "commandExecution")
+        return { state: `${state} command`, detail: typeof item.command === "string" ? item.command : undefined };
+    if (item.type === "fileChange")
+        return { state: `${state} file changes` };
+    if (item.type === "mcpToolCall")
+        return { state: `${state} MCP tool`, detail: String(item.tool ?? item.name ?? "") || undefined };
+    if (item.type === "dynamicToolCall")
+        return { state: `${state} tool`, detail: String(item.tool ?? item.name ?? "") || undefined };
+    if (item.type === "webSearch")
+        return { state: `${state} web search`, detail: typeof item.query === "string" ? item.query : undefined };
+    if (item.type === "contextCompaction")
+        return { state: completed ? "context compacted" : "compacting context" };
+    if (item.type === "agentMessage")
+        return { state: completed ? "received response" : "writing response" };
+    return undefined;
+}
 function loadSkillMarkdown(cwd, skill) {
     const projectPath = join(cwd, ".agents", "skills", skill, "SKILL.md");
     if (existsSync(projectPath))

package/dist/adapters/recovering.js

@@ -1,5 +1,6 @@
 import { isCancel, log, select } from "@clack/prompts";
 import { AsyncQueue } from "../util/asyncQueue.js";
+import { pauseActivityForInput, reportBuilderEvent } from "../activity.js";
 /** Adds interactive recovery around structured runtime turn failures. */
 export class RecoveringAdapter {
     opts;
@@ -25,11 +26,16 @@ export class RecoveringAdapter {
             const otherRuntime = this.runtime === "claude" ? "codex" : "claude";
             const choice = this.opts.choose
                 ? await this.opts.choose(result, this.runtime, otherRuntime)
-                : await promptTurnRecovery(result, this.opts.label, this.runtime, otherRuntime, this.opts.allowSwitch);
+                : await pauseActivityForInput(() => promptTurnRecovery(result, this.opts.label, this.runtime, otherRuntime, this.opts.allowSwitch));
             if (choice === "cancel")
                 return result;
             if (choice === "switch" && !this.opts.allowSwitch)
                 return result;
+            const recoveryEvent = choice === "retry"
+                ? { kind: "retry", provider: this.runtime, reason: `${this.opts.label} failed`, managedBy: "rafi" }
+                : { kind: "activity", provider: otherRuntime, state: `switching to ${otherRuntime}`, detail: "starting a fresh provider session" };
+            this.eventQueue.push(recoveryEvent);
+            reportBuilderEvent(recoveryEvent);
             const nextRuntime = choice === "switch" ? otherRuntime : this.runtime;
             const resumeSessionId = choice === "retry" ? this.adapter.sessionId() : undefined;
             await this.replaceAdapter(nextRuntime, resumeSessionId);

package/dist/adapters/types.d.ts

@@ -59,6 +59,21 @@ export type BuilderEvent = {
     kind: "tool";
     name: string;
     input: unknown;
+} | {
+    kind: "activity";
+    state: string;
+    detail?: string;
+    provider?: "claude" | "codex";
+    model?: string;
+    transient?: boolean;
+} | {
+    kind: "retry";
+    provider: "claude" | "codex";
+    reason: string;
+    attempt?: number;
+    maximum?: number;
+    delayMs?: number;
+    managedBy: "provider" | "rafi";
 } | {
     kind: "turn-complete";
     result: TurnResult;

package/dist/agentRun.d.ts

@@ -2,6 +2,7 @@ import { type PermissionConfig } from "./config.js";
 import { Log } from "./log.js";
 import { type StepStatus } from "./foreman.js";
 import type { BuilderAdapter, BuilderAdapterOptions, EffortLevel, TurnResult } from "./adapters/types.js";
+import type { AnsweredProviderQuestion } from "./providerQuestions.js";
 import { type RoleBundle } from "./roles.js";
 import type { AgentRuntime } from "./runtimeAuth.js";
 import type { AgentRoleDefaultsV1 } from "rafi-spec";
@@ -22,6 +23,10 @@ export interface RoleBuilderOptions {
     extraSkills?: string[];
     sandboxMode?: BuilderAdapterOptions["sandboxMode"];
     resumeSessionId?: string;
+    /** Observe successfully answered provider-native questions. */
+    onAnsweredQuestion?: (event: AnsweredProviderQuestion) => void;
+    /** Observe any provider-native question attempt, including denied prompts. */
+    onProviderQuestion?: (request: import("./adapters/types.js").PermissionRequest) => void;
 }
 export interface RoleBuilder {
     builder: BuilderAdapter;

package/dist/agentRun.js

@@ -115,7 +115,11 @@ export async function createRoleBuilder(opts) {
             runtimePhase: phaseForRole(opts.role),
             model,
             resumeSessionId,
-            permission: createPermissionHandler(policy, log, { interactive }),
+            permission: createPermissionHandler(policy, log, {
+                interactive,
+                onAnsweredQuestion: opts.onAnsweredQuestion,
+                onProviderQuestion: opts.onProviderQuestion,
+            }),
             effort,
             fast: opts.fast ?? saved?.fast,
             sandboxMode: opts.sandboxMode,