omnirush 0.8.5 → 0.9.0

package/assets/extensions/omnirush/auth.js

@@ -17,7 +17,11 @@
 //        -> 400 {"detail":"expired_token"}                    (unknown/expired)
 //   POST /device/refresh {refresh_token}
 //        -> 200 {access_token, refresh_token, gateway_url?}   (rotate both)
-//        -> 401 {"detail":"refresh_token_invalid_or_expired"}
+//        -> 401 {"detail":"refresh_token_invalid_or_expired"} (not the
+//           device's current refresh token — superseded more than the
+//           rotation grace ago — or the device was revoked/expired)
+//        -> 409 {"detail":"refresh_token_already_used"}       (race)
+//        -> 403 {"detail":"account_inactive|account_pending|account_rejected"}
 //   GET  /device/me        -> 200 device identity | 401 device_token_invalid
 //   POST /collect          -> zstd body, X-Omnirush-Session-ID header
 //
@@ -78,14 +82,36 @@ function ensureDir(dir) {
   fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
 }
 
-function readJsonFile(filePath) {
+/** Synchronous sleep (tiny waits between file-system retries only). */
+function sleepSync(ms) {
   try {
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
   } catch {
-    return null;
+    /* no Atomics.wait (never on node/bun): skip the pause */
   }
 }
 
+function readJsonFile(filePath) {
+  // An older CLI (before atomic writes) truncates then writes, so a
+  // reader can catch the file empty or half-written for a moment: a
+  // parse failure on an existing file is retried briefly before it
+  // counts as "no credentials".
+  for (let attempt = 0; attempt < 4; attempt++) {
+    let text;
+    try {
+      text = fs.readFileSync(filePath, "utf8");
+    } catch {
+      return null;
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      if (attempt < 3) sleepSync(15 * (attempt + 1));
+    }
+  }
+  return null;
+}
+
 /**
  * Enforce 0600 where POSIX mode bits exist (repairing files that were
  * written too openly). On Windows chmod is a permissions no-op — it only
@@ -101,10 +127,51 @@ function repairPosixMode(filePath) {
   }
 }
 
+const WINDOWS_BUSY = new Set(["EPERM", "EACCES", "EBUSY"]);
+
+/**
+ * Atomic replace: write a private temp file next to the target, flush it,
+ * rename it over the target. Readers in other processes see either the
+ * old or the new file, never a truncated one. On Windows a rename over a
+ * file another process has open can fail transiently (EPERM/EACCES/
+ * EBUSY) — retried with a short backoff.
+ */
+export function writeFileAtomic(filePath, data) {
+  const tmp = `${filePath}.${process.pid}.${Math.random().toString(36).slice(2, 10)}.tmp`;
+  const fd = fs.openSync(tmp, "wx", 0o600);
+  try {
+    fs.writeSync(fd, data);
+    try {
+      fs.fsyncSync(fd);
+    } catch {
+      /* not every filesystem supports fsync */
+    }
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    for (let attempt = 0; ; attempt++) {
+      try {
+        fs.renameSync(tmp, filePath);
+        return;
+      } catch (error) {
+        if (attempt >= 9 || !WINDOWS_BUSY.has(error?.code)) throw error;
+        sleepSync(20 * (attempt + 1));
+      }
+    }
+  } finally {
+    try {
+      fs.rmSync(tmp, { force: true });
+    } catch {
+      /* already renamed away */
+    }
+  }
+}
+
 function writeJsonFile0600(dir, name, value) {
   ensureDir(dir);
   const filePath = path.join(dir, name);
-  fs.writeFileSync(filePath, JSON.stringify(value, null, 2) + "\n", { mode: 0o600 });
+  writeFileAtomic(filePath, JSON.stringify(value, null, 2) + "\n");
   repairPosixMode(filePath);
 }
 
@@ -301,79 +368,177 @@ export async function pollForToken(origin, {
   }
 }
 
-// --- cross-process refresh coordination (issue B) --------------------------
+// --- cross-process refresh coordination ------------------------------------
 //
-// Several omnirush processes on one machine share ~/.omnirush/auth.json.
-// When the access token expires, every process sees the same 401 and
-// would refresh with the SAME refresh token; the first winner ROTATES
-// both tokens, the others' attempts then fail with a rejected refresh
-// token and they dead-end telling the (still signed-in!) user to log in
-// again. The refresher therefore: adopts newer on-disk tokens before
-// refreshing, serializes actual refreshes behind an exclusive lockfile,
-// and re-reads once more before declaring the session dead.
-
+// Every omnirush process on a machine — each terminal, and every
+// spawn_agents sub-agent (a separate process) — shares
+// <OMNIRUSH_DIR>/auth.json. The manager rotates BOTH tokens on every
+// refresh and remembers only the one refresh token a rotation just
+// replaced, for a short grace window (120 s on the live backend), so two
+// processes refreshing with the same pair minutes apart would leave the
+// second one holding a dead refresh token although the device session is
+// fine. The rules:
+//   - auth.json is the only source of truth: every request re-reads it
+//     (a token held in memory or in the environment goes stale the
+//     moment another process rotates);
+//   - a 401 first adopts a newer on-disk pair; only when the disk still
+//     holds the token that failed does anyone call /device/refresh, and
+//     then only under an exclusive lock, re-reading after acquiring it;
+//   - writes are atomic (temp file + rename), so no reader ever sees a
+//     half-written pair;
+//   - "session no longer valid" is reported only when the refresh token
+//     that is on disk RIGHT NOW (re-read under the lock) is rejected.
+
+// Same name as earlier releases, so old and new CLIs running side by
+// side still serialize against each other.
 const REFRESH_LOCK_FILE = ".refresh-lock";
 const REFRESH_LOCK_STALE_MS = 30_000;
-const REFRESH_LOCK_WAIT_MS = 35_000;
-const REFRESH_LOCK_POLL_MS = 200;
+const REFRESH_LOCK_WAIT_MS = 45_000;
+const REFRESH_LOCK_POLL_MS = 100;
+const REFRESH_LOCK_HEARTBEAT_MS = 5_000;
+
+function readLockInfo(lockPath) {
+  try {
+    const value = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+    return value && typeof value === "object" ? value : {};
+  } catch {
+    return null;
+  }
+}
+
+/** True when `pid` is certainly gone (only checkable on this host). */
+function processIsGone(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return false;
+  } catch (error) {
+    return error?.code === "ESRCH";
+  }
+}
+
+function lockIsStale(lockPath, info, staleMs, now) {
+  // Holder died (same host: its pid is gone) -> stale right away.
+  if (info && info.host === os.hostname() && processIsGone(info.pid)) return true;
+  // Otherwise by age: the holder refreshes its mtime every few seconds
+  // (heartbeat), so an old mtime means a hung or crashed holder.
+  try {
+    const stats = fs.statSync(lockPath);
+    return now() - stats.mtimeMs > staleMs;
+  } catch {
+    return false; // vanished — the caller just retries the create
+  }
+}
 
 /**
- * Take the exclusive refresh lock (O_EXCL create). A lock older than
- * REFRESH_LOCK_STALE_MS is crashed-process debris and is taken over.
- * Resolves true when WE hold the lock, false when it could not be
- * acquired within the wait budget (caller proceeds unlocked — an extra
- * rejected refresh is recoverable, a hang is not).
+ * Take the exclusive cross-process refresh lock (O_EXCL create, which
+ * works the same on Windows). Returns a handle for releaseRefreshLock, or
+ * null when it could not be had within `waitMs` (the caller then goes on
+ * unlocked — an extra refresh is recoverable, a hang is not).
  */
-async function acquireRefreshLock(dir, sleep) {
+export async function acquireRefreshLock(dir, {
+  staleMs = REFRESH_LOCK_STALE_MS,
+  waitMs = REFRESH_LOCK_WAIT_MS,
+  pollMs = REFRESH_LOCK_POLL_MS,
+  heartbeatMs = REFRESH_LOCK_HEARTBEAT_MS,
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+  now = () => Date.now(),
+} = {}) {
   const lockPath = path.join(dir, REFRESH_LOCK_FILE);
-  const deadline = Date.now() + REFRESH_LOCK_WAIT_MS;
+  const nonce = `${process.pid}-${Math.random().toString(36).slice(2, 12)}`;
+  const deadline = now() + waitMs;
+  try {
+    ensureDir(dir);
+  } catch {
+    return null;
+  }
   for (;;) {
     try {
       const fd = fs.openSync(lockPath, "wx", 0o600);
-      fs.writeSync(fd, JSON.stringify({ pid: process.pid, at: Date.now() }));
-      fs.closeSync(fd);
-      return true;
-    } catch (error) {
-      if (error?.code !== "EEXIST") return false;
       try {
-        const stats = fs.statSync(lockPath);
-        if (Date.now() - stats.mtimeMs > REFRESH_LOCK_STALE_MS) {
-          fs.rmSync(lockPath, { force: true });
+        fs.writeSync(fd, JSON.stringify({ pid: process.pid, host: os.hostname(), nonce, at: now() }));
+      } finally {
+        fs.closeSync(fd);
+      }
+      let heartbeat = null;
+      if (heartbeatMs > 0) {
+        heartbeat = setInterval(() => {
+          try {
+            const at = new Date();
+            fs.utimesSync(lockPath, at, at);
+          } catch {
+            /* lost the file — release copes */
+          }
+        }, heartbeatMs);
+        heartbeat.unref?.();
+      }
+      return { lockPath, nonce, heartbeat };
+    } catch (error) {
+      const code = error?.code;
+      if (code === "EEXIST") {
+        const info = readLockInfo(lockPath);
+        if (lockIsStale(lockPath, info, staleMs, now)) {
+          // Remove it only if it is still the lock we judged stale.
+          const again = readLockInfo(lockPath);
+          if ((again?.nonce ?? null) === (info?.nonce ?? null)) {
+            try {
+              fs.rmSync(lockPath, { force: true });
+            } catch {
+              /* Windows: someone has it open — retry below */
+            }
+          }
           continue;
         }
-      } catch {
-        continue; // vanished — retry the create
+      } else if (!WINDOWS_BUSY.has(code)) {
+        // Read-only or vanished state dir: no lock is possible at all.
+        return null;
       }
     }
-    if (Date.now() >= deadline) return false;
-    await sleep(REFRESH_LOCK_POLL_MS);
+    if (now() >= deadline) return null;
+    await sleep(pollMs + Math.floor(Math.random() * pollMs));
   }
 }
 
-/** Release the refresh lock, but only if we still own it. */
-function releaseRefreshLock(dir) {
-  const lockPath = path.join(dir, REFRESH_LOCK_FILE);
+/** Release the refresh lock, but only if it is still ours. */
+export function releaseRefreshLock(handle) {
+  if (!handle) return;
+  if (handle.heartbeat) clearInterval(handle.heartbeat);
+  const info = readLockInfo(handle.lockPath);
+  if (info?.nonce !== handle.nonce) return;
   try {
-    const content = fs.readFileSync(lockPath, "utf8");
-    if (content.includes(String(process.pid))) fs.rmSync(lockPath, { force: true });
+    fs.rmSync(handle.lockPath, { force: true });
   } catch {
-    /* gone already */
+    /* gone already, or Windows holds it open: the next taker ages it out */
   }
 }
 
+/**
+ * The manager refused a refresh. `status` is the HTTP status and `detail`
+ * the manager's code: 401 refresh_token_invalid_or_expired (the token is
+ * not the device's current one — or the device was revoked or expired;
+ * the manager does not tell these apart), 409 refresh_token_already_used
+ * (lost a race inside the manager), 403 account_* (account not usable).
+ */
 export class RefreshRejectedError extends Error {
-  constructor(detail) {
+  constructor(detail, status = 0) {
     super(`refresh rejected: ${detail}`);
     this.name = "RefreshRejectedError";
+    this.detail = detail;
+    this.status = status;
   }
 }
 
-/** Rotate both tokens. Throws RefreshRejectedError when the refresh token is dead. */
+/** Rotate both tokens. Throws RefreshRejectedError when the manager refuses. */
 export async function refreshTokens(origin, { refreshToken, fetchImpl } = {}) {
   const doFetch = fetchImpl ?? globalThis.fetch;
   const { response, payload } = await postJson(`${origin}/device/refresh`, { refresh_token: refreshToken }, doFetch);
   if (!response.ok) {
-    throw new RefreshRejectedError(detailOf(payload, `HTTP ${response.status}`));
+    if (response.status === 401 || response.status === 403 || response.status === 409 || response.status === 400) {
+      throw new RefreshRejectedError(detailOf(payload, `HTTP ${response.status}`), response.status);
+    }
+    // 5xx that outlived the retries, or anything unexpected: not a verdict
+    // on the session.
+    throw new Error(`device refresh failed: HTTP ${response.status}`);
   }
   const accessToken = typeof payload?.access_token === "string" ? payload.access_token : "";
   const nextRefreshToken = typeof payload?.refresh_token === "string" ? payload.refresh_token : "";
@@ -386,6 +551,34 @@ export async function refreshTokens(origin, { refreshToken, fetchImpl } = {}) {
   return { accessToken, refreshToken: nextRefreshToken, ...(gatewayUrl ? { gatewayUrl } : {}) };
 }
 
+/** The line a dead session prints (and why), by recover() outcome reason. */
+export function sessionEndedMessage(outcome) {
+  if (outcome?.reason === "account") {
+    return `Omnirush: this account cannot use Omnirush right now (${outcome.detail || "account not active"}) — see https://omnirush.ai/console`;
+  }
+  if (outcome?.reason === "signed_out") {
+    return "Omnirush: not signed in — run `omnirush login` to sign in.";
+  }
+  return "Omnirush: this device's session is no longer valid — run `omnirush login` to sign in again.";
+}
+
+/**
+ * Environment for a child omnirush process (sub-agent): where the shared
+ * credentials live, plus the CURRENT on-disk access token as a bootstrap
+ * value only — the child re-reads auth.json for every request, so a
+ * later rotation by any process never strands it.
+ */
+export function childAuthEnv(env = process.env) {
+  const dir = omniDir(env);
+  const out = { OMNIRUSH_DIR: dir };
+  const auth = loadAuth(dir);
+  if (auth) {
+    out.OMNIRUSH_TOKEN = auth.accessToken;
+    out.OMNIRUSH_ACCESS_TOKEN = auth.accessToken;
+  }
+  return out;
+}
+
 export async function deviceMe(origin, { accessToken, fetchImpl } = {}) {
   const doFetch = fetchImpl ?? globalThis.fetch;
   // 401 is a protocol answer (stale access token — the caller refreshes
@@ -428,108 +621,199 @@ export function redactForDisplay(value) {
 }
 
 /**
- * Single-flight token refresher (the GUI broker pattern): concurrent
- * callers share one HTTP refresh; a caller whose expected token was
- * already rotated resolves true without touching the network. Rotated
- * credentials persist back to the state dir (0600) before resolution.
+ * The process's view of the shared device credentials, and the one way
+ * to recover from a 401.
+ *
+ *   accessToken()      the current access token — re-read from auth.json
+ *                      on every call, so a rotation by any other process
+ *                      (another terminal, a sub-agent) is picked up by
+ *                      the very next request;
+ *   recover(tokenUsed) after a 401 on `tokenUsed`: resolves
+ *                      {status:"ok", accessToken} with a token worth
+ *                      retrying with, {status:"dead", reason, detail}
+ *                      when the device session is really gone
+ *                      (reason "session" | "account" | "signed_out"), or
+ *                      {status:"transient", error} when the manager could
+ *                      not be asked (network, 5xx) — never a sign-out.
+ *   refresh(expected)  the older boolean form of recover().
+ *
+ * Callers retry with the returned token and call recover() again if that
+ * one is refused too (an adopted on-disk token may itself have expired;
+ * the second call then refreshes it). Concurrent callers in one process
+ * share one recovery; across processes the refresh lock serializes.
  */
-export function createRefresher({ dir, origin, fetchImpl, now = () => Date.now() } = {}) {
+export function createRefresher({
+  dir,
+  origin,
+  fetchImpl,
+  now = () => Date.now(),
+  lock: lockOptions = {},
+  sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+} = {}) {
   const doFetch = fetchImpl ?? globalThis.fetch;
-  let auth = dir ? loadAuth(dir) : null;
+  // In-memory copy: only the fallback when there is no state dir, or the
+  // file cannot be read at the moment.
+  let memory = dir ? loadAuth(dir) : null;
   let inflight = null;
   let lastPersistError = null;
-
-  const setAuth = (next) => {
-    auth = next;
+  // A refresh token the manager already declared dead: answer later
+  // callers from here instead of asking again with the same token.
+  let deadFor = null;
+
+  const reload = () => {
+    if (!dir) return memory;
+    const disk = loadAuth(dir);
+    if (disk) memory = disk;
+    else if (!fs.existsSync(authFilePath(dir))) memory = null; // signed out
+    return memory;
   };
 
-  const persist = async (next, attempt = 0) => {
-    try {
-      saveAuth(dir, next);
-      lastPersistError = null;
-    } catch (error) {
-      lastPersistError = error?.message ?? "persist failed";
-      if (attempt < 3 && auth?.refreshToken === next.refreshToken) {
-        await new Promise((resolve) => setTimeout(resolve, 250 * 2 ** attempt));
-        await persist(next, attempt + 1);
+  const persist = async (next) => {
+    for (let attempt = 0; attempt < 4; attempt++) {
+      try {
+        saveAuth(dir, next);
+        lastPersistError = null;
+        return;
+      } catch (error) {
+        lastPersistError = error?.message ?? "persist failed";
+        await sleep(100 * 2 ** attempt);
       }
     }
   };
 
-  const performRefresh = async (expectedAccessToken) => {
-    if (!auth || auth.accessToken !== expectedAccessToken) return true;
-    // 1. Cross-process adoption: another process may have refreshed
-    // already — the on-disk access token would differ from ours. Adopt
-    // it and let the caller retry; no refresh call, no rotation race.
-    const onDiskBefore = dir ? loadAuth(dir) : null;
-    if (onDiskBefore && onDiskBefore.accessToken && onDiskBefore.accessToken !== expectedAccessToken) {
-      setAuth(onDiskBefore);
-      return true;
-    }
-    // 2. Serialize the actual refresh across processes: re-read under
-    // the lock (the winner may have finished while we waited for it).
-    const haveLock = dir
-      ? await acquireRefreshLock(dir, (ms) => new Promise((resolve) => setTimeout(resolve, ms)))
-      : false;
+  const ok = (auth) => ({ status: "ok", accessToken: auth.accessToken });
+
+  const recoverOnce = async (tokenUsed) => {
+    // 1. Someone (another process, or this one) already rotated: the disk
+    //    holds a different token — use it, no network, no race.
+    const latest = reload();
+    if (!latest) return { status: "dead", reason: "signed_out", detail: "no stored credentials" };
+    if (latest.accessToken !== tokenUsed) return ok(latest);
+    if (deadFor && deadFor.refreshToken === latest.refreshToken) return deadFor.outcome;
+
+    // 2. The disk token itself failed: refresh — under the cross-process
+    //    lock, re-reading once we hold it (the holder we waited for has
+    //    usually just written the rotated pair).
+    const handle = dir ? await acquireRefreshLock(dir, { sleep, ...lockOptions }) : null;
     try {
-      const underLock = dir ? loadAuth(dir) : null;
-      if (underLock && underLock.accessToken && underLock.accessToken !== expectedAccessToken) {
-        setAuth(underLock);
-        return true;
-      }
-      const attemptRefreshToken = underLock?.refreshToken ?? auth.refreshToken;
-      let next;
-      try {
-        next = await refreshTokens(origin, { refreshToken: attemptRefreshToken, fetchImpl: doFetch });
-      } catch (error) {
-        if (error instanceof RefreshRejectedError) {
-          // 3. Our refresh token was rejected — but the winner may have
-          // written its rotated pair after our attempt started. Adopt if
-          // the on-disk refresh token differs from the one we tried;
-          // otherwise the session is genuinely dead: caller surfaces a
-          // re-login hint (the stored pair stays for doctor).
-          const latest = dir ? loadAuth(dir) : null;
-          if (latest && latest.refreshToken && latest.refreshToken !== attemptRefreshToken) {
-            setAuth(latest);
-            return true;
+      let base = reload();
+      if (!base) return { status: "dead", reason: "signed_out", detail: "no stored credentials" };
+      if (base.accessToken !== tokenUsed) return ok(base);
+      for (let attempt = 0; attempt < 3; attempt++) {
+        let next;
+        try {
+          next = await refreshTokens(origin, { refreshToken: base.refreshToken, fetchImpl: doFetch });
+        } catch (error) {
+          if (!(error instanceof RefreshRejectedError)) {
+            return { status: "transient", error: error?.message ?? String(error) };
           }
-          return false;
+          // 3. Refused. If the pair on disk moved while we asked (a
+          //    process that did not wait for the lock, or an older CLI),
+          //    that pair is the live one.
+          const after = reload();
+          if (after && after.refreshToken !== base.refreshToken) return ok(after);
+          if (error.status === 409) {
+            // Lost a race inside the manager: ask again shortly.
+            await sleep(250 * (attempt + 1));
+            base = reload() ?? base;
+            continue;
+          }
+          const outcome = error.status === 403
+            ? { status: "dead", reason: "account", detail: error.detail }
+            : { status: "dead", reason: "session", detail: error.detail };
+          // The stored pair stays on disk (doctor reports it); the verdict
+          // is remembered for this refresh token only.
+          deadFor = { refreshToken: base.refreshToken, outcome };
+          return outcome;
         }
-        throw error;
+        memory = next;
+        if (dir) await persist(next);
+        deadFor = null;
+        return ok(next);
       }
-      setAuth(next);
-      await persist(next);
-      return true;
+      return { status: "transient", error: "refresh kept racing" };
+    } finally {
+      releaseRefreshLock(handle);
+    }
+  };
+
+  const recover = async (tokenUsed) => {
+    // One recovery at a time per process; a caller arriving meanwhile
+    // re-evaluates afterwards (usually: the disk now differs -> ok).
+    while (inflight) {
+      try {
+        await inflight;
+      } catch {
+        /* its own caller handles it */
+      }
+    }
+    inflight = recoverOnce(tokenUsed);
+    try {
+      return await inflight;
     } finally {
-      if (haveLock) releaseRefreshLock(dir);
+      inflight = null;
     }
   };
 
   return {
     get auth() {
-      return auth;
+      return reload();
     },
     get lastPersistError() {
       return lastPersistError;
     },
-    setAuth(next) {
-      setAuth(next);
+    accessToken() {
+      return reload()?.accessToken ?? "";
     },
-    reload() {
-      auth = dir ? loadAuth(dir) : null;
+    setAuth(next) {
+      memory = next;
     },
+    reload,
     now,
+    recover,
     async refresh(expectedAccessToken) {
-      if (!auth) return false;
-      if (auth.accessToken !== expectedAccessToken) return true;
-      inflight ??= performRefresh(expectedAccessToken).finally(() => {
-        inflight = null;
-      });
-      return inflight;
+      const outcome = await recover(expectedAccessToken);
+      return outcome.status === "ok";
     },
   };
 }
 
+/**
+ * Send a device-authenticated request with the CURRENT on-disk token and
+ * recover from 401s: `send(token)` performs the request. Up to
+ * `maxRecoveries` times a 401 asks the refresher for a better token and
+ * resends. Resolves {response, outcome}: `outcome` is null on success (or
+ * any non-401 answer), or the recover() verdict that ended the loop —
+ * {status:"dead", ...} means the device session itself is gone,
+ * {status:"transient", ...} that the manager could not be reached.
+ */
+export async function sendWithDeviceAuth(send, refresher, {
+  fallbackToken = "",
+  maxRecoveries = 3,
+  onResponse,
+} = {}) {
+  let token = refresher.accessToken() || fallbackToken;
+  let response = await send(token);
+  onResponse?.(response);
+  for (let round = 0; response?.status === 401 && round < maxRecoveries; round++) {
+    const outcome = await refresher.recover(token);
+    if (outcome.status !== "ok") return { response, outcome };
+    try {
+      await response.body?.cancel?.();
+    } catch {
+      /* already consumed */
+    }
+    token = outcome.accessToken;
+    response = await send(token);
+    onResponse?.(response);
+  }
+  if (response?.status === 401) {
+    // A token the manager issued moments ago is refused too.
+    return { response, outcome: { status: "dead", reason: "session", detail: "access token refused after refresh" } };
+  }
+  return { response, outcome: null };
+}
+
 /** Best-effort browser open. NEVER throws or crashes: the spawned child's
  * 'error' event is always handled (ENOENT on a headless Linux box would
  * otherwise take the CLI down — Foxtran's login crash). Linux tries a