@mnemom/mnemom 0.17.0-next.6 → 0.17.0-next.8

package/dist/lib/auth.js

@@ -117,7 +117,14 @@ export async function getAccessToken() {
     if (auth.expiresAt > now + 60) {
         return auth.accessToken;
     }
-    // Auto-refresh
+    // Auto-refresh. A *thrown* error from refreshStoredTokens() (transient
+    // exhaustion / non-revoke 4xx from oauthRefreshTokens(), MNE-7394) is
+    // intentionally allowed to propagate here rather than being coerced to the
+    // `null` re-login signal — a momentary AS outage must not masquerade as
+    // "credentials revoked". Only a genuine invalid_grant/invalid_client returns
+    // null (see refreshStoredTokens). Refining caller-side handling (distinguish
+    // propagate-vs-degrade) is tracked under MNE-7394's parent lane card
+    // (keith/oauth-token-lifetime).
     const refreshed = await refreshStoredTokens(auth);
     if (refreshed)
         return refreshed.accessToken;
@@ -139,6 +146,9 @@ export async function forceRefreshAccessToken() {
     const auth = getAuthInfo();
     if (!auth?.refreshToken)
         return null;
+    // As in getAccessToken, a thrown transient-exhaustion / non-revoke error from
+    // refreshStoredTokens() propagates rather than being coerced to null (MNE-7394;
+    // caller-side refinement tracked under keith/oauth-token-lifetime).
     const refreshed = await refreshStoredTokens(auth);
     return refreshed?.accessToken ?? null;
 }
@@ -226,6 +236,16 @@ export async function loginWithDeviceFlow() {
  * Refresh the stored tokens via the OAuth refresh_token grant. Requires both a
  * refresh token and the client_id they were issued to; returns null (rather
  * than throwing) when refresh isn't possible so callers degrade to re-login.
+ *
+ * Note: oauthRefreshTokens() returns null ONLY on a definitive revoke
+ * (invalid_grant/invalid_client) or missing credentials; on transient
+ * exhaustion (repeated 5xx / network faults) or any other non-revoke 4xx it
+ * *throws* (MNE-7394 / R6). That thrown error is intentionally allowed to
+ * propagate through this function to its callers rather than being coerced to
+ * null, so a momentary blip never presents as "credentials revoked". Refining
+ * the caller-side handling (propagate-vs-degrade in
+ * getAccessToken/forceRefreshAccessToken) is tracked under MNE-7394's parent
+ * lane card (keith/oauth-token-lifetime).
  */
 async function refreshStoredTokens(auth) {
     if (!auth.refreshToken || !auth.clientId)

package/dist/lib/{code-config.d.ts → launcher-config.d.ts}

@@ -1,27 +1,27 @@
 /**
- * lib/code-config.ts — persistent per-customer settings for `mnemom code`.
+ * lib/code-config.ts — persistent per-customer settings for `mnemom agent`.
  *
- * Settings live in a human-editable TOML file at ~/.mnemom/code.toml (the
+ * Settings live in a human-editable TOML file at ~/.mnemom/launcher.toml (the
  * Cargo/Codex `config.toml` convention — comments allowed, easy to hand-edit) so
  * a customer never has to retype their flags. The SECRET Anthropic key is
- * deliberately NOT stored here: it stays in ~/.mnemom/code.json at 0600 (see
+ * deliberately NOT stored here: it stays in ~/.mnemom/launcher.json at 0600 (see
  * commands/code.ts), so the file customers open, edit, and share never carries a
  * credential — the same split gh (config.yml/hosts.yml), aws (config/credentials)
  * and Codex (config.toml/auth.json) use.
  *
- * Precedence, highest wins: command-line FLAG > ENV > code.toml > built-in.
- * `loadCodeConfig` is pure parse+validate; `applyConfigToEnv` folds the
+ * Precedence, highest wins: command-line FLAG > ENV > launcher.toml > built-in.
+ * `loadLauncherConfig` is pure parse+validate; `applyConfigToEnv` folds the
  * env-backed settings UNDER any real env var (so env still wins and the
  * resolvers in lib/code.ts keep the built-in default as the final fallback);
  * the caller folds the plain-value settings under the CLI flags.
  */
-import { type LaunchShape } from "./code.js";
-/** The human-editable settings file. Secret key lives elsewhere (code.json). */
-export declare const CODE_CONFIG_PATH: string;
+import { type GoalModeDefault, type LaunchShape } from "./agent.js";
+/** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
+export declare const LAUNCHER_CONFIG_PATH: string;
 /** Where the CLI resolves the Anthropic key from; advisory ordering/restriction. */
 export type KeySource = "env" | "store" | "prompt";
 /** The validated settings, camelCased for TS (TOML keys are snake_case). */
-export interface CodeConfig {
+export interface LauncherConfig {
     gateway?: string;
     model?: string;
     agent?: string;
@@ -29,6 +29,8 @@ export interface CodeConfig {
     cli?: string;
     launch?: LaunchShape;
     keySource?: KeySource;
+    /** Standing goal-alignment default when neither --goal nor --implicit is given. */
+    goalMode?: GoalModeDefault;
     guardrails?: {
         maxTurns?: number;
         budgetUsd?: number;
@@ -36,43 +38,43 @@ export interface CodeConfig {
     };
 }
 /**
- * A settable key: its dotted config name, the getter/setter into a CodeConfig,
+ * A settable key: its dotted config name, the getter/setter into a LauncherConfig,
  * and a one-line description for `config list`/help. Kept as data so get/set/list
  * stay a single source of truth.
  */
 export interface ConfigKeySpec {
     key: string;
     describe: string;
-    get(cfg: CodeConfig): string | number | undefined;
-    set(cfg: CodeConfig, raw: string): void;
+    get(cfg: LauncherConfig): string | number | undefined;
+    set(cfg: LauncherConfig, raw: string): void;
 }
 /** The full set of settable keys — drives get/set/unset/list and validation. */
 export declare const CONFIG_KEYS: ConfigKeySpec[];
 export declare function configKeySpec(key: string): ConfigKeySpec | undefined;
 /**
- * Parse + validate a TOML settings document into a CodeConfig. Pure (no fs), so
+ * Parse + validate a TOML settings document into a LauncherConfig. Pure (no fs), so
  * it is unit-testable. Unknown top-level keys are ignored (forward-compatible);
  * known keys with the wrong shape throw a human-readable error.
  */
-export declare function parseCodeConfig(text: string): CodeConfig;
+export declare function parseLauncherConfig(text: string): LauncherConfig;
 /**
- * Load the settings from ~/.mnemom/code.toml (or `path`). A missing file is an
+ * Load the settings from ~/.mnemom/launcher.toml (or `path`). A missing file is an
  * empty config (never an error — first run has none). A malformed or invalid
  * file throws with the path so the customer can fix it, rather than silently
  * launching with the wrong settings.
  */
-export declare function loadCodeConfig(path?: string): CodeConfig;
-/** Serialize a CodeConfig back to TOML (snake_case keys), with a header comment. */
-export declare function serializeCodeConfig(cfg: CodeConfig): string;
-/** Persist a CodeConfig to `path` (default code.toml), atomically (temp+rename), 0600. */
-export declare function writeCodeConfig(cfg: CodeConfig, path?: string): void;
+export declare function loadLauncherConfig(path?: string): LauncherConfig;
+/** Serialize a LauncherConfig back to TOML (snake_case keys), with a header comment. */
+export declare function serializeLauncherConfig(cfg: LauncherConfig): string;
+/** Persist a LauncherConfig to `path` (default launcher.toml), atomically (temp+rename), 0600. */
+export declare function writeLauncherConfig(cfg: LauncherConfig, path?: string): void;
 /**
  * Fold the ENV-backed settings from config UNDER the environment: set the
- * MNEMOM_CODE_* var ONLY when it is not already present, so a real env var (and
+ * MNEMOM_AGENT_* var ONLY when it is not already present, so a real env var (and
  * therefore a flag that set one) still wins. The resolvers in lib/code.ts then
  * apply the built-in default when neither env nor config supplied a value.
  *
- * launch maps to MNEMOM_CODE_REMOTE_CONTROL using that var's existing contract
+ * launch maps to MNEMOM_AGENT_REMOTE_CONTROL using that var's existing contract
  * (see resolveLaunchShape): terminal→"0", remote-control→"1", server→"server".
  */
-export declare function applyConfigToEnv(cfg: CodeConfig, env?: NodeJS.ProcessEnv): void;
+export declare function applyConfigToEnv(cfg: LauncherConfig, env?: NodeJS.ProcessEnv): void;

package/dist/lib/{code-config.js → launcher-config.js}

@@ -1,16 +1,16 @@
 /**
- * lib/code-config.ts — persistent per-customer settings for `mnemom code`.
+ * lib/code-config.ts — persistent per-customer settings for `mnemom agent`.
  *
- * Settings live in a human-editable TOML file at ~/.mnemom/code.toml (the
+ * Settings live in a human-editable TOML file at ~/.mnemom/launcher.toml (the
  * Cargo/Codex `config.toml` convention — comments allowed, easy to hand-edit) so
  * a customer never has to retype their flags. The SECRET Anthropic key is
- * deliberately NOT stored here: it stays in ~/.mnemom/code.json at 0600 (see
+ * deliberately NOT stored here: it stays in ~/.mnemom/launcher.json at 0600 (see
  * commands/code.ts), so the file customers open, edit, and share never carries a
  * credential — the same split gh (config.yml/hosts.yml), aws (config/credentials)
  * and Codex (config.toml/auth.json) use.
  *
- * Precedence, highest wins: command-line FLAG > ENV > code.toml > built-in.
- * `loadCodeConfig` is pure parse+validate; `applyConfigToEnv` folds the
+ * Precedence, highest wins: command-line FLAG > ENV > launcher.toml > built-in.
+ * `loadLauncherConfig` is pure parse+validate; `applyConfigToEnv` folds the
  * env-backed settings UNDER any real env var (so env still wins and the
  * resolvers in lib/code.ts keep the built-in default as the final fallback);
  * the caller folds the plain-value settings under the CLI flags.
@@ -19,12 +19,13 @@ import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "
 import { dirname, join } from "node:path";
 import { parse as parseToml, stringify as stringifyToml, TomlError } from "smol-toml";
 import { MNEMOM_DIR } from "./config.js";
-import { isPositiveInt, isPositiveNumber } from "./code.js";
-/** The human-editable settings file. Secret key lives elsewhere (code.json). */
-export const CODE_CONFIG_PATH = join(MNEMOM_DIR, "code.toml");
+import { isPositiveInt, isPositiveNumber, } from "./agent.js";
+/** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
+export const LAUNCHER_CONFIG_PATH = join(MNEMOM_DIR, "launcher.toml");
 const LAUNCH_SHAPES = ["terminal", "remote-control", "server"];
 const EFFORTS = ["low", "medium", "high", "xhigh", "max"];
 const KEY_SOURCES = ["env", "store", "prompt"];
+const GOAL_MODES = ["implicit", "off"];
 function coerceLaunch(raw) {
     const v = raw.trim();
     if (LAUNCH_SHAPES.includes(v))
@@ -43,6 +44,12 @@ function coerceKeySource(raw) {
         return v;
     throw new Error(`key_source must be one of ${KEY_SOURCES.join(", ")} (got '${raw}').`);
 }
+function coerceGoalMode(raw) {
+    const v = raw.trim().toLowerCase();
+    if (GOAL_MODES.includes(v))
+        return v;
+    throw new Error(`goal_mode must be one of ${GOAL_MODES.join(", ")} (got '${raw}'). A sealed contract needs a statement, so it is always a per-launch --goal.`);
+}
 function coerceNonEmpty(name, raw) {
     const v = raw.trim();
     if (!v)
@@ -112,6 +119,14 @@ export const CONFIG_KEYS = [
             c.keySource = coerceKeySource(v);
         },
     },
+    {
+        key: "goal_mode",
+        describe: `Goal alignment when no --goal/--implicit is given (${GOAL_MODES.join("|")}); a sealed contract needs a per-launch --goal`,
+        get: (c) => c.goalMode,
+        set: (c, v) => {
+            c.goalMode = coerceGoalMode(v);
+        },
+    },
     {
         key: "guardrails.max_turns",
         describe: "Contract guardrail: turn ceiling (positive integer)",
@@ -147,18 +162,18 @@ export function configKeySpec(key) {
     return CONFIG_KEYS.find((k) => k.key === key);
 }
 /**
- * Parse + validate a TOML settings document into a CodeConfig. Pure (no fs), so
+ * Parse + validate a TOML settings document into a LauncherConfig. Pure (no fs), so
  * it is unit-testable. Unknown top-level keys are ignored (forward-compatible);
  * known keys with the wrong shape throw a human-readable error.
  */
-export function parseCodeConfig(text) {
+export function parseLauncherConfig(text) {
     let raw;
     try {
         raw = parseToml(text);
     }
     catch (err) {
         const detail = err instanceof TomlError ? err.message : String(err);
-        throw new Error(`could not parse code.toml: ${detail}`);
+        throw new Error(`could not parse launcher.toml: ${detail}`, { cause: err });
     }
     const cfg = {};
     const str = (v) => typeof v === "string" && v.trim() ? v.trim() : v === undefined ? undefined : String(v);
@@ -176,6 +191,8 @@ export function parseCodeConfig(text) {
         cfg.launch = coerceLaunch(str(raw.launch) ?? "");
     if (raw.key_source !== undefined)
         cfg.keySource = coerceKeySource(str(raw.key_source) ?? "");
+    if (raw.goal_mode !== undefined)
+        cfg.goalMode = coerceGoalMode(str(raw.goal_mode) ?? "");
     const g = raw.guardrails;
     if (g !== undefined) {
         if (typeof g !== "object" || g === null || Array.isArray(g)) {
@@ -192,12 +209,12 @@ export function parseCodeConfig(text) {
     return cfg;
 }
 /**
- * Load the settings from ~/.mnemom/code.toml (or `path`). A missing file is an
+ * Load the settings from ~/.mnemom/launcher.toml (or `path`). A missing file is an
  * empty config (never an error — first run has none). A malformed or invalid
  * file throws with the path so the customer can fix it, rather than silently
  * launching with the wrong settings.
  */
-export function loadCodeConfig(path = CODE_CONFIG_PATH) {
+export function loadLauncherConfig(path = LAUNCHER_CONFIG_PATH) {
     if (!existsSync(path))
         return {};
     let text;
@@ -208,15 +225,15 @@ export function loadCodeConfig(path = CODE_CONFIG_PATH) {
         return {};
     }
     try {
-        return parseCodeConfig(text);
+        return parseLauncherConfig(text);
     }
     catch (err) {
         const msg = err instanceof Error ? err.message : String(err);
-        throw new Error(`mnemom code: ${msg}\n  Fix or remove ${path}.`);
+        throw new Error(`mnemom agent: ${msg}\n  Fix or remove ${path}.`, { cause: err });
     }
 }
-/** Serialize a CodeConfig back to TOML (snake_case keys), with a header comment. */
-export function serializeCodeConfig(cfg) {
+/** Serialize a LauncherConfig back to TOML (snake_case keys), with a header comment. */
+export function serializeLauncherConfig(cfg) {
     const doc = {};
     if (cfg.gateway !== undefined)
         doc.gateway = cfg.gateway;
@@ -232,6 +249,8 @@ export function serializeCodeConfig(cfg) {
         doc.launch = cfg.launch;
     if (cfg.keySource !== undefined)
         doc.key_source = cfg.keySource;
+    if (cfg.goalMode !== undefined)
+        doc.goal_mode = cfg.goalMode;
     const g = cfg.guardrails;
     if (g && (g.maxTurns !== undefined || g.budgetUsd !== undefined || g.stallTurns !== undefined)) {
         const gr = {};
@@ -243,39 +262,39 @@ export function serializeCodeConfig(cfg) {
             gr.stall_turns = g.stallTurns;
         doc.guardrails = gr;
     }
-    const header = "# ~/.mnemom/code.toml — settings for `mnemom code` (the governed coding-agent launcher).\n" +
+    const header = "# ~/.mnemom/launcher.toml — settings for `mnemom agent` (the governed coding-agent launcher).\n" +
         "# Command-line flags override these; these override the built-in defaults.\n" +
-        "# The secret Anthropic key is NOT here — it lives in ~/.mnemom/code.json (0600).\n" +
-        "# Edit with `mnemom code config edit`, or set one key with `mnemom code config set <key> <value>`.\n\n";
+        "# The secret Anthropic key is NOT here — it lives in ~/.mnemom/launcher.json (0600).\n" +
+        "# Edit with `mnemom agent config edit`, or set one key with `mnemom agent config set <key> <value>`.\n\n";
     const body = Object.keys(doc).length ? stringifyToml(doc) : "";
     return `${header}${body}${body.endsWith("\n") || !body ? "" : "\n"}`;
 }
-/** Persist a CodeConfig to `path` (default code.toml), atomically (temp+rename), 0600. */
-export function writeCodeConfig(cfg, path = CODE_CONFIG_PATH) {
+/** Persist a LauncherConfig to `path` (default launcher.toml), atomically (temp+rename), 0600. */
+export function writeLauncherConfig(cfg, path = LAUNCHER_CONFIG_PATH) {
     const dir = dirname(path);
     mkdirSync(dir, { recursive: true });
     const tmp = join(dir, `.code-toml-tmp-${process.pid}-${Date.now()}`);
-    writeFileSync(tmp, serializeCodeConfig(cfg), { mode: 0o600 });
+    writeFileSync(tmp, serializeLauncherConfig(cfg), { mode: 0o600 });
     renameSync(tmp, path);
 }
 /**
  * Fold the ENV-backed settings from config UNDER the environment: set the
- * MNEMOM_CODE_* var ONLY when it is not already present, so a real env var (and
+ * MNEMOM_AGENT_* var ONLY when it is not already present, so a real env var (and
  * therefore a flag that set one) still wins. The resolvers in lib/code.ts then
  * apply the built-in default when neither env nor config supplied a value.
  *
- * launch maps to MNEMOM_CODE_REMOTE_CONTROL using that var's existing contract
+ * launch maps to MNEMOM_AGENT_REMOTE_CONTROL using that var's existing contract
  * (see resolveLaunchShape): terminal→"0", remote-control→"1", server→"server".
  */
 export function applyConfigToEnv(cfg, env = process.env) {
-    if (cfg.gateway && !(env.MNEMOM_CODE_GATEWAY ?? "").trim()) {
-        env.MNEMOM_CODE_GATEWAY = cfg.gateway;
+    if (cfg.gateway && !(env.MNEMOM_AGENT_GATEWAY ?? "").trim()) {
+        env.MNEMOM_AGENT_GATEWAY = cfg.gateway;
     }
-    if (cfg.cli && !(env.MNEMOM_CODE_CLI ?? "").trim()) {
-        env.MNEMOM_CODE_CLI = cfg.cli;
+    if (cfg.cli && !(env.MNEMOM_AGENT_CLI ?? "").trim()) {
+        env.MNEMOM_AGENT_CLI = cfg.cli;
     }
-    if (cfg.launch && !(env.MNEMOM_CODE_REMOTE_CONTROL ?? "").trim()) {
-        env.MNEMOM_CODE_REMOTE_CONTROL =
+    if (cfg.launch && !(env.MNEMOM_AGENT_REMOTE_CONTROL ?? "").trim()) {
+        env.MNEMOM_AGENT_REMOTE_CONTROL =
             cfg.launch === "server" ? "server" : cfg.launch === "remote-control" ? "1" : "0";
     }
 }

package/dist/lib/oauth.d.ts

@@ -105,11 +105,33 @@ export declare function loginWithDevice(opts?: {
     sleep?: (ms: number) => Promise<void>;
 }): Promise<DeviceResult>;
 /**
- * Exchange a refresh token for a fresh access token. Returns null if refresh is
- * not possible (no refresh token, or the AS rejects it — e.g. revoked/expired),
- * so callers can fall back to prompting for re-login rather than crashing.
+ * Exchange a refresh token for a fresh access token.
+ *
+ * Failure classification (R6 / MNE-7394) — a transient failure must never be
+ * indistinguishable from a revoked credential:
+ *   - 2xx → return the fresh tokens (carrying the prior refresh token forward
+ *     per RFC 6749 §6 when the AS omits a new one).
+ *   - A 4xx whose OAuth body `error` is `invalid_grant` / `invalid_client` →
+ *     return `null`, the re-login signal. RFC 6749 §5.2 defines these as the
+ *     errors that mean the presented grant/client credential is genuinely no
+ *     longer valid, so a fresh login is the correct remedy. No retry.
+ *   - Any other 4xx (e.g. `invalid_request`, `429`, an unrecognized/absent body
+ *     error, a non-JSON body) → throw. Something is wrong, but it does NOT mean
+ *     the credentials are revoked, so we must not discard the session.
+ *   - `res.status >= 500` or a fetch/network exception → retry with bounded
+ *     exponential backoff (~1s/2s/4s, REFRESH_MAX_ATTEMPTS attempts); if the
+ *     retries are exhausted, throw. Exhausting transient retries must NOT
+ *     masquerade as "credentials revoked" (fail-closed, MNE-442) — throwing
+ *     preserves the stored session so a later invocation can succeed once the
+ *     AS recovers.
+ *
+ * `null` is therefore narrowed to exactly the two re-login errors; every other
+ * outcome is a success, a retry, or a thrown error. `opts.sleep` is injectable
+ * so tests drive the backoff without real timers.
  */
-export declare function refreshTokens(refreshToken: string, clientId: string): Promise<OAuthTokens | null>;
+export declare function refreshTokens(refreshToken: string, clientId: string, opts?: {
+    sleep?: (ms: number) => Promise<void>;
+}): Promise<OAuthTokens | null>;
 /**
  * Open `url` in the user's default browser WITHOUT a shell. The URL is always
  * passed as a separate argv element (never concatenated into a command string),

package/dist/lib/oauth.js

@@ -39,6 +39,14 @@ const LOOPBACK_TIMEOUT_MS = 5 * 60 * 1000;
 // both interactive login poll loops emit, so a multi-minute browser sign-in
 // doesn't read as a hung CLI (matches the card-write retry tick in try-me).
 const LOGIN_HEARTBEAT_MS = 15 * 1000;
+// Refresh-token retry policy (R6 / MNE-7394). A transient AS 5xx or a dropped
+// network connection during refresh must be retried with bounded exponential
+// backoff rather than collapsed into the re-login signal — a one-second AS
+// hiccup or a flaky Wi-Fi moment must not invalidate a valid, long-lived
+// session. Per-attempt delay is REFRESH_BACKOFF_BASE_MS * 2**attemptIndex →
+// ~1s / 2s / 4s across REFRESH_MAX_ATTEMPTS attempts.
+const REFRESH_MAX_ATTEMPTS = 3;
+const REFRESH_BACKOFF_BASE_MS = 1000;
 let cachedMetadata = null;
 /**
  * Fetch (and process-cache) the AS metadata document. We resolve it relative to
@@ -359,40 +367,101 @@ async function pollDeviceToken(meta, clientId, authz, sleep, display) {
 // Refresh (RFC 6749 §6)
 // ============================================================================
 /**
- * Exchange a refresh token for a fresh access token. Returns null if refresh is
- * not possible (no refresh token, or the AS rejects it — e.g. revoked/expired),
- * so callers can fall back to prompting for re-login rather than crashing.
+ * Exchange a refresh token for a fresh access token.
+ *
+ * Failure classification (R6 / MNE-7394) — a transient failure must never be
+ * indistinguishable from a revoked credential:
+ *   - 2xx → return the fresh tokens (carrying the prior refresh token forward
+ *     per RFC 6749 §6 when the AS omits a new one).
+ *   - A 4xx whose OAuth body `error` is `invalid_grant` / `invalid_client` →
+ *     return `null`, the re-login signal. RFC 6749 §5.2 defines these as the
+ *     errors that mean the presented grant/client credential is genuinely no
+ *     longer valid, so a fresh login is the correct remedy. No retry.
+ *   - Any other 4xx (e.g. `invalid_request`, `429`, an unrecognized/absent body
+ *     error, a non-JSON body) → throw. Something is wrong, but it does NOT mean
+ *     the credentials are revoked, so we must not discard the session.
+ *   - `res.status >= 500` or a fetch/network exception → retry with bounded
+ *     exponential backoff (~1s/2s/4s, REFRESH_MAX_ATTEMPTS attempts); if the
+ *     retries are exhausted, throw. Exhausting transient retries must NOT
+ *     masquerade as "credentials revoked" (fail-closed, MNE-442) — throwing
+ *     preserves the stored session so a later invocation can succeed once the
+ *     AS recovers.
+ *
+ * `null` is therefore narrowed to exactly the two re-login errors; every other
+ * outcome is a success, a retry, or a thrown error. `opts.sleep` is injectable
+ * so tests drive the backoff without real timers.
  */
-export async function refreshTokens(refreshToken, clientId) {
+export async function refreshTokens(refreshToken, clientId, opts) {
     if (!refreshToken || !clientId)
         return null;
-    try {
-        const meta = await discover();
-        const res = await fetch(meta.token_endpoint, {
-            method: "POST",
-            headers: {
-                "Content-Type": "application/x-www-form-urlencoded",
-                Accept: "application/json",
-            },
-            body: new URLSearchParams({
-                grant_type: "refresh_token",
-                refresh_token: refreshToken,
-                client_id: clientId,
-            }),
-        });
-        if (!res.ok)
+    const sleep = opts?.sleep ?? defaultSleep;
+    // Discovery is not part of the refresh retry budget; a discovery failure
+    // propagates as it does today (it is already thrown by discover()).
+    const meta = await discover();
+    let lastTransient = "";
+    for (let attempt = 0; attempt < REFRESH_MAX_ATTEMPTS; attempt++) {
+        let res;
+        try {
+            res = await fetch(meta.token_endpoint, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    Accept: "application/json",
+                },
+                body: new URLSearchParams({
+                    grant_type: "refresh_token",
+                    refresh_token: refreshToken,
+                    client_id: clientId,
+                }),
+            });
+        }
+        catch (err) {
+            // Network/fetch exception (DNS failure, connection reset, timeout) — this
+            // is unrelated to the validity of the refresh token, so retry it.
+            lastTransient = err instanceof Error ? err.message : String(err);
+            if (attempt < REFRESH_MAX_ATTEMPTS - 1) {
+                await sleep(REFRESH_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            break;
+        }
+        if (res.ok) {
+            const data = (await res.json());
+            const tokens = tokensFromResponse(data);
+            // Per RFC 6749 §6, a refresh response MAY omit a new refresh token, in
+            // which case the old one remains valid — preserve it so the next refresh
+            // works.
+            if (!tokens.refreshToken)
+                tokens.refreshToken = refreshToken;
+            return tokens;
+        }
+        if (res.status >= 500) {
+            // Transient AS outage — retry with backoff, then fall through to the
+            // "exhausted" throw once no attempts remain.
+            lastTransient = `HTTP ${res.status}`;
+            if (attempt < REFRESH_MAX_ATTEMPTS - 1) {
+                await sleep(REFRESH_BACKOFF_BASE_MS * 2 ** attempt);
+                continue;
+            }
+            break;
+        }
+        // 4xx — a definitive client-side rejection, never retried. Only
+        // invalid_grant / invalid_client map to the null re-login signal; every
+        // other 4xx surfaces as a thrown error rather than a silent null that would
+        // wrongly discard a valid session.
+        const body = (await res.json().catch(() => ({})));
+        if (body.error === "invalid_grant" || body.error === "invalid_client") {
             return null;
-        const data = (await res.json());
-        const tokens = tokensFromResponse(data);
-        // Per RFC 6749 §6, a refresh response MAY omit a new refresh token, in which
-        // case the old one remains valid — preserve it so the next refresh works.
-        if (!tokens.refreshToken)
-            tokens.refreshToken = refreshToken;
-        return tokens;
-    }
-    catch {
-        return null;
+        }
+        const detail = body.error
+            ? body.error + (body.error_description ? ` — ${body.error_description}` : "")
+            : `HTTP ${res.status}`;
+        throw new Error(`Token refresh failed: ${detail}`);
     }
+    // Retries exhausted on a 5xx or a network exception (fail-closed, MNE-442):
+    // throw rather than return null so the session is preserved for a later retry.
+    throw new Error(`Token refresh failed after ${REFRESH_MAX_ATTEMPTS} attempts ` +
+        `(last error: ${lastTransient || "unknown transient failure"}).`);
 }
 // ============================================================================
 // Helpers

package/dist/lib/version-gate.js

@@ -67,7 +67,7 @@ export function enforceMinCliVersion(response, exit = process.exit, write = (chu
         return;
     exited = true;
     write(`\n✖ Your Mnemom CLI (v${CLI_VERSION}) is too old for this server (minimum v${floor}).\n` +
-        `  Old CLIs can silently drop newer request fields — e.g. \`--org\` on \`mnemom agents claim\`.\n\n` +
+        `  Old CLIs can silently drop newer request fields — e.g. \`--org\` on \`mnemom agent claim\`.\n\n` +
         `  Upgrade:  npm i -g @mnemom/mnemom@latest\n\n`);
     exit(1);
 }