@yul-labs/agent-relay 0.1.1 → 0.1.2

package/README.md

@@ -103,7 +103,9 @@ prompt ──> spawn agent in a PTY (its real TUI) ──> watch terminal output
    Codex with `-s workspace-write -a never`. The agent rarely asks — but the
    prompts that *still* appear (the directory-trust dialog, the occasional choice)
    are what the Decider answers. `approvalPolicy: "gated"` makes the agent ask
-   more (Claude `--permission-mode acceptEdits`, Codex `-a on-request`);
+   more — and routes those asks to the Decider — via Claude `--permission-mode
+   default` (its normal "ask before each edit/command" mode; **not** `acceptEdits`,
+   which would silently auto-approve edits) and Codex `-a on-request`;
    `"readonly"` sandboxes it (Claude `--permission-mode plan`, Codex `-s read-only`).
 2. When the terminal goes idle, agent-relay strips ANSI and **detects** a prompt:
    a numbered/▶ **menu** (single choice), a **multi-select** menu (checkboxes
@@ -144,6 +146,31 @@ arg of the keymap, so a TUI that submits with Enter-on-a-Next-row can be retuned
 The `rule` decider keeps the current selection and submits (no judgment); an LLM
 decider picks the task-relevant rows.
 
+### Getting a result back (what you can and can't read)
+
+agent-relay's job is to **drive** the agent and **answer its prompts** — not to
+recover the agent's prose answer from the screen. The TUI text is heavily mangled
+after ANSI stripping (words run together, spinners interleave), so **scraping a
+structured answer out of stdout is not reliable** and is deliberately not
+attempted. Two things you *can* rely on:
+
+- **For a structured result, have the agent WRITE IT TO A FILE.** Put it in the
+  prompt — e.g. *"...and write the final JSON to `result.json`"* — then read that
+  file after the run. This is the validated pattern for getting data back out.
+- **Token usage is surfaced** as `result.meta.usage`, read from the agent's OWN
+  session transcript (`~/.claude/projects/…` for Claude, `~/.codex/sessions/…` for
+  Codex) — so it works on every machine **regardless of TUI / status-line
+  settings**, and the token counts are the API's real numbers, not a scrape.
+  Fields: `{ source, model, inputTokens, outputTokens, cachedInputTokens,
+  cacheCreationTokens, reasoningTokens, totalTokens }`. `contextPercent` and
+  `sessionCostUsd` are best-effort *extras* scraped from the status line only when
+  it is enabled (cost reads `0` on subscription/Team billing). `source` is
+  `"transcript"` (authoritative) or `"status-line"` (scrape) so you know which.
+
+The proper long-term fix for the *answer text* is the **structured-first** path
+(Claude `--input-format stream-json` / Codex's JSON protocol) — see *Remaining
+TODO*.
+
 ## The Decider
 
 The Decider answers every detected prompt. Choose it in config (`decider`) or

package/dist/cli.js

@@ -1,10 +1,10 @@
 #!/usr/bin/env node
 import { Command } from 'commander';
-import fs6, { promises, constants, statSync, chmodSync } from 'fs';
-import path5 from 'path';
+import fs7, { promises, constants, statSync, chmodSync } from 'fs';
+import path6 from 'path';
 import { z } from 'zod';
-import { execa } from 'execa';
 import os from 'os';
+import { execa } from 'execa';
 import * as nodePty from 'node-pty';
 import { createRequire } from 'module';
 import { randomUUID } from 'crypto';
@@ -185,7 +185,7 @@ ${detail}`,
   return result.data;
 }
 function configPath(rootDir) {
-  return path5.resolve(rootDir, CONFIG_FILENAME);
+  return path6.resolve(rootDir, CONFIG_FILENAME);
 }
 async function loadConfig(rootDir) {
   const file = configPath(rootDir);
@@ -225,7 +225,7 @@ function stringifyConfig(config) {
 }
 async function saveConfig(rootDir, config) {
   const file = configPath(rootDir);
-  await promises.mkdir(path5.dirname(file), { recursive: true });
+  await promises.mkdir(path6.dirname(file), { recursive: true });
   await promises.writeFile(file, stringifyConfig(config), "utf8");
   return file;
 }
@@ -240,7 +240,7 @@ async function dirExists(p) {
   }
 }
 async function runInit(options) {
-  const rootDir = path5.resolve(options.rootDir);
+  const rootDir = path6.resolve(options.rootDir);
   const cfgPath = configPath(rootDir);
   let configCreated = false;
   let configExists = false;
@@ -255,8 +255,8 @@ async function runInit(options) {
     configCreated = true;
   }
   const config = await loadConfig(rootDir);
-  const sessionsDir = path5.resolve(rootDir, config.sessionsDir);
-  const logsDir = path5.resolve(rootDir, config.logsDir);
+  const sessionsDir = path6.resolve(rootDir, config.sessionsDir);
+  const logsDir = path6.resolve(rootDir, config.logsDir);
   const createdDirs = [];
   for (const dir of [sessionsDir, logsDir]) {
     if (!await dirExists(dir)) {
@@ -272,6 +272,100 @@ async function runInit(options) {
     createdDirs
   };
 }
+async function realish(p) {
+  try {
+    return await promises.realpath(p);
+  } catch {
+    return p;
+  }
+}
+function projectDirCandidates(absCwd) {
+  return [absCwd.replace(/[/.]/g, "-"), absCwd.replace(/\//g, "-")];
+}
+async function resolveProjectDir(root, cwd) {
+  const abs = await realish(cwd);
+  for (const name of projectDirCandidates(abs)) {
+    const dir = path6.join(root, name);
+    try {
+      const st = await promises.stat(dir);
+      if (st.isDirectory()) return dir;
+    } catch {
+    }
+  }
+  return void 0;
+}
+async function findLatestClaudeTranscript(opts) {
+  const root = opts.projectsDir ?? path6.join(os.homedir(), ".claude", "projects");
+  const since = opts.sinceMs ?? 0;
+  const dir = await resolveProjectDir(root, opts.cwd);
+  if (!dir) return void 0;
+  let files;
+  try {
+    files = await promises.readdir(dir);
+  } catch {
+    return void 0;
+  }
+  const candidates = [];
+  for (const f of files) {
+    if (!f.endsWith(".jsonl")) continue;
+    const file = path6.join(dir, f);
+    try {
+      const st = await promises.stat(file);
+      if (st.mtimeMs + 2e3 < since) continue;
+      candidates.push({ file, mtimeMs: st.mtimeMs });
+    } catch {
+    }
+  }
+  candidates.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return candidates[0]?.file;
+}
+async function sumClaudeUsage(file) {
+  let text;
+  try {
+    text = await promises.readFile(file, "utf8");
+  } catch {
+    return void 0;
+  }
+  let input = 0;
+  let output = 0;
+  let cacheCreate = 0;
+  let cacheRead = 0;
+  let model;
+  let any = false;
+  for (const line of text.split("\n")) {
+    if (!line.trim()) continue;
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const u = rec.message?.usage;
+    if (!u || typeof u !== "object") continue;
+    any = true;
+    input += u.input_tokens ?? 0;
+    output += u.output_tokens ?? 0;
+    cacheCreate += u.cache_creation_input_tokens ?? 0;
+    cacheRead += u.cache_read_input_tokens ?? 0;
+    if (!model && typeof rec.message?.model === "string")
+      model = rec.message.model;
+  }
+  if (!any) return void 0;
+  return {
+    source: "transcript",
+    model,
+    inputTokens: input,
+    outputTokens: output,
+    cacheCreationTokens: cacheCreate,
+    cachedInputTokens: cacheRead,
+    totalTokens: input + output + cacheCreate + cacheRead
+  };
+}
+async function findLatestClaudeUsage(opts) {
+  const file = await findLatestClaudeTranscript(opts);
+  if (!file) return void 0;
+  return sumClaudeUsage(file);
+}
 
 // src/core/util/json.ts
 function safeJsonParse(text) {
@@ -493,6 +587,7 @@ var CommandDecider = class {
     }
   }
 };
+var MIN_API_MAX_TOKENS = 512;
 var ApiDecider = class {
   constructor(opts) {
     this.opts = opts;
@@ -522,7 +617,7 @@ var ApiDecider = class {
         body: JSON.stringify({
           model: this.opts.model ?? "default",
           messages: [{ role: "user", content: render(req) }],
-          max_tokens: this.opts.maxTokens ?? 2048,
+          max_tokens: Math.max(this.opts.maxTokens ?? 2048, MIN_API_MAX_TOKENS),
           temperature: this.opts.temperature ?? 0,
           stream: false
         }),
@@ -594,8 +689,8 @@ async function isExecutableFile(file) {
 async function which(command) {
   if (!command) return null;
   const exts = pathExtensions();
-  if (command.includes(path5.sep) || command.includes("/")) {
-    const base = path5.resolve(command);
+  if (command.includes(path6.sep) || command.includes("/")) {
+    const base = path6.resolve(command);
     for (const ext of exts) {
       const candidate = base + ext;
       if (await isExecutableFile(candidate)) return candidate;
@@ -603,11 +698,11 @@ async function which(command) {
     return null;
   }
   const pathEnv = process.env.PATH ?? process.env.Path ?? "";
-  const dirs = pathEnv.split(path5.delimiter).filter(Boolean);
-  const fallbacks = process.platform === "win32" ? [] : ["/usr/local/bin", "/opt/homebrew/bin", path5.join(os.homedir(), ".local/bin")];
+  const dirs = pathEnv.split(path6.delimiter).filter(Boolean);
+  const fallbacks = process.platform === "win32" ? [] : ["/usr/local/bin", "/opt/homebrew/bin", path6.join(os.homedir(), ".local/bin")];
   for (const dir of [...dirs, ...fallbacks]) {
     for (const ext of exts) {
-      const candidate = path5.join(dir, command + ext);
+      const candidate = path6.join(dir, command + ext);
       if (await isExecutableFile(candidate)) return candidate;
     }
   }
@@ -733,11 +828,11 @@ function ensurePtyHelperExecutable() {
   if (process.platform === "win32") return;
   try {
     const require2 = createRequire(import.meta.url);
-    const root = path5.dirname(require2.resolve("node-pty/package.json"));
+    const root = path6.dirname(require2.resolve("node-pty/package.json"));
     const candidates = [
-      path5.join(root, "build", "Release", "spawn-helper"),
-      path5.join(root, "build", "Debug", "spawn-helper"),
-      path5.join(
+      path6.join(root, "build", "Release", "spawn-helper"),
+      path6.join(root, "build", "Debug", "spawn-helper"),
+      path6.join(
         root,
         "prebuilds",
         `${process.platform}-${process.arch}`,
@@ -899,6 +994,7 @@ function runPtySession(opts, ctx) {
     let handling = false;
     let quitting = false;
     let settled = false;
+    let usage;
     let finished = false;
     let disposeData;
     let disposeExit;
@@ -994,6 +1090,10 @@ function runPtySession(opts, ctx) {
     };
     const onSettle = async () => {
       if (finished || handling || quitting) return;
+      if (opts.scrapeUsage) {
+        const u = opts.scrapeUsage(cleanTerminalText(buffer));
+        if (u) usage = { ...usage, ...u };
+      }
       if (pendingComment !== void 0) {
         const comment = pendingComment;
         pendingComment = void 0;
@@ -1130,7 +1230,7 @@ function runPtySession(opts, ctx) {
         exitCode,
         error,
         sessionRef: void 0,
-        meta: { interactions, settled }
+        meta: { interactions, settled, ...usage ? { usage } : {} }
       });
     });
     if (ctx.signal.aborted) onAbort();
@@ -1244,6 +1344,7 @@ var InteractivePtyAdapter = class {
         completionPattern: this.cfg.completionPattern,
         completionIdleMs: input.completionIdleMs ?? this.cfg.completionIdleMs,
         workingPattern: this.cfg.workingPattern,
+        scrapeUsage: this.cfg.scrapeUsage,
         quitKeys: this.cfg.quitKeys,
         setup: extra?.setup,
         promptAfterSetup: extra?.promptAfterSetup,
@@ -1261,6 +1362,17 @@ var InteractivePtyAdapter = class {
 };
 
 // src/adapters/interactive/claude-interactive.ts
+function scrapeClaudeStatusLine(text) {
+  const u = { source: "status-line" };
+  const ctx = text.match(/context[^\n]*?(\d{1,3})\s*%/i);
+  if (ctx) {
+    u.contextPercent = Number(ctx[1]);
+    u.raw = ctx[0].trim().replace(/\s+/g, " ");
+  }
+  const cost = text.match(/session\s*\$\s*([\d.]+)/i);
+  if (cost) u.sessionCostUsd = Number(cost[1]);
+  return u.contextPercent !== void 0 || u.sessionCostUsd !== void 0 ? u : void 0;
+}
 var DEFINITION = {
   name: "claude",
   type: "claude",
@@ -1269,6 +1381,9 @@ var DEFINITION = {
   supportsResume: true
 };
 var ClaudeInteractiveAdapter = class _ClaudeInteractiveAdapter extends InteractivePtyAdapter {
+  clock;
+  /** Override the projects root (~/.claude/projects) for tests. */
+  projectsDir;
   constructor(opts = {}) {
     super({
       definition: DEFINITION,
@@ -1285,14 +1400,14 @@ var ClaudeInteractiveAdapter = class _ClaudeInteractiveAdapter extends Interacti
         if (input.approvalMode === "readonly")
           return [...head, "--permission-mode", "plan"];
         if (input.approvalMode === "gated")
-          return [...head, "--permission-mode", "acceptEdits"];
+          return [...head, "--permission-mode", "default"];
         return [...head, "--dangerously-skip-permissions"];
       },
       // Resume the most recent conversation in the cwd and send the follow-up
       // prompt. (`--continue` picks the latest session; the native id is not
       // captured in PTY mode, so a specific `--resume <id>` is not used.)
       resumeArgs: (input) => {
-        const mode = input.approvalMode === "readonly" ? ["--permission-mode", "plan"] : input.approvalMode === "gated" ? ["--permission-mode", "acceptEdits"] : ["--dangerously-skip-permissions"];
+        const mode = input.approvalMode === "readonly" ? ["--permission-mode", "plan"] : input.approvalMode === "gated" ? ["--permission-mode", "default"] : ["--dangerously-skip-permissions"];
         return ["--continue", "--effort", "xhigh", ...mode];
       },
       // Unattended ultracode: once Claude is idle (past the trust dialog), type
@@ -1306,6 +1421,10 @@ var ClaudeInteractiveAdapter = class _ClaudeInteractiveAdapter extends Interacti
         approvalPattern: /(allow|grant|permission|approve|trust|proceed|do you want)[^\n]{0,60}\?|\[y\/n\]|\(y\/n\)/i
       },
       keymap: new ArrowKeymap(),
+      // SUPPLEMENT only: grab context% / session $ from the status line when it
+      // is enabled. The authoritative token counts come from the transcript in
+      // run() below and overwrite these on the same meta.usage object.
+      scrapeUsage: scrapeClaudeStatusLine,
       // Claude's TUI stays open after a task; quit once it's been idle a while.
       completionIdleMs: 8e3,
       // While Claude is ACTIVELY working it shows "(esc to interrupt)" — that is
@@ -1319,6 +1438,32 @@ var ClaudeInteractiveAdapter = class _ClaudeInteractiveAdapter extends Interacti
       workingPattern: /interrupt/i,
       quitKeys: ""
     });
+    this.clock = opts.now ?? (() => /* @__PURE__ */ new Date());
+    this.projectsDir = opts.projectsDir;
+  }
+  /**
+   * Run Claude, then read AUTHORITATIVE token usage from its session transcript
+   * (~/.claude/projects/<cwd>/<id>.jsonl) and surface it as `meta.usage`. This is
+   * device-independent — it works regardless of whether the user has a usage
+   * status line — and overwrites the best-effort status-line scrape's token
+   * figures while keeping its context%/cost extras. Best-effort: if no transcript
+   * is found, the status-line usage (if any) is left as-is.
+   */
+  async run(input, ctx) {
+    const startedAt = this.clock().getTime();
+    const result = await super.run(input, ctx);
+    if (result.error) return result;
+    const transcript = await findLatestClaudeUsage({
+      cwd: input.cwd,
+      sinceMs: startedAt,
+      projectsDir: this.projectsDir
+    });
+    if (!transcript) return result;
+    const prior = result.meta?.usage ?? {};
+    return {
+      ...result,
+      meta: { ...result.meta, usage: { ...prior, ...transcript } }
+    };
   }
   static fromConfig(config) {
     return new _ClaudeInteractiveAdapter({
@@ -1328,7 +1473,7 @@ var ClaudeInteractiveAdapter = class _ClaudeInteractiveAdapter extends Interacti
   }
 };
 var ROLLOUT_UUID_RE = /-([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})\.jsonl$/;
-async function realish(p) {
+async function realish2(p) {
   try {
     return await promises.realpath(p);
   } catch {
@@ -1344,7 +1489,7 @@ async function listRollouts(root) {
     return out;
   }
   for (const y of years) {
-    const yDir = path5.join(root, y);
+    const yDir = path6.join(root, y);
     let months;
     try {
       months = await promises.readdir(yDir);
@@ -1352,7 +1497,7 @@ async function listRollouts(root) {
       continue;
     }
     for (const m of months) {
-      const mDir = path5.join(yDir, m);
+      const mDir = path6.join(yDir, m);
       let days;
       try {
         days = await promises.readdir(mDir);
@@ -1360,7 +1505,7 @@ async function listRollouts(root) {
         continue;
       }
       for (const d of days) {
-        const dDir = path5.join(mDir, d);
+        const dDir = path6.join(mDir, d);
         let files;
         try {
           files = await promises.readdir(dDir);
@@ -1369,7 +1514,7 @@ async function listRollouts(root) {
         }
         for (const f of files) {
           if (!f.startsWith("rollout-") || !f.endsWith(".jsonl")) continue;
-          const file = path5.join(dDir, f);
+          const file = path6.join(dDir, f);
           try {
             const st = await promises.stat(file);
             out.push({ file, mtimeMs: st.mtimeMs });
@@ -1402,25 +1547,55 @@ async function readSessionMeta(file) {
   }
 }
 function uuidFromRolloutFilename(file) {
-  const m = ROLLOUT_UUID_RE.exec(path5.basename(file));
+  const m = ROLLOUT_UUID_RE.exec(path6.basename(file));
   return m?.[1];
 }
-async function findLatestCodexSessionId(opts) {
-  const root = opts.sessionsDir ?? path5.join(os.homedir(), ".codex", "sessions");
+async function findLatestCodexRollout(opts) {
+  const root = opts.sessionsDir ?? path6.join(os.homedir(), ".codex", "sessions");
   const since = opts.sinceMs ?? 0;
-  const targetCwd = await realish(opts.cwd);
+  const targetCwd = await realish2(opts.cwd);
   const rollouts = await listRollouts(root);
   for (const { file, mtimeMs } of rollouts) {
     if (mtimeMs + 2e3 < since) continue;
     const meta = await readSessionMeta(file);
     if (!meta?.cwd) continue;
-    const metaCwd = await realish(meta.cwd);
+    const metaCwd = await realish2(meta.cwd);
     if (metaCwd !== targetCwd) continue;
     const id = meta.id ?? uuidFromRolloutFilename(file);
-    if (id) return id;
+    return { file, id };
   }
   return void 0;
 }
+async function sumCodexUsage(file) {
+  let text;
+  try {
+    text = await promises.readFile(file, "utf8");
+  } catch {
+    return void 0;
+  }
+  let total;
+  for (const line of text.split("\n")) {
+    if (!line.includes("token_count")) continue;
+    let rec;
+    try {
+      rec = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (rec.payload?.type !== "token_count") continue;
+    const t = rec.payload.info?.total_token_usage;
+    if (t && typeof t === "object") total = t;
+  }
+  if (!total) return void 0;
+  return {
+    source: "transcript",
+    inputTokens: total.input_tokens,
+    cachedInputTokens: total.cached_input_tokens,
+    outputTokens: total.output_tokens,
+    reasoningTokens: total.reasoning_output_tokens,
+    totalTokens: total.total_tokens
+  };
+}
 
 // src/adapters/interactive/codex-interactive.ts
 var DEFINITION2 = {
@@ -1478,29 +1653,28 @@ var CodexInteractiveAdapter = class _CodexInteractiveAdapter extends Interactive
     this.sessionsDir = opts.sessionsDir;
   }
   /**
-   * Run Codex, then capture its NATIVE session id (the rollout UUID) for this
-   * cwd and attach it to the result's `sessionRef` so the runner persists it and
-   * a later resume can use `codex resume <id> "<prompt>"`. Capture is best-effort:
-   * if no rollout matches (or any I/O fails) the result is returned unchanged, so
-   * the run still resumes via the `--last` fallback.
+   * Run Codex, then read its rollout for this cwd to capture (a) the NATIVE
+   * session id (the rollout UUID) for `sessionRef` so a later resume can use
+   * `codex resume <id> "<prompt>"`, and (b) authoritative token usage for
+   * `meta.usage` (device-independent — from Codex's own log, not the TUI). Both
+   * are best-effort: if no rollout matches (or any I/O fails) the result is
+   * returned unchanged, so the run still resumes via the `--last` fallback.
    */
   async run(input, ctx) {
     const startedAt = this.clock().getTime();
     const result = await super.run(input, ctx);
     if (result.error) return result;
-    const nativeSessionId = await findLatestCodexSessionId({
+    const rollout = await findLatestCodexRollout({
       cwd: input.cwd,
       sinceMs: startedAt,
       sessionsDir: this.sessionsDir
     });
-    if (!nativeSessionId) return result;
+    if (!rollout) return result;
+    const usage = await sumCodexUsage(rollout.file);
     return {
       ...result,
-      sessionRef: {
-        adapter: this.definition.name,
-        nativeSessionId,
-        resumable: true
-      }
+      sessionRef: rollout.id ? { adapter: this.definition.name, nativeSessionId: rollout.id, resumable: true } : result.sessionRef,
+      meta: usage ? { ...result.meta, usage } : result.meta
     };
   }
   static fromConfig(config) {
@@ -1780,11 +1954,11 @@ async function commandCheck(name, command, installHint) {
   };
 }
 async function runDoctor(options) {
-  const rootDir = path5.resolve(options.rootDir);
+  const rootDir = path6.resolve(options.rootDir);
   const checks = [];
   checks.push(checkNode());
-  let sessionsDir = path5.resolve(rootDir, ".agent-relay/sessions");
-  let logsDir = path5.resolve(rootDir, ".agent-relay/logs");
+  let sessionsDir = path6.resolve(rootDir, ".agent-relay/sessions");
+  let logsDir = path6.resolve(rootDir, ".agent-relay/logs");
   try {
     const config = await loadConfig(rootDir);
     checks.push({
@@ -1792,8 +1966,8 @@ async function runDoctor(options) {
       level: "ok",
       detail: `Valid config (defaultAdapter: ${config.defaultAdapter})`
     });
-    sessionsDir = path5.resolve(rootDir, config.sessionsDir);
-    logsDir = path5.resolve(rootDir, config.logsDir);
+    sessionsDir = path6.resolve(rootDir, config.sessionsDir);
+    logsDir = path6.resolve(rootDir, config.logsDir);
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     const missing = message.includes("not found");
@@ -1909,7 +2083,7 @@ var RunLogger = class {
     if (this.opts.maxBytes && this.bytes >= this.opts.maxBytes) {
       if (!this.truncated) {
         this.truncated = true;
-        fs6.appendFileSync(
+        fs7.appendFileSync(
           this.logFile,
           `... [log truncated at ${this.opts.maxBytes} bytes \u2014 raise --max-log-bytes for more]
 `
@@ -1917,12 +2091,12 @@ var RunLogger = class {
       }
       return;
     }
-    fs6.appendFileSync(this.logFile, text);
+    fs7.appendFileSync(this.logFile, text);
     this.bytes += Buffer.byteLength(text);
   }
   /** Ensure the log directory exists and write the run header. */
   start(header) {
-    fs6.mkdirSync(path5.dirname(this.logFile), { recursive: true });
+    fs7.mkdirSync(path6.dirname(this.logFile), { recursive: true });
     const lines = [
       "================ agent-relay run ================",
       `sessionId : ${header.sessionId}`,
@@ -1983,7 +2157,7 @@ var SessionManager = class {
   sessionsDir;
   /** Absolute path to a session's JSON metadata file. */
   filePath(sessionId) {
-    return path5.join(this.sessionsDir, `${sessionId}.json`);
+    return path6.join(this.sessionsDir, `${sessionId}.json`);
   }
   /** Build a fresh session record in the `created` state (not yet persisted). */
   create(input) {
@@ -2050,7 +2224,7 @@ var SessionManager = class {
       if (!entry.endsWith(".json")) continue;
       try {
         const raw = await promises.readFile(
-          path5.join(this.sessionsDir, entry),
+          path6.join(this.sessionsDir, entry),
           "utf8"
         );
         metas.push(JSON.parse(raw));
@@ -2074,12 +2248,12 @@ async function runAgent(options) {
   }
   const adapter = options.resolveAdapter(adapterName, config);
   const detector = options.detector ?? new CompositeCompletionDetector();
-  const rootDir = path5.resolve(options.rootDir);
-  const cwd = path5.resolve(options.cwd ?? rootDir);
-  const sessionsDir = path5.resolve(rootDir, config.sessionsDir);
-  const logsDir = path5.resolve(rootDir, config.logsDir);
+  const rootDir = path6.resolve(options.rootDir);
+  const cwd = path6.resolve(options.cwd ?? rootDir);
+  const sessionsDir = path6.resolve(rootDir, config.sessionsDir);
+  const logsDir = path6.resolve(rootDir, config.logsDir);
   const sessionId = options.sessionId ?? randomUUID();
-  const logFile = path5.join(logsDir, `${sessionId}.log`);
+  const logFile = path6.join(logsDir, `${sessionId}.log`);
   const sessions = new SessionManager(sessionsDir);
   const startedAt = iso();
   const session = sessions.create({
@@ -2375,7 +2549,7 @@ async function resolvePrompt(options) {
     );
   }
   if (options.promptFile) {
-    const file = path5.resolve(options.rootDir, options.promptFile);
+    const file = path6.resolve(options.rootDir, options.promptFile);
     try {
       const text = await promises.readFile(file, "utf8");
       if (!text.trim()) {
@@ -2402,7 +2576,7 @@ async function resolvePrompt(options) {
   );
 }
 async function runCommand(options) {
-  const rootDir = path5.resolve(options.rootDir);
+  const rootDir = path6.resolve(options.rootDir);
   const config = options.config ?? await loadConfigOrDefault(rootDir, options.onDefaultConfig);
   const prompt = await resolvePrompt({
     prompt: options.prompt,
@@ -2434,9 +2608,9 @@ async function runCommand(options) {
   });
 }
 async function resumeCommand(options) {
-  const rootDir = path5.resolve(options.rootDir);
+  const rootDir = path6.resolve(options.rootDir);
   const config = options.config ?? await loadConfigOrDefault(rootDir, options.onDefaultConfig);
-  const sessionsDir = path5.resolve(rootDir, config.sessionsDir);
+  const sessionsDir = path6.resolve(rootDir, config.sessionsDir);
   const sessions = new SessionManager(sessionsDir);
   const session = await sessions.load(options.sessionId);
   const resolveAdapter = options.resolveAdapter ?? createAdapterFactory();
@@ -2487,9 +2661,9 @@ async function resumeCommand(options) {
   return { session, resumable, resumed: true, outcome };
 }
 async function resolveManager(opts) {
-  const rootDir = path5.resolve(opts.rootDir);
+  const rootDir = path6.resolve(opts.rootDir);
   const config = await loadConfigOrDefault(rootDir, opts.onDefaultConfig);
-  const sessionsDir = path5.resolve(rootDir, config.sessionsDir);
+  const sessionsDir = path6.resolve(rootDir, config.sessionsDir);
   const sessions = new SessionManager(sessionsDir);
   return { sessions, metas: await sessions.list() };
 }
@@ -2810,7 +2984,7 @@ program.command("run").description("Run a prompt through an agent adapter").opti
   "api decider: OpenAI-compatible chat-completions URL"
 ).option("--decider-model <model>", "api decider: model name").option("--decider-key <key>", "api decider: bearer API key").option(
   "--decider-max-tokens <n>",
-  "api decider: max tokens",
+  "api decider: max tokens (default 2048; floor 512 \u2014 reasoning models need headroom)",
   positiveIntArg("--decider-max-tokens")
 ).option(
   "--decider-timeout-ms <n>",
@@ -2882,7 +3056,7 @@ program.command("resume").description("Inspect a prior session and optionally se
   "Decider override: rule | always-approve | command | api"
 ).option("--decider-command <cmdline>", "command decider: full command line").option("--decider-url <url>", "api decider: chat-completions URL").option("--decider-model <model>", "api decider: model name").option("--decider-key <key>", "api decider: bearer API key").option(
   "--decider-max-tokens <n>",
-  "api decider: max tokens",
+  "api decider: max tokens (default 2048; floor 512 \u2014 reasoning models need headroom)",
   positiveIntArg("--decider-max-tokens")
 ).option(
   "--decider-timeout-ms <n>",