@anyslate/cli 0.3.0 → 0.4.0

package/README.md

@@ -1,39 +1,92 @@
-# @anyslate/cli
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://mcp.anyslate.io/logo-full-dark.png">
+    <img src="https://mcp.anyslate.io/logo-full-light.png" alt="AnySlate" width="280">
+  </picture>
+</p>
 
-The bridge that lets your AI tools quietly tell AnySlate what you've been working on - without you having to remember to checkpoint anything.
+<h1 align="center">@anyslate/cli</h1>
 
-## What this is
+<p align="center">
+  <strong>Your AI tools remember what you did. Automatically.</strong><br>
+  Lifecycle hooks, git commits and CI runs → your AnySlate memory, without you lifting a finger.
+</p>
 
-A small command-line tool that runs on your machine. Your AI tools (Claude Code, git, CI) call it on your behalf as you work. It records what's happening into your AnySlate **Activity feed** - file edits, shell commands, commits - automatically and continuously.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@anyslate/cli"><img alt="npm" src="https://img.shields.io/npm/v/@anyslate/cli?color=f45f5f&labelColor=252c3e"></a>
+  <a href="https://nodejs.org"><img alt="node" src="https://img.shields.io/node/v/@anyslate/cli?color=f45f5f&labelColor=252c3e"></a>
+  <img alt="dependencies" src="https://img.shields.io/badge/runtime%20deps-0-f45f5f?labelColor=252c3e">
+  <img alt="license" src="https://img.shields.io/npm/l/@anyslate/cli?color=f45f5f&labelColor=252c3e">
+</p>
 
-Think of it like a Fitbit, but for your AI work. You don't tell a Fitbit "I just took 47 steps." You wear it, walk around, the count updates. Same shape here. You install this once, paste a small config snippet into your AI tool's settings, and from that point on, capture happens in the background while you work.
+---
 
-**You almost never run a CLI command yourself.** The tool exists to be invisible plumbing that other tools call. The setup below takes 5 minutes and ends with `anyslate doctor` telling you it works.
+## What is this?
 
-## Where it fits in your workflow
+**AnySlate** gives your AI tools a long-term memory — a place where decisions, tasks and
+work history live, so Claude, Cursor or Codex can pick up where you left off instead of
+starting cold every session.
 
-Most days you'll never type `anyslate` yourself. Here's what actually happens:
+**This CLI is how that memory gets filled in when no AI is watching.**
 
-| Trigger | Who calls the CLI | What lands |
+An AI can only record something if it decides to call a tool. But a lot of your real work
+happens outside that: you commit code, CI deploys, you run the test suite, you make a call
+while staring at a terminal. None of it has an AI present to write it down.
+
+This CLI closes that gap. Your tools call it for you:
+
+```
+Claude Code fires a hook  ─┐
+git runs post-commit      ─┼─→  anyslate  ─→  AnySlate memory
+CI finishes a deploy      ─┘
+```
+
+Think of it like a fitness tracker for your engineering work. You don't tell a fitness
+tracker "I just took 47 steps." You wear it, you walk, the number goes up. Same idea:
+install this once, paste one config block, and capture happens in the background forever.
+
+> **You will almost never type `anyslate` yourself.** It is plumbing that other tools call.
+> Setup takes about five minutes and ends with `anyslate doctor` confirming it works.
+
+## Quick start
+
+```bash
+npm i -g @anyslate/cli     # 1. install
+anyslate login             # 2. sign in (opens your browser)
+anyslate doctor            # 3. confirm it works
+```
+
+Then paste the hook block into `~/.claude/settings.json` — see
+[Wiring into Claude Code](#wiring-into-claude-code) — and restart Claude Code. Done.
+
+## What actually gets captured
+
+| Trigger | Who calls the CLI | What lands in your memory |
 |---|---|---|
-| You open a Claude Code session | Claude Code's `SessionStart` hook | Session-start activity; the AnySlate session is created on first sight |
-| Claude edits `routes/auth.ts` | Claude Code's `PostToolUse` hook | "Edited routes/auth.ts" in the activity ledger |
-| Claude runs `npm test` | Claude Code's `PostToolUse` hook | Command + output in the activity ledger |
-| You `git commit` | Git's `post-commit` hook | Commit metadata + diff stats captured |
-| Teammate merges your PR | GitHub webhook (no CLI needed) | PR-merged event captured |
-| You close the laptop | Claude Code's `Stop` hook | Session-end marker captured |
-| **You manually want to checkpoint a decision** | **You typing `anyslate checkpoint ...`** | **Captured immediately** |
-| **You want to upload a file as an artifact** | **You typing `anyslate upload-artifact ...`** | **File stored, returns `cloud://artifact/<id>`** |
+| You open a Claude Code session | `SessionStart` hook | Session start + working directory; the AnySlate memory is created on first sight |
+| Claude edits `routes/auth.ts` | `PostToolUse` hook | `Edited routes/auth.ts` in the activity ledger |
+| Claude runs `npm test` | `PostToolUse` hook | Command + exit status in the activity ledger |
+| You `git commit` | git `post-commit` hook | Commit metadata and diff stats |
+| A teammate merges your PR | GitHub webhook (no CLI needed) | PR-merged event |
+| You close the laptop | `Stop` hook | Session-end marker |
+| **You want to record a decision** | **you typing `anyslate checkpoint`** | **Captured immediately, as a decision** |
+| **You want to attach a file** | **you typing `anyslate upload-artifact`** | **Stored, returns `cloud://artifact/<id>`** |
 
-The first six rows are automatic - that's what the lifecycle hooks do. The bottom two are the rare moments where you'd actually type something yourself.
+The first six rows are automatic. The last two are the rare moments you'd type something.
 
-### What hook captures actually write - read this before you form expectations
+### What hook captures write — read this before forming expectations
 
-Hook captures land in a dedicated **`## Activity Ledger`** section of your memory page: which files were touched, which commands ran, what exit status they returned. That is the whole contract. The ledger is capped (25 files / 15 commands per entry) and is built deterministically - no LLM runs in the hook path, so capture never bills against your AI quota.
+Hook captures land in a dedicated **`## Activity Ledger`** section of your memory page:
+which files were touched, which commands ran, what exit status they returned. That is the
+whole contract. The ledger is capped (25 files / 15 commands per entry) and is built
+deterministically — **no LLM runs in the hook path**, so background capture never bills
+against your AI quota.
 
-Hook captures **do not** write to the **Decisions** or **Open Tasks** sections. Those stay human- and LLM-authored, and are populated by `anyslate checkpoint`, by the in-host MCP flow (`/anyslate-new`, `/anyslate-continue`), or by you editing the page. A hook firing on `Bash` has no decision in it to extract, and the product no longer pretends otherwise.
+Hook captures **do not** write to **Key Decisions** or **Open Tasks**. Those stay human-
+and LLM-authored. A hook firing on `Bash` has no decision inside it to extract, and the
+product no longer pretends otherwise.
 
-If you want a decision recorded, type it:
+If you want a decision recorded, say so:
 
 ```bash
 anyslate checkpoint --note "Decided: Redis for session cache, not memcached"
@@ -41,19 +94,26 @@ anyslate checkpoint --note "Decided: Redis for session cache, not memcached"
 
 ### Approval: hook captures auto-promote
 
-Every lifecycle hook - `Edit` / `Write` / `MultiEdit`, `Bash`, and the session start/stop markers - classifies **low-risk** and auto-promotes on its own, 30-90 seconds after capture. An edit-heavy session does **not** build an approval queue.
-
-Rows still wait for approval in **AI Memory → Activity** when they are genuinely riskier: a capture aimed at a different session than the one that produced it, a decision that supersedes an earlier one, a submission from an untrusted source, or one carrying `confidence < 0.8`.
-
-File edits used to map to `artifact_produced`, which is high-risk by classification. That was wrong on two counts: it forced a manual approval on the single most common event in a session, and `artifact_produced` is a contract meaning "I stored an artifact, here is its id" - which a hook can never satisfy, so the server rejected it. Edits now map to `task_completed` and carry the touched paths in the ledger.
+Every lifecycle hook — `Edit` / `Write` / `MultiEdit`, `Bash`, and the session start/stop
+markers — classifies **low-risk** and auto-promotes on its own, 30–90 seconds after
+capture. An edit-heavy session does **not** build an approval queue.
 
-## What you get back
+Rows still wait for approval in **AI Memory → Activity** when they are genuinely riskier: a
+capture aimed at a different session than the one that produced it, a decision that
+supersedes an earlier one, a submission from an untrusted source, or one carrying
+`confidence < 0.8`.
 
-After the setup is in place:
+## Why bother
 
 - **You stop forgetting to checkpoint.** Capture happens whether you remember or not.
-- **AnySlate sees what actually happened, not just what the AI claimed.** Git knows what files really changed. The hooks know what commands really ran.
-- **Your work follows you across tools.** Claude Code at home, Cursor at work, terminal in between - all feed the same memory. (Cursor and Windsurf feed it through the in-host MCP server, not this CLI - see the FAQ.)
+- **You see what actually happened, not just what the AI claimed.** If the agent says it
+  implemented `TokenRefreshService` and the diff is whitespace, that discrepancy is
+  visible. You trust the AI because you can check, not because you have to assume.
+- **Your work follows you across tools.** Claude Code at home, Cursor at work, a terminal
+  in between — all feeding one memory. (Cursor and Windsurf feed it through the in-host
+  MCP server rather than this CLI — see the [FAQ](#faq).)
+- **Nothing is canonical until it is.** Anything pending can be rejected without ever
+  touching a memory page.
 
 ## Install
 
@@ -136,6 +196,8 @@ export ANYSLATE_HANDLE=mh_xxxxxxxx                # optional, scope to one capab
 export ANYSLATE_DISABLE=1                         # optional, disables capture for this shell
 export ANYSLATE_HOME=/path/to/dir                 # optional, overrides ~/.anyslate
 export ANYSLATE_STDIN_TIMEOUT_MS=10000            # optional, stdin idle timeout (0 disables)
+export ANYSLATE_HOOK_TIMEOUT_MS=5000              # optional, request budget for one hook
+export ANYSLATE_MAX_CALLS_PER_MINUTE=60           # optional, local call ceiling (0 disables)
 ```
 
 Env vars override `~/.anyslate/cli.json`.
@@ -154,6 +216,24 @@ Capability handles are `mh_` + a 32-character id (e.g. `mh_V1StGXR8Z5jdHi6BmyT0a
 
 **If your token was minted with a memory scope, it already carries that scope server-side and `ANYSLATE_HANDLE` / `--handle` is ignored.** Scoped tokens cannot be widened per-call by design. To capture workspace-wide, mint an unscoped token. `anyslate doctor` reports which case you're in.
 
+### When capture pauses itself
+
+Since 0.4.0 the CLI refuses to keep calling a server that is refusing it. Three things changed:
+
+- **No unbounded retries.** `checkpoint` and `upload-artifact` retry at most 3 times, with exponential backoff and jitter and a 15-second total sleep budget. `hook` does not retry at all: it fires on every tool call, so a retry there is a doubled request rate in exchange for one row in an activity feed.
+- **`Retry-After` is obeyed.** A `429` or `503` that names a wait pauses this machine for exactly that long. The CLI never sleeps through a long one - the process exits and the pause is honoured by whichever process runs next.
+- **A circuit breaker that outlives the process.** Every hook is a separate process, so an in-memory breaker would be worthless. After 3 consecutive `401`s - or one definitively dead credential, such as a refresh token the server has already replaced - capture pauses, the pause is recorded in `~/.anyslate/cli-guard.json`, and the CLI tells you once:
+
+```
+anyslate: capture paused until 2026-08-02T12:15:00.000Z — repeated authentication failures (invalid_grant). Run `anyslate login` to sign in again; no requests are sent until then.
+```
+
+After that one line, paused hooks are completely silent and make **no** network request. Repeated pauses escalate: 15 minutes, then 1 hour, 6 hours, 24 hours.
+
+The pause is tied to the `apiUrl` + credential that earned it. `anyslate login` clears it immediately, and so does pointing `--api-url` somewhere else or swapping the token - fixing your setup is never punished by a wait. `anyslate doctor` always reports an active pause, and is itself never blocked by one.
+
+`ANYSLATE_MAX_CALLS_PER_MINUTE` is the last line of defence: a machine-wide ceiling (default 60/minute) on capture calls, so a runaway agent loop cannot become a load test. It is far above any real session; set it to `0` to disable.
+
 ### The two URL conventions - the one thing people get wrong
 
 AnySlate ships two clients and they want **different** URLs. This trips up nearly everyone:
@@ -237,7 +317,20 @@ Content is read as UTF-8. Binary files are not supported and are refused rather
 
 Two paths, one config file. `--token` selects the static path; its absence selects the browser flow.
 
-Both end the same way: one live request to `/mcp/auth/verify` that proves reachability, URL shape, token validity and scopes in a single round trip, then a `0600` write to `~/.anyslate/cli.json`. **On verification failure it writes nothing and exits non-zero.** Both are idempotent — they preserve the `apiUrl` and `handle` you already had (and re-normalize a stored `apiUrl` that carries a stale `/mcp` suffix).
+Both end the same way: one live request to `/mcp/auth/verify` that proves reachability, URL shape, token validity and scopes in a single round trip, then a `0600` write to `~/.anyslate/cli.json`. **On verification failure it writes nothing and exits non-zero.** Both preserve the `handle` you already had.
+
+**The sign-in target is explicit, never sticky.** Omitting `--api-url` always means
+**production**, even if your config currently points somewhere else — the stored value is
+deliberately not inherited. If it does point elsewhere, the CLI says so and shows you the
+flag to use:
+
+```
+anyslate: signing in to production (https://mcp.anyslate.io).
+anyslate: your config points at https://…workers.dev — pass `--api-url https://…workers.dev` to sign in there instead.
+```
+
+This matters because the target ends up in a URL printed to your terminal and opened in a
+browser. A short command should never quietly aim at a non-production host.
 
 A token missing the `memory:write` scope is a **warning**, not a block - but `anyslate hook` needs it, so heed it.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anyslate/cli",
-  "version": "0.3.0",
-  "description": "AnySlate CLI - lifecycle hooks, git/CI capture, and manual checkpoints for AI memory. Validates its connection at login, diagnoses itself with `anyslate doctor`, and fails open without failing silent.",
+  "version": "0.4.0",
+  "description": "AnySlate CLI - lifecycle hooks, git/CI capture, and manual checkpoints for AI memory. Validates its connection at login, diagnoses itself with `anyslate doctor`, backs off and circuit-breaks rather than retrying, and fails open without failing silent.",
   "type": "module",
   "bin": {
     "anyslate": "./bin/anyslate.mjs"

package/src/auth.mjs

@@ -9,7 +9,7 @@
 // The rules that fall out of that:
 //
 //   * Refresh PROACTIVELY, 5 minutes ahead of expiry, before the call. Waiting
-//     for the 401 spends a round trip and, on the hook path, risks the 15s
+//     for the 401 spends a round trip and, on the hook path, risks the timeout
 //     budget.
 //   * On a 401, refresh EXACTLY ONCE and retry EXACTLY ONCE. A loop here is a
 //     self-inflicted rate limit against an endpoint that is already refusing us.
@@ -19,10 +19,37 @@
 //     a process that must not hang.
 //   * Never throw. Callers are fail-open paths; a rejected promise here would
 //     become an uncaught exception in a hook and a non-zero exit.
+//
+// ---------------------------------------------------------------------------
+// 2026-08-02 — this file is where the client-side storm was possible
+// ---------------------------------------------------------------------------
+// "Refresh once, retry once" was already true PER PROCESS, and it was not
+// enough: every hook is a fresh process, so one machine with a stale refresh
+// token re-derived the same doomed `POST /oauth/token` + `POST /mcp` pair fifty
+// times a minute for hours, and no single invocation was misbehaving.
+//
+// Three additions close that, all funnelled through `callToolWithAuth` because
+// it is the one choke point every capture command already goes through:
+//
+//   1. a PERSISTED circuit breaker (guard.mjs) consulted BEFORE any credential
+//      is resolved — an open breaker costs the server exactly zero requests,
+//   2. bounded retry with jitter and a hard attempt cap (backoff.mjs), with
+//      `Retry-After` honoured rather than ignored,
+//   3. the refresh stays paired with the ONE call that needed it, even across
+//      retries — a retried call never re-mints.
 
 import { readConfigFile, updateConfigFile, withRefreshLock } from './credentials.mjs';
-import { callTool } from './mcp-client.mjs';
+import { callTool, formatCallFailure } from './mcp-client.mjs';
 import { discover, refreshAccessToken, REFRESH_SKEW_MS } from './oauth.mjs';
+import { DEFAULT_RETRY, classifyFailure, planRetry, retryAfterMsOf, sleep } from './backoff.mjs';
+import {
+  breakerGate,
+  breakerNotice,
+  ceilingNotice,
+  recordCallFailure,
+  recordCallSuccess,
+  reserveCallSlot,
+} from './guard.mjs';
 
 export { REFRESH_SKEW_MS };
 
@@ -105,12 +132,17 @@ async function refreshEndpoints({ oauth, root, fetchImpl }) {
  * "somebody else already refreshed" short-circuit hands the caller back the
  * very token that just 401'd, and the retry fails identically.
  *
+ * `lockWaitMs` exists for the hook path. The default 10s wait is fine for a
+ * user-initiated command but is 10s of a lifecycle hook standing in front of
+ * the user's editor, and a machine whose refreshes are all failing is exactly
+ * the machine where every hook queues behind the last one.
+ *
  * @param {{env: NodeJS.ProcessEnv, root: string, fetchImpl?: typeof fetch, now?: number,
- *          staleToken?: string|null}} opts
+ *          staleToken?: string|null, lockWaitMs?: number}} opts
  * @returns {Promise<{ok: true, token: string, rotated: boolean, oauth: object}
  *   | {ok: false, code: string, message: string}>}
  */
-export async function refreshCredentials({ env, root, fetchImpl = fetch, now, staleToken = null }) {
+export async function refreshCredentials({ env, root, fetchImpl = fetch, now, staleToken = null, lockWaitMs }) {
   return withRefreshLock(
     async () => {
       // Re-read INSIDE the lock. While we queued, a sibling hook may have done
@@ -180,7 +212,7 @@ export async function refreshCredentials({ env, root, fetchImpl = fetch, now, st
       }
       return { ok: true, token: next.access_token, rotated: true, oauth: next };
     },
-    { env },
+    { env, waitMs: lockWaitMs },
   );
 }
 
@@ -194,11 +226,12 @@ export async function refreshCredentials({ env, root, fetchImpl = fetch, now, st
  * static token also exists, we fall back to it rather than failing the call —
  * with `warning` set, so the caller can say so.
  *
- * @param {{cfg: object, env: NodeJS.ProcessEnv, fetchImpl?: typeof fetch, force?: boolean, now?: number}} opts
+ * @param {{cfg: object, env: NodeJS.ProcessEnv, fetchImpl?: typeof fetch, force?: boolean,
+ *          now?: number, lockWaitMs?: number}} opts
  * @returns {Promise<{ok: true, token: string, mode: 'env'|'oauth'|'static', refreshed: boolean, warning?: string}
  *   | {ok: false, code: string, message: string, mode: string}>}
  */
-export async function resolveBearer({ cfg, env, fetchImpl = fetch, force = false, now }) {
+export async function resolveBearer({ cfg, env, fetchImpl = fetch, force = false, now, lockWaitMs }) {
   if (cfg?.sources?.mcpToken === 'env' && cfg.mcpToken) {
     return { ok: true, token: cfg.mcpToken, mode: 'env', refreshed: false };
   }
@@ -216,6 +249,7 @@ export async function resolveBearer({ cfg, env, fetchImpl = fetch, force = false
       fetchImpl,
       now,
       staleToken: force ? (oauth.access_token ?? null) : null,
+      lockWaitMs,
     });
     if (refreshed.ok) {
       return { ok: true, token: refreshed.token, mode: 'oauth', refreshed: refreshed.rotated };
@@ -246,44 +280,137 @@ export async function resolveBearer({ cfg, env, fetchImpl = fetch, force = false
 }
 
 /**
- * `callTool` with the auth lifecycle wrapped around it: proactive refresh, then
- * at most one refresh-and-retry on a 401.
+ * `callTool` with the whole availability contract wrapped around it: the
+ * persisted breaker, the machine ceiling, proactive refresh, at most one
+ * refresh-and-retry on a 401, and bounded backoff on anything transient.
+ *
+ * The 401 retry is gated on `mode === 'oauth'`: a static token that 401s is
+ * revoked or mistyped, and re-sending it cannot help.
  *
- * The retry is gated on `mode === 'oauth'`: a static token that 401s is revoked
- * or mistyped, and re-sending it cannot help.
+ * ATTEMPTS ARE PROVABLY BOUNDED. The loop condition is a counter compared to
+ * `policy.maxAttempts + 1` — the `+1` is the single post-refresh retry, which
+ * must be allowed even on the hook path (`maxAttempts: 1`) because an access
+ * token that aged out mid-session is the normal case, not an anomaly. There is
+ * no `while (true)` and no recursion anywhere on this path.
  *
  * @param {{cfg: object, env: NodeJS.ProcessEnv, toolName: string, args: object,
- *          fetchImpl?: typeof fetch, timeoutMs?: number}} opts
+ *          fetchImpl?: typeof fetch, timeoutMs?: number, retry?: object,
+ *          lockWaitMs?: number}} opts
  * @returns {Promise<object>} the callTool result, plus `authMode` / `authWarning`,
- *   or an auth failure shaped like a callTool failure (`authError: true`).
+ *   or an auth failure shaped like a callTool failure (`authError: true`), or a
+ *   locally-refused call (`breakerOpen` / `rateCapped`) that never left the machine.
  */
-export async function callToolWithAuth({ cfg, env, toolName, args, fetchImpl, timeoutMs }) {
-  const first = await resolveBearer({ cfg, env, fetchImpl });
+export async function callToolWithAuth({ cfg, env, toolName, args, fetchImpl, timeoutMs, retry, lockWaitMs }) {
+  const policy = { ...DEFAULT_RETRY, ...(retry ?? {}) };
+
+  // Cheapest possible check first: an open breaker resolves no credential,
+  // opens no socket, and mints no token. That is the entire point — the
+  // incident cost ~50 requests a minute for days precisely because a client
+  // with no hope of succeeding still asked.
+  const gate = breakerGate({ cfg, env });
+  if (gate.open) {
+    return {
+      ok: false,
+      status: 0,
+      data: breakerNotice(gate),
+      raw: null,
+      breakerOpen: true,
+      breaker: gate,
+      authMode: cfg?.authMode ?? 'none',
+    };
+  }
+
+  const slot = reserveCallSlot({ env });
+  if (!slot.allowed) {
+    return { ok: false, status: 0, data: ceilingNotice(slot), raw: null, rateCapped: true, rateSlot: slot };
+  }
+
+  const first = await resolveBearer({ cfg, env, fetchImpl, lockWaitMs });
   if (!first.ok) {
-    return { ok: false, status: 0, data: first.message, raw: null, authError: true, authMode: first.mode };
+    const breaker = recordCallFailure({ cfg, env, kind: 'auth', code: first.code, detail: first.code });
+    return {
+      ok: false,
+      status: 0,
+      data: first.message,
+      raw: null,
+      authError: true,
+      authMode: first.mode,
+      breaker,
+    };
   }
 
-  const invoke = (token) =>
-    callTool({ apiUrl: cfg.apiUrl, token, toolName, args, fetchImpl, timeoutMs });
+  let token = first.token;
+  let mode = first.mode;
+  let warning = first.warning;
+  // A proactive refresh already spent this call's one re-mint.
+  let refreshSpent = first.refreshed;
+  let retried = false;
 
-  let res = await invoke(first.token);
-  res.authMode = first.mode;
-  if (first.warning) res.authWarning = first.warning;
+  const hardCap = policy.maxAttempts + 1;
+  let attempt = 0;
+  let spentDelayMs = 0;
+  let res = null;
 
-  const retryable = !res.ok && res.status === 401 && first.mode === 'oauth' && !first.refreshed;
-  if (!retryable) return res;
+  while (attempt < hardCap) {
+    attempt += 1;
+    res = await callTool({ apiUrl: cfg.apiUrl, token, toolName, args, fetchImpl, timeoutMs });
+    res.authMode = mode;
+    if (warning) res.authWarning = warning;
+    if (retried) res.authRetried = true;
+    if (attempt > 1) res.attempts = attempt;
 
-  const second = await resolveBearer({ cfg, env, fetchImpl, force: true });
-  if (!second.ok) {
-    res.authError = true;
-    res.authRefreshFailed = second.message;
+    if (res.ok) break;
+
+    const kind = classifyFailure(res);
+
+    // One refresh, paired with the call that needed it — not with each attempt.
+    // Re-minting per attempt is what turned a dead credential into two requests
+    // per hook instead of one.
+    if (kind === 'auth' && mode === 'oauth' && !refreshSpent) {
+      refreshSpent = true;
+      const second = await resolveBearer({ cfg, env, fetchImpl, force: true, lockWaitMs });
+      if (!second.ok) {
+        res.authError = true;
+        res.authRefreshFailed = second.message;
+        res.authCode = second.code;
+        break;
+      }
+      token = second.token;
+      mode = second.mode;
+      warning = second.warning;
+      retried = true;
+      continue;
+    }
+
+    const retryAfterMs = retryAfterMsOf(res);
+    const plan = planRetry({ kind, attempt, spentDelayMs, retryAfterMs, policy });
+    if (!plan.retry) break;
+    await sleep(plan.delayMs);
+    spentDelayMs += plan.delayMs;
+  }
+
+  if (res.ok) {
+    recordCallSuccess({ cfg, env });
     return res;
   }
-  const retried = await invoke(second.token);
-  retried.authMode = second.mode;
-  retried.authRetried = true;
-  if (second.warning) retried.authWarning = second.warning;
-  return retried;
+
+  const kind = classifyFailure(res);
+  res.breaker = recordCallFailure({
+    cfg,
+    env,
+    kind,
+    code: res.authCode,
+    detail: failureDetail(res, kind),
+    retryAfterMs: retryAfterMsOf(res),
+  });
+  return res;
+}
+
+/** A short, token-free reason to persist alongside the breaker state. */
+function failureDetail(res, kind) {
+  if (kind === 'auth' && res.authRefreshFailed) return 'OAuth refresh failed';
+  if (res.networkError) return typeof res.data === 'string' ? res.data : 'request failed';
+  return `HTTP ${res.status}`;
 }
 
 /**
@@ -308,3 +435,33 @@ export function formatAuthFailure(prefix, res) {
   }
   return null;
 }
+
+/**
+ * The failure line for a call this machine refused to make.
+ *
+ * `formatCallFailure` would render `server 0 — …` for these, inventing an HTTP
+ * exchange that never happened. Both cases are local decisions and must read
+ * that way, or the user goes looking for a server problem that is not there.
+ *
+ * @param {string} prefix
+ * @param {object} res
+ * @returns {string|null}
+ */
+export function formatLocalRefusal(prefix, res) {
+  if (res?.breakerOpen || res?.rateCapped) {
+    return `${prefix}: ${typeof res.data === 'string' ? res.data : JSON.stringify(res.data)}\n`;
+  }
+  return null;
+}
+
+/**
+ * The one failure formatter every capture command uses, so a new failure mode
+ * can never reach a command that does not know how to render it.
+ *
+ * @param {string} prefix
+ * @param {object} res
+ * @returns {string}
+ */
+export function formatFailure(prefix, res) {
+  return formatLocalRefusal(prefix, res) ?? formatAuthFailure(prefix, res) ?? formatCallFailure(prefix, res);
+}