ai-foreman 1.0.8 → 1.0.10

package/README.md

@@ -75,6 +75,7 @@ What each part does:
 - TODOs
 - roadmap docs
 - ticket files
+- folders or globs containing planning notes
 
 ## Primary Options
 
@@ -112,6 +113,7 @@ Resume rule:
 | `-a, --agent <agent>` | `claude` / `codex` | `claude` | Builder agent. |
 | `-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. |
 | `--fast` | flag | off | Lower latency. |
 | `-y, --yes` | flag | off | Skips confirmation before builder edits ticket files. |
 
@@ -143,12 +145,14 @@ Claude Code:
 - Default agent.
 - 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.
 
 Codex:
 
 - Use `--agent codex`.
 - 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.
 
 Task file:
 
@@ -229,10 +233,12 @@ Supported source material can include:
 - TODOs
 - roadmap docs
 - Markdown trackers
+- folders or globs containing planning notes
 
 ```bash
 # Claude Code
 ai-foreman tickets populate --project ./my-project
+ai-foreman tickets populate --project ./my-project --sources docs/tickets.md docs/plans/**
 
 # Codex
 ai-foreman tickets populate --project ./my-project --agent codex
@@ -518,6 +524,3 @@ Package output:
 - **`@rafi-ai/cli`** — CLI for `rafi create` and `rafi compile`
 
 
-
-
-

package/dist/adapters/claude.js

@@ -11,6 +11,7 @@ export async function requireClaudeSDK() {
     }
 }
 import { AsyncQueue } from "../util/asyncQueue.js";
+import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 /**
  * Pure function: build the `options` object passed to `query()`.
  * Extracted so tests can assert on the shape without making a live SDK call.
@@ -50,8 +51,14 @@ export class ClaudeAdapter {
     pending;
     closed = false;
     static async create(opts) {
-        const { query } = await requireClaudeSDK();
-        return new ClaudeAdapter(opts, query);
+        try {
+            const { query } = await requireClaudeSDK();
+            return new ClaudeAdapter(opts, query);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            throw new Error(normalizeRuntimeErrorText("claude", message, null, "adapter startup"), { cause: err });
+        }
     }
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     constructor(opts, query) {
@@ -83,7 +90,8 @@ export class ClaudeAdapter {
                 (err instanceof Error &&
                     (err.name === "AbortError" || err.message.includes("aborted")));
             if (!isShutdownAbort) {
-                const message = err instanceof Error ? err.message : String(err);
+                const rawMessage = err instanceof Error ? err.message : String(err);
+                const message = normalizeRuntimeErrorText("claude", rawMessage, null, "builder stream");
                 this.eventQueue.push({ kind: "error", message });
                 this.pending?.reject(new Error(message));
                 this.pending = undefined;
@@ -118,7 +126,9 @@ export class ClaudeAdapter {
                     ? msg.errors.join("; ")
                     : "";
             const result = {
-                text,
+                text: msg.is_error
+                    ? normalizeRuntimeErrorText("claude", text, null, "builder turn")
+                    : text,
                 isError: msg.is_error,
                 numTurns: msg.num_turns,
                 costUsd: msg.total_cost_usd,

package/dist/adapters/codex.js

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
 import { createInterface } from "node:readline";
 import { AsyncQueue } from "../util/asyncQueue.js";
+import { normalizeRuntimeErrorText } from "../runtimeAuth.js";
 /**
  * Pure function: parse one JSONL event from `codex exec --json` output into
  * structured actions. Exported for unit testing; production code calls this
@@ -122,6 +123,9 @@ export class CodexAdapter {
                 if (!text && code !== 0) {
                     text = Buffer.concat(stderrChunks).toString().trim();
                 }
+                if (code !== 0) {
+                    text = normalizeRuntimeErrorText("codex", text, code, "builder turn");
+                }
                 const result = {
                     text,
                     isError: code !== 0,

package/dist/cli/runtimeAuthPrompt.d.ts

@@ -0,0 +1,2 @@
+import { type AgentRuntime } from "../runtimeAuth.js";
+export declare function ensureRuntimeReadyForCommand(projectDir: string, runtime: AgentRuntime, label: string): Promise<void>;

package/dist/cli/runtimeAuthPrompt.js

@@ -0,0 +1,27 @@
+import { select, isCancel, log } from "@clack/prompts";
+import { checkRuntimeReady, RuntimeAuthError, runtimeCommandLabel, } from "../runtimeAuth.js";
+export async function ensureRuntimeReadyForCommand(projectDir, runtime, label) {
+    while (true) {
+        try {
+            checkRuntimeReady(projectDir, runtime);
+            return;
+        }
+        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") {
+                console.log("foreman: cancelled");
+                process.exit(0);
+            }
+        }
+    }
+}

package/dist/cli/start.js

@@ -10,6 +10,7 @@ import { CodexAdapter } from "../adapters/codex.js";
 import { Foreman, createPermissionHandler } from "../foreman.js";
 import { printEvents } from "./events.js";
 import { loadRoleBundle } from "../roles.js";
+import { ensureRuntimeReadyForCommand } from "./runtimeAuthPrompt.js";
 function fail(message) {
     console.error(`foreman: ${message}`);
     process.exit(1);
@@ -94,6 +95,8 @@ export function buildStartCommand() {
         const logPath = join(cwd, ".foreman", `${stamp}.jsonl`);
         const log = new Log(logPath);
         const policy = new PermissionPolicy(config.permissions, cwd);
+        const agent = opts.agent;
+        await ensureRuntimeReadyForCommand(cwd, agent, "start");
         const roleBundle = loadRoleBundle("builder", { projectDir: cwd });
         const adapterOpts = {
             cwd,
@@ -105,7 +108,7 @@ export function buildStartCommand() {
             systemPromptAppend: roleBundle.system || undefined,
             skills: roleBundle.skills.length > 0 ? roleBundle.skills : undefined,
         };
-        const builder = opts.agent === "codex"
+        const builder = agent === "codex"
             ? new CodexAdapter(adapterOpts)
             : await ClaudeAdapter.create(adapterOpts);
         const qaEnabled = opts.qa !== false && config.qa.enabled !== false;
@@ -116,7 +119,7 @@ export function buildStartCommand() {
             opts.fast ? "fast" : null,
             qaEnabled ? null : "qa=off",
         ].filter(Boolean).join(" ");
-        console.log(`foreman: driving a ${opts.agent} builder through ${steps} step(s)${modifiers ? ` [${modifiers}]` : ""}`);
+        console.log(`foreman: driving a ${agent} builder through ${steps} step(s)${modifiers ? ` [${modifiers}]` : ""}`);
         console.log(`foreman: project ${cwd}`);
         if (trackerRelPath)
             console.log(`foreman: tracker ${trackerRelPath}`);

package/dist/cli/tickets.d.ts

@@ -1,3 +1,3 @@
 import { Command } from "commander";
-export declare function buildPopulateInstruction(): string;
+export declare function buildPopulateInstruction(sourceHints?: string[]): string;
 export declare function buildTicketsCommand(): Command;

package/dist/cli/tickets.js

@@ -13,6 +13,7 @@ import { cmdInit, cmdUpdate, cmdComplete, cmdBlock, cmdUnblock, cmdCancel, cmdDi
 import { isTicketsInitialized } from "../tickets/config.js";
 import { importFromMarkdown } from "../tickets/importer.js";
 import { formatValidationIssues } from "../tickets/validate.js";
+import { ensureRuntimeReadyForCommand } from "./runtimeAuthPrompt.js";
 function fail(msg) {
     console.error(`foreman tickets: ${msg}`);
     process.exit(1);
@@ -36,14 +37,26 @@ function makeLogPath(projectDir, label) {
     const stamp = new Date().toISOString().replace(/[:.]/g, "-");
     return join(projectDir, ".foreman", `${stamp}-${label}.jsonl`);
 }
-export function buildPopulateInstruction() {
+export function buildPopulateInstruction(sourceHints) {
+    const sources = sourceHints ?? [];
+    const sourceHintBlock = sources.length > 0
+        ? `
+User-provided planning source hints:
+${sources.map((source) => `- ${source}`).join("\n")}
+
+Treat these as files, folders, or globs to check first. Any reasonable project-planning format is acceptable because you are responsible for interpreting it. If a hinted source does not exist or is ambiguous, continue scanning the repository before asking for help.
+`
+        : `
+No specific planning sources were provided. Scan the repository for relevant planning and ticketing documents.
+`;
     return `You are being run by Foreman to populate this repository's Foreman ticket tracker.
 
 Goal:
 - Convert every existing project ticket, task, backlog item, roadmap item, or implementation step into Foreman's structured ticket system.
 - Do not implement product/code changes. Only update ticket-tracker files.
+${sourceHintBlock}
 
-Read these files first:
+Before editing, read these tracker control files:
 - .tickets/config.yaml
 - .tickets/tickets.yaml
 - .tickets/tracker-rules.md
@@ -106,6 +119,7 @@ export function buildTicketsCommand() {
         .option("-a, --agent <agent>", "builder agent (claude | codex)", "claude")
         .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")
         .option("--fast", "fast mode - lower latency")
         .option("-y, --yes", "skip confirmation prompt before letting the builder edit tickets")
         .action(async (opts) => {
@@ -135,6 +149,7 @@ export function buildTicketsCommand() {
         const logPath = makeLogPath(dir, "tickets-populate");
         const log = new Log(logPath);
         const policy = new PermissionPolicy(config.permissions, dir);
+        await ensureRuntimeReadyForCommand(dir, agent, "tickets populate");
         const adapterOpts = {
             cwd: dir,
             model: opts.model,
@@ -151,7 +166,7 @@ export function buildTicketsCommand() {
         console.log(`foreman tickets: project ${dir}`);
         console.log(`foreman tickets: log ${logPath}\n`);
         try {
-            const turn = await foreman.runInstruction(buildPopulateInstruction());
+            const turn = await foreman.runInstruction(buildPopulateInstruction(opts.sources));
             await builder.close();
             await viewer;
             log.write("ticket-populate", {

package/dist/runtimeAuth.d.ts

@@ -0,0 +1,23 @@
+export type AgentRuntime = "claude" | "codex";
+export interface RuntimeAuthErrorOptions {
+    runtime: AgentRuntime;
+    context: string;
+    exitCode?: number | null;
+    stdout?: string;
+    stderr?: string;
+    cause?: unknown;
+}
+export declare class RuntimeAuthError extends Error {
+    readonly runtime: AgentRuntime;
+    readonly exitCode?: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly authLikely: boolean;
+    constructor(opts: RuntimeAuthErrorOptions);
+}
+export declare function checkRuntimeReady(projectDir: string, runtime: AgentRuntime): void;
+export declare function normalizeRuntimeErrorText(runtime: AgentRuntime, text: string, exitCode?: number | null, context?: string): string;
+export declare function isRuntimeAuthFailure(output: string): boolean;
+export declare function runtimeCommandLabel(runtime: AgentRuntime): string;
+export declare function runtimeRepairCommands(runtime: AgentRuntime): string;
+export declare function formatRuntimeAuthFailure(opts: RuntimeAuthErrorOptions): string;

package/dist/runtimeAuth.js

@@ -0,0 +1,116 @@
+import { execFileSync } from "node:child_process";
+export class RuntimeAuthError extends Error {
+    runtime;
+    exitCode;
+    stdout;
+    stderr;
+    authLikely;
+    constructor(opts) {
+        super(formatRuntimeAuthFailure(opts), { cause: opts.cause });
+        this.name = "RuntimeAuthError";
+        this.runtime = opts.runtime;
+        this.exitCode = opts.exitCode;
+        this.stdout = opts.stdout ?? "";
+        this.stderr = opts.stderr ?? "";
+        this.authLikely = isRuntimeAuthFailure(`${this.stderr}\n${this.stdout}`);
+    }
+}
+export function checkRuntimeReady(projectDir, runtime) {
+    try {
+        if (runtime === "claude") {
+            execFileSync("claude", ["-p", "Return exactly OK"], {
+                cwd: projectDir,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        else {
+            execFileSync("codex", ["exec", "-C", projectDir, "Return exactly OK"], {
+                cwd: projectDir,
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+    }
+    catch (err) {
+        const failure = err;
+        throw new RuntimeAuthError({
+            runtime,
+            context: "readiness check",
+            exitCode: failure.status,
+            stdout: outputToString(failure.stdout),
+            stderr: outputToString(failure.stderr),
+            cause: err,
+        });
+    }
+}
+export function normalizeRuntimeErrorText(runtime, text, exitCode, context = "builder turn") {
+    if (!isRuntimeAuthFailure(text))
+        return text;
+    return formatRuntimeAuthFailure({
+        runtime,
+        context,
+        exitCode,
+        stderr: text,
+    });
+}
+export function isRuntimeAuthFailure(output) {
+    return [
+        /\b401\b/i,
+        /invalid authentication credentials/i,
+        /not logged in/i,
+        /login required/i,
+        /unauthenticated/i,
+        /unauthorized/i,
+        /expired[\w\s-]*token/i,
+        /token[\w\s-]*expired/i,
+        /session expired/i,
+        /authentication.*expired/i,
+    ].some((pattern) => pattern.test(output));
+}
+export function runtimeCommandLabel(runtime) {
+    return runtime === "claude" ? "claude -p" : "codex exec";
+}
+export function runtimeRepairCommands(runtime) {
+    if (runtime === "claude") {
+        return [
+            "claude auth logout",
+            "claude auth login --claudeai",
+            'claude -p "Return exactly OK"',
+            "",
+            "Claude subscription users may also need:",
+            "claude setup-token",
+        ].join("\n");
+    }
+    return [
+        "codex login",
+        'codex exec "Return exactly OK"',
+    ].join("\n");
+}
+export function formatRuntimeAuthFailure(opts) {
+    const output = [opts.stderr, opts.stdout].filter(Boolean).join("\n").trim();
+    const exit = opts.exitCode === undefined || opts.exitCode === null ? "unknown" : String(opts.exitCode);
+    const authLine = isRuntimeAuthFailure(output)
+        ? "The runtime output looks like an authentication failure."
+        : "This often means the selected agent runtime is missing or not authenticated.";
+    const details = output ? `\n\nRuntime output:\n${truncateRuntimeOutput(output)}` : "";
+    return (`${runtimeCommandLabel(opts.runtime)} failed during ${opts.context} (exit code ${exit}).\n\n` +
+        `${authLine}\n\n` +
+        "Repair and verify:\n" +
+        indent(runtimeRepairCommands(opts.runtime)) +
+        details);
+}
+function outputToString(value) {
+    if (!value)
+        return "";
+    return Buffer.isBuffer(value) ? value.toString("utf8") : value;
+}
+function truncateRuntimeOutput(output) {
+    const max = 2000;
+    if (output.length <= max)
+        return output;
+    return `${output.slice(0, max).trimEnd()}\n... truncated ...`;
+}
+function indent(value) {
+    return value.split("\n").map((line) => `  ${line}`).join("\n");
+}

package/package.json

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