ccdeck 3.29.10 → 3.30.0

package/src/server/cswap-auto-loop.mjs

@@ -0,0 +1,342 @@
+// The deck-managed auto-switch loop: `cswap auto --once` run on claude-swap's
+// own interval, one tick at a time, and only while the user has it switched on
+// — a choice kept in ~/.agents-deck/cswap-auto.json across restarts.
+//
+// Moved out of cswap-auto.mjs unchanged, with what one tick is (summarise,
+// runAutoTick). cswap-auto.mjs re-exports setAutoEnabled and initCswapAuto,
+// which is where the route and the boot reach them; its settings write asks
+// restartLoop for a new interval, and its status route reports loopEnabled and
+// lastTick.
+import { run } from "./exec.mjs";
+import { failureDetail } from "./exec-output.mjs";
+import { cswapBin } from "./cswap-install.mjs";
+import { externalAutoRunning, readCswapConfig } from "./cswap-auto-readers.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 { 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
+
+// ── 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: failureDetail(r, 300) };
+  }
+  return { ok: true, ...summarise(r.stdout) };
+}
+
+// ── 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;
+/** 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;
+// 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;
+  }
+  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 };
+}
+
+/**
+ * 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() {
+  // 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
+}
+
+function stopLoop() {
+  if (_timer) { clearInterval(_timer); _timer = null; }
+}
+
+/** Put a new interval into effect: the timer goes, and a fresh read of the
+ *  interval installs the next one. */
+export function restartLoop() {
+  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).
+  return startLoop();
+}
+
+/** Whether the user has the loop switched on — the setting, which a new
+ *  interval and the status route both ask about, rather than whether a timer is
+ *  installed right now. */
+export function loopEnabled() {
+  return _enabled;
+}
+
+/** What the most recent tick did, as /api/cswap-auto reports it; null before
+ *  the first. */
+export function lastTick() {
+  return _lastTick;
+}
+
+/** 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(); }
+}

package/src/server/cswap-auto-readers.mjs

@@ -0,0 +1,303 @@
+// The two readings behind GET /api/cswap-auto — claude-swap's settings map, and
+// whether the user is running a `cswap auto` loop of their own — each shared by
+// everyone who asks inside its window, one child at a time (#616).
+//
+// Moved out of cswap-auto.mjs unchanged, with the rule that tells the user's
+// loop from the deck's own ticks. cswap-auto.mjs asks both on every status
+// read, takes the tick interval out of the settings map, asks about the other
+// engine before every tick, and drops both readings when it writes a setting;
+// it re-exports all five names, which is where the suite reaches them.
+import { run } from "./exec.mjs";
+import { cswapBin } from "./cswap-install.mjs";
+
+// ── 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, not only for its callers (#383). Its two callers in
+ * cswap-auto.mjs — `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;
+}
+
+// ── 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, not only for its callers (#383). Its two callers in
+ * cswap-auto.mjs 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);
+}