ccdeck 1.43.0 → 1.45.0

package/src/server/cswap-auto.mjs

@@ -0,0 +1,595 @@
+// Auto-switch controls: read and write claude-swap's autoswitch settings and
+// run a tick on a schedule.
+//
+// The engine is claude-swap's own — `cswap auto --once` evaluates one tick and
+// exits, honouring the cooldown, quarantine and poll-budget state it keeps in
+// its own files. Running that on an interval gets the same behaviour as the
+// long-lived `cswap auto` loop while leaving all the decisions with the tool
+// that owns them: nothing here decides when to switch, only when to ask.
+//
+// A tick can move the user's live Claude account, so it is off unless turned
+// 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";
+
+const STATE_DIR  = join(homedir(), ".agents-deck");
+const STATE_PATH = join(STATE_DIR, "cswap-auto.json");
+
+const TICK_TIMEOUT_MS = 120_000;   // a tick can refresh a token and switch
+const MIN_INTERVAL_S  = 15;        // claude-swap's own floor
+
+// Only these may be written, and only with a value of the right shape. The
+// value reaches an exec argument, and `cswap config set` will happily store
+// whatever it is handed.
+const SETTINGS = {
+  "autoswitch.threshold":       { type: "number", min: 50, max: 99.9 },
+  "autoswitch.intervalSeconds": { type: "number", min: 15, max: 3600 },
+  "autoswitch.cooldownSeconds": { type: "number", min: 0,  max: 86400 },
+  "autoswitch.hysteresisPct":   { type: "number", min: 0,  max: 50 },
+  "autoswitch.model":           { type: "model" },
+};
+
+// ── one reading at a time ──────────────────────────────────────────────────
+
+/**
+ * #616: /api/cswap-auto is a GET with no cache, no dedupe and no throttle, and
+ * autoStatus() runs BOTH of this module's readers on every one of them — so the
+ * number of children was exactly twice the number of requests.
+ *
+ * Measured on macOS with claude-swap installed, counting real children through a
+ * PATH shim: one autoStatus() is 2 children (`cswap config` and `ps -Ao args=`)
+ * and about 190ms warm; two back-to-back calls are 4; twenty-five concurrent
+ * readers produced 50 — twenty-five Python interpreters and twenty-five `ps` —
+ * and took 1.3 to 1.9s between them against 190ms for one, so the cost per
+ * reader grows rather than holds. With the guard below the same twenty-five are
+ * 2 children and 190ms, which is one reader's worth.
+ *
+ * On Windows the process-table half is `Get-CimInstance Win32_Process` through
+ * PowerShell, carrying an 8s deadline of its own, which is the same order of
+ * cost as the Get-Process #544 measured at about six seconds; and where cswap is
+ * not on PATH each call also re-pays cswapBin()'s probe, which memoizes only
+ * success and which `candidates` expands to four spellings there, two of them
+ * launched through cmd.exe.
+ *
+ * Two callers reach these without an attacker anywhere: AccountsPanel polls the
+ * route every 15s per open tab, and runTick asks externalAutoRunning() again
+ * before every tick. And it is a GET, so it passes isTrustedRead for any local
+ * client that sends neither Origin nor Sec-Fetch-Site — curl, a shell script, a
+ * sandboxed agent.
+ *
+ * The fix is #544's, at the route that sweep did not reach: a minimum gap plus
+ * one shared in-flight promise per reader. There is no MAX_OUTSTANDING beside it
+ * the way ccusage.mjs has one, and there does not need to be — ccusage keys its
+ * cache by date range, so a flood of distinct ranges can never share a run,
+ * while each reader here asks exactly one question and every caller of it can
+ * therefore join the same child.
+ *
+ * What is NOT shared is the window, because the two halves are not the same
+ * question. See CONFIG_MIN_GAP_MS and EXTERNAL_MIN_GAP_MS.
+ */
+
+/**
+ * `cswap config` — the settings map, which is also what the panel DISPLAYS.
+ *
+ * The deck is not its only writer: `cswap config set` typed in a terminal
+ * changes it behind the deck's back, and the panel is where the user would
+ * expect to see that. So this window has to stay well under AccountsPanel's
+ * 15s poll, or an edit made outside the deck waits for the window AND the poll.
+ * Three seconds does not delay a single tab by one frame — its polls are five
+ * gaps apart — while a burst of requests and two tabs whose polls land within
+ * three seconds of each other collapse onto one child.
+ */
+const CONFIG_MIN_GAP_MS = 3_000;
+
+/**
+ * The process table — the expensive half, and the one whose answer changes
+ * least: it is a boolean about whether the user has their own `cswap auto`
+ * running, and nobody starts one between two fifteen-second polls.
+ *
+ * Ten seconds is chosen against the two scheduled callers rather than against
+ * the cost: AccountsPanel's poll is 15s and MIN_INTERVAL_S — claude-swap's own
+ * floor, and the smallest tick interval SETTINGS will accept — is also 15, so a
+ * gap below both means neither of them is ever handed a reading older than its
+ * own period. The deck's tick still decides on a fresh process table, and the
+ * panel still shows one; what disappears is the second, third and twenty-fifth
+ * copy taken in the same ten seconds.
+ *
+ * Worst case for a caller in a loop is now 20 `cswap config` and 6 process-table
+ * children a minute, whatever it asks for, against a pair per request before.
+ */
+const EXTERNAL_MIN_GAP_MS = 10_000;
+
+const _config   = { last: null, inFlight: null };
+const _external = { last: null, inFlight: null };
+
+/**
+ * One reading of `read`, shared by everyone who asks inside `gapMs`.
+ *
+ * Only a real reading is remembered, which is what `value != null` means here:
+ * readCswapConfig spells its failure `null` — autoStatus reports
+ * `ok: config != null`, so holding one for three seconds would turn a single
+ * hiccup into a panel that renders itself as broken for longer than the hiccup
+ * lasted — and externalAutoRunning has no failure spelling at all, answering
+ * `false` for a process table it could not read because that is the same answer
+ * as an empty one and is the safe one either way. The in-flight share still
+ * applies to a failing read, so a burst arriving during one is a single failing
+ * child rather than a burst of them.
+ *
+ * `slot.inFlight === mine` on both hops is claude-accounts.mjs's guard and is
+ * here for its reason: invalidateCswapAutoCache drops `inFlight` so the next
+ * caller starts a read that knows the settings moved, and a read from BEFORE the
+ * write must neither store its answer under the new state nor clear the new
+ * read's promise on its way out.
+ *
+ * The reading is not keyed by platform even though externalAutoRunning branches
+ * on one. A process does not change platform; the two test files that flip
+ * `process.platform` to reach the other half from this one call
+ * invalidateCswapAutoCache between cases.
+ */
+function throttled(slot, gapMs, read) {
+  const now = Date.now();
+  if (slot.last && now - slot.last.at < gapMs) return Promise.resolve(slot.last.value);
+  if (slot.inFlight) return slot.inFlight;
+  const mine = read()
+    .then(value => {
+      if (value != null && slot.inFlight === mine) slot.last = { at: Date.now(), value };
+      return value;
+    })
+    .finally(() => { if (slot.inFlight === mine) slot.inFlight = null; });
+  slot.inFlight = mine;
+  return mine;
+}
+
+/**
+ * Forget both readings, because the deck has just changed what they would say.
+ *
+ * The one caller is setCswapConfig. There is no `?refresh=1` on /api/cswap-auto
+ * and no force argument through autoStatus, because the panel's explicit-refresh
+ * path is not a query parameter: every auto-switch control is a POST followed by
+ * `load(true)`, which re-fetches this route. Dropping the reading inside the
+ * write is what makes that reload show what was written rather than the map read
+ * a moment before it — the same disagreement between an optimistic value and the
+ * next read that #584 was.
+ *
+ * The process-table reading goes with it. A settings write does not start
+ * anybody's `cswap auto`, so this is not correctness for that half — it is that
+ * one function which forgets everything this module is holding cannot be called
+ * half-right, and the cost is at most one extra `ps` on a path the user reached
+ * by clicking. It is also what the tests reset between cases.
+ */
+export function invalidateCswapAutoCache() {
+  _config.last = _config.inFlight = null;
+  _external.last = _external.inFlight = null;
+}
+
+// ── settings ───────────────────────────────────────────────────────────────
+
+/**
+ * Parse `cswap config` — "key   value   (default)" per line.
+ *
+ * Exported for its test rather than for a caller (#383). The two callers here —
+ * `autoStatus`, which hands the map straight to the settings panel, and
+ * `tickInterval`, which takes the poll interval out of it — both reduce the
+ * parse to something a test cannot see through: the panel takes whatever shape
+ * it is given, and the interval collapses four fields to one number that is
+ * clamped anyway. The parse itself is a regex over human-formatted output from a
+ * separate Python tool, on both line-ending conventions. See
+ * cswap-auto-readers.test.ts.
+ *
+ * One reading at a time and one every CONFIG_MIN_GAP_MS at most; the parse below
+ * is what a reading is, and admission control is the wrapper. See throttled.
+ */
+export function readCswapConfig() {
+  return throttled(_config, CONFIG_MIN_GAP_MS, readCswapConfigNow);
+}
+
+async function readCswapConfigNow() {
+  const r = await run(await cswapBin(), ["config"]);
+  if (!r.ok) return null;
+  const out = {};
+  for (const line of r.stdout.split("\n")) {
+    const m = line.match(/^(\S+)\s+(.*?)\s*(\(default\))?\s*$/);
+    if (!m || !m[1].includes(".")) continue;
+    const raw = m[2].trim();
+    out[m[1]] = {
+      value:     raw === "(none)" ? null : raw,
+      isDefault: Boolean(m[3]),
+    };
+  }
+  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];
+  if (!spec) return { ok: false, reason: "unknown_setting" };
+
+  let str;
+  if (spec.type === "number") {
+    const n = Number(value);
+    if (!Number.isFinite(n) || n < spec.min || n > spec.max) return { ok: false, reason: "out_of_range" };
+    str = String(n);
+  } else if (spec.type === "enum") {
+    if (!spec.values.includes(value)) return { ok: false, reason: "bad_value" };
+    str = value;
+  } else {
+    // Model names: a comma-separated list of plain words, or "all".
+    str = String(value ?? "").trim();
+    if (str && !MODEL_LIST_OK.test(str)) return { ok: false, reason: "bad_value" };
+  }
+
+  const r = await run(await cswapBin(), ["config", "set", key, str]);
+  // Whatever the CLI said. A write that reported a failure may still have landed
+  // — and `r.ok` is not proof either way here, which is the whole of #584 — so
+  // the only safe thing to hold after asking cswap to change a setting is
+  // nothing. The panel reloads this route immediately afterwards and gets a real
+  // read; see invalidateCswapAutoCache.
+  invalidateCswapAutoCache();
+  return r.ok ? { ok: true } : { ok: false, reason: "set_failed", detail: (r.stderr || r.stdout).trim().slice(0, 300) };
+}
+
+// ── ticks ──────────────────────────────────────────────────────────────────
+
+/** Last meaningful event from a `cswap auto --once --json` run. */
+function summarise(stdout) {
+  const events = stdout.split("\n")
+    .map(l => { try { return JSON.parse(l); } catch { return null; } })
+    .filter(e => e && typeof e === "object");
+
+  const poll   = events.find(e => e.event === "poll") ?? null;
+  const action = [...events].reverse().find(e => e.event !== "poll" && e.event !== "sleep") ?? null;
+
+  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,
+    to:        action?.to ?? null,
+    active:    poll?.active ?? null,
+    threshold: poll?.threshold ?? null,
+    headroom:  poll?.headroomPct ?? null,
+    windows:   poll?.windowsPct ?? null,
+  };
+}
+
+/** Evaluate a tick for real. May switch the active account. */
+async function runAutoTick() {
+  const r = await run(await cswapBin(), ["auto", "--once", "--json"], { timeout: TICK_TIMEOUT_MS });
+  if (!r.ok && !r.stdout) {
+    return { ok: false, reason: "tick_failed", detail: (r.stderr || "").trim().slice(0, 300) };
+  }
+  return { ok: true, ...summarise(r.stdout) };
+}
+
+// ── 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.
+ *
+ * Two engines would not corrupt anything — claude-swap serializes decisions
+ * under its state lock — but they would double the tick rate against a request
+ * budget that is already the scarce resource here, and the user would have two
+ * things switching their account with no single place showing why. So the deck
+ * reports it and stays out of the way.
+ *
+ * Exported for its test rather than for a caller (#383). Its two callers reduce
+ * it to a boolean on a status object and to a skipped tick, so neither can show
+ * WHICH command line was matched — and the matching is the whole function. The
+ * two halves also run completely different commands, `ps` against
+ * `Get-CimInstance`, so on any one machine only half of it is ever exercised at
+ * all. See cswap-auto-readers.test.ts, which drives both from either host.
+ *
+ * One reading at a time and one every EXTERNAL_MIN_GAP_MS at most — the
+ * expensive half of #616, and the one both of its callers ask for on a
+ * fifteen-second timer. See throttled.
+ */
+export function externalAutoRunning() {
+  return throttled(_external, EXTERNAL_MIN_GAP_MS, externalAutoRunningNow);
+}
+
+async function externalAutoRunningNow() {
+  // 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. 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 | 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);
+  }
+
+  // `ps`, not `pgrep -a`: BSD pgrep ignores -a and prints bare PIDs, so a
+  // command-line match against its output silently never fires.
+  const r = await run("ps", ["-Ao", "args="], { timeout: 5_000 });
+  if (!r.stdout.trim()) return false;
+  return r.stdout.split("\n").some(isLoop);
+}
+
+// ── deck-managed loop ──────────────────────────────────────────────────────
+
+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 {}; }
+}
+async function saveState(state) {
+  try {
+    await mkdir(STATE_DIR, { recursive: true });
+    await writeFile(STATE_PATH, JSON.stringify(state, null, 2));
+  } catch { /* best-effort */ }
+}
+
+async function tickInterval() {
+  const cfg = await readCswapConfig();
+  const raw = Number(cfg?.["autoswitch.intervalSeconds"]?.value);
+  return Math.max(MIN_INTERVAL_S, Number.isFinite(raw) ? raw : 60) * 1000;
+}
+
+/**
+ * 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()) {
+    _lastTick = { at: Date.now(), event: "skipped", reason: "external-engine" };
+    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 || _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
+}
+
+function stopLoop() {
+  if (_timer) { clearInterval(_timer); _timer = null; }
+}
+
+/** Turn the deck-managed loop on or off, persisting the choice. */
+export async function setAutoEnabled(enabled) {
+  _enabled = Boolean(enabled);
+  await saveState({ ...(await loadState()), enabled: _enabled });
+  if (_enabled) await startLoop(); else stopLoop();
+  return { ok: true, enabled: _enabled };
+}
+
+/** Restore the persisted setting at server boot. */
+export async function initCswapAuto() {
+  const state = await loadState();
+  if (state.enabled) { _enabled = true; await startLoop(); }
+}
+
+export async function autoStatus() {
+  const [config, external] = await Promise.all([readCswapConfig(), externalAutoRunning()]);
+  return {
+    ok:        config != null,
+    enabled:   _enabled,
+    external,                       // user is running their own `cswap auto`
+    lastTick:  _lastTick,
+    settings:  config ?? {},
+  };
+}
+
+// ── per-account rotation flag ──────────────────────────────────────────────
+
+/** Hold an account out of auto-rotation, or return it. */
+export async function setAccountEnabled(accountNum, enabled) {
+  const num = Number(accountNum);
+  if (!Number.isInteger(num) || num < 1 || num > 999) return { ok: false, reason: "bad_account" };
+  const r = await run(await cswapBin(), [enabled ? "enable" : "disable", String(num)]);
+  return r.ok ? { ok: true } : { ok: false, reason: "command_failed", detail: (r.stderr || r.stdout).trim().slice(0, 300) };
+}