ai-foreman 1.2.0 → 1.3.1

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. |
 
@@ -257,11 +258,15 @@ Init options:
 | `-p, --project <dir>` | `./my-project` / `../repo` | current directory | Project to initialize. |
 | `--app-name <name>` | `"My App"` | none | Application name stored in tracker config. |
 | `--timezone <tz>` | `America/Chicago` / `UTC` | `UTC` | IANA timezone. |
-| `--queue-limit <n>` | `25` / `50` / `100` | `50` | Next-queue window size. |
+| `--implementation-limit <n>` | `250` / `500` / `1000` | `500` | Implementation queue window for generated docs and Foreman selection. |
+| `--view-limit <n>` | `1000` / `20000` | `20000` | Default row limit for the display queue command. |
+| `--queue-limit <n>` | `250` / `500` / `1000` | none | Deprecated alias for `--implementation-limit`. |
 | `--docs-root <dir>` | `docs` / `docs-rafi` | `rafi-config.yaml` docs.root, then `docs` | Root for generated progress/archive docs. |
 
 `tickets init` reads `docs.root` from `rafi-config.yaml` when present. `--docs-root` overrides that value. The selected root must be a safe repo-relative directory, and init refuses to overwrite an existing selected `ticket-progress.md`.
 
+Init writes `implementation_limit` and `view_limit` to `.tickets/config.yaml`. Existing configs with `queue_limit` still load as an implementation limit, with the old default value `50` upgraded to `500`.
+
 This creates:
 
 ```txt
@@ -283,7 +288,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 +302,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 +314,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 +542,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 { DEFAULT_TICKETS_CONFIG, 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,22 @@ function fail(msg) {
 function cwd(opts) {
     return resolve(opts.project ?? ".");
 }
-const VALID_EFFORT = ["low", "medium", "high", "xhigh"];
+function unique(values) {
+    return [...new Set(values)];
+}
+function optionWasProvided(command, name) {
+    const source = command.getOptionValueSource(name);
+    return source !== undefined && source !== "default";
+}
+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 +86,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 ────────────────────────────────────────────────────────────────────
@@ -90,15 +138,24 @@ export function buildTicketsCommand() {
         .option("-p, --project <dir>", "project directory (default: cwd)")
         .option("--app-name <name>", "application name")
         .option("--timezone <tz>", "IANA timezone (e.g. America/Chicago)", "UTC")
-        .option("--queue-limit <n>", "next-queue window size", "50")
+        .option("--implementation-limit <n>", "implementation queue window size", String(DEFAULT_TICKETS_CONFIG.implementationLimit))
+        .option("--view-limit <n>", "ticket queue display limit", String(DEFAULT_TICKETS_CONFIG.viewLimit))
+        .option("--queue-limit <n>", "deprecated alias for --implementation-limit")
         .option("--docs-root <dir>", "repo-relative directory for generated ticket docs")
-        .action((opts) => {
+        .action((opts, command) => {
         const dir = cwd(opts);
         try {
+            const hasImplementationLimit = optionWasProvided(command, "implementationLimit");
+            const hasLegacyQueueLimit = optionWasProvided(command, "queueLimit");
+            if (hasImplementationLimit && hasLegacyQueueLimit) {
+                fail("--implementation-limit and deprecated --queue-limit cannot both be passed");
+            }
             cmdInit(dir, {
                 appName: opts.appName,
                 timezone: opts.timezone,
-                queueLimit: Number(opts.queueLimit),
+                implementationLimit: hasImplementationLimit ? Number(opts.implementationLimit) : undefined,
+                viewLimit: optionWasProvided(command, "viewLimit") ? Number(opts.viewLimit) : undefined,
+                queueLimit: hasLegacyQueueLimit ? Number(opts.queueLimit) : undefined,
                 docsRoot: opts.docsRoot,
             });
             console.log(`foreman tickets: initialized .tickets/ in ${dir}`);
@@ -111,7 +168,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 +181,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 +197,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 +259,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));
         }
     });
@@ -453,12 +502,12 @@ export function buildTicketsCommand() {
     // ── queue ─────────────────────────────────────────────────────────────────────
     tickets
         .command("queue")
-        .description("Print the next-N queue to stdout.")
+        .description("Print the ticket queue to stdout.")
         .option("-p, --project <dir>", "project directory (default: cwd)")
-        .option("--limit <n>", "override queue limit")
+        .option("--limit <n>", "override view limit")
         .action((opts) => {
         try {
-            const rows = cmdQueue(cwd(opts), opts.limit ? Number(opts.limit) : undefined);
+            const rows = cmdQueue(cwd(opts), opts.limit !== undefined ? Number(opts.limit) : undefined);
             if (rows.length === 0) {
                 console.log("No remaining tickets.");
             }

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

@@ -2,7 +2,7 @@ import { select, isCancel } from "@clack/prompts";
 import { MARKER_SPEC, QA_MARKER_SPEC } from "./markers.js";
 import { fireNotification } from "./notify.js";
 import { isTicketsInitialized } from "./tickets/config.js";
-import { cmdUpdate, cmdComplete, cmdBlock, cmdQueue } from "./tickets/commands.js";
+import { cmdUpdate, cmdComplete, cmdBlock, cmdImplementationQueue } from "./tickets/commands.js";
 /** Phrases that suggest the builder ended its turn by asking the human. */
 const QUESTION_HINTS = [
     "should i",
@@ -324,7 +324,7 @@ export class Foreman {
             let pendingTicketId;
             if (this.ticketsEnabled && this.projectDir) {
                 try {
-                    const queue = cmdQueue(this.projectDir);
+                    const queue = cmdImplementationQueue(this.projectDir);
                     const next = queue.find((r) => r.status === "next");
                     if (next) {
                         pendingTicketId = next.ticket;

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/dist/tickets/commands.d.ts

@@ -14,6 +14,9 @@ export declare function openContext(projectDir: string): TicketContext;
 export interface InitOptions {
     appName?: string;
     timezone?: string;
+    implementationLimit?: number;
+    viewLimit?: number;
+    /** @deprecated Use implementationLimit. */
     queueLimit?: number;
     docsRoot?: string;
 }
@@ -85,6 +88,7 @@ export interface ValidateResult {
 }
 export declare function cmdValidate(projectDir: string): ValidateResult;
 export declare function cmdQueue(projectDir: string, limit?: number): import("./queue.js").QueueRow[];
+export declare function cmdImplementationQueue(projectDir: string): import("./queue.js").QueueRow[];
 export declare function cmdArchive(projectDir: string, _opts: {
     olderThanDays?: number;
 }): void;

package/dist/tickets/commands.js

@@ -1,7 +1,7 @@
 import { mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { stringify } from "yaml";
-import { initDocsRoot, loadTicketsConfig, pathExistsOrSymlink, resolveTicketPaths, isTicketsInitialized, } from "./config.js";
+import { DEFAULT_TICKETS_CONFIG, initDocsRoot, loadTicketsConfig, pathExistsOrSymlink, resolveTicketPaths, isTicketsInitialized, } from "./config.js";
 import { loadTickets, saveTickets } from "./ticketLoader.js";
 import { StateDb } from "./stateDb.js";
 import { nowTimestamp, logEvent } from "./events.js";
@@ -32,6 +32,9 @@ export function cmdInit(projectDir, opts) {
     if (isTicketsInitialized(projectDir)) {
         throw new Error(".tickets/config.yaml already exists — already initialized.");
     }
+    if (opts.implementationLimit !== undefined && opts.queueLimit !== undefined) {
+        throw new Error("--implementation-limit and deprecated --queue-limit cannot both be set");
+    }
     const ticketsDir = join(projectDir, ".tickets");
     const docsRoot = initDocsRoot(projectDir, opts.docsRoot);
     const progressDoc = `${docsRoot}/ticket-progress.md`;
@@ -46,7 +49,8 @@ export function cmdInit(projectDir, opts) {
     mkdirSync(join(projectDir, docsRoot), { recursive: true });
     const config = {
         app_name: opts.appName ?? "My App",
-        queue_limit: opts.queueLimit ?? 50,
+        implementation_limit: opts.implementationLimit ?? opts.queueLimit ?? DEFAULT_TICKETS_CONFIG.implementationLimit,
+        view_limit: opts.viewLimit ?? DEFAULT_TICKETS_CONFIG.viewLimit,
         timezone: opts.timezone ?? "UTC",
         timestamp_format: "iso8601_offset",
         paths: {
@@ -424,7 +428,13 @@ export function cmdValidate(projectDir) {
 export function cmdQueue(projectDir, limit) {
     return withContext(projectDir, (ctx) => {
         const states = ctx.db.getAllStates();
-        return buildNextQueue(ctx.tickets, states, limit ?? ctx.config.queueLimit);
+        return buildNextQueue(ctx.tickets, states, limit ?? ctx.config.viewLimit);
+    });
+}
+export function cmdImplementationQueue(projectDir) {
+    return withContext(projectDir, (ctx) => {
+        const states = ctx.db.getAllStates();
+        return buildNextQueue(ctx.tickets, states, ctx.config.implementationLimit);
     });
 }
 // ── archive ───────────────────────────────────────────────────────────────────

package/dist/tickets/config.d.ts

@@ -22,7 +22,8 @@ export interface TicketsBehavior {
 }
 export interface TicketsConfig {
     appName: string;
-    queueLimit: number;
+    implementationLimit: number;
+    viewLimit: number;
     timezone: string;
     paths: TicketsPaths;
     rendering: TicketsRendering;

package/dist/tickets/config.js

@@ -3,7 +3,8 @@ import { dirname, isAbsolute, join, normalize, relative, resolve } from "node:pa
 import { parse } from "yaml";
 export const DEFAULT_TICKETS_CONFIG = {
     appName: "My App",
-    queueLimit: 50,
+    implementationLimit: 500,
+    viewLimit: 20_000,
     timezone: "UTC",
     paths: {
         tickets: ".tickets/tickets.yaml",
@@ -126,7 +127,8 @@ export function loadTicketsConfig(projectDir) {
     assertPlainObject(raw.behavior, "behavior", configPath);
     const config = {
         appName: raw.app_name ?? DEFAULT_TICKETS_CONFIG.appName,
-        queueLimit: raw.queue_limit ?? DEFAULT_TICKETS_CONFIG.queueLimit,
+        implementationLimit: resolveImplementationLimit(raw),
+        viewLimit: raw.view_limit ?? DEFAULT_TICKETS_CONFIG.viewLimit,
         timezone: raw.timezone ?? DEFAULT_TICKETS_CONFIG.timezone,
         paths: {
             ...DEFAULT_TICKETS_CONFIG.paths,
@@ -144,6 +146,17 @@ export function loadTicketsConfig(projectDir) {
     validateTicketsConfig(config, configPath);
     return config;
 }
+function resolveImplementationLimit(raw) {
+    if (raw.implementation_limit !== undefined) {
+        return raw.implementation_limit;
+    }
+    if (raw.queue_limit !== undefined) {
+        return raw.queue_limit === 50
+            ? DEFAULT_TICKETS_CONFIG.implementationLimit
+            : raw.queue_limit;
+    }
+    return DEFAULT_TICKETS_CONFIG.implementationLimit;
+}
 function assertPlainObject(value, name, configPath) {
     if (value !== undefined && (!value || typeof value !== "object" || Array.isArray(value))) {
         throw new Error(`${configPath}: ${name} must be an object`);
@@ -153,8 +166,11 @@ function validateTicketsConfig(config, configPath) {
     if (!config.appName || typeof config.appName !== "string") {
         throw new Error(`${configPath}: app_name must be a non-empty string`);
     }
-    if (!Number.isInteger(config.queueLimit) || config.queueLimit < 1) {
-        throw new Error(`${configPath}: queue_limit must be a positive integer`);
+    if (!Number.isInteger(config.implementationLimit) || config.implementationLimit < 1) {
+        throw new Error(`${configPath}: implementation_limit must be a positive integer`);
+    }
+    if (!Number.isInteger(config.viewLimit) || config.viewLimit < 1) {
+        throw new Error(`${configPath}: view_limit must be a positive integer`);
     }
     if (!config.timezone || typeof config.timezone !== "string") {
         throw new Error(`${configPath}: timezone must be a non-empty IANA timezone string`);

package/dist/tickets/renderMarkdown.js

@@ -59,7 +59,7 @@ export const DEFAULT_TRACKER_RULES = renderTrackerRules();
 export function renderProgressDoc(input) {
     const { config, projectDir, ticketDefs, states, db } = input;
     const now = input.now ?? DateTime.now().setZone(config.timezone).toISO();
-    const queueRows = buildNextQueue(ticketDefs, states, config.queueLimit);
+    const queueRows = buildNextQueue(ticketDefs, states, config.implementationLimit);
     const activeRows = buildActiveStatusRows(queueRows, ticketDefs, states);
     const futureWork = db.getFutureWork();
     const recentEvents = db.getRecentEvents(config.rendering.maxWorkLogRows);
@@ -82,7 +82,8 @@ export function renderProgressDoc(input) {
     lines.push("## Tracker Metadata");
     lines.push(section("TRACKER_METADATA", table(["Field", "Value"], [
         ["App", config.appName],
-        ["Queue Limit", String(config.queueLimit)],
+        ["Implementation Limit", String(config.implementationLimit)],
+        ["View Limit", String(config.viewLimit)],
         ["Timezone", config.timezone],
         ["Generated At", now],
         ["Remaining Tickets", String(queueRows.length > 0 ? "≥" + queueRows.length : "0")],

package/dist/tickets/validate.js

@@ -25,12 +25,12 @@ export function runAllValidation(config, projectDir, ticketDefs, states, db) {
         }
     }
     // Pass 3: queue validation
-    const queueRows = buildNextQueue(ticketDefs, states, config.queueLimit);
+    const queueRows = buildNextQueue(ticketDefs, states, config.implementationLimit);
     const remaining = ticketDefs.filter((t) => {
         const s = states.get(t.id);
         return s?.status !== "done" && s?.status !== "canceled";
     });
-    const expectedLen = Math.min(config.queueLimit, remaining.length);
+    const expectedLen = Math.min(config.implementationLimit, remaining.length);
     if (queueRows.length !== expectedLen) {
         issues.push({ pass: 3, severity: "error", message: `[queue] expected ${expectedLen} rows, got ${queueRows.length}` });
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-foreman",
-  "version": "1.2.0",
+  "version": "1.3.1",
   "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"