agent-dag 1.42.0 → 1.44.1

package/src/server/cswap-admin.mjs

@@ -17,10 +17,13 @@
 // first account's record. Nothing upstream prevents it, so every mutation here
 // goes through one mutex.
 import { AsyncLocalStorage } from "node:async_hooks";
+import { existsSync } from "node:fs";
 import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
 import { join } from "node:path";
-import { looksMissing, run, runDetached, runInteractive } from "./exec.mjs";
+import { looksMissing, pathLookup, run, runDetached, runInteractive } from "./exec.mjs";
 import { backupRoot, invalidateClaudeAccountsCache } from "./claude-accounts.mjs";
+import { claudeCliCandidates } from "./claude-dir.mjs";
 import { cswapBin } from "./cswap-install.mjs";
 import { PRODUCT } from "./brand.mjs";
 
@@ -77,8 +80,79 @@ export function withStoreLock(fn) {
 // import, remove, rename, reorder — failed with cmd.exe's "is not recognized",
 // while the read-only half of the panel worked, because it was already using
 // the resolver. Reported from Windows on 2026-08-14.
+
+/**
+ * Which `claude` the account surface runs: the configured one, else the first
+ * candidate this machine actually has, else the bare name.
+ *
+ * WHY THIS IS NOT `AGENTS_DECK_CLAUDE ?? "claude"` ANY MORE (#570). That was
+ * the whole of this module's resolution, and it feeds every child the accounts
+ * panel starts — `claude auth status --json` for `currentIdentity`, and the
+ * `claude auth login` whose output the sign-in dialog reads a link out of. On a
+ * machine whose `claude` is at `~/.local/bin/claude` but whose deck was started
+ * from something that never sourced a shell rc — a LaunchAgent, a systemd user
+ * unit, pm2, a desktop shortcut — the bare name is an ENOENT, so the login
+ * child is dead within milliseconds, the flow reports `no_url`, and the dialog
+ * shows "the claude CLI could not be run: not on PATH. Set AGENTS_DECK_CLAUDE
+ * to its full path." That sentence is a real remedy and it is why this was a
+ * smaller bug than #553; it is still a request to spell out a path the deck had
+ * already found for itself, because `hasClaudeInstalled()` stat'ed that exact
+ * file at boot to decide this was a Claude machine, and since #553 the quota
+ * panel beside this one runs the same binary without being told anything.
+ *
+ * SO IT READS THE SAME LIST, ON THE SAME TERMS #553 SETTLED ON. The list is
+ * `claudeCliCandidates` in claude-dir.mjs, whose other two readers are
+ * `hasClaudeInstalled()` — the boot question this module's whole surface hangs
+ * off — and `quotaClaudeBin` in quota.mjs. This is the same question at a third
+ * site, so nothing here is decided again:
+ *
+ *   - AGENTS_DECK_CLAUDE first, and it is the one thing that skips the list
+ *     entirely. It is documented in the README as "full path to the `claude`
+ *     CLI", it is what the failure message above tells people to set, and
+ *     someone who set it has already been through this once — second-guessing
+ *     them with a stat would be answering a question they have closed. An empty
+ *     value reads as unset, the way `AGENTS_DECK_CSWAP` does in cswapBin.
+ *   - Then the candidate list's own order, unchanged: PATH first on POSIX, the
+ *     two known install directories first on Windows. Preferring a different
+ *     copy would silently change which binary signs somebody in on every
+ *     machine that has two, and a `claude auth login` that suddenly runs a
+ *     different binary is a credential path, not a detail.
+ *   - The bare name is only answered with when PATH actually holds it, and
+ *     `pathLookup` is a yes/no gate rather than the path it found, so spawn's
+ *     own resolution — and, on Windows, exec.mjs's PATHEXT walk, since `claude`
+ *     there is `claude.exe` or `claude.cmd` and never the bare word — stays in
+ *     charge of the PATH case exactly as before.
+ *   - The absolute candidates are stat'ed only once PATH has come up empty, so
+ *     the common case costs one stat rather than a directory walk. Against what
+ *     follows it — a whole Claude Code process, and a browser sign-in a human
+ *     is walking through — that is not a cost worth naming.
+ *
+ * Pure, with the platform, environment, home directory and existence check all
+ * parameters, so the Windows branch is checkable from the platforms this repo
+ * is actually developed on. Exported for that test rather than for a caller
+ * (#383): `claudeBin` below is the only one, and it hands back the real
+ * machine's answer.
+ */
+export function adminClaudeBin(platform = process.platform, env = process.env,
+                               home = homedir(), exists = existsSync) {
+  if (env.AGENTS_DECK_CLAUDE) return env.AGENTS_DECK_CLAUDE;
+  const sep = platform === "win32" ? "\\" : "/";
+  // process.env is case-insensitive on Windows; an injected plain object in a
+  // test is not, and %Path% is how the variable is actually spelled there.
+  const pathEnv = env.PATH ?? env.Path ?? env.path ?? "";
+  for (const c of claudeCliCandidates(platform, env, home)) {
+    if (c.includes(sep)) { if (exists(c)) return c; }
+    else if (pathLookup(c, platform, { pathEnv, exists })) return c;
+  }
+  // Nothing on PATH and nothing at any known install directory. The bare name
+  // is still the right last resort — POSIX `execvp` and cmd.exe's own search
+  // both deserve their turn at a layout no list here knows — and the ENOENT it
+  // produces is what failureText turns into the AGENTS_DECK_CLAUDE sentence.
+  return "claude";
+}
+
 async function claudeBin() {
-  return process.env.AGENTS_DECK_CLAUDE ?? "claude";
+  return adminClaudeBin();
 }
 
 /** Slot → email for everything currently in the store, plus the active slot. */
@@ -212,7 +286,71 @@ export function loginState() {
   return { state, url: url ?? null, error: error ?? null, account: account ?? null, expiresAt: expiresAt ?? null };
 }
 
+/**
+ * What an address may be made of before it becomes an argv element.
+ *
+ * NOT AN RFC 5322 PARSER, and it should not be read as one. RFC 5322 permits
+ * quoted local parts, spaces inside them, comments in parentheses and bracketed
+ * address literals; a regex that accepted all of that would accept precisely the
+ * shapes this exists to keep out. The job here is narrower and worth stating
+ * plainly: keep a FLAG-SHAPED or WHITESPACE-BEARING string out of a spawn's
+ * argument vector. Anything it wrongly refuses is an address nobody has ever
+ * typed into this dialog; anything it wrongly accepts is inert as an argument,
+ * which is the only property being defended. Whether the address exists is
+ * Anthropic's question, asked a moment later by the CLI itself.
+ *
+ * `--email` was the field the alias allowlist below missed. `email.includes("@")`
+ * was the whole of its validation and the value came straight off the request
+ * body, so the two residuals exec.mjs documents were both reachable through it
+ * on Windows, where `claude` is a `.cmd` shim and the vector goes through
+ * `cmd.exe /d /s /c`: an interior newline is a command separator inside that one
+ * quoted line, and `%USERPROFILE%` expands inside quotes with no escape
+ * available. `"a@b\ncalc.exe"` and `"%USERPROFILE%@x"` both satisfy
+ * `includes("@")`, and both are payloads alias-charset.test.ts already pins as
+ * refused for the other field.
+ *
+ * The leading-character rule is the same argv-position rule ALIAS_OK now carries.
+ * `-x@y.z` starts with a dash, so a child parser reads it as an option rather
+ * than as the value of `--email`, and what happens next depends entirely on
+ * which options that CLI happens to define.
+ */
+const EMAIL_OK =
+  /^[A-Za-z0-9][A-Za-z0-9._%+-]{0,63}@[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?(?:\.[A-Za-z0-9](?:[A-Za-z0-9-]{0,61}[A-Za-z0-9])?)+$/;
+
+// The SMTP forward-path limit. The pattern above bounds each PIECE — 64 for the
+// local part, 63 per label — and a domain may carry any number of labels, so
+// without this the whole is unbounded. A bound belongs here for the reason
+// ALIAS_OK has one: on Windows the value ends up inside a single cmd.exe command
+// line, which has a hard length limit of its own.
+const EMAIL_MAX_LENGTH = 254;
+
+/**
+ * The `--email` value `claude auth login` should be given, or a refusal.
+ *
+ * Three answers rather than two, and the third is the one that matters: `null`
+ * means NO ADDRESS WAS OFFERED, which is the only shape the deck's own dialog
+ * sends (`AddAccountDialog` posts a bare `{action:"login"}`) and which must stay
+ * an ordinary sign-in with no flag appended. A value that is present and
+ * unusable is refused outright instead of being quietly dropped: dropping it
+ * would run a DIFFERENT sign-in from the one that was asked for and call it a
+ * success, and this route is reachable by anything holding the deck token.
+ */
+function loginEmailArg(email) {
+  if (email == null) return { ok: true, email: null };
+  if (typeof email !== "string") return { ok: false };
+  const clean = email.trim();
+  if (!clean) return { ok: true, email: null };
+  if (clean.length > EMAIL_MAX_LENGTH || !EMAIL_OK.test(clean)) return { ok: false };
+  return { ok: true, email: clean };
+}
+
 export async function startLogin({ email } = {}) {
+  // Argv position is settled first, before any state moves. A refusal here must
+  // not cancel a sign-in that is already running — the caller asked for
+  // something the deck will not do, and the flow already in flight is not part
+  // of that bargain.
+  const wanted = loginEmailArg(email);
+  if (!wanted.ok) return { ok: false, reason: "bad_email", ...loginState() };
   // Registering is the half that writes to the store; interrupting it would
   // leave an account half-recorded, so that one is refused. A flow merely
   // waiting for a code is not precious — it is most often the one abandoned by
@@ -225,7 +363,7 @@ export async function startLogin({ email } = {}) {
     await cancelLogin();
   }
   if (!_starting) {
-    _starting = spawnLogin(email).finally(() => { _starting = null; });
+    _starting = spawnLogin(wanted.email).finally(() => { _starting = null; });
   }
   const flow = await _starting;
 
@@ -277,7 +415,10 @@ async function spawnLogin(email) {
   const identity = await currentIdentity();
 
   const args = ["auth", "login"];
-  if (typeof email === "string" && email.includes("@")) args.push("--email", email);
+  // Already through loginEmailArg, which is the only caller's boundary: this is
+  // either an address that cannot be read as a flag or null, and null is the
+  // ordinary case.
+  if (email) args.push("--email", email);
 
   const child = runInteractive(await claudeBin(), args, { timeout: LOGIN_TIMEOUT_MS });
   // A sign-in outlives the request that started it, so it can also outlive the
@@ -600,8 +741,34 @@ export async function removeAccount(num) {
  * list, and it closes the unbounded-length half too: an alias is a short name
  * shown instead of an email, so 64 characters is not a constraint anyone meets
  * by accident.
+ *
+ * The leading `(?!-)` is the half that allowlist missed, and it is not about
+ * quoting at all — it is about ARGV POSITION, which no amount of quoting fixes
+ * because the value arrives intact and is then read as syntax by the CHILD.
+ * `-` is in the character class, so `--unset` matched, and
+ * `setAlias(3, "--unset")` built ["alias", "3", "--unset"] — character for
+ * character claude-swap's own command for CLEARING an alias. Its `_alias_command`
+ * hands that vector to argparse, which sets `unset=True` and leaves `alias_name`
+ * as None; the store dropped the name, cswap printed "Removed alias for
+ * Account 3", exited 0, and the deck reported the rename as a success. Any other
+ * `-x` spelling is consumed the same way — `-h` prints help and exits 0, which
+ * also arrives here as a rename that worked.
+ *
+ * argparse does honour `--` as an end-of-options separator, so
+ * ["alias", "3", "--", "--unset"] would reach `set_alias` as data. It is
+ * deliberately not used: the separator only helps for the one child whose parser
+ * we can read, `claude auth login` is the other spawn on this route and its
+ * parser is not ours to verify, and a value the deck refuses outright cannot be
+ * mangled by a CLI that changes its mind later. The validator is the guard.
+ *
+ * Refusing a leading dash rather than requiring a leading alphanumeric is the
+ * narrower rule, and it is the one the hazard actually describes: `.env` and
+ * `_work` are ordinary positional arguments to every parser involved, while
+ * `acme-corp` — the one dash-bearing name in alias-charset.test.ts's list of
+ * names people use — keeps working because only the FIRST character is
+ * constrained.
  */
-const ALIAS_OK = /^[A-Za-z0-9 ._-]{1,64}$/;
+const ALIAS_OK = /^(?!-)[A-Za-z0-9 ._-]{1,64}$/;
 
 export async function setAlias(num, alias) {
   const n = Number(num);
@@ -675,11 +842,18 @@ export async function moveAccount(num, slot) {
  * Windows it is cmd.exe's two-line "is not recognized …/operable program or
  * batch file.", and `firstUseful` — which takes the LAST line, correctly for
  * every other CLI — leaves the second half on screen by itself.
+ *
+ * The exit status goes to looksMissing beside the text (#552). This is the one
+ * caller with no candidate spelling to compare against, so the shape rules alone
+ * are all the TEXT can offer it — and on a non-English Windows the text says
+ * nothing this recognises. The status does: 9009 is cmd.exe's "no such command"
+ * in every language. Without it, a German user pressing "share…" got the last
+ * line of a translated sentence instead of the sentence about PATH.
  */
 export function failureText(r, what = "cswap") {
   const out = `${r?.stderr ?? ""}\n${r?.stdout ?? ""}`;
   const tool = String(what).split(" ")[0];
-  if (r?.code === "ENOENT" || looksMissing(out)) {
+  if (r?.code === "ENOENT" || looksMissing(out, "", r?.code)) {
     return tool === "claude"
       ? "the claude CLI could not be run: not on PATH. Set AGENTS_DECK_CLAUDE to its full path."
       : "cswap could not be run: not on PATH, and not in the places uv and pipx install to. Set AGENTS_DECK_CSWAP to its full path.";

package/src/server/cswap-auto.mjs

@@ -11,6 +11,8 @@
 // on and the setting survives restarts.
 import { run } from "./exec.mjs";
 import { cswapBin } from "./cswap-install.mjs";
+import { invalidateClaudeAccountsCache } from "./claude-accounts.mjs";
+import { invalidateQuotaCache } from "./quota.mjs";
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
 import { homedir } from "node:os";
@@ -62,6 +64,29 @@ export async function readCswapConfig() {
   return out;
 }
 
+/**
+ * What the model list may be made of before it becomes an argv element.
+ *
+ * The character class is the same one this field has always had — a
+ * comma-separated list of plain model names, bounded at 120 — with the one rule
+ * #543 wrote down at cswap-admin.mjs's EMAIL_OK added to the front: *"The
+ * leading-character rule is the same argv-position rule ALIAS_OK now carries."*
+ *
+ * This is the THIRD free-text field to reach an argument vector and the first
+ * one that pass missed, because it lives in a different module. It is not a
+ * different question. `{ key: "autoswitch.model", value: "-h" }` produced
+ * `cswap config set autoswitch.model -h`; argparse on the other side reads the
+ * leading dash as an option rather than as data, prints help, exits 0 — so
+ * `r.ok` is true and the deck reports a setting saved that was never written,
+ * after which the panel's optimistic value disagrees with the next read (#584).
+ *
+ * Only the first character is constrained, so `claude-3-5-sonnet` and every
+ * other dash-bearing model name still works. cswap-argv-position.test.ts
+ * enumerates every field this rule covers, so a fourth cannot be added without
+ * one.
+ */
+const MODEL_LIST_OK = /^(?!-)[A-Za-z0-9 ,._-]{1,120}$/;
+
 /** Validate against SETTINGS, then hand to `cswap config set`. */
 export async function setCswapConfig(key, value) {
   const spec = SETTINGS[key];
@@ -78,7 +103,7 @@ export async function setCswapConfig(key, value) {
   } else {
     // Model names: a comma-separated list of plain words, or "all".
     str = String(value ?? "").trim();
-    if (str && !/^[A-Za-z0-9 ,._-]{1,120}$/.test(str)) return { ok: false, reason: "bad_value" };
+    if (str && !MODEL_LIST_OK.test(str)) return { ok: false, reason: "bad_value" };
   }
 
   const r = await run(await cswapBin(), ["config", "set", key, str]);
@@ -98,6 +123,14 @@ function summarise(stdout) {
 
   return {
     event:     action?.event ?? "no-switch",
+    // Whether the LIVE ACCOUNT MOVED, which is a narrower question than which
+    // event came last and the only one the caches care about. Taken over every
+    // event rather than over `action`, so a quarantine or an error emitted after
+    // the switch cannot hide it; and `dryRun` is checked even though this
+    // module's ticks never pass `--dry-run`, because the engine emits the same
+    // `switch` event for a decision it did not carry out, and a false positive
+    // here throws away readings that cost a subprocess each.
+    switched:  events.some(e => e.event === "switch" && e.dryRun !== true),
     reason:    action?.reason ?? null,
     detail:    action?.detail ?? null,
     from:      action?.from ?? null,
@@ -120,6 +153,68 @@ async function runAutoTick() {
 
 // ── external engine detection ──────────────────────────────────────────────
 
+/**
+ * One command line, as a list of the words a process was actually launched
+ * with.
+ *
+ * The quote characters are separators here, not delimiters, and that is the
+ * whole point of #552. `Win32_Process.CommandLine` reports what the CREATOR
+ * wrote, and every launcher on Windows except a human typing at `cmd.exe`
+ * quotes the executable:
+ *
+ *     "C:\Users\dorin\.local\bin\cswap.exe" auto
+ *
+ * — which is what .NET's `Process.Start` writes, so PowerShell, Windows
+ * Terminal's default profile, Task Scheduler and an Explorer shortcut all
+ * produce it. A pattern that wanted whitespace immediately after `cswap.exe`
+ * saw a `"` there and answered no, for every one of them.
+ *
+ * The deck's own spawns are the same shape from the other side: viaCmd in
+ * src/server/exec.mjs launches a `.cmd` shim as
+ * `cmd.exe /d /s /c ""C:\…\cswap.cmd" "auto" "--once""`, with the whole line
+ * wrapped in one more pair of quotes because that is what `cmd /c` wants.
+ * Treating `"` as a separator takes both apart with no parser and no knowledge
+ * of which launcher wrote the line — the outer pair, the per-argument pairs and
+ * the bare case all collapse to the same token list.
+ *
+ * What it deliberately does NOT do is respect a quoted path containing spaces:
+ * `"C:\Program Files\cswap\cswap.exe" auto` splits into three tokens rather than
+ * two. That costs nothing here — the tail token is still `cswap.exe` followed by
+ * `auto`, which is the only question asked — and the alternative is a real
+ * command-line parser for a probe whose wrong answer must never be a crash.
+ */
+export function commandTokens(line) {
+  return String(line ?? "").split(/["\s]+/).filter(Boolean);
+}
+
+/** The last path component of a token: `C:\bin\cswap.exe` → `cswap.exe`. */
+const leaf = (token) => token.split(/[\\/]/).pop() ?? "";
+
+/** Every spelling of the executable, on every platform. */
+const CSWAP_EXE = /^cswap(\.exe|\.cmd|\.bat)?$/i;
+
+/**
+ * True when this command line is a long-lived `cswap auto` loop.
+ *
+ * The rule, stated over tokens rather than characters: some token IS the cswap
+ * executable — its last path component, so `/opt/bin/mycswap` and `notcswap`
+ * are somebody else's program — and the token straight after it is exactly
+ * `auto`, so `autopilot` and `automate` are not this. `--once` anywhere rules
+ * the line out: the deck's own ticks carry it, and so does a cron user's.
+ *
+ * Pure and exported so the Windows shapes can be checked from a Mac. The
+ * residual false positive is a line that mentions cswap as an ARGUMENT and then
+ * `auto` — `myprog --exe cswap auto`. That direction is the safe one: a wrong
+ * `true` is a deck that stays quiet, while a wrong `false` is two engines moving
+ * the same live Claude account.
+ */
+export function looksLikeAutoLoop(line) {
+  if (/--once/i.test(String(line ?? ""))) return false;
+  const tokens = commandTokens(line);
+  return tokens.some((token, i) =>
+    CSWAP_EXE.test(leaf(token)) && String(tokens[i + 1] ?? "").toLowerCase() === "auto");
+}
+
 /**
  * True when the user is already running `cswap auto` themselves.
  *
@@ -138,17 +233,25 @@ async function runAutoTick() {
  */
 export async function externalAutoRunning() {
   // A line is the user's loop if it runs `cswap auto` without --once. Our own
-  // ticks are --once, and so is a cron user's.
-  const isLoop = (line) => /(^|[\\/])cswap(\.exe|\.cmd|\.bat)?\s+auto(\s|$)/i.test(line.trim())
-                        && !/--once/i.test(line);
+  // ticks are --once, and so is a cron user's. See looksLikeAutoLoop.
+  const isLoop = looksLikeAutoLoop;
 
   if (process.platform === "win32") {
     // No `ps` on Windows, and `tasklist` reports the image name only — every
     // Python tool shows up as python.exe, which cannot tell cswap from
     // anything else. CIM is the one place the full command line is available.
+    //
+    // `Out-String -Width 32767` is not decoration. `-ExpandProperty` emits
+    // strings, and strings leave PowerShell through its console FORMATTER,
+    // which hard-wraps at the host buffer width — 80 columns on a redirected
+    // stdout, which is what a spawned child always has. A real command line
+    // (`"C:\Users\dorin\AppData\Local\Programs\Python\Python312\Scripts\cswap.exe" auto`)
+    // is longer than that, so the executable and its subcommand arrived on
+    // SEPARATE LINES and no per-line match could ever see both. 32767 is the
+    // maximum length Windows allows a command line, so nothing real can wrap.
     const r = await run("powershell.exe", [
       "-NoProfile", "-NonInteractive", "-Command",
-      "Get-CimInstance Win32_Process | Select-Object -ExpandProperty CommandLine",
+      "Get-CimInstance Win32_Process | Select-Object -ExpandProperty CommandLine | Out-String -Width 32767",
     ], { timeout: 8_000 });
     if (!r.ok) return false;   // no PowerShell, or the query was refused
     return r.stdout.split("\n").some(isLoop);
@@ -166,6 +269,12 @@ export async function externalAutoRunning() {
 let _timer   = null;
 let _lastTick = null;
 let _enabled  = false;
+// Set the instant startLoop is entered and cleared when it settles, because
+// `_timer` cannot do that job: it is assigned AFTER an await, and the window in
+// between is what #537 was. See startLoop.
+let _starting = false;
+// The tick in flight, so the interval can skip rather than stack. See tick.
+let _ticking = null;
 
 async function loadState() {
   try { return JSON.parse(await readFile(STATE_PATH, "utf8")); } catch { return {}; }
@@ -183,7 +292,31 @@ async function tickInterval() {
   return Math.max(MIN_INTERVAL_S, Number.isFinite(raw) ? raw : 60) * 1000;
 }
 
-async function tick() {
+/**
+ * Everything the deck holds that belongs to ONE Claude account, dropped.
+ *
+ * The accounts roster is keyed on whichever account claude-swap says is active,
+ * and every quota percentage was read for whoever was active when it was
+ * collected. A switch makes both of them the wrong account's, and neither cache
+ * has any way to find that out for itself: they are refreshed on timers, by
+ * panels that were not told.
+ *
+ * The two caches decay at very different rates, which is why saying nothing was
+ * visibly wrong rather than briefly wrong. claude-accounts.mjs holds its roster
+ * for CACHE_MS = 5s, so the panel flips to the new account almost at once, while
+ * quota.mjs holds its result for a CACHE_MS of its own = 60s — and `_lastGood`
+ * outlives even that, coming back under a "stale" label every five seconds until
+ * the store has something to say about the account the deck moved TO. So for up
+ * to a minute, and for longer than that in the fallback, two panels on one screen
+ * described two different accounts, and the wrong one was the big quota bars:
+ * sitting at the 90% that triggered the switch, for an account nobody is on.
+ */
+function forgetAccountScopedCaches() {
+  invalidateClaudeAccountsCache();
+  invalidateQuotaCache();
+}
+
+async function runTick() {
   // Re-check each time: the user can start their own loop at any point, and
   // the deck should fall silent rather than compete with it.
   if (await externalAutoRunning()) {
@@ -191,14 +324,80 @@ async function tick() {
     return;
   }
   const result = await runAutoTick();
+  // Before `_lastTick`, not after. This is the only path in the deck that moves
+  // the live account without a click behind it, so nothing else is in a position
+  // to make the call — and `_lastTick` is what /api/cswap-auto reports, so
+  // dropping the caches first means anything that can see the tick happened is
+  // already looking at caches that know about it.
+  //
+  // Only on a tick that actually switched. A tick is mostly a poll that decides
+  // to do nothing — cooldown, no candidates, nothing over the threshold — and
+  // invalidating on those would throw away readings the deck paid a subprocess
+  // for, every interval, forever.
+  if (result.switched) forgetAccountScopedCaches();
   _lastTick = { at: Date.now(), ...result };
 }
 
+/**
+ * One tick at a time, whatever the interval is.
+ *
+ * The interval floor is 15 seconds (MIN_INTERVAL_S, and SETTINGS allows exactly
+ * that), while a single tick can legitimately take 8 for externalAutoRunning's
+ * `Get-CimInstance`/`ps` plus 120 for runAutoTick's own timeout. Nothing capped
+ * the fan-out, so a slow `cswap auto --once` — one that is refreshing a token
+ * and switching an account — could have eight copies of itself running against
+ * each other two minutes later, each with a PowerShell process beside it on
+ * Windows. `_lastTick` was then written by whichever finished last rather than
+ * by the most recent tick, so the panel's "last tick" could go backwards.
+ *
+ * A skipped tick is not a lost one: the next interval is at most 15 seconds
+ * away, and the work this schedules is idempotent by design.
+ */
+function tick() {
+  if (_ticking) return _ticking;
+  _ticking = runTick().finally(() => { _ticking = null; });
+  return _ticking;
+}
+
+/**
+ * Start the deck-managed loop, at most once.
+ *
+ * `if (_timer) return` looked like a guard and was not one: `_timer` is assigned
+ * after `await tickInterval()`, which shells out to `cswap config`, so two
+ * callers could both be past the check before either had set it. Two ways in
+ * during that window, both reachable from the UI:
+ *
+ *   - enable then disable, a few hundred milliseconds apart. The disable set
+ *     `_enabled = false` and called stopLoop, which cleared nothing because
+ *     `_timer` was still null — and then the enable came back and installed the
+ *     interval. autoStatus() reported `enabled: false` and the toggle read off
+ *     while every tick went on running `cswap auto --once`, which switches the
+ *     user's live Claude account. A control that says it is off while it moves
+ *     credentials is the worst shape this bug could take.
+ *
+ *   - two enables (a double click, or two tabs). Two intervals, only the second
+ *     reachable from `_timer`, so the first could never be cleared again for the
+ *     life of the process.
+ *
+ * initCswapAuto is a third way in: index.mjs fires it unawaited while the server
+ * is already accepting requests.
+ *
+ * `_starting` is set before the await, so the guard covers the whole function.
+ * `_enabled` is re-read after it, because the answer may have changed while this
+ * was waiting on a subprocess — and a loop that installs itself after the user
+ * has turned it off is the same defect from the other side.
+ */
 async function startLoop() {
-  if (_timer) return;
-  const ms = await tickInterval();
-  _timer = setInterval(() => { tick().catch(() => {}); }, ms);
-  _timer.unref?.();
+  if (_timer || _starting) return;
+  _starting = true;
+  try {
+    const ms = await tickInterval();
+    if (!_enabled) return;   // turned off while we were asking cswap
+    _timer = setInterval(() => { tick().catch(() => {}); }, ms);
+    _timer.unref?.();
+  } finally {
+    _starting = false;
+  }
   tick().catch(() => {});   // don't make the user wait a full interval for the first one
 }