ai-foreman 1.2.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
@@ -159,7 +160,7 @@ gh repo view <host>/<owner>/<repo>
 | `-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. |
 
@@ -283,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:
 
@@ -297,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
@@ -308,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
@@ -535,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/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,20 +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 { resolveAgentForProject } from "./runtimeSelection.js";
+import { assertEffortLevel, createRoleBuilder, makeLogPath, } from "../agentRun.js";
 function fail(msg) {
     console.error(`foreman tickets: ${msg}`);
     process.exit(1);
@@ -22,15 +20,18 @@ function fail(msg) {
 function cwd(opts) {
     return resolve(opts.project ?? ".");
 }
-const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
+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 ?? [];
@@ -81,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 ────────────────────────────────────────────────────────────────────
@@ -111,7 +155,7 @@ 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)")
         .option("-m, --model <model>", "override the builder's model")
@@ -124,14 +168,6 @@ export function buildTicketsCommand() {
         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`);
         }
@@ -148,35 +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);
-        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,
-            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", {
@@ -211,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.2.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",
@@ -17,6 +17,10 @@
     "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"