ccdeck 3.28.1 → 3.29.0

package/src/server/account-health.mjs

@@ -0,0 +1,38 @@
+/** A collector's verdict is about the stored copy, not the live CLI session.
+ * In particular, an inaccessible Keychain does not make the stored copy dead:
+ * treating it as dead starts a futile peer-healing loop on every LAN round. */
+const LOST_COPY = new Set(["no_credentials", "relogin_required", "foreign_credential"]);
+
+export function storedCopyAlive(alive, verdict) {
+  // An unreadable keychain or a deferred token refresh is a failure to CHECK,
+  // not evidence that the stored login has died. Do not repeatedly overwrite
+  // that slot with copies from a peer while the check is unavailable.
+  if (verdict === "keychain_unavailable" || verdict === "token_expired") return true;
+  return alive === true && !LOST_COPY.has(verdict);
+}
+
+/** When a collector verdict is present, only `ok` is positive export evidence.
+ * Unknown and transient verdict strings are therefore fail-closed. */
+export function exportVerdictOk(verdict) {
+  return verdict === "ok";
+}
+
+/** Cached preflight for the LAN hot path. A KNOWN bad or unknown verdict is
+ * refused before spawning an export. An inactive slot with no verdict may reach
+ * the bounded export itself: it exports the stored copy, which carries the
+ * slot's own identity. The ACTIVE slot may not, because its export is the live
+ * CLI login, which can belong to another account or be expired while the
+ * blob's labels still name the slot, so the identity check cannot catch it.
+ * Its verdict is refreshed in the background and the next round shares it. */
+export function cachedExportReadable(verdict, { active = false } = {}) {
+  if (verdict == null) return !active;
+  return exportVerdictOk(verdict);
+}
+
+/** Is the live CLI login the account this slot names? The active slot exports
+ * the live login, and a verdict can predate a `/login` as somebody else. */
+export function liveLoginIs(identity, email, org) {
+  const live = String(identity?.email ?? "").trim().toLowerCase();
+  if (!live || live !== String(email ?? "").trim().toLowerCase()) return false;
+  return !identity.orgId || !org || identity.orgId === org;
+}

package/src/server/claude-accounts.mjs

@@ -16,6 +16,7 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { cswapBin, cswapVersion, installHint } from "./cswap-install.mjs";
 import { run, runDetached } from "./exec.mjs";
+import { storedCopyAlive } from "./account-health.mjs";
 // The CLI identity oracle, already written and already trusted by the account
 // admin routes. #721 needs the same answer, so it reuses the same function
 // rather than shelling out a second way to ask one question.
@@ -347,14 +348,39 @@ export function nextReadAt(row, matches, fetchedAtMs, isActive, now) {
  * for `--json` and keeps the verdicts. Still not awaited by anyone — the nudge
  * stays synchronous for its callers — and still one child at a time.
  */
-let _verdicts = { at: 0, byNum: {} };
+let _verdicts = { at: 0, byNum: {}, identities: {} };
 /** Stale after this, because a verdict that outlives its cause is worse than no
  *  verdict: "no credentials" under an account somebody has since signed into is
  *  a sentence that sends them to fix what is already fixed. */
 const VERDICT_TTL_MS = 10 * 60_000;
-/** One `cswap list --json` at a time. A collection can take a while on a cold
- *  network, and a nudge landing inside one must not start a second. */
-let _verdictInFlight = false;
+/** Run one `cswap list --json` at a time. A post-write question must start
+ * after any older collection has finished; routine readers can share the
+ * latest pending answer without starting another slow collection. */
+export function createVerdictQueue(collect) {
+  let pending = null;
+  return {
+    ask({ fresh = false } = {}) {
+      if (pending && !fresh) return pending;
+      const previous = pending;
+      // Start the first poll immediately: requestCollection promises the UI that
+      // its refresh has started before it returns. Only subsequent fresh polls
+      // wait for the earlier snapshot to finish.
+      let next;
+      if (previous) next = previous.then(collect, collect);
+      else {
+        try { next = Promise.resolve(collect()); }
+        catch (error) { next = Promise.reject(error); }
+      }
+      pending = next;
+      void next.then(
+        () => { if (pending === next) pending = null; },
+        () => { if (pending === next) pending = null; },
+      );
+      return next;
+    },
+    busy() { return pending !== null; },
+  };
+}
 
 /**
  * Ask claude-swap about one account RIGHT NOW, rather than reading the cache.
@@ -374,6 +400,20 @@ let _verdictInFlight = false;
 export async function verdictNow(email, org, { runner = run, bin = cswapBin } = {}) {
   const want = String(email ?? "").trim().toLowerCase();
   if (!want) return null;
+  const all = await verdictsNow({ runner, bin, fresh: true });
+  return all?.find(a => a.email === want && a.org === (org ?? ""))?.status ?? null;
+}
+
+/**
+ * Every account's verdict from ONE `cswap list --json`, as `{ email, org,
+ * status, active }` rows (email lower-cased, status null when claude-swap gave none),
+ * or null when the question could not be asked at all.
+ *
+ * For a caller holding several identities at once — a round that imported
+ * three logins asks once, not three times, since each ask is a full usage
+ * collection that can take a minute on a cold network.
+ */
+async function collectVerdicts({ runner, bin }) {
   try {
     const out = await runner(await bin(), ["list", "--json"], { timeout: VERDICT_TIMEOUT_MS });
     if (!out?.ok) return null;
@@ -381,20 +421,47 @@ export async function verdictNow(email, org, { runner = run, bin = cswapBin } =
     // The same freshly-read answer feeds the cache the panel draws from, since
     // it cost a subprocess either way.
     const byNum = readVerdicts(out.stdout);
-    if (Object.keys(byNum).length) _verdicts = { at: Date.now(), byNum };
+    const identities = {};
     for (const a of Array.isArray(d?.accounts) ? d.accounts : []) {
-      if (String(a?.email ?? "").trim().toLowerCase() !== want) continue;
-      if ((a?.organizationUuid ?? "") !== (org ?? "")) continue;
-      return typeof a?.usageStatus === "string" ? a.usageStatus : null;
+      if (Number.isInteger(a?.number) && typeof a?.email === "string" && a.email.trim()) {
+        identities[String(a.number)] = `${a.email.trim().toLowerCase()}@@${a.organizationUuid ?? ""}`;
+      }
     }
-    return null;
+    _verdicts = { at: Date.now(), byNum, identities };
+    return (Array.isArray(d?.accounts) ? d.accounts : []).map(a => ({
+      number: a?.number,
+      email: String(a?.email ?? "").trim().toLowerCase(),
+      org: a?.organizationUuid ?? "",
+      status: typeof a?.usageStatus === "string" ? a.usageStatus : null,
+      // For the account Claude Code is signed in as, claude-swap reads the
+      // LIVE credential, not the stored copy — so its verdict there is about
+      // the live login. See checkImports.
+      active: a?.active === true,
+    }));
   } catch { return null; }
 }
 
+const verdictQueue = createVerdictQueue(() => collectVerdicts({ runner: run, bin: cswapBin }));
+
+/** Routine readers share a collection; post-write callers wait for any older
+ * collection and start a new one, so they never inspect the pre-write store. */
+export function verdictsNow({ runner = run, bin = cswapBin, fresh = false } = {}) {
+  // Tests and callers supplying their own runner must receive their own answer.
+  if (runner !== run || bin !== cswapBin) return collectVerdicts({ runner, bin });
+  return verdictQueue.ask({ fresh });
+}
+
 /** claude-swap's verdict for a slot, or null when there is none fresh enough. */
-function verdictFor(num, now) {
-  if (now - _verdicts.at > VERDICT_TTL_MS) return null;
-  const v = _verdicts.byNum[String(num)];
+function verdictFor(num, now, email, org) {
+  return cachedVerdictFor(_verdicts, num, now, email, org);
+}
+
+/** Only attach a cached slot verdict to the identity it was collected for. */
+export function cachedVerdictFor(cache, num, now, email, org) {
+  if (now - cache.at > VERDICT_TTL_MS) return null;
+  const identity = `${String(email ?? "").trim().toLowerCase()}@@${org ?? ""}`;
+  if (cache.identities[String(num)] !== identity) return null;
+  const v = cache.byNum[String(num)];
   return typeof v === "string" && v !== "" ? v : null;
 }
 
@@ -439,22 +506,12 @@ function nudgeCollector(rows, slots, now, activeNum) {
     cswapBin().then(bin => runDetached(bin, ["auto", "--once", "--dry-run", "--json"])).catch(() => {});
     return;
   }
-  if (_verdictInFlight) return;
-  _verdictInFlight = true;
+  if (verdictQueue.busy()) return;
   // Fire-and-forget: this function is deliberately synchronous so callers never
   // wait on it, and resolving the binary is the only async part. `run` rather
   // than `runDetached` only so the output can be read; the caller is no more
   // aware of it than before.
-  cswapBin()
-    .then(bin => run(bin, ["list", "--json"], { timeout: VERDICT_TIMEOUT_MS }))
-    .then(out => {
-      const byNum = out?.ok ? readVerdicts(out.stdout) : {};
-      // Replaced whole rather than merged. A slot that has gone away must not
-      // keep the verdict it had when it was last seen.
-      if (Object.keys(byNum).length) _verdicts = { at: Date.now(), byNum };
-    })
-    .catch(() => {})
-    .finally(() => { _verdictInFlight = false; });
+  void verdictsNow();
 }
 
 /** Long enough for a cold collection over a slow network, short enough that a
@@ -637,6 +694,7 @@ async function readRoster(now, gen) {
         .filter(Boolean),
     ].filter(Boolean);
 
+    const collector = verdictFor(num, now, acct.email, acct.organizationUuid);
     accounts.push({
       num:      Number(num),
       email:    acct.email ?? null,
@@ -654,7 +712,7 @@ async function readRoster(now, gen) {
       // `stale-copy` row means the live session is fine while the copy in the
       // store is dead, and the copy is what a share would carry and what a
       // peer's copy would heal. So both kinds of trouble read as not alive.
-      alive:    trouble == null,
+      alive:    storedCopyAlive(trouble == null, collector),
       active:   String(seq.activeAccountNumber) === num,
       disabled: acct.disabled === true,
       lanes,
@@ -694,7 +752,7 @@ async function readRoster(now, gen) {
       // "no_credentials", "relogin_required", "keychain_unavailable", … It is
       // what turns "not collecting" into a sentence with a next step in it, and
       // it is null on every machine where the collector has not been asked yet.
-      collector: verdictFor(num, now),
+      collector,
     });
   }
 

package/src/server/cswap-admin.mjs

@@ -24,7 +24,8 @@ import { readFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { looksMissing, pathLookup, run, runDetached, runInteractive } from "./exec.mjs";
-import { backupRoot, invalidateClaudeAccountsCache, verdictNow } from "./claude-accounts.mjs";
+import { backupRoot, invalidateClaudeAccountsCache, verdictNow, verdictsNow } from "./claude-accounts.mjs";
+import { HERE } from "./lan-sync.mjs";
 import { withStoreLock } from "./store-lock.mjs";
 import { adminClaudeBin, currentIdentity } from "./claude-identity.mjs";
 import { claudeCliCandidates } from "./claude-dir.mjs";
@@ -35,6 +36,109 @@ import { PRODUCT } from "./brand.mjs";
 // open longer than a user would plausibly take to fetch one.
 const LOGIN_TIMEOUT_MS = 5 * 60_000;
 const CSWAP_TIMEOUT_MS = 60_000;
+// ── whether this process can read what claude-swap holds ────────────────────
+//
+// ASKED OF CLAUDE-SWAP, NEVER READ OFF ITS WORDS. A Keychain it cannot open is
+// logged to its own log file and nowhere else: `cswap export` then says only
+// "no backup credentials found for account N", which is also what an account
+// with no stored login says, and `cswap import` falls back to its .enc file and
+// exits 0. Nothing on stderr tells a locked Keychain apart, so nothing here
+// looks. `cswap list --json` does tell it apart — a per-account `usageStatus`
+// of `keychain_unavailable` — and that is the one signal these read.
+//
+// MACOS ONLY. claude-swap reports `keychain_unavailable` on Linux and Windows
+// as well, for an .enc file it cannot open, and every sentence these feed talks
+// about a Mac's Keychain and a Terminal window.
+
+/** Fresh verdict rows for several identities from one `cswap list --json`, in
+ *  the order asked; null for any claude-swap would not answer for. */
+async function rowsNow(ids, verdicts) {
+  const all = await verdicts({ fresh: true });
+  return ids.map(({ email, org }) => {
+    const want = String(email ?? "").trim().toLowerCase();
+    return all?.find(a => a.email === want && a.org === (org ?? "")) ?? null;
+  });
+}
+
+/**
+ * Why a share came out empty: `keychain_unavailable` when claude-swap says
+ * EVERY account that failed is one this Mac's Keychain will not open, and
+ * `export_failed` otherwise — the reason has to be true of the whole failure,
+ * because the detail printed beside it is.
+ */
+export async function exportFailure(failed, store, { platform = process.platform, verdicts = verdictsNow } = {}) {
+  if (platform !== "darwin" || !failed.length) return "export_failed";
+  const got = await rowsNow(
+    failed.map(f => ({ email: f.email, org: store?.orgs?.[f.num] ?? "" })),
+    verdicts,
+  );
+  // The panel's own copy of the verdicts was just replaced; its cached account
+  // list must not go on drawing the old ones.
+  invalidateClaudeAccountsCache();
+  return got.every(r => r?.status === "keychain_unavailable") ? "keychain_unavailable" : "export_failed";
+}
+
+/** What claude-swap's verdict on a login that just landed means for it here.
+ *  Everything else — `ok`, a transient `unavailable`, an api-key account — is a
+ *  login that arrived and can be read, which is all this is asked. */
+const AFTER_IMPORT = {
+  keychain_unavailable: HERE.unreadable,
+  no_credentials: HERE.noLogin,
+  relogin_required: HERE.expired,
+};
+
+/** A Mac's locally unreadable login cannot be offered to a paired deck. */
+export function markUnreadable(accounts, platform = process.platform) {
+  if (platform !== "darwin" || !Array.isArray(accounts)) return accounts;
+  return accounts.map(a => a.collector === "keychain_unavailable" ? { ...a, readable: false } : a);
+}
+
+/**
+ * The logins a round just imported, checked once from inside this process.
+ *
+ * `cswap import` exiting 0 is not proof: on a Mac it falls back quietly when
+ * the Keychain will not take the write, and a deck started from SSH or a
+ * LaunchAgent may then be unable to read what it holds. One HERE code per
+ * identity (see lan-sync.mjs), or null for one that is fine — and
+ * `HERE.unverified` when claude-swap could not be asked at all, because an
+ * unanswered question is not a yes.
+ *
+ * One `cswap list --json` for the whole round, after it, rather than one per
+ * login inside it: each is a usage collection that can take a minute, and the
+ * peer hangs up on a connection left idle for thirty seconds.
+ *
+ * THE SIGNED-IN ACCOUNT IS READ LIVE. For it, claude-swap's verdict is about the
+ * live login rather than the copy just written, so an expired or missing live
+ * login says nothing about the import and reads as unverified. A Keychain it
+ * cannot open still counts: it is the same Keychain, from the same session.
+ */
+export async function checkImports(ids, { platform = process.platform, verdicts = verdictsNow } = {}) {
+  if (platform !== "darwin" || !ids.length) return ids.map(() => null);
+  const got = await rowsNow(ids, verdicts);
+  return got.map(r => {
+    if (r?.status == null) return HERE.unverified;
+    if (!Object.hasOwn(AFTER_IMPORT, r.status)) return null;
+    return r.active && r.status !== "keychain_unavailable" ? HERE.unverified : AFTER_IMPORT[r.status];
+  });
+}
+
+/**
+ * An import's per-account results, each landed one carrying `check` — its
+ * checkImports code — when this Mac found something wrong with it. For the
+ * Add Account route, which says "imported" per account and was as blind to an
+ * unreadable login as the LAN round was.
+ */
+export async function checkImportResults(results, opts) {
+  const list = Array.isArray(results) ? results : [];
+  const came = list.filter(r => landed([r]));
+  if (!came.length) return list;
+  const codes = await checkImports(came.map(r => ({ email: r.email, org: r.org ?? "" })), opts);
+  return list.map(r => {
+    const code = codes[came.indexOf(r)];
+    return typeof code === "string" ? { ...r, check: code } : r;
+  });
+}
+
 // How long to wait for the CLI's verdict on a pasted code before saying so.
 // Exchanging a code is one HTTPS round trip; a minute is generous.
 const CODE_VERDICT_MS = 60_000;
@@ -889,8 +993,13 @@ export function mergeExports(texts) {
  *
  * The default export shape is used deliberately, never --full, which would
  * embed the entire ~/.claude.json including every project and MCP server.
+ *
+ * `explain: false` skips asking claude-swap why an empty export failed. The
+ * LAN answers a peer that gives up after ten seconds, and that question is a
+ * usage collection that can take a minute; it refreshes the verdict in the
+ * background instead, so the next round's refusal can name the Keychain.
  */
-export async function shareAccounts(nums) {
+export async function shareAccounts(nums, { explain = true } = {}) {
   const asked = Array.isArray(nums) ? nums : [nums];
   // One spawn per account, so the length of this list is a length of time the
   // request holds. A store never has fifty accounts; a caller that sends nine
@@ -939,7 +1048,17 @@ export async function shareAccounts(nums) {
   // Nothing came out at all. There is no partial bundle to hand over, so this
   // is the plain failure the single-account share has always reported.
   if (!texts.length) {
-    return { ok: false, reason: "export_failed", detail: failed[0]?.detail ?? "", failed };
+    if (!explain) {
+      if (process.platform === "darwin") void verdictsNow().then(() => invalidateClaudeAccountsCache(), () => {});
+      return { ok: false, reason: "export_failed", detail: failed[0]?.detail ?? "", failed };
+    }
+    const reason = await exportFailure(failed, store);
+    // failed[0]'s own line would read "no backup credentials found", which
+    // sends somebody to sign in again over a login that is perfectly fine.
+    const detail = reason === "keychain_unavailable"
+      ? `claude-swap could not open this Mac's Keychain — start ${PRODUCT} from a Terminal window on the Mac itself, not over SSH or as a background service`
+      : failed[0]?.detail ?? "";
+    return { ok: false, reason, detail, failed };
   }
 
   const merged = mergeExports(texts);
@@ -1106,7 +1225,7 @@ export function importOutcomes(before, after, wanted, stderr = "") {
  * from here - the fix is a re-login. Requiring the pair is what makes the
  * clobber something a person chose while looking at the address.
  */
-export async function importAccount(blob, { force = false, only = null } = {}) {
+export async function importAccount(blob, { force = false, only = null, collect = true } = {}) {
   const un = unwrapShare(blob);
   if (!un.ok) return { ok: false, reason: un.reason };
 
@@ -1153,7 +1272,10 @@ export async function importAccount(blob, { force = false, only = null } = {}) {
         })();
 
     const arrived = results.filter(x => x.state === "imported");
-    if (arrived.length) runDetached(await cswapBin(), ["list"]);
+    // `collect: false` when a checkImports follows: its `cswap list --json` is
+    // the same collection, and two at once race for one slot's claim, so the
+    // loser reads a fresh slot as `unavailable`.
+    if (arrived.length && collect) runDetached(await cswapBin(), ["list"]);
     return {
       ok: true,
       results,
@@ -1204,14 +1326,20 @@ export async function importAccount(blob, { force = false, only = null } = {}) {
  * would rewrite every matching credential on this machine, and a fresh token
  * replaced by a stale one is not recoverable from here.
  */
-export async function fillEmptySlot(blob, { email, org } = {}) {
+export async function fillEmptySlot(blob, { email, org, platform = process.platform, collect = true } = {}) {
   return withStoreLock(async () => {
     // FIRST STATEMENT INSIDE THE LOCK. Anything awaited before this re-opens
     // the window it exists to close.
     const now = await verdictNow(email, org ?? "");
-    if (now !== "no_credentials") return { ok: false, why: "claude-swap kept the slot it already has" };
+    // THIS LINE IS THE PROTECTION: anything but `no_credentials` — an
+    // unreadable Keychain included, which is an unknown and not an empty slot —
+    // refuses the forced write. The ternary only names which refusal it was,
+    // since "kept the slot it already has" sends nobody to unlock the Mac.
+    if (now !== "no_credentials") {
+      return { ok: false, why: platform === "darwin" && now === "keychain_unavailable" ? HERE.unreadable : "claude-swap kept the slot it already has" };
+    }
 
-    const forced = await importAccount(blob, { force: true, only: { email, org: org ?? "" } });
+    const forced = await importAccount(blob, { force: true, only: { email, org: org ?? "" }, collect });
     if (!forced?.ok) return { ok: false, why: forced?.reason ?? "import refused" };
     // `added` counts `imported` alone, and a forced replace is `healed` — see
     // landed, which is the difference between a repair and a repair reported as

package/src/server/deck-prefs.mjs

@@ -109,6 +109,7 @@ export const DEFAULTS = Object.freeze({
     // network it does not own turns this off in the dialog, in one press.
     autoAsk: true,
     autoAccept: true,
+    pairingMode: "automatic",
     // WHICH ACCOUNT THIS DECK IS ON, told to the decks it is paired with — and
     // only ever one it shares, so an unticked account is never named. On, so two
     // of one person's machines show each other where they are working; off, and
@@ -232,6 +233,7 @@ function normaliseLan(raw) {
     // overrides it, because a truthy string from a hand-edited file is not an
     // answer.
     autoAccept: typeof src.autoAccept === "boolean" ? src.autoAccept : DEFAULTS.lan.autoAccept,
+    pairingMode: src.pairingMode === "invite" ? "invite" : "automatic",
     // Whether paired decks are told which shared account this one is on. Absent
     // is on — the default above — and only a real boolean turns it off.
     shareActive: typeof src.shareActive === "boolean" ? src.shareActive : DEFAULTS.lan.shareActive,

package/src/server/fm-station.mjs

@@ -0,0 +1,186 @@
+// Custom Claude FM stations that live on YouTube (#1208).
+//
+// A station somebody adds by link is played by the browser, never by this
+// process: a direct stream goes into an <audio> element and a YouTube one into
+// the same embed Claude FM uses. The only thing the deck itself does is the
+// lookup below, which turns a `/@handle/live` or `watch?v=` link into the
+// channel and the video the embed needs, because YouTube only says which video
+// a handle is broadcasting in the page it serves.
+//
+// THAT MAKES THIS THE ONE ROUTE WHERE A CALLER NAMES WHAT THE DECK FETCHES, so
+// the link is never fetched as given. It is parsed down to one of three shapes
+// and the request is rebuilt from the parts: https, www.youtube.com, no port,
+// no login, a path this file wrote and an id that matched a strict pattern.
+// A link with a port or a login is refused rather than cleaned, because nobody
+// copies one of those out of a YouTube tab and both change where the request
+// would really go. index.mjs puts the route behind the guarded-read gate too,
+// so a page on another site cannot use it to make the deck call anything.
+const CHANNEL_ID = /^UC[A-Za-z0-9_-]{22}$/;
+const VIDEO_ID = /^[A-Za-z0-9_-]{11}$/;
+const HANDLE = /^[A-Za-z0-9._-]{1,64}$/;
+const YOUTUBE_HOSTS = new Set(["youtube.com", "www.youtube.com", "m.youtube.com"]);
+
+export const FM_STATION_READ_LIMIT = 2_000_000;
+export const FM_STATION_TIMEOUT_MS = 6_000;
+/** How long an answer stands. A station that resolved stays resolved for as
+ *  long as claude-fm.mjs trusts its own live check; one that did not is asked
+ *  again sooner, since "not live" is the answer most likely to change. */
+export const FM_STATION_CACHE_MS = 10 * 60_000;
+export const FM_STATION_MISS_CACHE_MS = 60_000;
+/** Answers kept at once. A deck has a handful of stations; the cap only has to
+ *  stop a caller walking the map up with invented handles. */
+const CACHE_MAX = 32;
+const MAX_REDIRECTS = 5;
+
+const BROWSER_UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/124.0 Safari/537.36";
+const CANONICAL_VIDEO = /<link\s+rel="canonical"\s+href="https:\/\/www\.youtube\.com\/watch\?v=([A-Za-z0-9_-]{11})"/;
+const EXTERNAL_CHANNEL = /"externalChannelId"\s*:\s*"(UC[A-Za-z0-9_-]{22})"/;
+const CHANNEL_URL = /https:\/\/www\.youtube\.com\/channel\/(UC[A-Za-z0-9_-]{22})/;
+
+export function parseYouTubeStationUrl(value) {
+  let url;
+  try { url = new URL(String(value ?? "").trim()); } catch { return null; }
+  if (url.protocol !== "https:") return null;
+  if (url.port || url.username || url.password) return null;
+  if (!YOUTUBE_HOSTS.has(url.hostname.toLowerCase())) return null;
+
+  const channel = /^\/channel\/([^/]+)(?:\/live)?\/?$/.exec(url.pathname)?.[1];
+  if (channel && CHANNEL_ID.test(channel)) {
+    return { kind: "channel", url: `https://www.youtube.com/channel/${channel}/live`, channel };
+  }
+
+  const handle = /^\/@([^/]+)\/live\/?$/.exec(url.pathname)?.[1];
+  if (handle && HANDLE.test(handle)) {
+    return { kind: "handle", url: `https://www.youtube.com/@${handle}/live`, handle };
+  }
+
+  if (url.pathname === "/watch") {
+    const video = url.searchParams.get("v") ?? "";
+    if (VIDEO_ID.test(video)) return { kind: "video", url: `https://www.youtube.com/watch?v=${video}`, video };
+  }
+  return null;
+}
+
+export function readYouTubeStationPage(html) {
+  const page = typeof html === "string" ? html : "";
+  const detailsAt = page.indexOf('"videoDetails"');
+  const details = detailsAt < 0 ? "" : page.slice(detailsAt, detailsAt + 24_000);
+  const live = /"isLiveContent"\s*:\s*true/.test(details) || /"isLive"\s*:\s*true/.test(details);
+  const channel = /"channelId"\s*:\s*"(UC[A-Za-z0-9_-]{22})"/.exec(details)?.[1]
+    ?? EXTERNAL_CHANNEL.exec(page)?.[1]
+    ?? CHANNEL_URL.exec(page)?.[1]
+    ?? null;
+  const video = CANONICAL_VIDEO.exec(page)?.[1] ?? null;
+  return { live, channel, video };
+}
+
+const _cache = new Map();
+const _inflight = new Map();
+
+/** For tests: every answer this process remembers, forgotten. */
+export function forgetFmStations() {
+  _cache.clear();
+  _inflight.clear();
+}
+
+/**
+ * The channel and video a YouTube station link plays, or why it cannot.
+ *
+ * CACHED AND SHARED, the way fetchClaudeFm is. Every canvas that mounts with a
+ * custom station selected asks this, and four open tabs were four page loads
+ * of up to 2MB each from YouTube on every reload; one lookup per link now
+ * answers all of them, and a second caller that arrives while the first is
+ * still reading waits for that same read.
+ */
+export async function resolveYouTubeStation(value, { fetchImpl, now = Date.now } = {}) {
+  const parsed = parseYouTubeStationUrl(value);
+  if (!parsed) return { ok: false, error: "unsupported_url" };
+  if (parsed.kind === "channel") return { ok: true, channel: parsed.channel, video: null };
+
+  const key = parsed.url;
+  const hit = _cache.get(key);
+  if (hit && now() - hit.at < (hit.answer.ok ? FM_STATION_CACHE_MS : FM_STATION_MISS_CACHE_MS)) return hit.answer;
+  const pending = _inflight.get(key);
+  if (pending) return pending;
+
+  const lookup = lookUp(parsed, fetchImpl ?? fetch)
+    .then(answer => {
+      _cache.delete(key);
+      _cache.set(key, { at: now(), answer });
+      // A Map iterates in insertion order, so the first key is the oldest.
+      while (_cache.size > CACHE_MAX) _cache.delete(_cache.keys().next().value);
+      return answer;
+    })
+    .finally(() => { _inflight.delete(key); });
+  _inflight.set(key, lookup);
+  return lookup;
+}
+
+async function lookUp(parsed, get) {
+  try {
+    // Validate every hop before fetching it. Automatic redirects may contact
+    // an arbitrary host before response.url can be inspected (SSRF).
+    const signal = AbortSignal.timeout(FM_STATION_TIMEOUT_MS);
+    let target = parsed.url;
+    let response;
+    for (let redirects = 0; ; redirects++) {
+      if (!isYouTubeHost(target)) return { ok: false, error: "unresolved" };
+      response = await get(target, {
+        headers: { "User-Agent": BROWSER_UA, "Accept-Language": "en-US,en;q=0.9" },
+        signal,
+        redirect: "manual",
+      });
+      // A custom fetch implementation must not silently follow redirects.
+      if (response.url && !isYouTubeHost(response.url)) {
+        try { await response.body?.cancel(); } catch { /* already closed */ }
+        return { ok: false, error: "unresolved" };
+      }
+      if (![301, 302, 303, 307, 308].includes(response.status)) break;
+      const location = response.headers?.get("location");
+      try { await response.body?.cancel(); } catch { /* already closed */ }
+      if (!location || redirects >= MAX_REDIRECTS) return { ok: false, error: "unresolved" };
+      try { target = new URL(location, target).href; }
+      catch { return { ok: false, error: "unresolved" }; }
+    }
+    if (!response.ok) return { ok: false, error: `youtube_${response.status}` };
+    const marks = readYouTubeStationPage(await readBounded(response));
+    if (parsed.kind === "video" && !marks.live) return { ok: false, error: "not_live" };
+    if (parsed.kind === "handle" && !marks.live && !marks.video) return { ok: false, error: "not_live" };
+    if (marks.channel) return { ok: true, channel: marks.channel, video: marks.video };
+    if (marks.video) return { ok: true, channel: null, video: marks.video };
+    if (parsed.kind === "video") return { ok: true, channel: null, video: parsed.video };
+    return { ok: false, error: "unresolved" };
+  } catch {
+    // Offline, DNS, a timeout: one answer, because the canvas does the same
+    // thing with all of them, and the error text is the operator's, not the
+    // page's — see the note above index.mjs's `guard`.
+    return { ok: false, error: "unreachable" };
+  }
+}
+
+function isYouTubeHost(href) {
+  try {
+    const url = new URL(href);
+    const host = url.hostname.toLowerCase();
+    return url.protocol === "https:" && !url.username && !url.password && !url.port
+      && (host === "youtube.com" || host.endsWith(".youtube.com"));
+  } catch { return false; }
+}
+
+async function readBounded(response, limit = FM_STATION_READ_LIMIT) {
+  if (!response.body?.getReader) return (await response.text()).slice(0, limit);
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let out = "";
+  try {
+    while (out.length < limit) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      out += decoder.decode(value, { stream: true });
+      if (out.includes('"isLive":true') && out.includes('rel="canonical"') && out.includes('"channelId"')) break;
+    }
+  } finally {
+    try { await reader.cancel(); } catch { /* connection already closed */ }
+  }
+  return out.slice(0, limit);
+}