@anyslate/cli 0.2.0 → 0.3.0

package/README.md

@@ -17,7 +17,7 @@ Most days you'll never type `anyslate` yourself. Here's what actually happens:
 | Trigger | Who calls the CLI | What lands |
 |---|---|---|
 | You open a Claude Code session | Claude Code's `SessionStart` hook | Session-start activity; the AnySlate session is created on first sight |
-| Claude edits `routes/auth.ts` | Claude Code's `PostToolUse` hook | "Edited routes/auth.ts" in the activity ledger (**awaits your approval** - see below) |
+| Claude edits `routes/auth.ts` | Claude Code's `PostToolUse` hook | "Edited routes/auth.ts" in the activity ledger |
 | Claude runs `npm test` | Claude Code's `PostToolUse` hook | Command + output in the activity ledger |
 | You `git commit` | Git's `post-commit` hook | Commit metadata + diff stats captured |
 | Teammate merges your PR | GitHub webhook (no CLI needed) | PR-merged event captured |
@@ -39,11 +39,13 @@ If you want a decision recorded, type it:
 anyslate checkpoint --note "Decided: Redis for session cache, not memcached"
 ```
 
-### Approval: file edits wait, shell commands don't
+### Approval: hook captures auto-promote
 
-The classifier treats `Edit` / `Write` / `MultiEdit` as **high-risk** - those rows stay pending in **AI Memory → Activity** until you approve them. `Bash` and session lifecycle events classify **low-risk** and auto-promote on their own.
+Every lifecycle hook - `Edit` / `Write` / `MultiEdit`, `Bash`, and the session start/stop markers - classifies **low-risk** and auto-promotes on its own, 30-90 seconds after capture. An edit-heavy session does **not** build an approval queue.
 
-This is deliberate, and it means a Claude Code session that edits a lot of files produces a queue you have to work through. Budget a few seconds a day for it, or approve in bulk.
+Rows still wait for approval in **AI Memory → Activity** when they are genuinely riskier: a capture aimed at a different session than the one that produced it, a decision that supersedes an earlier one, a submission from an untrusted source, or one carrying `confidence < 0.8`.
+
+File edits used to map to `artifact_produced`, which is high-risk by classification. That was wrong on two counts: it forced a manual approval on the single most common event in a session, and `artifact_produced` is a contract meaning "I stored an artifact, here is its id" - which a hook can never satisfy, so the server rejected it. Edits now map to `task_completed` and carry the touched paths in the ledger.
 
 ## What you get back
 
@@ -75,22 +77,56 @@ Requires Node ≥ 20.
 
 ## Authenticate
 
-Mint an MCP token in the AnySlate app: **Avatar (top-right) → API Tokens → Tokens tab → Create Token**. This is the same dialog on the desktop app and on the cloud app at `https://cloud.anyslate.io`; the dialog is titled *MCP Tokens*. MCP token minting is **available on every plan** - Free, Pro and Unlimited - with no token quota.
+```bash
+anyslate login
+```
+
+That's it. `login` opens your browser, you approve the CLI on the AnySlate consent screen, and the credentials land in `~/.anyslate/cli.json` (mode `0600`). Nothing to copy, nothing to paste.
+
+What happens under the hood, in case you're the kind of person who wants to know before you run it: OAuth 2.1 authorization code with PKCE. The CLI reads every endpoint from the server's discovery documents (`/.well-known/oauth-authorization-server` and `/.well-known/oauth-protected-resource`) rather than assuming any path, registers itself once via Dynamic Client Registration and caches the resulting client id, binds a short-lived listener on `127.0.0.1` for the callback, and verifies the resulting token with one live request before writing anything.
+
+The access token lasts **one hour**; a refresh token lasts **30 days**. The CLI refreshes automatically — five minutes ahead of expiry, and again if a call comes back `401` — so your hooks keep capturing without you thinking about it. Refresh tokens are single-use and rotate on every refresh; the new one is written to disk immediately.
+
+Then confirm the whole install:
+
+```bash
+anyslate doctor
+```
 
-Copy the token (it starts with `as_mcp_`; you only see it once), then:
+### Signing in to a non-production environment
+
+```bash
+anyslate login --api-url https://anyslate-mcp-service-development.example.workers.dev
+```
+
+`--api-url` takes the service **root** (no `/mcp` suffix — see [the two URL conventions](#the-two-url-conventions---the-one-thing-people-get-wrong)). Every OAuth endpoint, and the OAuth `resource` identifier, is then read from *that* root's discovery documents. Dev and production issue different client ids, so the CLI caches one per root and reuses it.
+
+If discovery fails, `login` says which host it tried and stops. It will not fall back to guessed endpoint paths.
+
+### Static tokens, for CI
+
+Browsers are in short supply on a build agent. The token path is unchanged and stays supported:
 
 ```bash
 anyslate login --token as_mcp_your_token_here
+# or, with no config file at all:
+export ANYSLATE_MCP_TOKEN=as_mcp_your_token_here
 ```
 
-`login` verifies the token against the server before writing anything. If the host is unreachable, the URL isn't an AnySlate MCP service, or the token is unrecognised/revoked/expired, it prints the reason, **writes nothing, and exits non-zero**. See [`anyslate login`](#anyslate-login) for the `--force` / `--no-verify` escapes.
+Mint the token in the AnySlate app: **Avatar (top-right) → API Tokens → Tokens tab → Create Token**. This is the same dialog on the desktop app and on the cloud app at `https://cloud.anyslate.io`; the dialog is titled *MCP Tokens*. MCP token minting is **available on every plan** - Free, Pro and Unlimited - with no token quota. Copy the token (it starts with `as_mcp_`; you only see it once).
 
-Then confirm the whole install:
+`login --token` verifies the token against the server before writing anything. If the host is unreachable, the URL isn't an AnySlate MCP service, or the token is unrecognised/revoked/expired, it prints the reason, **writes nothing, and exits non-zero**. See [`anyslate login`](#anyslate-login) for the `--force` / `--no-verify` escapes.
+
+Static tokens never expire and are never refreshed. That is the trade: convenient for CI, and the reason the browser flow is the default everywhere else.
+
+### Signing out
 
 ```bash
-anyslate doctor
+anyslate logout
 ```
 
+Revokes the session server-side, then removes the credentials from `~/.anyslate/cli.json`. Your `apiUrl`, `handle` and cached client registration are kept, so `anyslate login` afterwards is a one-liner.
+
 ### Environment variables
 
 ```bash
@@ -104,6 +140,14 @@ export ANYSLATE_STDIN_TIMEOUT_MS=10000            # optional, stdin idle timeout
 
 Env vars override `~/.anyslate/cli.json`.
 
+The bearer the CLI actually sends is resolved in this order, first hit wins:
+
+1. `ANYSLATE_MCP_TOKEN` — a static token from the environment. Never refreshed.
+2. The OAuth access token from `cli.json`, refreshed if it is expired or close to it.
+3. The static `mcp_token` in `cli.json`.
+
+`anyslate doctor` prints which of the three won, so an `ANYSLATE_MCP_TOKEN` you exported weeks ago and forgot cannot silently shadow a browser sign-in.
+
 `ANYSLATE_DISABLE=1` stops `hook` / `checkpoint` / `upload-artifact` from making any network call (they exit 0). `doctor` and `login` still run, so you can diagnose and set up while capture is off. Any value counts as "on" except empty, `0`, `false`, `no`, `off`.
 
 Capability handles are `mh_` + a 32-character id (e.g. `mh_V1StGXR8Z5jdHi6BmyT0aQx3nKpL7cWe`), minted alongside a scoped token in the **Handles** tab of the same dialog. **A handle id that isn't yours or doesn't exist is rejected server-side** - since 0.2.0 the CLI reports that as a failure instead of exiting 0 silently.
@@ -134,8 +178,10 @@ anyslate: using "https://mcp.anyslate.io". Run `anyslate login --api-url https:/
 anyslate hook <session-start|post-tool-use|stop> [--strict] [--session <id>] [--note <text>] [--host <hint>]
 anyslate checkpoint --note "..." [--kind milestone] [--session <id>] [--host <hint>] [--source <source>]
 anyslate upload-artifact --session <id> --kind <kind> [--file <path>] [--language <lang>] [--path-hint <path>]
+anyslate login [--api-url <URL>] [--no-browser] [--timeout <seconds>] [--handle <ID>]
 anyslate login --token <BEARER> [--handle <ID>] [--api-url <URL>] [--force] [--no-verify]
-anyslate doctor [--deep]
+anyslate logout [--local]
+anyslate doctor [--deep] [--refresh]
 anyslate version | help
 ```
 
@@ -143,7 +189,11 @@ anyslate version | help
 
 The one command whose job is to fail loudly. Run it after setup and any time capture seems dead. It exits non-zero if any check FAILs.
 
-It checks, in order: which config layer won (env var vs `cli.json`) per key; that a token is present; that the token *looks* like a token; that the URL parses and has the right shape (**before** any token verdict, because a wrong URL 404s ahead of auth and would otherwise be misread as a bad token); that the host is reachable and healthy; that the token is valid (and, if not, whether it is unrecognised, revoked or expired); that the token carries `memory:write`; the effective handle scope; that `anyslate` is on the PATH a hook subprocess would get; and whether Claude Code's hooks are actually wired in `~/.claude/settings.json`.
+It checks, in order: which config layer won (env var vs `cli.json`) per key; that a credential is present; **which auth mode is in use** — OAuth or static token — and for OAuth how long the access token has left and whether a refresh token is stored; that the token *looks* like a token; that the URL parses and has the right shape (**before** any token verdict, because a wrong URL 404s ahead of auth and would otherwise be misread as a bad token); that the host is reachable and healthy; **whether refresh works**; that the token is valid (and, if not, whether it is unrecognised, revoked or expired); that the token carries `memory:write`; the effective handle scope; that `anyslate` is on the PATH a hook subprocess would get; and whether Claude Code's hooks are actually wired in `~/.claude/settings.json`.
+
+The refresh check runs **after** reachability on purpose: a refresh against a host that is down fails for a reason that has nothing to do with your credentials, and reporting that as "refresh is broken" sends you hunting for the wrong bug. If the access token is still comfortably valid, `doctor` reports the refresh token as present but does not spend it — pass `--refresh` to force a real refresh round trip (which rotates the token).
+
+An expired OAuth access token is a **WARN**, not a FAIL: access tokens are supposed to expire hourly. The FAIL you care about is `oauth-refresh`, which means renewal itself is broken and you need to run `anyslate login` again.
 
 Reading the output:
 
@@ -151,7 +201,7 @@ Reading the output:
 - **WARN** - works, but something is narrower or more fragile than you probably intend (e.g. a project-scoped token, or a config key coming from an env var you forgot you exported).
 - **FAIL** - this is why capture isn't working. Each FAIL prints the specific remedy.
 
-`doctor` is **not** side-effect-free: verifying the token updates its `last_used_at`, consumes rate-limit budget, and writes an audit-log row. `--deep` additionally submits a real `doctor_probe` activity, which is visible in your Activity feed - that's why it's opt-in.
+`doctor` is **not** side-effect-free: verifying the token updates its `last_used_at`, consumes rate-limit budget, and writes an audit-log row. `--deep` additionally submits a real `doctor_probe` activity, which is visible in your Activity feed - that's why it's opt-in. `--refresh` forces an OAuth refresh, which rotates your refresh token - also why it's opt-in.
 
 ### `anyslate hook ...`
 
@@ -185,14 +235,39 @@ Content is read as UTF-8. Binary files are not supported and are refused rather
 
 ### `anyslate login`
 
-Verifies, then writes `~/.anyslate/cli.json` with mode `0600`. Idempotent - preserves the apiUrl/handle if you only update the token (the preserved apiUrl is re-normalized and re-verified).
+Two paths, one config file. `--token` selects the static path; its absence selects the browser flow.
+
+Both end the same way: one live request to `/mcp/auth/verify` that proves reachability, URL shape, token validity and scopes in a single round trip, then a `0600` write to `~/.anyslate/cli.json`. **On verification failure it writes nothing and exits non-zero.** Both are idempotent — they preserve the `apiUrl` and `handle` you already had (and re-normalize a stored `apiUrl` that carries a stale `/mcp` suffix).
+
+A token missing the `memory:write` scope is a **warning**, not a block - but `anyslate hook` needs it, so heed it.
+
+**Browser flow flags**
+
+- `--api-url <root>` - which environment to sign in to. Defaults to production. Every OAuth endpoint comes from that root's discovery documents.
+- `--no-browser` - print the authorization URL instead of launching anything. For SSH sessions and containers. The URL is printed either way, so a browser that fails to appear never leaves you stuck.
+- `--timeout <seconds>` - how long to wait for the callback. Default `180`.
+- `--handle <ID>` - store a capability handle alongside the credentials.
 
-Verification is a single request that proves reachability, URL shape, token existence, revocation, expiry and scopes in one round trip. **On failure it writes nothing and exits non-zero.** Two escapes:
+**Static-token flags**
 
 - `--force` - write anyway, with a warning. For when you know the server is temporarily down.
 - `--no-verify` - skip the probe entirely. For air-gapped or offline setup.
 
-A token missing the `memory:write` scope is a **warning**, not a block - but `anyslate hook` needs it, so heed it.
+**What gets stored.** The browser flow writes an `oauth` block: the client id, the access token, the refresh token, the absolute expiry, and the token endpoint and `resource` it discovered (cached so a background refresh costs one request instead of three, and bound to the root so switching environments re-discovers rather than reusing the wrong one). The static flow writes `mcp_token`, exactly as before. Neither path touches the other's keys.
+
+**Refresh.** Handled automatically by whichever command needs it — `hook`, `checkpoint`, `upload-artifact`, `doctor`. It happens five minutes before expiry, and once more on a `401`. Since hooks can fire in parallel, refreshes are serialized with a lock file and the config is replaced atomically, so two concurrent hooks cannot lose each other's rotated token. A hook **never** opens a browser: if refresh fails there, it logs the reason and exits 0 like any other failure.
+
+### `anyslate logout`
+
+Revokes the OAuth session at the server's revocation endpoint (refresh token first — it's the 30-day one), then removes `oauth` and `mcp_token` from `~/.anyslate/cli.json`.
+
+Revocation is best effort. If the host is unreachable the credentials are still cleared and you get a warning, because a `logout` that refuses to run offline is a `logout` you cannot use when you most need one.
+
+`apiUrl`, `handle` and the cached client registration survive. The registration is not a credential, and re-registering costs one of the ten Dynamic Client Registrations allowed per hour.
+
+- `--local` - skip revocation and only clear the local file. The server-side session then stays live until it expires.
+
+If `ANYSLATE_MCP_TOKEN` is set in your environment, `logout` says so: it overrides the config, so capture keeps working until you unset it.
 
 ## Wiring into Claude Code
 
@@ -258,7 +333,16 @@ Set `ANYSLATE_DISABLE=1` in the shell where you're running the AI tool. The CLI
 Setting `ANYSLATE_MCP_TOKEN=` (empty) does **not** disable capture - an empty string falls through to the token in `~/.anyslate/cli.json`, so capture keeps running. Earlier versions of this README claimed otherwise; that claim was wrong. Use `ANYSLATE_DISABLE=1`.
 
 **Where does the data live?**
-In your AnySlate workspace. The CLI is a stateless client; it sends events to the AnySlate MCP service over HTTPS and stores nothing locally beyond your token in `~/.anyslate/cli.json` and the local run logs described under `anyslate hook` (all mode 0600).
+In your AnySlate workspace. The CLI is a stateless client; it sends events to the AnySlate MCP service over HTTPS and stores nothing locally beyond your credentials in `~/.anyslate/cli.json` and the local run logs described under `anyslate hook` (all mode 0600). The run logs redact anything token-shaped before writing.
+
+**Do I need to log in again every hour?**
+No. The one-hour lifetime is the access token's; the CLI renews it in the background from a 30-day refresh token, including inside hooks running unattended. You'll re-authenticate roughly monthly, or whenever you run `anyslate logout`.
+
+**I'm on a headless box / over SSH. Can I still use the browser flow?**
+Yes - `anyslate login --no-browser` prints the URL, you open it on a machine that has a browser, and it redirects back to `127.0.0.1` on the port the CLI is listening on. That only works if the browser can reach that loopback address, so from a remote box you'll want an SSH tunnel - or just use `--token`, which is what it's there for.
+
+**Is the CLI adding dependencies to do OAuth?**
+No. It has no runtime dependencies. PKCE, the loopback listener and the browser launch are all `node:` builtins, and there's a test that fails the build if an import ever points outside them.
 
 **Can I see what was captured?**
 Yes - **AI Memory → Activity** shows every captured row with its status (pending / merged / rejected / failed), and failures under the **Failed** tab carry the reason. High-risk items wait for approval; low-risk items promote on their own in 30-90 seconds.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anyslate/cli",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "AnySlate CLI - lifecycle hooks, git/CI capture, and manual checkpoints for AI memory. Validates its connection at login, diagnoses itself with `anyslate doctor`, and fails open without failing silent.",
   "type": "module",
   "bin": {

package/src/auth.mjs

@@ -0,0 +1,310 @@
+// Bearer resolution and refresh for every command that talks to the server.
+//
+// THIS IS THE LOAD-BEARING PART OF THE OAUTH WORK. A static `as_mcp_` token
+// never expires, so `loadConfig().mcpToken` was the whole auth story. An OAuth
+// access token lives 3600 seconds, and hooks fire unattended in
+// non-interactive shells — so a token WILL expire mid-session, in a process
+// with no terminal, no browser, and a hard "must exit 0" contract.
+//
+// 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
+//     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.
+//   * Persist the rotated refresh token immediately (rotation is on server-side).
+//   * NEVER open a browser. This module is imported by `hook`; a browser launch
+//     from a lifecycle hook would spray tabs across the user's screen and hang
+//     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.
+
+import { readConfigFile, updateConfigFile, withRefreshLock } from './credentials.mjs';
+import { callTool } from './mcp-client.mjs';
+import { discover, refreshAccessToken, REFRESH_SKEW_MS } from './oauth.mjs';
+
+export { REFRESH_SKEW_MS };
+
+/** Everything a hook/checkpoint/upload path is allowed to say about auth. */
+export const RELOGIN_HINT = 'Run `anyslate login` to sign in again.';
+
+/**
+ * @param {unknown} expiresAt ISO 8601
+ * @returns {number|null} epoch ms, or null when unparseable
+ */
+export function expiryMs(expiresAt) {
+  if (typeof expiresAt !== 'string' || !expiresAt) return null;
+  const t = Date.parse(expiresAt);
+  return Number.isFinite(t) ? t : null;
+}
+
+/**
+ * Is this credential inside the refresh window (or already dead)?
+ *
+ * An UNPARSEABLE or ABSENT expiry counts as expiring. Treating "I do not know"
+ * as "still valid" is how a config written by a future version, or hand-edited,
+ * turns into a silent 401 loop.
+ *
+ * @param {{expires_at?: string}|null|undefined} oauth
+ * @param {number} [skewMs]
+ * @param {number} [now]
+ */
+export function isExpiring(oauth, skewMs = REFRESH_SKEW_MS, now = Date.now()) {
+  if (!oauth?.access_token) return true;
+  const t = expiryMs(oauth.expires_at);
+  if (t == null) return true;
+  return t - now <= skewMs;
+}
+
+/** Hard expiry, no skew — used for reporting, not for refresh decisions. */
+export function isExpired(oauth, now = Date.now()) {
+  return isExpiring(oauth, 0, now);
+}
+
+/** Minutes until expiry, for human output. Negative means already expired. */
+export function minutesUntilExpiry(oauth, now = Date.now()) {
+  const t = expiryMs(oauth?.expires_at);
+  if (t == null) return null;
+  return Math.round((t - now) / 60_000);
+}
+
+/** Does this config hold OAuth credentials worth using or refreshing? */
+export function hasOauthCredentials(oauth) {
+  return !!(oauth && (oauth.access_token || oauth.refresh_token));
+}
+
+/**
+ * Resolve the endpoints used for a refresh.
+ *
+ * `login` caches `token_endpoint`/`resource`/`root` alongside the tokens, so
+ * the common refresh costs ONE request rather than three. The cache is only
+ * trusted when it was recorded for the root we are actually calling — a
+ * `--api-url` switch from prod to dev must re-discover, because the two issue
+ * different client ids and different `resource` values.
+ *
+ * @returns {Promise<{ok: true, tokenEndpoint: string, resource: string}
+ *   | {ok: false, code: string, message: string}>}
+ */
+async function refreshEndpoints({ oauth, root, fetchImpl }) {
+  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 });
+  if (!found.ok) return found;
+  return { ok: true, tokenEndpoint: found.tokenEndpoint, resource: found.resource };
+}
+
+/**
+ * Perform one refresh, under the lock, persisting the rotated token.
+ *
+ * `staleToken` is the access token that just failed. It exists because expiry
+ * alone cannot decide whether a refresh is still needed: a token the server
+ * rejected with a 401 may have an `expires_at` an hour in the future (revoked
+ * early, clock skew, a config restored from a backup). Without it, the
+ * "somebody else already refreshed" short-circuit hands the caller back the
+ * very token that just 401'd, and the retry fails identically.
+ *
+ * @param {{env: NodeJS.ProcessEnv, root: string, fetchImpl?: typeof fetch, now?: number,
+ *          staleToken?: string|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 }) {
+  return withRefreshLock(
+    async () => {
+      // 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.
+      const disk = readConfigFile(env);
+      const oauth = disk.oauth && typeof disk.oauth === 'object' ? disk.oauth : null;
+
+      if (!hasOauthCredentials(oauth)) {
+        return { ok: false, code: 'no_oauth_credentials', message: 'anyslate: no OAuth credentials to refresh.' };
+      }
+
+      // Skip only when the on-disk token is BOTH unexpired AND different from
+      // the one we are replacing — i.e. genuinely somebody else's fresh token.
+      const supersededByPeer = staleToken ? oauth.access_token && oauth.access_token !== staleToken : true;
+      if (supersededByPeer && !isExpiring(oauth, REFRESH_SKEW_MS, now)) {
+        return { ok: true, token: oauth.access_token, rotated: false, oauth };
+      }
+      if (!oauth.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 endpoints = await refreshEndpoints({ oauth, root, fetchImpl });
+      if (!endpoints.ok) return endpoints;
+
+      const res = await refreshAccessToken({
+        tokenEndpoint: endpoints.tokenEndpoint,
+        refreshToken: oauth.refresh_token,
+        clientId: oauth.client_id,
+        resource: endpoints.resource,
+        fetchImpl,
+        now,
+      });
+      if (!res.ok) {
+        return {
+          ok: false,
+          code: res.code || 'refresh_failed',
+          message: `${res.message} ${RELOGIN_HINT}`,
+        };
+      }
+
+      // Persist BEFORE returning. Rotation means the old refresh token is dead
+      // the instant the server answered; a crash between here and the next
+      // write would lose the only usable credential.
+      const next = {
+        ...oauth,
+        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,
+        expires_at: res.tokens.expires_at,
+        token_endpoint: endpoints.tokenEndpoint,
+        resource: endpoints.resource,
+        root,
+      };
+      try {
+        updateConfigFile((current) => ({ ...current, oauth: { ...(current.oauth ?? {}), ...next } }), env);
+      } catch (e) {
+        return {
+          ok: false,
+          code: 'persist_failed',
+          message: `anyslate: refreshed the OAuth session but could not write the config (${e?.message ?? e}).`,
+        };
+      }
+      return { ok: true, token: next.access_token, rotated: true, oauth: next };
+    },
+    { env },
+  );
+}
+
+/**
+ * The bearer for the next call, refreshing if needed.
+ *
+ * Precedence mirrors loadConfig: ANYSLATE_MCP_TOKEN → OAuth → static
+ * `mcp_token` → nothing. The one deliberate divergence: loadConfig cannot
+ * refresh (it is synchronous), so an EXPIRED OAuth credential falls through
+ * there while here it is refreshed and preferred. If the refresh fails and a
+ * 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
+ * @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 }) {
+  if (cfg?.sources?.mcpToken === 'env' && cfg.mcpToken) {
+    return { ok: true, token: cfg.mcpToken, mode: 'env', refreshed: false };
+  }
+
+  const oauth = cfg?.oauth ?? null;
+  if (hasOauthCredentials(oauth)) {
+    if (!force && !isExpiring(oauth, REFRESH_SKEW_MS, now)) {
+      return { ok: true, token: oauth.access_token, mode: 'oauth', refreshed: false };
+    }
+    // `force` means "the token we just used was rejected" — name it, so the
+    // lock's peer-refresh check cannot hand the same rejected token back.
+    const refreshed = await refreshCredentials({
+      env,
+      root: cfg.apiUrl,
+      fetchImpl,
+      now,
+      staleToken: force ? (oauth.access_token ?? null) : null,
+    });
+    if (refreshed.ok) {
+      return { ok: true, token: refreshed.token, mode: 'oauth', refreshed: refreshed.rotated };
+    }
+    if (cfg.staticToken) {
+      return {
+        ok: true,
+        token: cfg.staticToken,
+        mode: 'static',
+        refreshed: false,
+        warning: `anyslate: OAuth refresh failed (${refreshed.code}) — falling back to the static token in your config.`,
+      };
+    }
+    return { ...refreshed, mode: 'oauth' };
+  }
+
+  if (cfg?.mcpToken) {
+    return { ok: true, token: cfg.mcpToken, mode: 'static', refreshed: false };
+  }
+
+  return {
+    ok: false,
+    mode: 'none',
+    code: 'no_credentials',
+    message:
+      'no credentials configured. Run `anyslate login` to sign in with your browser, or `anyslate login --token <BEARER>` for CI. Mint a token in the AnySlate desktop app at Avatar (top-right) → API Tokens.',
+  };
+}
+
+/**
+ * `callTool` with the auth lifecycle wrapped around it: proactive refresh, then
+ * at most one refresh-and-retry on a 401.
+ *
+ * The retry is gated on `mode === 'oauth'`: a static token that 401s is revoked
+ * or mistyped, and re-sending it cannot help.
+ *
+ * @param {{cfg: object, env: NodeJS.ProcessEnv, toolName: string, args: object,
+ *          fetchImpl?: typeof fetch, timeoutMs?: number}} opts
+ * @returns {Promise<object>} the callTool result, plus `authMode` / `authWarning`,
+ *   or an auth failure shaped like a callTool failure (`authError: true`).
+ */
+export async function callToolWithAuth({ cfg, env, toolName, args, fetchImpl, timeoutMs }) {
+  const first = await resolveBearer({ cfg, env, fetchImpl });
+  if (!first.ok) {
+    return { ok: false, status: 0, data: first.message, raw: null, authError: true, authMode: first.mode };
+  }
+
+  const invoke = (token) =>
+    callTool({ apiUrl: cfg.apiUrl, token, toolName, args, fetchImpl, timeoutMs });
+
+  let res = await invoke(first.token);
+  res.authMode = first.mode;
+  if (first.warning) res.authWarning = first.warning;
+
+  const retryable = !res.ok && res.status === 401 && first.mode === 'oauth' && !first.refreshed;
+  if (!retryable) return res;
+
+  const second = await resolveBearer({ cfg, env, fetchImpl, force: true });
+  if (!second.ok) {
+    res.authError = true;
+    res.authRefreshFailed = second.message;
+    return res;
+  }
+  const retried = await invoke(second.token);
+  retried.authMode = second.mode;
+  retried.authRetried = true;
+  if (second.warning) retried.authWarning = second.warning;
+  return retried;
+}
+
+/**
+ * The failure line for a result that failed on AUTH rather than on transport.
+ *
+ * `formatCallFailure` renders `server ${status} — ${data}`, which for an auth
+ * failure that never reached the server would print `server 0` — an HTTP status
+ * that did not happen. Returns null when this is an ordinary failure and the
+ * existing formatter should be used instead.
+ *
+ * @param {string} prefix
+ * @param {object} res
+ * @returns {string|null}
+ */
+export function formatAuthFailure(prefix, res) {
+  if (!res?.authError) return null;
+  if (res.authRefreshFailed) {
+    return `${prefix}: server ${res.status} and the OAuth refresh failed — ${res.authRefreshFailed}\n`;
+  }
+  if (res.status === 0 && !res.networkError) {
+    return `${prefix}: ${typeof res.data === 'string' ? res.data : JSON.stringify(res.data)}\n`;
+  }
+  return null;
+}

package/src/commands/checkpoint.mjs

@@ -12,7 +12,8 @@
 // stdout carries results only. Every error goes to stderr.
 
 import { loadConfig, requireToken, apiUrlNormalizationNotice, DISABLED_NOTICE } from '../config.mjs';
-import { callTool, formatCallFailure } from '../mcp-client.mjs';
+import { formatCallFailure } from '../mcp-client.mjs';
+import { callToolWithAuth, formatAuthFailure } from '../auth.mjs';
 import { recordRun } from '../runlog.mjs';
 import { VERSION } from '../version.mjs';
 import { makeIo } from '../io.mjs';
@@ -51,10 +52,11 @@ export async function runCheckpoint(argv, deps = {}) {
   const notice = apiUrlNormalizationNotice(cfg);
   if (notice) err.write(notice);
 
-  const tokenCheck = requireToken(cfg);
-  if (!tokenCheck.ok) {
-    err.write(`anyslate checkpoint: ${tokenCheck.error}\n`);
-    recordRun({ command: 'checkpoint', ok: false, apiUrl: cfg.apiUrl, error: tokenCheck.error, version: VERSION, exitCode: 1 }, env);
+  // Presence only — an expired OAuth token is refreshed by callToolWithAuth.
+  if (cfg.authMode === 'none') {
+    const error = requireToken({ mcpToken: null }).error;
+    err.write(`anyslate checkpoint: ${error}\n`);
+    recordRun({ command: 'checkpoint', ok: false, apiUrl: cfg.apiUrl, error, version: VERSION, exitCode: 1 }, env);
     return 1;
   }
 
@@ -74,15 +76,16 @@ export async function runCheckpoint(argv, deps = {}) {
   if (flags.session) args.session_id_hint = flags.session;
 
   try {
-    const res = await callTool({
-      apiUrl: cfg.apiUrl,
-      token: cfg.mcpToken,
+    const res = await callToolWithAuth({
+      cfg,
+      env,
       toolName: 'activity_submit',
       args,
       fetchImpl: deps.fetchImpl,
     });
+    if (res.authWarning) err.write(`${res.authWarning}\n`);
     if (!res.ok) {
-      const message = formatCallFailure('anyslate checkpoint', res);
+      const message = formatAuthFailure('anyslate checkpoint', res) ?? formatCallFailure('anyslate checkpoint', res);
       err.write(message);
       recordRun(
         {