ai-foreman 1.5.0 → 1.6.1

package/README.md

@@ -47,6 +47,14 @@ Requires:
 
 - Node.js 20 or newer.
 
+### Claude runtime and enterprise authentication
+
+Foreman first resolves and probes the system `claude` command, then passes that exact absolute executable path to the Claude Agent SDK. It does not use the SDK's bundled Claude executable. SDK sessions inherit the current environment and load Claude's user, project, and local settings; organization-managed policy remains applied by Claude Code. This preserves enterprise SSO such as `/login-okta`, managed settings, and proxy/certificate configuration.
+
+The SDK package is an optional dependency of `ai-foreman`. Do not install `@anthropic-ai/claude-agent-sdk` into the application being built unless that application independently uses it.
+
+Run `ai-foreman doctor .` to see the selected executable, SDK-wrapper status, settings sources, and relevant environment-variable names. Add `--live-claude` for a bounded, no-tools request through the real adapter path. That opt-in check uses account quota.
+
 ## Use
 
 - Check the target project.

package/dist/adapters/claude.d.ts

@@ -13,6 +13,7 @@ export declare function buildClaudeQueryOptions(opts: Omit<BuilderAdapterOptions
  * requests routed to the foreman's handler via `canUseTool`.
  */
 export declare class ClaudeAdapter implements BuilderAdapter {
+    private readonly opts;
     readonly agent: "claude";
     private readonly inbox;
     private readonly eventQueue;
@@ -20,6 +21,10 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private readonly abort;
     private readonly pumpDone;
     private _sessionId?;
+    private readonly stderrChunks;
+    private turnSignals;
+    private structuredError?;
+    private apiErrorStatus?;
     private pending?;
     private closed;
     static create(opts: BuilderAdapterOptions): Promise<ClaudeAdapter>;
@@ -28,6 +33,7 @@ export declare class ClaudeAdapter implements BuilderAdapter {
     private pump;
     private handle;
     sendTurn(text: string): Promise<TurnResult>;
+    private captureStderr;
     sessionId(): string | undefined;
     events(): AsyncIterable<BuilderEvent>;
     close(): Promise<void>;

package/dist/adapters/claude.js

@@ -4,14 +4,14 @@ export async function requireClaudeSDK() {
         return await import("@anthropic-ai/claude-agent-sdk");
     }
     catch {
-        throw new Error("Claude Agent SDK not installed.\n" +
-            "To use Claude Code as your agent runtime, run:\n" +
-            "  npm install @anthropic-ai/claude-agent-sdk\n" +
-            "Or use Codex only: ai-foreman start --agent codex");
+        throw new Error("Rafi's Claude Agent SDK dependency is not installed.\n" +
+            "Reinstall Rafi/ai-foreman with optional dependencies enabled; do not install the SDK into the target application.\n" +
+            "Or use Codex for this run with --agent codex.");
     }
 }
 import { AsyncQueue } from "../util/asyncQueue.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
+import { classifyClaudeSdkFailure, resolveExecutablePath, sanitizeDiagnostics, } from "../runtimeReadiness.js";
 /**
  * Pure function: build the `options` object passed to `query()`.
  * Extracted so tests can assert on the shape without making a live SDK call.
@@ -20,18 +20,20 @@ import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 export function buildClaudeQueryOptions(opts) {
     const base = {
         cwd: opts.cwd,
+        pathToClaudeCodeExecutable: opts.runtimeExecutable,
+        env: { ...process.env },
         model: opts.model,
         resume: opts.resumeSessionId,
         permissionMode: "acceptEdits",
         effort: opts.effort,
         extraArgs: opts.fast ? { fast: null } : undefined,
+        settingSources: ["user", "project", "local"],
     };
     if (opts.systemPromptAppend) {
         base.systemPrompt = { type: "preset", preset: "claude_code", append: opts.systemPromptAppend };
     }
     if (opts.skills !== undefined) {
         base.skills = opts.skills;
-        base.settingSources = ["project"];
     }
     return base;
 }
@@ -41,6 +43,7 @@ export function buildClaudeQueryOptions(opts) {
  * requests routed to the foreman's handler via `canUseTool`.
  */
 export class ClaudeAdapter {
+    opts;
     agent = "claude";
     inbox = new AsyncQueue();
     eventQueue = new AsyncQueue();
@@ -48,12 +51,20 @@ export class ClaudeAdapter {
     abort = new AbortController();
     pumpDone;
     _sessionId;
+    stderrChunks = [];
+    turnSignals = [];
+    structuredError;
+    apiErrorStatus;
     pending;
     closed = false;
     static async create(opts) {
         try {
+            const runtimeExecutable = opts.runtimeExecutable ?? resolveExecutablePath("claude");
+            if (!runtimeExecutable) {
+                throw new Error("Claude Code executable not found on PATH. Install your organization-approved Claude Code CLI, then retry.");
+            }
             const { query } = await requireClaudeSDK();
-            return new ClaudeAdapter(opts, query);
+            return new ClaudeAdapter({ ...opts, runtimeExecutable }, query);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
@@ -62,11 +73,13 @@ export class ClaudeAdapter {
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     constructor(opts, query) {
+        this.opts = opts;
         this.query = query({
             prompt: this.inbox,
             options: {
                 ...buildClaudeQueryOptions(opts),
                 abortController: this.abort,
+                stderr: (data) => this.captureStderr(data),
                 canUseTool: async (toolName, input) => {
                     const decision = await opts.permission({ toolName, input });
                     return decision.behavior === "allow"
@@ -106,6 +119,10 @@ export class ClaudeAdapter {
             this._sessionId = msg.session_id;
         }
         if (msg.type === "assistant") {
+            if (msg.error) {
+                this.structuredError = msg.error;
+                this.turnSignals.push(`assistant error: ${msg.error}`);
+            }
             for (const block of msg.message.content) {
                 if (block.type === "text" && block.text) {
                     this.eventQueue.push({ kind: "text", text: block.text });
@@ -119,23 +136,52 @@ export class ClaudeAdapter {
                 }
             }
         }
+        else if (msg.type === "auth_status") {
+            if (msg.error)
+                this.turnSignals.push(`auth status: ${msg.error}`);
+            if (msg.output.length > 0)
+                this.turnSignals.push(...msg.output.map((line) => `auth: ${line}`));
+        }
+        else if (msg.type === "system" && msg.subtype === "api_retry") {
+            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})`}`);
+        }
         else if (msg.type === "result") {
+            if ("api_error_status" in msg)
+                this.apiErrorStatus = msg.api_error_status;
             const text = "result" in msg && typeof msg.result === "string"
                 ? msg.result
                 : "errors" in msg
                     ? msg.errors.join("; ")
                     : "";
+            const rawDiagnostics = sanitizeDiagnostics([
+                text,
+                ...this.turnSignals,
+                ...this.stderrChunks,
+            ].filter(Boolean).join("\n"));
+            const failure = msg.is_error ? {
+                runtime: "claude",
+                phase: this.opts.runtimePhase ?? "builder",
+                category: classifyClaudeSdkFailure(this.structuredError, this.apiErrorStatus, rawDiagnostics),
+                executable: this.opts.runtimeExecutable ?? "claude",
+                cwd: this.opts.cwd,
+                diagnostics: rawDiagnostics,
+            } : undefined;
             const result = {
-                text: msg.is_error
-                    ? normalizeRuntimeErrorText("claude", text, null, "builder turn")
-                    : text,
+                text: failure ? formatClaudeFailure(failure) : text,
                 isError: msg.is_error,
                 numTurns: msg.num_turns,
                 costUsd: msg.total_cost_usd,
+                failure,
             };
             this.eventQueue.push({ kind: "turn-complete", result });
             this.pending?.resolve(result);
             this.pending = undefined;
+            this.turnSignals = [];
+            this.structuredError = undefined;
+            this.apiErrorStatus = undefined;
+            this.stderrChunks.length = 0;
         }
     }
     sendTurn(text) {
@@ -145,6 +191,9 @@ export class ClaudeAdapter {
             return Promise.reject(new Error("a turn is already in progress"));
         }
         return new Promise((resolve, reject) => {
+            this.turnSignals = [];
+            this.structuredError = undefined;
+            this.apiErrorStatus = undefined;
             this.pending = { resolve, reject };
             this.inbox.push({
                 type: "user",
@@ -153,6 +202,11 @@ export class ClaudeAdapter {
             });
         });
     }
+    captureStderr(data) {
+        this.stderrChunks.push(data);
+        while (this.stderrChunks.join("").length > 8 * 1024)
+            this.stderrChunks.shift();
+    }
     sessionId() {
         return this._sessionId;
     }
@@ -174,3 +228,24 @@ export class ClaudeAdapter {
         await this.pumpDone.catch(() => { });
     }
 }
+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))
+        .sort();
+    const lines = [
+        `Claude failed during ${failure.phase} (${failure.category}).`,
+        `Executable: ${failure.executable}`,
+        `Working directory: ${failure.cwd}`,
+        "Settings: user, project, local, and managed policy",
+        `Relevant environment variables set: ${environmentNames.length > 0 ? environmentNames.join(", ") : "none"}`,
+    ];
+    if (failure.category === "authentication") {
+        lines.push("Authenticate using the Claude Code login method approved by your organization, then verify the exact executable with `claude -p \"Return exactly OK\"`.");
+    }
+    else if (failure.category === "network") {
+        lines.push("Check the organization proxy/CA configuration, including HTTPS_PROXY, NODE_EXTRA_CA_CERTS, and CLAUDE_CODE_CERT_STORE where applicable.");
+    }
+    if (failure.diagnostics)
+        lines.push("", "Runtime diagnostics:", failure.diagnostics);
+    return lines.join("\n");
+}

package/dist/adapters/recovering.d.ts

@@ -0,0 +1,30 @@
+import type { AgentRuntime } from "../runtimeAuth.js";
+import type { BuilderAdapter, BuilderEvent, TurnResult } from "./types.js";
+export type TurnRecoveryChoice = "retry" | "switch" | "cancel";
+export interface RecoveringAdapterOptions {
+    initial: BuilderAdapter;
+    runtime: AgentRuntime;
+    enabled: boolean;
+    allowSwitch: boolean;
+    label: string;
+    recreate: (runtime: AgentRuntime, resumeSessionId?: string) => Promise<BuilderAdapter>;
+    choose?: (result: TurnResult, runtime: AgentRuntime, otherRuntime: AgentRuntime) => Promise<TurnRecoveryChoice>;
+    onRuntimeChange?: (runtime: AgentRuntime) => void;
+}
+/** Adds interactive recovery around structured runtime turn failures. */
+export declare class RecoveringAdapter implements BuilderAdapter {
+    private readonly opts;
+    private adapter;
+    private runtime;
+    private readonly eventQueue;
+    private eventPump;
+    private closed;
+    constructor(opts: RecoveringAdapterOptions);
+    get agent(): "claude" | "codex";
+    sendTurn(text: string): Promise<TurnResult>;
+    sessionId(): string | undefined;
+    events(): AsyncIterable<BuilderEvent>;
+    close(): Promise<void>;
+    private replaceAdapter;
+    private forwardEvents;
+}

package/dist/adapters/recovering.js

@@ -0,0 +1,83 @@
+import { isCancel, log, select } from "@clack/prompts";
+import { AsyncQueue } from "../util/asyncQueue.js";
+/** Adds interactive recovery around structured runtime turn failures. */
+export class RecoveringAdapter {
+    opts;
+    adapter;
+    runtime;
+    eventQueue = new AsyncQueue();
+    eventPump;
+    closed = false;
+    constructor(opts) {
+        this.opts = opts;
+        this.adapter = opts.initial;
+        this.runtime = opts.runtime;
+        this.eventPump = this.forwardEvents(this.adapter);
+    }
+    get agent() {
+        return this.adapter.agent;
+    }
+    async sendTurn(text) {
+        while (true) {
+            const result = await this.adapter.sendTurn(text);
+            if (!this.opts.enabled || !result.isError || !result.failure)
+                return result;
+            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);
+            if (choice === "cancel")
+                return result;
+            if (choice === "switch" && !this.opts.allowSwitch)
+                return result;
+            const nextRuntime = choice === "switch" ? otherRuntime : this.runtime;
+            const resumeSessionId = choice === "retry" ? this.adapter.sessionId() : undefined;
+            await this.replaceAdapter(nextRuntime, resumeSessionId);
+            if (choice === "switch") {
+                log.info(`Using ${nextRuntime} for the rest of this run. This is a fresh provider session; conversational continuity was not transferred.`);
+            }
+        }
+    }
+    sessionId() {
+        return this.adapter.sessionId();
+    }
+    events() {
+        return this.eventQueue;
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        await this.adapter.close().catch(() => { });
+        await this.eventPump.catch(() => { });
+        this.eventQueue.close();
+    }
+    async replaceAdapter(runtime, resumeSessionId) {
+        await this.adapter.close().catch(() => { });
+        await this.eventPump.catch(() => { });
+        this.adapter = await this.opts.recreate(runtime, resumeSessionId);
+        this.runtime = runtime;
+        this.opts.onRuntimeChange?.(runtime);
+        this.eventPump = this.forwardEvents(this.adapter);
+    }
+    async forwardEvents(adapter) {
+        for await (const event of adapter.events())
+            this.eventQueue.push(event);
+    }
+}
+async function promptTurnRecovery(result, label, runtime, otherRuntime, allowSwitch) {
+    log.error(result.text);
+    const choice = await select({
+        message: `${runtime} failed during ${label}. What should Rafi do?`,
+        options: [
+            { value: "retry", label: "Fix the runtime manually, then retry this turn" },
+            ...(allowSwitch
+                ? [{ value: "switch", label: `Switch to ${otherRuntime} for this run (fresh session)` }]
+                : []),
+            { value: "cancel", label: "Cancel this command and keep project state" },
+        ],
+    });
+    if (isCancel(choice))
+        return "cancel";
+    return choice;
+}

package/dist/adapters/types.d.ts

@@ -1,6 +1,7 @@
 /**
  * Agent-agnostic interface over a coding agent ("builder").
  */
+import type { RuntimeProbeCategory, RuntimeProbePhase } from "rafi-spec";
 /** A permission request surfaced by a builder before it runs a tool. */
 export interface PermissionRequest {
     toolName: string;
@@ -24,6 +25,14 @@ export interface TurnResult {
     isError: boolean;
     numTurns: number;
     costUsd: number;
+    failure?: {
+        runtime: "claude" | "codex";
+        phase: RuntimeProbePhase;
+        category: RuntimeProbeCategory;
+        executable: string;
+        cwd: string;
+        diagnostics: string;
+    };
 }
 /** Observability events emitted while a builder works. */
 export type BuilderEvent = {
@@ -44,6 +53,10 @@ export type EffortLevel = "low" | "medium" | "high" | "xhigh";
 export interface BuilderAdapterOptions {
     /** Working directory the builder operates in. */
     cwd: string;
+    /** Absolute runtime executable path verified by the readiness probe. */
+    runtimeExecutable?: string;
+    /** User-facing execution phase for diagnostics. */
+    runtimePhase?: RuntimeProbePhase;
     /** Permission decision callback. */
     permission: PermissionHandler;
     /** Resume a prior session instead of starting fresh. */

package/dist/adapters/types.js

@@ -1,4 +1 @@
-/**
- * Agent-agnostic interface over a coding agent ("builder").
- */
 export {};

package/dist/agentRun.d.ts

@@ -16,7 +16,7 @@ export interface RoleBuilderOptions {
     yes?: boolean;
     allowSwitch?: boolean;
     label: string;
-    log: Log;
+    log?: Log;
     permissionConfig?: PermissionConfig;
     extraSkills?: string[];
     sandboxMode?: BuilderAdapterOptions["sandboxMode"];
@@ -29,11 +29,12 @@ export interface RoleBuilder {
     effort?: EffortLevel;
     roleBundle: RoleBundle;
     skills: string[];
+    log: Log;
 }
 export interface RoleInstructionRunOptions extends Omit<RoleBuilderOptions, "log"> {
     instruction: string;
     logPath?: string;
-    logEvent?: "rafi-plan" | "ticket-populate" | "preflight";
+    logEvent?: "rafi-plan" | "ticket-populate" | "preflight" | "uninstall-proposal";
 }
 export interface RoleInstructionRunResult {
     turn: {

package/dist/agentRun.js

@@ -1,15 +1,17 @@
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { loadConfig, DEFAULT_CONFIG } from "./config.js";
 import { Log } from "./log.js";
 import { PermissionPolicy } from "./permissions/policy.js";
 import { ClaudeAdapter } from "./adapters/claude.js";
 import { CodexAdapter } from "./adapters/codex.js";
+import { RecoveringAdapter } from "./adapters/recovering.js";
 import { Foreman, createPermissionHandler } from "./foreman.js";
 import { printEvents } from "./cli/events.js";
 import { loadRoleBundle } from "./roles.js";
 import { ensureRuntimeReadyForCommand } from "./cli/runtimeAuthPrompt.js";
 import { resolveAgentForProject } from "./cli/runtimeSelection.js";
+import { parse as parseYaml } from "yaml";
 export const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
 export function assertEffortLevel(effort) {
     if (effort && !VALID_EFFORT.includes(effort)) {
@@ -84,12 +86,16 @@ export async function createRoleBuilder(opts) {
     if (!existsSync(opts.projectDir)) {
         throw new Error(`project directory not found: ${opts.projectDir}`);
     }
-    assertEffortLevel(opts.effort);
-    let runtime = resolveAgentForProject(opts.projectDir, opts.agent);
+    const saved = readRoleDefaults(opts.projectDir, opts.role);
+    const configuredEffort = saved?.reasoning && saved.reasoning !== "default" ? saved.reasoning : undefined;
+    const effectiveEffort = opts.effort ?? (VALID_EFFORT.includes(configuredEffort) ? configuredEffort : undefined);
+    assertEffortLevel(effectiveEffort);
+    let runtime = resolveAgentForProject(opts.projectDir, opts.agent ?? saved?.make);
     const config = loadConfig(join(opts.projectDir, "foreman.yaml"));
+    const log = opts.log ?? new Log(makeLogPath(opts.projectDir, opts.label.replace(/\s+/g, "-")));
     const roleBundle = loadRoleBundle(opts.role, { projectDir: opts.projectDir });
-    const initialModel = opts.model ?? roleBundle.model ?? undefined;
-    const effort = opts.effort ?? roleBundle.effort ?? undefined;
+    const initialModel = opts.model ?? (saved?.model !== "default" ? saved?.model : undefined) ?? roleBundle.model ?? undefined;
+    const effort = effectiveEffort ?? roleBundle.effort ?? undefined;
     const ready = await ensureRuntimeReadyForCommand(opts.projectDir, runtime, {
         label: opts.label,
         yes: Boolean(opts.yes),
@@ -97,32 +103,82 @@ export async function createRoleBuilder(opts) {
         model: initialModel,
     });
     runtime = ready.runtime;
-    const model = ready.model;
+    let model = ready.model;
+    let runtimeExecutable = ready.executable;
     const policy = new PermissionPolicy(opts.permissionConfig ?? config.permissions, opts.projectDir);
     const skills = mergeSkills(roleBundle.skills, opts.extraSkills);
-    const adapterOpts = {
-        cwd: opts.projectDir,
-        model,
-        resumeSessionId: opts.resumeSessionId,
-        permission: createPermissionHandler(policy, opts.log),
-        effort,
-        fast: opts.fast,
-        sandboxMode: opts.sandboxMode,
-        systemPromptAppend: roleBundle.system || undefined,
-        skills: skills.length > 0 ? skills : undefined,
+    const makeAdapter = async (nextRuntime, resumeSessionId) => {
+        const adapterOpts = {
+            cwd: opts.projectDir,
+            runtimeExecutable,
+            runtimePhase: phaseForRole(opts.role),
+            model,
+            resumeSessionId,
+            permission: createPermissionHandler(policy, log),
+            effort,
+            fast: opts.fast ?? saved?.fast,
+            sandboxMode: opts.sandboxMode,
+            systemPromptAppend: roleBundle.system || undefined,
+            skills: skills.length > 0 ? skills : undefined,
+        };
+        return nextRuntime === "codex"
+            ? new CodexAdapter(adapterOpts)
+            : await ClaudeAdapter.create(adapterOpts);
     };
-    const builder = runtime === "codex"
-        ? new CodexAdapter(adapterOpts)
-        : await ClaudeAdapter.create(adapterOpts);
-    return { builder, runtime, model, effort, roleBundle, skills };
+    const initial = await makeAdapter(runtime, opts.resumeSessionId);
+    const builder = new RecoveringAdapter({
+        initial,
+        runtime,
+        label: opts.label,
+        enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+        allowSwitch: opts.allowSwitch !== false && !opts.resumeSessionId,
+        recreate: async (nextRuntime, resumeSessionId) => {
+            const nextReady = await ensureRuntimeReadyForCommand(opts.projectDir, nextRuntime, {
+                label: opts.label,
+                allowSwitch: false,
+                model: nextRuntime === runtime ? model : undefined,
+            });
+            runtime = nextReady.runtime;
+            model = nextReady.model;
+            runtimeExecutable = nextReady.executable;
+            return makeAdapter(runtime, resumeSessionId);
+        },
+    });
+    return { builder, runtime, model, effort, roleBundle, skills, log };
+}
+function phaseForRole(role) {
+    if (role === "planner")
+        return "planning";
+    if (role === "ticket-maker")
+        return "ticket-population";
+    if (role === "qa")
+        return "qa";
+    if (role === "uninstaller")
+        return "uninstaller";
+    return "builder";
+}
+function readRoleDefaults(projectDir, role) {
+    const path = join(projectDir, "rafi-config.yaml");
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const config = parseYaml(readFileSync(path, "utf8"));
+        return config?.agent_defaults?.version === 1
+            ? config.agent_defaults.roles[role]
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
 export async function runRoleInstruction(opts) {
     const logPath = opts.logPath ?? makeLogPath(opts.projectDir, opts.label.replace(/\s+/g, "-"));
     const log = new Log(logPath);
-    const { builder, runtime, model, effort, roleBundle, skills } = await createRoleBuilder({
+    const roleBuilder = await createRoleBuilder({
         ...opts,
         log,
     });
+    const { builder, effort, roleBundle, skills } = roleBuilder;
     const viewer = printEvents(builder.events());
     const config = loadConfig(join(opts.projectDir, "foreman.yaml"));
     const foreman = new Foreman(builder, log, config.notifications.enabled, false, 3, opts.projectDir);
@@ -133,8 +189,8 @@ export async function runRoleInstruction(opts) {
         if (opts.logEvent) {
             log.write(opts.logEvent, {
                 role: opts.role,
-                runtime,
-                model,
+                runtime: builder.agent,
+                model: builder.agent === roleBuilder.runtime ? roleBuilder.model : undefined,
                 effort,
                 sessionId: builder.sessionId(),
                 statusKind: turn.status.kind,
@@ -144,7 +200,16 @@ export async function runRoleInstruction(opts) {
                 isError: turn.result.isError,
             });
         }
-        return { turn, runtime, model, effort, sessionId: builder.sessionId(), logPath, roleBundle, skills };
+        return {
+            turn,
+            runtime: builder.agent,
+            model: builder.agent === roleBuilder.runtime ? roleBuilder.model : undefined,
+            effort,
+            sessionId: builder.sessionId(),
+            logPath,
+            roleBundle,
+            skills,
+        };
     }
     catch (err) {
         await builder.close().catch(() => { });

package/dist/branch/git.d.ts

@@ -14,6 +14,7 @@ export declare function generatedTrackerDirtyPaths(paths: {
 export declare function ensureCleanBaseWorktree(cwd: string, opts?: BaseWorktreeCleanOptions): void;
 export declare function ensureForemanExcluded(cwd: string): void;
 export declare function createTicketWorktree(projectDir: string, runId: string, branch: string, base: string): string;
+export declare function findWorktreeForBranch(projectDir: string, branch: string): string | undefined;
 export declare function removeTicketWorktree(projectDir: string, worktreePath: string): void;
 export declare function currentWorktreeBranch(worktreePath: string): string;
 export declare function hasTrackerChanges(worktreePath: string, paths?: {
@@ -24,5 +25,7 @@ export declare function hasWorktreeChanges(worktreePath: string): boolean;
 export declare function commitAll(worktreePath: string, message: string): string | undefined;
 export declare function headCommitIfAhead(worktreePath: string, base: string): string | undefined;
 export declare function pushBranch(worktreePath: string, branch: string): void;
+export declare function mergeBranchToLocalBase(projectDir: string, branch: string, baseBranch: string, message: string, method?: "squash" | "merge" | "rebase"): string;
+/** Compatibility export for callers compiled against the older helper. */
 export declare function squashMergeBranchToLocalBase(projectDir: string, branch: string, baseBranch: string, message: string): string;
 export declare function deleteLocalBranch(projectDir: string, branch: string): void;

package/dist/branch/git.js

@@ -51,6 +51,19 @@ export function createTicketWorktree(projectDir, runId, branch, base) {
     runGit(projectDir, ["worktree", "add", "-b", branch, worktreePath, base]);
     return worktreePath;
 }
+export function findWorktreeForBranch(projectDir, branch) {
+    const output = runGit(projectDir, ["worktree", "list", "--porcelain"]).stdout;
+    let worktree;
+    for (const line of output.split(/\r?\n/)) {
+        if (line.startsWith("worktree "))
+            worktree = line.slice("worktree ".length);
+        if (line === `branch refs/heads/${branch}` && worktree)
+            return worktree;
+        if (!line.trim())
+            worktree = undefined;
+    }
+    return undefined;
+}
 export function removeTicketWorktree(projectDir, worktreePath) {
     try {
         runGit(projectDir, ["worktree", "remove", "--force", worktreePath]);
@@ -101,15 +114,28 @@ export function headCommitIfAhead(worktreePath, base) {
 export function pushBranch(worktreePath, branch) {
     runGit(worktreePath, ["push", "-u", "origin", branch]);
 }
-export function squashMergeBranchToLocalBase(projectDir, branch, baseBranch, message) {
-    const current = currentGitRef(projectDir);
-    if (current !== baseBranch) {
+export function mergeBranchToLocalBase(projectDir, branch, baseBranch, message, method = "squash") {
+    if (method === "rebase")
+        runGit(projectDir, ["rebase", baseBranch, branch]);
+    if (currentGitRef(projectDir) !== baseBranch) {
         runGit(projectDir, ["checkout", baseBranch]);
     }
-    runGit(projectDir, ["merge", "--squash", branch]);
-    runGit(projectDir, ["commit", "-m", message]);
+    if (method === "squash") {
+        runGit(projectDir, ["merge", "--squash", branch]);
+        runGit(projectDir, ["commit", "-m", message]);
+    }
+    else if (method === "merge") {
+        runGit(projectDir, ["merge", "--no-ff", branch, "-m", message]);
+    }
+    else {
+        runGit(projectDir, ["merge", "--ff-only", branch]);
+    }
     return runGit(projectDir, ["rev-parse", "--short", "HEAD"]).stdout;
 }
+/** Compatibility export for callers compiled against the older helper. */
+export function squashMergeBranchToLocalBase(projectDir, branch, baseBranch, message) {
+    return mergeBranchToLocalBase(projectDir, branch, baseBranch, message, "squash");
+}
 export function deleteLocalBranch(projectDir, branch) {
     try {
         runGit(projectDir, ["branch", "-D", branch]);