viewable-one 0.0.0-stage → 0.12.1

package/lib/auth.mjs

@@ -0,0 +1,1387 @@
+// `glytch login` / `glytch logout`, and the one function everything else in
+// this bridge calls to reach the hosted board (brief 30, W2a, 2026-09-11).
+//
+// THE RULING THIS FILE IS FOR: the local stdio MCP server is retired.
+// Every agent - a session in the linked folder, a
+// script, a child the runner spawns - reaches the board through the HOSTED
+// endpoint from here on (https://app.viewable.one/mcp by default,
+// supabase/functions/board-mcp). Two credential shapes answer that endpoint,
+// per its own auth.mjs: a `pmb_` personal access token, minted by hand in
+// Settings, and a `pmo_` OAuth access token, issued by supabase/functions/
+// board-oauth. This file drives the SAME OAuth flow the endpoint already
+// serves to claude.ai - discovery, dynamic client registration, PKCE, a
+// loopback redirect - so a person on a laptop gets the same one-paste-one-
+// button connect a phone does, without typing a token anywhere.
+//
+// WHAT IS STORED, and why it is more than the three fields that make the
+// token useful. `~/.glytch/auth.json` (or GLYTCH_HOME) carries
+// `{accessToken, refreshToken, accessExpiresAt, appUrl, mcpUrl, clientId,
+// tokenEndpoint}`. `clientId` and `tokenEndpoint` are not optional extras:
+// `refreshTokens` (board-oauth/oauth.mjs) needs the client's own id on every
+// refresh_token grant, and re-discovering the authorization server on every
+// refresh - which happens roughly hourly - would be a network round trip this
+// file can avoid by writing down what login already learned. Mode 0600,
+// because it is a bearer credential and the file has no second reader.
+//
+// THE SCRIPT DOOR. `VIEWABLE_BOARD_TOKEN` (a `pmb_` personal access token from
+// Settings) bypasses this file and its expiry entirely - a script that sets
+// it once needs no browser, no refresh, and no `glytch login`. hostedToken()
+// checks it FIRST, so a script always gets exactly the token it set.
+//
+// THE SAME `pmb_` TOKEN, PERSISTED (brief 43, 2026-09-19). `glytch init
+// --yes` and `glytch login`, given VIEWABLE_BOARD_TOKEN, write it into this SAME
+// file as `{accessToken, personal: true, appUrl, mcpUrl}` instead of leaving
+// it live only in the process that had the variable set - a daemon started
+// after that shell exits inherits none of its environment, and would
+// otherwise come up with nothing to reach the board with. `personal: true` is
+// what tells hostedToken(), hostedStatus() and `glytch doctor` this record is
+// never refreshed and never expires, ahead of the OAuth fields the rest of
+// this file writes; the env var still wins outright when it is actually set,
+// and the stored personal token is what a later process - unsigned in its own
+// environment - falls back to before ever trying the OAuth refresh path.
+//
+// The runner requests the explicit `board runner` grant. Its registered name is
+// display-only; the consented scope selects its longer access-token lifetime.
+
+import { randomBytes, createHash } from "node:crypto";
+import { readFile, unlink, mkdir, rm, stat } from "node:fs/promises";
+import { createServer } from "node:http";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+
+import { glytchHome } from "./registry.mjs";
+import { writeFileAtomic } from "./atomic.mjs";
+import { movedAuth } from "./retired-address.mjs";
+
+/** The app origin every discovery document, redirect and MCP URL is relative
+ *  to. `GLYTCH_APP_URL` overrides it (a staging deploy, a local dev server);
+ *  production is the default so a bare `viewable login` works with nothing set. */
+export const DEFAULT_APP_URL = "https://app.viewable.one";
+
+/** The runner's display name (never an authorization credential). Kept
+ *  here as the one place it is spelled, and cross-referenced (not imported -
+ *  a Supabase Edge Function deploys as the files in its own directory and
+ *  nothing may reach out of it) from board-oauth/oauth.mjs. */
+export const RUNNER_CLIENT_NAME = "glytch-runner";
+
+/** Ask explicitly for board access and control of connected computers. */
+const SCOPE = "board runner";
+
+/** Refresh if the access token is within this long of expiring. A minute is
+ *  enough slack for the round trip a refresh itself takes; refreshing on
+ *  every call would cost a network round trip nothing needed. */
+const REFRESH_SKEW_MS = 60_000;
+
+/** How long a person has to finish the browser flow before `login()` gives up
+ *  and closes the loopback server. Five minutes: long enough to find the
+ *  window and sign in, short enough that a session left in a terminal does
+ *  not hold a listening socket open forever.
+ *
+ * IT BOUNDS THE PERSON, NOT THE MACHINE (2026-09-12 review, F2). It used to
+ * run until the exchange resolved, so a login whose callback arrived at 4:59
+ * was still on this clock while the token endpoint answered: the timer fired
+ * mid-exchange, `login()` rejected with "Timed out", and the exchange went on
+ * to write auth.json anyway - a CLI saying it failed on a machine that is
+ * signed in. It is cleared the moment a callback is claimed; what happens
+ * after that is the machine's part, bounded by EXCHANGE_TIMEOUT_MS. */
+const LOGIN_TIMEOUT_MS = 5 * 60_000;
+
+/** How long the token exchange itself may take once the person is back from
+ *  the browser. One minute, because nothing here waits on a human any more -
+ *  it is one HTTPS round trip - and an exchange that hangs would otherwise
+ *  hold the loopback socket open with no clock on it at all. */
+const EXCHANGE_TIMEOUT_MS = 60_000;
+
+const authFilePath = (env = process.env) => join(glytchHome(env), "auth.json");
+
+const trimTrailingSlash = (s) => String(s).replace(/\/+$/, "");
+
+/** The app origin this run should use: the explicit argument, then
+ *  `GLYTCH_APP_URL`, then the production default. */
+export function appUrlFrom(explicit, env = process.env) {
+  const asked = typeof explicit === "string" && explicit.trim() !== "" ? explicit.trim() : undefined;
+  const fromEnv = typeof (env.VIEWABLE_APP_URL ?? env.GLYTCH_APP_URL) === "string" && (env.VIEWABLE_APP_URL ?? env.GLYTCH_APP_URL).trim() !== ""
+    ? (env.VIEWABLE_APP_URL ?? env.GLYTCH_APP_URL).trim()
+    : undefined;
+  return trimTrailingSlash(asked ?? fromEnv ?? DEFAULT_APP_URL);
+}
+
+// --------------------------------------------------------------- the file
+
+/** The stored credential, or null when there is none (never signed in,
+ *  `logout` ran, or the file is unreadable JSON - treated the same as absent
+ *  rather than a crash, because a corrupt file is not this session's to fix). */
+export async function readAuthFile(env = process.env) {
+  try {
+    const raw = await readFile(authFilePath(env), "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" && typeof parsed.accessToken === "string" ? movedAuth(parsed, DEFAULT_APP_URL) : null;
+  } catch {
+    return null;
+  }
+}
+
+async function writeAuthFile(data, env = process.env) {
+  const home = glytchHome(env);
+  await mkdir(home, { recursive: true });
+  // mode 0600 at creation; writeFileAtomic renames the temp file (created with
+  // this mode) into place, so the final file carries it too rather than
+  // whatever the previous file's mode happened to be.
+  await writeFileAtomic(authFilePath(env), `${JSON.stringify(data, null, 2)}\n`, "utf8", { mode: 0o600 });
+}
+
+/** Sign out: delete the stored credential. Returns whether there was one.
+ *  Does not revoke the token at the endpoint - that is `oauth/revoke`, and a
+ *  laptop with no network right now should still be able to forget its own
+ *  file. */
+export async function logout(env = process.env) {
+  // The dead-credential mark goes with it (2026-09-13). It is keyed to a
+  // refresh token that is about to stop existing, so leaving it behind would
+  // only litter; it is cleared before the credential rather than after, so a
+  // logout interrupted half way never leaves a mark with no auth.json to
+  // match it against.
+  await clearDeadMark(env);
+  try {
+    await unlink(authFilePath(env));
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+// ------------------------------------------------------------- the token
+
+/* ONE REFRESH AT A TIME, ACROSS EVERY CALLER (2026-09-13).
+ *
+ * THE BUG THIS EXISTS FOR, because it cost a day and looked like three other
+ * things first. A refresh token is SINGLE-USE - board-oauth/store.mjs
+ * `takeRefresh` rotates it, and presenting a spent one is by definition the
+ * stolen-token signal, so `revokeFamily` kills the whole family including the
+ * token that was just minted for whoever won the race. `hostedToken` had no
+ * lock of any kind, and the daemon runs one watch loop PER REGISTERED FOLDER
+ * (multiwatch.mjs, `for (const folder of first) startFolder(folder)`, five of
+ * them on his machine). Both `runnerApi.post` and `hosted.callTool` recover
+ * from a 401 by calling back in with `forceRefresh: true`. So a single expiry
+ * or a single 401 put five callers through here at once, all reading the same
+ * `auth.json` and posting the same refresh token: one rotated, four read as
+ * reuse, and the family died ~0.2s after being issued.
+ *
+ * It is self-sustaining, which is why it never recovered: every caller is 401
+ * again immediately, forces another refresh, and kills the next family too.
+ * `viewable login` could not fix it either - the new family was revoked inside
+ * a second by the loops already spinning. Observed twice on 2026-09-13
+ * (02:19:54 killed the runner, 09:30:14 killed the recovery login), both
+ * times two rows one second apart sharing a family_id with `last_used_at`
+ * null on the newer one.
+ *
+ * TWO LOCKS, because there are two ways to be concurrent here. The in-process
+ * map covers the five watch loops, which is the case that actually bit. The
+ * lock DIRECTORY covers a second process - a spawned session reaching the
+ * board, `viewable doctor`, a second daemon - because `mkdir` is the one
+ * filesystem primitive that is atomic and fails EEXIST everywhere, with no
+ * dependency. Whoever loses either lock does NOT refresh: it waits, re-reads
+ * the file, and uses what the winner wrote.
+ *
+ * A revoked refresh token is not retried at poll cadence: presenting a spent
+ * refresh token is itself what triggers the next `revokeFamily`
+ * (board-oauth/oauth.mjs:684-687), so a loop that keeps presenting one holds
+ * the alarm down that killed its own family. See THE DEAD GATE below, which
+ * is what stops it. */
+const refreshInFlight = new Map();
+
+/** How long to wait for another process's refresh before giving up on the
+ *  lock and using whatever is on disk. A refresh is one HTTPS round trip;
+ *  ten seconds is far past the point where waiting longer helps. */
+const LOCK_WAIT_MS = 10_000;
+
+/** A lock directory older than this belonged to a process that died holding
+ *  it. Generous against a slow network, short enough that a crash does not
+ *  wedge a laptop until it reboots. */
+const LOCK_STALE_MS = 60_000;
+
+const LOCK_POLL_MS = 50;
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Take the cross-process refresh lock, or null if another process holds it
+ *  and has not finished within LOCK_WAIT_MS, or the filesystem refuses it.
+ *  Never throws: without the cross-process lock the caller does not refresh;
+ *  it re-reads the credential and mark, returning a usable cached token or null. */
+async function takeRefreshLock(env, now) {
+  const path = `${authFilePath(env)}.refresh.lock`;
+  const deadline = now() + LOCK_WAIT_MS;
+  for (;;) {
+    try {
+      await mkdir(path);
+      return path;
+    } catch (error) {
+      if (error?.code !== "EEXIST") return null;
+      // Held. If the holder is long gone, clear it and try once more on the
+      // next turn of this loop rather than racing to recreate it here.
+      try {
+        const held = await stat(path);
+        if (now() - held.mtimeMs > LOCK_STALE_MS) {
+          await rm(path, { recursive: true, force: true });
+          continue;
+        }
+      } catch { /* it went away underneath us; the retry will take it */ }
+      if (now() >= deadline) return null;
+      await sleep(LOCK_POLL_MS);
+    }
+  }
+}
+
+const dropRefreshLock = async (path) => {
+  if (path === null) return;
+  try { await rm(path, { recursive: true, force: true }); } catch { /* already gone */ }
+};
+
+/* THE DEAD GATE (2026-09-13): a credential that is DEAD, not merely stale.
+ *
+ * STALE is the case this file was already good at: the access token has aged
+ * past its hour (or twelve), the refresh token is fine, and one round trip
+ * fixes it invisibly. That path is untouched.
+ *
+ * DEAD is a different fact. The endpoint has told us, in so many words, that
+ * this credential cannot be renewed - `invalid_grant` from a refresh token
+ * that was revoked, rotated or has expired, or `invalid_client` from a client
+ * registration that no longer exists (board-oauth/oauth.mjs:626-694). No
+ * number of retries fixes it and only a person can: `viewable login`.
+ *
+ * Retrying it at poll cadence is actively harmful rather than merely noisy,
+ * which is why this is a gate and not a log line. `revokeFamily` updates every
+ * row sharing a family_id, access tokens included (board-oauth/store.mjs:114-
+ * 123), so a family killed by one reuse takes the access token with it; and
+ * presenting a spent refresh token is itself what triggers the next
+ * `revokeFamily`. A loop that keeps presenting one is holding the alarm down.
+ *
+ * IT COOPERATES WITH THE REFRESH LOCK ABOVE RATHER THAN DUPLICATING IT. The
+ * lock's job is "only one of us refreshes at a time"; this gate's job is
+ * "none of us refreshes at all for a while". It is checked BEFORE the
+ * in-flight map, so a dead credential never takes the lock, never queues
+ * behind a refresh, and costs nothing. Permanent refresh refusals never
+ * expire; transient failures use a timed backoff shared by every process.
+ *
+ * IT LIVES ON DISK, beside auth.json and for the same reason the lock is a
+ * directory: `viewable doctor`, a spawned session and the daemon are three
+ * processes, and a mark only one of them can see would let the other two go
+ * on hammering while doctor reported health. It stores a SHA-256 of the
+ * refresh token, never the token - enough to answer "is this still the
+ * credential that died", with no second copy of a bearer on disk.
+ *
+ * IT CLEARS ITSELF, which is the part that matters most. `viewable login`
+ * writes a new refresh token; a refresh another process wins writes one too.
+ * Either way the fingerprint stops matching and the mark is void on the next
+ * read - nobody has to know it exists, and no backoff outlives the credential
+ * it was about. A successful refresh clears transient-only history.
+ * Access-token rejection history follows rotation, so a server that keeps
+ * rejecting new tokens cannot reset the cooldown by accepting each refresh.
+ * A successful refresh clears carried history older than the maximum backoff,
+ * allowing a recovered credential to warn and start at one minute again. */
+
+/** First wait after a transient refresh failure or an access-token rejection. */
+const DEAD_BACKOFF_START_MS = 60_000;
+
+/** Cap transient retries at one per half hour. Permanent refresh refusals
+ *  do not retry until login replaces the credential. */
+const DEAD_BACKOFF_MAX_MS = 30 * 60_000;
+
+/** The OAuth error codes that mean "a person must sign in again", per RFC
+ *  6749 section 5.2 and what board-oauth actually answers. Everything else -
+ *  a 5xx, a timeout, a proxy returning HTML, an unreadable body - is the
+ *  network having a bad minute: back off, while still offering a cached
+ *  access token that has not literally expired. */
+const TERMINAL_REFRESH_ERRORS = new Set([
+  "invalid_grant",
+  "invalid_client",
+  "unauthorized_client",
+  "invalid_scope",
+]);
+
+/** The one sentence a person gets. Not a log to read, not a stack: what is
+ *  wrong and the command that fixes it, in one line, wherever it surfaces -
+ *  the runner's log, a tool result, or `viewable doctor`'s own row. */
+export const REAUTH_REQUIRED_HINT =
+  "Your Viewable sign-in has expired and cannot be renewed: run `viewable login` to sign in again.";
+
+/** The personal-token sibling of REAUTH_REQUIRED_HINT (2026-09-19, brief 43
+ *  review, B2). A `pmb_` token is not refreshed - it is revoked from
+ *  Settings - so the fix is not `viewable login`, it is a fresh token copied
+ *  from the same place the old one came from. */
+export const PERSONAL_TOKEN_REJECTED_HINT =
+  "The stored personal token was rejected by the board: copy a fresh one from Settings and set VIEWABLE_BOARD_TOKEN, " +
+  "or run `viewable login` again.";
+
+/** The OAuth-pair mark: keyed by the refresh token, same path and shape this
+ *  file has always used. Every plain (non-`personal`) record's mark lives
+ *  here, and so does a merged record's OAuth-side mark. */
+const deadMarkPath = (env = process.env) => `${authFilePath(env)}.dead`;
+
+/** The personal-token mark, keyed by the `pmb_` access token itself
+ *  (2026-09-19, TWO CREDENTIALS below). A SEPARATE FILE, not a second field
+ *  in the same mark, so the two never overwrite each other and so every
+ *  existing reader of `auth.json.dead` (doctor, the test suite) keeps seeing
+ *  exactly the OAuth-pair mark it always did. */
+const personalDeadMarkPath = (env = process.env) => `${authFilePath(env)}.dead.personal`;
+
+const markPathFor = (kind, env) => (kind === "personal" ? personalDeadMarkPath(env) : deadMarkPath(env));
+
+const credentialFingerprint = (token) =>
+  createHash("sha256").update(String(token)).digest("hex");
+
+/** Whether a merged record's OAuth pair is actually usable - present AND
+ *  complete enough to refresh with. Named once because `hostedToken`,
+ *  `reauthRequired` and `hostedStatus` all ask it. */
+const hasOAuthPair = (stored) =>
+  typeof stored?.refreshToken === "string" && stored.refreshToken !== "" &&
+  typeof stored?.tokenEndpoint === "string" && typeof stored?.clientId === "string";
+
+/** TWO CREDENTIALS, TWO MARKS (2026-09-19). A merged record - `personal:
+ *  true` written by `login()` over an existing OAuth credential, which keeps
+ *  the OAuth pair alongside the personal token rather than discarding it
+ *  (B7) - carries two DISTINCT bearers an endpoint can reject independently:
+ *  the `pmb_` personal token, and the OAuth pair behind its refresh token.
+ *  Fingerprinting the mark against whichever one the caller means, rather
+ *  than always preferring the refresh token, is what the rest of this file
+ *  is for.
+ *
+ * THE BUG THIS REPLACES. A single mark, fingerprinted by
+ * `fingerprintSubject` (refresh token whenever one was on file), meant that
+ * on a merged record a REJECTED PERSONAL TOKEN wrote a mark keyed by the
+ * REFRESH TOKEN. `hostedToken`'s `personal: true` branch read that same
+ * mark, saw it live, and fell through to `oauthAccessToken(...,
+ * forceRefresh: true)` on every single call - not just the first one after
+ * the rejection - which rotated the refresh token every poll. Worse, a
+ * successful refresh cleared the one mark that existed, so the very next
+ * poll offered the revoked personal token again, got rejected again, and
+ * the whole cycle repeated at poll cadence forever: a rotation burned every
+ * cycle, `PERSONAL_TOKEN_REJECTED_HINT` never settling.
+ *
+ * `subjectFor("personal", stored)` is the `pmb_` token itself (only when
+ * `stored.personal === true` - a plain OAuth record has no personal
+ * credential to mark). `subjectFor("oauth", stored)` is the refresh token,
+ * with a fallback to the access token for the rare pre-brief-43 record that
+ * has neither `personal` nor a refresh token (the ordinary case this file
+ * already handled before merged records existed). */
+const subjectFor = (kind, stored) => {
+  if (!stored) return null;
+  if (kind === "personal") {
+    return stored.personal === true && typeof stored.accessToken === "string" && stored.accessToken !== ""
+      ? stored.accessToken
+      : null;
+  }
+  if (typeof stored.refreshToken === "string" && stored.refreshToken !== "") return stored.refreshToken;
+  return stored.personal !== true && typeof stored.accessToken === "string" && stored.accessToken !== ""
+    ? stored.accessToken
+    : null;
+};
+
+/** Say it once, to stderr, and never again for the same credential - the
+ *  `notified` flag on the mark is what makes it once rather than once per
+ *  call. Injectable so the suite can read it without a captured stream. */
+const writeToStderr = (message) => {
+  try { process.stderr.write(`${message}\n`); } catch { /* no stderr to write to */ }
+};
+
+/** The mark on file for THIS credential of THIS kind, or null. `kind` is
+ *  `"personal"` or `"oauth"` (default) - see subjectFor and markPathFor.
+ *  Null also when the mark describes a different token than the one on file
+ *  now, in which case it is deleted on the way past: that is the
+ *  self-clearing half, and it is why signing in again needs no other step
+ *  (a rotated refresh token voids the oauth mark; a fresh personal token
+ *  voids the personal one - independently, since each lives in its own
+ *  file). Transient cooldowns share this storage but are hidden from
+ *  status/reauth readers unless explicitly requested. */
+async function matchingDeadMark(stored, env, kind = "oauth", includeTransient = false) {
+  const subject = subjectFor(kind, stored);
+  if (subject === null) return null;
+  let mark;
+  try {
+    mark = JSON.parse(await readFile(markPathFor(kind, env), "utf8"));
+  } catch {
+    return null;
+  }
+  if (!mark || typeof mark !== "object" || typeof mark.fingerprint !== "string") return null;
+  if (mark.fingerprint !== credentialFingerprint(subject)) {
+    await clearDeadMark(env, kind);
+    return null;
+  }
+  return !includeTransient && mark.reason === "refresh_transient" ? null : mark;
+}
+
+/** Clears one mark (`kind` given) or both (omitted - `logout()`'s case: the
+ *  whole record is going away, personal and OAuth marks alike). */
+async function clearDeadMark(env, kind) {
+  const paths = kind ? [markPathFor(kind, env)] : [deadMarkPath(env), personalDeadMarkPath(env)];
+  await Promise.all(paths.map(async (path) => {
+    try { await unlink(path); } catch { /* already gone */ }
+  }));
+}
+
+/** Record a credential failure: permanent for refresh refusals, otherwise
+ *  double the wait. `prior` is the mark already on file for the same credential, so a
+ *  refusal that keeps repeating backs further off instead of resetting to a
+ *  minute each time. Never throws: a home directory that refuses the mark
+ *  falls back to the old behaviour rather than turning a refused token into
+ *  a crash. */
+async function markCredentialDead(stored, env, now, reason, prior, notify, kind = "oauth") {
+  // A recovered credential may still carry history when its next refresh
+  // fails. Expire that history here too, before deriving the new failure.
+  if (prior && prior.reason !== "refresh_refused" && now() - Number(prior.until) > DEAD_BACKOFF_MAX_MS) {
+    prior = null;
+  }
+  const keepRefreshWait = reason === "rejected" && prior?.reason === "refresh_transient" && now() < Number(prior.until);
+  const tries = Number(prior?.tries ?? 0) + (keepRefreshWait ? 0 : 1);
+  const wait = Math.min(DEAD_BACKOFF_START_MS * 2 ** (tries - 1), DEAD_BACKOFF_MAX_MS);
+  const alreadyToldThem = prior?.notified === true;
+  const mark = {
+    fingerprint: credentialFingerprint(subjectFor(kind, stored)),
+    reason,
+    tries,
+    since: prior?.since ?? new Date(now()).toISOString(),
+    until: reason === "refresh_refused" ? null : keepRefreshWait ? prior.until : now() + wait,
+    notified: alreadyToldThem || reason !== "refresh_transient",
+  };
+  try {
+    await mkdir(glytchHome(env), { recursive: true });
+    await writeFileAtomic(markPathFor(kind, env), `${JSON.stringify(mark, null, 2)}\n`, "utf8", { mode: 0o600 });
+  } catch { /* see above: the mark is an optimisation, not a precondition */ }
+  // The personal token gets its own sentence (B2): it is rejected, not
+  // expired, and the fix is a fresh token from Settings, not `glytch login`.
+  if (reason !== "refresh_transient" && !alreadyToldThem) {
+    (notify ?? writeToStderr)(kind === "personal" ? PERSONAL_TOKEN_REJECTED_HINT : REAUTH_REQUIRED_HINT);
+  }
+  return mark;
+}
+
+/** Whether the credential on file is one the endpoint has refused - the
+ *  question `viewable doctor` asks, and the one a caller asks before deciding
+ *  between "you were never signed in" and REAUTH_REQUIRED_HINT. Costs one
+ *  small file read and no network, so it keeps the promise hostedStatus
+ *  already makes. Deliberately ignores `until`: that bounds when the next
+ *  access-token probe is allowed. A permanent refresh refusal never probes.
+ *
+ * `viewable login` IS THE FIX FOR THE OAUTH PAIR, NEVER FOR THE PERSONAL TOKEN
+ * (2026-09-19). A merged record with a dead personal token but a live OAuth
+ * pair is not asking for `viewable login` - it still has a working credential,
+ * and PERSONAL_TOKEN_REJECTED_HINT already said what to do about the other
+ * one. So this checks the OAuth mark whenever there IS an OAuth pair to fall
+ * back on, and only checks the personal mark when there is nothing else -
+ * exactly `hostedToken`'s own branching, below. */
+export async function reauthRequired(env = process.env) {
+  const stored = await readAuthFile(env);
+  if (stored === null) return false;
+  if (stored.personal === true && !hasOAuthPair(stored)) {
+    return (await matchingDeadMark(stored, env, "personal")) !== null;
+  }
+  return (await matchingDeadMark(stored, env, "oauth")) !== null;
+}
+
+/** A 401 the endpoint gave us on a token a forced refresh could not fix -
+ *  called by lib/hosted.mjs and lib/runnerApi.mjs, which are where that fact
+ *  is actually observed. It is separate evidence from a refused REFRESH: a
+ *  revoked family answers 401 on the access token while the copy on disk is
+ *  still minutes from its local expiry, so without this the gate would let a
+ *  loop keep posting a token the server has already rejected.
+ *
+ * `token` IS THE BEARER THAT WAS ACTUALLY SENT (2026-09-19) - the caller's
+ * own record of what went out on the wire, not a guess re-derived from
+ * `auth.json` after the fact. That matters on a merged record: the personal
+ * token and the OAuth access token are two different bearers, and only the
+ * caller knows which one this particular 401 was about. Omitting `token`
+ * (kept for the handful of direct test calls this file's own suite makes) is
+ * read as "the record's own primary credential" - the personal token for a
+ * `personal: true` record, the OAuth pair otherwise - which is right for a
+ * merged record's personal-token rejection but WOULD mismark an OAuth-pair
+ * rejection on one, so every real caller now passes `token`. */
+export async function noteCredentialRejected({ env = process.env, now = () => Date.now(), notify, token } = {}) {
+  const stored = await readAuthFile(env);
+  if (stored === null) return false;
+  const kind = rejectedKind(stored, token);
+  if (kind === null) return false;
+  // The forced refresh ran after this access-token rejection. Preserve its
+  // retry count and deadline while also suppressing the rejected access token.
+  const prior = await matchingDeadMark(stored, env, kind, true);
+  if (prior?.reason !== "refresh_refused") {
+    await markCredentialDead(stored, env, now, "rejected", prior, notify, kind);
+  }
+  return true;
+}
+
+/** Which credential a 401 was about: the caller's own `token` when it says
+ *  so, matched against the two bearers a merged record can carry
+ *  (`stored.accessToken`, the personal token, and `stored.oauthAccessToken`,
+ *  the cached OAuth access token - see `hostedToken`'s `fields` below); for
+ *  a plain OAuth record, its single `accessToken` is always the OAuth one.
+ *  Returns null when `token` matches neither - stale by the time the 401
+ *  came back, most likely because another process already refreshed - since
+ *  there is nothing on file to mark it against. */
+function rejectedKind(stored, token) {
+  if (typeof token === "string" && token !== "") {
+    if (stored.personal === true && token === stored.accessToken) return "personal";
+    if (stored.personal === true) return typeof stored.oauthAccessToken === "string" && token === stored.oauthAccessToken ? "oauth" : null;
+    return token === stored.accessToken ? "oauth" : null;
+  }
+  if (stored.personal === true) return "personal";
+  if (typeof stored.refreshToken === "string" && stored.refreshToken !== "") return "oauth";
+  return null;
+}
+
+/** A valid access token, or null when there is genuinely none to be had.
+ *
+ * `VIEWABLE_BOARD_TOKEN` wins outright: a script that sets a personal access
+ * token means exactly that token, forever, with no file and no refresh.
+ *
+ * Otherwise, the stored OAuth token is returned as-is unless it is within a
+ * minute of expiring (or `forceRefresh` asks anyway), in which case a refresh
+ * is attempted and the file is rewritten with the new pair. A refresh that
+ * fails transiently falls back to the token on file if it has not
+ * literally expired yet - a network blip should not turn a live token into a
+ * refusal - and only returns null once there is truly nothing left to offer.
+ *
+ * Concurrent callers do not each refresh; see the block above. */
+export async function hostedToken({
+  env = process.env,
+  forceRefresh = false,
+  fetchImpl = fetch,
+  now = () => Date.now(),
+  notify,
+  log = () => {},
+} = {}) {
+  // Compatibility read: old installs may still set GLYTCH_BOARD_TOKEN (#2196).
+  const scripted = typeof (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN) === "string" ? (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN).trim() : "";
+  if (scripted !== "") return scripted;
+
+  const stored = await readAuthFile(env);
+  if (!stored) return null;
+
+  // A STORED PERSONAL TOKEN (brief 43, 2026-09-19) IS NOT AN OAUTH RECORD -
+  // unless `login()` has merged an OAuth pair alongside it (B7, below).
+  // `login()` writes `personal: true` when it sees VIEWABLE_BOARD_TOKEN in ITS
+  // OWN environment - the paste-and-run install sets the variable for one
+  // shell, and the daemon that keeps running after that shell is gone needs
+  // the same bearer without the variable. On its own the personal token has
+  // no `accessExpiresAt` to compare against (it would read as expired, being
+  // `undefined`), no `refreshToken` to spend, and no refresh attempt - a
+  // `pmb_` token is revoked from Settings, not refreshed.
+  //
+  // IT STILL GOES THROUGH THE DEAD GATE (2026-09-19, brief 43 review, B2).
+  // There is no refresh to fail here, but there is still a 401 a caller can
+  // observe and report through `noteCredentialRejected` - and before this fix
+  // that call never wrote a mark for a personal record at all. `subjectFor`
+  // now fingerprints a personal record's OWN mark against the access token
+  // itself, in its own file, so a personal-only record gets a mark of its
+  // own no matter what else is (or is not) on the record beside it.
+  if (stored.personal === true) {
+    const oauthPair = hasOAuthPair(stored);
+    // PERSONAL-TOKEN DEAD GATE. Checked against the personal mark ONLY -
+    // 2026-09-19, the fix for the loop described at subjectFor's own
+    // comment. A rejected personal token must stop being offered for the
+    // WHOLE backoff window regardless of what the OAuth pair beside it is
+    // doing, and an OAuth-pair rejection (case b, below) must never silence
+    // the personal token - they are two credentials, and this gate only
+    // ever asks about one of them.
+    const personalDead = await matchingDeadMark(stored, env, "personal");
+    const personalIsDead = personalDead !== null && now() < Number(personalDead.until);
+    if (!personalIsDead) return stored.accessToken;
+    if (!oauthPair) return null;
+    // FALL THROUGH TO THE OAUTH PAIR (2026-09-19, brief 43 review, B7;
+    // 2026-09-19 fix). `login()` with VIEWABLE_BOARD_TOKEN over an existing
+    // OAuth credential keeps both in the same record, so a personal token
+    // with a live dead mark falls through to the OAuth pair rather than
+    // handing back null for the whole backoff window while a working
+    // credential sits right beside the refused one - but it is an ORDINARY
+    // refresh here, not `forceRefresh: true`: the merged record's cached
+    // OAuth access token lives in its OWN fields (`oauthAccessToken`,
+    // `oauthAccessExpiresAt`, below), never in `accessToken`/
+    // `accessExpiresAt` (those describe the personal token and only the
+    // personal token, so nothing here has to guess which credential a
+    // shared field is about). Once that OAuth access token is fresh, N
+    // more polls with the personal mark still live read it straight off
+    // disk - no refresh, no rotation - until the caller's own `forceRefresh`
+    // or a real 401 on the OAuth side asks for one.
+    return oauthAccessToken(stored, {
+      env, fetchImpl, now, notify, forceRefresh, log,
+      fields: { token: "oauthAccessToken", expires: "oauthAccessExpiresAt" },
+    });
+  }
+
+  // THE DEAD GATE, and it sits BEFORE the freshness check on purpose - see the
+  // block above. Local freshness is a claim about a clock; the mark is what
+  // the endpoint actually said. They disagree in exactly the case that hurts:
+  // `revokeFamily` kills the access token alongside the refresh token
+  // (board-oauth/store.mjs:114-123), so a revoked credential goes on LOOKING
+  // fresh here for the rest of its nominal life - up to twelve hours for the
+  // runner's own client. Gated after the freshness check, the one caller shape
+  // that actually loops would have been the one shape that still hammered.
+  return oauthAccessToken(stored, { env, fetchImpl, now, notify, forceRefresh, log });
+}
+
+/** The freshness check, the single-flight refresh and its lock - the part of
+ *  `hostedToken` shared by an ordinary OAuth record and a merged
+ *  `personal: true` record that has fallen through to its OAuth pair (B7).
+ *
+ * `fields` says WHERE the OAuth access token and its expiry live on the
+ * record - `{token: "accessToken", expires: "accessExpiresAt"}` (the
+ * default) for a plain OAuth record, where that pair IS the whole
+ * credential; `{token: "oauthAccessToken", expires: "oauthAccessExpiresAt"}`
+ * for a merged record falling through from its personal token, where
+ * `accessToken`/`accessExpiresAt` are the PERSONAL token's own fields and
+ * must never be read or overwritten here (2026-09-19 fix - this is the
+ * answer to "does `accessExpiresAt` on a merged record describe the OAuth
+ * access token or the personal one": it is always the personal one on a
+ * merged record, which is exactly why the OAuth side gets its own two
+ * fields rather than sharing). The dead mark this function writes on a
+ * terminal refusal is always the `"oauth"` kind - refusing to renew the
+ * refresh token is a fact about the OAuth pair regardless of which field
+ * shape asked for the refresh. */
+async function oauthAccessToken(stored, {
+  env, forceRefresh, fetchImpl, now, notify,
+  fields = { token: "accessToken", expires: "accessExpiresAt" },
+  log = () => {},
+}) {
+  // Both ordinary credentials and a personal-token fallback obey this gate.
+  // Older finite refusals get one re-check after their cooldown.
+  const dead = await matchingDeadMark(stored, env, "oauth", true);
+  if (dead?.reason === "refresh_refused" && dead.until === null) return null;
+  if (dead !== null && now() < Number(dead.until)) {
+    const t = stored[fields.token];
+    return dead.reason === "refresh_transient" && typeof t === "string" && t !== "" &&
+      Number(stored[fields.expires]) > now() ? t : null;
+  }
+
+  const fresh = (row) => {
+    const t = row[fields.token];
+    return typeof t === "string" && t !== "" && Number(row[fields.expires]) - now() >= REFRESH_SKEW_MS;
+  };
+  if (!forceRefresh && fresh(stored)) return stored[fields.token];
+
+  if (!stored.refreshToken || !stored.tokenEndpoint || !stored.clientId) {
+    // Nothing to refresh WITH. Still usable if it has not actually expired.
+    const t = stored[fields.token];
+    return typeof t === "string" && t !== "" && Number(stored[fields.expires]) > now() ? t : null;
+  }
+
+  // Keyed by the auth file rather than by process: a test with its own
+  // GLYTCH_HOME, and a person with two, are genuinely separate credentials
+  // and must not queue behind each other. A given file only ever uses ONE
+  // `fields` shape at a time (a record is either personal or is not), so
+  // the path alone is still the right key.
+  const key = authFilePath(env);
+  const running = refreshInFlight.get(key);
+  if (running) return running;
+
+  const attempt = (async () => {
+    const lock = await takeRefreshLock(env, now);
+    let source = stored;
+    try {
+      // DOUBLE-CHECKED, and the check is "did the token CHANGE", not "is it
+      // fresh now". A 401 forces a refresh on a token that may still be
+      // minutes from expiry, so freshness would send us to the endpoint with
+      // the very token the winner already spent. A different access token on
+      // disk means somebody refreshed while we waited, and their result is
+      // the answer to both questions.
+      const current = await readAuthFile(env);
+      if (current && current[fields.token] !== stored[fields.token]) return current[fields.token];
+      source = current ?? stored;
+      // A process ahead of us may have recorded a failure while we waited.
+      const mark = await matchingDeadMark(source, env, "oauth", true);
+      if (mark?.reason === "refresh_refused" && mark.until === null) return null;
+      if (lock === null || (mark !== null && now() < Number(mark.until))) {
+        const t = source[fields.token];
+        return (mark === null || mark.reason === "refresh_transient") && typeof t === "string" &&
+          t !== "" && Number(source[fields.expires]) > now() ? t : null;
+      }
+      // A REFRESH IS ABOUT TO HAPPEN OVER THE NETWORK (2026-09-21, the
+      // claim-to-spawn gap). Every path above this line returns early -
+      // nothing on file to refresh, already fresh, another process just
+      // refreshed - so reaching here means an HTTPS round trip is about to
+      // block whoever called `hostedToken`, silently until now.
+      const refreshStartedAt = now();
+      const refreshed = await refreshStoredTokens(source, { fetchImpl, now });
+      log(`refreshed hosted token (${Math.round(now() - refreshStartedAt)}ms)`);
+      const updated = {
+        ...source,
+        [fields.token]: refreshed.accessToken,
+        // Rotation: a refresh token is single-use (board-oauth's own rule),
+        // shared by both field shapes because there is only ever one
+        // refresh token on a record no matter which access-token field it
+        // is renewing.
+        refreshToken: refreshed.refreshToken,
+        [fields.expires]: refreshed.accessExpiresAt,
+      };
+      await writeAuthFile(updated, env);
+      // The new access token can be tried, but a successful refresh is not
+      // proof that the board will accept it. Carry rejection history across
+      // rotation as an expired transient mark: no gate or sign-in warning,
+      // while the next 401 continues the backoff instead of resetting it.
+      // There is no board-acceptance hook here. A successful refresh after
+      // the carried deadline has been quiet for more than the maximum wait
+      // resets history, so a recovered outage cannot poison future failures.
+      // An active 401 loop retries at its deadline and keeps its history.
+      // Ordinary transient-only recovery still clears its history.
+      // The PERSONAL mark, if any, is untouched - a working OAuth
+      // fallback does not un-reject the personal token that got rejected;
+      // see hostedToken's own comment for why offering it again is the bug
+      // this whole file exists to fix.
+      if (mark?.notified === true && mark.reason !== "refresh_refused" &&
+          now() - Number(mark.until) <= DEAD_BACKOFF_MAX_MS) {
+        try {
+          await writeFileAtomic(deadMarkPath(env), `${JSON.stringify({
+            ...mark, fingerprint: credentialFingerprint(updated.refreshToken),
+            reason: "refresh_transient", until: now(),
+          }, null, 2)}\n`, "utf8", { mode: 0o600 });
+        } catch { /* history is best-effort; the new credential is already saved */ }
+      } else {
+        await clearDeadMark(env, "oauth");
+      }
+      return updated[fields.token];
+    } catch (error) {
+      const current = await readAuthFile(env);
+      // A login during the request must not inherit the old token's failure.
+      if (current && current.refreshToken !== source.refreshToken) return null;
+      const prior = await matchingDeadMark(source, env, "oauth", true);
+      await markCredentialDead(source, env, now,
+        error?.terminal === true ? "refresh_refused" : "refresh_transient",
+        prior, notify, "oauth");
+      if (error?.terminal === true) return null;
+      const t = source[fields.token];
+      return typeof t === "string" && t !== "" && Number(source[fields.expires]) > now() ? t : null;
+    } finally {
+      await dropRefreshLock(lock);
+    }
+  })();
+
+  refreshInFlight.set(key, attempt);
+  try {
+    return await attempt;
+  } finally {
+    refreshInFlight.delete(key);
+  }
+}
+
+/** The bare refresh_token grant: posts it, and returns just the new pair
+ *  (never the rest of `stored`) so the caller decides which fields on the
+ *  full record it belongs in - `accessToken`/`accessExpiresAt` for a plain
+ *  OAuth record, `oauthAccessToken`/`oauthAccessExpiresAt` for a merged
+ *  one's fallback (see oauthAccessToken's `fields`). */
+async function refreshStoredTokens(stored, { fetchImpl, now }) {
+  const response = await fetchImpl(stored.tokenEndpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: new URLSearchParams({
+      grant_type: "refresh_token",
+      refresh_token: stored.refreshToken,
+      client_id: stored.clientId,
+    }),
+  });
+  const text = await response.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`refresh: the token endpoint answered ${response.status} with unreadable JSON`);
+  }
+  if (!response.ok || typeof body.access_token !== "string") {
+    const failure = new Error(`refresh: ${body.error_description ?? body.error ?? `HTTP ${response.status}`}`);
+    // TERMINAL vs TRANSIENT, and the OAuth error code is the only honest way
+    // to tell them apart. `invalid_grant` means this refresh token will never
+    // work again; a 503 or a dropped connection means try later. Marked on
+    // the error rather than decided here, because the caller is the one
+    // holding the refresh lock and the one that has to record it.
+    if (TERMINAL_REFRESH_ERRORS.has(body.error)) failure.terminal = true;
+    throw failure;
+  }
+  return {
+    accessToken: body.access_token,
+    // Rotation: a refresh token is single-use (board-oauth's own rule), so the
+    // new one replaces the old one. A server that omits it (should not
+    // happen) leaves the prior one in place rather than dropping the ability
+    // to refresh again.
+    refreshToken: typeof body.refresh_token === "string" ? body.refresh_token : stored.refreshToken,
+    accessExpiresAt: now() + Math.max(0, Number(body.expires_in) || 0) * 1000,
+  };
+}
+
+/** Where the child's own header points: the MCP url and the app origin it was
+ *  derived from. Reads the stored file when there is one (login already
+ *  discovered the real mcpUrl); otherwise derives the default shape from
+ *  `GLYTCH_APP_URL` / the production origin, same as a fresh login would
+ *  before ever calling the endpoint. */
+export async function hostedConfig({ env = process.env } = {}) {
+  const stored = await readAuthFile(env);
+  if (stored && typeof stored.mcpUrl === "string" && typeof stored.appUrl === "string") {
+    return { appUrl: stored.appUrl, mcpUrl: stored.mcpUrl };
+  }
+  const appUrl = appUrlFrom(undefined, env);
+  return { appUrl, mcpUrl: `${appUrl}/mcp` };
+}
+
+/** Cheap, no-network status for `viewable doctor`'s one row: is there a
+ *  credential on file (or a script token in the environment) at all, and is
+ *  it one the endpoint has already refused. Does NOT refresh or validate
+ *  against the endpoint - doctor rows are meant to be read constantly, and a
+ *  network call per `doctor` run for one row is not the bargain the rest of
+ *  doctor keeps.
+ *
+ * `dead` JOINED IT 2026-09-13, and it is the reason the row was misleading
+ * before. "Signed in" used to mean no more than "auth.json exists", so the
+ * one row a person checks when their runner cannot authenticate read green
+ * on exactly the machine that could not authenticate. The dead-credential
+ * mark is written next to auth.json by whichever process hit the refusal
+ * (the daemon, usually), so doctor can report it from another process
+ * without a network call of its own. */
+export async function hostedStatus(env = process.env) {
+  // Compatibility read: old installs may still set GLYTCH_BOARD_TOKEN (#2196).
+  if (typeof (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN) === "string" && (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN).trim() !== "") {
+    return { signedIn: true, via: "VIEWABLE_BOARD_TOKEN" };
+  }
+  const stored = await readAuthFile(env);
+  if (stored === null) return { signedIn: false, via: null };
+  // A stored personal token (brief 43) DOES have a dead mark to check, since
+  // 2026-09-19's B2 fix - it is a distinct `via` so `glytch doctor` can word
+  // this row unlike the OAuth case ("rejected" rather than "expired and
+  // cannot be renewed": a `pmb_` token is revoked from Settings, never
+  // refreshed, so the fix is a fresh one from there, not `glytch login`).
+  //
+  // TWO MARKS TO CHECK ON A MERGED RECORD (2026-09-19 fix): the personal
+  // token's own mark surfaces first - it is the credential this row is
+  // named after (`via: "personal token"`), and a live one is worth flagging
+  // even while the OAuth pair carries the actual traffic. Only when the
+  // personal token is NOT what's dead does the row fall back to the
+  // OAuth-pair mark, so a merged record whose fallback has itself run dry
+  // still reads as `dead: true` rather than silently green.
+  if (stored.personal === true) {
+    const personalMark = await matchingDeadMark(stored, env, "personal");
+    const mark = personalMark ?? (hasOAuthPair(stored) ? await matchingDeadMark(stored, env, "oauth") : null);
+    return {
+      signedIn: true,
+      via: "personal token",
+      ...(mark !== null ? { dead: true, deadSince: mark.since, deadReason: mark.reason } : {}),
+    };
+  }
+  const mark = await matchingDeadMark(stored, env);
+  return {
+    signedIn: true,
+    via: "viewable login",
+    ...(mark !== null ? { dead: true, deadSince: mark.since, deadReason: mark.reason } : {}),
+  };
+}
+
+// ---------------------------------------------------------------- login
+
+const b64url = (buf) => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+async function fetchJson(fetchImpl, url, init) {
+  const response = await fetchImpl(url, init);
+  const text = await response.text();
+  let body;
+  try {
+    body = JSON.parse(text);
+  } catch {
+    throw new Error(`${url}: answered ${response.status} with unreadable JSON: ${text.slice(0, 200)}`);
+  }
+  if (!response.ok) {
+    throw new Error(`${url}: ${body.error_description ?? body.error ?? `HTTP ${response.status}`}`);
+  }
+  return body;
+}
+
+/** RFC 9728: what resource a token from this app is actually issued FOR, and
+ *  which authorization server issues it. The app's own origin is NOT the
+ *  answer - board-oauth's RESOURCE is server config (index.ts's OAUTH_ISSUER
+ *  / OAUTH_RESOURCE), not derived from the request - so an app running on
+ *  `http://localhost:5273` (GLYTCH_APP_URL pointed at a dev server mirroring
+ *  routes.json's rewrites) still proxies this exact document to the SAME
+ *  deployed board-oauth function, which names the PRODUCTION resource
+ *  regardless of what origin asked. Tried as `/mcp` first - RFC 9728's
+ *  per-resource path, and the one routes.json actually rewrites - then the
+ *  bare well-known path; a deploy with neither (older server, before this
+ *  document existed) falls back to the old guess, `${base}/mcp`, and says so,
+ *  rather than failing a login outright.
+ *
+ * THE BUG THIS REPLACES: `login()` used to derive the RFC 8707 `resource` as
+ * `${base}/mcp` unconditionally, so pointing it at a local dev server asked
+ * for `http://localhost:5273/mcp` - a resource board-oauth was never
+ * configured to issue tokens for - and the authorize step refused it outright
+ * ("This server issues tokens for https://prompt.glytch.ai/mcp only."). The
+ * resource a token is FOR is whatever the protected-resource metadata names,
+ * never the app origin a person happened to paste. */
+async function discoverResource(fetchImpl, base, log) {
+  for (const path of ["/.well-known/oauth-protected-resource/mcp", "/.well-known/oauth-protected-resource"]) {
+    try {
+      const response = await fetchImpl(`${base}${path}`);
+      if (!response.ok) continue;
+      const body = JSON.parse(await response.text());
+      if (typeof body.resource !== "string" || body.resource === "") continue;
+      const authorizationServerBase =
+        Array.isArray(body.authorization_servers) && typeof body.authorization_servers[0] === "string"
+          ? trimTrailingSlash(body.authorization_servers[0])
+          : base;
+      return { resource: body.resource, authorizationServerBase };
+    } catch {
+      // Try the next path, or fall through to the guess below.
+    }
+  }
+  log(
+    `${base}: no protected-resource metadata found there (an older deploy?) - guessing ${base}/mcp as the ` +
+      `resource. If sign-in is refused, the app's real resource lives elsewhere.`,
+  );
+  return { resource: `${base}/mcp`, authorizationServerBase: base };
+}
+
+/** Open a URL in the person's default browser. Best-effort and silent on
+ *  failure - the caller always prints the URL too, which is the fallback that
+ *  matters on a headless box or an unfamiliar platform. */
+export function openInBrowser(url) {
+  try {
+    const platform = process.platform;
+    const [cmd, args] =
+      platform === "darwin"
+        ? ["open", [url]]
+        : platform === "win32"
+          ? ["cmd", ["/c", "start", "", url]]
+          : ["xdg-open", [url]];
+    const child = spawn(cmd, args, { stdio: "ignore", detached: true, windowsHide: true });
+    child.on("error", () => {});
+    child.unref();
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Where the loopback callback sends the browser once it is done: the app's
+ *  own `/connected` page (brief 31 follow-up, 2026-09-12 - the user's ruling
+ *  from a screenshot of the bare browser-default page a bearer code used to
+ *  sit in the address bar of). `client=glytch` is what lets `/connected`
+ *  address "Glytch is signed in on this machine" rather than something
+ *  generic; `errorCode`, when given, is a short machine word the page turns
+ *  into a sentence - never the OAuth error text itself, and never the code. */
+function connectedUrl(appUrl, errorCode) {
+  const target = new URL(`${trimTrailingSlash(appUrl)}/connected`);
+  target.searchParams.set("client", "glytch");
+  if (errorCode) target.searchParams.set("error", errorCode);
+  return target.toString();
+}
+
+/** Wait for exactly one GET to `/callback` on this server. Unlike the old
+ *  inline-HTML page, this one exchanges the code and writes the credential
+ *  (via `exchange`) *before* it answers, because the answer - always a 302 to
+ *  `${appUrl}/connected` - has to reflect the real outcome: `?client=glytch`
+ *  alone on success, plus `&error=<state_mismatch|missing_code|denied|
+ *  exchange_failed>` on a failure. The authorization code is exchanged for a
+ *  token and then discarded; it is never placed in the Location this browser
+ *  is sent to. A minimal text/plain body rides behind the redirect for a
+ *  client that does not follow it. Resolves with what `exchange` returned, or
+ *  rejects with the same messages `login()` always threw for these cases; a
+ *  timeout or a server error does the same. The server is closed either way.
+ *
+ * EXACTLY ONE CALLBACK RUNS THE FLOW (2026-09-12 review, F1). A browser does
+ * not promise to request a redirect target once: a reload, a back button or
+ * an address-bar prefetch can GET `/callback` again with the SAME single-use
+ * authorization code. This listener used to run `handle` for every one of
+ * them, so a second exchange of a code the endpoint has already burned raced
+ * the first - and whichever lost decided what the CLI printed, while the
+ * winner had already written auth.json. So the first callback that passes the
+ * state and code checks CLAIMS the flow: `claimed` is set synchronously,
+ * before the first `await`, and every later request is answered out of what
+ * the claim produced - the same `/connected` target once the outcome is
+ * known, one plain line while it is still in flight - and never reaches
+ * `exchange` at all. */
+function waitForCallback(
+  server,
+  { timeoutMs = LOGIN_TIMEOUT_MS, exchangeTimeoutMs = EXCHANGE_TIMEOUT_MS, appUrl, expectedState, exchange },
+) {
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    // THE CLAIM (F1): set synchronously by the first callback that passes the
+    // checks, so a second request sees it before any await can yield.
+    let claimed = false;
+    // What the claiming request answered with, so a later one is told the
+    // same story about the same sign-in. `answered` true with `answeredError`
+    // undefined is the success answer.
+    let answered = false;
+    let answeredError;
+    const finish = (fn, value) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      server.close();
+      fn(value);
+    };
+    const timer = setTimeout(
+      () => finish(reject, new Error("Timed out waiting for the browser sign-in to finish.")),
+      timeoutMs,
+    );
+    if (timer.unref) timer.unref();
+    server.on("error", (error) => finish(reject, error));
+
+    const answer = (res, errorCode) => {
+      answered = true;
+      answeredError = errorCode;
+      res.writeHead(302, {
+        Location: connectedUrl(appUrl, errorCode),
+        "Content-Type": "text/plain; charset=utf-8",
+      });
+      res.end(
+        errorCode
+          ? "Sign-in did not complete. You can close this tab and go back to your terminal."
+          : "Signed in to Viewable. You can close this tab and go back to your terminal.",
+      );
+    };
+
+    /** A reload, a prefetch or a second tab arriving once the flow is
+     *  claimed: it gets the claiming request's own answer and nothing else
+     *  happens. While the exchange is still in flight there is no outcome to
+     *  redirect to yet, so this one says so in a line rather than sending the
+     *  browser to a `/connected` page that would have to guess. */
+    const alreadyHandled = (res) => {
+      if (answered) {
+        answer(res, answeredError);
+        return;
+      }
+      res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8" });
+      res.end("This sign-in is already being completed. You can close this tab and go back to your terminal.");
+    };
+
+    async function handle(params, res) {
+      if (params.get("error")) {
+        const description = params.get("error_description") ?? params.get("error");
+        answer(res, "denied");
+        finish(reject, new Error(`Sign-in was not approved: ${description}`));
+        return;
+      }
+      if (params.get("state") !== expectedState) {
+        answer(res, "state_mismatch");
+        finish(reject, new Error("The sign-in reply's state did not match. Try again."));
+        return;
+      }
+      const code = params.get("code");
+      if (!code) {
+        answer(res, "missing_code");
+        finish(reject, new Error("The sign-in reply carried no authorization code."));
+        return;
+      }
+      // CLAIMED, synchronously, ahead of the await below: from here on this
+      // request owns the flow and no other one may exchange this code.
+      claimed = true;
+      // F2: the browser part is done - the person came back - so the clock
+      // that bounded it comes off HERE rather than after the exchange, and
+      // the exchange runs on a shorter one of its own.
+      clearTimeout(timer);
+      const exchangeTimer = setTimeout(
+        () => finish(reject, new Error("The sign-in code could not be exchanged in time. Try `viewable login` again.")),
+        exchangeTimeoutMs,
+      );
+      if (exchangeTimer.unref) exchangeTimer.unref();
+      try {
+        // `stillWanted` is how the caller's own exchange knows this flow is
+        // still the live one: nothing may be written to disk after `finish`
+        // has already rejected (see login's exchange below).
+        const stored = await exchange(code, { stillWanted: () => !settled });
+        clearTimeout(exchangeTimer);
+        if (settled) {
+          // The bound above already answered the CLI. The browser is still
+          // waiting for something, and it is not a success.
+          answer(res, "exchange_failed");
+          return;
+        }
+        answer(res);
+        finish(resolve, stored);
+      } catch (error) {
+        clearTimeout(exchangeTimer);
+        answer(res, "exchange_failed");
+        finish(reject, error);
+      }
+    }
+
+    server.on("request", (req, res) => {
+      const url = new URL(req.url ?? "/", "http://127.0.0.1");
+      if (url.pathname !== "/callback") {
+        res.writeHead(404).end();
+        return;
+      }
+      // `settled` covers the checks that fail and finish synchronously (a
+      // denied consent, a bad state, no code at all): those never claim, but
+      // their outcome is already decided and a second request must not
+      // re-decide it. `claimed` covers the one that is mid-exchange.
+      if (claimed || settled) {
+        alreadyHandled(res);
+        return;
+      }
+      void handle(url.searchParams, res);
+    });
+  });
+}
+
+/** The whole OAuth 2.1 + PKCE + Dynamic Client Registration flow, driven
+ *  against the SAME endpoints board-oauth serves to claude.ai
+ *  (supabase/functions/board-oauth/README.md has the wire-level sequence).
+ *  Returns the stored credential on success; writes it to `~/.glytch/auth.json`
+ *  (or GLYTCH_HOME) before returning.
+ *
+ * `openUrl` and `fetchImpl` are injected so the test drives the whole flow -
+ * discovery, registration, the loopback redirect, the token exchange - against
+ * a stub, with no real browser and no real network. */
+export async function login({
+  appUrl,
+  env = process.env,
+  openUrl = openInBrowser,
+  fetchImpl = fetch,
+  log = () => {},
+  now = () => Date.now(),
+  // The two clocks, injected for the same reason everything else here is:
+  // the test proves what a timer firing at the wrong moment does without
+  // waiting five real minutes for one.
+  timeoutMs = LOGIN_TIMEOUT_MS,
+  exchangeTimeoutMs = EXCHANGE_TIMEOUT_MS,
+} = {}) {
+  // THE SCRIPT DOOR PERSISTS ITSELF (brief 43, 2026-09-19, "the install,
+  // optimised"). `VIEWABLE_BOARD_TOKEN` already answers every board call with
+  // no file at all - hostedToken() checks it first, above - but that is true
+  // only for THIS process's environment. The paste-and-run install sets the
+  // variable for exactly the one shell that runs `glytch init --yes`, and the
+  // daemon `init` goes on to start (or the one already watching this folder)
+  // is a SEPARATE process with no such variable of its own: unsigned the
+  // moment that shell exits, unless the token lands on disk here. So `login()`
+  // - and therefore `init`'s own sign-in step, which calls this - writes it as
+  // a STORED PERSONAL TOKEN (see hostedToken's `personal: true` branch above)
+  // the instant it sees the variable, opens no browser, waits on nobody, and
+  // returns.
+  // Compatibility read: old installs may still set GLYTCH_BOARD_TOKEN (#2196).
+  const scripted = typeof (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN) === "string" ? (env.VIEWABLE_BOARD_TOKEN ?? env.GLYTCH_BOARD_TOKEN).trim() : "";
+  if (scripted !== "") {
+    const base = appUrlFrom(appUrl, env);
+    // KEEP THE OAUTH PAIR, DO NOT OVERWRITE IT WHOLE (2026-09-19, brief 43
+    // review, B7). This used to write `{accessToken, personal: true, appUrl,
+    // mcpUrl}` unconditionally, so a machine already signed in with `glytch
+    // login` and then run once with VIEWABLE_BOARD_TOKEN set (a CI box, an
+    // install script re-run) lost its refresh token outright - the only
+    // thing left once the personal token was later revoked was
+    // REAUTH_REQUIRED_HINT with nothing to refresh. An existing record's
+    // `refreshToken`, `clientId` and `tokenEndpoint` now ride along under the
+    // new personal token; `hostedToken`'s own `personal: true` branch prefers
+    // this OAuth pair once the personal token gets a live dead mark (B7's
+    // other half).
+    //
+    // THE OAUTH ACCESS TOKEN MOVES INTO ITS OWN FIELDS, NOT JUST THE REFRESH
+    // TOKEN (2026-09-19 fix). B7 above kept `refreshToken` alive but left the
+    // still-valid OAuth ACCESS token to be overwritten by `accessToken:
+    // scripted` with no home to move to, and left the old OAuth
+    // `accessExpiresAt` sitting under the new personal token's `accessToken`
+    // - a timestamp that describes a credential no longer in that field. The
+    // merged record's `personal: true` branch in `hostedToken` reads the
+    // OAuth pair from `oauthAccessToken`/`oauthAccessExpiresAt` (added by the
+    // dead-mark fix, same day), never from `accessToken`/`accessExpiresAt`
+    // once `personal: true` - those describe the personal token and only the
+    // personal token. So the still-live OAuth access token has to land there
+    // BEFORE the personal token takes over `accessToken`, or the fallback
+    // finds nothing cached and spends a refresh rotation on a credential that
+    // was already fresh on disk.
+    //
+    // `existing` MAY ALREADY BE A MERGED RECORD (a second `VIEWABLE_BOARD_TOKEN`
+    // login over one written by an earlier such login): its `accessToken` is
+    // already the personal token, not the OAuth one, so moving it into
+    // `oauthAccessToken` here would clobber a live OAuth access token with a
+    // stale personal one. Only a record that was NOT already `personal: true`
+    // has an OAuth access token sitting in the shared `accessToken` field.
+    //
+    // A personal token has no expiry of its own to compare against
+    // (`hostedToken`'s `personal: true` branch never reads `accessExpiresAt`
+    // for it - see that branch's own comment), so `accessExpiresAt` is
+    // cleared rather than left describing the credential it no longer names.
+    const existing = await readAuthFile(env);
+    const keepsOAuth = typeof existing?.refreshToken === "string" && existing.refreshToken !== "";
+    const result = keepsOAuth
+      ? {
+          ...existing,
+          accessToken: scripted,
+          accessExpiresAt: undefined,
+          personal: true,
+          appUrl: base,
+          mcpUrl: `${base}/mcp`,
+          oauthAccessToken: existing.personal === true ? existing.oauthAccessToken : existing.accessToken,
+          oauthAccessExpiresAt: existing.personal === true ? existing.oauthAccessExpiresAt : existing.accessExpiresAt,
+        }
+      : { accessToken: scripted, personal: true, appUrl: base, mcpUrl: `${base}/mcp` };
+    await writeAuthFile(result, env);
+    log(
+      keepsOAuth
+        ? "VIEWABLE_BOARD_TOKEN is set - saved it to ~/.glytch/auth.json as a personal access token, keeping the " +
+            "OAuth sign-in already there beside it. No browser needed."
+        : "VIEWABLE_BOARD_TOKEN is set - saved it to ~/.glytch/auth.json as a personal access token. No browser needed.",
+    );
+    return result;
+  }
+
+  const base = appUrlFrom(appUrl, env);
+
+  // 1. RESOURCE DISCOVERY (RFC 9728). What this login is FOR, and where its
+  // authorization server actually lives - see discoverResource's own comment
+  // for why `${base}/mcp` was never a safe guess. `mcpUrl` is stored as this
+  // resource, so board calls afterwards go to the endpoint the token is
+  // actually valid for; `appUrl` stays `base`, the configured app, for
+  // `/connected` and for the next discovery.
+  const { resource, authorizationServerBase } = await discoverResource(fetchImpl, base, log);
+  const mcpUrl = resource;
+
+  // 2. AUTHORIZATION-SERVER DISCOVERY (RFC 8414), against the server the
+  // resource document named - not necessarily `base`: a local dev app's
+  // protected-resource document still names the PRODUCTION authorization
+  // server, and that is who has to answer this. Board-mcp's own 401 points a
+  // bare bearer through this same two-hop chain (resource_metadata ->
+  // authorization_servers[0] -> this document).
+  const metadata = await fetchJson(fetchImpl, `${authorizationServerBase}/.well-known/oauth-authorization-server`);
+  const { authorization_endpoint, token_endpoint, registration_endpoint } = metadata;
+  if (!authorization_endpoint || !token_endpoint || !registration_endpoint) {
+    throw new Error(`${base}: the authorization-server document is missing an endpoint.`);
+  }
+
+  // 3. THE LOOPBACK SERVER, bound to 127.0.0.1 only (never 0.0.0.0 - this is
+  // where the authorization code lands, and it should not be reachable from
+  // anywhere but this machine), on a random port so two logins never collide.
+  const server = createServer();
+  await new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", resolve);
+  });
+  const port = server.address().port;
+  const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+  try {
+    // 4. DYNAMIC CLIENT REGISTRATION (RFC 7591). Public client - no secret,
+    // PKCE is the whole proof - registered under RUNNER_CLIENT_NAME so
+    // board-oauth's issueTokens recognises this as the bridge's own client and
+    // gives it the longer access-token lifetime a long-running spawned session
+    // needs (see the file header).
+    const registration = await fetchJson(fetchImpl, registration_endpoint, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        client_name: RUNNER_CLIENT_NAME,
+        redirect_uris: [redirectUri],
+        grant_types: ["authorization_code", "refresh_token"],
+        response_types: ["code"],
+        token_endpoint_auth_method: "none",
+      }),
+    });
+    const clientId = registration.client_id;
+    if (typeof clientId !== "string" || clientId === "") {
+      throw new Error(`${registration_endpoint}: registration did not return a client_id.`);
+    }
+
+    // 5. PKCE. 32 random bytes base64url-encoded is 43 characters, exactly the
+    // floor of the S256 verifier length board-oauth's oauth.mjs requires
+    // (43-128, RFC 7636); the challenge is the same encoding of its sha256.
+    const verifier = b64url(randomBytes(32));
+    const challenge = b64url(createHash("sha256").update(verifier).digest());
+    const state = b64url(randomBytes(16));
+
+    const authorizeUrl = new URL(authorization_endpoint);
+    authorizeUrl.searchParams.set("response_type", "code");
+    authorizeUrl.searchParams.set("client_id", clientId);
+    authorizeUrl.searchParams.set("redirect_uri", redirectUri);
+    authorizeUrl.searchParams.set("code_challenge", challenge);
+    authorizeUrl.searchParams.set("code_challenge_method", "S256");
+    authorizeUrl.searchParams.set("state", state);
+    authorizeUrl.searchParams.set("scope", SCOPE);
+    // RFC 8707: names the resource this token is FOR - discovered above, not
+    // guessed from `base` - matched by board-oauth against its own configured
+    // RESOURCE.
+    authorizeUrl.searchParams.set("resource", new URL("/functions/v1/board-runner", mcpUrl).toString());
+
+    log(`Open this URL to sign in to Viewable:\n\n  ${authorizeUrl.toString()}\n`);
+    const opened = openUrl(authorizeUrl.toString());
+    if (!opened) log("Could not open a browser automatically - paste the URL above into one.");
+
+    // 6. WAIT FOR THE REDIRECT. The state check, the code check, the 7.
+    // EXCHANGE (form-encoded, per RFC 6749 - the same shape board-oauth's
+    // readParams accepts from every real client) and writing the credential
+    // all happen inside `exchange`, called from within waitForCallback -
+    // because the loopback's own answer to the browser is a redirect to
+    // `/connected` that has to reflect whichever of those actually happened,
+    // and by the time this call returns the browser already has it.
+    const stored = await waitForCallback(server, {
+      appUrl: base,
+      expectedState: state,
+      timeoutMs,
+      exchangeTimeoutMs,
+      exchange: async (code, { stillWanted = () => true } = {}) => {
+        const tokenResponse = await fetchJson(fetchImpl, token_endpoint, {
+          method: "POST",
+          headers: { "Content-Type": "application/x-www-form-urlencoded" },
+          body: new URLSearchParams({
+            grant_type: "authorization_code",
+            code,
+            redirect_uri: redirectUri,
+            client_id: clientId,
+            code_verifier: verifier,
+            // RFC 8707 again, at the token step: the same resource named on
+            // the authorize URL, not re-derived from `base`.
+            resource: new URL("/functions/v1/board-runner", mcpUrl).toString(),
+          }),
+        });
+        if (typeof tokenResponse.access_token !== "string") {
+          throw new Error(`${token_endpoint}: no access_token in the response.`);
+        }
+        const freshOAuth = {
+          refreshToken: typeof tokenResponse.refresh_token === "string" ? tokenResponse.refresh_token : null,
+          appUrl: base,
+          mcpUrl,
+          clientId,
+          tokenEndpoint: token_endpoint,
+        };
+        const freshAccessExpiresAt = now() + Math.max(0, Number(tokenResponse.expires_in) || 0) * 1000;
+        // THE REVERSE MERGE (2026-09-19 fix). `glytch login` over an existing
+        // STORED PERSONAL TOKEN (`VIEWABLE_BOARD_TOKEN`, brief 43) must keep
+        // that token rather than discarding it - the same shape the other
+        // direction (B7, above) keeps: `accessToken`/`personal: true` name
+        // the personal credential, `oauthAccessToken`/`oauthAccessExpiresAt`
+        // name this fresh OAuth pair's access token, and `refreshToken` /
+        // `clientId` / `tokenEndpoint` sit at the top level either way. A
+        // personal record with no OAuth pair yet reads `existing.personal`
+        // straight; one already merged (a second `glytch login` refreshing
+        // the OAuth side of a record `VIEWABLE_BOARD_TOKEN` already merged
+        // into) hits the same branch, since it is still `personal: true`.
+        const existing = await readAuthFile(env);
+        const keepsPersonal = existing?.personal === true && typeof existing.accessToken === "string" && existing.accessToken !== "";
+        const result = keepsPersonal
+          ? {
+              ...existing,
+              ...freshOAuth,
+              personal: true,
+              accessToken: existing.accessToken,
+              accessExpiresAt: existing.accessExpiresAt,
+              oauthAccessToken: tokenResponse.access_token,
+              oauthAccessExpiresAt: freshAccessExpiresAt,
+            }
+          : { ...freshOAuth, accessToken: tokenResponse.access_token, accessExpiresAt: freshAccessExpiresAt };
+        // NOTHING LANDS ON DISK AFTER THIS LOGIN HAS ALREADY FAILED (F2). A
+        // bound that fired, or a server error, rejects the caller while this
+        // round trip is still in the air; writing the credential afterwards
+        // would leave a machine signed in by a command that said it was not.
+        if (!stillWanted()) {
+          throw new Error("The sign-in finished after this login had already given up. Run `viewable login` again.");
+        }
+        await writeAuthFile(result, env);
+        // THE HUMAN ACT THE DEAD MARK ASKS FOR HAS HAPPENED (2026-09-13), so
+        // the OAuth mark goes, unconditionally - a new grant means this
+        // credential is no longer the one any live mark describes. The
+        // PERSONAL mark, if this was a reverse merge, is left alone: the
+        // personal token kept alongside was not replaced by this sign-in, so
+        // whatever `PERSONAL_TOKEN_REJECTED_HINT` already said about it still
+        // stands (2026-09-19 fix - see `keepsPersonal` above).
+        await clearDeadMark(env, keepsPersonal ? "oauth" : undefined);
+        return result;
+      },
+    });
+    return stored;
+  } finally {
+    // waitForCallback already closes the server on its own path; this covers
+    // every earlier throw (discovery, registration, PKCE) where it never got
+    // that far.
+    server.close();
+  }
+}