jeo-code 0.8.21 → 0.8.23

package/src/commands/routine.ts

@@ -0,0 +1,249 @@
+/**
+ * `jeo routine init` — generate a GitHub Actions workflow that runs
+ * `jeo "<prompt>" -p` headlessly on a schedule or repo event.
+ *
+ * This is the SCOPED-SAFE take on "Routines": jeo-code itself never runs a
+ * scheduler, listens on a port, or accepts a webhook — it's a pure template
+ * generator. GitHub's own hosted runners do the actual triggering/running,
+ * which achieves "runs without your laptop" with zero new attack surface
+ * inside jeo-code's own process. See ../util/routine-template.ts for the
+ * pure YAML-building logic this command wraps with flag parsing + I/O.
+ */
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { renderRoutineWorkflow, validateCron, type RoutineConfig, type RoutineTrigger } from "../util/routine-template";
+import { slugify } from "../agent/memory-okf";
+
+const TRIGGERS: readonly RoutineTrigger[] = ["schedule", "issues", "pull_request"];
+function isTrigger(val: string | undefined): val is RoutineTrigger {
+  return val !== undefined && (TRIGGERS as readonly string[]).includes(val);
+}
+
+const VALUE_FLAGS: Record<string, true> = { "--name": true, "--trigger": true, "--cron": true, "--prompt": true, "--api-key-env": true, "--out": true };
+
+interface ParsedInit {
+  name: string;
+  triggerRaw?: string;
+  cron?: string;
+  prompt?: string;
+  apiKeyEnvVar: string;
+  openPr: boolean;
+  out?: string;
+  force: boolean;
+  dryRun: boolean;
+  json: boolean;
+  help: boolean;
+  /** Parse-level problems: unknown flags, or a value-flag given with no value. */
+  errors: string[];
+}
+
+/** `--flag value` or `--flag=value`, matching launch/flags.ts's takeValue shape
+ *  (a bare value-flag followed by another `-`-prefixed token is treated as
+ *  missing, not as accidentally swallowing the next flag). */
+function takeValue(args: string[], index: number, flag: string): { value?: string; nextIndex: number } {
+  const current = args[index]!;
+  const inline = `${flag}=`;
+  if (current.startsWith(inline)) return { value: current.slice(inline.length), nextIndex: index };
+  const next = args[index + 1];
+  if (next !== undefined && !next.startsWith("-")) return { value: next, nextIndex: index + 1 };
+  return { nextIndex: index };
+}
+
+function parseInitArgs(args: string[]): ParsedInit {
+  const parsed: ParsedInit = {
+    name: "jeo routine",
+    apiKeyEnvVar: "ANTHROPIC_API_KEY",
+    openPr: true,
+    force: false,
+    dryRun: false,
+    json: false,
+    help: false,
+    errors: [],
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    const flag = a.includes("=") ? a.slice(0, a.indexOf("=")) : a;
+
+    if (flag === "-h" || flag === "--help") { parsed.help = true; continue; }
+    if (flag === "--no-pr") { parsed.openPr = false; continue; }
+    if (flag === "--force") { parsed.force = true; continue; }
+    if (flag === "--dry-run") { parsed.dryRun = true; continue; }
+    if (flag === "--json") { parsed.json = true; continue; }
+
+    if (VALUE_FLAGS[flag]) {
+      const { value, nextIndex } = takeValue(args, i, flag);
+      i = nextIndex;
+      if (value === undefined) {
+        parsed.errors.push(`${flag} requires a value`);
+        continue;
+      }
+      switch (flag) {
+        case "--name": parsed.name = value; break;
+        case "--trigger": parsed.triggerRaw = value; break;
+        case "--cron": parsed.cron = value; break;
+        case "--prompt": parsed.prompt = value; break;
+        case "--api-key-env": parsed.apiKeyEnvVar = value; break;
+        case "--out": parsed.out = value; break;
+      }
+      continue;
+    }
+
+    parsed.errors.push(`Unknown flag: ${a}`);
+  }
+
+  return parsed;
+}
+
+function printUsage(): void {
+  console.log("Usage: jeo routine init [options]");
+  console.log("");
+  console.log('Generate a GitHub Actions workflow that runs `jeo "<prompt>" -p` headlessly');
+  console.log("on a schedule or repo event. GitHub's own hosted runners do the triggering —");
+  console.log("jeo-code never runs a scheduler or listens on a port for this.");
+  console.log("");
+  console.log("Options:");
+  console.log("  --trigger <schedule|issues|pull_request>  Required. What fires the routine.");
+  console.log("  --prompt <text>            Required. The task/goal text passed to `jeo -p`.");
+  console.log('  --cron <expr>              Required when --trigger schedule (e.g. "0 7 * * *").');
+  console.log('  --name <name>              Workflow display name. Default: "jeo routine".');
+  console.log("  --api-key-env <VAR_NAME>   Secret env var name. Default: ANTHROPIC_API_KEY.");
+  console.log("  --no-pr                    Commit directly to the branch instead of opening a PR.");
+  console.log("  --out <path>               Output path. Default: .github/workflows/jeo-routine-<slug>.yml");
+  console.log("  --force                    Overwrite an existing file at --out.");
+  console.log("  --dry-run                  Print the rendered YAML instead of writing it.");
+  console.log("  --json                     Machine-readable output.");
+  console.log("  -h, --help                 Show this help message.");
+}
+
+async function runInit(args: string[]): Promise<void> {
+  const parsed = parseInitArgs(args);
+
+  if (parsed.errors.length > 0) {
+    for (const e of parsed.errors) console.log(`Error: ${e}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (parsed.help) {
+    printUsage();
+    return;
+  }
+
+  const problems: string[] = [];
+  if (!isTrigger(parsed.triggerRaw)) {
+    problems.push(
+      parsed.triggerRaw
+        ? `--trigger must be one of: schedule, issues, pull_request (got '${parsed.triggerRaw}')`
+        : "--trigger is required (one of: schedule, issues, pull_request)",
+    );
+  }
+  if (!parsed.prompt) {
+    problems.push("--prompt is required");
+  }
+  const trigger = isTrigger(parsed.triggerRaw) ? parsed.triggerRaw : undefined;
+  if (trigger === "schedule") {
+    if (!parsed.cron) {
+      problems.push("--cron is required when --trigger schedule");
+    } else if (!validateCron(parsed.cron)) {
+      problems.push(`--cron '${parsed.cron}' does not look like a valid 5-field cron expression`);
+    }
+  }
+
+  if (problems.length > 0) {
+    for (const p of problems) console.log(`Error: ${p}`);
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  const config: RoutineConfig = {
+    name: parsed.name,
+    trigger: trigger!,
+    cron: parsed.cron,
+    prompt: parsed.prompt!,
+    apiKeyEnvVar: parsed.apiKeyEnvVar,
+    openPr: parsed.openPr,
+  };
+
+  let yaml: string;
+  try {
+    yaml = renderRoutineWorkflow(config);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (parsed.json) console.log(JSON.stringify({ error: msg }));
+    else console.log(`Error: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  const outPath = parsed.out ?? path.join(".github", "workflows", `jeo-routine-${slugify(parsed.name)}.yml`);
+  const resolvedOut = path.resolve(process.cwd(), outPath);
+
+  if (parsed.dryRun) {
+    if (parsed.json) console.log(JSON.stringify({ dryRun: true, out: resolvedOut, yaml }, null, 2));
+    else console.log(yaml);
+    return;
+  }
+
+  let exists = true;
+  try {
+    await fs.access(resolvedOut);
+  } catch {
+    exists = false;
+  }
+  if (exists && !parsed.force) {
+    const msg = `${resolvedOut} already exists. Use --force to overwrite.`;
+    if (parsed.json) console.log(JSON.stringify({ error: msg }));
+    else console.log(`Error: ${msg}`);
+    process.exitCode = 1;
+    return;
+  }
+
+  await fs.mkdir(path.dirname(resolvedOut), { recursive: true });
+  // Atomic write: build the file fully off to the side, then rename into
+  // place, so a crash mid-write never leaves a truncated workflow file.
+  const tmpPath = `${resolvedOut}.tmp-${process.pid}`;
+  await fs.writeFile(tmpPath, yaml, "utf-8");
+  await fs.rename(tmpPath, resolvedOut);
+
+  if (parsed.json) {
+    console.log(JSON.stringify({ wrote: resolvedOut, trigger, apiKeyEnvVar: parsed.apiKeyEnvVar, openPr: parsed.openPr }, null, 2));
+    return;
+  }
+
+  console.log(`Wrote ${resolvedOut}`);
+  console.log("");
+  console.log("Next steps:");
+  console.log(`  - Add '${parsed.apiKeyEnvVar}' as a repo secret: Settings -> Secrets and variables -> Actions.`);
+  if (trigger === "schedule") {
+    console.log("  - Scheduled workflows only run on the repo's default branch, and GitHub may");
+    console.log("    delay or skip scheduled runs on low-activity repos — this is documented");
+    console.log("    GitHub Actions behavior, not a bug in the generated workflow.");
+  }
+  console.log(`  - Commit and push ${resolvedOut} to enable it.`);
+}
+
+export async function runRoutineCommand(args: string[]): Promise<void> {
+  const sub = args[0];
+
+  if (sub === "-h" || sub === "--help") {
+    printUsage();
+    return;
+  }
+
+  if (sub === undefined) {
+    printUsage();
+    process.exitCode = 1;
+    return;
+  }
+
+  if (sub !== "init") {
+    console.log(`Unknown 'jeo routine' subcommand '${sub}'. Usage: jeo routine init [options]`);
+    process.exitCode = 1;
+    return;
+  }
+
+  await runInit(args.slice(1));
+}

package/src/commands/skills.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs/promises";
 import * as path from "node:path";
 import { SKILLS, getSkillFrom, formatSkill, loadSkills, skillDirs, bundledSkillFileContent, userSkillsDir } from "../skills/catalog";
 import { getLocalJeoDir } from "../agent/state";
+import { appendSkillLesson, evalSkillLessons, type SkillLesson } from "../agent/skill-lessons";
 
 export { userSkillsDir };
 
@@ -147,6 +148,62 @@ export async function runSkillsCommand(args: string[] = []): Promise<void> {
     return;
   }
 
+  // `jeo skills lesson <skill> <failure|anti-pattern> "<title>" "<detail>"` — manual
+  // lesson entry into the project-level skill file (the same compounding write the
+  // launch.ts stall-guard fires automatically; lets an agent or human record one directly).
+  if (cleanArgs[0] === "lesson") {
+    const [, skillName, kindArg, title, detail] = cleanArgs;
+    if (!skillName || !kindArg || !title || !detail) {
+      console.log('Usage: jeo skills lesson <skill> <failure|anti-pattern> "<title>" "<detail>"');
+      process.exitCode = 1;
+      return;
+    }
+    const kind: SkillLesson["kind"] | null =
+      kindArg === "failure" ? "failure-mode" : kindArg === "anti-pattern" ? "anti-pattern" : null;
+    if (!kind) {
+      console.log(`Error: kind must be 'failure' or 'anti-pattern' (got '${kindArg}').`);
+      process.exitCode = 1;
+      return;
+    }
+    const result = await appendSkillLesson(cwd, { skill: skillName, kind, title, detail });
+    if (isJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.appended) {
+      console.log("Appended.");
+    } else if (result.reason === "duplicate") {
+      console.log("Already recorded (duplicate).");
+    } else {
+      console.log(`Error: ${result.reason ?? "unknown error"}`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  // `jeo skills eval <skill>` — self-eval half: judge whether recorded lessons are
+  // still covered by the skill's current guidance, or have gone stale.
+  if (cleanArgs[0] === "eval") {
+    const skillName = cleanArgs[1];
+    if (!skillName) {
+      console.log("Error: Missing skill name for 'eval' command.");
+      process.exitCode = 1;
+      return;
+    }
+    const result = await evalSkillLessons(cwd, skillName);
+    if (result === null) {
+      console.log(`No recorded lessons for '${skillName}' yet.`);
+      return;
+    }
+    if (isJson) {
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.log(`${result.covered}/${result.total} lessons still covered by current guidance.`);
+      for (const s of result.stale) {
+        console.log(`  STALE  ${s.title}: ${s.reason}`);
+      }
+    }
+    return;
+  }
+
   // List/lookup over the MERGED set (bundled + ~/.jeo/skills + ~/.agents/skills + project dirs), matching the REPL /skill.
   const skills = await loadSkills(cwd);
   const command = cleanArgs[0];

package/src/tui/app.ts

@@ -11,7 +11,8 @@
  */
 import { Renderer } from "./renderer";
 import { readWorkflowStateStrict } from "../agent/state";
-import { size, isTTY, hideCursor, showCursor, enterAltScreen, leaveAltScreen } from "./terminal";
+import { size, isTTY, hideCursor, showCursor, enterAltScreen, leaveAltScreen, watchResize } from "./terminal";
+
 import { Spinner } from "./components/spinner";
 import { ToolList } from "./components/tool-list";
 import { StreamRegion } from "./components/stream";
@@ -251,6 +252,10 @@ export class LaunchTui {
   private lastResizeAt = 0;
   private lastCols = -1;
   private lastRows = -1;
+  // Stops the poll-based resize safety net (terminal.ts's watchResize) started in
+  // begin(); cleared in finish() alongside the 'resize'/SIGCONT listeners.
+  private stopResizeWatch: (() => void) | undefined;
+
   private pendingIndex: number | null = null;
   private pendingTitle: string | null = null;
   private pendingForge: ForgeSummary | null = null;
@@ -1172,7 +1177,15 @@ export class LaunchTui {
         if (processMax > 0 && resumeCount + 1 >= processMax) process.setMaxListeners(resumeCount + 2);
         process.on("SIGCONT", this.onResume);
       }
+      // Poll-based safety net (terminal.ts's watchResize): catches a resize the TTY
+      // 'resize' event missed (e.g. a tmux pane switch while this pane wasn't the
+      // foreground one — tmux only forwards SIGWINCH to the active pane). Cheap
+      // (300ms comparison poll), fires resizeRepaint() only on an actual geometry
+      // change, and is a no-op alongside a real 'resize' event (whichever notices
+      // first wins; lastCols/lastRows dedupe the other).
+      this.stopResizeWatch = watchResize(() => this.resizeRepaint());
     }
+
     // Animate the spinner + elapsed clock while the model is thinking.
     this.timer = setInterval(() => {
       try {
@@ -1269,7 +1282,12 @@ export class LaunchTui {
       if (process.platform !== "win32") {
         process.removeListener("SIGCONT", this.onResume);
       }
+      if (this.stopResizeWatch) {
+        this.stopResizeWatch();
+        this.stopResizeWatch = undefined;
+      }
     }
+
     if (this.usedAltScreen) {
       // Leave the alt screen (restores the main buffer + scrollback), then print the
       // static summary below the prior output so the turn leaves exactly one record.

package/src/tui/terminal.ts

@@ -84,6 +84,75 @@ export function size(): { cols: number; rows: number } {
     rows: process.stdout.rows || 24,
   };
 }
+/** True live geometry via `getWindowSize()` — a real `TIOCGWINSZ` ioctl through libuv,
+ *  bypassing `process.stdout.columns`/`.rows` entirely. Node/Bun only refresh THOSE
+ *  cached fields when a `'resize'` (SIGWINCH) event fires, which is exactly the signal
+ *  {@link watchResize} exists to work around (tmux pane/window switch while jeo's pane
+ *  isn't foregrounded, a SIGCONT race after Ctrl-Z, an SSH/multiplexer layer that only
+ *  propagates the ioctl update on the next write) — in every one of those, the cached
+ *  fields go stale and NOTHING re-freshes them without a real event. Returns `null` when
+ *  unavailable (older runtimes, non-TTY streams — Bun/Node only expose `getWindowSize`
+ *  on a real `tty.WriteStream`), it throws (handle torn down), or it reports `0,0` (no
+ *  controlling terminal ever set a winsize, e.g. a bare pty as `bun test` sees). */
+function liveWindowSize(): { cols: number; rows: number } | null {
+  const stream = process.stdout as NodeJS.WriteStream & { getWindowSize?: () => [number, number] };
+  if (typeof stream.getWindowSize !== "function") return null;
+  try {
+    const [cols, rows] = stream.getWindowSize();
+    return cols > 0 && rows > 0 ? { cols, rows } : null;
+  } catch {
+    return null;
+  }
+}
+
+/** Poll-based resize watcher — a SAFETY NET alongside the TTY `'resize'` event.
+ *  `'resize'` (SIGWINCH) is missed in several real-world cases jeo actually hits: a
+ *  tmux pane/window switch while jeo's pane isn't the foreground one (tmux only
+ *  forwards SIGWINCH to the active pane), a SIGCONT race after Ctrl-Z where the resize
+ *  happened entirely during the stop, and some SSH/multiplexer layers that only
+ *  propagate the ioctl update on the next write rather than emitting a fresh event.
+ *  In every one of these, `process.stdout.columns`/`.rows` (and therefore `size()`)
+ *  go stale and NOTHING short of a real `'resize'` event ever refreshes them — so a
+ *  naive poll comparing `size()` against itself can never observe a change that
+ *  already happened, it would just keep comparing one stale cache to itself.
+ *
+ *  Each tick instead asks the OS DIRECTLY via {@link liveWindowSize} (a cheap,
+ *  allocation-free ioctl — safe every `intervalMs`). When that live read disagrees
+ *  with the last-seen geometry, this SELF-HEALS the stale cache — writing the
+ *  corrected values onto `process.stdout.columns`/`.rows` exactly like Node's own
+ *  SIGWINCH handler would — before firing `onChange`, so every other reader of
+ *  `size()` (the live-frame `draw()`, `resizeRepaint()`, `idleResizeHandler()`, a
+ *  picker's `repaint()`) sees the corrected geometry too, not just this callback.
+ *  When `getWindowSize` is unavailable, falls back to comparing `size()` against
+ *  itself (the pre-existing behavior) — still catches a genuine cache update that
+ *  arrived via some OTHER path (e.g. a real `'resize'` event firing between polls).
+ *  Never fires spuriously — only on an actual geometry change — so it composes
+ *  safely alongside an existing `'resize'` listener (whichever notices first wins,
+ *  the other becomes a no-op once both routes converge on the same geometry).
+ *  Returns a `stop()` to clear the interval; the timer is `unref()`d so it can never
+ *  keep the process alive on its own. */
+export function watchResize(onChange: (cols: number, rows: number) => void, intervalMs = 300): () => void {
+  let last = size();
+  const timer = setInterval(() => {
+    const live = liveWindowSize();
+    const cur = live ?? size();
+    if (cur.cols !== last.cols || cur.rows !== last.rows) {
+      last = cur;
+      if (live) {
+        try {
+          process.stdout.columns = live.cols;
+          process.stdout.rows = live.rows;
+        } catch { /* non-writable in this environment — onChange still fires below */ }
+      }
+      onChange(cur.cols, cur.rows);
+    }
+  }, intervalMs);
+  if (typeof (timer as unknown as { unref?: () => void }).unref === "function") {
+    (timer as unknown as { unref: () => void }).unref();
+  }
+  return () => clearInterval(timer);
+}
+
 
 export function isTTY(): boolean {
   return !!process.stdout.isTTY;
@@ -137,3 +206,23 @@ export function enableKittyKeyboard(): string {
 export function disableKittyKeyboard(): string {
   return `${ESC}<u`;
 }
+/** Set the terminal's TEXT CURSOR color via OSC 12 (`\x1b]12;#rrggbb\x07`) — widely
+ *  supported (xterm, iTerm2, kitty, wezterm, alacritty, ghostty, foot, most tmux/VTE
+ *  terminals). jeo's input box parks the REAL terminal cursor at the caret (see
+ *  `input-box.ts`'s `cursorRow`/`cursorCol`) rather than drawing a fake one, so the
+ *  cursor's on-screen color is entirely up to the terminal's default — usually a
+ *  solid white/light block. On every theme except `mono` (whose panels/prompt already
+ *  render colorless), that default cursor color visually MATCHES the light card
+ *  backgrounds used elsewhere in the UI (e.g. `cardFillPaint`), making the caret
+ *  nearly impossible to spot against typed text. Setting it to the theme's accent hue
+ *  gives the caret a color that's always distinct from body text and panel fills. */
+export function setCursorColor(hex: string): string {
+  return `\x1b]12;${hex}\x07`;
+}
+
+/** Restore the terminal's default cursor color (OSC 112, no color id) — the
+ *  counterpart to {@link setCursorColor}, sent on exit so a shell/editor started
+ *  afterward isn't left with jeo's accent-colored cursor. */
+export function resetCursorColor(): string {
+  return `\x1b]112\x07`;
+}

package/src/util/provider-error.ts

@@ -117,6 +117,21 @@ export function friendlyProviderError(err: unknown): string {
   if (status === 401 || status === 403 || /\b40[13]\b/.test(msg)) {
     return `${provider} rejected the credential (HTTP ${status ?? "401/403"}). Run 'jeo auth status', re-login with /provider login <name>, and for Antigravity prefer '/provider login antigravity' (gemini login only works when the Cloud Code Assist backend authorizes that token).`;
   }
+  // A persistent 5xx (server-side fault on the provider's backend) — `ProviderHttpError`
+  // already embeds the numeric status directly in its message ("… failed (HTTP 500) …",
+  // caught here too, redundantly but harmlessly), but `ProviderStreamError` (the in-band
+  // SSE/stream error shape — antigravity.ts/gemini.ts's `google.rpc.Status` and
+  // openai-responses.ts's `response.failed`/`error` events) composes its `.message` from
+  // a STRING status code only ("Antigravity stream failed (INTERNAL): internal error"),
+  // never the numeric one, even though `.status` carries it correctly (explicitStatus
+  // for antigravity/gemini's google.rpc.Status `error.code`; the 500 default for
+  // openai-responses's non-rate_limit_exceeded codes). Without a digit anywhere in the
+  // text, launch.ts's `routeFailureReason` `/\b(?:500|502|503|504|529)\b/` text regex
+  // never matched, so the equivalent-pool fallback never fired for a stream-shaped 5xx
+  // even with a credentialed same-tier fallback sitting right there.
+  if (status !== undefined && status >= 500 && status < 600) {
+    return `${provider} hit a persistent server-side error (HTTP ${status}) — ${msg}. The provider's backend itself is failing; switch model with /model or wait and retry.`;
+  }
   if ((err instanceof Error && err.name === "TimeoutError") || /the operation timed out/i.test(msg)) {
     return `${provider} did not complete the request within the call timeout (default 30min). This is expected for a HIGH/XHIGH-reasoning-effort completion that legitimately runs long on a hard problem — raise JEO_CALL_TIMEOUT_MS (ms) if this recurs, or lower the thinking level with /model.`;
   }

package/src/util/retry.ts

@@ -5,8 +5,16 @@ export interface RetryOptions {
   isRetryable?: (err: unknown, attempt: number) => boolean;
   sleep?: (ms: number) => Promise<void>;   // injectable for tests (default real setTimeout)
   random?: () => number;   // injectable RNG for jitter (default Math.random); equal-jitter in [0.5x, 1x]
-  /** Notified before each backoff wait; `delayMs` is the wait actually applied. */
-  onRetry?: (attempt: number, err: unknown, delayMs: number) => void;
+  /** Notified before each backoff wait; `delayMs` is the wait actually applied.
+   *  Returning `false` (explicitly) aborts the retry ladder immediately — the
+   *  pending error is thrown right away instead of sleeping and re-attempting.
+   *  Lets a caller with a same-tier FALLBACK model available bail out of a
+   *  same-model rate-limit retry loop early rather than riding the full
+   *  `rateLimitRetries` budget (up to ~90s of escalating backoff) before the
+   *  turn-level equivalent-pool fallback ever gets a chance to switch models.
+   *  Any other return value (including `undefined`, the common case) continues
+   *  the retry ladder unchanged. */
+  onRetry?: (attempt: number, err: unknown, delayMs: number) => void | false;
   /** Aborts an in-progress backoff wait (e.g. Ctrl-C / turn cancel). Already-aborted or
    *  aborted-mid-wait rejects immediately instead of completing the sleep — the escape hatch
    *  for a long, honored provider `Retry-After` (see `rateLimitMaxServerDelayMs`: those are no
@@ -200,8 +208,11 @@ export async function withRetry<T>(fn: () => Promise<T>, opts?: RetryOptions): P
         : 0;
       const delay = Math.max(base, floor);
 
-      if (onRetry) {
-        onRetry(attempt, err, delay);
+      // A `false` return from onRetry means the caller wants to bail NOW instead of
+      // sleeping and re-attempting (see RetryOptions.onRetry's doc comment) — throw
+      // the pending error immediately rather than entering the backoff wait.
+      if (onRetry && onRetry(attempt, err, delay) === false) {
+        throw err;
       }
 
       await abortableSleep(sleep, delay, signal);