@anyslate/cli 0.3.1 → 0.4.1

package/README.md

@@ -196,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`.
@@ -214,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:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@anyslate/cli",
-  "version": "0.3.1",
-  "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.1",
+  "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 };
 
@@ -86,15 +113,59 @@ export function hasOauthCredentials(oauth) {
  * @returns {Promise<{ok: true, tokenEndpoint: string, resource: string}
  *   | {ok: false, code: string, message: string}>}
  */
-async function refreshEndpoints({ oauth, root, fetchImpl }) {
+async function refreshEndpoints({ oauth, root, fetchImpl, timeoutMs }) {
   if (oauth?.root === root && oauth?.token_endpoint && oauth?.resource) {
     return { ok: true, tokenEndpoint: oauth.token_endpoint, resource: oauth.resource };
   }
-  const found = await discover({ root, fetchImpl });
+  const found = await discover({ root, fetchImpl, timeoutMs });
   if (!found.ok) return found;
   return { ok: true, tokenEndpoint: found.tokenEndpoint, resource: found.resource };
 }
 
+/**
+ * Prefer a peer's already-persisted OAuth session over minting a new one.
+ *
+ * Refresh tokens are single-use server-side. Concurrent hooks (each a fresh
+ * process) that both redeem the same refresh token leave the loser with
+ * `invalid_grant` even though a usable access token is already on disk —
+ * and historically that loser opened the circuit breaker and told the user
+ * to re-login. Reading disk again closes that hole.
+ *
+ * @param {{env: NodeJS.ProcessEnv, staleToken?: string|null, now?: number,
+ *          startingRefresh?: string|null}} opts
+ * @returns {{ok: true, token: string, rotated: false, oauth: object}|null}
+ */
+export function readPeerRefreshedCredentials({ env, staleToken = null, now = Date.now(), startingRefresh = null }) {
+  const disk = readConfigFile(env);
+  const oauth = disk.oauth && typeof disk.oauth === 'object' ? disk.oauth : null;
+  if (!oauth?.access_token) return null;
+
+  // A peer rotated when the refresh token on disk changed, or when the access
+  // token differs from the one we are replacing.
+  const refreshMoved =
+    startingRefresh && oauth.refresh_token && oauth.refresh_token !== startingRefresh;
+  const accessMoved = staleToken ? oauth.access_token !== staleToken : false;
+  if (!refreshMoved && !accessMoved && staleToken) return null;
+
+  // Accept any not-hard-expired peer token. Requiring the full 5-minute skew
+  // would reject a peer refresh that landed seconds ago for no good reason.
+  if (isExpired(oauth, now)) return null;
+  if (staleToken && oauth.access_token === staleToken && !refreshMoved) return null;
+
+  return { ok: true, token: oauth.access_token, rotated: false, oauth };
+}
+
+const sleepMs = (ms) => new Promise((r) => setTimeout(r, ms));
+
+/** Default lock wait when the caller does not override (interactive commands). */
+const LOCK_WAIT_DEFAULT = 10_000;
+
+/** Milliseconds left before an absolute deadline, or null when unbounded. */
+export function remainingMs(deadline, now = Date.now()) {
+  if (deadline == null || !Number.isFinite(deadline)) return null;
+  return Math.max(0, deadline - now);
+}
+
 /**
  * Perform one refresh, under the lock, persisting the rotated token.
  *
@@ -105,14 +176,42 @@ 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 too long for a lifecycle hook standing in
+ * front of the user's editor.
+ *
+ * When the lock is NOT held (wait timed out), we poll disk for a peer refresh
+ * instead of racing the single-use refresh token. Only if nothing usable
+ * appears do we attempt the network refresh — and on `invalid_grant` we
+ * re-check disk one last time before declaring the session dead.
+ *
+ * `deadline` (epoch ms) caps lock wait, unlocked peer-poll, discovery, and the
+ * refresh HTTP call so a hook's advertised budget cannot be exceeded before
+ * the MCP call even starts. When omitted, behaviour matches the unbounded
+ * interactive path (15s per HTTP call).
+ *
  * @param {{env: NodeJS.ProcessEnv, root: string, fetchImpl?: typeof fetch, now?: number,
- *          staleToken?: string|null}} opts
+ *          staleToken?: string|null, lockWaitMs?: number, deadline?: number|null}} 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,
+  deadline = null,
+}) {
+  const lockCap = remainingMs(deadline);
+  const effectiveLockWait =
+    lockCap == null
+      ? lockWaitMs
+      : Math.min(typeof lockWaitMs === 'number' ? lockWaitMs : LOCK_WAIT_DEFAULT, lockCap);
+
   return withRefreshLock(
-    async () => {
+    async ({ held }) => {
       // Re-read INSIDE the lock. While we queued, a sibling hook may have done
       // the whole refresh already — redeeming our (now-replaced) refresh token
       // would fail and, worse, would overwrite theirs.
@@ -137,18 +236,107 @@ export async function refreshCredentials({ env, root, fetchImpl = fetch, now, st
         };
       }
 
-      const endpoints = await refreshEndpoints({ oauth, root, fetchImpl });
+      const startingRefresh = oauth.refresh_token;
+
+      // Unlocked callers must not stampede the token endpoint. Poll briefly
+      // for a peer that held the lock; if one lands, we are done. Poll time is
+      // taken from the SHARED deadline (not an extra lockWait on top).
+      if (!held) {
+        const rem = remainingMs(deadline);
+        const pollMs =
+          rem == null
+            ? Math.min(typeof lockWaitMs === 'number' ? lockWaitMs : 2_000, 1_500)
+            : Math.min(rem, 500);
+        const pollDeadline = Date.now() + pollMs;
+        while (Date.now() < pollDeadline) {
+          await sleepMs(50);
+          const peer = readPeerRefreshedCredentials({
+            env,
+            staleToken: staleToken ?? oauth.access_token,
+            now,
+            startingRefresh,
+          });
+          if (peer) return peer;
+        }
+      }
+
+      // Re-read after the poll — a peer may have finished in the last tick.
+      const latest = readConfigFile(env);
+      const latestOauth = latest.oauth && typeof latest.oauth === 'object' ? latest.oauth : oauth;
+      if (
+        latestOauth?.access_token &&
+        latestOauth.access_token !== (staleToken ?? oauth.access_token) &&
+        !isExpiring(latestOauth, REFRESH_SKEW_MS, now)
+      ) {
+        return { ok: true, token: latestOauth.access_token, rotated: false, oauth: latestOauth };
+      }
+      if (!latestOauth?.refresh_token) {
+        return {
+          ok: false,
+          code: 'no_refresh_token',
+          message: `anyslate: the stored OAuth session has no refresh token and its access token has expired. ${RELOGIN_HINT}`,
+        };
+      }
+
+      const httpTimeout = remainingMs(deadline) ?? 15_000;
+      if (httpTimeout <= 0) {
+        const peer = readPeerRefreshedCredentials({
+          env,
+          staleToken: staleToken ?? oauth.access_token,
+          now,
+          startingRefresh,
+        });
+        if (peer) return peer;
+        return {
+          ok: false,
+          code: 'refresh_timeout',
+          message: `anyslate: timed out before the OAuth refresh could run. ${RELOGIN_HINT}`,
+        };
+      }
+
+      const endpoints = await refreshEndpoints({
+        oauth: latestOauth,
+        root,
+        fetchImpl,
+        timeoutMs: httpTimeout,
+      });
       if (!endpoints.ok) return endpoints;
 
+      const refreshTimeout = remainingMs(deadline) ?? httpTimeout;
+      if (refreshTimeout <= 0) {
+        const peer = readPeerRefreshedCredentials({
+          env,
+          staleToken: staleToken ?? oauth.access_token,
+          now,
+          startingRefresh,
+        });
+        if (peer) return peer;
+        return {
+          ok: false,
+          code: 'refresh_timeout',
+          message: `anyslate: timed out before the OAuth refresh could run. ${RELOGIN_HINT}`,
+        };
+      }
+
       const res = await refreshAccessToken({
         tokenEndpoint: endpoints.tokenEndpoint,
-        refreshToken: oauth.refresh_token,
-        clientId: oauth.client_id,
+        refreshToken: latestOauth.refresh_token,
+        clientId: latestOauth.client_id,
         resource: endpoints.resource,
         fetchImpl,
         now,
+        timeoutMs: refreshTimeout,
       });
       if (!res.ok) {
+        // Loser of a refresh race: peer already rotated and persisted. Prefer
+        // their tokens over "run anyslate login" + circuit-breaker pause.
+        const peer = readPeerRefreshedCredentials({
+          env,
+          staleToken: staleToken ?? oauth.access_token,
+          now,
+          startingRefresh,
+        });
+        if (peer) return peer;
         return {
           ok: false,
           code: res.code || 'refresh_failed',
@@ -160,10 +348,10 @@ export async function refreshCredentials({ env, root, fetchImpl = fetch, now, st
       // the instant the server answered; a crash between here and the next
       // write would lose the only usable credential.
       const next = {
-        ...oauth,
+        ...latestOauth,
         access_token: res.tokens.access_token,
         // A response that omits refresh_token means "keep the one you have".
-        refresh_token: res.tokens.refresh_token || oauth.refresh_token,
+        refresh_token: res.tokens.refresh_token || latestOauth.refresh_token,
         expires_at: res.tokens.expires_at,
         token_endpoint: endpoints.tokenEndpoint,
         resource: endpoints.resource,
@@ -180,7 +368,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: effectiveLockWait },
   );
 }
 
@@ -194,11 +382,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, deadline?: number|null}} 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, deadline = null }) {
   if (cfg?.sources?.mcpToken === 'env' && cfg.mcpToken) {
     return { ok: true, token: cfg.mcpToken, mode: 'env', refreshed: false };
   }
@@ -216,6 +405,8 @@ export async function resolveBearer({ cfg, env, fetchImpl = fetch, force = false
       fetchImpl,
       now,
       staleToken: force ? (oauth.access_token ?? null) : null,
+      lockWaitMs,
+      deadline,
     });
     if (refreshed.ok) {
       return { ok: true, token: refreshed.token, mode: 'oauth', refreshed: refreshed.rotated };
@@ -246,44 +437,162 @@ 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 ?? {}) };
+
+  // When the caller names a timeout (hooks: 5s), treat it as a WALL budget for
+  // refresh + MCP call combined — not "15s refresh then 5s call". Interactive
+  // commands leave timeoutMs undefined and keep the unbounded refresh path.
+  const deadline = typeof timeoutMs === 'number' && timeoutMs > 0 ? Date.now() + timeoutMs : null;
+
+  // 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, deadline });
   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;
+    const callTimeout = remainingMs(deadline) ?? timeoutMs;
+    if (deadline != null && (callTimeout == null || callTimeout <= 0)) {
+      res = {
+        ok: false,
+        status: 0,
+        data: `anyslate: timed out after ${timeoutMs}ms (spent on credential refresh).`,
+        raw: null,
+        networkError: true,
+        authMode: mode,
+      };
+      if (warning) res.authWarning = warning;
+      break;
+    }
+    res = await callTool({
+      apiUrl: cfg.apiUrl,
+      token,
+      toolName,
+      args,
+      fetchImpl,
+      timeoutMs: callTimeout,
+    });
+    res.authMode = mode;
+    if (warning) res.authWarning = warning;
+    if (retried) res.authRetried = true;
+    if (attempt > 1) res.attempts = attempt;
+
+    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, deadline });
+      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 second = await resolveBearer({ cfg, env, fetchImpl, force: true });
-  if (!second.ok) {
-    res.authError = true;
-    res.authRefreshFailed = second.message;
+    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 +617,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);
+}