ai-foreman 1.1.0 → 1.3.0

package/README.md

@@ -51,7 +51,7 @@ Requires:
 
 - Check the target project.
 - Initialize Foreman's local ticket tracker.
-- Ask agent to convert existing tickets or populate them
+- Ask the ticket-maker role to convert existing tickets or populate them
 - Run foreman for 5 tickets (and QA each one when done)
 
 ```bash
@@ -65,12 +65,13 @@ What each part does:
 
 - `./my-project`: the repo Foreman will work on.
 - `tickets init`: creates the local `.tickets/` tracker.
-- `tickets populate`: asks Codex to convert project planning material.
+- `tickets populate`: asks the ticket-maker role to convert project planning material.
 - Converted output uses Foreman's schema.
 - `start`: drives Codex through the next tickets one step at a time.
 
 `tickets populate` can convert:
 
+- a managed Rafi plan at `<docs.root>/rafi-plan.md`
 - plans
 - TODOs
 - roadmap docs
@@ -85,7 +86,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,10 +157,10 @@ 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. |
+| `--sources <paths...>` | `docs/tickets.md docs/plans/**` | Configured Rafi `<docs.root>/rafi-plan.md`, then ticket docs root, then `docs/rafi-plan.md`, otherwise scans | Optional files, folders, or globs for the agent to check first. Any reasonable planning format is OK. |
 | `--fast` | flag | off | Lower latency. |
 | `-y, --yes` | flag | off | Skips confirmation before builder edits ticket files. |
 
@@ -188,17 +189,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:
 
@@ -275,7 +284,7 @@ With `--docs-root docs-rafi`, the generated tracker docs are written under `docs
 
 If the project already has planning material:
 
-- Ask a builder to convert it into Foreman's ticket format.
+- Ask the ticket-maker role to convert it into Foreman's ticket format.
 
 Supported source material can include:
 
@@ -289,6 +298,7 @@ Supported source material can include:
 ```bash
 # Claude Code
 ai-foreman tickets populate --project ./my-project
+ai-foreman tickets populate --project ./my-project --sources docs/rafi-plan.md
 ai-foreman tickets populate --project ./my-project --sources docs/tickets.md docs/plans/**
 
 # Codex
@@ -300,6 +310,7 @@ ai-foreman tickets populate --project ./my-project --agent codex --model gpt-5.5
 
 - read `.tickets/*`
 - read the configured progress doc
+- prefer the configured Rafi `<docs.root>/rafi-plan.md`, then the ticket docs root, then `docs/rafi-plan.md` when no `--sources` are provided
 - read existing planning files
 - fill `.tickets/tickets.yaml`
 - render the progress doc
@@ -527,7 +538,8 @@ For Claude:
 For Codex:
 
 - Codex tool calls are not currently intercepted by Foreman.
-- Codex runs under `codex exec --sandbox workspace-write`.
+- Runtime implementation and ticket population runs use `codex exec --sandbox workspace-write`.
+- Read-only callers such as `rafi plan` can request `codex exec --sandbox read-only`.
 - Codex safety depends on Codex's own sandboxing.
 
 Default config:

package/dist/adapters/codex.d.ts

@@ -21,7 +21,7 @@ export declare function parseCodexLine(raw: Record<string, unknown>): CodexLineR
  * subsequent turns.
  *
  * NOTE: opts.permission is accepted for interface conformance but is not
- * invoked. Codex manages its own tool sandboxing via --sandbox workspace-write.
+ * invoked. Codex manages its own tool sandboxing via --sandbox.
  */
 export declare class CodexAdapter implements BuilderAdapter {
     private readonly opts;
@@ -39,6 +39,7 @@ export declare class CodexAdapter implements BuilderAdapter {
     buildInstruction(instruction: string): string;
     /** Build the `codex exec` argument list for the given instruction. */
     buildArgs(instruction: string): string[];
+    private buildSkillsAppendix;
     sendTurn(instruction: string): Promise<TurnResult>;
     sessionId(): string | undefined;
     events(): AsyncIterable<BuilderEvent>;

package/dist/adapters/codex.js

@@ -1,5 +1,8 @@
 import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
 import { createInterface } from "node:readline";
+import { loadSkill } from "special-agents";
 import { AsyncQueue } from "../util/asyncQueue.js";
 import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 /**
@@ -44,7 +47,7 @@ export function parseCodexLine(raw) {
  * subsequent turns.
  *
  * NOTE: opts.permission is accepted for interface conformance but is not
- * invoked. Codex manages its own tool sandboxing via --sandbox workspace-write.
+ * invoked. Codex manages its own tool sandboxing via --sandbox.
  */
 export class CodexAdapter {
     opts;
@@ -63,13 +66,22 @@ export class CodexAdapter {
      * role guidance must ride along with each turn.
      */
     buildInstruction(instruction) {
-        return this.opts.systemPromptAppend
-            ? `${this.opts.systemPromptAppend}\n\n${instruction}`
-            : instruction;
+        return [
+            this.opts.systemPromptAppend,
+            this.buildSkillsAppendix(),
+            instruction,
+        ].filter((part) => Boolean(part)).join("\n\n");
     }
     /** Build the `codex exec` argument list for the given instruction. */
     buildArgs(instruction) {
-        const args = ["exec", "--json", "--sandbox", "workspace-write", "-C", this.opts.cwd];
+        const args = [
+            "exec",
+            "--json",
+            "--sandbox",
+            this.opts.sandboxMode ?? "workspace-write",
+            "-C",
+            this.opts.cwd,
+        ];
         if (this.opts.model)
             args.push("-m", this.opts.model);
         if (this.opts.effort) {
@@ -84,6 +96,20 @@ export class CodexAdapter {
         args.push(instruction);
         return args;
     }
+    buildSkillsAppendix() {
+        if (!this.opts.skills || this.opts.skills.length === 0)
+            return undefined;
+        const blocks = this.opts.skills
+            .map((skill) => loadSkillMarkdown(this.opts.cwd, skill))
+            .filter((block) => Boolean(block));
+        if (blocks.length === 0)
+            return undefined;
+        return [
+            "# Preloaded Skills",
+            "Use the following skills for this run.",
+            ...blocks,
+        ].join("\n\n");
+    }
     sendTurn(instruction) {
         if (this._closed)
             return Promise.reject(new Error("builder is closed"));
@@ -158,3 +184,17 @@ export class CodexAdapter {
         return Promise.resolve();
     }
 }
+function loadSkillMarkdown(cwd, skill) {
+    const projectPath = join(cwd, ".agents", "skills", skill, "SKILL.md");
+    if (existsSync(projectPath)) {
+        return `## ${skill}\n${readFileSync(projectPath, "utf8").trim()}`;
+    }
+    try {
+        const bundled = loadSkill(skill);
+        const body = bundled.body?.trim();
+        return body ? `## ${bundled.name}\n${body}` : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/adapters/types.d.ts

@@ -54,6 +54,8 @@ export interface BuilderAdapterOptions {
     effort?: EffortLevel;
     /** Fast mode: lower latency at the cost of some quality. */
     fast?: boolean;
+    /** Codex sandbox mode. Defaults to workspace-write for implementation runs. */
+    sandboxMode?: "workspace-write" | "read-only";
     /** Role system text to append to the harness system prompt (from .rafi/compiled or library). */
     systemPromptAppend?: string;
     /** Skill names to preload for this session (Claude: lazy-loaded; Codex: flattened). */

package/dist/agentRun.d.ts

@@ -0,0 +1,55 @@
+import { type PermissionConfig } from "./config.js";
+import { Log } from "./log.js";
+import { type StepStatus } from "./foreman.js";
+import type { BuilderAdapter, BuilderAdapterOptions, EffortLevel, TurnResult } from "./adapters/types.js";
+import { type RoleBundle } from "./roles.js";
+import type { AgentRuntime } from "./runtimeAuth.js";
+export type { EffortLevel } from "./adapters/types.js";
+export declare const VALID_EFFORT: readonly EffortLevel[];
+export interface RoleBuilderOptions {
+    projectDir: string;
+    role: string;
+    agent?: string;
+    model?: string;
+    effort?: EffortLevel;
+    fast?: boolean;
+    yes?: boolean;
+    allowSwitch?: boolean;
+    label: string;
+    log: Log;
+    permissionConfig?: PermissionConfig;
+    extraSkills?: string[];
+    sandboxMode?: BuilderAdapterOptions["sandboxMode"];
+    resumeSessionId?: string;
+}
+export interface RoleBuilder {
+    builder: BuilderAdapter;
+    runtime: AgentRuntime;
+    model?: string;
+    effort?: EffortLevel;
+    roleBundle: RoleBundle;
+    skills: string[];
+}
+export interface RoleInstructionRunOptions extends Omit<RoleBuilderOptions, "log"> {
+    instruction: string;
+    logPath?: string;
+    logEvent?: "rafi-plan" | "ticket-populate" | "preflight";
+}
+export interface RoleInstructionRunResult {
+    turn: {
+        result: TurnResult;
+        status: StepStatus;
+    };
+    runtime: AgentRuntime;
+    model?: string;
+    effort?: EffortLevel;
+    logPath: string;
+    roleBundle: RoleBundle;
+    skills: string[];
+}
+export declare function assertEffortLevel(effort: string | undefined): asserts effort is EffortLevel | undefined;
+export declare function makeLogPath(projectDir: string, label: string): string;
+export declare function mergeSkills(roleSkills: readonly string[], extraSkills?: readonly string[]): string[];
+export declare function readOnlyPermissionConfig(): PermissionConfig;
+export declare function createRoleBuilder(opts: RoleBuilderOptions): Promise<RoleBuilder>;
+export declare function runRoleInstruction(opts: RoleInstructionRunOptions): Promise<RoleInstructionRunResult>;

package/dist/agentRun.js

@@ -0,0 +1,151 @@
+import { existsSync } 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 { 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";
+export const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
+export function assertEffortLevel(effort) {
+    if (effort && !VALID_EFFORT.includes(effort)) {
+        throw new Error(`unknown effort "${effort}" - choose: ${VALID_EFFORT.join(" | ")}`);
+    }
+}
+export function makeLogPath(projectDir, label) {
+    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+    return join(projectDir, ".foreman", `${stamp}-${label}.jsonl`);
+}
+export function mergeSkills(roleSkills, extraSkills = []) {
+    return [...new Set([...roleSkills, ...extraSkills])];
+}
+export function readOnlyPermissionConfig() {
+    return {
+        allowBash: [
+            "pwd",
+            "ls",
+            "cat ",
+            "sed -n ",
+            "grep ",
+            "rg ",
+            "head ",
+            "tail ",
+            "wc ",
+            "git status",
+            "git diff --stat",
+            "git diff --name-only",
+            "git log --oneline",
+            "git show --stat",
+            "git ls-files",
+            "git grep",
+        ],
+        escalateBash: [
+            ...DEFAULT_CONFIG.permissions.escalateBash,
+            " --output",
+            " -o",
+            " --exec",
+            " --format",
+            "git add",
+            "git commit",
+            "git checkout",
+            "git restore",
+            "git stash",
+            "npm install",
+            "npm run",
+            "npm ci",
+            "pnpm ",
+            "yarn ",
+            "mkdir ",
+            "touch ",
+            "mv ",
+            "cp ",
+            "rm ",
+            "ai-foreman tickets",
+            "foreman tickets",
+        ],
+        strictShellRedirection: true,
+        allowTools: ["Read", "Glob", "Grep", "TodoWrite"],
+        escalateTools: [
+            ...new Set([
+                ...DEFAULT_CONFIG.permissions.escalateTools,
+                "Edit",
+                "Write",
+                "MultiEdit",
+                "NotebookEdit",
+            ]),
+        ],
+    };
+}
+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 config = loadConfig(join(opts.projectDir, "foreman.yaml"));
+    const roleBundle = loadRoleBundle(opts.role, { projectDir: opts.projectDir });
+    const initialModel = opts.model ?? roleBundle.model ?? undefined;
+    const effort = opts.effort ?? roleBundle.effort ?? undefined;
+    const ready = await ensureRuntimeReadyForCommand(opts.projectDir, runtime, {
+        label: opts.label,
+        yes: Boolean(opts.yes),
+        allowSwitch: opts.allowSwitch,
+        model: initialModel,
+    });
+    runtime = ready.runtime;
+    const model = ready.model;
+    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 builder = runtime === "codex"
+        ? new CodexAdapter(adapterOpts)
+        : await ClaudeAdapter.create(adapterOpts);
+    return { builder, runtime, model, effort, roleBundle, skills };
+}
+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({
+        ...opts,
+        log,
+    });
+    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);
+    try {
+        const turn = await foreman.runInstruction(opts.instruction);
+        await builder.close();
+        await viewer;
+        if (opts.logEvent) {
+            log.write(opts.logEvent, {
+                role: opts.role,
+                statusKind: turn.status.kind,
+                summary: turn.status.summary,
+                reason: turn.status.reason,
+                costUsd: turn.result.costUsd,
+                isError: turn.result.isError,
+            });
+        }
+        return { turn, runtime, model, effort, logPath, roleBundle, skills };
+    }
+    catch (err) {
+        await builder.close().catch(() => { });
+        await viewer.catch(() => { });
+        log.write("error", { message: String(err) });
+        throw err;
+    }
+}

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.d.ts

@@ -1,3 +1,17 @@
 import { Command } from "commander";
+import { Log } from "../log.js";
+import type { EffortLevel } from "../adapters/types.js";
+import { type RoleBuilderOptions } from "../agentRun.js";
+import type { TicketsConfig } from "../tickets/config.js";
 export declare function buildPopulateInstruction(sourceHints?: string[], progressDoc?: string): string;
+export declare function resolvePopulateSources(projectDir: string, explicitSources: string[] | undefined, ticketsConfig: TicketsConfig): string[] | undefined;
+export declare function buildPopulateAgentRunOptions(opts: {
+    projectDir: string;
+    agent?: string;
+    model?: string;
+    effort?: EffortLevel;
+    fast?: boolean;
+    yes?: boolean;
+    log: Log;
+}): RoleBuilderOptions;
 export declare function buildTicketsCommand(): Command;

package/dist/cli/tickets.js

@@ -1,19 +1,18 @@
 import { Command } from "commander";
-import { existsSync } from "node:fs";
-import { isAbsolute, join, resolve } from "node:path";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { parse as parseYaml } from "yaml";
 import { select, isCancel } from "@clack/prompts";
 import { loadConfig } 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 { Foreman, createPermissionHandler } from "../foreman.js";
+import { Foreman } from "../foreman.js";
 import { printEvents } from "./events.js";
 import { cmdInit, cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdCancel, cmdDiscover, cmdAcceptFutureWork, cmdReorder, cmdRender, cmdValidate, cmdQueue, cmdArchive, } from "../tickets/commands.js";
 import { isTicketsInitialized, loadTicketsConfig } from "../tickets/config.js";
+import { validateDocsRoot } from "../tickets/config.js";
 import { importFromMarkdown } from "../tickets/importer.js";
 import { formatValidationIssues } from "../tickets/validate.js";
-import { ensureRuntimeReadyForCommand } from "./runtimeAuthPrompt.js";
+import { assertEffortLevel, createRoleBuilder, makeLogPath, } from "../agentRun.js";
 function fail(msg) {
     console.error(`foreman tickets: ${msg}`);
     process.exit(1);
@@ -21,21 +20,18 @@ 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 unique(values) {
+    return [...new Set(values)];
 }
+const TICKET_POPULATE_ROLE = "ticket-maker";
+const RAFI_CONFIG_FILES = ["rafi-config.yaml", "project.yaml"];
 function validateEffort(effort) {
-    if (effort && !VALID_EFFORT.includes(effort)) {
-        fail(`unknown effort "${effort}" — choose: ${VALID_EFFORT.join(" | ")}`);
+    try {
+        assertEffortLevel(effort);
+    }
+    catch (err) {
+        fail(err instanceof Error ? err.message : String(err));
     }
-}
-function makeLogPath(projectDir, label) {
-    const stamp = new Date().toISOString().replace(/[:.]/g, "-");
-    return join(projectDir, ".foreman", `${stamp}-${label}.jsonl`);
 }
 export function buildPopulateInstruction(sourceHints, progressDoc = "docs/ticket-progress.md") {
     const sources = sourceHints ?? [];
@@ -86,6 +82,49 @@ STEP_STATUS: done | summary="populated Foreman tickets from existing project tic
 or
 STEP_STATUS: blocked | reason="why ticket population cannot proceed"`;
 }
+export function resolvePopulateSources(projectDir, explicitSources, ticketsConfig) {
+    if (explicitSources && explicitSources.length > 0)
+        return explicitSources;
+    const rafiPlan = resolveConfiguredRafiPlanSource(projectDir, "rafi-config.yaml");
+    if (rafiPlan)
+        return [rafiPlan];
+    const legacyPlan = resolveConfiguredRafiPlanSource(projectDir, "project.yaml");
+    if (legacyPlan)
+        return [legacyPlan];
+    const candidates = unique([
+        join(dirname(ticketsConfig.paths.progressDoc), "rafi-plan.md"),
+        "docs/rafi-plan.md",
+    ]);
+    const plan = candidates.find((candidate) => existsSync(join(projectDir, candidate)));
+    return plan ? [plan] : undefined;
+}
+function resolveConfiguredRafiPlanSource(projectDir, file) {
+    const configPath = join(projectDir, file);
+    if (!existsSync(configPath))
+        return undefined;
+    const raw = parseYaml(readFileSync(configPath, "utf8"));
+    if (!raw || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new Error(`${file}: expected a YAML object`);
+    }
+    const docs = raw.docs;
+    if (typeof docs?.root !== "string")
+        return undefined;
+    const candidate = `${validateDocsRoot(projectDir, docs.root)}/rafi-plan.md`;
+    return existsSync(join(projectDir, candidate)) ? candidate : undefined;
+}
+export function buildPopulateAgentRunOptions(opts) {
+    return {
+        projectDir: opts.projectDir,
+        role: TICKET_POPULATE_ROLE,
+        agent: opts.agent,
+        model: opts.model,
+        effort: opts.effort,
+        fast: opts.fast,
+        yes: opts.yes,
+        label: "tickets populate",
+        log: opts.log,
+    };
+}
 export function buildTicketsCommand() {
     const tickets = new Command("tickets").description("Manage the structured ticket tracker for a project.");
     // ── init ────────────────────────────────────────────────────────────────────
@@ -116,9 +155,9 @@ export function buildTicketsCommand() {
     // ── populate ────────────────────────────────────────────────────────────────
     tickets
         .command("populate")
-        .description("Ask a builder to populate .tickets/tickets.yaml from existing project ticket/backlog docs.")
+        .description("Ask the ticket-maker role 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,8 +165,6 @@ 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}`);
@@ -147,29 +184,34 @@ export function buildTicketsCommand() {
                 process.exit(0);
             }
         }
-        const config = loadConfig(join(dir, "foreman.yaml"));
         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 adapterOpts = {
-            cwd: dir,
-            model: opts.model,
-            permission: createPermissionHandler(policy, log),
-            effort: opts.effort,
-            fast: opts.fast,
-        };
-        const builder = agent === "codex"
-            ? new CodexAdapter(adapterOpts)
-            : await ClaudeAdapter.create(adapterOpts);
-        const viewer = printEvents(builder.events());
-        const foreman = new Foreman(builder, log, config.notifications.enabled, false, 3, dir);
-        console.log(`foreman tickets: populating tickets with ${agent}`);
-        console.log(`foreman tickets: project ${dir}`);
-        console.log(`foreman tickets: log ${logPath}\n`);
+        const config = loadConfig(join(dir, "foreman.yaml"));
+        let builder;
+        let viewer;
         try {
+            const roleBuilder = await createRoleBuilder(buildPopulateAgentRunOptions({
+                projectDir: dir,
+                agent: opts.agent,
+                model: opts.model,
+                effort: opts.effort,
+                fast: opts.fast,
+                yes: Boolean(opts.yes),
+                log,
+            }));
+            builder = roleBuilder.builder;
+            viewer = printEvents(builder.events());
+            const foreman = new Foreman(builder, log, config.notifications.enabled, false, 3, dir);
+            console.log(`foreman tickets: populating tickets with ${roleBuilder.runtime}`);
+            console.log(`foreman tickets: project ${dir}`);
+            console.log(`foreman tickets: role ${TICKET_POPULATE_ROLE}`);
+            console.log(`foreman tickets: log ${logPath}\n`);
             const ticketsConfig = loadTicketsConfig(dir);
-            const turn = await foreman.runInstruction(buildPopulateInstruction(opts.sources, ticketsConfig.paths.progressDoc));
+            const sourceHints = resolvePopulateSources(dir, opts.sources, ticketsConfig);
+            if (sourceHints?.length) {
+                console.log(`foreman tickets: source hints ${sourceHints.join(" ")}`);
+            }
+            const turn = await foreman.runInstruction(buildPopulateInstruction(sourceHints, ticketsConfig.paths.progressDoc));
             await builder.close();
             await viewer;
             log.write("ticket-populate", {
@@ -204,7 +246,8 @@ export function buildTicketsCommand() {
             console.log(`foreman tickets: populated .tickets/tickets.yaml and rendered ${ticketsConfig.paths.progressDoc}`);
         }
         catch (err) {
-            await builder.close().catch(() => { });
+            await builder?.close().catch(() => { });
+            await viewer?.catch(() => { });
             fail(String(err instanceof Error ? err.message : err));
         }
     });

package/dist/config.d.ts

@@ -3,6 +3,8 @@ export interface PermissionConfig {
     allowBash: string[];
     /** Bash command substrings that always escalate (checked first). */
     escalateBash: string[];
+    /** Escalate shell redirection even when it is attached to an allowed command. */
+    strictShellRedirection?: boolean;
     /** Tool names auto-approved when their target stays inside the worktree. */
     allowTools: string[];
     /** Tool names that always escalate. */

package/dist/config.js

@@ -98,6 +98,9 @@ function validateConfig(raw, path) {
                 throw new Error(`${path}: permissions.${key} must be an array of strings`);
             }
         }
+        if (permissions.strictShellRedirection !== undefined && typeof permissions.strictShellRedirection !== "boolean") {
+            throw new Error(`${path}: permissions.strictShellRedirection must be a boolean`);
+        }
     }
     if (cfg.notifications !== undefined) {
         validateBooleanObject(cfg.notifications, "notifications", path);

package/dist/log.d.ts

@@ -1,7 +1,7 @@
 /** A single structured log record. */
 export interface LogRecord {
     ts: string;
-    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "ticket-populate" | "qa" | "qa-fix" | "error";
+    event: "batch-start" | "batch-end" | "branch-plan" | "branch-start" | "branch-session" | "branch-resume" | "branch-issue" | "branch-complete" | "branch-push" | "github-readiness-failed" | "pr-created" | "pr-existing" | "pr-failed" | "step" | "permission" | "escalation" | "needs_input" | "preflight" | "rafi-plan" | "ticket-populate" | "qa" | "qa-fix" | "error";
     [key: string]: unknown;
 }
 /** Append-only JSONL logger. One line per record, plus an echo to the console. */

package/dist/permissions/policy.js

@@ -4,10 +4,12 @@ const FILE_TOOLS = new Set(["Edit", "Write", "MultiEdit", "NotebookEdit"]);
 /** Shell operators we split on to vet each segment of a chained command. */
 const SHELL_SPLIT = /\s*(?:&&|\|\||;|\|)\s*/;
 /** Shell features that make a prefix allow-list too easy to bypass. */
-const ESCALATE_SHELL_SYNTAX = [
-    { pattern: /\s\d?>|\s>>|\s</, reason: "shell redirection is not auto-approved" },
-    { pattern: /\$\(|`/, reason: "shell substitution is not auto-approved" },
-];
+const SHELL_REDIRECTION = {
+    standard: /\s\d?>|\s>>|\s</,
+    strict: /(?:^|[^\\])(?:\d+)?(?:>>?|<<?)/,
+    reason: "shell redirection is not auto-approved",
+};
+const SHELL_SUBSTITUTION = { pattern: /\$\(|`/, reason: "shell substitution is not auto-approved" };
 /**
  * Rules-based permission classifier. No LLM: routine requests are auto-approved,
  * anything risky or unrecognized escalates to the human (fail safe).
@@ -51,7 +53,13 @@ export class PermissionPolicy {
         if (hitEscalate) {
             return { decision: "escalate", reason: `command matches "${hitEscalate}"` };
         }
-        const syntax = ESCALATE_SHELL_SYNTAX.find((s) => s.pattern.test(command));
+        const syntax = [
+            {
+                pattern: this.config.strictShellRedirection ? SHELL_REDIRECTION.strict : SHELL_REDIRECTION.standard,
+                reason: SHELL_REDIRECTION.reason,
+            },
+            SHELL_SUBSTITUTION,
+        ].find((s) => s.pattern.test(command));
         if (syntax) {
             return { decision: "escalate", reason: syntax.reason };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.1.0",
+  "version": "1.3.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,9 +14,13 @@
   },
   "homepage": "https://github.com/ttante/rafi/tree/main/packages/ai-foreman#readme",
   "bin": {
-    "ai-foreman": "./dist/index.js"
+    "ai-foreman": "dist/index.js"
   },
   "exports": {
+    "./agent-run.js": {
+      "types": "./dist/agentRun.d.ts",
+      "default": "./dist/agentRun.js"
+    },
     "./cli/tickets.js": {
       "types": "./dist/cli/tickets.d.ts",
       "default": "./dist/cli/tickets.js"