@anyslate/cli 0.3.1 → 0.4.1

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,29 @@ import { makeIo } from '../io.mjs';
 
 const ALLOWED = new Set(['session-start', 'post-tool-use', 'stop']);
 
+/**
+ * Total budget for credential refresh + 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. Auth (lock wait / peer poll / refresh HTTP) shares this budget
+ * with the MCP call — it is not stacked on top.
+ */
+export const HOOK_TIMEOUT_MS = 5_000;
+
+/**
+ * How long a hook will queue behind another process's token refresh. Kept well
+ * below HOOK_TIMEOUT_MS so an unlocked loser still has time for a short peer
+ * poll + refresh HTTP + the activity_submit call inside the same wall budget.
+ */
+export const HOOK_LOCK_WAIT_MS = 1_500;
+
+/** @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 +139,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 +195,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.