ai-foreman 1.1.0 → 1.2.0

package/README.md

@@ -85,7 +85,7 @@ What each part does:
 | --- | --- | --- | --- |
 | `<project>` | `./my-project` / `../repo` | required | Target repo the agent works in. |
 | `-s, --steps <n>` | `1` / `5` / `10` | required | Max tickets or implementation steps to drive. |
-| `-a, --agent <agent>` | `claude` / `codex` | `claude` | Builder agent. |
+| `-a, --agent <agent>` | `claude` / `codex` | single `rafi-config.yaml` target, otherwise `claude` | Builder agent. Explicit `--agent` always wins. |
 | `-m, --model <model>` | `gpt-5.5` / any supported agent model | agent default | Overrides the builder model. |
 | `--effort <level>` | Claude Code: `low` / `medium` / `high` / `xhigh`<br>Codex: `low` / `medium` / `high` / `xhigh` | agent default | Reasoning level. |
 | `--fast` | flag | off | Lower latency. For Codex, maps to `effort=low` when `--effort` is not set. |
@@ -156,7 +156,7 @@ gh repo view <host>/<owner>/<repo>
 | Option | Common values | Default | Notes |
 | --- | --- | --- | --- |
 | `-p, --project <dir>` | `./my-project` / `../repo` | current directory | Target repo with `.tickets/`. |
-| `-a, --agent <agent>` | `claude` / `codex` | `claude` | Builder agent. |
+| `-a, --agent <agent>` | `claude` / `codex` | single `rafi-config.yaml` target, otherwise `claude` | Builder agent. Explicit `--agent` always wins. |
 | `-m, --model <model>` | `gpt-5.5` / any supported agent model | agent default | Overrides the builder model. |
 | `--effort <level>` | Claude Code: `low` / `medium` / `high` / `xhigh`<br>Codex: `low` / `medium` / `high` / `xhigh` | agent default | Reasoning level. |
 | `--sources <paths...>` | `docs/tickets.md docs/plans/**` | scans relevant docs automatically | Optional files, folders, or globs for the agent to check first. Any reasonable planning format is OK. |
@@ -188,17 +188,25 @@ Without tickets, Foreman still works with:
 
 Claude Code:
 
-- Default agent.
+- Default agent when no single runtime target is configured.
 - Uses your existing Claude Code credentials.
 - Runs through the Claude Agent SDK.
-- `start` and `tickets populate` check Claude auth before launching the builder and prompt you to repair it if needed.
+- `start` and `tickets populate` check Claude auth before launching the builder and prompt you to repair it, switch to Codex for the current run, or cancel when interactive.
 
 Codex:
 
-- Use `--agent codex`.
+- Use `--agent codex`, or set `harness.targets: ["codex"]` in `rafi-config.yaml` and omit `--agent`.
 - Shells out to `codex exec`.
 - Requires the `codex` CLI on your `PATH`.
-- `start` and `tickets populate --agent codex` check Codex auth before launching the builder and prompt you to repair it if needed.
+- `start` and `tickets populate --agent codex` check Codex auth before launching the builder and prompt you to repair it, switch to Claude for the current run, or cancel when interactive.
+
+Runtime defaults and recovery:
+
+- If `--agent` is omitted, Foreman reads `rafi-config.yaml`. A single `harness.targets` value selects that runtime; missing config or both targets default to Claude.
+- Non-interactive and `--yes` runs fail clearly instead of switching runtimes automatically.
+- Resume and continue flows do not offer runtime switching because session IDs are runtime-specific.
+- If an interactive command switches providers, a provider-specific `--model` override is ignored for that run. `--effort` and `--fast` remain in effect.
+- Cancel stops the command and keeps project files, generated files, and installed packages in place.
 
 Task file:
 

package/dist/cli/runtimeAuthPrompt.d.ts

@@ -1,2 +1,21 @@
-import { type AgentRuntime } from "../runtimeAuth.js";
-export declare function ensureRuntimeReadyForCommand(projectDir: string, runtime: AgentRuntime, label: string): Promise<void>;
+import { RuntimeAuthError, type AgentRuntime } from "../runtimeAuth.js";
+export type RuntimeCommandRecoveryChoice = "retry" | "switch" | "cancel";
+export interface RuntimeCommandRecoveryContext {
+    otherRuntime: AgentRuntime;
+    allowSwitch: boolean;
+}
+export interface RuntimeReadyForCommandOptions {
+    label: string;
+    yes?: boolean;
+    allowSwitch?: boolean;
+    model?: string | undefined;
+    check?: (projectDir: string, runtime: AgentRuntime) => void;
+    checkClaudeSdk?: () => Promise<void>;
+    choose?: (err: RuntimeAuthError, context: RuntimeCommandRecoveryContext) => Promise<RuntimeCommandRecoveryChoice>;
+}
+export interface RuntimeReadyForCommandResult {
+    runtime: AgentRuntime;
+    model?: string;
+    fellBack: boolean;
+}
+export declare function ensureRuntimeReadyForCommand(projectDir: string, runtime: AgentRuntime, labelOrOptions: string | RuntimeReadyForCommandOptions): Promise<RuntimeReadyForCommandResult>;

package/dist/cli/runtimeAuthPrompt.js

@@ -1,27 +1,79 @@
 import { select, isCancel, log } from "@clack/prompts";
+import { requireClaudeSDK } from "../adapters/claude.js";
 import { checkRuntimeReady, RuntimeAuthError, runtimeCommandLabel, } from "../runtimeAuth.js";
-export async function ensureRuntimeReadyForCommand(projectDir, runtime, label) {
+import { otherRuntime, runtimeDisplayName } from "./runtimeSelection.js";
+export async function ensureRuntimeReadyForCommand(projectDir, runtime, labelOrOptions) {
+    const opts = typeof labelOrOptions === "string"
+        ? { label: labelOrOptions }
+        : labelOrOptions;
+    const check = opts.check ?? checkRuntimeReady;
+    const checkClaudeSdk = opts.checkClaudeSdk ?? requireClaudeSDK;
+    const allowSwitch = opts.allowSwitch !== false;
+    const nonInteractive = !opts.choose && (Boolean(opts.yes) || !process.stdin.isTTY || !process.stdout.isTTY);
     while (true) {
         try {
-            checkRuntimeReady(projectDir, runtime);
-            return;
+            check(projectDir, runtime);
+            return { runtime, model: opts.model, fellBack: false };
         }
         catch (err) {
             const failure = err instanceof RuntimeAuthError
                 ? err
-                : new RuntimeAuthError({ runtime, context: label, cause: err });
-            log.error(failure.message);
-            const choice = await select({
-                message: `${runtimeCommandLabel(runtime)} is not ready for ${label}. Fix authentication, then retry the check.`,
-                options: [
-                    { value: "retry", label: "Retry check" },
-                    { value: "cancel", label: "Cancel" },
-                ],
-            });
-            if (isCancel(choice) || choice === "cancel") {
+                : new RuntimeAuthError({ runtime, context: opts.label, cause: err });
+            if (nonInteractive) {
+                throw failure;
+            }
+            const fallbackRuntime = otherRuntime(runtime);
+            const choice = opts.choose
+                ? await opts.choose(failure, { otherRuntime: fallbackRuntime, allowSwitch })
+                : await promptRuntimeRecovery(failure, opts.label, fallbackRuntime, allowSwitch);
+            if (choice === "retry")
+                continue;
+            if (choice === "switch" && allowSwitch) {
+                try {
+                    check(projectDir, fallbackRuntime);
+                    if (fallbackRuntime === "claude") {
+                        await checkClaudeSdk();
+                    }
+                    if (opts.model) {
+                        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 };
+                }
+                catch (switchErr) {
+                    const switchFailure = switchErr instanceof RuntimeAuthError
+                        ? switchErr
+                        : new RuntimeAuthError({ runtime: fallbackRuntime, context: opts.label, cause: switchErr });
+                    log.error(`Fallback runtime is not ready:\n${switchFailure.message}`);
+                    continue;
+                }
+            }
+            if (choice === "cancel") {
                 console.log("foreman: cancelled");
                 process.exit(0);
             }
+            throw failure;
         }
     }
 }
+async function promptRuntimeRecovery(err, label, fallbackRuntime, allowSwitch) {
+    log.error(err.message);
+    log.info("Cancel stops this command and keeps project files in place. It does not uninstall packages, delete generated files, or change configuration.");
+    if (!allowSwitch) {
+        log.info("Switching runtimes is disabled while resuming because session IDs are runtime-specific.");
+    }
+    const options = [
+        { value: "retry", label: "Fix manually and retry check" },
+        ...(allowSwitch
+            ? [{ value: "switch", label: `Use ${runtimeDisplayName(fallbackRuntime)} for now` }]
+            : []),
+        { value: "cancel", label: "Cancel - stop here; keep generated files" },
+    ];
+    const choice = await select({
+        message: `${runtimeCommandLabel(err.runtime)} is not ready for ${label}. What should Foreman do?`,
+        options,
+    });
+    if (isCancel(choice))
+        return "cancel";
+    return choice;
+}

package/dist/cli/runtimeSelection.d.ts

@@ -0,0 +1,9 @@
+import type { AgentRuntime } from "../runtimeAuth.js";
+export declare const VALID_AGENTS: readonly ["claude", "codex"];
+export declare function isAgentRuntime(value: string): value is AgentRuntime;
+export declare function validateAgentRuntime(value: string): AgentRuntime;
+export declare function otherRuntime(runtime: AgentRuntime): AgentRuntime;
+export declare function runtimeDisplayName(runtime: AgentRuntime): string;
+export declare function defaultAgentForProject(projectDir: string): AgentRuntime;
+export declare function resolveAgentForProject(projectDir: string, explicitAgent?: string): AgentRuntime;
+export declare function readRafiRuntimeTargets(projectDir: string): AgentRuntime[] | undefined;

package/dist/cli/runtimeSelection.js

@@ -0,0 +1,48 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parse as parseYaml } from "yaml";
+export const VALID_AGENTS = ["claude", "codex"];
+export function isAgentRuntime(value) {
+    return VALID_AGENTS.includes(value);
+}
+export function validateAgentRuntime(value) {
+    if (isAgentRuntime(value))
+        return value;
+    throw new Error(`unknown agent "${value}" - choose: ${VALID_AGENTS.join(" | ")}`);
+}
+export function otherRuntime(runtime) {
+    return runtime === "claude" ? "codex" : "claude";
+}
+export function runtimeDisplayName(runtime) {
+    return runtime === "claude" ? "Claude" : "Codex";
+}
+export function defaultAgentForProject(projectDir) {
+    const targets = readRafiRuntimeTargets(projectDir);
+    return targets?.length === 1 ? targets[0] : "claude";
+}
+export function resolveAgentForProject(projectDir, explicitAgent) {
+    if (explicitAgent !== undefined)
+        return validateAgentRuntime(explicitAgent);
+    return defaultAgentForProject(projectDir);
+}
+export function readRafiRuntimeTargets(projectDir) {
+    const configPath = join(projectDir, "rafi-config.yaml");
+    if (!existsSync(configPath))
+        return undefined;
+    try {
+        const raw = parseYaml(readFileSync(configPath, "utf8"));
+        const targets = raw?.harness?.targets;
+        if (!Array.isArray(targets))
+            return undefined;
+        const out = [];
+        for (const target of targets) {
+            if ((target === "claude" || target === "codex") && !out.includes(target)) {
+                out.push(target);
+            }
+        }
+        return out.length > 0 ? out : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/cli/start.js

@@ -11,6 +11,7 @@ import { Foreman, createPermissionHandler } from "../foreman.js";
 import { printEvents } from "./events.js";
 import { loadRoleBundle } from "../roles.js";
 import { ensureRuntimeReadyForCommand } from "./runtimeAuthPrompt.js";
+import { resolveAgentForProject } from "./runtimeSelection.js";
 import { isTicketsInitialized, loadTicketsConfig, resolveTicketPaths } from "../tickets/config.js";
 import { loadTickets } from "../tickets/ticketLoader.js";
 import { StateDb } from "../tickets/stateDb.js";
@@ -97,7 +98,7 @@ export function buildStartCommand() {
         .description("Enlist a builder and drive it through a batch of N steps.")
         .argument("<project>", "path to the project directory the builder works in")
         .requiredOption("-s, --steps <n>", "number of steps to drive")
-        .option("-a, --agent <agent>", "builder agent (claude | codex)", "claude")
+        .option("-a, --agent <agent>", "builder agent (claude | codex)")
         .option("-m, --model <model>", "override the builder's model")
         .option("-r, --resume <sessionId>", "resume a prior builder session")
         .option("--continue", "resume the most recent logged session for this project")
@@ -119,10 +120,6 @@ export function buildStartCommand() {
         if (!Number.isInteger(steps) || steps < 1) {
             fail("--steps must be a positive integer");
         }
-        const VALID_AGENTS = ["claude", "codex"];
-        if (!VALID_AGENTS.includes(opts.agent)) {
-            fail(`unknown agent "${opts.agent}" — choose: ${VALID_AGENTS.join(" | ")}`);
-        }
         const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
         if (opts.effort && !VALID_EFFORT.includes(opts.effort)) {
             fail(`unknown effort "${opts.effort}" — choose: ${VALID_EFFORT.join(" | ")}`);
@@ -130,6 +127,14 @@ export function buildStartCommand() {
         const cwd = resolve(project);
         if (!existsSync(cwd))
             fail(`project directory not found: ${cwd}`);
+        let agent;
+        try {
+            agent = resolveAgentForProject(cwd, opts.agent);
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+        let model = opts.model;
         const configuredTrackerPath = isTicketsInitialized(cwd)
             ? loadTicketsConfig(cwd).paths.progressDoc
             : undefined;
@@ -193,14 +198,13 @@ export function buildStartCommand() {
         const stamp = new Date().toISOString().replace(/[:.]/g, "-");
         const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
         const log = new Log(logPath);
-        const agent = opts.agent;
         const qaEnabled = opts.qa !== false && config.qa.enabled !== false;
         const createBuilder = async (builderCwd, sessionId) => {
             const builderPolicy = new PermissionPolicy(config.permissions, builderCwd);
             const roleBundle = loadRoleBundle("builder", { projectDir: builderCwd });
             const adapterOpts = {
                 cwd: builderCwd,
-                model: opts.model,
+                model,
                 resumeSessionId: sessionId,
                 permission: createPermissionHandler(builderPolicy, log),
                 effort: opts.effort,
@@ -224,7 +228,14 @@ export function buildStartCommand() {
             if (opts.createPr) {
                 await ensureGitHubReadyForCreatePr(cwd, log, Boolean(opts.yes));
             }
-            await ensureRuntimeReadyForCommand(cwd, agent, "start");
+            const ready = await ensureRuntimeReadyForCommand(cwd, agent, {
+                label: "start",
+                yes: Boolean(opts.yes),
+                allowSwitch: !(opts.resume || opts.continue),
+                model,
+            });
+            agent = ready.runtime;
+            model = ready.model;
             const ticketPaths = resolveTicketPaths(ticketsConfig, cwd);
             const tickets = loadTickets(ticketPaths.tickets);
             const db = new StateDb(ticketPaths.stateDb);
@@ -337,7 +348,7 @@ export function buildStartCommand() {
                 plan,
                 log,
                 agent,
-                model: opts.model,
+                model,
                 effort: opts.effort,
                 fast: opts.fast,
                 notificationsEnabled: config.notifications.enabled,
@@ -378,11 +389,18 @@ export function buildStartCommand() {
             const failed = summaries.some((row) => row.buildStatus === "blocked" || row.buildStatus === "needs-human");
             process.exit(failed ? 2 : 0);
         }
-        await ensureRuntimeReadyForCommand(cwd, agent, "start");
+        const ready = await ensureRuntimeReadyForCommand(cwd, agent, {
+            label: "start",
+            yes: Boolean(opts.yes),
+            allowSwitch: !(opts.resume || opts.continue),
+            model,
+        });
+        agent = ready.runtime;
+        model = ready.model;
         const builder = await createBuilder(cwd, resumeSessionId);
         const foreman = new Foreman(builder, log, config.notifications.enabled, qaEnabled, 3, cwd);
         const modifiers = [
-            opts.model ? `model=${opts.model}` : null,
+            model ? `model=${model}` : null,
             opts.effort ? `effort=${opts.effort}` : null,
             opts.fast ? "fast" : null,
             qaEnabled ? null : "qa=off",

package/dist/cli/tickets.js

@@ -14,6 +14,7 @@ import { isTicketsInitialized, loadTicketsConfig } from "../tickets/config.js";
 import { importFromMarkdown } from "../tickets/importer.js";
 import { formatValidationIssues } from "../tickets/validate.js";
 import { ensureRuntimeReadyForCommand } from "./runtimeAuthPrompt.js";
+import { resolveAgentForProject } from "./runtimeSelection.js";
 function fail(msg) {
     console.error(`foreman tickets: ${msg}`);
     process.exit(1);
@@ -21,13 +22,7 @@ function fail(msg) {
 function cwd(opts) {
     return resolve(opts.project ?? ".");
 }
-const VALID_AGENTS = ["claude", "codex"];
 const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
-function validateAgent(agent) {
-    if (!VALID_AGENTS.includes(agent)) {
-        fail(`unknown agent "${agent}" — choose: ${VALID_AGENTS.join(" | ")}`);
-    }
-}
 function validateEffort(effort) {
     if (effort && !VALID_EFFORT.includes(effort)) {
         fail(`unknown effort "${effort}" — choose: ${VALID_EFFORT.join(" | ")}`);
@@ -118,7 +113,7 @@ export function buildTicketsCommand() {
         .command("populate")
         .description("Ask a builder to populate .tickets/tickets.yaml from existing project ticket/backlog docs.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
-        .option("-a, --agent <agent>", "builder agent (claude | codex)", "claude")
+        .option("-a, --agent <agent>", "builder agent (claude | codex)")
         .option("-m, --model <model>", "override the builder's model")
         .option("--effort <level>", "reasoning effort level (low|medium|high|xhigh)")
         .option("--sources <paths...>", "source hint files, folders, or globs to check first")
@@ -126,11 +121,17 @@ export function buildTicketsCommand() {
         .option("-y, --yes", "skip confirmation prompt before letting the builder edit tickets")
         .action(async (opts) => {
         const dir = cwd(opts);
-        const agent = opts.agent;
-        validateAgent(agent);
         validateEffort(opts.effort);
         if (!existsSync(dir))
             fail(`project directory not found: ${dir}`);
+        let agent;
+        try {
+            agent = resolveAgentForProject(dir, opts.agent);
+        }
+        catch (err) {
+            fail(err instanceof Error ? err.message : String(err));
+        }
+        let model = opts.model;
         if (!isTicketsInitialized(dir)) {
             fail(`ticket tracker is not initialized in ${dir}; run \`foreman tickets init --project ${dir}\` first`);
         }
@@ -151,10 +152,16 @@ export function buildTicketsCommand() {
         const logPath = makeLogPath(dir, "tickets-populate");
         const log = new Log(logPath);
         const policy = new PermissionPolicy(config.permissions, dir);
-        await ensureRuntimeReadyForCommand(dir, agent, "tickets populate");
+        const ready = await ensureRuntimeReadyForCommand(dir, agent, {
+            label: "tickets populate",
+            yes: Boolean(opts.yes),
+            model,
+        });
+        agent = ready.runtime;
+        model = ready.model;
         const adapterOpts = {
             cwd: dir,
-            model: opts.model,
+            model,
             permission: createPermissionHandler(policy, log),
             effort: opts.effort,
             fast: opts.fast,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.1.0",
+  "version": "1.2.0",
   "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",
@@ -14,7 +14,7 @@
   },
   "homepage": "https://github.com/ttante/rafi/tree/main/packages/ai-foreman#readme",
   "bin": {
-    "ai-foreman": "./dist/index.js"
+    "ai-foreman": "dist/index.js"
   },
   "exports": {
     "./cli/tickets.js": {