ccdeck 3.29.11 → 3.31.0

package/src/server/cswap-auto.mjs

@@ -9,22 +9,21 @@
 //
 // A tick can move the user's live Claude account, so it is off unless turned
 // on and the setting survives restarts.
+//
+// Split three ways: this module writes the settings, answers the status route
+// and holds an account out of rotation; cswap-auto-readers.mjs takes the two
+// readings behind that route, and cswap-auto-loop.mjs runs the ticks.
 import { run } from "./exec.mjs";
+import { failureDetail } from "./exec-output.mjs";
 import { cswapBin } from "./cswap-install.mjs";
-import { invalidateClaudeAccountsCache } from "./claude-accounts.mjs";
-import { invalidateQuotaCache } from "./quota.mjs";
-// The one store mutex. A tick is the only thing in the deck that moves the live
-// account with nobody watching, which is why it of all writers must queue.
+import {
+  commandTokens, externalAutoRunning, invalidateCswapAutoCache, looksLikeAutoLoop, readCswapConfig,
+} from "./cswap-auto-readers.mjs";
+import { initCswapAuto, lastTick, loopEnabled, restartLoop, setAutoEnabled } from "./cswap-auto-loop.mjs";
+import { invalidateClaudeAccountsCache, slotNumber } from "./claude-accounts.mjs";
+// The one store mutex, which the rotation flag below holds like every other
+// writer of claude-swap's store.
 import { withStoreLock } from "./store-lock.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
@@ -37,176 +36,13 @@ const SETTINGS = {
   "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;
-}
+// The two readings behind the status route — the settings map and whether the
+// user runs their own loop — each one child at a time and one per window
+// (#616): cswap-auto-readers.mjs.
+export { invalidateCswapAutoCache, readCswapConfig };
 
 // ── 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.
  *
@@ -230,8 +66,15 @@ async function readCswapConfigNow() {
  */
 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) {
+/**
+ * The argument a setting's value becomes, as `{ ok: true, str }`, or the
+ * refusal `{ ok: false, reason }` setCswapConfig answers with instead.
+ *
+ * Validated against SETTINGS and nothing else, and pure: neither answer spawns
+ * anything, so a test can hand it every shape a caller might send without a
+ * `cswap` behind it. setCswapConfig is its one caller.
+ */
+export function settingArg(key, value) {
   // `Object.hasOwn`, not a bare read. `SETTINGS["constructor"]` is truthy and
   // its `.type` is undefined, so a prototype member passed the allowlist and
   // fell through to the free-text branch — reaching `cswap config set
@@ -254,6 +97,14 @@ export async function setCswapConfig(key, value) {
     str = String(value ?? "").trim();
     if (str && !MODEL_LIST_OK.test(str)) return { ok: false, reason: "bad_value" };
   }
+  return { ok: true, str };
+}
+
+/** Validate against SETTINGS, then hand to `cswap config set`. */
+export async function setCswapConfig(key, value) {
+  const arg = settingArg(key, value);
+  if (!arg.ok) return arg;
+  const { str } = arg;
 
   const r = await run(await cswapBin(), ["config", "set", key, str]);
   // Whatever the CLI said. A write that reported a failure may still have landed
@@ -269,437 +120,28 @@ export async function setCswapConfig(key, value) {
   // process — sixty `cswap auto --once` spawns an hour instead of one, against
   // the shared per-account request budget this subsystem exists to protect.
   // Lowering it was equally inert.
-  if (r.ok && key === "autoswitch.intervalSeconds" && _enabled) {
-    stopLoop();
-    // startLoop records the ask when one is already in flight, so this can no
-    // longer be swallowed by the boot's own start — see the note there (#791).
-    await startLoop();
-  }
-  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.
- *
- * UNDER THE STORE MUTEX (#1039). `cswap auto --once` is not a question: it
- * reads sequence.json, decides, and writes it back, which is the unlocked
- * read-modify-write cswap-admin.mjs's header opens by explaining and the reason
- * every mutation there goes through one lock. This one was outside it, and it
- * is the writer least likely to be noticed — nobody presses it. The interval
- * floor is MIN_INTERVAL_S = 15 s (claude-swap's own) and one `cswap add` is
- * allowed sixty, so a tick landing inside a sign-in takes no coincidence at
- * all: whichever write lands second drops the other's record, and the deck
- * reports a rotation that was silently undone, or the account the user has just
- * added is gone.
- *
- * A tick skipped because the lock was busy is not a tick lost — `tick()` already
- * says as much about its own guard: the next interval is at most fifteen
- * seconds away and the work is idempotent by design. Here it is not even
- * skipped, only queued.
- */
-async function runAutoTick() {
-  const r = await withStoreLock(async () =>
-    run(await cswapBin(), ["auto", "--once", "--json"], { timeout: TICK_TIMEOUT_MS }));
-  // A KILLED RUN IS NOT A QUIET ONE. `run`'s timeout path deliberately keeps an
-  // 8 KB tail of whatever the child managed to print, so `!r.ok && !r.stdout`
-  // is false for a tick that emitted its `{"event":"poll"}` line and then
-  // stalled — and the killed run fell through to `ok: true`. The panel then
-  // showed a healthy `no-switch` every two minutes, forever, while the engine
-  // did nothing at all: exactly the trap exec.mjs's own header names.
-  if (r.timedOut) {
-    return { ok: false, reason: "tick_timeout", detail: `cswap auto --once did not finish within ${TICK_TIMEOUT_MS / 1000}s` };
-  }
-  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;
-// What every tick waits for before it runs anything: the launcher's word that
-// the claude-swap it drives is not being installed or upgraded underneath it.
-// Settled by default, so a caller with nothing to wait for — a respawn, a test,
-// the dev server — ticks exactly as before. See initCswapAuto (#1043).
-let _toolQuiet = Promise.resolve();
-
-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() {
-  // NOT WHILE THE TOOL IS BEING SET UP (#1043). A tick is `cswap auto --once`,
-  // which moves the user's live Claude credentials, and the boot arms this loop
-  // the moment the port binds — while bin/deck.js may still be installing
-  // claude-swap, or has just fired an upgrade of it that nothing awaits. It sits
-  // here rather than in startLoop so that it holds every tick that could land in
-  // that window: the boot's eager one, an interval that comes round during a
-  // three-minute install, and one the user starts from the panel meanwhile.
-  // Everything below is asked after it, so a switch turned off while this was
-  // waiting is seen as off.
-  await _toolQuiet;
-  // 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;
-  }
-  // AND RE-CHECK THE SWITCH ITSELF, after that await. `stopLoop` clears the
-  // interval and nothing else, so a tick already running went on to move the
-  // user's live account seconds after the panel had drawn itself as off. The
-  // await above is not short: ticks are at least fifteen seconds apart against
-  // a ten-second floor, so every one pays a real process-table read — on
-  // Windows a PowerShell Get-CimInstance with an eight-second deadline. The
-  // panel then showed `enabled: false` beside a `lastTick` of
-  // `{event: "switch", from, to}` stamped after the user turned it off.
-  if (!_enabled) {
-    _lastTick = { at: Date.now(), event: "skipped", reason: "disabled" };
-    return;
+  if (r.ok && key === "autoswitch.intervalSeconds" && loopEnabled()) {
+    await restartLoop();
   }
-  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();
-  // Record the move for the account-projects report. Only on a real switch, and
-  // best effort — the tick must not fail because a log line did not append. The
-  // slot is resolved from the store inside recordSwap, so cswap's `to` need not
-  // be threaded through here.
-  if (result.switched) {
-    import("./swap-log.mjs")
-      .then(({ recordSwap }) => recordSwap(result.to, "auto"))
-      .catch(() => {});
-  }
-  _lastTick = { at: Date.now(), ...result };
+  return r.ok ? { ok: true } : { ok: false, reason: "set_failed", detail: failureDetail(r, 300) };
 }
 
-/**
- * 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;
-}
+// Whether the user is already running `cswap auto` themselves, and the rule
+// that tells their loop from the deck's own ticks: cswap-auto-readers.mjs.
+export { commandTokens, externalAutoRunning, looksLikeAutoLoop };
 
-/**
- * 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() {
-  // A start requested while one is already in flight is REMEMBERED, not dropped
-  // (#791). `initCswapAuto()` is fired unawaited at boot, so this sits inside
-  // `await tickInterval()` — a `cswap config` spawn, preceded on Windows by
-  // cswapBin() probing up to four spellings, two of them through cmd.exe, each
-  // with an 8s deadline — while the panel is already serving. A user setting
-  // the interval in that window called stopLoop() (no timer yet: a no-op) and
-  // then startLoop(), which returned here having done nothing; the boot's own
-  // start then resumed with the interval it had read BEFORE the write and
-  // installed the timer at the old value. The panel read back the new number
-  // while the loop kept the old one for the life of the process.
-  if (_starting) { _restartWanted = true; return; }
-  if (_timer) return;
-  _starting = true;
-  try {
-    // Loop rather than a single pass: the config may be written again while
-    // THIS read is in flight, and the answer must be the last one written.
-    for (;;) {
-      _restartWanted = false;
-      const ms = await tickInterval();
-      if (!_enabled) return;   // turned off while we were asking cswap
-      if (_restartWanted) continue;   // the interval changed under this read
-      _timer = setInterval(() => { tick().catch(() => {}); }, ms);
-      _timer.unref?.();
-      break;
-    }
-  } finally {
-    _starting = false;
-  }
-  tick().catch(() => {});   // don't make the user wait a full interval for the first one
-}
-
-/** Set when a restart is asked for while `startLoop` is mid-read, so the read
- *  that is already running takes the new value instead of installing the old
- *  one. Module-level beside `_starting`, which it exists to answer for. */
-let _restartWanted = false;
-
-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.
- *
- * `after` is the launcher's promise that claude-swap is quiet: its startup job
- * has settled, and so has any upgrade that job started without waiting for.
- * index.mjs passes on what bin/deck.js hands startServer. With nothing to wait
- * for it is null, and the loop ticks as it always did. A rejection counts as
- * settled, because a job that failed has nothing left running either.
- *
- * The loop still starts here and reads its interval here. Only the ticks wait.
- */
-export async function initCswapAuto({ after = null } = {}) {
-  _toolQuiet = Promise.resolve(after).then(() => {}, () => {});
-  const state = await loadState();
-  if (state.enabled) { _enabled = true; await startLoop(); }
-}
+// The deck-managed loop — its interval, one tick at a time, the switch that
+// turns it on and the boot that restores it — and what one tick is:
+// cswap-auto-loop.mjs.
+export { initCswapAuto, setAutoEnabled };
 
 export async function autoStatus() {
   const [config, external] = await Promise.all([readCswapConfig(), externalAutoRunning()]);
   return {
     ok:        config != null,
-    enabled:   _enabled,
+    enabled:   loopEnabled(),
     external,                       // user is running their own `cswap auto`
-    lastTick:  _lastTick,
+    lastTick:  lastTick(),
     settings:  config ?? {},
   };
 }
@@ -708,11 +150,11 @@ export async function autoStatus() {
 
 /** Hold an account out of auto-rotation, or return it.
  *
- *  UNDER THE MUTEX AND FOLLOWED BY AN INVALIDATION, like the nine other
- *  mutations of claude-swap's store, and this was the one that was neither.
+ *  UNDER THE MUTEX AND FOLLOWED BY AN INVALIDATION, like every other
+ *  mutation of claude-swap's store, and this was the one that was neither.
  *
  *  `cswap enable/disable` writes `accounts[N].disabled` in sequence.json, which
- *  is the field the roster reads at claude-accounts.mjs:734 — so it is the
+ *  is the field claude-accounts.mjs's roster reads as `disabled` — so it is the
  *  read-modify-write cswap-admin.mjs opens by explaining is why every mutation
  *  goes through one mutex.
  *
@@ -728,8 +170,8 @@ export async function autoStatus() {
  *  so, and calls a floor that answers ?refresh=1 with the stale roster "the
  *  guard being the bug". */
 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 num = slotNumber(accountNum);
+  if (num == null) return { ok: false, reason: "bad_account" };
   // Statically, from store-lock.mjs, like the tick above. #950 reached for it
   // through a dynamic `import("./cswap-admin.mjs")` to avoid adding a static
   // edge between two modules that already imported each other, which was the
@@ -739,7 +181,7 @@ export async function setAccountEnabled(accountNum, enabled) {
   // get it.
   return withStoreLock(async () => {
     const r = await run(await cswapBin(), [enabled ? "enable" : "disable", String(num)]);
-    if (!r.ok) return { ok: false, reason: "command_failed", detail: (r.stderr || r.stdout).trim().slice(0, 300) };
+    if (!r.ok) return { ok: false, reason: "command_failed", detail: failureDetail(r, 300) };
     invalidateClaudeAccountsCache();
     return { ok: true };
   });