ai-foreman 1.6.0 → 1.6.2

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.js

@@ -5,6 +5,7 @@ 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";
@@ -102,25 +103,60 @@ 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, log),
-        effort,
-        fast: opts.fast ?? saved?.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);
+    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))
@@ -138,10 +174,11 @@ function readRoleDefaults(projectDir, role) {
 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);
@@ -152,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,
@@ -163,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/cli/doctor.js

@@ -6,6 +6,8 @@ import { loadConfig } from "../config.js";
 import { isTicketsInitialized } from "../tickets/config.js";
 import { cmdValidate } from "../tickets/commands.js";
 import { checkGitHubReadiness, inspectGitHubRemote } from "../branch/github.js";
+import { requireClaudeSDK } from "../adapters/claude.js";
+import { resolveExecutablePath, sanitizeDiagnostics } from "../runtimeReadiness.js";
 const PACKAGE_VERSION = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8"))?.version;
 function commandVersion(command) {
     const result = spawnSync(command, ["--version"], {
@@ -23,7 +25,8 @@ export function buildDoctorCommand() {
         .description("Check Foreman, agent CLIs, config, and optional ticket tracker readiness.")
         .argument("[project]", "path to the project directory", ".")
         .option("--github", "run GitHub PR readiness checks")
-        .action((project, opts) => {
+        .option("--live-claude", "run a bounded no-tools Claude adapter request (uses account quota)")
+        .action(async (project, opts) => {
         const cwd = resolve(project);
         let errors = 0;
         const report = (ok, label, detail) => {
@@ -46,11 +49,37 @@ export function buildDoctorCommand() {
         catch (err) {
             report(false, "foreman.yaml", err instanceof Error ? err.message : String(err));
         }
-        const claude = commandVersion("claude");
+        const claudeExecutable = resolveExecutablePath("claude");
+        const claude = claudeExecutable ? commandVersion(claudeExecutable) : { ok: false };
         if (claude.ok)
-            warn("claude CLI found", claude.detail);
+            warn("claude CLI found", `${claudeExecutable} (${claude.detail})`);
         else
-            warn("claude CLI not found", "Claude adapter may still work through the SDK if credentials are configured");
+            warn("claude CLI not found", "required for Claude runs; Rafi never falls back to the SDK-bundled binary");
+        try {
+            await requireClaudeSDK();
+            warn("Rafi Claude SDK wrapper", "available; execution uses the system Claude CLI above");
+        }
+        catch (err) {
+            report(false, "Rafi Claude SDK wrapper", err instanceof Error ? err.message.split("\n")[0] : String(err));
+        }
+        warn("Claude setting sources", "user, project, local, and managed policy");
+        const relevantEnvironment = 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();
+        warn("Claude environment names", relevantEnvironment.length > 0 ? relevantEnvironment.join(", ") : "none set");
+        const projectSdkRemoval = projectClaudeSdkRemoval(cwd);
+        if (projectSdkRemoval) {
+            warn("project-local Claude Agent SDK", `Rafi does not use this dependency; keep it if the application does, otherwise: ${projectSdkRemoval}`);
+        }
+        if (opts.liveClaude) {
+            if (!claudeExecutable) {
+                report(false, "live Claude adapter", "system Claude executable is missing");
+            }
+            else {
+                const live = await liveClaudeSmoke(cwd, claudeExecutable);
+                report(live.ok, "live Claude adapter", live.detail);
+            }
+        }
         const codex = commandVersion("codex");
         if (codex.ok)
             warn("codex CLI found", codex.detail);
@@ -91,6 +120,64 @@ export function buildDoctorCommand() {
         process.exit(errors === 0 ? 0 : 1);
     });
 }
+async function liveClaudeSmoke(cwd, executable) {
+    const abortController = new AbortController();
+    const timer = setTimeout(() => abortController.abort(), 45_000);
+    timer.unref();
+    try {
+        const { query } = await requireClaudeSDK();
+        const queryInstance = query({
+            prompt: "Return exactly OK",
+            options: {
+                cwd,
+                pathToClaudeCodeExecutable: executable,
+                settingSources: ["user", "project", "local"],
+                tools: [],
+                permissionMode: "dontAsk",
+                persistSession: false,
+                abortController,
+            },
+        });
+        for await (const message of queryInstance) {
+            if (message.type !== "result")
+                continue;
+            const output = "result" in message ? message.result : message.errors.join("; ");
+            return message.is_error
+                ? { ok: false, detail: sanitizeDiagnostics(output || "Claude returned an error") }
+                : { ok: output.trim().toUpperCase() === "OK", detail: sanitizeDiagnostics(output) };
+        }
+        return { ok: false, detail: "Claude adapter ended without a result" };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        return { ok: false, detail: abortController.signal.aborted ? "timed out after 45 seconds" : sanitizeDiagnostics(message) };
+    }
+    finally {
+        clearTimeout(timer);
+        abortController.abort();
+    }
+}
+function projectClaudeSdkRemoval(cwd) {
+    const packagePath = join(cwd, "package.json");
+    if (!existsSync(packagePath))
+        return undefined;
+    try {
+        const pkg = JSON.parse(readFileSync(packagePath, "utf8"));
+        const name = "@anthropic-ai/claude-agent-sdk";
+        if (!pkg.dependencies?.[name] && !pkg.devDependencies?.[name] && !pkg.optionalDependencies?.[name])
+            return undefined;
+        if (existsSync(join(cwd, "pnpm-lock.yaml")))
+            return `pnpm remove ${name}`;
+        if (existsSync(join(cwd, "yarn.lock")))
+            return `yarn remove ${name}`;
+        if (existsSync(join(cwd, "bun.lock")) || existsSync(join(cwd, "bun.lockb")))
+            return `bun remove ${name}`;
+        return `npm uninstall ${name}`;
+    }
+    catch {
+        return undefined;
+    }
+}
 function truncateOneLine(value) {
     const compact = value.replace(/\s+/g, " ").trim();
     return compact.length <= 180 ? compact : `${compact.slice(0, 180).trimEnd()}...`;

package/dist/cli/runtimeAuthPrompt.d.ts

@@ -1,4 +1,5 @@
 import { RuntimeAuthError, type AgentRuntime } from "../runtimeAuth.js";
+import type { RuntimeProbeResult } from "rafi-spec";
 export type RuntimeCommandRecoveryChoice = "retry" | "switch" | "cancel";
 export interface RuntimeCommandRecoveryContext {
     otherRuntime: AgentRuntime;
@@ -9,7 +10,7 @@ export interface RuntimeReadyForCommandOptions {
     yes?: boolean;
     allowSwitch?: boolean;
     model?: string | undefined;
-    check?: (projectDir: string, runtime: AgentRuntime) => void | Promise<void>;
+    check?: (projectDir: string, runtime: AgentRuntime) => void | RuntimeProbeResult | Promise<void | RuntimeProbeResult>;
     checkClaudeSdk?: () => Promise<void>;
     choose?: (err: RuntimeAuthError, context: RuntimeCommandRecoveryContext) => Promise<RuntimeCommandRecoveryChoice>;
 }
@@ -17,5 +18,6 @@ export interface RuntimeReadyForCommandResult {
     runtime: AgentRuntime;
     model?: string;
     fellBack: boolean;
+    executable: string;
 }
 export declare function ensureRuntimeReadyForCommand(projectDir: string, runtime: AgentRuntime, labelOrOptions: string | RuntimeReadyForCommandOptions): Promise<RuntimeReadyForCommandResult>;

package/dist/cli/runtimeAuthPrompt.js

@@ -1,6 +1,7 @@
 import { select, isCancel, log } from "@clack/prompts";
 import { requireClaudeSDK } from "../adapters/claude.js";
 import { checkRuntimeReady, RuntimeAuthError, runtimeCommandLabel, } from "../runtimeAuth.js";
+import { resolveExecutablePath } from "../runtimeReadiness.js";
 import { otherRuntime, runtimeDisplayName } from "./runtimeSelection.js";
 export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrOptions) {
     const opts = typeof labelOrOptions === "string"
@@ -12,13 +13,23 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
     const nonInteractive = !opts.choose && (Boolean(opts.yes) || !process.stdin.isTTY || !process.stdout.isTTY);
     while (true) {
         try {
-            await check(projectDir, runtime);
-            return { runtime, model: opts.model, fellBack: false };
+            const probe = await check(projectDir, runtime);
+            if (runtime === "claude")
+                await checkClaudeSdk();
+            const executable = probe?.executable ?? resolveExecutablePath(runtime === "claude" ? "claude" : "codex");
+            if (!executable)
+                throw new Error(`${runtime} executable disappeared after readiness`);
+            return { runtime, model: opts.model, fellBack: false, executable };
         }
         catch (err) {
             const failure = err instanceof RuntimeAuthError
                 ? err
-                : new RuntimeAuthError({ runtime, context: opts.label, cause: err });
+                : new RuntimeAuthError({
+                    runtime,
+                    context: opts.label,
+                    stderr: err instanceof Error ? err.message : String(err),
+                    cause: err,
+                });
             if (nonInteractive) {
                 throw failure;
             }
@@ -30,7 +41,7 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
                 continue;
             if (choice === "switch" && allowSwitch) {
                 try {
-                    await check(projectDir, fallbackRuntime);
+                    const probe = await check(projectDir, fallbackRuntime);
                     if (fallbackRuntime === "claude") {
                         await checkClaudeSdk();
                     }
@@ -38,12 +49,20 @@ export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrO
                         console.log(`foreman: ignored --model ${opts.model} after switching to ${fallbackRuntime}; model names are provider-specific.`);
                     }
                     console.log(`foreman: using ${runtimeDisplayName(fallbackRuntime)} for this run.`);
-                    return { runtime: fallbackRuntime, model: undefined, fellBack: true };
+                    const executable = probe?.executable ?? resolveExecutablePath(fallbackRuntime === "claude" ? "claude" : "codex");
+                    if (!executable)
+                        throw new Error(`${fallbackRuntime} executable disappeared after readiness`);
+                    return { runtime: fallbackRuntime, model: undefined, fellBack: true, executable };
                 }
                 catch (switchErr) {
                     const switchFailure = switchErr instanceof RuntimeAuthError
                         ? switchErr
-                        : new RuntimeAuthError({ runtime: fallbackRuntime, context: opts.label, cause: switchErr });
+                        : new RuntimeAuthError({
+                            runtime: fallbackRuntime,
+                            context: opts.label,
+                            stderr: switchErr instanceof Error ? switchErr.message : String(switchErr),
+                            cause: switchErr,
+                        });
                     log.error(`Fallback runtime is not ready:\n${switchFailure.message}`);
                     continue;
                 }

package/dist/cli/start.d.ts

@@ -1,2 +1,4 @@
 import { Command } from "commander";
+export declare function formatStartResumeCommand(executable: "ai-foreman", projectDir: string, steps: number, sessionId: string): string;
+export declare function formatResumeGuidance(executable: "rafi" | "ai-foreman", projectDir: string, steps: number, sessionId?: string): string[];
 export declare function buildStartCommand(): Command;

package/dist/cli/start.js

@@ -7,6 +7,7 @@ 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 "./events.js";
 import { loadRoleBundle } from "../roles.js";
@@ -52,6 +53,31 @@ function collectTicket(value, previous) {
 function unique(values) {
     return [...new Set(values)];
 }
+export function formatStartResumeCommand(executable, projectDir, steps, sessionId) {
+    return [
+        executable,
+        "start",
+        shellQuote(projectDir),
+        "--steps",
+        String(steps),
+        "--resume",
+        shellQuote(sessionId),
+    ].join(" ");
+}
+export function formatResumeGuidance(executable, projectDir, steps, sessionId) {
+    if (executable === "rafi") {
+        return [
+            "foreman: resume this run with:",
+            `  rafi build:resume ${shellQuote(projectDir)}`,
+        ];
+    }
+    if (!sessionId)
+        return [];
+    return [
+        "foreman: resume this builder with:",
+        `  ${formatStartResumeCommand("ai-foreman", projectDir, steps, sessionId)}`,
+    ];
+}
 function optionWasProvided(command, name) {
     const source = command.getOptionValueSource(name);
     return source !== undefined && source !== "default";
@@ -291,10 +317,12 @@ export function buildStartCommand() {
             fail(err instanceof Error ? err.message : String(err));
         }
         let model = opts.model ?? explicitDefaultValue(roleDefaults.builder?.model);
+        let agentExecutable;
         const builderEffort = opts.effort ?? explicitEffort(roleDefaults.builder?.reasoning);
         const builderFast = opts.fast ?? roleDefaults.builder?.fast;
         let qaAgent = resolveAgentForProject(cwd, roleDefaults.qa?.make);
         let qaModel = explicitDefaultValue(roleDefaults.qa?.model);
+        let qaExecutable;
         const qaEffort = explicitEffort(roleDefaults.qa?.reasoning);
         const qaFast = roleDefaults.qa?.fast ?? false;
         const configuredTrackerPath = isTicketsInitialized(cwd)
@@ -364,11 +392,13 @@ export function buildStartCommand() {
         const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
         const log = new Log(logPath);
         const qaEnabled = opts.qa !== false && config.qa.enabled !== false;
-        const createBuilder = async (builderCwd, sessionId) => {
+        const createRawBuilder = async (builderCwd, sessionId) => {
             const builderPolicy = new PermissionPolicy(config.permissions, builderCwd);
             const roleBundle = loadRoleBundle("builder", { projectDir: builderCwd });
             const adapterOpts = {
                 cwd: builderCwd,
+                runtimeExecutable: agentExecutable,
+                runtimePhase: "builder",
                 model,
                 resumeSessionId: sessionId,
                 permission: createPermissionHandler(builderPolicy, log),
@@ -381,11 +411,34 @@ export function buildStartCommand() {
                 ? new CodexAdapter(adapterOpts)
                 : await ClaudeAdapter.create(adapterOpts);
         };
-        const createQa = async (qaCwd, sessionId) => {
+        const createBuilder = async (builderCwd, sessionId) => {
+            const initial = await createRawBuilder(builderCwd, sessionId);
+            return new RecoveringAdapter({
+                initial,
+                runtime: agent,
+                label: "builder turn",
+                enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                allowSwitch: !(opts.resume || opts.continue),
+                recreate: async (nextRuntime, resumeSessionId) => {
+                    const nextReady = await ensureRuntimeReadyForCommand(builderCwd, nextRuntime, {
+                        label: "builder recovery",
+                        allowSwitch: false,
+                        model: nextRuntime === agent ? model : undefined,
+                    });
+                    agent = nextReady.runtime;
+                    model = nextReady.model;
+                    agentExecutable = nextReady.executable;
+                    return createRawBuilder(builderCwd, resumeSessionId);
+                },
+            });
+        };
+        const createRawQa = async (qaCwd, sessionId) => {
             const qaPolicy = new PermissionPolicy(config.permissions, qaCwd);
             const roleBundle = loadRoleBundle("qa", { projectDir: qaCwd });
             const adapterOpts = {
                 cwd: qaCwd,
+                runtimeExecutable: qaExecutable,
+                runtimePhase: "qa",
                 model: qaModel,
                 resumeSessionId: sessionId,
                 permission: createPermissionHandler(qaPolicy, log),
@@ -398,6 +451,27 @@ export function buildStartCommand() {
                 ? new CodexAdapter(adapterOpts)
                 : await ClaudeAdapter.create(adapterOpts);
         };
+        const createQa = async (qaCwd, sessionId) => {
+            const initial = await createRawQa(qaCwd, sessionId);
+            return new RecoveringAdapter({
+                initial,
+                runtime: qaAgent,
+                label: "QA turn",
+                enabled: !opts.yes && Boolean(process.stdin.isTTY && process.stdout.isTTY),
+                allowSwitch: !sessionId,
+                recreate: async (nextRuntime, resumeSessionId) => {
+                    const nextReady = await ensureRuntimeReadyForCommand(qaCwd, nextRuntime, {
+                        label: "QA recovery",
+                        allowSwitch: false,
+                        model: nextRuntime === qaAgent ? qaModel : undefined,
+                    });
+                    qaAgent = nextReady.runtime;
+                    qaModel = nextReady.model;
+                    qaExecutable = nextReady.executable;
+                    return createRawQa(qaCwd, resumeSessionId);
+                },
+            });
+        };
         if (branchMode) {
             const ticketsConfig = loadTicketsConfig(cwd);
             const allowedBaseDirtyPaths = generatedTrackerDirtyPaths(ticketsConfig.paths);
@@ -418,6 +492,7 @@ export function buildStartCommand() {
             });
             agent = ready.runtime;
             model = ready.model;
+            agentExecutable = ready.executable;
             const ticketPaths = resolveTicketPaths(ticketsConfig, cwd);
             const tickets = loadTickets(ticketPaths.tickets);
             const db = new StateDb(ticketPaths.stateDb);
@@ -481,6 +556,8 @@ export function buildStartCommand() {
                     auditBuilder = await createBuilder(cwd);
                     auditViewer = printEvents(auditBuilder.events());
                     const audit = await auditBuilder.sendTurn(buildBranchAuditInstruction(plan.nodes.map((node) => node.ticket)));
+                    if (audit.isError)
+                        throw new Error(audit.text);
                     const auditDependencies = parseAuditDependencies(audit.text);
                     plan = buildBranchPlan(tickets, states, {
                         steps,
@@ -604,10 +681,12 @@ export function buildStartCommand() {
         });
         agent = ready.runtime;
         model = ready.model;
+        agentExecutable = ready.executable;
         if (qaEnabled) {
             const qaReady = await ensureRuntimeReadyForCommand(cwd, qaAgent, { label: "independent QA", yes: Boolean(opts.yes), model: qaModel });
             qaAgent = qaReady.runtime;
             qaModel = qaReady.model;
+            qaExecutable = qaReady.executable;
         }
         const capturedBuilder = {
             role: "builder", source: opts.agent || opts.model || opts.effort || opts.fast ? "cli" : roleDefaults.builder ? "project" : "provider",
@@ -698,9 +777,13 @@ export function buildStartCommand() {
             console.log(`foreman: outcome — ${result.outcome}`);
             if (result.detail)
                 console.log(`foreman: ${result.detail}`);
-            const sid = builder.sessionId();
-            if (sid)
-                console.log(`foreman: resume this builder with  --resume ${sid}`);
+            if (result.outcome !== "all-done" && result.outcome !== "plan-complete") {
+                const executable = command.parent?.name() === "rafi" ? "rafi" : "ai-foreman";
+                const remainingSteps = Math.max(1, result.requested - result.completed);
+                for (const line of formatResumeGuidance(executable, cwd, remainingSteps, builder.sessionId())) {
+                    console.log(line);
+                }
+            }
             process.exit(result.outcome === "needs-human" ? 2 : 0);
         }
         catch (err) {
@@ -733,3 +816,8 @@ function explicitDefaultValue(value) {
 function explicitEffort(value) {
     return value && ["low", "medium", "high", "xhigh"].includes(value) ? value : undefined;
 }
+function shellQuote(value) {
+    return /^[A-Za-z0-9_./:@%+=,-]+$/.test(value)
+        ? value
+        : `'${value.replace(/'/g, `'"'"'`)}'`;
+}

package/dist/foreman.js

@@ -249,13 +249,18 @@ export class Foreman {
         this.log.write("preflight", {
             ticketsProvided: ticketsContent !== undefined,
             costUsd: result.costUsd,
+            isError: result.isError,
         });
+        if (result.isError)
+            throw new Error(result.text);
         return result.text;
     }
     /** Send user feedback on the plan; builder responds with a revised list. Does not count toward steps. */
     async sendPreflightFeedback(feedback) {
         const result = await this.builder.sendTurn(feedback);
-        this.log.write("preflight", { feedback: true, costUsd: result.costUsd });
+        this.log.write("preflight", { feedback: true, costUsd: result.costUsd, isError: result.isError });
+        if (result.isError)
+            throw new Error(result.text);
     }
     /** Send one custom instruction through the same needs_input loop as a batch turn. */
     async runInstruction(instruction) {
@@ -472,7 +477,11 @@ function fingerprintProtectedTree(root) {
             const path = join(directory, entry.name);
             const rel = relative(root, path).replace(/\\/g, "/");
             if (entry.isDirectory()) {
-                if (ignored.has(entry.name) || rel.startsWith(".foreman/") || rel.startsWith(".rafi/cache/"))
+                if (ignored.has(entry.name)
+                    || rel === ".foreman"
+                    || rel.startsWith(".foreman/")
+                    || rel === ".rafi/cache"
+                    || rel.startsWith(".rafi/cache/"))
                     continue;
                 visit(path);
             }

package/dist/runtimeAuth.d.ts

@@ -15,7 +15,7 @@ export declare class RuntimeAuthError extends Error {
     readonly authLikely: boolean;
     constructor(opts: RuntimeAuthErrorOptions);
 }
-export declare function checkRuntimeReady(projectDir: string, runtime: AgentRuntime): Promise<void>;
+export declare function checkRuntimeReady(projectDir: string, runtime: AgentRuntime): Promise<import("rafi-spec").RuntimeProbeResult>;
 export declare function normalizeRuntimeErrorText(runtime: AgentRuntime, text: string, exitCode?: number | null, context?: string): string;
 export declare function isRuntimeAuthFailure(output: string): boolean;
 export declare function runtimeCommandLabel(runtime: AgentRuntime): string;

package/dist/runtimeAuth.js

@@ -24,6 +24,7 @@ export async function checkRuntimeReady(projectDir, runtime) {
             exitCode: result.exitCode,
             stderr: formatRuntimeProbeFailure(result),
         });
+    return result;
 }
 export function normalizeRuntimeErrorText(runtime, text, exitCode, context = "builder turn") {
     if (!isRuntimeAuthFailure(text))
@@ -55,12 +56,9 @@ export function runtimeCommandLabel(runtime) {
 export function runtimeRepairCommands(runtime) {
     if (runtime === "claude") {
         return [
-            "claude auth logout",
-            "claude auth login --claudeai",
+            "Authenticate in Claude Code using the login method approved by your organization.",
+            "Enterprise users should keep using their organization-provided flow (for example, /login-okta).",
             'claude -p "Return exactly OK"',
-            "",
-            "Claude subscription users may also need:",
-            "claude setup-token",
         ].join("\n");
     }
     return [
@@ -73,7 +71,7 @@ export function formatRuntimeAuthFailure(opts) {
     const exit = opts.exitCode === undefined || opts.exitCode === null ? "unknown" : String(opts.exitCode);
     const authLine = isRuntimeAuthFailure(output)
         ? "The runtime output looks like an authentication failure."
-        : "This often means the selected agent runtime is missing or not authenticated.";
+        : "The selected runtime failed; review the actual output below before changing authentication.";
     const details = output ? `\n\nRuntime output:\n${truncateRuntimeOutput(output)}` : "";
     return (`${runtimeCommandLabel(opts.runtime)} failed during ${opts.context} (exit code ${exit}).\n\n` +
         `${authLine}\n\n` +

package/dist/runtimeReadiness.d.ts

@@ -8,7 +8,10 @@ export interface ProbeRuntimeOptions {
     maxDiagnosticsBytes?: number;
     env?: NodeJS.ProcessEnv;
 }
+/** Resolve the executable Node will launch without involving a shell. */
+export declare function resolveExecutablePath(command: string, env?: NodeJS.ProcessEnv, platform?: NodeJS.Platform): string | undefined;
 export declare function probeRuntime(cwd: string, runtime: AgentRuntime, opts?: ProbeRuntimeOptions): Promise<RuntimeProbeResult>;
 export declare function classifyRuntimeFailure(text: string, phase?: RuntimeProbePhase): RuntimeProbeCategory;
+export declare function classifyClaudeSdkFailure(error: string | undefined, status: number | null | undefined, diagnostics: string): RuntimeProbeCategory;
 export declare function sanitizeDiagnostics(text: string, maxBytes?: number): string;
 export declare function formatRuntimeProbeFailure(result: RuntimeProbeResult): string;

package/dist/runtimeReadiness.js

@@ -1,14 +1,64 @@
 import { spawn } from "node:child_process";
+import { accessSync, constants, statSync } from "node:fs";
+import { delimiter, isAbsolute, resolve } from "node:path";
 export const RUNTIME_PROBE_TIMEOUT_MS = 30_000;
 export const RUNTIME_DIAGNOSTIC_LIMIT = 8 * 1024;
 const RELEVANT_ENV = /^(ANTHROPIC|CLAUDE|CODEX|OPENAI|HTTP_PROXY|HTTPS_PROXY|NO_PROXY|SSL_CERT_FILE|NODE_EXTRA_CA_CERTS)(_|$)/i;
+/** Resolve the executable Node will launch without involving a shell. */
+export function resolveExecutablePath(command, env = process.env, platform = process.platform) {
+    const hasPathSeparator = command.includes("/") || command.includes("\\");
+    if (isAbsolute(command) || hasPathSeparator) {
+        const candidate = resolve(command);
+        return isRunnableFile(candidate, platform) ? candidate : undefined;
+    }
+    const pathValue = platform === "win32"
+        ? env.Path ?? env.PATH ?? env.path
+        : env.PATH;
+    if (!pathValue)
+        return undefined;
+    const extensions = platform === "win32"
+        ? executableExtensions(command, env.PATHEXT)
+        : [""];
+    const pathDelimiter = platform === "win32" ? ";" : delimiter;
+    for (const entry of pathValue.split(pathDelimiter)) {
+        const directory = entry || process.cwd();
+        for (const extension of extensions) {
+            const candidate = resolve(directory, `${command}${extension}`);
+            if (isRunnableFile(candidate, platform))
+                return candidate;
+        }
+    }
+    return undefined;
+}
+function executableExtensions(command, pathExt) {
+    const extensions = (pathExt ?? ".COM;.EXE;.BAT;.CMD")
+        .split(";")
+        .filter(Boolean)
+        .map((value) => value.startsWith(".") ? value : `.${value}`);
+    const lower = command.toLowerCase();
+    return extensions.some((extension) => lower.endsWith(extension.toLowerCase()))
+        ? [""]
+        : extensions;
+}
+function isRunnableFile(path, platform) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        accessSync(path, platform === "win32" ? constants.F_OK : constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export async function probeRuntime(cwd, runtime, opts = {}) {
-    const executable = runtime === "claude" ? "claude" : "codex";
+    const env = opts.env ?? process.env;
+    const command = runtime === "claude" ? "claude" : "codex";
+    const executable = resolveExecutablePath(command, env) ?? command;
     const args = runtime === "claude"
         ? ["-p", "Return exactly OK"]
         : ["exec", "--skip-git-repo-check", "-C", cwd, "Return exactly OK"];
     const phase = opts.phase ?? "readiness";
-    const env = opts.env ?? process.env;
     const limit = opts.maxDiagnosticsBytes ?? RUNTIME_DIAGNOSTIC_LIMIT;
     const timeoutMs = opts.timeoutMs ?? RUNTIME_PROBE_TIMEOUT_MS;
     return new Promise((resolveResult) => {
@@ -89,6 +139,29 @@ export function classifyRuntimeFailure(text, phase = "readiness") {
         return "capability-discovery";
     return "unknown";
 }
+export function classifyClaudeSdkFailure(error, status, diagnostics) {
+    switch (error) {
+        case "authentication_failed": return "authentication";
+        case "oauth_org_not_allowed": return "authorization";
+        case "rate_limit": return "rate-limit";
+        case "model_not_found":
+        case "invalid_request":
+        case "max_output_tokens": return "configuration";
+        case "billing_error": return "authorization";
+        case "server_error": return "agent-stream";
+    }
+    if (status === 401)
+        return "authentication";
+    if (status === 403)
+        return "authorization";
+    if (status === 407)
+        return "network";
+    if (status === 429)
+        return "rate-limit";
+    if (status !== undefined && status !== null && status >= 500)
+        return "agent-stream";
+    return classifyRuntimeFailure(diagnostics, "builder");
+}
 export function sanitizeDiagnostics(text, maxBytes = RUNTIME_DIAGNOSTIC_LIMIT) {
     const clean = text
         .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "")
@@ -110,7 +183,7 @@ export function formatRuntimeProbeFailure(result) {
     ];
     if (result.category === "authentication") {
         lines.push(result.runtime === "claude"
-            ? "Authenticate with `claude auth login --claudeai`, then retry."
+            ? "Authenticate with the Claude Code login method approved by your organization, then rerun `claude -p \"Return exactly OK\"`."
             : "Authenticate with `codex login`, then retry.");
     }
     else {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "description": "An orchestrator that keeps Codex CLI / Claude Code builders moving through their step list unattended. Part of Rafi.",
   "license": "Apache-2.0",
   "type": "module",
@@ -29,6 +29,10 @@
       "types": "./dist/runtimeReadiness.d.ts",
       "default": "./dist/runtimeReadiness.js"
     },
+    "./claude-adapter.js": {
+      "types": "./dist/adapters/claude.d.ts",
+      "default": "./dist/adapters/claude.js"
+    },
     "./roles.js": {
       "types": "./dist/roles.d.ts",
       "default": "./dist/roles.js"