@brainbase-labs/cli 0.47.0 → 0.48.0

package/README.md

@@ -336,7 +336,7 @@ Playbook files carry a small YAML frontmatter (`title`, `description`) — the C
 | `BRAINBASE_API_URL` | Legacy KLS host override. Control requests use `/api/cli`; it is also the fallback for model-proxy and registry traffic. |
 | `BRAINBASE_PROXY_URL` | Override the model-proxy host used when enabling harness tracking. |
 | `BRAINBASE_REGISTRY_URL` | Override the registry API host. |
-| `BRAINBASE_TOKEN` | Use a PAT instead of the stored login session. The only way a PAT authenticates a control-plane command — see [Auth](#auth). |
+| `BRAINBASE_TOKEN` | Use a PAT instead of the stored login session. Outranks both the session and the PAT saved in `token.json`. See [Auth](#auth). |
 | `BRAINBASE_HOME` | Where local state lives (default: `~/.brainbase`) |
 
 Model-proxy and registry traffic fall back through `BRAINBASE_API_URL`,
@@ -344,30 +344,26 @@ the server captured at login, and finally `https://api.v1.brainbaselabs.com`.
 
 ## Auth
 
-Three credentials, and which ones a command considers depends on the service
-it talks to:
+Every command tries three credentials, in this order:
 
-| Commands | Credentials tried, in order |
-|-|-|
-| `agent`, `orchestration`, `link`, `unlink`, `sync`, `status`, `team` | `BRAINBASE_TOKEN`, then the `auth.json` session |
-| `template`, `skill`, `token` | `BRAINBASE_TOKEN`, then the session, then `token.json` |
-| `task` commands | `BRAINBASE_TOKEN`, then the session, then `token.json` — the last only when no session is configured |
-| `benchmark` control-plane commands | `BRAINBASE_TOKEN`, then the session |
+1. `BRAINBASE_TOKEN`
+2. the `auth.json` login session, renewed first if it has expired
+3. the PAT that `brainbase token create` saved in `~/.brainbase/token.json`,
+   when there is no session or it could not be renewed. A PAT minted by a
+   different account than the session is never used in its place.
 
-`brainbase whoami` (or `--json`) reports which one is active.
+`brainbase whoami` (or `--json`) reports which one is active. It renews an
+expired session itself, so what it reports is what the next command will use.
 
-**For CI:** `brainbase token create` saves the PAT to `~/.brainbase/token.json`,
-and control-plane commands never read that file — `brainbase agent push` needs
-the token in `BRAINBASE_TOKEN`:
+**For CI:** a runner has no `token.json`, so hand it the PAT as a secret:
 
 ```bash
 export BRAINBASE_TOKEN=bbpat_…
 brainbase agent push
 ```
 
-Do not bake a `~/.brainbase` directory into a build image: a leftover
-`auth.json` outranks the stored PAT, and every control-plane command starts
-failing once its session expires.
+Do not bake a `~/.brainbase` directory into a build image. Ship
+`BRAINBASE_TOKEN` as a secret instead.
 
 An explicit PAT does not inherit routing from a stored login. Set
 `BRAINBASE_CONTROL_PLANE_URL` when using a PAT against a non-default MAS host.

package/dist/index.js

@@ -36091,7 +36091,7 @@ function padStart(s, n) {
 // package.json
 var package_default = {
   name: "@brainbase-labs/cli",
-  version: "0.47.0",
+  version: "0.48.0",
   description: "Pack, share, and install agent templates across harnesses (Claude Code, Codex, ...).",
   type: "module",
   bin: {
@@ -40994,7 +40994,8 @@ var AuthSessionSchema = exports_external.object({
   supabase_url: exports_external.string().optional(),
   supabase_anon_key: exports_external.string().optional(),
   web_url: exports_external.string().optional(),
-  authedAt: exports_external.string()
+  authedAt: exports_external.string(),
+  refresh_rejected: exports_external.object({ at: exports_external.string(), code: exports_external.string() }).optional()
 });
 function readAuth() {
   if (!exists(AUTH_FILE))
@@ -41141,6 +41142,47 @@ function authStatus() {
     return { ok: false, session: s, reason: "session expired" };
   return { ok: true, session: s };
 }
+function isSessionRefreshable(session) {
+  return Boolean(session.refresh_token && session.supabase_url && session.supabase_anon_key && !session.refresh_rejected);
+}
+var lastRefreshFailure = null;
+function refreshFailureFor(session) {
+  if (session.refresh_rejected) {
+    return { kind: "rejected", detail: session.refresh_rejected.code };
+  }
+  if (lastRefreshFailure && lastRefreshFailure.refreshToken === session.refresh_token) {
+    return lastRefreshFailure.failure;
+  }
+  return null;
+}
+function noteRefreshFailure(session, failure) {
+  lastRefreshFailure = { refreshToken: session.refresh_token ?? "", failure };
+}
+async function rejectionCode(res) {
+  if (![400, 401, 403].includes(res.status))
+    return null;
+  try {
+    const body = await res.json();
+    for (const key of ["error_code", "error"]) {
+      const value = body[key];
+      if (typeof value === "string" && value.trim())
+        return value.trim();
+    }
+  } catch {}
+  return null;
+}
+function markRefreshRejected(session, code) {
+  withAuthLock(() => {
+    const current = readAuth();
+    if (!current || !isSameAuthIdentity(current, session) || current.access_token !== session.access_token || current.refresh_token !== session.refresh_token) {
+      return;
+    }
+    writeAuthUnlocked({
+      ...current,
+      refresh_rejected: { at: new Date().toISOString(), code }
+    });
+  });
+}
 var refreshInFlight = null;
 function validatedRefreshResult(expectedSession, result) {
   const current = readAuth();
@@ -41162,10 +41204,11 @@ function adoptRefreshedLineage(session) {
   return isAuthValid(current) ? current : null;
 }
 async function refreshSession(session) {
-  if (!session.refresh_token)
+  if (!isSessionRefreshable(session))
     return null;
-  if (!session.supabase_url || !session.supabase_anon_key)
+  if (!session.refresh_token || !session.supabase_url || !session.supabase_anon_key) {
     return null;
+  }
   const releaseRefreshLock = acquireLock(REFRESH_LOCK_FILE, REFRESH_LOCK_TIMEOUT_MS);
   if (!releaseRefreshLock) {
     const adopted = adoptRefreshedLineage(session);
@@ -41173,12 +41216,24 @@ async function refreshSession(session) {
       return adopted;
     if (isAuthValid(session))
       return session;
+    noteRefreshFailure(session, {
+      kind: "unavailable",
+      detail: "timed out waiting for another command to renew it"
+    });
     throw new AuthRefreshLockTimeoutError;
   }
   try {
     const adopted = adoptRefreshedLineage(session);
     if (adopted !== undefined)
       return adopted;
+    const onDisk = readAuth();
+    if (onDisk?.refresh_rejected) {
+      noteRefreshFailure(session, {
+        kind: "rejected",
+        detail: onDisk.refresh_rejected.code
+      });
+      return null;
+    }
     const url = `${session.supabase_url.replace(/\/+$/, "")}/auth/v1/token?grant_type=refresh_token`;
     let res;
     try {
@@ -41192,19 +41247,43 @@ async function refreshSession(session) {
         },
         body: JSON.stringify({ refresh_token: session.refresh_token })
       });
-    } catch {
+    } catch (error) {
+      noteRefreshFailure(session, {
+        kind: "unavailable",
+        detail: `could not reach ${new URL(url).host}: ${error.message}`
+      });
       return null;
     }
-    if (!res.ok)
+    if (!res.ok) {
+      const code = await rejectionCode(res);
+      if (code) {
+        markRefreshRejected(session, code);
+        noteRefreshFailure(session, { kind: "rejected", detail: code });
+      } else {
+        noteRefreshFailure(session, {
+          kind: "unavailable",
+          detail: `the auth server answered HTTP ${res.status}`
+        });
+      }
       return null;
+    }
     let data;
     try {
       data = await res.json();
     } catch {
+      noteRefreshFailure(session, {
+        kind: "unavailable",
+        detail: "the auth server sent an unreadable response"
+      });
       return null;
     }
-    if (!data.access_token)
+    if (!data.access_token) {
+      noteRefreshFailure(session, {
+        kind: "unavailable",
+        detail: "the auth server sent no access token"
+      });
       return null;
+    }
     const now = Math.floor(Date.now() / 1000);
     const expires_at = data.expires_at ?? (data.expires_in ? now + data.expires_in : undefined);
     const updated = {
@@ -41224,6 +41303,7 @@ async function refreshSession(session) {
       if (adopted2 !== undefined)
         return adopted2;
       writeAuthUnlocked(updated);
+      lastRefreshFailure = null;
       return updated;
     });
   } finally {
@@ -41263,7 +41343,7 @@ async function refreshSessionAfterUnauthorized(rejectedSession) {
     return current;
   }
   const refreshed = await tryRefreshSession(rejectedSession);
-  if (refreshed) {
+  if (refreshed && refreshed.access_token !== rejectedSession.access_token) {
     if (!isSameAuthIdentity(refreshed, rejectedSession)) {
       throw new AuthSessionChangedError;
     }
@@ -41276,8 +41356,21 @@ async function refreshSessionAfterUnauthorized(rejectedSession) {
   if (latest.access_token !== rejectedSession.access_token && isAuthValid(latest)) {
     return latest;
   }
+  expireRejectedAccessToken(rejectedSession);
   return null;
 }
+function expireRejectedAccessToken(session) {
+  withAuthLock(() => {
+    const current = readAuth();
+    if (!current || !isSameAuthIdentity(current, session) || current.access_token !== session.access_token || !isAuthValid(current)) {
+      return;
+    }
+    writeAuthUnlocked({
+      ...current,
+      expires_at: Math.floor(Date.now() / 1000) - 1
+    });
+  });
+}
 async function ensureFreshSession() {
   const s = readAuth();
   if (!s)
@@ -54875,7 +54968,8 @@ var StoredTokenSchema = exports_external.object({
   token: exports_external.string(),
   prefix: exports_external.string(),
   name: exports_external.string().optional(),
-  createdAt: exports_external.string()
+  createdAt: exports_external.string(),
+  user_id: exports_external.string().optional()
 });
 function withTokenLock(operation) {
   const release = acquireLock(TOKEN_LOCK_FILE, TOKEN_LOCK_TIMEOUT_MS);
@@ -54897,7 +54991,7 @@ function readToken() {
     return null;
   }
 }
-function writeToken(token, name) {
+function writeToken(token, name, userId) {
   if (!isValidTokenFormat(token)) {
     throw new Error("refusing to store token: invalid format");
   }
@@ -54906,7 +55000,8 @@ function writeToken(token, name) {
     token,
     prefix: tokenPrefix(token),
     name,
-    createdAt: new Date().toISOString()
+    createdAt: new Date().toISOString(),
+    ...userId ? { user_id: userId } : {}
   };
   withTokenLock(() => writeJsonAtomic(TOKEN_FILE, stored));
   return stored;
@@ -54940,8 +55035,6 @@ function clearTokenIfMatches(prefix) {
 }
 
 // src/core/credentials.ts
-var REGISTRY_COMMANDS = "template, skill, token";
-var CONTROL_PLANE_COMMANDS = "agent, orchestration, link, unlink, sync, status, team";
 var NOT_A_PAT = "(not a bbpat_… token)";
 function maskPat(token) {
   if (!isValidTokenFormat(token))
@@ -54954,58 +55047,89 @@ function readEnvPat() {
     return null;
   return { prefix: maskPat(value), malformed: !isValidTokenFormat(value) };
 }
-function storedPatIgnoredHint(client) {
-  const setEnv = `Set BRAINBASE_TOKEN to that token's value to authenticate with it here, ` + "or run `brainbase login` to refresh the session";
-  switch (client) {
-    case "control-plane":
-      return `The PAT saved in ${TOKEN_FILE} is never used by control-plane ` + `commands (${CONTROL_PLANE_COMMANDS}). ${setEnv}.`;
-    case "managed-task":
-      return `The PAT saved in ${TOKEN_FILE} is not used while a login session is ` + `configured. ${setEnv} — or \`brainbase logout\`, which leaves the ` + "PAT as the only credential.";
-    default: {
-      const exhaustive = client;
-      throw new Error(`unhandled credential client: ${String(exhaustive)}`);
-    }
+function storedPatFor(session) {
+  const stored = readToken();
+  if (!stored)
+    return null;
+  if (session && stored.user_id && stored.user_id !== session.user_id) {
+    return null;
   }
+  return stored;
 }
-function withStoredPatHint(reason, client) {
-  if (!readToken())
-    return reason;
-  const trimmed = reason.trimEnd();
-  const separator = /[.!?:]$/.test(trimmed) ? " " : ". ";
-  return `${trimmed}${separator}${storedPatIgnoredHint(client)}`;
+var announcedFallback = false;
+function announceStoredPatFallback(session, stored) {
+  if (!session || announcedFallback)
+    return;
+  announcedFallback = true;
+  console.error(`Login session ${sessionProblem(session)}; using the PAT saved in ${TOKEN_FILE} ` + `(${stored.prefix}…). Run \`brainbase login\` to switch back.`);
+}
+function sessionProblem(session) {
+  const failure = refreshFailureFor(session);
+  if (failure?.kind === "rejected") {
+    return `expired and could not be renewed (the auth server rejected its refresh token: ${failure.detail})`;
+  }
+  if (failure?.kind === "unavailable") {
+    return `expired and could not be renewed (${failure.detail})`;
+  }
+  if (!isSessionRefreshable(session)) {
+    return "expired and cannot be renewed (no refresh token was saved with it)";
+  }
+  return "expired";
+}
+function noUsableCredentialMessage() {
+  const session = readAuth();
+  if (!session) {
+    return "Not logged in. Run `brainbase login` to connect this device.";
+  }
+  const failure = refreshFailureFor(session);
+  const retry = failure?.kind === "unavailable" ? " Check your connection and retry, or run `brainbase login`." : " Run `brainbase login` to sign in again.";
+  const stored = readToken();
+  const mismatch = stored && !storedPatFor(session) ? ` The PAT saved in ${TOKEN_FILE} belongs to a different account, so it was not used.` : "";
+  return `Your login session ${sessionProblem(session)}.${retry}${mismatch}`;
 }
-function withRejectedSessionHint(message, source, client) {
+function withRejectedSessionHint(message, source) {
   if (source !== "session")
     return message;
-  return withStoredPatHint(message, client);
-}
-function isRefreshable(session) {
-  return Boolean(session.refresh_token && session.supabase_url && session.supabase_anon_key);
+  const trimmed = message.trimEnd();
+  const separator = /[.!?:]$/.test(trimmed) ? " " : ". ";
+  const session = readAuth();
+  const renewable = session ? isSessionRefreshable(session) : false;
+  if (session && !renewable && storedPatFor(session)) {
+    return `${trimmed}${separator}The login session could not be renewed; ` + `retry to use the PAT saved in ${TOKEN_FILE}, or run \`brainbase login\`.`;
+  }
+  return `${trimmed}${separator}The login session could not be renewed. Run \`brainbase login\` to sign in again.`;
 }
 function describeCredentials() {
   const env3 = readEnvPat();
   const status = authStatus();
-  const stored = readToken();
-  const refreshable = Boolean(status.session && !status.ok && isRefreshable(status.session));
+  const storedToken = readToken();
+  const storedUsable = storedToken ? storedPatFor(status.session) : null;
+  const refreshable = Boolean(status.session && !status.ok && isSessionRefreshable(status.session));
+  const failure = status.session ? refreshFailureFor(status.session) : null;
   const session = status.session ? {
     email: status.session.email ?? null,
     userId: status.session.user_id,
     expiresAt: status.session.expires_at ?? null,
     expired: !status.ok,
-    refreshable
+    refreshable,
+    refreshError: failure ? failure.kind === "rejected" ? `rejected: ${failure.detail}` : failure.detail : null
   } : null;
   let active = null;
   if (env3)
     active = "env_pat";
-  else if (status.ok || refreshable)
+  else if (status.ok || refreshable && !failure)
     active = "session";
-  else if (stored)
+  else if (storedUsable)
     active = "stored_pat";
   return {
     active,
     envPat: env3,
     session,
-    storedPat: stored ? { name: stored.name ?? null, prefix: stored.prefix } : null
+    storedPat: storedToken ? {
+      name: storedToken.name ?? null,
+      prefix: storedToken.prefix,
+      usable: Boolean(storedUsable)
+    } : null
   };
 }
 
@@ -55092,7 +55216,7 @@ function legacyScheduleError() {
 function legacyAgentConfigError() {
   return new ApiError("Declarative machine/model config requires the MAS control plane. Set BRAINBASE_CONTROL_PLANE_URL or unset the legacy BRAINBASE_API_URL override.", 400);
 }
-async function resolveCredential(storedPatHint = "control-plane") {
+async function resolveCredential() {
   const envToken = process.env.BRAINBASE_TOKEN;
   if (envToken && envToken.trim()) {
     return {
@@ -55101,43 +55225,39 @@ async function resolveCredential(storedPatHint = "control-plane") {
       source: "env_pat"
     };
   }
-  const session = await ensureFreshSession();
-  if (session) {
-    return {
-      bearer: session.access_token,
-      session,
-      source: "session"
-    };
-  }
-  const status = authStatus();
-  const reason = status.reason ?? "not logged in";
-  throw new ApiError(status.ok ? "CLI authentication changed while this command was starting; retry it" : storedPatHint ? withStoredPatHint(reason, storedPatHint) : reason, 401);
-}
-async function resolveMasCredential() {
-  const configuredSession = readAuth();
+  const configured = readAuth();
+  let session;
   try {
-    return await resolveCredential(null);
+    session = await ensureFreshSession();
   } catch (error) {
-    if (!(error instanceof ApiError && error.status === 401)) {
+    if (!(error instanceof AuthRefreshLockTimeoutError))
       throw error;
-    }
-    if (configuredSession || readAuth()) {
-      if (readToken()) {
-        throw new ApiError(`${error.message}. ${storedPatIgnoredHint("managed-task")}`, 401);
-      }
+    const current2 = readAuth();
+    const stored2 = storedPatFor(current2);
+    if (!stored2 || (configured?.user_id ?? null) !== (current2?.user_id ?? null)) {
       throw error;
     }
+    announceStoredPatFallback(current2, stored2);
+    return { bearer: stored2.token, session: null, source: "stored_pat" };
   }
-  const storedToken = readToken();
-  if (storedToken) {
+  if (session) {
     return {
-      bearer: storedToken.token,
-      session: null,
-      source: "stored_pat"
+      bearer: session.access_token,
+      session,
+      source: "session"
     };
   }
   const status = authStatus();
-  throw new ApiError(status.ok ? "CLI authentication changed while this command was starting; retry it" : status.reason ?? "not logged in", 401);
+  const current = readAuth();
+  if (status.ok || (configured?.user_id ?? null) !== (current?.user_id ?? null)) {
+    throw new ApiError("CLI authentication changed while this command was starting; retry it", 401);
+  }
+  const stored = storedPatFor(current);
+  if (stored) {
+    announceStoredPatFallback(current, stored);
+    return { bearer: stored.token, session: null, source: "stored_pat" };
+  }
+  throw new ApiError(noUsableCredentialMessage(), 401);
 }
 function networkErrorCode(error) {
   if (!error || typeof error !== "object")
@@ -55225,7 +55345,7 @@ async function request(pathname, init = {}) {
   } catch {}
   if (!res.ok) {
     const message = apiErrorMessage(body, res.status);
-    throw new ApiError(res.status === 401 ? withRejectedSessionHint(message, credential.source, "control-plane") : message, res.status, body);
+    throw new ApiError(res.status === 401 ? withRejectedSessionHint(message, credential.source) : message, res.status, body);
   }
   return body;
 }
@@ -55278,7 +55398,7 @@ function parseMasTaskCreateResponse(body) {
   };
 }
 async function masRequest(pathname, init) {
-  const credential = await resolveMasCredential();
+  const credential = await resolveCredential();
   let currentSession = credential.session;
   let ambiguousNetworkRetriesRemaining = 1;
   let requestMayHaveSucceeded = false;
@@ -55369,7 +55489,7 @@ async function masRequest(pathname, init) {
     }
     if (!res.ok) {
       const message = masApiErrorMessage(body, res.status);
-      throw new ApiError(res.status >= 500 ? `${message} Task creation may still be processing; check your tasks before running this command again.` : res.status === 401 ? withRejectedSessionHint(message, credential.source, "managed-task") : message, res.status, body);
+      throw new ApiError(res.status >= 500 ? `${message} Task creation may still be processing; check your tasks before running this command again.` : res.status === 401 ? withRejectedSessionHint(message, credential.source) : message, res.status, body);
     }
     return body;
   }
@@ -55383,7 +55503,7 @@ function masNamedRecord(body, what, nameField) {
   return { id: record.id, name };
 }
 async function masReadRequest(pathname, callerSignal) {
-  const credential = await resolveMasCredential();
+  const credential = await resolveCredential();
   let currentSession = credential.session;
   let refreshSessionAvailable = credential.source === "session";
   let res;
@@ -55421,7 +55541,7 @@ async function masReadRequest(pathname, callerSignal) {
   } catch {}
   if (!res.ok) {
     const message = masApiErrorMessage(body, res.status);
-    throw new ApiError(res.status === 401 ? withRejectedSessionHint(message, credential.source, "managed-task") : res.status === 404 && isUnroutedPath(body) ? `This control plane does not serve ${pathname} yet. Update the server, or use the web app.` : message, res.status, body);
+    throw new ApiError(res.status === 401 ? withRejectedSessionHint(message, credential.source) : res.status === 404 && isUnroutedPath(body) ? `This control plane does not serve ${pathname} yet. Update the server, or use the web app.` : message, res.status, body);
   }
   return body;
 }
@@ -55440,7 +55560,7 @@ function withRequestDeadline(callerSignal, timeoutMs) {
   return combined.signal;
 }
 async function masResourceRequest(pathname, init = {}, onHeaders) {
-  const credential = await resolveMasCredential();
+  const credential = await resolveCredential();
   let currentSession = credential.session;
   const res = await sendWithAuthRetry(credential.source === "session" ? currentSession : null, async (refreshed) => {
     if (refreshed)
@@ -55462,7 +55582,7 @@ async function masResourceRequest(pathname, init = {}, onHeaders) {
   } catch {}
   if (!res.ok) {
     const message = masApiErrorMessage(body, res.status);
-    const failure = new ApiError(res.status === 401 ? withRejectedSessionHint(message, credential.source, "managed-task") : res.status === 404 && isUnroutedPath(body) ? `This control plane does not serve ${pathname} yet. Update the server, or use the web app.` : message, res.status, body);
+    const failure = new ApiError(res.status === 401 ? withRejectedSessionHint(message, credential.source) : res.status === 404 && isUnroutedPath(body) ? `This control plane does not serve ${pathname} yet. Update the server, or use the web app.` : message, res.status, body);
     const retryAfter = res.headers.get("Retry-After");
     if (retryAfter)
       failure.retryAfter = retryAfter;
@@ -55475,12 +55595,12 @@ async function masResourceRequest(pathname, init = {}, onHeaders) {
 class StreamHostMovedError extends ApiError {
 }
 async function masStreamTarget(pathname) {
-  const credential = await resolveMasCredential();
+  const credential = await resolveCredential();
   const base2 = masApiBase(credential.session);
   return {
     url: `${base2}${pathname}`,
     resolveBearer: async () => {
-      const fresh = await resolveMasCredential();
+      const fresh = await resolveCredential();
       const freshBase = masApiBase(fresh.session);
       if (freshBase !== base2) {
         throw new StreamHostMovedError(`The control plane moved from ${base2} to ${freshBase} while this stream was open, so the current credential was not sent. Re-run the command to follow against the new host.`);
@@ -55934,18 +56054,26 @@ async function resolveAuth() {
   } catch (error) {
     if (!(error instanceof AuthRefreshLockTimeoutError))
       throw error;
-    const pat2 = readToken();
-    if (pat2)
+    const session = readAuth();
+    const pat2 = storedPatFor(session);
+    if (pat2) {
+      announceStoredPatFallback(session, pat2);
       return patAuth(pat2.token);
+    }
     throw error;
   }
   if (freshSession)
     return jwtAuth(freshSession);
   const status = authStatus();
-  const pat = readToken();
-  if (pat)
+  if (status.ok) {
+    throw new ApiError("CLI authentication changed while this command was starting; retry it", 401);
+  }
+  const pat = storedPatFor(status.session);
+  if (pat) {
+    announceStoredPatFallback(status.session, pat);
     return patAuth(pat.token);
-  throw new ApiError(status.ok ? "CLI authentication changed while this command was starting; retry it" : status.reason ?? "not logged in", 401);
+  }
+  throw new ApiError(noUsableCredentialMessage(), 401);
 }
 function mergeHeaders(auth, overrides) {
   const headers = new Headers(auth);
@@ -63396,13 +63524,62 @@ async function runLogout() {
 }
 
 // src/cli/whoami.ts
-function usableForControlPlane(report) {
+var PAT_LOOKUP_TIMEOUT_MS = 5000;
+async function settleSession() {
+  if (process.env.BRAINBASE_TOKEN?.trim())
+    return;
+  if (!readAuth())
+    return;
+  try {
+    await ensureFreshSession();
+  } catch {}
+}
+function activePat(report) {
+  if (report.active === "env_pat") {
+    return report.envPat?.malformed ? null : process.env.BRAINBASE_TOKEN?.trim() ?? null;
+  }
+  if (report.active === "stored_pat")
+    return readToken()?.token ?? null;
+  return null;
+}
+async function lookupPat(token) {
+  let res;
+  try {
+    res = await fetch(`${baseUrl(null)}/v1/registry/me`, {
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "X-Auth-Source": "pat",
+        Accept: "application/json"
+      },
+      signal: AbortSignal.timeout(PAT_LOOKUP_TIMEOUT_MS)
+    });
+  } catch {
+    return { kind: "unknown" };
+  }
+  let body = null;
+  try {
+    body = await res.json();
+  } catch {}
+  const detail = body && typeof body === "object" && typeof body.detail === "string" ? body.detail : null;
+  if (res.status === 401 && detail)
+    return { kind: "rejected", message: detail };
+  if (!res.ok || !body || typeof body !== "object")
+    return { kind: "unknown" };
+  const obj = body;
+  return {
+    kind: "ok",
+    userId: typeof obj.id === "string" ? obj.id : null,
+    email: typeof obj.email === "string" ? obj.email : null
+  };
+}
+function usableForControlPlane(report, pat) {
   switch (report.active) {
     case "env_pat":
-      return !report.envPat?.malformed;
+      return !report.envPat?.malformed && pat.kind !== "rejected";
+    case "stored_pat":
+      return pat.kind !== "rejected";
     case "session":
       return true;
-    case "stored_pat":
     case null:
       return false;
     default: {
@@ -63411,41 +63588,44 @@ function usableForControlPlane(report) {
     }
   }
 }
-function exitCodeFor(report) {
-  return usableForControlPlane(report) ? 0 : 1;
-}
-function reasonFor(report) {
+function reasonFor(report, pat) {
+  if (pat.kind === "rejected") {
+    const which = report.active === "env_pat" ? "the PAT in BRAINBASE_TOKEN" : "the PAT saved in token.json";
+    return `The server rejected ${which} (${pat.message}). ` + "Mint a new one with `brainbase token create`, or run `brainbase login`.";
+  }
   switch (report.active) {
     case "env_pat":
       return report.envPat?.malformed ? "BRAINBASE_TOKEN is set to something that is not a `bbpat_…` token, " + "and it outranks every other credential — so every request will fail " + "until it is corrected or unset. Mint one with `brainbase token create`." : null;
     case "session":
       return null;
     case "stored_pat":
-      return `The stored PAT authenticates registry commands (${REGISTRY_COMMANDS}) only. ` + `Set BRAINBASE_TOKEN to its value for ${CONTROL_PLANE_COMMANDS}, ` + "or run `brainbase login`.";
+      return report.session ? noUsableCredentialMessage() : null;
     case null:
-      return report.session?.expired ? "Session expired. Run `brainbase login` to connect this device." : "Not logged in. Run `brainbase login` to connect this device.";
+      return noUsableCredentialMessage();
     default: {
       const exhaustive = report.active;
       throw new Error(`unhandled credential: ${String(exhaustive)}`);
     }
   }
 }
-function toJson(report, reason) {
+function toJson(report, pat, reason) {
   const usingSession = report.active === "session";
+  const patIdentity = pat.kind === "ok" ? pat : null;
   return {
     credential: report.active,
-    authenticated: report.active !== null && !report.envPat?.malformed,
-    control_plane: usableForControlPlane(report),
-    email: usingSession ? report.session?.email ?? null : null,
-    user_id: usingSession ? report.session?.userId ?? null : null,
+    authenticated: report.active !== null && !report.envPat?.malformed && pat.kind !== "rejected",
+    control_plane: usableForControlPlane(report, pat),
+    email: usingSession ? report.session?.email ?? null : patIdentity?.email ?? null,
+    user_id: usingSession ? report.session?.userId ?? null : patIdentity?.userId ?? null,
     expires_at: usingSession ? report.session?.expiresAt ?? null : null,
     token_prefix: report.active === "env_pat" ? report.envPat?.prefix ?? null : report.active === "stored_pat" ? report.storedPat?.prefix ?? null : null,
     control_plane_url: controlPlaneBaseUrl(usingSession ? readAuth() : null),
     session: report.session ? {
       present: true,
       expired: report.session.expired,
-      refreshable: report.session.refreshable
-    } : { present: false, expired: false, refreshable: false },
+      refreshable: report.session.refreshable,
+      refresh_error: report.session.refreshError
+    } : { present: false, expired: false, refreshable: false, refresh_error: null },
     stored_pat: report.storedPat ? { present: true, name: report.storedPat.name } : { present: false, name: null },
     reason
   };
@@ -63463,13 +63643,10 @@ function cardRows(report) {
       }
       break;
     case "session":
-      rows.push([
-        "credential",
-        report.session?.refreshable ? "login session (auth.json) — expired, renews on next use" : "login session (auth.json)"
-      ]);
+      rows.push(["credential", "login session (auth.json)"]);
       break;
     case "stored_pat":
-      rows.push(["credential", "stored PAT (token.json)"]);
+      rows.push(["credential", "saved PAT (token.json)"]);
       rows.push([
         "token",
         report.storedPat?.name ? `${displayPrefix(report.storedPat.prefix)} (${report.storedPat.name})` : displayPrefix(report.storedPat?.prefix ?? "?")
@@ -63483,26 +63660,30 @@ function cardRows(report) {
     }
   }
   if (report.session && report.active !== "session") {
+    const state = !report.session.expired ? "not used, env PAT wins" : report.session.refreshError ? `expired, renewal failed: ${report.session.refreshError}` : "expired";
     rows.push([
       "session",
-      `${report.session.email ?? report.session.userId} (${report.session.expired ? "expired" : "not used — env PAT wins"})`
+      `${report.session.email ?? report.session.userId} (${state})`
     ]);
   }
   return rows;
 }
 async function runWhoami(args = {}) {
+  await settleSession();
   const report = describeCredentials();
-  const reason = reasonFor(report);
-  process.exitCode = exitCodeFor(report);
+  const token = activePat(report);
+  const pat = token ? await lookupPat(token) : { kind: "unknown" };
+  const reason = reasonFor(report, pat);
+  process.exitCode = usableForControlPlane(report, pat) ? 0 : 1;
   if (args.json) {
-    console.log(JSON.stringify(toJson(report, reason), null, 2));
+    console.log(JSON.stringify(toJson(report, pat, reason), null, 2));
     return;
   }
   const signedIn = report.active !== null;
   await showIdentityCard({
     title: signedIn ? "WHOAMI" : "NOT SIGNED IN",
     tone: process.exitCode === 0 ? "ok" : "warn",
-    email: report.active === "session" ? report.session?.email ?? report.session?.userId ?? null : null,
+    email: report.active === "session" ? report.session?.email ?? report.session?.userId ?? null : pat.kind === "ok" ? pat.email ?? pat.userId : null,
     controlPlaneUrl: signedIn ? controlPlaneBaseUrl(report.active === "session" ? readAuth() : null) : null,
     expiresAt: report.active === "session" ? report.session?.expiresAt : null,
     rows: cardRows(report),
@@ -75158,22 +75339,13 @@ function TokenCreatedCard(props) {
             children: [
               "saved to ",
               props.storedAt,
-              " (mode 0600) — covers ",
-              REGISTRY_COMMANDS
+              " (mode 0600), used whenever no login session is usable"
             ]
           }, undefined, true, undefined, this),
           /* @__PURE__ */ jsx_dev_runtime17.jsxDEV(Text, {
             dimColor: true,
-            children: [
-              CONTROL_PLANE_COMMANDS,
-              " do ",
-              /* @__PURE__ */ jsx_dev_runtime17.jsxDEV(Text, {
-                bold: true,
-                children: "not"
-              }, undefined, false, undefined, this),
-              " read that file — export it instead:"
-            ]
-          }, undefined, true, undefined, this)
+            children: "for CI or another machine, export it instead:"
+          }, undefined, false, undefined, this)
         ]
       }, undefined, true, undefined, this)
     ]
@@ -75363,7 +75535,7 @@ function sessionWouldBeUsed() {
   const { ok, session } = authStatus();
   if (ok)
     return true;
-  return Boolean(session?.refresh_token && session.supabase_url && session.supabase_anon_key);
+  return Boolean(session && isSessionRefreshable(session));
 }
 function withLoginHint(error) {
   if (!(error instanceof ApiError) || error.status !== 403)
@@ -75397,6 +75569,7 @@ async function runTokenCreate(args) {
   } else {
     scopes = args.scopes;
   }
+  const minter = readAuth()?.user_id;
   const spinner2 = de();
   spinner2.start("Creating token…");
   let created;
@@ -75411,7 +75584,10 @@ async function runTokenCreate(args) {
   }
   spinner2.stop("Token created.");
   try {
-    writeToken(created.token, name);
+    if (readAuth()?.user_id !== minter) {
+      throw new Error("the login changed while it was being created");
+    }
+    writeToken(created.token, name, minter);
   } catch (error) {
     throw new Error(`Created token ${created.id}, but could not save it locally: ${error.message}
 ` + `This is the only time it is shown — copy it now:
@@ -96053,11 +96229,6 @@ var COMMANDS3 = [
   "help",
   "version"
 ];
-var STORED_PAT_COMMANDS = new Set([
-  "template",
-  "skill",
-  "token"
-]);
 var SUBCOMMAND_OWNED_FLAGS = {
   token: ["--scope", "--name"]
 };
@@ -96244,7 +96415,7 @@ function help() {
   out.push(`  ${import_picocolors80.default.dim("BRAINBASE_API_URL")}      legacy KLS host override (uses /api/cli; proxy/registry fallback)`);
   out.push(`  ${import_picocolors80.default.dim("BRAINBASE_PROXY_URL")}    override the model-proxy URL used by harness traffic (default https://api.v1.brainbaselabs.com)`);
   out.push(`  ${import_picocolors80.default.dim("BRAINBASE_REGISTRY_URL")} override the registry API URL (default https://api.v1.brainbaselabs.com)`);
-  out.push(`  ${import_picocolors80.default.dim("BRAINBASE_TOKEN")}        long-lived CLI PAT; the only PAT control-plane commands accept (token.json is not read there)`);
+  out.push(`  ${import_picocolors80.default.dim("BRAINBASE_TOKEN")}        long-lived CLI PAT; outranks the login session and the PAT saved in token.json`);
   out.push(`  ${import_picocolors80.default.dim("BRAINBASE_SKIP_AUTH")}    bypass the auth gate for development`);
   out.push(`  ${import_picocolors80.default.dim("BRAINBASE_NON_INTERACTIVE")} force non-interactive mode — skip/auto-default prompts (CI & agents)`);
   out.push(`  ${import_picocolors80.default.dim("BRAINBASE_RUN_ENTRYPOINT")} =1 → agent pull executes the agent entrypoint (sandbox boots; or pass --run-entrypoint)`);
@@ -96397,12 +96568,12 @@ async function requireAuth(cmd) {
   if (envToken && envToken.trim())
     return;
   let status = authStatus();
-  if (!status.ok && status.session?.refresh_token) {
+  if (!status.ok && status.session) {
     let refreshed;
     try {
       refreshed = await tryRefreshSession(status.session);
     } catch (error2) {
-      if (error2 instanceof AuthRefreshLockTimeoutError && STORED_PAT_COMMANDS.has(cmd) && readToken()) {
+      if (error2 instanceof AuthRefreshLockTimeoutError && storedPatFor(status.session)) {
         return;
       }
       throw error2;
@@ -96413,16 +96584,13 @@ async function requireAuth(cmd) {
   }
   if (status.ok)
     return;
-  if (STORED_PAT_COMMANDS.has(cmd) && readToken())
+  if (storedPatFor(status.session))
     return;
   console.error("");
   console.error(`  ${brandTint("◆")}  ${import_picocolors80.default.bold("brainbase")}`);
   console.error("");
   console.error(`  ${import_picocolors80.default.red("✗")}  You need to sign in to use ${import_picocolors80.default.bold("brainbase " + cmd)}.`);
-  if (status.reason)
-    console.error(`     ${import_picocolors80.default.dim(status.reason)}`);
-  console.error("");
-  console.error(`     Run ${import_picocolors80.default.cyan("brainbase login")} to connect this device.`);
+  console.error(`     ${import_picocolors80.default.dim(noUsableCredentialMessage())}`);
   console.error("");
   process14.exit(1);
 }
@@ -96706,7 +96874,7 @@ ${didYouMean(cmd, COMMANDS3, "brainbase")}`);
   } catch (err) {
     console.error(import_picocolors80.default.red(`
 ${err.message}`));
-    if (err instanceof ApiError && err.status === 401) {
+    if (err instanceof ApiError && err.status === 401 && !err.message.includes("brainbase login")) {
       console.error(`  Run ${import_picocolors80.default.cyan("brainbase login")} to connect this device.`);
     }
     if (process14.env.BRAINBASE_DEBUG)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brainbase-labs/cli",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "description": "Pack, share, and install agent templates across harnesses (Claude Code, Codex, ...).",
   "type": "module",
   "bin": {