ai-foreman 1.7.3 → 1.7.5

package/dist/adapters/types.d.ts

@@ -8,13 +8,30 @@ export interface PermissionRequest {
     input: Record<string, unknown>;
     /** Human-readable prompt from the agent, when available. */
     title?: string;
+    /** Signaled if the provider-side operation should be aborted. */
+    signal?: AbortSignal;
+    /** Provider-native identifier for this specific tool call, when available. */
+    toolUseID?: string;
+    /** Short provider-rendered name for the requested action, when available. */
+    displayName?: string;
+    /** Provider-rendered detail for the requested action, when available. */
+    description?: string;
+    /** Provider explanation for why permission was requested, when available. */
+    decisionReason?: string;
+    /** Provider path that triggered the permission request, when available. */
+    blockedPath?: string;
 }
 /** The foreman's verdict on a permission request. */
 export type PermissionDecision = {
     behavior: "allow";
+    /** Provider-native tool input to continue with after host interaction. */
+    updatedInput?: Record<string, unknown>;
+    /** Provider-native permission updates to apply after approval. */
+    updatedPermissions?: Array<Record<string, unknown>>;
 } | {
     behavior: "deny";
     message: string;
+    interrupt?: boolean;
 };
 /** Decides each permission request. Supplied by the foreman, called by the adapter. */
 export type PermissionHandler = (req: PermissionRequest) => Promise<PermissionDecision>;
@@ -42,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

@@ -107,6 +107,7 @@ export async function createRoleBuilder(opts) {
     let runtimeExecutable = ready.executable;
     const policy = new PermissionPolicy(opts.permissionConfig ?? config.permissions, opts.projectDir);
     const skills = mergeSkills(roleBundle.skills, opts.extraSkills);
+    const interactive = !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY);
     const makeAdapter = async (nextRuntime, resumeSessionId) => {
         const adapterOpts = {
             cwd: opts.projectDir,
@@ -114,7 +115,11 @@ export async function createRoleBuilder(opts) {
             runtimePhase: phaseForRole(opts.role),
             model,
             resumeSessionId,
-            permission: createPermissionHandler(policy, log),
+            permission: createPermissionHandler(policy, log, {
+                interactive,
+                onAnsweredQuestion: opts.onAnsweredQuestion,
+                onProviderQuestion: opts.onProviderQuestion,
+            }),
             effort,
             fast: opts.fast ?? saved?.fast,
             sandboxMode: opts.sandboxMode,
@@ -130,7 +135,7 @@ export async function createRoleBuilder(opts) {
         initial,
         runtime,
         label: opts.label,
-        enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        enabled: interactive,
         allowSwitch: opts.allowSwitch !== false && !opts.resumeSessionId,
         recreate: async (nextRuntime, resumeSessionId) => {
             const nextReady = await ensureRuntimeReadyForCommand(opts.projectDir, nextRuntime, {

package/dist/branch/github.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { branchNodeFooter } from "./presentation.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 15_000;
 const OUTPUT_LIMIT = 2_000;
 function runCommand(cwd, bin, args, timeoutMs = DEFAULT_COMMAND_TIMEOUT_MS) {
@@ -440,7 +441,7 @@ function buildPrBody(opts) {
         `- Dependencies: ${opts.node.dependencies.length ? opts.node.dependencies.join(", ") : "None"}`,
         `- Commit: ${opts.commit ?? "N/A"}`,
         "",
-        "Generated by Rafi ai-foreman branch-per-ticket mode.",
+        branchNodeFooter(opts.node),
         "",
     ].join("\n");
 }

package/dist/branch/gitlab.js

@@ -1,6 +1,7 @@
 import { spawnSync } from "node:child_process";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import { branchNodeFooter } from "./presentation.js";
 const DEFAULT_COMMAND_TIMEOUT_MS = 15_000;
 const OUTPUT_LIMIT = 2_000;
 export function preflightGlab(cwd) {
@@ -272,7 +273,7 @@ function buildMrBody(opts) {
         `- Dependencies: ${opts.node.dependencies.length ? opts.node.dependencies.join(", ") : "None"}`,
         `- Commit: ${opts.commit ?? "N/A"}`,
         "",
-        "Generated by Rafi ai-foreman branch-per-ticket mode.",
+        branchNodeFooter(opts.node),
         "",
     ].join("\n");
 }

package/dist/branch/presentation.d.ts

@@ -0,0 +1,17 @@
+import type { BranchPlan, BranchPlanNode } from "./types.js";
+export type BranchAllocationMode = "per-ticket" | "shared" | "mixed";
+export interface BranchPresentation {
+    allocationMode: BranchAllocationMode;
+    description: "one branch per ticket" | "one shared branch" | "mixed shared and per-ticket branches" | "stacked delivery branches";
+    banner: string;
+    prompt: string;
+}
+export interface BranchPresentationOptions {
+    stacked?: boolean;
+    resumed?: boolean;
+}
+export declare function branchPlanLogMetadata(plan: BranchPlan, presentation: BranchPresentation): Record<string, unknown>;
+/** Describe an isolated branch run from its final, transformed plan. */
+export declare function presentBranchPlan(plan: BranchPlan, options?: BranchPresentationOptions): BranchPresentation;
+export declare function branchNodeBehavior(node: BranchPlanNode): "shared delivery branch" | "per-ticket branch";
+export declare function branchNodeFooter(node: BranchPlanNode): string;

package/dist/branch/presentation.js

@@ -0,0 +1,38 @@
+export function branchPlanLogMetadata(plan, presentation) {
+    return {
+        baseRef: plan.baseRef,
+        tickets: plan.nodes.map((node) => node.ticket.id),
+        branches: plan.nodes.map((node) => ({ ticket: node.ticket.id, branch: node.branch, base: node.baseBranch })),
+        issues: plan.issues,
+        branchMode: presentation.allocationMode,
+        executionDescription: presentation.description,
+    };
+}
+/** Describe an isolated branch run from its final, transformed plan. */
+export function presentBranchPlan(plan, options = {}) {
+    const sharedNodes = plan.nodes.filter((node) => Boolean(node.deliveryUnitId)).length;
+    const allocationMode = sharedNodes === 0
+        ? "per-ticket"
+        : sharedNodes === plan.nodes.length
+            ? "shared"
+            : "mixed";
+    const description = options.stacked
+        ? "stacked delivery branches"
+        : allocationMode === "shared"
+            ? "one shared branch"
+            : allocationMode === "mixed"
+                ? "mixed shared and per-ticket branches"
+                : "one branch per ticket";
+    return {
+        allocationMode,
+        description,
+        banner: `foreman: ${options.resumed ? "resuming " : ""}${description} for ${plan.nodes.length} ticket(s)`,
+        prompt: `Proceed with ${description}?`,
+    };
+}
+export function branchNodeBehavior(node) {
+    return node.deliveryUnitId ? "shared delivery branch" : "per-ticket branch";
+}
+export function branchNodeFooter(node) {
+    return `Generated by Rafi ai-foreman for a ${branchNodeBehavior(node)}.`;
+}

package/dist/branch/resume.d.ts

@@ -16,6 +16,8 @@ export interface BranchResumeSession {
     reviewProvider?: string;
     prReady?: boolean;
     keepWorktrees?: boolean;
+    deliveryUnitId?: string;
+    deliveryUnitFinal?: boolean;
     ts?: string;
 }
 export declare function findResumableBranchSessions(foremanDir: string): BranchResumeSession[];

package/dist/branch/resume.js

@@ -43,6 +43,8 @@ export function findResumableBranchSessions(foremanDir) {
                     reviewProvider: stringField(record.reviewProvider),
                     prReady: booleanField(record.prReady),
                     keepWorktrees: booleanField(record.keepWorktrees),
+                    deliveryUnitId: stringField(record.deliveryUnitId),
+                    deliveryUnitFinal: booleanField(record.deliveryUnitFinal),
                     ts: stringField(record.ts),
                 });
             }

package/dist/branch/runner.js

@@ -1,5 +1,5 @@
 import { buildDurableQaFixHandoff, compactWithRetry, runIsolatedQa } from "../qaReview.js";
-import { changeManifest } from "../qaSnapshot.js";
+import { changeManifestAsync } from "../qaSnapshot.js";
 import { Foreman, MARKER_SPEC, parseStepStatus } from "../foreman.js";
 import { fireNotification } from "../notify.js";
 import { cmdBlock, cmdComplete, cmdUpdate } from "../tickets/commands.js";
@@ -9,6 +9,7 @@ import { checkGitLabMrMerged, createOrReuseMr, enableGitLabAutoMerge, pushBranch
 import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { WorkflowDb } from "../workflowDb.js";
+import { currentActivity, withActivityPhase } from "../activity.js";
 export function readDeliveryUnitSession(projectDir, unitId) {
     const path = deliverySessionPath(projectDir, unitId);
     if (!existsSync(path))
@@ -176,6 +177,8 @@ export async function runBranchPlan(opts) {
                     reviewProvider,
                     prReady: opts.prReady,
                     keepWorktrees: opts.keepWorktrees,
+                    deliveryUnitId: node.deliveryUnitId,
+                    deliveryUnitFinal: node.deliveryUnitFinal,
                 });
                 if (node.deliveryUnitId) {
                     const path = deliverySessionPath(opts.projectDir, node.deliveryUnitId);
@@ -228,7 +231,7 @@ export async function runBranchPlan(opts) {
                             await builder.close();
                             builder = await opts.createBuilder(worktreePath);
                         }
-                        const digest = changeManifest(worktreePath).diffDigest;
+                        const digest = (await withActivityPhase("recording QA fix changes", () => changeManifestAsync(worktreePath, (state, detail) => currentActivity()?.update(state, detail), "recording QA fix changes"))).diffDigest;
                         const fixed = await builder.sendTurn(buildDurableQaFixHandoff(node.ticket, issues, worktreePath, result.text, digest));
                         const fixedStatus = parseStepStatus(fixed.text);
                         builderStreamSession = opts.builderSessionStrategy === "compact" ? builder.sessionId() : undefined;
@@ -287,9 +290,12 @@ export async function runBranchPlan(opts) {
                 workflowCheckpoint(opts.projectDir, opts.runId, "push-before", node.ticket.id, { branch: node.branch, sha: commit });
                 const pushOperation = `${opts.runId}:push:${node.branch}`;
                 planJournal(opts.projectDir, opts.runId, pushOperation, "push", { branch: node.branch, sha: commit, remote: "origin" });
-                const push = reviewProvider === "gitlab"
-                    ? pushBranchForMr(worktreePath, node.branch)
-                    : pushBranchForPr(worktreePath, node.branch);
+                const push = await withActivityPhase(`pushing ${node.branch}`, async () => {
+                    currentActivity()?.update(`pushing ${node.branch}`, `publishing ${node.ticket.id}`);
+                    return reviewProvider === "gitlab"
+                        ? pushBranchForMr(worktreePath, node.branch)
+                        : pushBranchForPr(worktreePath, node.branch);
+                });
                 if (push.ok) {
                     confirmJournal(opts.projectDir, pushOperation, node.branch, { sha: commit });
                     opts.log.write("branch-push", { ticket: node.ticket.id, branch: node.branch, status: "pushed" });
@@ -326,24 +332,27 @@ export async function runBranchPlan(opts) {
                 workflowCheckpoint(opts.projectDir, opts.runId, "review-creation-before", node.ticket.id, { provider: reviewProvider, head: node.branch, base: node.baseBranch });
                 const reviewOperation = `${opts.runId}:${reviewProvider === "gitlab" ? "mr" : "pr"}:${node.branch}:${node.baseBranch}`;
                 planJournal(opts.projectDir, opts.runId, reviewOperation, reviewProvider === "gitlab" ? "mr-create" : "pr-create", { head: node.branch, base: node.baseBranch, sha: commit });
-                const pr = reviewProvider === "gitlab"
-                    ? createOrReuseMr(opts.projectDir, {
-                        node,
-                        ready: opts.prReady || completionMode === "auto-merge",
-                        runId: opts.runId,
-                        qaEvidence: qaSummary,
-                        commit,
-                        autoMerge: false,
-                        cleanup: opts.cleanupBranches ?? true,
-                        mergeMethod: opts.mergeMethod ?? "squash",
-                    })
-                    : createOrReusePr(opts.projectDir, {
-                        node,
-                        ready: opts.prReady || completionMode === "auto-merge",
-                        runId: opts.runId,
-                        qaEvidence: qaSummary,
-                        commit,
-                    });
+                const pr = await withActivityPhase(`creating ${reviewProvider === "gitlab" ? "merge request" : "pull request"}`, async () => {
+                    currentActivity()?.update(`creating ${reviewProvider === "gitlab" ? "merge request" : "pull request"}`, node.ticket.id);
+                    return reviewProvider === "gitlab"
+                        ? createOrReuseMr(opts.projectDir, {
+                            node,
+                            ready: opts.prReady || completionMode === "auto-merge",
+                            runId: opts.runId,
+                            qaEvidence: qaSummary,
+                            commit,
+                            autoMerge: false,
+                            cleanup: opts.cleanupBranches ?? true,
+                            mergeMethod: opts.mergeMethod ?? "squash",
+                        })
+                        : createOrReusePr(opts.projectDir, {
+                            node,
+                            ready: opts.prReady || completionMode === "auto-merge",
+                            runId: opts.runId,
+                            qaEvidence: qaSummary,
+                            commit,
+                        });
+                });
                 summary.pr = pr;
                 if (pr.status === "created" || pr.status === "existing") {
                     confirmJournal(opts.projectDir, reviewOperation, pr.url, { head: node.branch, base: node.baseBranch, url: pr.url });
@@ -362,7 +371,10 @@ export async function runBranchPlan(opts) {
                     continue;
                 }
                 if (completionMode === "auto-merge" && reviewProvider === "github") {
-                    const autoMerge = enableGitHubAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
+                    const autoMerge = await withActivityPhase("enabling GitHub auto-merge", async () => {
+                        currentActivity()?.update("enabling GitHub auto-merge", node.branch);
+                        return enableGitHubAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
+                    });
                     summary.pr = autoMerge.status === "failed" ? autoMerge : { ...pr, status: "auto_merge_enabled", url: autoMerge.url ?? pr.url };
                     if (autoMerge.status === "failed") {
                         opts.log.write("pr-auto-merge-failed", failureLogFields(node, autoMerge));
@@ -373,7 +385,10 @@ export async function runBranchPlan(opts) {
                     opts.log.write("pr-auto-merge-enabled", { ticket: node.ticket.id, branch: node.branch, url: summary.pr.url });
                 }
                 else if (completionMode === "auto-merge" && reviewProvider === "gitlab") {
-                    const autoMerge = enableGitLabAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
+                    const autoMerge = await withActivityPhase("enabling GitLab auto-merge", async () => {
+                        currentActivity()?.update("enabling GitLab auto-merge", node.branch);
+                        return enableGitLabAutoMerge(opts.projectDir, node.branch, opts.cleanupBranches ?? true, opts.mergeMethod ?? "squash");
+                    });
                     summary.pr = autoMerge.status === "failed" ? autoMerge : { ...pr, status: "auto_merge_enabled", url: autoMerge.url ?? pr.url };
                     if (autoMerge.status === "failed") {
                         opts.log.write("mr-auto-merge-failed", failureLogFields(node, autoMerge));
@@ -501,6 +516,9 @@ function workflowCheckpoint(projectDir, runId, checkpoint, ticket, payload) {
     }
 }
 async function waitForAutoMergeDependencies(opts, node, provider) {
+    return withActivityPhase("checking dependency merges", () => waitForAutoMergeDependenciesInternal(opts, node, provider));
+}
+async function waitForAutoMergeDependenciesInternal(opts, node, provider) {
     const dependencyNodes = node.dependencies
         .map((dep) => opts.plan.nodes.find((candidate) => candidate.ticket.id === dep))
         .filter((dep) => Boolean(dep));
@@ -532,6 +550,7 @@ async function waitForAutoMergeDependencies(opts, node, provider) {
         if (pending.length === 0)
             return { ok: true };
         const message = `auto-merge dependency ${pending.join(", ")} has not merged into the root base yet`;
+        currentActivity()?.update("waiting for dependency merge", pending.join(", "));
         if (!opts.autoMergeWait) {
             return {
                 ok: false,

package/dist/cli/events.js

@@ -1,11 +1,19 @@
+import { currentActivity } from "../activity.js";
 /** Print a compact live feed of builder activity. */
 export async function printEvents(events) {
     let atLineStart = true;
     for await (const ev of events) {
         if (ev.kind === "text") {
             if (ev.text) {
-                process.stdout.write(ev.text);
-                atLineStart = ev.text.endsWith("\n");
+                const reporter = currentActivity();
+                if (reporter) {
+                    reporter.writePersistent(ev.text);
+                    atLineStart = true;
+                }
+                else {
+                    process.stdout.write(ev.text);
+                    atLineStart = ev.text.endsWith("\n");
+                }
             }
         }
         else if (ev.kind === "tool") {
@@ -13,7 +21,7 @@ export async function printEvents(events) {
                 process.stdout.write("\n");
                 atLineStart = true;
             }
-            console.log(`  -> ${ev.name} ${briefInput(ev.input)}`);
+            writeLine(`  -> ${ev.name} ${briefInput(ev.input)}`);
         }
         else if (ev.kind === "turn-complete") {
             if (!atLineStart) {
@@ -22,19 +30,30 @@ export async function printEvents(events) {
             }
             const tag = ev.result.isError ? "turn errored" : "turn complete";
             const cost = ev.result.costUsd > 0 ? ` ($${ev.result.costUsd.toFixed(4)})` : "";
-            console.log(`  - ${tag}${cost}`);
+            writeLine(`  - ${tag}${cost}`);
         }
         else if (ev.kind === "error") {
             if (!atLineStart) {
                 process.stdout.write("\n");
                 atLineStart = true;
             }
-            console.log(`  ! error: ${ev.message}`);
+            writeLine(`  ! error: ${ev.message}`);
+        }
+        else if (ev.kind === "retry" && !currentActivity()) {
+            const attempt = ev.attempt ? ` (${ev.attempt}${ev.maximum ? `/${ev.maximum}` : ""})` : "";
+            writeLine(`  ! ${ev.provider}: ${ev.reason}; retrying${attempt}`);
         }
     }
     if (!atLineStart)
         process.stdout.write("\n");
 }
+function writeLine(line) {
+    const reporter = currentActivity();
+    if (reporter)
+        reporter.writePersistent(line);
+    else
+        console.log(line);
+}
 function briefInput(input) {
     if (input && typeof input === "object") {
         const o = input;

package/dist/cli/runtimeAuthPrompt.js

@@ -3,6 +3,7 @@ import { requireClaudeSDK } from "../adapters/claude.js";
 import { checkRuntimeReady, RuntimeAuthError, runtimeCommandLabel, } from "../runtimeAuth.js";
 import { resolveExecutablePath } from "../runtimeReadiness.js";
 import { otherRuntime, runtimeDisplayName } from "./runtimeSelection.js";
+import { currentActivity } from "../activity.js";
 export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrOptions) {
     const opts = typeof labelOrOptions === "string"
         ? { label: labelOrOptions }
@@ -37,9 +38,12 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
             const choice = opts.choose
                 ? await opts.choose(failure, { otherRuntime: fallbackRuntime, allowSwitch })
                 : await promptRuntimeRecovery(failure, opts.label, fallbackRuntime, allowSwitch);
-            if (choice === "retry")
+            if (choice === "retry") {
+                currentActivity()?.note(`rafi: retrying ${runtime} readiness check`);
                 continue;
+            }
             if (choice === "switch" && allowSwitch) {
+                currentActivity()?.note(`rafi: checking fallback runtime ${fallbackRuntime}`);
                 try {
                     const probe = await check(projectDir, fallbackRuntime);
                     if (fallbackRuntime === "claude") {

package/dist/cli/start.js

@@ -22,12 +22,14 @@ import { collectBaseWorktreeDirtyPaths, currentGitRef, ensureCleanBaseWorktree,
 import { formatGitHubFailure, preflightGh } from "../branch/github.js";
 import { preflightGlab } from "../branch/gitlab.js";
 import { readDeliveryUnitSession, runBranchPlan } from "../branch/runner.js";
+import { branchPlanLogMetadata, presentBranchPlan } from "../branch/presentation.js";
 import { checkpointBuildRun, completeBuildRun, createBuildRun, heartbeatBuildRun, persistBuildSession, readBuildRuns, releaseBuildLease, resumeBuildRun } from "../buildRuns.js";
 import { parse as parseYaml } from "yaml";
 import { findResumableBranchSessions, formatBranchContinueCommand, formatBranchSummaryFollowupCommands, } from "../branch/resume.js";
 import { detectGitProvider, loadTicketSetupConfig } from "../tickets/setupConfig.js";
 import { loadDeliveryConfig, selectDeliveryUnitForRun, selectStacksForRun, updateStackDeliveryState } from "../tickets/delivery.js";
 import { AgentStatusReporter } from "../statusReporter.js";
+import { currentActivity, withActivityPhase } from "../activity.js";
 import { WorkflowDb } from "../workflowDb.js";
 import { makeLogPath as makeRoleLogPath, readOnlyPermissionConfig, runRoleInstruction } from "../agentRun.js";
 function fail(message) {
@@ -185,7 +187,10 @@ function branchContinueTicketHelp(cwd, flag = "--continue") {
 }
 async function ensureGitHubReadyForCreatePr(cwd, log, yes) {
     while (true) {
-        const result = preflightGh(cwd);
+        const result = await withActivityPhase("checking GitHub readiness", async () => {
+            currentActivity()?.update("checking GitHub readiness", "remote, authentication, and repository access");
+            return preflightGh(cwd);
+        });
         if (result.ok)
             return;
         log.write("github-readiness-failed", {
@@ -211,6 +216,7 @@ async function ensureGitHubReadyForCreatePr(cwd, log, yes) {
             console.log("ai-foreman: cancelled");
             process.exit(0);
         }
+        currentActivity()?.note("rafi: retrying GitHub readiness check");
     }
 }
 async function ensureReviewProviderReady(cwd, provider, log, yes) {
@@ -219,7 +225,10 @@ async function ensureReviewProviderReady(cwd, provider, log, yes) {
         return;
     }
     while (true) {
-        const result = preflightGlab(cwd);
+        const result = await withActivityPhase("checking GitLab readiness", async () => {
+            currentActivity()?.update("checking GitLab readiness", "remote, authentication, and repository access");
+            return preflightGlab(cwd);
+        });
         if (result.ok)
             return;
         log.write("gitlab-readiness-failed", {
@@ -245,6 +254,7 @@ async function ensureReviewProviderReady(cwd, provider, log, yes) {
             console.log("ai-foreman: cancelled");
             process.exit(0);
         }
+        currentActivity()?.note("rafi: retrying GitLab readiness check");
     }
 }
 export function buildStartCommand() {
@@ -415,7 +425,7 @@ export function buildStartCommand() {
             fail("--max-branch-depth must be a positive integer");
         }
         if (!branchMode && continueTickets.length > 0) {
-            fail("--ticket is only supported with --branch-per-ticket --continue or --branch-per-ticket --resume");
+            fail("--ticket is only supported when continuing or resuming an isolated branch run");
         }
         if (branchMode) {
             if (opts.resume && continueTickets.length > 1) {
@@ -428,9 +438,9 @@ export function buildStartCommand() {
                 fail("--ticket in branch mode requires --continue or --resume <sessionId>");
             }
             if (opts.tickets)
-                fail("--tickets is not supported with --branch-per-ticket; initialize and use .tickets/tickets.yaml");
+                fail("--tickets is not supported with an isolated branch run; initialize and use .tickets/tickets.yaml");
             if (!isTicketsInitialized(cwd))
-                fail("--branch-per-ticket requires initialized .tickets/ (run ai-foreman tickets init)");
+                fail("isolated branch runs require initialized .tickets/ (run ai-foreman tickets init)");
             if (branchDefaults.createReview && !branchDefaults.reviewProvider) {
                 fail("PR/MR completion is enabled but no GitHub or GitLab origin remote was detected; pass --provider github|gitlab or --completion none");
             }
@@ -563,6 +573,7 @@ export function buildStartCommand() {
             db.close();
             const ticketById = new Map(tickets.map((ticket) => [ticket.id, ticket]));
             const resumeSessionByTicket = new Map();
+            let auditDependencyCount;
             let plan;
             if (continueTickets.length > 0) {
                 const sessions = findResumableBranchSessions(join(cwd, ".foreman"));
@@ -589,6 +600,8 @@ export function buildStartCommand() {
                         dependencies: [],
                         depth: 1,
                         worktreePath: session.worktreePath,
+                        deliveryUnitId: session.deliveryUnitId,
+                        deliveryUnitFinal: session.deliveryUnitFinal,
                     });
                 }
                 plan = {
@@ -596,13 +609,6 @@ export function buildStartCommand() {
                     nodes,
                     issues: [],
                 };
-                log.write("branch-plan", {
-                    baseRef: plan.baseRef,
-                    tickets: plan.nodes.map((node) => node.ticket.id),
-                    branches: plan.nodes.map((node) => ({ ticket: node.ticket.id, branch: node.branch, base: node.baseBranch })),
-                    issues: plan.issues,
-                    resume: true,
-                });
             }
             else {
                 plan = buildBranchPlan(tickets, states, {
@@ -631,13 +637,7 @@ export function buildStartCommand() {
                         rootBaseBranches: branchDefaults.rootBaseBranches,
                         ticketIds: selectedStackTickets ?? deliveryRun?.remaining.slice(0, steps) ?? recoveryRecord?.tickets,
                     });
-                    log.write("branch-plan", {
-                        baseRef: plan.baseRef,
-                        tickets: plan.nodes.map((node) => node.ticket.id),
-                        branches: plan.nodes.map((node) => ({ ticket: node.ticket.id, branch: node.branch, base: node.baseBranch })),
-                        issues: plan.issues,
-                        auditDependencyCount: auditDependencies.length,
-                    });
+                    auditDependencyCount = auditDependencies.length;
                 }
                 finally {
                     await auditBuilder?.close().catch(() => { });
@@ -660,7 +660,16 @@ export function buildStartCommand() {
                         resumeSessionByTicket.set(plan.nodes[0].ticket.id, { worktreePath: prior.worktreePath, sessionId: opts.resume });
                 }
             }
-            console.log(`foreman: ${continueTickets.length > 0 ? "resuming branch-per-ticket mode" : "branch-per-ticket mode"} for ${plan.nodes.length} ticket(s)`);
+            const branchPresentation = presentBranchPlan(plan, {
+                stacked: selectedStacks.length > 0,
+                resumed: continueTickets.length > 0 || Boolean(recoveryRecord),
+            });
+            log.write("branch-plan", {
+                ...branchPlanLogMetadata(plan, branchPresentation),
+                ...(auditDependencyCount === undefined ? {} : { auditDependencyCount }),
+                ...(continueTickets.length > 0 || recoveryRecord ? { resume: true } : {}),
+            });
+            console.log(branchPresentation.banner);
             console.log(`foreman: project ${cwd}`);
             console.log(`foreman: base ${plan.baseRef}`);
             console.log(`foreman: log ${logPath}\n`);
@@ -680,7 +689,7 @@ export function buildStartCommand() {
             console.log();
             if (!opts.yes && plan.issues.every((issue) => !issue.blocking)) {
                 const action = await select({
-                    message: "Proceed with branch-per-ticket run?",
+                    message: branchPresentation.prompt,
                     options: [
                         { value: "proceed", label: "Proceed" },
                         { value: "cancel", label: "Cancel" },
@@ -702,7 +711,7 @@ export function buildStartCommand() {
             };
             let masterRun = recoveryRecord ? resumeBuildRun(cwd, recoveryRecord.runId, { builder: capturedBranchBuilder, qa: capturedBranchQa, builderSessionId: opts.resume ? String(opts.resume) : null }) : createBuildRun({
                 tickets: plan.nodes.map((node) => node.ticket.id), deliveryUnit: selectedStacks.length ? selectedStacks.map((stack) => stack.id).join(",") : deliveryRun?.unit.id,
-                repositoryRoot: cwd, branchMode: "per-ticket", builder: capturedBranchBuilder, qa: capturedBranchQa,
+                repositoryRoot: cwd, branchMode: branchPresentation.allocationMode, builder: capturedBranchBuilder, qa: capturedBranchQa,
             });
             const branchHeartbeat = setInterval(() => { masterRun = heartbeatBuildRun(cwd, masterRun); }, 10_000);
             branchHeartbeat.unref();
@@ -827,7 +836,11 @@ export function buildStartCommand() {
             reasoning: capturedBuilder.reasoning, fast: capturedBuilder.fast, step: 1, total: steps,
             phase: "builder work session", sessionTransition: resumeSessionId ? "resumed exact session" : "initial session", adapter: () => foreman.builderAdapter(),
         }, (line, snapshot) => {
-            console.log(line);
+            const activity = currentActivity();
+            if (activity)
+                activity.writePersistent(line);
+            else
+                console.log(line);
             log.write("agent-status", { ...snapshot });
             const db = new WorkflowDb(cwd);
             try {

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";
@@ -36,7 +37,11 @@ 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;
 /** Builds the permission callback: classify, log, allow or escalate. */
-export declare function createPermissionHandler(policy: PermissionPolicy, log: Log): PermissionHandler;
+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;
     requested: number;