ccdeck 3.43.4 → 3.45.0

package/src/server/autoswitch-failover.mjs

@@ -0,0 +1,138 @@
+// Auto-switch away from an active login that has died.
+//
+// WHY THE ENGINE CANNOT DO THIS UNDER THE DECK. claude-swap fails over only
+// after the active account's usage has been unreadable for `unhealthyTicks`
+// polls in a row (3 by default), and it counts them on the engine instance. The
+// deck runs the engine as `cswap auto --once`, a new process per tick, so the
+// count is 1 every time: each tick reports `active-usage-unknown 1/3` and the
+// user stays on an account they can no longer use. Its idle hold has the same
+// shape — `_idle_hold_since` starts again with every process, so its
+// thirty-minute cap is never reached either. (claude-swap 0.26.0: cli.py builds
+// a fresh AutoSwitchEngine for each --once run; autoswitch.py keeps both
+// counters on it.)
+//
+// So the deck finishes that one decision itself, and nothing else: every other
+// switch is still the engine's.
+//
+// WHAT COUNTS AS DEAD. Three answers from three places, all required:
+//   - the engine could not read the active account this tick;
+//   - claude-swap's stored copy of it is not alive (account-health.mjs);
+//   - the `claude` CLI itself says nobody is signed in. That is what Claude
+//     Code leaves behind once a refresh is refused: "Login expired · Please run
+//     /login" clears the saved credentials.
+// Each alone has a known false alarm. An unreadable usage endpoint is a network
+// blip; a dead stored copy beside a working session is #721's stale copy; and a
+// signed-out CLI whose stored copy is alive is a /logout somebody meant, or one
+// claude-swap can still repair. A CLI that could not be asked is no answer, so
+// it never counts as signed out.
+//
+// WHERE IT GOES. An account claude-swap can still use, not disabled, under the
+// threshold the tick ran with, and not one of the two the deck's own rules
+// never land on either: set aside by claude-swap's engine (its refresh token is
+// dead, the very thing being left) or in use by a local `cswap run` session.
+// The freshest reading first, then the most headroom. A reading can be old —
+// claude-swap collects idle accounts on its own schedule — and an old reading
+// is still better than staying on a login that cannot answer at all; once the
+// new account is active, the engine reads it and moves on by its own rules if
+// it is full.
+//
+// AND THE DECK'S RULES. With a home or the weekly rule set, the loop answers a
+// tick inside their cooldown without running the engine — except for an
+// emergency, and an active account the engine could not read is one: it is
+// the only way this failover hears of a dead login. The move it makes is
+// recorded as the tick's (noteEngineTick), so the rules do not mistake it for
+// a switch made by hand.
+//
+// HOW OFTEN. Once per FAILOVER_COOLDOWN_MS. A target whose login dies too is
+// found the same way a tick later, and the wait keeps that from becoming a walk
+// through every dead account in the store inside a minute.
+import { fetchClaudeAccounts, switchClaudeAccount } from "./claude-accounts.mjs";
+import { cliSignIn } from "./claude-identity.mjs";
+
+/** The engine's two ways of saying it could not read the active account. */
+export const LOST_ACTIVE_REASONS = new Set(["active-usage-unknown", "active-idle"]);
+
+/** claude-swap's own cooldown after a switch, used here between failovers. */
+export const FAILOVER_COOLDOWN_MS = 5 * 60_000;
+
+/** What `failOver` names the switch, and the stuck tick, after. */
+export const LOGIN_EXPIRED = "login-expired";
+
+/** Whether a tick's answer could be a dead active login worth asking about. */
+export function engineLostActive(tick) {
+  return tick?.ok === true && tick.event === "no-switch" && LOST_ACTIVE_REASONS.has(tick.reason);
+}
+
+/** The active roster row when its stored login is gone, else null. A stale
+ *  copy is a working session the collector cannot see (#721), never this. */
+export function deadActiveRow(accounts) {
+  const active = Array.isArray(accounts) ? accounts.find(a => a?.active) : null;
+  if (!active || active.staleCopy || active.alive !== false) return null;
+  return active;
+}
+
+/** The accounts a failover may land on, best first. `held` is the slots no
+ *  move may land on whatever the rule (cswap-auto-choice.mjs slotsHeldBack):
+ *  ones claude-swap's engine set aside, and ones a local `cswap run` session
+ *  is using — the same two the deck's own rules skip. */
+export function failoverTargets(accounts, threshold, held = new Set()) {
+  const limit = typeof threshold === "number" && Number.isFinite(threshold) ? threshold : 90;
+  return (Array.isArray(accounts) ? accounts : [])
+    .filter(a => a && !a.active && !a.disabled && a.alive === true && !a.staleCopy && !a.stopped
+      && !held.has(a.num)
+      && typeof a.headroom === "number" && 100 - a.headroom < limit)
+    .sort((a, b) => Number(a.stale === true) - Number(b.stale === true) || b.headroom - a.headroom);
+}
+
+const refOf = a => ({ number: a.num, email: a.email ?? "" });
+
+/**
+ * Finish a tick the engine could not finish: switch away from the active
+ * account when its login is dead, or say why not.
+ *
+ * Null when this tick is not about a dead login at all — the tick then stands
+ * as the engine reported it. Otherwise a tick-shaped answer to merge over it:
+ * a `switch` with `trigger: "login-expired"`, or a `no-switch` whose reason is
+ * `login-expired` and whose detail says what stood in the way.
+ *
+ * `before` runs inside the store lock, ahead of the switch, so the loop can
+ * stand down if it was turned off or a terminal engine started meanwhile.
+ * `heldBack(accounts)` names the slots no move may land on (failoverTargets);
+ * one it cannot read holds nothing back.
+ */
+export async function failOver(tick, {
+  lastAt = null,
+  now = Date.now(),
+  before,
+  roster = () => fetchClaudeAccounts({ force: true }),
+  signIn = cliSignIn,
+  switchTo = switchClaudeAccount,
+  heldBack = async () => new Set(),
+} = {}) {
+  if (!engineLostActive(tick)) return null;
+  const read = await roster().catch(() => null);
+  const dead = deadActiveRow(read?.ok ? read.accounts : null);
+  if (!dead) return null;
+  const cli = await signIn().catch(() => null);
+  if (cli?.loggedIn !== false) return null;
+
+  const from = refOf(dead);
+  if (lastAt != null && now - lastAt < FAILOVER_COOLDOWN_MS) {
+    return { event: "no-switch", reason: LOGIN_EXPIRED, detail: "waiting after the last switch away from an expired login", from };
+  }
+  const held = await Promise.resolve().then(() => heldBack(read.accounts)).catch(() => null);
+  const [target] = failoverTargets(read.accounts, tick.threshold, held instanceof Set ? held : new Set());
+  if (!target) {
+    // `stuck`: the one answer the notifier says, and the panel shows.
+    return { event: "no-switch", reason: LOGIN_EXPIRED, detail: "no other account is ready", stuck: true, from };
+  }
+  // Forced: the current login is the dead one, and Claude Code has already
+  // cleared it. A plain switch would first back that empty login up, and
+  // claude-swap refuses to (see switchClaudeAccount).
+  const r = await switchTo(target.num, { before, force: true });
+  if (r?.skipped) return { event: "skipped", reason: r.skipped };
+  if (!r?.ok) {
+    return { ok: false, event: "no-switch", reason: "failover_failed", detail: r?.output || r?.reason || "switch failed", from };
+  }
+  return { event: "switch", switched: true, trigger: LOGIN_EXPIRED, from, to: refOf(target) };
+}

package/src/server/claude-accounts.mjs

@@ -39,10 +39,11 @@ import { currentIdentity } from "./claude-identity.mjs";
 // cycle is a lock that may not be there yet when a mutation wants it.
 import { withStoreLock } from "./store-lock.mjs";
 // claude-swap's own per-slot verdicts, which have to be ASKED for rather than
-// read off the store. The roster puts them on each row; verdictNow and
-// verdictsNow are re-exported because cswap-admin.mjs and lan-deck.mjs reach
-// them through this module.
-import { verdictFor, verdictsAskedAt } from "./claude-verdicts.mjs";
+// read off the store. The roster puts them on each row, and a switch asks for a
+// collection through the same queue before it reads its target (#2184);
+// verdictNow and verdictsNow are re-exported because cswap-admin.mjs and
+// lan-deck.mjs reach them through this module.
+import { verdictFor, verdictsAskedAt, verdictsNow } from "./claude-verdicts.mjs";
 export { verdictNow, verdictsNow } from "./claude-verdicts.mjs";
 // Asking claude-swap to collect, which every roster read does when something is
 // due, and when each account will next be read.
@@ -51,6 +52,13 @@ import { nextReadAt, nudgeCollector } from "./claude-collector.mjs";
 // (#1893). Pure, and keyed the way LAN sync keys accounts.
 import { hasRecovered, reauthFor } from "./account-origins.mjs";
 import { accountKey } from "./lan-copies.mjs";
+// What each organization's Claude settings were last seen to turn on, so a row
+// can say it before anyone switches to the account. See its header for when the
+// shared remote-settings.json can be pinned on an organization at all.
+import { observeOrgTelemetry } from "./org-telemetry.mjs";
+// Whether a switch target's stored login is known dead, and whether a
+// collection would read it first (#2184). Pure, and imports nothing.
+import { collectionWouldRead, deadLoginOf } from "./login-guard.mjs";
 import { dirname, join } from "node:path";
 import { existsSync } from "node:fs";
 import { homedir, platform } from "node:os";
@@ -463,6 +471,7 @@ async function readRoster(now, gen) {
   }
 
   const rows = await readUsageRows(root);
+  const orgTelemetry = await observeOrgTelemetry({ seq }).catch(() => ({}));
 
   // Kick a collection for the NEXT poll if anything is due — either because
   // claude-swap's schedule says so, or because an account has never been
@@ -496,7 +505,7 @@ async function readRoster(now, gen) {
     const row = rows[num];
     const key = accountKey(acct.email, acct.organizationUuid);
     const origin = Object.hasOwn(origins, key) ? origins[key] : null;
-    const shown = rosterRow({ seq, num, acct, row, identity, now, key, origin });
+    const shown = rosterRow({ seq, num, acct, row, identity, now, key, origin, telemetry: orgTelemetry[acct.organizationUuid] ?? null });
     accounts.push(shown);
     // A put-off incident is over once a read succeeds after it, and the
     // put-off goes with it (#1893) — said here, where the read is, rather than
@@ -523,7 +532,7 @@ function observedMs(seconds) {
   return Number.isFinite(ms) && ms > 0 && Number.isFinite(new Date(ms).getTime()) ? ms : null;
 }
 
-function rosterRow({ seq, num, acct, row, identity, now, key, origin = null }) {
+function rosterRow({ seq, num, acct, row, identity, now, key, origin = null, telemetry = null }) {
   const matches = rowIsFor(row, acct);
   const good = matches ? row.lastGood : null;
 
@@ -613,6 +622,11 @@ function rosterRow({ seq, num, acct, row, identity, now, key, origin = null }) {
     // claude-swap has refused its login since: `{ key, since, dismissed }`.
     // `key` and `since` together name it, for "Not now" to send back.
     reauth: reauth ? { key, ...reauth } : null,
+    // What this account's organization last turned on for Claude Code's
+    // telemetry export, when the deck has seen its settings (org-telemetry.mjs):
+    // `{ orgName, level, content, destinations, seenAt }`. `level` "off" was
+    // seen off; null was never seen, which is unknown and not "off".
+    telemetry: telemetry ?? null,
   };
 }
 
@@ -628,8 +642,8 @@ function rosterRow({ seq, num, acct, row, identity, now, key, origin = null }) {
  * It says nothing about whether the user is signed in. Measured on the machine
  * that reported this, at the same instant:
  *
- *   claude auth status --json  ->  loggedIn: true, claude3@sapec.md
- *   cswap list --json          ->  claude3@sapec.md: relogin_required
+ *   claude auth status --json  ->  loggedIn: true, carol@example.net
+ *   cswap list --json          ->  carol@example.net: relogin_required
  *   GET /api/quota             ->  source: cli, 5h 33%, 7d 37%
  *
  * The user had signed in again in a terminal, which refreshes the LIVE
@@ -796,6 +810,82 @@ export function slotNumber(accountNum) {
   return Number.isInteger(num) && num >= 1 && num <= 999 ? num : null;
 }
 
+// ── before a switch: is the target's login known dead? (#2184) ──────────────
+
+/** How long a switch waits for claude-swap to read its target first. A cold
+ *  collection can take a minute; a switch that waited that long would read as
+ *  a hang, and what it could not learn in time it does not hold against the
+ *  target. */
+const SWITCH_READ_WAIT_MS = 15_000;
+
+/** Slot `num` as the store holds it — the account, its usage row and whether
+ *  that row is the account's own — or null when there is no such slot. */
+async function switchTarget(num) {
+  const root = backupRoot();
+  const seq = await readSequence(root);
+  const key = String(num);
+  const acct = seq?.accounts?.[key];
+  if (!acct) return null;
+  const row = (await readUsageRows(root))[key];
+  return { acct, row, matches: rowIsFor(row, acct), active: activeSlot(seq) === key };
+}
+
+/**
+ * Ask claude-swap to read slot `num` before a switch onto it, when a
+ * collection would read it at all — see login-guard.mjs for why that is the
+ * only check 0.26.0 offers, and the incident it would have caught.
+ *
+ * Shares the verdict queue's `cswap list --json`, so it never starts a second
+ * collection beside one already running, and waits for it no longer than
+ * SWITCH_READ_WAIT_MS. Outside the store lock: a collection takes none of the
+ * deck's, and a mutation queued behind this one must not wait out somebody
+ * else's network. Never throws — a check that cannot be made is no answer.
+ */
+export async function readBeforeSwitch(num, { now = Date.now(), collect = () => verdictsNow(), waitMs = SWITCH_READ_WAIT_MS } = {}) {
+  let timer = null;
+  try {
+    const t = await switchTarget(num);
+    if (!t || t.active || deadLoginOf(t.row, { matches: t.matches })) return false;
+    if (!collectionWouldRead(t.row, { matches: t.matches, now })) return false;
+    const waited = new Promise(resolve => { timer = setTimeout(resolve, waitMs); timer.unref?.(); });
+    await Promise.race([Promise.resolve().then(collect).catch(() => null), waited]);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (timer) clearTimeout(timer);
+  }
+}
+
+/**
+ * The refusal for a switch onto slot `num`, when claude-swap's store says its
+ * stored login is dead — or null, which is every case it cannot say so,
+ * including a store it could not read.
+ *
+ * `{ ok: false, reason: "login_expired", account: { num, email, alias }, error,
+ * since }`, so the panel can name the account and offer the sign-in that fixes
+ * it. A switch to the slot that is already active is not this question: it
+ * writes nothing live.
+ */
+export async function expiredSwitchTarget(num) {
+  try {
+    const t = await switchTarget(num);
+    if (!t || t.active) return null;
+    const signedIn = originsNow()[accountKey(t.acct.email, t.acct.organizationUuid)]?.signedInAt;
+    const dead = deadLoginOf(t.row, { matches: t.matches, signedInAt: signedIn > 0 ? signedIn : null });
+    if (!dead) return null;
+    return {
+      ok: false,
+      reason: "login_expired",
+      account: { num, email: t.acct.email ?? null, alias: t.acct.alias ?? null },
+      error: dead.error,
+      since: dead.since,
+    };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Switch the active Claude account by delegating to `cswap`.
  *
@@ -817,8 +907,25 @@ export function slotNumber(accountNum) {
  * The validation stays OUTSIDE the lock. A slot number that is not one is not a
  * mutation and must not wait behind somebody else's sixty-second `cswap add`
  * to be told so.
+ *
+ * AND IT DOES NOT SWITCH ONTO A LOGIN KNOWN TO BE DEAD (#2184). Every session
+ * on the machine runs on the login this puts live, so a dead one stops all of
+ * them at once. The target is read first when a collection would read it
+ * (readBeforeSwitch), and judged inside the lock, on the store as it stands
+ * when `cswap switch` would run (expiredSwitchTarget). Anything that cannot be
+ * judged lets the switch go ahead.
+ *
+ * `before`, when given, is asked first thing inside the lock: a switch nobody
+ * pressed — the auto-switch failover — may have been turned off while it
+ * queued, and answers `{ skipped: <why> }` instead of moving the account.
+ *
+ * `force` is `cswap switch --force`: activate the target without backing up
+ * the current login first. Only for a current login already known to be dead.
+ * Claude Code clears a login whose refresh was refused, and a plain switch then
+ * refuses in turn ("Current account credential is empty …; refusing to
+ * overwrite its backup"), which would leave the user exactly where they were.
  */
-export function switchClaudeAccount(accountNum) {
+export function switchClaudeAccount(accountNum, { before, force = false } = {}) {
   // Straight into an exec argument, so nothing but a slot number gets through.
   const num = slotNumber(accountNum);
   if (num == null) {
@@ -827,13 +934,17 @@ export function switchClaudeAccount(accountNum) {
 
   // Argument vector, never a shell — and resolved through exec.mjs so the
   // Windows `.exe`/`.cmd` shim is found too.
-  return withStoreLock(() => cswapBin()
-    .then(bin => run(bin, ["switch", String(num)], { timeout: 30_000 }))
-    .then(r => {
-      if (r.ok) return { ok: true, output: r.stdout.trim() };
-      const reason = r.code === "ENOENT" ? "no_cswap" : r.killed ? "timeout" : "switch_failed";
-      return { ok: false, reason, output: failureDetail(r, 500) };
-    }));
+  return readBeforeSwitch(num).then(() => withStoreLock(async () => {
+    const skipped = before ? await before() : null;
+    if (skipped) return { ok: false, skipped };
+    const expired = await expiredSwitchTarget(num);
+    if (expired) return expired;
+    const argv = force ? ["switch", String(num), "--force"] : ["switch", String(num)];
+    const r = await run(await cswapBin(), argv, { timeout: 30_000 });
+    if (r.ok) return { ok: true, output: r.stdout.trim() };
+    const reason = r.code === "ENOENT" ? "no_cswap" : r.killed ? "timeout" : "switch_failed";
+    return { ok: false, reason, output: failureDetail(r, 500) };
+  }));
 }
 
 /**

package/src/server/claude-dir.mjs

@@ -19,7 +19,7 @@
 // to "where does the `claude` command live", and the deck now asks that question
 // at boot, before any quota exists, to decide whether this is a Claude machine
 // at all. One list, one caller-visible name, no second spelling to drift.
-import { existsSync } from "node:fs";
+import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve, posix as posixPath, win32 as winPath } from "node:path";
 
@@ -131,15 +131,26 @@ function claudeCliOnDisk({
   home = homedir(),
   exists = existsSync,
 } = {}) {
+  for (const _ of claudeCliFound({ platform, env, home, exists })) return true;
+  return false;
+}
+
+/**
+ * Every `claude` the walk above finds, in the order it finds them — the known
+ * install paths first, then each PATH entry. claudeCliOnDisk stops at the first;
+ * claudeCodeVersions below reads them all, because an old CLI anywhere on the
+ * machine still reads the settings file a new one does.
+ */
+function* claudeCliFound({ platform, env, home, exists }) {
   const path = platform === "win32" ? winPath : posixPath;
   const bare = [];
   for (const candidate of claudeCliCandidates(platform, env, home)) {
     // A full path is worth a single stat; a bare name means "ask PATH", which
     // is the walk below. Same split quotaClaudeBin makes, for the same reason.
-    if (candidate.includes(path.sep)) { if (exists(candidate)) return true; }
+    if (candidate.includes(path.sep)) { if (exists(candidate)) yield candidate; }
     else bare.push(candidate);
   }
-  if (bare.length === 0) return false;
+  if (bare.length === 0) return;
 
   // process.env is case-insensitive on Windows, but an injected plain object in
   // a test is not, and %Path% is how the variable is actually spelled there.
@@ -156,10 +167,136 @@ function claudeCliOnDisk({
     const dir = entry.trim().replace(/^"+|"+$/g, "");
     if (dir === "") continue;
     for (const name of bare) {
-      for (const ext of exts) if (exists(path.join(dir, name + ext))) return true;
+      for (const ext of exts) {
+        const found = path.join(dir, name + ext);
+        if (exists(found)) yield found;
+      }
     }
   }
-  return false;
+}
+
+/** A Claude Code version as its installers spell it: three numbers, and a
+ *  pre-release or build suffix that does not change which release it is. */
+const CC_VERSION_RE = /^(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.+-]*)?$/;
+
+/** Whether `version` is `min` or newer, by the three numbers. */
+export function claudeVersionAtLeast(version, min) {
+  const a = CC_VERSION_RE.exec(String(version ?? ""));
+  const b = CC_VERSION_RE.exec(String(min ?? ""));
+  if (!a || !b) return false;
+  for (let i = 1; i <= 3; i++) {
+    const d = Number(a[i]) - Number(b[i]);
+    if (d !== 0) return d > 0;
+  }
+  return true;
+}
+
+/** The npm package every npm install of Claude Code is. */
+const CC_PACKAGE = "@anthropic-ai/claude-code";
+
+/**
+ * The version of the one install `bin` belongs to, read off disk, or
+ * undefined when its layout does not say.
+ *
+ *   npm      the package's own package.json, found by walking up from the
+ *            file the bin resolves to — or, for the `claude.cmd` shim npm
+ *            writes on Windows, in the node_modules beside the shim
+ *   native   `~/.local/bin/claude` links to `…/claude/versions/<version>`;
+ *            on Windows it is a copy, and the newest of those versions is the
+ *            one the installer put there
+ *   Homebrew the cask's binary lives at `…/Caskroom/claude-code/<version>/claude`
+ *
+ * The package.json comes first, and a version-shaped directory is believed only
+ * where those two layouts put one: a node manager keeps the NODE version in its
+ * paths (`…/installs/node/22.14.0/…`), and reading that as Claude Code's would
+ * let a machine with an old CLI through the gate.
+ */
+function installVersion(bin, { platform, home, exists, realpath, readText, list }) {
+  const path = platform === "win32" ? winPath : posixPath;
+  let real = bin;
+  try { real = realpath(bin); } catch { /* a dangling link reads as itself */ }
+  const fromPackage = file => {
+    try {
+      const pkg = JSON.parse(readText(file));
+      return pkg?.name === CC_PACKAGE && CC_VERSION_RE.test(pkg.version) ? pkg.version : undefined;
+    } catch { return undefined; }
+  };
+  const beside = path.join(path.dirname(bin), "node_modules", ...CC_PACKAGE.split("/"), "package.json");
+  if (exists(beside)) {
+    const v = fromPackage(beside);
+    if (v) return v;
+  }
+  let dir = path.dirname(real);
+  for (let i = 0; i < 5; i++) {
+    const file = path.join(dir, "package.json");
+    if (exists(file)) {
+      const v = fromPackage(file);
+      if (v) return v;
+    }
+    const up = path.dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  const name = path.basename(real);
+  const parent = path.basename(path.dirname(real));
+  if (CC_VERSION_RE.test(name) && parent === "versions") return name;
+  if (CC_VERSION_RE.test(parent) && path.basename(path.dirname(path.dirname(real))) === "claude-code") return parent;
+  const nativeBin = path.join(home, ".local", "bin");
+  if (path.dirname(real) === nativeBin) {
+    try {
+      const versions = list(path.join(home, ".local", "share", "claude", "versions"))
+        .filter(v => CC_VERSION_RE.test(v));
+      let newest;
+      for (const v of versions) if (!newest || claudeVersionAtLeast(v, newest)) newest = v;
+      if (newest) return newest;
+    } catch { /* no native install beside it */ }
+  }
+  return undefined;
+}
+
+/**
+ * The versions of every Claude Code the deck can find on this machine, read
+ * off disk without running any of them — the same places hasClaudeInstalled
+ * looks, each resolved to the install it belongs to. Distinct, and only the
+ * ones whose layout names a version: an install that does not say is left out
+ * rather than guessed at.
+ *
+ * WITHOUT A CHILD PROCESS, for the reason claudeCliOnDisk gives: the installer
+ * asks this at boot, and a `claude --version` is about three seconds there.
+ * Every dependency is injected so the suite can lay out an npm, a native and a
+ * Homebrew install for any platform without one on the machine.
+ */
+export function claudeCodeVersions(deps = {}) {
+  const out = new Set();
+  for (const { version } of claudeCodeInstalls(deps)) if (version) out.add(version);
+  return [...out];
+}
+
+/**
+ * Every `claude` the deck can find, each with the version its install layout
+ * names, or `version: undefined` where the layout does not say. The same walk
+ * and the same reading as claudeCodeVersions, which keeps only the versions;
+ * this keeps the installs that did not answer too, for a gate that has to
+ * treat "a Claude Code whose version is unknown" as a reason to refuse rather
+ * than as one fewer Claude Code (skill-hook.mjs).
+ */
+export function claudeCodeInstalls({
+  platform = process.platform,
+  env = process.env,
+  home = homedir(),
+  exists = existsSync,
+  realpath = p => realpathSync.native(p),
+  readText = p => readFileSync(p, "utf8"),
+  list = p => readdirSync(p),
+} = {}) {
+  const out = [];
+  const seen = new Set();
+  for (const bin of claudeCliFound({ platform, env, home, exists })) {
+    if (seen.has(bin)) continue;
+    seen.add(bin);
+    out.push({ bin, version: installVersion(bin, { platform, home, exists, realpath, readText, list }) });
+  }
+  return out;
 }
 
 /**

package/src/server/claude-identity.mjs

@@ -120,3 +120,26 @@ export async function currentIdentity() {
     return null;
   }
 }
+
+/**
+ * Whether the CLI says anybody is signed in — the answer currentIdentity folds
+ * away: `{ loggedIn: true, email }`, `{ loggedIn: false }`, or null when there
+ * is no answer to read.
+ *
+ * `claude auth status --json` exits 1 when nobody is signed in and still prints
+ * `{"loggedIn": false, …}` (Claude Code 2.1.302), so `r.ok` cannot tell
+ * "signed out" from "could not ask". currentIdentity returns null for both,
+ * which is right for its callers. The auto-switch failover may only act on a
+ * CLI that has said the login is gone, so it reads the printed answer whatever
+ * the exit code, and a run that timed out or printed nothing is no answer.
+ */
+export async function cliSignIn() {
+  const r = await run(adminClaudeBin(), ["auth", "status", "--json"], { timeout: 20_000 });
+  if (r.timedOut) return null;
+  try {
+    const j = JSON.parse(r.stdout);
+    if (j?.loggedIn === true) return { loggedIn: true, email: j.email ?? "" };
+    if (j?.loggedIn === false) return { loggedIn: false };
+  } catch { /* nothing printed that could be read */ }
+  return null;
+}