ccdeck 3.43.4 → 3.45.0

package/src/server/integrations/store.mjs

@@ -0,0 +1,226 @@
+// The trackers this deck is connected to (#2178): what each connection is, kept
+// in one file, and the credential it uses, kept in another.
+//
+// TWO FILES, AND WHY. `integrations.json` holds what the page may see — the
+// name, the address, which account answered, what the provider learned about
+// the server — and is read for every list. `integrations-secrets.json` holds
+// the tokens and nothing else, is read only when a request to the tracker is
+// about to be signed, and is never serialised into an answer. Splitting them
+// means no code path that returns connections can carry a token by accident:
+// the token is not in the object it returns.
+//
+// There is no keychain anywhere in this deck, so both are plain files in a
+// folder of their own, `integrations/` in the deck's home (deck-home.mjs, which
+// honours CCDECK_HOME), kept at 0700 whatever the home itself is — written the way
+// prefs.json and Codex's auth.json are: a fresh temp file created 0600 with
+// O_EXCL, fsynced, chmod'ed, then renamed over the old one with the retrying
+// rename Windows needs. writeFileAtomic is deliberately not used: it creates a
+// new file at 0666 minus the umask, which is world-readable on most machines.
+//
+// THE SECRET IS OPAQUE. A string today (a Jira token), an object tomorrow (an
+// OAuth access/refresh pair). Nothing in this file looks inside it; a provider
+// decides what it is and the proxy hands it back to the provider to sign with.
+//
+// Nothing here is shared with paired decks: the LAN exchange is an explicit
+// allowlist (lan-manifest.mjs, lan-copies.mjs) and prefs never sync, so a
+// connection made on this machine stays on this machine.
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, readFile, rename, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { createTemp, renameWithRetry } from "../atomic-write.mjs";
+import { deckDataDir } from "../deck-home.mjs";
+import { PRODUCT } from "../brand.mjs";
+
+export const META_FILE = "integrations.json";
+export const SECRETS_FILE = "integrations-secrets.json";
+const FILE_MODE = 0o600;
+const DIR_MODE = 0o700;
+/** More than anybody connects by hand; a bound on what a list answer costs. */
+export const MAX_CONNECTIONS = 50;
+/** The folder both files live in, inside the deck's home. */
+export const STORE_DIR = "integrations";
+
+const text = (v, max = 500) => (typeof v === "string" ? v.slice(0, max) : "");
+
+/** A connection as it is kept: every field a known type, nothing else. */
+function normaliseConnection(raw) {
+  if (!raw || typeof raw !== "object" || typeof raw.id !== "string" || typeof raw.kind !== "string") return null;
+  const account = raw.account && typeof raw.account === "object" ? raw.account : {};
+  const origins = Array.isArray(raw.allowedOrigins) ? raw.allowedOrigins.filter(o => typeof o === "string").slice(0, 8) : [];
+  return {
+    id: text(raw.id, 64),
+    kind: text(raw.kind, 32),
+    name: text(raw.name, 120),
+    baseUrl: text(raw.baseUrl, 500),
+    account: {
+      id: text(account.id, 200),
+      login: text(account.login, 200),
+      name: text(account.name, 200),
+      avatarUrl: text(account.avatarUrl, 1000),
+    },
+    meta: raw.meta && typeof raw.meta === "object" && !Array.isArray(raw.meta) ? raw.meta : {},
+    allowedOrigins: origins,
+    createdAt: text(raw.createdAt, 40),
+    updatedAt: text(raw.updatedAt, 40),
+  };
+}
+
+/**
+ * @param {object} [opts]
+ * @param {() => string} [opts.dir] the directory both files live in; the deck's home by default
+ * @param {(msg: string) => void} [opts.warn]
+ */
+export function createIntegrationsStore({ dir = () => join(deckDataDir(), STORE_DIR), warn = msg => console.warn(msg) } = {}) {
+  /** Every write, one at a time, so two pages saving at once cannot lose one. */
+  let chain = Promise.resolve();
+  const queued = job => {
+    const run = chain.then(job, job);
+    chain = run.catch(() => {});
+    return run;
+  };
+
+  async function readJson(path, label) {
+    let raw;
+    try { raw = await readFile(path, "utf8"); }
+    catch (err) {
+      if (err?.code === "ENOENT") return null;
+      throw err;
+    }
+    try { return JSON.parse(raw.replace(/^/, "")); }
+    catch {
+      // Kept aside rather than overwritten: a damaged secrets file is still
+      // the user's tokens, and the next save would otherwise replace it with
+      // an empty one. Its contents are never logged.
+      const aside = `${path}.corrupt-${Date.now()}`;
+      await rename(path, aside).catch(() => {});
+      warn(`${PRODUCT}: ${label} could not be read as JSON and was moved aside to ${aside}.`);
+      return null;
+    }
+  }
+
+  async function load() {
+    const home = dir();
+    const meta = await readJson(join(home, META_FILE), META_FILE);
+    const secrets = await readJson(join(home, SECRETS_FILE), SECRETS_FILE);
+    const connections = (Array.isArray(meta?.connections) ? meta.connections : [])
+      .map(normaliseConnection).filter(Boolean).slice(0, MAX_CONNECTIONS);
+    const ids = new Set(connections.map(c => c.id));
+    const kept = secrets?.secrets && typeof secrets.secrets === "object" ? secrets.secrets : {};
+    // A secret whose connection is gone is dropped at the next write: a
+    // disconnect that half-failed must not leave a token behind for ever.
+    const secretMap = new Map(Object.entries(kept).filter(([id, value]) => ids.has(id) && value != null));
+    return { connections, secrets: secretMap };
+  }
+
+  /** The safe write: temp at 0600 with O_EXCL, fsync, chmod, rename. */
+  async function writeFile(name, value) {
+    const home = dir();
+    await mkdir(home, { recursive: true, mode: DIR_MODE });
+    // Made 0700 by mkdir only when it did not exist yet; held there on every
+    // write, so a folder someone loosened does not stay loose.
+    if (process.platform !== "win32") await chmod(home, DIR_MODE).catch(() => {});
+    const target = join(home, name);
+    const { tmp, handle } = await createTemp(target, { mode: FILE_MODE });
+    let landed = false;
+    try {
+      try {
+        await handle.writeFile(JSON.stringify(value, null, 2) + "\n", "utf8");
+        await handle.sync();
+      } finally {
+        await handle.close();
+      }
+      await chmod(tmp, FILE_MODE);
+      await renameWithRetry(tmp, target);
+      landed = true;
+    } finally {
+      // A temp left behind may hold tokens in cleartext.
+      if (!landed) await unlink(tmp).catch(() => {});
+    }
+  }
+
+  const writeMeta = connections => writeFile(META_FILE, { version: 1, connections });
+  const writeSecrets = map => writeFile(SECRETS_FILE, { version: 1, secrets: Object.fromEntries(map) });
+
+  /** What a page may see of a connection: everything but the secret, and
+   *  whether one is saved. */
+  const publicOf = (conn, secrets) => ({ ...conn, tokenSaved: secrets.has(conn.id) });
+
+  return {
+    /** Every connection, as a page may see it. `own(conn, secret)`, when
+     *  given, is handed each connection that has a secret, with it, and
+     *  answers the connection to list: the routes take that secret out of what
+     *  an earlier build kept (routes.mjs). */
+    async list({ own } = {}) {
+      const { connections, secrets } = await load();
+      return connections.map(c => publicOf(own && secrets.has(c.id) ? own(c, secrets.get(c.id)) : c, secrets));
+    },
+
+    /** One connection, as a page may see it, or null. */
+    async get(id) {
+      const { connections, secrets } = await load();
+      const conn = connections.find(c => c.id === id);
+      return conn ? publicOf(conn, secrets) : null;
+    },
+
+    /** The opaque secret for one connection, or null. The ONE read of the
+     *  secrets file, and its only caller is the proxy that signs requests. */
+    async secret(id) {
+      const { secrets } = await load();
+      return secrets.get(id) ?? null;
+    },
+
+    /** Add a connection with its secret. Answers it as a page may see it. */
+    create(fields, secret) {
+      return queued(async () => {
+        const { connections, secrets } = await load();
+        if (connections.length >= MAX_CONNECTIONS) throw new Error("too many connections");
+        const now = new Date().toISOString();
+        const conn = normaliseConnection({ ...fields, id: randomUUID(), createdAt: now, updatedAt: now });
+        // The secret first: if the second write fails the connection does not
+        // exist, and the orphaned secret is dropped by the next write.
+        if (secret != null) {
+          secrets.set(conn.id, secret);
+          await writeSecrets(secrets);
+        }
+        await writeMeta([...connections, conn]);
+        return publicOf(conn, secrets);
+      });
+    },
+
+    /** Change a connection. `secret` undefined keeps the saved one. */
+    update(id, patch, secret) {
+      return queued(async () => {
+        const { connections, secrets } = await load();
+        const at = connections.findIndex(c => c.id === id);
+        if (at < 0) return null;
+        const prev = connections[at];
+        const next = normaliseConnection({ ...prev, ...patch, id: prev.id, kind: prev.kind, createdAt: prev.createdAt, updatedAt: new Date().toISOString() });
+        if (secret !== undefined) {
+          if (secret === null) secrets.delete(id); else secrets.set(id, secret);
+          await writeSecrets(secrets);
+        }
+        const list = connections.slice();
+        list[at] = next;
+        await writeMeta(list);
+        return publicOf(next, secrets);
+      });
+    },
+
+    /** Forget a connection and its secret. True when there was one. */
+    remove(id) {
+      return queued(async () => {
+        const { connections, secrets } = await load();
+        const had = connections.some(c => c.id === id);
+        // The secret goes first: a disconnect that fails halfway leaves a
+        // connection with no token (visible, and Disconnect can be pressed
+        // again), never a token with no connection.
+        if (secrets.delete(id) || had) await writeSecrets(secrets);
+        if (had) await writeMeta(connections.filter(c => c.id !== id));
+        return had;
+      });
+    },
+  };
+}
+
+/** The deck's own store, in its home. */
+export const integrationsStore = createIntegrationsStore();

package/src/server/lan-deck.mjs

@@ -31,6 +31,9 @@ import { run } from "./exec.mjs";
 // A LAN round checks the imports it lands the way the paste box does.
 import { CHECKS_IMPORTS } from "./account-routes.mjs";
 import { RUNNING_VERSION } from "./running-version.mjs";
+// Which of this deck's accounts a paired deck is working on, for the account
+// notifier, which reaches the engine's status through it (#2192).
+import { connectLanStatus } from "./lan-elsewhere.mjs";
 
 // ── LAN sync ────────────────────────────────────────────────────────────────
 //
@@ -301,6 +304,10 @@ export const lanEngine = createEngine({
   },
 });
 
+// The status the account notifier reads "which deck is on what" from — see
+// lan-elsewhere.mjs, which says why it does not import this file for it.
+connectLanStatus(() => lanEngine.status());
+
 /**
  * What prefs is entitled to tell the LAN engine, and what it is not.
  *

package/src/server/lan-elsewhere.d.mts

@@ -0,0 +1,30 @@
+// The page's view of lan-elsewhere.mjs: the rule the accounts' rows read, the
+// same one the notifier reads on the server.
+
+/** The parts of a status row the rule reads — the engine's and the page's
+ *  status rows are both this and more. */
+export interface ElsewherePeer {
+  fp: string;
+  peerFp?: string | null;
+  name?: string;
+  addr?: string;
+  paired?: boolean;
+  offers?: { at: number; current?: { key?: string } | { hidden: true } | { other: true } | null } | null;
+}
+
+export interface ElsewhereStatus<P extends ElsewherePeer = ElsewherePeer> {
+  enabled?: boolean;
+  peers?: P[];
+  addrs?: string[];
+  aliases?: Record<string, string>;
+}
+
+export const ELSEWHERE_FRESH_MS: number;
+export function decksByAccount<P extends ElsewherePeer>(
+  status: ElsewhereStatus<P> | null | undefined, now: number, freshMs?: number,
+): Map<string, P[]>;
+export function deckName(p: ElsewherePeer, aliases?: Record<string, string>): string;
+export function namesByAccount(status: ElsewhereStatus | null | undefined, now: number, freshMs?: number): Map<string, string[]>;
+export function deckList(names: readonly string[]): string;
+export function connectLanStatus(status: (() => unknown) | null): void;
+export function elsewhereNow(now?: number): Map<string, string[]>;

package/src/server/lan-elsewhere.mjs

@@ -0,0 +1,137 @@
+// Which of this deck's accounts another deck is working on right now (#2192).
+//
+// ONE LOGIN, LIVE IN ONE PLACE. A Claude refresh token is good for one renewal:
+// the copy that renews it first gets a new one, and every other copy of that
+// login is refused with invalid_grant from then on. Claude Code answers that by
+// wiping the stored login, and every session on that machine stops with "Login
+// expired · Please run /login". Two machines that hold one copied login hold one
+// expiry too, so both reach for the renewal within minutes of each other and
+// the slower one loses. Measured on one pair of decks: three of seven
+// interruptions in a month landed on the 8-hour renewal with nothing on that
+// machine renewing in between.
+//
+// Local network already says which account each paired deck is on (`current`
+// in its manifest — see currentFor in lan-copies.mjs), so this needs nothing new
+// on the wire: it reads what the status already holds. It is the one rule the
+// row's warning and the notification both ask, so the two cannot disagree
+// about which deck is on what. The page reads it through lan-elsewhere.d.mts;
+// the server through the door at the bottom, which lan-deck.mjs connects to its
+// engine.
+//
+// IT WARNS AND DOES NOTHING ELSE. The login a deck is on already stays on that
+// deck (manifestFor marks it `inUse` and `serve` refuses it), and Auto-switch
+// may still move to a login a paired deck is on (3.43.3). What is left is a
+// copy a paired deck held before this deck went live on it — which only the
+// two decks saying where they are can show, and only a person can settle. A
+// deck that hides which account it is on, or is on one it does not share with
+// this one, says nothing here, and nothing is guessed in its place.
+//
+// Pure apart from that door. No sockets, no timers, no filesystem.
+
+/**
+ * How recent a deck's word has to be for "it is on this account right now".
+ *
+ * A paired deck says which account it is on in every manifest, and a manifest
+ * crosses at least once a minute each way — this deck's round asks it, and its
+ * round carries one in. Five minutes is five rounds: a dropped round or two does
+ * not take the warning down and put it back, which would read as two incidents,
+ * and a deck that was switched off stops counting soon after. Past it, what the
+ * deck said is its last word rather than its current one.
+ */
+export const ELSEWHERE_FRESH_MS = 5 * 60_000;
+
+/** An address that is this machine: loopback, or one of its own. A second deck
+ *  on this machine shares its Claude login rather than copying it, so it is not
+ *  another place the login is live. */
+function onThisMachine(addr, mine) {
+  if (typeof addr !== "string" || !addr) return false;
+  if (addr === "::1" || addr === "localhost" || addr.startsWith("127.")) return true;
+  return Array.isArray(mine) && mine.includes(addr);
+}
+
+/**
+ * The paired decks that said, within `freshMs`, that they are working on one of
+ * the accounts they share — keyed by account, one row per deck.
+ *
+ * ONLY WHAT A DECK SAID, AND ONLY RECENTLY. A deck names the account it is on
+ * only when it shares that account and its owner left "Show paired decks which
+ * of these this deck is using" on; `hidden`, `other`, nothing at all (a deck
+ * older than 3.22.15 never says) and a word older than `freshMs` all prove
+ * nothing, and none of them is drawn as a deck on an account. A deck that is
+ * not paired any more is not counted either: what it said was said to a deck
+ * that no longer listens.
+ *
+ * `status` is the engine's status() — or the page's copy of it, the same shape.
+ */
+export function decksByAccount(status, now, freshMs = ELSEWHERE_FRESH_MS) {
+  const out = new Map();
+  if (!status?.enabled) return out;
+  const seen = new Set();
+  for (const p of Array.isArray(status.peers) ? status.peers : []) {
+    if (!p || p.paired !== true) continue;
+    const said = p.offers;
+    const key = said?.current && typeof said.current.key === "string" ? said.current.key : "";
+    if (!key || typeof said.at !== "number" || !Number.isFinite(said.at)) continue;
+    // Within the window, and not from the future: a clock that ran ahead is not
+    // a promise about the next five minutes.
+    if (now - said.at > freshMs || said.at - now > freshMs) continue;
+    if (onThisMachine(p.addr, status.addrs)) continue;
+    // One deck reached two ways is merged into one row by the engine already;
+    // the same deck under the same key twice would still be one deck.
+    const id = `${key}|${p.peerFp ?? p.fp}`;
+    if (seen.has(id)) continue;
+    seen.add(id);
+    out.set(key, [...(out.get(key) ?? []), p]);
+  }
+  return out;
+}
+
+/** A deck as a sentence names it: the name somebody here gave it, else its own. */
+export function deckName(p, aliases) {
+  const id = p?.peerFp ?? p?.fp;
+  const given = aliases && typeof aliases === "object" && typeof aliases[id] === "string" ? aliases[id].trim() : "";
+  const own = typeof p?.name === "string" ? p.name.trim() : "";
+  return given || own || "another deck";
+}
+
+/** The same answer as names: account key to the decks on it, each named once
+ *  and in order, so one machine reached under two keys is one name. */
+export function namesByAccount(status, now, freshMs = ELSEWHERE_FRESH_MS) {
+  const out = new Map();
+  for (const [key, rows] of decksByAccount(status, now, freshMs)) {
+    const names = [...new Set(rows.map(p => deckName(p, status?.aliases)))].sort((a, b) => a.localeCompare(b));
+    out.set(key, names);
+  }
+  return out;
+}
+
+/** "iMac", "iMac and PC", "iMac, Mac and PC". */
+export function deckList(names) {
+  if (names.length <= 1) return names[0] ?? "another deck";
+  return `${names.slice(0, -1).join(", ")} and ${names[names.length - 1]}`;
+}
+
+// ── the door ────────────────────────────────────────────────────────────────
+//
+// The notifier needs the engine's status, and the engine lives in lan-deck.mjs,
+// which imports far more than the notifier should. So lan-deck.mjs hands its
+// status() in here as it loads, and the notifier asks here. Until it does — a
+// test that runs the notifier on its own — the answer is that no deck is on
+// anything, which is what a deck with Local network off would say too.
+
+let _status = null;
+
+/** lan-deck.mjs's, once, as it loads. */
+export function connectLanStatus(status) {
+  _status = typeof status === "function" ? status : null;
+}
+
+/** namesByAccount over the engine's status as it is now. Never throws: a
+ *  status that could not be read is a deck that knows of nobody. */
+export function elsewhereNow(now = Date.now()) {
+  try {
+    return _status ? namesByAccount(_status(), now) : new Map();
+  } catch {
+    return new Map();
+  }
+}

package/src/server/lan-engine.mjs

@@ -107,7 +107,7 @@ export function defaultName() {
  *
  * It returned the first one, and that was wrong the first time somebody
  * checked: on this machine the first is 192.168.1.82 and the deck it needs to
- * reach is on Tailscale at 100.67.32.58, so the panel would have offered an
+ * reach is on Tailscale at 100.64.0.100, so the panel would have offered an
  * address that peer cannot route to and left them to work out why.
  *
  * WHICH ONE IS RIGHT DEPENDS ON WHERE THE PEER IS, which this side cannot
@@ -654,7 +654,7 @@ export function createEngine({
       // WHO IS ACTUALLY THERE. A typed address is a row that says `192.168.1.5:54340`
       // and nothing else until somebody answers it — and once one has, the deck
       // on the other end has told us what it calls itself. The row says that
-      // from then on, because "Constantin-PC" is what the person who typed the
+      // from then on, because "Consultant-PC" is what the person who typed the
       // address was trying to reach.
       //
       // A DIAL-BACK THAT ANSWERED IS AN ORDINARY PEER NOW. It was on trial only

package/src/server/lan-sync.mjs

@@ -288,8 +288,8 @@ function machineKey() {
  * The part of a hostname that names the machine, rather than the network it is
  * on at the moment.
  *
- * macOS answers `os.hostname()` with `Petrus-MacBook-Pro.local` at one moment
- * and `Petrus-MacBook-Pro` at another, and a DHCP server can hang its own
+ * macOS answers `os.hostname()` with `Oswald-MacBook-Pro.local` at one moment
+ * and `Oswald-MacBook-Pro` at another, and a DHCP server can hang its own
  * domain on the end — `.lan`, `.home`, `.fritz.box`. hostId hashed whatever it
  * was handed, so two decks on one computer started either side of such a change
  * disagreed about which machine they were on. Sharing a key, each read the other
@@ -418,7 +418,7 @@ export function beaconVerdict(beacon, { selfFp, selfInstance, selfHost, formerHo
     // taking a new key is the engine's to do.
     //
     // AND ONE MACHINE'S OWN TWIN IS NOT A CLASH, which is the whole of a defect
-    // reported as "Fiodor pressed yes ten times and it keeps asking". Several
+    // reported as "Elliot pressed yes ten times and it keeps asking". Several
     // decks on one computer share a config directory, so they start with one
     // key; each read the others' beacons as somebody wearing its name, each
     // took a fresh key, each wrote that key to the file the others read — and

package/src/server/lan-wire.mjs

@@ -397,9 +397,9 @@ export function credentialAad(fromFp, toFp, key) {
 // two engines of the version before this, the round that healed one account
 // and added another read, after `ok`:
 //
-//   {"t":"manifest","accounts":[{"key":"claude1@sapec.md@@org-1","email":"claude1@sapec.md","alive":true},…],"current":{"key":"claude1@sapec.md@@org-1"}}
-//   {"t":"want","key":"claude2@sapec.md@@org-2","nonce":"…","proof":"…"}
-//   {"t":"have","key":"claude2@sapec.md@@org-2","sealed":{…}}
+//   {"t":"manifest","accounts":[{"key":"alice@example.net@@org-1","email":"alice@example.net","alive":true},…],"current":{"key":"alice@example.net@@org-1"}}
+//   {"t":"want","key":"bob@example.net@@org-2","nonce":"…","proof":"…"}
+//   {"t":"have","key":"bob@example.net@@org-2","sealed":{…}}
 //
 // So anybody on the same network segment could read every address a deck
 // shares, which of its copies are broken, which one the machine is on, and

package/src/server/login-guard.mjs

@@ -0,0 +1,162 @@
+// Never put a dead login under every session on the machine (#2184).
+//
+// Every Claude Code session on a machine shares one login. `cswap switch N`
+// writes slot N's stored copy over it, and when that copy's refresh token is
+// already dead every running session fails within seconds with "Login expired ·
+// Please run /login". On the owner's machine that was three of the seven login
+// interruptions in the month before this was written.
+//
+// claude-swap's own `auto` engine refreshes a target before it activates it and
+// quarantines one whose refresh is refused. A plain `cswap switch` does neither,
+// and that is the command the deck runs. So the deck asks claude-swap's store
+// first, and refuses only on evidence: a dead-login error on the slot's own
+// usage row, newer than the last good read and the last sign-in. Anything it
+// cannot tell — no row, a row for somebody else, a store it cannot read — lets
+// the switch go ahead exactly as it did before.
+//
+// WHY NOT ASK CLAUDE-SWAP ABOUT ONE SLOT. 0.26.0 has no command that checks a
+// single account. `cswap list --json` is the nearest: a collection over every
+// account that is due, under claude-swap's own locks, which refreshes an
+// expired stored token through its one-time-grant gate and strikes the slot
+// when the refresh is refused. It never re-reads a slot it has already struck,
+// and it skips one its plan says is not due. So the deck asks for one only when
+// it would actually read the target (collectionWouldRead) — the 2026-10-12
+// incident was exactly that case: slot 5 last read ten minutes earlier, its
+// poll overdue, and the refusal that proved its login dead recorded one second
+// AFTER the switch had put it live.
+//
+// Pure: no file, no clock, no subprocess. claude-accounts.mjs reads the store
+// and asks these, and account-routes.mjs hands removeLeavingLiveLogin its three
+// steps.
+
+/** claude-swap's two words for a stored refresh token only a sign-in can
+ *  replace — its PERMANENT_AUTH_ERRORS. The panel says "login expired". */
+export const DEAD_LOGIN_ERRORS = new Set(["invalid_grant", "no_refresh_token"]);
+
+/** claude-swap's SERVE_TTL_S: younger than this, an on-demand collection
+ *  serves the row from the store and fetches nothing. */
+const SERVE_TTL_MS = 180_000;
+
+/** A claude-swap timestamp (epoch seconds) in ms, or null. */
+function ms(seconds) {
+  const v = typeof seconds === "number" ? seconds * 1000 : NaN;
+  return Number.isFinite(v) && v > 0 ? v : null;
+}
+
+/**
+ * Whether a slot's stored login is KNOWN dead, from its usage row.
+ *
+ * `matches` is rowIsFor's answer — a row left by the slot's previous occupant
+ * says nothing about this one. `signedInAt` is when the deck last signed this
+ * account in, in ms, or null.
+ *
+ * Dead is claude-swap's strike (`authDeadStrikes`, set by an `invalid_grant` or
+ * `no_refresh_token` and lifted by a good read or by any write of a new
+ * credential — add, import, a sign-in) or that error on a failing row, from a
+ * store that predates the strike count. And only when the refusal is the newest
+ * thing known about the login: a good read or a sign-in after it is about a
+ * login that has since worked. Transient errors — a 429, a timeout, a network
+ * that is not there — are never evidence either way.
+ *
+ * Answers `{ error, since }`, `since` being when the refusal was recorded (ms,
+ * or null when the row does not say), or null.
+ */
+export function deadLoginOf(row, { matches = false, signedInAt = null } = {}) {
+  if (!matches || !row || typeof row !== "object") return null;
+  const struck = Number(row.authDeadStrikes) >= 1;
+  const refused = Number(row.consecutiveFailures) > 0 && DEAD_LOGIN_ERRORS.has(row.lastError);
+  if (!struck && !refused) return null;
+  const failedAt = ms(row.lastAttemptAt);
+  const goodAt = ms(row.fetchedAt);
+  if (failedAt != null && goodAt != null && goodAt > failedAt) return null;
+  if (failedAt != null && Number.isFinite(signedInAt) && signedInAt > failedAt) return null;
+  return { error: DEAD_LOGIN_ERRORS.has(row.lastError) ? row.lastError : "invalid_grant", since: failedAt };
+}
+
+/**
+ * Whether a `cswap list` asked for right now would read this row — claude-swap's
+ * own on-demand rule (usage_store._row_eligible with respect_plans), so the deck
+ * spends a collection on a switch only when it can change the answer.
+ *
+ * No row, or one for somebody else, is read on the first pass. A struck row is
+ * never read again, a row in backoff or claimed by another collector waits, and
+ * otherwise it must be both older than the serve TTL and past its planned poll.
+ */
+export function collectionWouldRead(row, { matches = false, now }) {
+  if (!matches || !row || typeof row !== "object") return true;
+  if (Number(row.authDeadStrikes) >= 1) return false;
+  const backoff = ms(row.backoffUntil);
+  if (backoff != null && backoff > now) return false;
+  const claim = ms(row.claimUntil);
+  if (claim != null && claim > now) return false;
+  const fetched = ms(row.fetchedAt);
+  const next = ms(row.nextPollAt);
+  return (fetched == null || now - fetched > SERVE_TTL_MS) && (next == null || now >= next);
+}
+
+// ── removing the active account ─────────────────────────────────────────────
+//
+// `cswap remove` deletes the slot's stored copy and its entry, and nothing else:
+// it does not activate another slot, and Claude Code stays signed in as the
+// account that was removed. When that login works, that is the right thing to
+// leave alone — every session goes on running. When it is the expired one, the
+// sessions are already failing and nothing would ever move them: auto-switch
+// will not touch a login claude-swap no longer manages. So then, and only then,
+// the deck moves Claude Code to a working account once the removal has landed.
+// After it, the dead login belongs to no slot, so `cswap switch` activates the
+// target directly instead of refusing to back up the empty login first.
+
+/** The roster's active row when its login is one only a sign-in brings back —
+ *  the panel's "Login expired" on the live account. Never a stale copy (#721):
+ *  there the user IS signed in, and only claude-swap's copy is dead. */
+export function activeLoginExpired(row) {
+  if (!row?.active || row.staleCopy) return false;
+  if (row.stopped) return row.collector === "relogin_required";
+  return DEAD_LOGIN_ERRORS.has(row.error);
+}
+
+/** The accounts Claude Code may be moved to, best first: working, not held
+ *  out, and with nothing wrong on the row — the freshest reading first, then the
+ *  most room. `held` is the slots no move the deck makes may land on: set aside
+ *  by claude-swap's engine, or in use by a local `cswap run` session
+ *  (cswap-auto-choice.mjs slotsHeldBack). */
+export function liveTargets(accounts, leaving, held = new Set()) {
+  return (Array.isArray(accounts) ? accounts : [])
+    .filter(a => a && a.num !== leaving && !a.active && !a.disabled && a.alive === true
+      && !a.staleCopy && !a.stopped && !a.error && !held.has(a.num))
+    .sort((a, b) => Number(a.stale === true) - Number(b.stale === true) || (b.headroom ?? -1) - (a.headroom ?? -1));
+}
+
+/** How many accounts a removal tries before it says none would take over. Each
+ *  try can wait on a collection, and a store full of dead logins is a sign-in's
+ *  job, not a walk through every slot. */
+const MOVE_TRIES = 3;
+
+/**
+ * Remove an account, and when it was the active one with its login expired,
+ * move Claude Code to a working account afterwards.
+ *
+ * `roster()` is the roster as it stood before the removal, `remove(num)` is
+ * cswap-admin's removeAccount and `switchTo(num)` the switch route's own path,
+ * guard included. `heldBack(accounts)` names the slots the move may not land
+ * on (liveTargets); one it cannot read holds nothing back. Answers the
+ * removal's own answer, plus `movedTo` (the account now active) or
+ * `stillExpired` (nothing could take over).
+ */
+export async function removeLeavingLiveLogin(num, { roster, remove, switchTo, heldBack = async () => new Set() }) {
+  const before = await Promise.resolve().then(roster).catch(() => null);
+  const removed = await remove(num);
+  if (!removed?.ok) return removed;
+  const accounts = before?.ok && Array.isArray(before.accounts) ? before.accounts : [];
+  const row = accounts.find(a => a?.num === Number(num));
+  if (!activeLoginExpired(row)) return removed;
+  const held = await Promise.resolve().then(() => heldBack(accounts)).catch(() => null);
+  for (const target of liveTargets(accounts, row.num, held instanceof Set ? held : new Set()).slice(0, MOVE_TRIES)) {
+    const moved = await Promise.resolve().then(() => switchTo(target.num)).catch(() => null);
+    if (moved?.ok) return { ...removed, movedTo: { num: target.num, email: target.email ?? null, alias: target.alias ?? null } };
+    // Only a target refused for its own login is a reason to try the next one.
+    // Anything else — no claude-swap, a timeout — would refuse the next as well.
+    if (moved?.reason !== "login_expired") break;
+  }
+  return { ...removed, stillExpired: true };
+}

package/src/server/login-service.mjs

@@ -403,6 +403,9 @@ export const SETTING_VARS = Object.freeze([
   "AGENTS_DECK_NO_INSTALL", "AGENTS_DECK_NO_DOWNLOAD", "AGENTS_DECK_NO_UPDATE_CHECK", "AGENTS_DECK_NO_STATUS",
   "AGENTS_DECK_NO_FRESHEN", "AGENTS_DECK_NO_NOTIFY", "AGENTS_DECK_NO_LAN", "AGENTS_DECK_NO_REPORTS",
   "AGENTS_DECK_CSWAP", "AGENTS_DECK_CLAUDE", "AGENTS_DECK_CCUSAGE", "CLAUDE_SWAP_BACKUP", "AGENTS_DECK_LHM_PORT",
+  // The opt-in for Skill activity's typed-command hook (skill-hook.mjs). A deck
+  // started at login without it would take the entry back out.
+  "AGENTS_DECK_SKILL_HOOK",
 ]);
 
 export function settingsEnv(env = process.env) {