@anyslate/cli 0.3.1 → 0.4.0

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.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);
+}

package/src/backoff.mjs

@@ -0,0 +1,178 @@
+// Retry policy — the client half of the 2026-08-02 database overload.
+//
+// The request tail from that outage is ONE machine running anyslate-cli/0.3.1
+// with a stale refresh token, emitting `POST /oauth/token` followed by
+// `POST /mcp` roughly fifty times a minute, for hours. Nothing in the client
+// ever said "wait": an auth failure re-minted a token and re-issued the call
+// immediately, so the only ceiling on request rate was how fast a process could
+// loop. When the database then answered "overloaded", every client retried at
+// once and deepened the overload.
+//
+// Nothing here is about making a call succeed. It is about making failure cheap
+// for the server:
+//
+//   * a HARD attempt cap per process — no path in this CLI may loop unbounded,
+//   * exponential backoff with jitter between attempts, so a fleet recovering
+//     from one outage does not resynchronise into the next one,
+//   * `Retry-After` on a 429/503 OVERRIDES our own schedule, and when the
+//     server asks for longer than the whole retry budget we do NOT sleep on it —
+//     the wait is handed to the circuit breaker (guard.mjs), the process exits,
+//     and the *next* process is the one that honours it. Sleeping instead would
+//     hold a hook open across the user's editor.
+//
+// Pure module: no I/O, no ambient timers, injectable clock/randomness, so the
+// policy is unit-testable without a server.
+
+/**
+ * The default budget, used by the user-initiated commands (`checkpoint`,
+ * `upload-artifact`) where an exit code is meaningful and a second or two of
+ * waiting is cheaper than a lost capture.
+ */
+export const DEFAULT_RETRY = {
+  maxAttempts: 3,
+  baseDelayMs: 500,
+  maxDelayMs: 8_000,
+  /** Ceiling on time spent sleeping across ALL attempts of one call. */
+  maxTotalDelayMs: 15_000,
+  /** A `Retry-After` longer than this is never slept on — the breaker holds it. */
+  maxRetryAfterSleepMs: 5_000,
+};
+
+/**
+ * Hooks get NO retries at all.
+ *
+ * A hook fires on every tool call, in front of the user's editor, and the event
+ * it carries is one row in an activity feed. Re-sending it doubles the request
+ * rate the incident was made of, in exchange for a row nobody will miss. One
+ * attempt, short timeout, move on.
+ */
+export const HOOK_RETRY = {
+  ...DEFAULT_RETRY,
+  maxAttempts: 1,
+  maxTotalDelayMs: 0,
+};
+
+/**
+ * Why a call failed, in the only four buckets that change what we do next.
+ *
+ *   auth      — 401/invalid_token. One paired refresh may fix it; repetition
+ *               never will, so this is what trips the breaker.
+ *   throttled — 429/503. The server named a wait; honour it, never retry inside it.
+ *   transient — 5xx, or the request never landed. Worth one backed-off retry.
+ *   fatal     — 4xx we caused (bad payload, unknown kind, denied handle). The
+ *               server already spent the work; re-sending is pure waste.
+ *
+ * @param {{ok?: boolean, status?: number, networkError?: boolean}} res  a callTool result
+ * @returns {'auth'|'throttled'|'transient'|'fatal'|null} null when the call succeeded
+ */
+export function classifyFailure(res) {
+  if (!res || res.ok) return null;
+  if (res.networkError) return 'transient';
+  const status = Number(res.status);
+  if (status === 401) return 'auth';
+  if (status === 429 || status === 503) return 'throttled';
+  if (status === 0 || status >= 500) return 'transient';
+  return 'fatal';
+}
+
+/**
+ * The wait the server asked for, in milliseconds.
+ *
+ * `callTool` already parses `Retry-After` and the body's `retry_after_seconds`
+ * into `retryAfterSeconds` (both the transport 429 and the tool-level one), so
+ * this only has to normalise it.
+ *
+ * @param {{retryAfterSeconds?: number|null}} res
+ * @returns {number|null}
+ */
+export function retryAfterMsOf(res) {
+  const seconds = Number(res?.retryAfterSeconds);
+  if (!Number.isFinite(seconds) || seconds <= 0) return null;
+  return Math.round(seconds * 1000);
+}
+
+/**
+ * Exponential backoff with jitter.
+ *
+ * Equal jitter (half fixed, half random) rather than full jitter: it still
+ * decorrelates a fleet of clients that all failed on the same server-side
+ * second, while guaranteeing that attempt N really does wait longer than
+ * attempt N-1. Full jitter can draw ~0ms and re-send instantly, which is the
+ * behaviour this module exists to remove.
+ *
+ * @param {number} attempt  1-based; the delay BEFORE attempt+1
+ * @param {typeof DEFAULT_RETRY} policy
+ * @param {() => number} [random]
+ * @returns {number}
+ */
+export function backoffDelayMs(attempt, policy = DEFAULT_RETRY, random = Math.random) {
+  const exponential = policy.baseDelayMs * 2 ** Math.max(0, attempt - 1);
+  const capped = Math.min(policy.maxDelayMs, exponential);
+  return Math.round(capped / 2 + random() * (capped / 2));
+}
+
+/**
+ * The whole retry decision for one failed attempt.
+ *
+ * Returns `retry: false` for every reason a request must NOT be repeated, and
+ * says which one — the caller records that reason, so a machine that stops
+ * retrying can explain itself instead of just going quiet.
+ *
+ * @param {object} opts
+ * @param {'auth'|'throttled'|'transient'|'fatal'|null} opts.kind
+ * @param {number} opts.attempt          how many attempts have already been made
+ * @param {number} [opts.spentDelayMs]   time already slept on this call
+ * @param {number|null} [opts.retryAfterMs]
+ * @param {typeof DEFAULT_RETRY} [opts.policy]
+ * @param {() => number} [opts.random]
+ * @returns {{retry: boolean, delayMs: number, reason: string}}
+ */
+export function planRetry({
+  kind,
+  attempt,
+  spentDelayMs = 0,
+  retryAfterMs = null,
+  policy = DEFAULT_RETRY,
+  random = Math.random,
+}) {
+  if (kind !== 'throttled' && kind !== 'transient') {
+    return { retry: false, delayMs: 0, reason: kind === 'auth' ? 'auth' : 'not_retryable' };
+  }
+  if (attempt >= policy.maxAttempts) {
+    return { retry: false, delayMs: 0, reason: 'attempt_cap' };
+  }
+
+  // A named wait always wins over our schedule — but only if we can afford to
+  // sit through it. A server that says "60s" gets an exiting process and a
+  // persisted cool-down, not a hook blocking the editor for a minute.
+  if (retryAfterMs != null) {
+    if (retryAfterMs > policy.maxRetryAfterSleepMs) {
+      return { retry: false, delayMs: 0, reason: 'retry_after_too_long' };
+    }
+    if (spentDelayMs + retryAfterMs > policy.maxTotalDelayMs) {
+      return { retry: false, delayMs: 0, reason: 'delay_budget' };
+    }
+    return { retry: true, delayMs: retryAfterMs, reason: 'retry_after' };
+  }
+
+  const delayMs = backoffDelayMs(attempt, policy, random);
+  if (spentDelayMs + delayMs > policy.maxTotalDelayMs) {
+    return { retry: false, delayMs: 0, reason: 'delay_budget' };
+  }
+  return { retry: true, delayMs, reason: 'backoff' };
+}
+
+/**
+ * Deliberately a REF'd timer. An `unref`ed one lets Node drain its event loop
+ * and exit mid-backoff, which would turn "wait, then retry" into "exit 0 having
+ * silently dropped the call". The bound on how long this can hold a process is
+ * `maxTotalDelayMs`, not the timer flag.
+ *
+ * @param {number} ms
+ * @returns {Promise<void>}
+ */
+export function sleep(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}

package/src/commands/checkpoint.mjs

@@ -12,8 +12,8 @@
 // stdout carries results only. Every error goes to stderr.
 
 import { loadConfig, requireToken, apiUrlNormalizationNotice, DISABLED_NOTICE } from '../config.mjs';
-import { formatCallFailure } from '../mcp-client.mjs';
-import { callToolWithAuth, formatAuthFailure } from '../auth.mjs';
+import { callToolWithAuth, formatFailure } from '../auth.mjs';
+import { markNotified } from '../guard.mjs';
 import { recordRun } from '../runlog.mjs';
 import { VERSION } from '../version.mjs';
 import { makeIo } from '../io.mjs';
@@ -84,8 +84,18 @@ export async function runCheckpoint(argv, deps = {}) {
       fetchImpl: deps.fetchImpl,
     });
     if (res.authWarning) err.write(`${res.authWarning}\n`);
+
+    // A paused breaker or the local ceiling means no request was made, so there
+    // is no round trip to record. Unlike `hook` this is a command the user just
+    // typed, so it always says why rather than staying quiet.
+    if (res.breakerOpen || res.rateCapped) {
+      err.write(formatFailure('anyslate checkpoint', res));
+      if (res.breakerOpen) markNotified(env);
+      return 1;
+    }
+
     if (!res.ok) {
-      const message = formatAuthFailure('anyslate checkpoint', res) ?? formatCallFailure('anyslate checkpoint', res);
+      const message = formatFailure('anyslate checkpoint', res);
       err.write(message);
       recordRun(
         {

package/src/commands/doctor.mjs

@@ -27,6 +27,7 @@ import {
 } from '../config.mjs';
 import { checkUrlShape, hasWriteScope, isValidTokenFormat, probeVerify, tokenPreview } from '../verify.mjs';
 import { hasOauthCredentials, isExpired, minutesUntilExpiry, resolveBearer } from '../auth.mjs';
+import { breakerGate, guardPath } from '../guard.mjs';
 import { lastRunPath, readLastRun } from '../runlog.mjs';
 import { callTool } from '../mcp-client.mjs';
 import { VERSION, USER_AGENT } from '../version.mjs';
@@ -128,6 +129,24 @@ export async function runDoctor(argv = [], deps = {}) {
     }
   }
 
+  // ---- 1b. Circuit breaker ------------------------------------------------
+  // Pure local state, so it is answerable when the service is down — which is
+  // exactly when it will be open. It sits this early because "capture is paused
+  // and no request is being made" reframes every check below it: the token may
+  // be perfect and capture still dead until the pause expires or `login` runs.
+  // `doctor` itself is never gated by it; diagnosing must always be possible.
+  const pause = breakerGate({ cfg, env });
+  if (pause.open) {
+    add(
+      WARN,
+      'breaker',
+      `Capture is paused until ${pause.until} (${pause.reason}${pause.detail ? `: ${pause.detail}` : ''}) — no requests are being sent.`,
+      pause.reason === 'auth'
+        ? 'Run `anyslate login` to sign in again; that clears the pause immediately.'
+        : `The pause clears itself, or delete ${guardPath(env)} to clear it now.`,
+    );
+  }
+
   // ---- 2. Token present --------------------------------------------------
   // "Present" now has three shapes: an env/static token, a live OAuth access
   // token, or OAuth credentials whose access token has aged out but which carry

package/src/commands/hook.mjs

@@ -17,10 +17,19 @@
 // Tool-level errors (HTTP 200 + result.isError) now count as failures and are
 // therefore visible to --strict — previously a 403 handle denial printed
 // nothing and exited 0.
+//
+// COST CEILING (2026-08-02). This command is the one the incident was made of:
+// PostToolUse fires per tool call, so a busy session runs it dozens of times a
+// minute, and every run is a fresh process with no memory of the last. It is
+// therefore the strictest caller in the CLI — one attempt, never a retry, a
+// short timeout, and a persisted breaker that makes a hopeless call cost the
+// server nothing at all. A dropped activity row is one line in a feed; a hook
+// that retries is a doubled request rate in front of the user's editor.
 
 import { loadConfig, requireToken, apiUrlNormalizationNotice, DISABLED_NOTICE } from '../config.mjs';
-import { formatCallFailure } from '../mcp-client.mjs';
-import { callToolWithAuth, formatAuthFailure } from '../auth.mjs';
+import { callToolWithAuth, formatFailure } from '../auth.mjs';
+import { HOOK_RETRY } from '../backoff.mjs';
+import { markNotified } from '../guard.mjs';
 import { buildHookSubmission, parseHookEvent } from '../hooks.mjs';
 import { readStdin, stdinTimeoutFromEnv } from '../stdin.mjs';
 import { recordRun, shouldEscalate, escalationPayload } from '../runlog.mjs';
@@ -29,6 +38,27 @@ import { makeIo } from '../io.mjs';
 
 const ALLOWED = new Set(['session-start', 'post-tool-use', 'stop']);
 
+/**
+ * Total budget for the two requests a submission costs (initialize +
+ * tools/call). Deliberately far below the 15s every other command gets: a hook
+ * runs in front of a human, and a slow server must not become a slow editor.
+ * `ANYSLATE_HOOK_TIMEOUT_MS` raises it for pathologically slow links.
+ */
+export const HOOK_TIMEOUT_MS = 5_000;
+
+/**
+ * How long a hook will queue behind another process's token refresh. The shared
+ * default is 10s, which on a machine where every refresh is failing means every
+ * hook waits the full ten seconds to learn nothing.
+ */
+export const HOOK_LOCK_WAIT_MS = 2_000;
+
+/** @param {NodeJS.ProcessEnv} env */
+function hookTimeoutMs(env) {
+  const raw = Number(env.ANYSLATE_HOOK_TIMEOUT_MS);
+  return Number.isFinite(raw) && raw > 0 ? raw : HOOK_TIMEOUT_MS;
+}
+
 /**
  * @param {string[]} argv  arguments after `hook`
  * @param {{env?: NodeJS.ProcessEnv, fetchImpl?: typeof fetch}} [deps]
@@ -107,10 +137,31 @@ export async function runHook(argv, deps = {}) {
       toolName: 'activity_submit',
       args,
       fetchImpl: deps.fetchImpl,
+      timeoutMs: hookTimeoutMs(env),
+      retry: HOOK_RETRY,
+      lockWaitMs: HOOK_LOCK_WAIT_MS,
     });
     if (res.authWarning) err.write(`${res.authWarning}\n`);
+
+    // A locally-refused call made no request, so there is no run outcome to
+    // record — the run log is a record of round trips, and filling it with
+    // "we did not try" would bury the failure that caused the pause. The user
+    // is told once per pause; after that a paused hook is completely silent,
+    // which is the whole contract: cost the server nothing, cost the user
+    // nothing, keep the fix on screen exactly once.
+    if (res.breakerOpen || res.rateCapped) {
+      if (!res.breakerOpen || res.breaker?.noticeDue) {
+        err.write(formatFailure(prefix, res));
+        if (res.breakerOpen) {
+          markNotified(env);
+          escalatePause(out, sub, res);
+        }
+      }
+      return strict ? 1 : 0;
+    }
+
     if (!res.ok) {
-      return fail(formatAuthFailure(prefix, res) ?? formatCallFailure(prefix, res), {
+      return fail(formatFailure(prefix, res), {
         status: res.status,
         isError: !!res.isError,
         networkError: !!res.networkError,
@@ -142,6 +193,23 @@ function escalateIfNeeded(out, sub, state, error) {
   out.write(escalationPayload({ ...state, error }));
 }
 
+/**
+ * A paused breaker is the one state where stderr is guaranteed to be read by
+ * nobody AND the fix is a single command. Say it through the channel Claude
+ * Code renders, once, at the only point in a session where acting on it is
+ * cheap.
+ */
+function escalatePause(out, sub, res) {
+  if (sub !== 'session-start') return;
+  out.write(
+    escalationPayload({
+      consecutiveFailures: 0,
+      failingSince: null,
+      error: typeof res.data === 'string' ? res.data : 'capture paused',
+    }),
+  );
+}
+
 /** @param {string[]} argv */
 function parseFlags(argv) {
   const out = { strict: false };

package/src/commands/login.mjs

@@ -26,6 +26,7 @@ import { join } from 'node:path';
 import { DEFAULT_API_URL, anyslateDir, isCaptureDisabled, normalizeApiRoot } from '../config.mjs';
 import { checkUrlShape, isValidTokenFormat, probeVerify, scopeWarning, tokenPreview } from '../verify.mjs';
 import { readConfigFile, writeConfigFile } from '../credentials.mjs';
+import { clearBreaker } from '../guard.mjs';
 import {
   DEFAULT_CALLBACK_TIMEOUT_S,
   REGISTERED_REDIRECT_URI,
@@ -199,6 +200,10 @@ async function runTokenLogin(flags, deps) {
     err.write(`anyslate login: write failed (${e?.message ?? e})\n`);
     return 1;
   }
+  // A pause earned by the credential the user has just replaced must not
+  // outlive it — otherwise the documented fix ("run `anyslate login`") appears
+  // to do nothing for the next fifteen minutes.
+  clearBreaker(env);
 
   out.write(`anyslate: wrote ${path}\n`);
   out.write(`  apiUrl: ${next.apiUrl}\n`);
@@ -386,6 +391,8 @@ async function runOauthLogin(flags, deps) {
       err.write(`anyslate login: write failed (${e?.message ?? e})\n`);
       return 1;
     }
+    // See the static path: a fresh sign-in cancels the pause its predecessor earned.
+    clearBreaker(env);
 
     out.write(`anyslate: wrote ${path}\n`);
     out.write(`  apiUrl: ${root}\n`);

package/src/commands/logout.mjs

@@ -22,6 +22,7 @@
 import { join } from 'node:path';
 import { anyslateDir, loadConfig } from '../config.mjs';
 import { readConfigFile, writeConfigFile } from '../credentials.mjs';
+import { clearBreaker } from '../guard.mjs';
 import { discover, revocationEndpointFor, revokeToken } from '../oauth.mjs';
 import { makeIo } from '../io.mjs';
 
@@ -101,6 +102,9 @@ export async function runLogout(argv = [], deps = {}) {
     err.write(`anyslate logout: could not update ${path} (${e?.message ?? e})\n`);
     return 1;
   }
+  // The breaker is state about a credential that no longer exists. Leaving it
+  // behind would make the next `login` look broken.
+  clearBreaker(env);
 
   const cleared = [hadOauth && 'OAuth session', hadStatic && 'static token'].filter(Boolean).join(' and ');
   out.write(`anyslate: cleared the ${cleared} from ${path}.\n`);

package/src/commands/upload-artifact.mjs

@@ -16,8 +16,8 @@
 import { readFileSync } from 'node:fs';
 import { basename } from 'node:path';
 import { loadConfig, requireToken, apiUrlNormalizationNotice, DISABLED_NOTICE } from '../config.mjs';
-import { formatCallFailure } from '../mcp-client.mjs';
-import { callToolWithAuth, formatAuthFailure } from '../auth.mjs';
+import { callToolWithAuth, formatFailure } from '../auth.mjs';
+import { markNotified } from '../guard.mjs';
 import { readStdin, stdinTimeoutFromEnv } from '../stdin.mjs';
 import { recordRun } from '../runlog.mjs';
 import { VERSION } from '../version.mjs';
@@ -143,9 +143,17 @@ export async function runUploadArtifact(argv, deps = {}) {
       fetchImpl: deps.fetchImpl,
     });
     if (res.authWarning) err.write(`${res.authWarning}\n`);
+
+    // No request left the machine, so nothing is recorded as a round trip. See
+    // the same branch in checkpoint.mjs.
+    if (res.breakerOpen || res.rateCapped) {
+      err.write(formatFailure('anyslate upload-artifact', res));
+      if (res.breakerOpen) markNotified(env);
+      return 1;
+    }
+
     if (!res.ok) {
-      const message =
-        formatAuthFailure('anyslate upload-artifact', res) ?? formatCallFailure('anyslate upload-artifact', res);
+      const message = formatFailure('anyslate upload-artifact', res);
       err.write(message);
       recordRun(
         {

package/src/credentials.mjs

@@ -40,12 +40,21 @@ export function cliConfigPath(env = process.env) {
 }
 
 /**
+ * Read any JSON file out of `~/.anyslate`, tolerating every way it can be
+ * missing or malformed.
+ *
+ * Generic because the credential file is no longer the only state the CLI keeps
+ * across processes: the circuit breaker (guard.mjs) has to survive a process
+ * exit for the same reason a refresh token does, and it must inherit the same
+ * atomic-write discipline rather than growing its own.
+ *
+ * @param {string} name  file name inside the AnySlate directory
  * @param {NodeJS.ProcessEnv} [env]
  * @returns {Record<string, any>}
  */
-export function readConfigFile(env = process.env) {
+export function readJsonFile(name, env = process.env) {
   try {
-    const parsed = JSON.parse(readFileSync(cliConfigPath(env), 'utf8'));
+    const parsed = JSON.parse(readFileSync(join(anyslateDir(env), name), 'utf8'));
     return parsed && typeof parsed === 'object' ? parsed : {};
   } catch {
     return {};
@@ -55,15 +64,16 @@ export function readConfigFile(env = process.env) {
 /**
  * Serialize + rename. Never writes the target path in place.
  *
+ * @param {string} name
  * @param {Record<string, any>} next
  * @param {NodeJS.ProcessEnv} [env]
  * @returns {string} the path written
  */
-export function writeConfigFile(next, env = process.env) {
+export function writeJsonFile(name, next, env = process.env) {
   const dir = anyslateDir(env);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
-  const path = join(dir, CONFIG_FILE);
-  const tmp = join(dir, `${CONFIG_FILE}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
+  const path = join(dir, name);
+  const tmp = join(dir, `${name}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`);
   try {
     writeFileSync(tmp, JSON.stringify(next, null, 2), { mode: 0o600 });
     renameSync(tmp, path);
@@ -78,6 +88,23 @@ export function writeConfigFile(next, env = process.env) {
   return path;
 }
 
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {Record<string, any>}
+ */
+export function readConfigFile(env = process.env) {
+  return readJsonFile(CONFIG_FILE, env);
+}
+
+/**
+ * @param {Record<string, any>} next
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {string} the path written
+ */
+export function writeConfigFile(next, env = process.env) {
+  return writeJsonFile(CONFIG_FILE, next, env);
+}
+
 /**
  * Read-modify-write. `mutate` receives the CURRENT on-disk object (not a
  * snapshot the caller took earlier) and returns the object to persist.

package/src/guard.mjs

@@ -0,0 +1,381 @@
+// Client-side circuit breaker and local call ceiling — `~/.anyslate/cli-guard.json`.
+//
+// WHY THIS HAS TO BE ON DISK. Every hook invocation is its own process. An
+// in-memory breaker would be reconstructed, empty, fifty times a minute, which
+// is exactly the shape of the 2026-08-02 overload: one machine with a stale
+// refresh token issued `POST /oauth/token` + `POST /mcp` continuously for hours
+// because each new process started with no memory that the last fifty had all
+// been rejected. The breaker is only useful if it OUTLIVES the process.
+//
+// WHAT IT ENFORCES
+//   * after repeated 401s (or one definitively dead credential) capture is
+//     paused for an escalating period, the user is told ONCE how to fix it
+//     (`anyslate login`), and until then the client makes no request at all,
+//   * a `Retry-After` from a 429/503 becomes a persisted pause, so the wait is
+//     honoured by whichever process runs next rather than by a sleeping hook,
+//   * repeated transport failures (the server saying "overloaded") pause too,
+//     so a struggling service is not kept under load by its own clients,
+//   * a generous per-minute ceiling on calls from this machine, as a backstop
+//     against a runaway agent that is succeeding at fifty calls a minute.
+//
+// FINGERPRINTING, SO A FIX IS NOT PUNISHED. The breaker is bound to the
+// (apiUrl, credential) pair that tripped it. Point the CLI at a different
+// service root, swap the token, or run `anyslate login`, and it no longer
+// applies — otherwise "I fixed my config" would still mean fifteen minutes of
+// dead capture. An OAuth session is fingerprinted by its `client_id`, which
+// survives refresh-token rotation; if it did not, every refresh would silently
+// reset the breaker and we would be back to the storm.
+//
+// FAILS OPEN, ALWAYS. Every function here swallows its own I/O errors. A
+// guard file we cannot read or write must never be the reason a user's capture
+// or login stops working — a local cache blip converting into a lockout is a
+// worse failure than the one this module prevents.
+
+import { createHash } from 'node:crypto';
+import { unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { anyslateDir } from './config.mjs';
+import { readJsonFile, writeJsonFile } from './credentials.mjs';
+
+export const GUARD_FILE = 'cli-guard.json';
+
+/** Consecutive 401s before capture is paused. One is a blip; three is a state. */
+export const AUTH_FAILURES_BEFORE_OPEN = 3;
+
+/** Consecutive transport failures before we stop leaning on a struggling host. */
+export const TRANSIENT_FAILURES_BEFORE_OPEN = 5;
+
+/**
+ * Escalating pauses. A credential that is still dead after 15 minutes is not
+ * going to be alive at 16, and the user has already been told what to do — so
+ * the client backs further off rather than re-asking every quarter hour.
+ */
+export const AUTH_PAUSE_LADDER_MS = [15 * 60_000, 60 * 60_000, 6 * 60 * 60_000, 24 * 60 * 60_000];
+export const TRANSIENT_PAUSE_LADDER_MS = [30_000, 2 * 60_000, 10 * 60_000, 30 * 60_000];
+
+/** Clamp on a server-named wait: long enough to respect, short enough to recover from. */
+export const MIN_THROTTLE_MS = 1_000;
+export const MAX_THROTTLE_MS = 60 * 60_000;
+
+/**
+ * Machine-wide ceiling on capture calls per rolling minute. Set well above any
+ * human session (a busy Claude Code hour is single-digit calls per minute) —
+ * it exists to cap a runaway loop, not to shape normal traffic.
+ * `ANYSLATE_MAX_CALLS_PER_MINUTE=0` disables it.
+ */
+export const DEFAULT_CALLS_PER_MINUTE = 60;
+
+/** Auth failures that no amount of retrying can resolve — pause on the first one. */
+const TERMINAL_AUTH_CODES = new Set([
+  'invalid_grant',
+  'no_refresh_token',
+  'no_oauth_credentials',
+  'no_credentials',
+  'unauthorized_client',
+  'invalid_client',
+]);
+
+export function guardPath(env = process.env) {
+  return join(anyslateDir(env), GUARD_FILE);
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {Record<string, any>}
+ */
+export function readGuard(env = process.env) {
+  return readJsonFile(GUARD_FILE, env);
+}
+
+/**
+ * @param {Record<string, any>} next
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {boolean} whether it landed — callers proceed either way
+ */
+export function writeGuard(next, env = process.env) {
+  try {
+    writeJsonFile(GUARD_FILE, next, env);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Identify the (endpoint, credential) pair a breaker state belongs to, without
+ * storing anything a leaked guard file could be used with. Hashed for the same
+ * reason the run log is redacted: this file is written to a shared home
+ * directory and read by `doctor`.
+ *
+ * @param {{apiUrl?: string, authMode?: string, oauth?: object|null, mcpToken?: string|null,
+ *          staticToken?: string|null, sources?: {mcpToken?: string}}} cfg
+ * @returns {string}
+ */
+export function authFingerprint(cfg) {
+  const apiUrl = String(cfg?.apiUrl ?? '');
+  let identity = 'none';
+  if (cfg?.sources?.mcpToken === 'env' && cfg?.mcpToken) {
+    identity = `env:${cfg.mcpToken}`;
+  } else if (cfg?.oauth && (cfg.oauth.access_token || cfg.oauth.refresh_token)) {
+    // client_id, NOT the tokens: rotation replaces those on every refresh, and a
+    // fingerprint that changes hourly is a breaker that never holds.
+    identity = `oauth:${cfg.oauth.client_id ?? ''}:${cfg.oauth.root ?? ''}`;
+  } else if (cfg?.staticToken || cfg?.mcpToken) {
+    identity = `static:${cfg.staticToken ?? cfg.mcpToken}`;
+  }
+  return createHash('sha256').update(`${apiUrl}|${identity}`).digest('hex').slice(0, 16);
+}
+
+/**
+ * Is capture paused right now for this config?
+ *
+ * Pure read — the caller decides whether to speak, then calls `markNotified`.
+ * Splitting it that way keeps "tell the user once" honest across processes: the
+ * flag is only set once something was actually printed.
+ *
+ * @param {{cfg: object, env?: NodeJS.ProcessEnv, now?: number}} opts
+ * @returns {{open: boolean, reason: string|null, detail: string|null, until: string|null,
+ *   pausedForMs: number, noticeDue: boolean}}
+ */
+export function breakerGate({ cfg, env = process.env, now = Date.now() }) {
+  const closed = { open: false, reason: null, detail: null, until: null, pausedForMs: 0, noticeDue: false };
+  const state = readGuard(env);
+  if (!state.open_until) return closed;
+
+  // A different endpoint or credential is a different problem; do not serve a
+  // stale verdict about a setup the user has since changed.
+  if (state.fingerprint && state.fingerprint !== authFingerprint(cfg)) return closed;
+
+  const until = Date.parse(String(state.open_until));
+  if (!Number.isFinite(until) || until <= now) return closed;
+
+  return {
+    open: true,
+    reason: state.reason ?? 'auth',
+    detail: state.detail ?? null,
+    until: new Date(until).toISOString(),
+    pausedForMs: until - now,
+    noticeDue: !state.notified_at,
+  };
+}
+
+/**
+ * The one line a paused client is allowed to say. Names the fix, names when it
+ * will try again, and never repeats itself on the hook path.
+ *
+ * @param {{reason: string|null, detail: string|null, until: string|null}} gate
+ * @returns {string}
+ */
+export function breakerNotice(gate) {
+  const until = gate.until ? ` until ${gate.until}` : '';
+  const detail = gate.detail ? ` (${gate.detail})` : '';
+  if (gate.reason === 'auth') {
+    return (
+      `anyslate: capture paused${until} — repeated authentication failures${detail}. ` +
+      'Run `anyslate login` to sign in again; no requests are sent until then.'
+    );
+  }
+  if (gate.reason === 'throttled') {
+    return `anyslate: capture paused${until} — the server asked this client to back off${detail}.`;
+  }
+  return (
+    `anyslate: capture paused${until} — repeated failures reaching the service${detail}. ` +
+    'Run `anyslate doctor` to check it.'
+  );
+}
+
+/**
+ * Record that a call was rejected, and open the breaker if this is a pattern.
+ *
+ * @param {object} opts
+ * @param {object} opts.cfg
+ * @param {'auth'|'throttled'|'transient'|'fatal'|null} opts.kind
+ * @param {string} [opts.code]        OAuth/refresh error code, when there is one
+ * @param {string} [opts.detail]      short human reason, stored for `doctor`
+ * @param {number|null} [opts.retryAfterMs]
+ * @param {NodeJS.ProcessEnv} [opts.env]
+ * @param {number} [opts.now]
+ * @returns {{opened: boolean, open: boolean, reason: string|null, until: string|null, detail: string|null}}
+ */
+export function recordCallFailure({ cfg, kind, code, detail, retryAfterMs = null, env = process.env, now = Date.now() }) {
+  const quiet = { opened: false, open: false, reason: null, until: null, detail: null };
+  // A 4xx we caused is not a reason to stop capturing: the request was cheap to
+  // reject and the next one may be well-formed.
+  if (kind !== 'auth' && kind !== 'throttled' && kind !== 'transient') return quiet;
+
+  const fingerprint = authFingerprint(cfg);
+  const previous = readGuard(env);
+  // Counters belong to one (endpoint, credential) pair; a switch resets them.
+  const carried = previous.fingerprint === fingerprint ? previous : {};
+
+  const next = {
+    fingerprint,
+    auth_failures: Number(carried.auth_failures) || 0,
+    transient_failures: Number(carried.transient_failures) || 0,
+    trips: Number(carried.trips) || 0,
+    open_until: carried.open_until ?? null,
+    reason: carried.reason ?? null,
+    detail: carried.detail ?? null,
+    notified_at: carried.notified_at ?? null,
+    window_started_at: carried.window_started_at ?? null,
+    window_calls: Number(carried.window_calls) || 0,
+    updated_at: new Date(now).toISOString(),
+  };
+
+  let pauseMs = 0;
+  if (kind === 'throttled') {
+    // One is enough. `Retry-After` is an instruction, not a hint, and the
+    // machine that ignored it is the one that took the database down.
+    pauseMs = clamp(retryAfterMs ?? TRANSIENT_PAUSE_LADDER_MS[0], MIN_THROTTLE_MS, MAX_THROTTLE_MS);
+    next.reason = 'throttled';
+  } else if (kind === 'auth') {
+    next.auth_failures += 1;
+    const terminal = code ? TERMINAL_AUTH_CODES.has(code) : false;
+    if (terminal || next.auth_failures >= AUTH_FAILURES_BEFORE_OPEN) {
+      pauseMs = ladder(AUTH_PAUSE_LADDER_MS, next.trips);
+      next.reason = 'auth';
+    }
+  } else {
+    next.transient_failures += 1;
+    if (next.transient_failures >= TRANSIENT_FAILURES_BEFORE_OPEN) {
+      pauseMs = ladder(TRANSIENT_PAUSE_LADDER_MS, next.trips);
+      next.reason = 'server';
+    }
+  }
+
+  if (!pauseMs) {
+    writeGuard(next, env);
+    return quiet;
+  }
+
+  next.open_until = new Date(now + pauseMs).toISOString();
+  next.detail = detail ? String(detail).slice(0, 200) : (code ?? null);
+  next.trips += 1;
+  next.auth_failures = 0;
+  next.transient_failures = 0;
+  // Re-arm the "say it once" flag: a NEW pause deserves a fresh notice.
+  next.notified_at = null;
+  writeGuard(next, env);
+
+  return { opened: true, open: true, reason: next.reason, until: next.open_until, detail: next.detail };
+}
+
+/**
+ * A call landed. Everything the breaker knew is stale.
+ *
+ * The rolling-minute window is deliberately preserved — a successful call still
+ * counts against the machine ceiling.
+ *
+ * @param {{cfg: object, env?: NodeJS.ProcessEnv}} opts
+ */
+export function recordCallSuccess({ cfg, env = process.env }) {
+  const previous = readGuard(env);
+  if (!previous.open_until && !previous.auth_failures && !previous.transient_failures && !previous.trips) return;
+  writeGuard(
+    {
+      fingerprint: authFingerprint(cfg),
+      auth_failures: 0,
+      transient_failures: 0,
+      trips: 0,
+      open_until: null,
+      reason: null,
+      detail: null,
+      notified_at: null,
+      window_started_at: previous.window_started_at ?? null,
+      window_calls: Number(previous.window_calls) || 0,
+      updated_at: new Date().toISOString(),
+    },
+    env,
+  );
+}
+
+/**
+ * Mark the pause as explained, so the next hook stays quiet.
+ * @param {NodeJS.ProcessEnv} [env]
+ * @param {number} [now]
+ */
+export function markNotified(env = process.env, now = Date.now()) {
+  const state = readGuard(env);
+  if (!state.open_until) return;
+  writeGuard({ ...state, notified_at: new Date(now).toISOString() }, env);
+}
+
+/**
+ * Drop the breaker entirely. `login` calls this: the user has just proved they
+ * can authenticate, so making them wait out a pause earned by the credential
+ * they just replaced would be absurd.
+ *
+ * @param {NodeJS.ProcessEnv} [env]
+ */
+export function clearBreaker(env = process.env) {
+  try {
+    unlinkSync(guardPath(env));
+  } catch {
+    // Never existed, or the home directory is not ours to write. Either way the
+    // breaker reads as closed, which is the fail-open answer.
+  }
+}
+
+/**
+ * The machine-wide ceiling. Read-modify-write, so two hooks racing in the same
+ * second can undercount — that is the intended direction to be wrong in: this
+ * is a runaway backstop, not an accounting system, and a lost increment lets a
+ * legitimate call through rather than dropping it.
+ *
+ * @param {{env?: NodeJS.ProcessEnv, now?: number, limit?: number}} [opts]
+ * @returns {{allowed: boolean, count: number, limit: number, resetInMs: number}}
+ */
+export function reserveCallSlot({ env = process.env, now = Date.now(), limit } = {}) {
+  const ceiling = limit ?? callsPerMinuteLimit(env);
+  if (!ceiling) return { allowed: true, count: 0, limit: 0, resetInMs: 0 };
+
+  const state = readGuard(env);
+  const startedAt = Date.parse(String(state.window_started_at ?? ''));
+  const fresh = !Number.isFinite(startedAt) || now - startedAt >= 60_000;
+  const windowStart = fresh ? now : startedAt;
+  const count = (fresh ? 0 : Number(state.window_calls) || 0) + 1;
+
+  writeGuard(
+    { ...state, window_started_at: new Date(windowStart).toISOString(), window_calls: count },
+    env,
+  );
+
+  return {
+    allowed: count <= ceiling,
+    count,
+    limit: ceiling,
+    resetInMs: Math.max(0, windowStart + 60_000 - now),
+  };
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {number} 0 disables the ceiling
+ */
+export function callsPerMinuteLimit(env = process.env) {
+  const raw = env.ANYSLATE_MAX_CALLS_PER_MINUTE;
+  if (raw === undefined || raw === null || String(raw).trim() === '') return DEFAULT_CALLS_PER_MINUTE;
+  const n = Number(raw);
+  if (!Number.isFinite(n) || n < 0) return DEFAULT_CALLS_PER_MINUTE;
+  return Math.floor(n);
+}
+
+/**
+ * @param {{count: number, limit: number, resetInMs: number}} slot
+ * @returns {string}
+ */
+export function ceilingNotice(slot) {
+  return (
+    `anyslate: local rate ceiling reached (${slot.count} calls in the last minute, limit ${slot.limit}) — ` +
+    `skipping this one for ${Math.ceil(slot.resetInMs / 1000)}s. ` +
+    'Raise or disable it with ANYSLATE_MAX_CALLS_PER_MINUTE.'
+  );
+}
+
+function ladder(steps, index) {
+  return steps[Math.min(index, steps.length - 1)];
+}
+
+function clamp(value, min, max) {
+  return Math.min(max, Math.max(min, value));
+}

package/src/index.mjs

@@ -78,6 +78,18 @@ env:
   ANYSLATE_DISABLE=1  kill switch: hook / checkpoint / upload-artifact make no
                       network call and exit 0. \`doctor\` and \`login\` still run
                       so you can diagnose and set up while capture is off.
+  ANYSLATE_HOOK_TIMEOUT_MS
+                      total request budget for one \`hook\` submission
+                      (default 5000). Hooks never retry.
+  ANYSLATE_MAX_CALLS_PER_MINUTE
+                      machine-wide ceiling on capture calls (default 60;
+                      0 disables). A backstop against a runaway loop.
+
+capture pauses:
+  After repeated authentication failures — or when the server answers 429/503
+  with a Retry-After — the CLI stops calling entirely and records the pause in
+  ~/.anyslate/cli-guard.json. It says so once, then stays silent. \`anyslate
+  login\` clears an auth pause immediately; \`anyslate doctor\` always reports one.
 `;
 
 /**

package/src/mcp-client.mjs

@@ -99,9 +99,20 @@ export function formatErrorPayload(raw) {
 }
 
 /**
- * Extract 429 metadata. `Retry-After` was never read and
+ * Statuses that carry a server-named wait.
+ *
+ * 503 joined 429 after 2026-08-02: when the database was overloaded the
+ * handlers returned bare 500s, every client read that as "try again now", and
+ * the retries deepened the outage. The service now answers 503 + `Retry-After`
+ * on that path, so the client has to read it there too — an unread Retry-After
+ * is the same as no Retry-After.
+ */
+const THROTTLE_STATUSES = new Set([429, 503]);
+
+/**
+ * Extract throttle metadata. `Retry-After` was never read and
  * `retry_after_seconds`/`reset_at`/`reason` survived only in `raw`
- * (defect #31). Surfacing only — no retry/backoff logic.
+ * (defect #31). Surfacing only — backoff.mjs/guard.mjs decide what to do with it.
  *
  * @param {Response} res
  * @param {unknown} raw
@@ -294,7 +305,7 @@ export async function callTool({
         const formatted = formatErrorPayload(init.raw);
         const errLike = formatted ?? { message: `initialize failed (HTTP ${init.status})` };
         const out = { ok: false, status: init.status, data: errLike, raw: init.raw };
-        if (init.status === 429) {
+        if (THROTTLE_STATUSES.has(init.status)) {
           const rl = extractRateLimit(init.res, init.raw);
           out.rateLimit = rl;
           out.retryAfterSeconds = rl.retry_after_seconds;
@@ -322,7 +333,7 @@ export async function callTool({
 
     const status = res.status;
     const raw = await readBody(res);
-    const rateLimit = status === 429 ? extractRateLimit(res, raw) : null;
+    const rateLimit = THROTTLE_STATUSES.has(status) ? extractRateLimit(res, raw) : null;
 
     const finish = (out) => {
       if (rateLimit) {
@@ -356,7 +367,7 @@ export async function callTool({
         const embeddedStatus = Number.isFinite(parsed.status) ? Number(parsed.status) : status;
         const data = formatErrorPayload(parsed) ?? parsed.error ?? text ?? 'tool returned isError';
         const out = { ok: false, status: embeddedStatus, data, raw, isError: true };
-        if (embeddedStatus === 429) {
+        if (THROTTLE_STATUSES.has(embeddedStatus)) {
           const rl = extractRateLimit(res, parsed);
           out.rateLimit = rl;
           out.retryAfterSeconds = rl.retry_after_seconds;