@mathismeadows/roamer-device-auth 1.3.1 → 1.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mathismeadows/roamer-device-auth",
-  "version": "1.3.1",
+  "version": "1.4.0",
   "private": false,
   "mcpName": "com.mathismeadows/roamer-mcp",
   "type": "module",

package/roamer-device-auth.mjs

@@ -20,6 +20,18 @@
 // package — roamer-bridge.sh (here and in roamer-mcp-plugin) invokes the published,
 // version-pinned package via npx rather than running this file in place.
 //
+// AUTH-51: every cached credential is namespaced per connecting MCP client, not shared
+// machine-wide. Before this, one interactive sign-in (say, from Claude Code) silently
+// authenticated every other local MCP host that later spawned this same bridge (e.g.
+// Cursor) — no re-consent, no visibility, no way to revoke one without the other. Root
+// cause and full context: spec item AUTH-51. Client identity comes from the `clientInfo.name`
+// an MCP host sends in its own `initialize` request — the only client-identifying signal
+// the stdio transport offers. This is NOT a security boundary (any local process can
+// fabricate that name, or read these cache files directly — same-account processes always
+// can) — see AUTH-51's explicit non-goal. Its job is stopping *accidental* sharing between
+// distinct, legitimate MCP hosts, and making any reuse of a cached session visible via an OS
+// notification rather than silent.
+//
 // stdout is reserved for the JSON-RPC protocol channel; all logging goes to stderr.
 
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
@@ -48,15 +60,16 @@ const ROAMER_MCP_URL = process.env.ROAMER_MCP_URL ?? "https://roamer-mcp.mathism
 const ROAMER_MCP_ORIGIN = new URL(ROAMER_MCP_URL).origin;
 
 const CACHE_DIR = join(homedir(), ".mcp-auth-device");
-const CACHE_FILE = join(CACHE_DIR, "roamer_tokens.json");
-const PENDING_FILE = join(CACHE_DIR, "roamer_pending.json");
 
-// AUTH-14: the loopback flow's own independent cache — never assumed interchangeable with
-// the device-code cache above, matching this file's existing precedent of not trusting a
-// differently-obtained cache just because it happens to share field names (see
-// CACHE_VERSION's own comment on the mcp-remote-era predecessor of that exact mistake).
-const LOOPBACK_TOKENS_FILE = join(CACHE_DIR, "roamer_loopback_tokens.json");
-const LOOPBACK_CLIENT_FILE = join(CACHE_DIR, "roamer_loopback_client.json");
+// AUTH-51: every on-disk cache is namespaced per client slug — a null slug (the connecting
+// host sent no usable clientInfo.name) means "never persist": the caller gets a real
+// interactive sign-in on every single invocation instead of falling into any shared
+// catch-all bucket, which would just recreate the bug this item fixes for a smaller
+// population of clients.
+function cacheFilePath(baseName, clientSlug) {
+  if (!clientSlug) return null;
+  return join(CACHE_DIR, `${baseName}__${clientSlug}.json`);
+}
 
 // Bumped whenever the cached shape changes meaningfully. A cache written by a prior
 // mechanism (e.g. the retired Entra-direct flow, AUTH-11/14) happens to share field names
@@ -77,6 +90,28 @@ function isAuthError(err) {
   return /invalid_token|unauthorized|\b401\b/i.test(err?.message ?? "");
 }
 
+// AUTH-51: the only client-identifying signal MCP's stdio transport offers — the
+// `clientInfo.name` an MCP host sends in its own `initialize` request, which by protocol is
+// always the very first message a host sends. Deliberately tolerant: any parse failure or
+// missing/blank name just means "no usable identity", never a thrown error — a
+// non-compliant host must degrade gracefully (an uncached, always-fresh sign-in), not crash
+// the bridge.
+function clientSlugFromInitializeLine(line) {
+  try {
+    const message = JSON.parse(line);
+    const name = message?.params?.clientInfo?.name;
+    if (typeof name !== "string" || !name.trim()) return null;
+    const slug = name
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9_-]+/g, "-")
+      .replace(/^-+|-+$/g, "");
+    return slug || null;
+  } catch {
+    return null;
+  }
+}
+
 // A native dialog is an OS-level surface, guaranteed visible independent of whether the MCP
 // host surfaces this process's stderr anywhere a human will see it (confirmed on the old
 // Entra-direct flow: a stderr-only first version left the user with no way to see the code).
@@ -91,9 +126,31 @@ async function showDeviceCodeDialog(verificationUri, userCode) {
   }
 }
 
-async function readCachedTokens() {
+// AUTH-51: fires once per process, only when the token this run ends up using was obtained
+// without any interactive step this time (a cache hit or a silent background refresh) — the
+// exact moment that used to be completely invisible. Deliberately NOT fired for routine
+// mid-session refreshes of an already-visible, already-established session (see forwardLine
+// below) — only for the initial per-process acquisition, so a long-lived connection doesn't
+// spam a notification every time its token happens to roll over.
+async function notifySessionReused(clientSlug) {
+  const label = clientSlug ?? "an unidentified client";
+  const message = `Reused an existing Roamer MCP session for ${label}.`;
   try {
-    const tokens = JSON.parse(await readFile(CACHE_FILE, "utf8"));
+    await execFileAsync("osascript", [
+      "-e",
+      `display notification "${message.replace(/"/g, '\\"')}" with title "Roamer MCP"`,
+    ]);
+  } catch {
+    // Best-effort, macOS-only — the stderr log line below is the fallback for every other OS.
+  }
+  log(message);
+}
+
+async function readCachedTokens(clientSlug) {
+  const path = cacheFilePath("roamer_tokens", clientSlug);
+  if (!path) return null;
+  try {
+    const tokens = JSON.parse(await readFile(path, "utf8"));
     // A cache from an incompatible prior format must never be trusted just because it
     // happens to have the right field names — see CACHE_VERSION's comment.
     if (tokens?.cacheVersion !== CACHE_VERSION) return null;
@@ -103,14 +160,18 @@ async function readCachedTokens() {
   }
 }
 
-async function writeCachedTokens(tokens) {
+async function writeCachedTokens(clientSlug, tokens) {
+  const path = cacheFilePath("roamer_tokens", clientSlug);
+  if (!path) return; // AUTH-51: no usable client identity — never persisted.
   await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
   const stamped = { ...tokens, cacheVersion: CACHE_VERSION };
-  await writeFile(CACHE_FILE, JSON.stringify(stamped, null, 2), { mode: 0o600 });
+  await writeFile(path, JSON.stringify(stamped, null, 2), { mode: 0o600 });
 }
 
-function clearCachedTokens() {
-  return writeFile(CACHE_FILE, "{}", { mode: 0o600 }).catch(() => {});
+function clearCachedTokens(clientSlug) {
+  const path = cacheFilePath("roamer_tokens", clientSlug);
+  if (!path) return Promise.resolve();
+  return writeFile(path, "{}", { mode: 0o600 }).catch(() => {});
 }
 
 // AUTH-14/AUTH-38: loopback-flow caches, stamped with the authorization server URL they were
@@ -120,9 +181,11 @@ function clearCachedTokens() {
 // discovery documents from Cloudflare Access Managed OAuth to RoamerMcp's own AS, and a client_id
 // or token cached from before that change would otherwise be silently carried forward and
 // presented to a completely different issuer with no invalidation at all.
-async function readLoopbackTokens(issuerUrl) {
+async function readLoopbackTokens(clientSlug, issuerUrl) {
+  const path = cacheFilePath("roamer_loopback_tokens", clientSlug);
+  if (!path) return null;
   try {
-    const tokens = JSON.parse(await readFile(LOOPBACK_TOKENS_FILE, "utf8"));
+    const tokens = JSON.parse(await readFile(path, "utf8"));
     if (tokens?.issuerUrl !== issuerUrl) return null;
     return tokens?.access_token ? tokens : null;
   } catch {
@@ -130,22 +193,28 @@ async function readLoopbackTokens(issuerUrl) {
   }
 }
 
-async function writeLoopbackTokens(tokens, issuerUrl) {
+async function writeLoopbackTokens(clientSlug, tokens, issuerUrl) {
+  const path = cacheFilePath("roamer_loopback_tokens", clientSlug);
+  if (!path) return; // AUTH-51: no usable client identity — never persisted.
   await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
   const stamped = { ...tokens, issuerUrl };
-  await writeFile(LOOPBACK_TOKENS_FILE, JSON.stringify(stamped, null, 2), { mode: 0o600 });
+  await writeFile(path, JSON.stringify(stamped, null, 2), { mode: 0o600 });
 }
 
-function clearLoopbackTokens() {
-  return writeFile(LOOPBACK_TOKENS_FILE, "{}", { mode: 0o600 }).catch(() => {});
+function clearLoopbackTokens(clientSlug) {
+  const path = cacheFilePath("roamer_loopback_tokens", clientSlug);
+  if (!path) return Promise.resolve();
+  return writeFile(path, "{}", { mode: 0o600 }).catch(() => {});
 }
 
 // DCR'd client registration is reused across runs — the authorization server's
 // registration_endpoint has no reason to be hit on every single sign-in, only the first one (or
 // after a reset, or after an issuer change per this function's own issuerUrl check above).
-async function readLoopbackClientInfo(issuerUrl) {
+async function readLoopbackClientInfo(clientSlug, issuerUrl) {
+  const path = cacheFilePath("roamer_loopback_client", clientSlug);
+  if (!path) return null;
   try {
-    const info = JSON.parse(await readFile(LOOPBACK_CLIENT_FILE, "utf8"));
+    const info = JSON.parse(await readFile(path, "utf8"));
     if (info?.issuerUrl !== issuerUrl) return null;
     return info?.client_id ? info : null;
   } catch {
@@ -153,10 +222,12 @@ async function readLoopbackClientInfo(issuerUrl) {
   }
 }
 
-async function writeLoopbackClientInfo(info, issuerUrl) {
+async function writeLoopbackClientInfo(clientSlug, info, issuerUrl) {
+  const path = cacheFilePath("roamer_loopback_client", clientSlug);
+  if (!path) return; // AUTH-51: no usable client identity — never persisted.
   await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
   const stamped = { ...info, issuerUrl };
-  await writeFile(LOOPBACK_CLIENT_FILE, JSON.stringify(stamped, null, 2), { mode: 0o600 });
+  await writeFile(path, JSON.stringify(stamped, null, 2), { mode: 0o600 });
 }
 
 // AUTH-14: which auth mechanism a given machine uses. Safari-default clients (macOS only —
@@ -165,7 +236,7 @@ async function writeLoopbackClientInfo(info, issuerUrl) {
 // non-macOS platform (no Launch Services plist to query, so this always reports "unknown"
 // there — correctly falling through to the loopback path), takes the lighter direct
 // redirect. ROAMER_MCP_AUTH_FLOW overrides detection entirely — used by this file's own
-// test suite to pin a deterministic path regardless of the CI machine's real OS/browser.
+// test suite to pin a deterministic path regardless of the CI runner's real OS/default browser.
 async function detectDefaultBrowser() {
   const override = process.env.ROAMER_MCP_AUTH_FLOW;
   if (override === "device-code") return "com.apple.safari";
@@ -193,9 +264,11 @@ async function detectDefaultBrowser() {
 // user_code — the user would see a different code every single retry, forever, with no
 // path to ever actually finish signing in. Confirmed live 2026-08-21. Persisting the
 // pending flow means a respawned process resumes polling the SAME still-valid code instead.
-async function readPendingFlow() {
+async function readPendingFlow(clientSlug) {
+  const path = cacheFilePath("roamer_pending", clientSlug);
+  if (!path) return null;
   try {
-    const pending = JSON.parse(await readFile(PENDING_FILE, "utf8"));
+    const pending = JSON.parse(await readFile(path, "utf8"));
     if (!pending?.device_code || Date.now() > pending.expiresAt) return null;
     return pending;
   } catch {
@@ -203,15 +276,19 @@ async function readPendingFlow() {
   }
 }
 
-async function writePendingFlow(device) {
+async function writePendingFlow(clientSlug, device) {
+  const path = cacheFilePath("roamer_pending", clientSlug);
+  if (!path) return device; // AUTH-51: no usable client identity — never persisted.
   await mkdir(CACHE_DIR, { recursive: true, mode: 0o700 });
   const pending = { ...device, expiresAt: Date.now() + device.expires_in * 1000 };
-  await writeFile(PENDING_FILE, JSON.stringify(pending, null, 2), { mode: 0o600 });
+  await writeFile(path, JSON.stringify(pending, null, 2), { mode: 0o600 });
   return pending;
 }
 
-function clearPendingFlow() {
-  return writeFile(PENDING_FILE, "{}", { mode: 0o600 }).catch(() => {});
+function clearPendingFlow(clientSlug) {
+  const path = cacheFilePath("roamer_pending", clientSlug);
+  if (!path) return Promise.resolve();
+  return writeFile(path, "{}", { mode: 0o600 }).catch(() => {});
 }
 
 function expiresSoon(tokens) {
@@ -271,21 +348,28 @@ async function pollDeviceFlow(deviceCode, intervalSeconds) {
 // their own competing flow — worst case that means multiple device-code dialogs popping up
 // at once, or two refreshes racing on a rotating refresh_token where the loser's retry then
 // forces an unnecessary full sign-in. All concurrent callers await the same in-flight op.
+// AUTH-51: still a single (not per-client) in-flight guard — a given process only ever
+// resolves one clientSlug for its whole lifetime, decided once at startup, so there's never
+// more than one client's flow in flight within a single process anyway.
 let inFlightTokens = null;
 
-function getValidTokens(forceRefresh = false) {
+function getValidTokens(clientSlug, forceRefresh = false) {
   if (inFlightTokens) return inFlightTokens;
-  inFlightTokens = doGetValidTokens(forceRefresh).finally(() => {
+  inFlightTokens = doGetValidTokens(clientSlug, forceRefresh).finally(() => {
     inFlightTokens = null;
   });
   return inFlightTokens;
 }
 
-async function doGetValidTokens(forceRefresh) {
-  let tokens = forceRefresh ? null : await readCachedTokens();
+// AUTH-51: returns { tokens, reusedSilently } — reusedSilently is true only when no
+// interactive step ran this call (a valid cache hit or a silent refresh-token refresh),
+// which is exactly the case that used to be invisible and is now what triggers
+// notifySessionReused in main().
+async function doGetValidTokens(clientSlug, forceRefresh) {
+  let tokens = forceRefresh ? null : await readCachedTokens(clientSlug);
 
   if (!forceRefresh && tokens?.access_token && !expiresSoon(tokens)) {
-    return tokens;
+    return { tokens, reusedSilently: true };
   }
 
   if (!forceRefresh && tokens?.refresh_token) {
@@ -293,23 +377,23 @@ async function doGetValidTokens(forceRefresh) {
       log("Refreshing cached token...");
       const fresh = await refreshTokens(tokens.refresh_token);
       tokens = { ...fresh, obtained_at: Date.now() };
-      await writeCachedTokens(tokens);
-      return tokens;
+      await writeCachedTokens(clientSlug, tokens);
+      return { tokens, reusedSilently: true };
     } catch (err) {
       log(`Refresh failed (${err.message}), falling back to a fresh sign-in.`);
     }
   }
 
-  if (forceRefresh) await clearCachedTokens();
+  if (forceRefresh) await clearCachedTokens(clientSlug);
 
   // Resume an already-in-progress flow (from a process this host killed and respawned)
   // instead of minting a new device_code the user would have to start over for.
-  let device = await readPendingFlow();
+  let device = await readPendingFlow(clientSlug);
   let resuming = Boolean(device);
   if (!resuming) {
     log("Starting sign-in...");
     device = await startDeviceFlow();
-    await writePendingFlow(device);
+    await writePendingFlow(clientSlug, device);
   } else {
     log("Resuming an already-in-progress sign-in (a prior process was restarted before it finished)...");
   }
@@ -339,15 +423,15 @@ async function doGetValidTokens(forceRefresh) {
   try {
     const fresh = await pollDeviceFlow(device.device_code, device.interval ?? 5);
     tokens = { ...fresh, obtained_at: Date.now() };
-    await writeCachedTokens(tokens);
-    await clearPendingFlow();
+    await writeCachedTokens(clientSlug, tokens);
+    await clearPendingFlow(clientSlug);
     log("Sign-in complete.");
-    return tokens;
+    return { tokens, reusedSilently: false };
   } catch (err) {
     // A hard failure (expired/denied, not just this process being killed) means the pending
     // code is genuinely dead — clear it so the next attempt starts a real fresh one instead
     // of retrying a code that will never succeed.
-    await clearPendingFlow();
+    await clearPendingFlow(clientSlug);
     throw err;
   }
 }
@@ -358,6 +442,9 @@ async function doGetValidTokens(forceRefresh) {
 // stable across runs. A fixed port sidesteps re-registering on every single interactive
 // sign-in; the tradeoff (a port-in-use conflict is possible, if rare) is the same one this
 // project's original AUTH-11/AUTH-14 mcp-remote-based flow already lived with for months.
+// AUTH-51: this is a pre-existing, unrelated limitation — two different MCP hosts both
+// needing a fresh interactive loopback sign-in at literally the same moment would still
+// race on this one port, same as two runs of the same client already could before this fix.
 const LOOPBACK_PORT = Number(process.env.ROAMER_MCP_OAUTH_PORT ?? 38271);
 const LOOPBACK_REDIRECT_URI = `http://127.0.0.1:${LOOPBACK_PORT}/callback`;
 
@@ -415,56 +502,61 @@ async function discoverLoopbackServerInfo() {
 // of the two mechanisms is ever active in a given process (see detectDefaultBrowser).
 let inFlightLoopbackTokens = null;
 
-function getValidTokensLoopback(forceRefresh = false) {
+function getValidTokensLoopback(clientSlug, forceRefresh = false) {
   if (inFlightLoopbackTokens) return inFlightLoopbackTokens;
-  inFlightLoopbackTokens = doGetValidTokensLoopback(forceRefresh).finally(() => {
+  inFlightLoopbackTokens = doGetValidTokensLoopback(clientSlug, forceRefresh).finally(() => {
     inFlightLoopbackTokens = null;
   });
   return inFlightLoopbackTokens;
 }
 
-async function doGetValidTokensLoopback(forceRefresh) {
+// AUTH-51: returns { tokens, reusedSilently } — see doGetValidTokens's comment above, same
+// contract for the loopback mechanism.
+async function doGetValidTokensLoopback(clientSlug, forceRefresh) {
   // AUTH-38: discovery has to run before any cached token/client is trusted, not after — a
   // cached-but-not-yet-expired token from a prior authorization server would otherwise be
   // returned early below without ever learning the issuer changed underneath it.
   const serverInfo = await discoverLoopbackServerInfo();
   const issuerUrl = serverInfo.authorizationServerUrl.toString();
 
-  let tokens = forceRefresh ? null : await readLoopbackTokens(issuerUrl);
+  let tokens = forceRefresh ? null : await readLoopbackTokens(clientSlug, issuerUrl);
 
   if (!forceRefresh && tokens?.access_token && !expiresSoon(tokens)) {
-    return tokens;
+    return { tokens, reusedSilently: true };
   }
 
-  let clientInformation = await readLoopbackClientInfo(issuerUrl);
+  let clientInformation = await readLoopbackClientInfo(clientSlug, issuerUrl);
 
   if (!forceRefresh && tokens?.refresh_token && clientInformation) {
     try {
       log("Refreshing cached token...");
       const fresh = await refreshLoopbackTokens(tokens.refresh_token, serverInfo, clientInformation);
       tokens = { ...fresh, obtained_at: Date.now() };
-      await writeLoopbackTokens(tokens, issuerUrl);
-      return tokens;
+      await writeLoopbackTokens(clientSlug, tokens, issuerUrl);
+      return { tokens, reusedSilently: true };
     } catch (err) {
       log(`Refresh failed (${err.message}), falling back to a fresh sign-in.`);
     }
   }
 
-  if (forceRefresh) await clearLoopbackTokens();
+  if (forceRefresh) await clearLoopbackTokens(clientSlug);
 
   if (!clientInformation) {
     log("Registering as a new OAuth client...");
+    // AUTH-51: the registered client_name carries the connecting client's own identity when
+    // known, so a future server-side session list/audit view could actually tell clients
+    // apart instead of seeing the same generic name for every stdio-bridge user.
     clientInformation = await registerClient(serverInfo.authorizationServerUrl, {
       metadata: serverInfo.authorizationServerMetadata,
       clientMetadata: {
-        client_name: "Roamer MCP (stdio bridge)",
+        client_name: clientSlug ? `Roamer MCP (stdio bridge — ${clientSlug})` : "Roamer MCP (stdio bridge)",
         redirect_uris: [LOOPBACK_REDIRECT_URI],
         grant_types: ["authorization_code", "refresh_token"],
         response_types: ["code"],
         token_endpoint_auth_method: "none",
       },
     });
-    await writeLoopbackClientInfo(clientInformation, issuerUrl);
+    await writeLoopbackClientInfo(clientSlug, clientInformation, issuerUrl);
   }
 
   log("Starting sign-in...");
@@ -517,13 +609,16 @@ async function doGetValidTokensLoopback(forceRefresh) {
     redirectUri: LOOPBACK_REDIRECT_URI,
   });
   tokens = { ...fresh, obtained_at: Date.now() };
-  await writeLoopbackTokens(tokens, issuerUrl);
+  await writeLoopbackTokens(clientSlug, tokens, issuerUrl);
   log("Sign-in complete.");
-  return tokens;
+  return { tokens, reusedSilently: false };
 }
 
 // AUTH-28: extracted so it can run both for live traffic (post-sign-in) and for messages
 // queued while sign-in was still in progress, with identical forwarding/retry behavior.
+// AUTH-51: unchanged — takes a plain getFreshTokens(forceRefresh) => Promise<tokens>
+// function; main() adapts the new { tokens, reusedSilently }-returning, clientSlug-aware
+// functions above into that shape rather than changing this function's own contract.
 async function forwardLine(transport, line, getTokens, setTokens, getFreshTokens) {
   try {
     let tokens = getTokens();
@@ -577,6 +672,15 @@ async function main() {
   let ready = false;
   const pendingLines = [];
 
+  // AUTH-51: which client is asking, resolved once from the first stdin line (the MCP
+  // `initialize` request, always message #1 by protocol) before any credential is touched.
+  let clientSlug = null;
+  let slugResolved = false;
+  let resolveFirstLine;
+  const firstLine = new Promise((resolve) => {
+    resolveFirstLine = resolve;
+  });
+
   const getTokens = () => tokens;
   const setTokens = (fresh) => {
     tokens = fresh;
@@ -586,8 +690,9 @@ async function main() {
   // only consumer) never runs before `ready` flips true, which itself never happens before
   // these are set, so deferring the assignment past the listener attach is safe and keeps
   // AUTH-28's guarantee (listener attaches before any await) intact.
-  let getFreshTokens;
-  let clearFreshTokens;
+  let getFreshTokens; // (clientSlug, forceRefresh) => Promise<{ tokens, reusedSilently }>
+  let clearFreshTokens; // () => Promise<void>
+  let freshTokensForForward; // (forceRefresh) => Promise<tokens> — forwardLine's plain-tokens contract
 
   let buffer = "";
   process.stdin.setEncoding("utf8");
@@ -598,8 +703,13 @@ async function main() {
       const line = buffer.slice(0, newlineIndex);
       buffer = buffer.slice(newlineIndex + 1);
       if (!line.trim()) continue;
+      if (!slugResolved) {
+        slugResolved = true;
+        clientSlug = clientSlugFromInitializeLine(line);
+        resolveFirstLine();
+      }
       if (ready) {
-        forwardLine(transport, line, getTokens, setTokens, getFreshTokens);
+        forwardLine(transport, line, getTokens, setTokens, freshTokensForForward);
       } else {
         pendingLines.push(line);
       }
@@ -614,16 +724,29 @@ async function main() {
 
   log("Local STDIO proxy running. Press Ctrl+C to exit.");
 
+  // AUTH-51: wait for that first line before authenticating, so the credential this process
+  // obtains is scoped to the right client. Safe alongside AUTH-28's no-silence guarantee —
+  // the listener above is already attached and queuing by this point, and a well-behaved
+  // host sends `initialize` immediately on spawn with nothing required from this process
+  // first, so this wait adds no meaningful latency and never reintroduces the
+  // respond-before-timeout gap AUTH-28 fixed.
+  await firstLine;
+  log(clientSlug ? `Client identified as "${clientSlug}".` : "No usable client identity sent — this sign-in will not be cached for reuse.");
+
   // AUTH-14: decided once per process — detectDefaultBrowser() shells out to Launch
   // Services, no need to re-check mid-session. Safari-default machines keep using the
   // existing device-code mechanism (AUTH-25); everything else uses the lighter loopback
   // redirect, including refreshes and reactive re-auth below.
   const isSafari = (await detectDefaultBrowser()) === "com.apple.safari";
   getFreshTokens = isSafari ? getValidTokens : getValidTokensLoopback;
-  clearFreshTokens = isSafari ? clearCachedTokens : clearLoopbackTokens;
+  clearFreshTokens = () => (isSafari ? clearCachedTokens(clientSlug) : clearLoopbackTokens(clientSlug));
+  freshTokensForForward = (force) => getFreshTokens(clientSlug, force).then((result) => result.tokens);
 
+  let reusedSilently = false;
   try {
-    tokens = await getFreshTokens();
+    const result = await getFreshTokens(clientSlug);
+    tokens = result.tokens;
+    reusedSilently = result.reusedSilently;
   } catch (err) {
     // Sign-in genuinely failed (denied/expired), not just slow — every message queued while
     // we waited, starting with `initialize`, gets a real JSON-RPC error so the host sees an
@@ -633,6 +756,10 @@ async function main() {
     process.exit(1);
   }
 
+  // AUTH-51: the moment that used to be completely silent — a process starting up and
+  // immediately using a credential it never interactively obtained this run.
+  if (reusedSilently) await notifySessionReused(clientSlug);
+
   transport = new StreamableHTTPClientTransport(new URL(ROAMER_MCP_URL), {
     requestInit: {
       get headers() {
@@ -660,7 +787,7 @@ async function main() {
 
   ready = true;
   for (const line of pendingLines) {
-    forwardLine(transport, line, getTokens, setTokens, getFreshTokens);
+    forwardLine(transport, line, getTokens, setTokens, freshTokensForForward);
   }
 }
 
@@ -681,6 +808,12 @@ export {
   respondWithSignInError,
   forwardLine,
   detectDefaultBrowser,
+  clientSlugFromInitializeLine,
+  readCachedTokens,
+  writeCachedTokens,
+  clearCachedTokens,
+  readPendingFlow,
+  writePendingFlow,
   readLoopbackTokens,
   writeLoopbackTokens,
   readLoopbackClientInfo,