ccdeck 3.43.4 → 3.45.0

package/src/server/account-projects.mjs

@@ -28,7 +28,7 @@ import { StringDecoder } from "node:string_decoder";
 import { renameWithRetry } from "./atomic-write.mjs";
 import { ccProjectSlug, claudeConfigDir } from "./claude-dir.mjs";
 import { accountKey } from "./lan-sync.mjs";
-import { readSwapLog, accountAtTime, trackedSince, seedActive, markGap } from "./swap-log.mjs";
+import { readSwapLog, accountAtTime, trackedSince, seedActive, markGap, swapProjectsRoot } from "./swap-log.mjs";
 // The rules the live transcript scan counts a line's usage by, so this rollup
 // and a session's card cannot disagree about which lines billed anything, nor
 // about the speed they were billed at — see transcript-scan.mjs.
@@ -43,7 +43,7 @@ import {
  *  a per-account total is never quietly inflated by work that is not that
  *  account's. A NUL keeps it from ever colliding with a real `email@@org` key. */
 export const UNATTRIBUTED = "\u0000unattributed";
-const STATE_VERSION = 7;
+const STATE_VERSION = 8;
 
 /** Where the tally and cursors live, beside cswap-auto's own state. */
 export function statePath(home = homedir()) {
@@ -372,11 +372,11 @@ async function listTranscripts(roots) {
       if (seen.has(path)) continue;
       seen.add(path);
       const parts = relative(root, dir).split(/[\\/]/).filter(Boolean);
-      found.push({ path, slug: parts[0] ?? "", depth: parts.length });
+      found.push({ root, path, slug: parts[0] ?? "", depth: parts.length });
     }
   }
   found.sort((a, b) => a.depth - b.depth);
-  return new Map(found.map(f => [f.path, f.slug]));
+  return new Map(found.map(f => [f.path, f]));
 }
 
 /** Drop day buckets older than the retention window and prune the empty
@@ -494,6 +494,8 @@ export function createProjectRollup({
   clearInterval: clearIv = clearInterval,
 } = {}) {
   let state = { version: STATE_VERSION, cursors: {}, tally: {}, folders: {}, requests: {} };
+  let canonicalRoots = [];
+  let gapRoots = [];
   let timer = null;
   let running = false;
   let dirty = false;
@@ -502,20 +504,29 @@ export function createProjectRollup({
   async function load() {
     if (loaded) return;
     loaded = true;
+    canonicalRoots = [...new Set(await Promise.all(roots.map(r => swapProjectsRoot(r))))];
+    gapRoots = canonicalRoots;
     try {
       const disk = JSON.parse(await readFile(stateFile, "utf8"));
+      gapRoots = [...new Set([...canonicalRoots, ...(Array.isArray(disk?.sourceRoots) ? disk.sourceRoots.filter(r => typeof r === "string") : [])])];
       if (disk && disk.version === STATE_VERSION && disk.tally && disk.cursors) {
         state = disk;
         state.folders ??= {};
         state.requests ??= {};
-      } else if (disk && [1, 2, 3, 4, 5, 6].includes(disk.version)) {
+        if (JSON.stringify(disk.sourceRoots) !== JSON.stringify(canonicalRoots)) {
+          state = { version: STATE_VERSION, cursors: {}, tally: {}, folders: {}, requests: {},
+            lastAlive: disk.lastAlive };
+          dirty = true;
+        }
+      } else if (disk && [1, 2, 3, 4, 5, 6, 7].includes(disk.version)) {
         // Version 1 counted every API content block; version 2 keyed each row
         // by the line's own cwd, a row per folder the agent cd'd into (#1278);
         // version 3 kept no speed, so every fast turn read at the standard
         // rate; version 4 billed a subagent's request from its streaming
         // snapshot, most of its output and its speed missing (#1883); version
         // 5 billed a resumed subagent's request again each time its file
-        // restated its history; version 6 kept no per-request context tiers.
+        // restated its history; version 6 kept no per-request context tiers;
+        // version 7 charged independent transcript roots to the same account.
         // None of them can be re-keyed, since it no
         // longer knows which transcript a count came from. Keep the heartbeat
         // so a restart gap remains fenced, but rebuild the tally from
@@ -524,6 +535,27 @@ export function createProjectRollup({
         dirty = true;
       }
     } catch { /* first run: empty state */ }
+    state.sourceRoots = canonicalRoots;
+  }
+
+  /** The swap-log entries that speak for any of `scope`, a list of canonical
+   *  roots. An entry written before swaps recorded their projects root has
+   *  none, and cannot prove which config directory it controlled — unless
+   *  only one is known: a single configured root (two configured paths are two
+   *  candidates, even when they resolve to one directory today), and no other
+   *  root anywhere in the log. Then it can only have spoken for that root, and
+   *  its history stays the account's, as it was before the upgrade. Otherwise
+   *  it is left out, and the usage it covered stays unattributed. The log is
+   *  the record asked because it only grows, so the answer cannot change back
+   *  from one boot to the next. */
+  function timelineFor(timeline, scope) {
+    let legacyRoot = null;
+    if (new Set(roots.map(r => resolve(r))).size === 1) {
+      const known = new Set(canonicalRoots);
+      for (const e of timeline) if (e.projectsRoot !== undefined) known.add(e.projectsRoot);
+      if (known.size === 1) legacyRoot = canonicalRoots[0];
+    }
+    return timeline.filter(e => scope.includes(e.projectsRoot === undefined ? legacyRoot : e.projectsRoot));
   }
 
   async function persist() {
@@ -541,7 +573,7 @@ export function createProjectRollup({
     } catch { /* a failed persist just re-folds next time; cursors stay in memory */ }
   }
 
-  async function foldFile(path, slug, timeline) {
+  async function foldFile(path, slug, timeline, root) {
     let st = null;
     try { st = await stat(path); } catch { return; }
     let offset = state.cursors[path] ?? 0;
@@ -552,7 +584,8 @@ export function createProjectRollup({
     // is the rare, safe side to err on.
     if (st.size < offset) { state.cursors[path] = st.size; delete state.requests[path]; dirty = true; return; }
     if (st.size <= offset) return;
-    const from = { slug, folders: state.folders, requests: state.requests, path };
+    const folders = state.folders[root] ??= {};
+    const from = { slug, folders, requests: state.requests, path };
     let fh = null;
     try {
       fh = await open(path, "r");
@@ -574,19 +607,26 @@ export function createProjectRollup({
       // switched accounts by hand while nothing was recording. Written before
       // the seed so the order is stop → start.
       if (state.lastAlive && nowMs - state.lastAlive > GAP_MS) {
-        await markGap(state.lastAlive + 1, swapLog);
+        for (const root of gapRoots) await markGap(state.lastAlive + 1, swapLog, root);
       }
-      await seedActive({ now, path: swapLog, root: storeRoot });   // anchor the current account, once, deduped
+      await seedActive({ now, path: swapLog, root: storeRoot, projectsRoot: canonicalRoots[0] });   // anchor the current account, once, deduped
       const timeline = await readSwapLog(swapLog);
-      const files = await listTranscripts(roots);
-      for (const [path, slug] of files) await foldFile(path, slug, timeline);
+      const files = await listTranscripts(canonicalRoots);
+      // Each root is attributed only by the entries that speak for it; an
+      // unscoped legacy entry speaks for none unless its root is unambiguous
+      // (timelineFor).
+      const timelines = new Map(canonicalRoots.map(root => [root, timelineFor(timeline, [root])]));
+      for (const [path, { slug, root }] of files) await foldFile(path, slug, timelines.get(root), root);
       // Forget the cursors and request ledgers of files that are gone, and
       // the folders of project directories with no transcript left, so none of
       // the three maps grows forever.
       for (const p of Object.keys(state.cursors)) if (!files.has(p)) { delete state.cursors[p]; dirty = true; }
       for (const p of Object.keys(state.requests)) if (!files.has(p)) { delete state.requests[p]; dirty = true; }
-      const slugs = new Set(files.values());
-      for (const s of Object.keys(state.folders)) if (!slugs.has(s)) { delete state.folders[s]; dirty = true; }
+      for (const root of Object.keys(state.folders)) {
+        const slugs = new Set([...files.values()].filter(f => f.root === root).map(f => f.slug));
+        for (const s of Object.keys(state.folders[root])) if (!slugs.has(s)) { delete state.folders[root][s]; dirty = true; }
+        if (!slugs.size) delete state.folders[root];
+      }
       // Heartbeat: record that the deck was alive now, so a later boot can see
       // how long it was down. Cheap when nothing else changed — only bumped
       // (and so only persisted) once every HEARTBEAT_MS while idle.
@@ -607,7 +647,7 @@ export function createProjectRollup({
     async report(key, days) {
       await load();
       const timeline = await readSwapLog(swapLog);
-      return reportFrom(state.tally, timeline, key, days, now());
+      return reportFrom(state.tally, timelineFor(timeline, canonicalRoots), key, days, now());
     },
     _state: () => state,
   };

package/src/server/account-routes.mjs

@@ -25,6 +25,9 @@ import { readBody, send } from "./http-io.mjs";
 import { heldPrefs } from "./prefs-state.mjs";
 import { PRODUCT } from "./brand.mjs";
 import { incidentsFrom, withDismissed, withSignIn, withTidied } from "./account-origins.mjs";
+// What a removal of the active account does after it lands (#2184). Pure and
+// importless, so it puts nothing on the path to a listening socket.
+import { removeLeavingLiveLogin } from "./login-guard.mjs";
 
 // Resolved the way pinned-build.mjs resolves it, from a file in the same
 // directory, so every lazy import below is the URL the pin has already evaluated.
@@ -52,7 +55,18 @@ export async function handleClaudeAccountSwitch(req, res) {
   try { parsed = JSON.parse(body ?? ""); } catch { /* handled below */ }
   if (!parsed || typeof parsed !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
 
-  const result = await switchClaudeAccount(parsed.account);
+  send(res, ...await switchAndTell(parsed.account, { switchClaudeAccount, invalidateClaudeAccountsCache }));
+}
+
+/**
+ * One switch somebody asked for, and everything that has to hear about it —
+ * as `[status, body]`. The switch route's, and the one a removal of an expired
+ * active login makes afterwards (removeLeavingLiveLogin), so both say it the
+ * same way. The two functions it needs from claude-accounts.mjs are the
+ * caller's, which has already imported it.
+ */
+async function switchAndTell(account, { switchClaudeAccount, invalidateClaudeAccountsCache }) {
+  const result = await switchClaudeAccount(account);
   // The active account just moved; the next poll should see it immediately
   // rather than serving the pre-switch roster for another few seconds.
   invalidateClaudeAccountsCache();
@@ -73,10 +87,10 @@ export async function handleClaudeAccountSwitch(req, res) {
     // effort — a failed log write must never fail the switch — so it is not
     // awaited into the response.
     import(pathToFileURL(join(PKG_ROOT, "src/server/swap-log.mjs")).href)
-      .then(({ recordSwap }) => recordSwap(parsed.account, "manual"))
+      .then(({ recordSwap }) => recordSwap(account, "manual"))
       .catch(() => {});
   }
-  send(res, result.ok ? 200 : 400, result);
+  return [result.ok ? 200 : 400, result];
 }
 
 // The account-projects rollup, started once and shared. Its timer is unref'd
@@ -256,6 +270,33 @@ async function dismissReauth(raw) {
   return { ok: true };
 }
 
+/**
+ * Remove an account — and when it was the active one and its login had expired,
+ * move Claude Code to a working account once it is gone (#2184).
+ *
+ * `cswap remove` leaves the live login where it is. That is right when the
+ * login works and wrong when it is the dead one: every session stays stopped,
+ * and nothing else will move them, since auto-switch does not touch a login
+ * claude-swap no longer manages. The roster is read BEFORE the removal, because
+ * after it the account is not on it to ask about; the move goes through the
+ * switch route's own path, guard and bookkeeping included. Like Auto-switch's
+ * moves, it never lands on an account claude-swap set aside or one a local
+ * `cswap run` session is using (slotsHeldBack).
+ */
+async function removeAccount(admin, num) {
+  const accounts = await import(
+    pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href
+  );
+  return removeLeavingLiveLogin(num, {
+    roster: () => accounts.fetchClaudeAccounts({ force: true }),
+    remove: n => admin.removeAccount(n),
+    switchTo: async n => (await switchAndTell(n, accounts))[1],
+    heldBack: async rows => (await import(
+      pathToFileURL(join(PKG_ROOT, "src/server/cswap-auto-choice.mjs")).href
+    )).slotsHeldBack(rows),
+  });
+}
+
 // Reading the login's progress. The browser polls this while its dialog is
 // open, the same way the upgrade notice polls /api/version.
 export async function handleAccountLoginState(_req, res) {
@@ -302,7 +343,9 @@ export async function handleClaudeAccountAdmin(req, res) {
       result = out?.ok ? { ...out, results: await admin.checkImportResults(out.results) } : out;
       break;
     }
-    case "remove":       result = await admin.removeAccount(parsed.account); break;
+    // #2184. Removing the ACTIVE account leaves Claude Code signed in as it;
+    // when that login is the expired one, a working account takes over after.
+    case "remove":       result = await removeAccount(admin, parsed.account); break;
     // #721. Re-captures the active slot's credentials in place; see
     // recaptureActive for why this is not a login and cannot become one.
     case "recapture":    result = await admin.recaptureActive(); break;

package/src/server/account-watch.mjs

@@ -21,6 +21,13 @@ import {
 } from "./account-notify.mjs";
 import { deckDataDir } from "./deck-home.mjs";
 import { writeFileAtomic } from "./atomic-write.mjs";
+// What a StopFailure says, and the words a notification names a session by.
+import { stopFailureOf, switchCanCure } from "./stop-failure.mjs";
+import { whoOf } from "./block-notify.mjs";
+// Which deck is on what, as Local network last heard it, and the identity rule
+// its keys are made by (#2192).
+import { elsewhereNow } from "./lan-elsewhere.mjs";
+import { accountKey } from "./lan-copies.mjs";
 
 const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
 
@@ -39,11 +46,24 @@ export function recordsPath(home = deckDataDir()) {
  */
 export const WATCH_MS = 2 * 60_000;
 
+/**
+ * How often the notifier asks Local network whether the account this deck is
+ * on is live on another deck too (#2192). A round is a minute, so asking more
+ * often finds nothing new; and with no deck on any account of this one's, the
+ * look is the engine's status and nothing else — the store is not read.
+ */
+export const ELSEWHERE_WATCH_MS = 60_000;
+
 let _deps = null;
 let _notifier = null;
 let _autoOn = false;
 let _timer = null;
+let _elsewhereTimer = null;
 let _watching = null;
+/** The auto-switch loop's "tick now", handed in by the loop as it loads
+ *  (cswap-auto-loop.mjs `tickSoon`). Null until then, and on a deck that never
+ *  loads it — one with no Claude to switch. */
+let _tickSoon = null;
 
 /**
  * Hand the notifier its OS call, its product name and its switches. Called
@@ -75,6 +95,16 @@ function notifier() {
   return _notifier;
 }
 
+/**
+ * For the suite: settles once every record save the notifier has started has
+ * finished. A save follows its notice and is an atomic write, whose rename
+ * Windows retries while a scanner holds the file, so no fixed pause after a
+ * tick is long enough to read the records back.
+ */
+export function accountNotifySettled() {
+  return _notifier ? _notifier.settled() : Promise.resolve();
+}
+
 /** The deck's auto-switch loop was switched on or off (cswap-auto-loop.mjs). */
 export function noteAutoSwitch(enabled) {
   _autoOn = enabled === true;
@@ -86,16 +116,55 @@ export function noteAutoSwitch(enabled) {
  * notification is raised: a switch somebody pressed never comes through here.
  * After a switch, claude-swap's roster is read for the two accounts' names and
  * keys — the store, which the deck already reads, rather than anything more out
- * of the tick's own output.
+ * of the tick's own output. `meta.startedAt` is when the tick began.
  */
-export function noteAutoTick(result) {
+export function noteAutoTick(result, meta = {}) {
   const n = notifier();
   if (!n || !result) return Promise.resolve();
-  return (result.switched ? storeAccounts() : Promise.resolve(null))
-    .then(accounts => n.tick(result, accounts))
+  // A dead login with nowhere to go is named too, so its notice can say whose.
+  const named = result.switched || result.reason === "login-expired";
+  return (named ? Promise.all([storeAccounts(), result.switched ? telemetryReader() : null]) : Promise.resolve([null, null]))
+    .then(([accounts, telemetryOf]) => n.tick(result, accounts, { ...meta, telemetryOf }))
     .catch(() => {});
 }
 
+/** What each organization's settings were last seen to turn on, as the
+ *  sentence a swap notice carries (org-telemetry.mjs), or null. */
+async function telemetryReader() {
+  try {
+    const { knownOrgTelemetry, telemetryClause } = await import(pathToFileURL(join(PKG_ROOT, "src/server/org-telemetry.mjs")).href);
+    const records = await knownOrgTelemetry();
+    return org => telemetryClause(records?.[org]);
+  } catch {
+    return null;
+  }
+}
+
+/** The loop's way to be asked for a tick now. Called once, as it loads. */
+export function connectEarlyTick(fn) {
+  _tickSoon = typeof fn === "function" ? fn : null;
+}
+
+/**
+ * A hook event, as pushEvent takes it in: when it is a turn that stopped on an
+ * expired login or a usage limit, the incident is counted for its notification
+ * and the auto-switch loop is asked to tick now rather than at its next
+ * interval. The loop coalesces the asks and does nothing while it is off, so
+ * ten sessions stopping in one second are one tick, and a deck with auto-switch
+ * off only counts.
+ *
+ * Every other event, and every stop that is not one of those two, returns at
+ * once — this is on the path every hook event takes. Never throws.
+ */
+export function noteHookStop(raw, at = Date.now()) {
+  try {
+    const stop = stopFailureOf(raw, at);
+    if (!stop || !switchCanCure(stop.kind)) return;
+    notifier()?.stopped({ sessionId: raw.session_id, who: whoOf(raw), kind: stop.kind, at });
+    _tickSoon?.();
+  } catch { /* never the ingest path's problem */ }
+}
+
 /** claude-swap's roster, number → `{ email, organizationUuid, alias }`, or null. */
 async function storeAccounts() {
   try {
@@ -155,6 +224,35 @@ export function watchOnce(providers) {
   return _watching;
 }
 
+/**
+ * One look at whether the account this deck is on is one a paired deck says it
+ * is on too, handed to the notifier, which says it once per incident.
+ *
+ * The store is read only when some deck is on some account, and through the
+ * roster's own cache, which the panel and every LAN round already keep warm. A
+ * roster that could not be read says nothing and closes nothing: not knowing
+ * which account this deck is on is not the same as being on none.
+ */
+export async function watchElsewhereOnce(now = Date.now()) {
+  const n = notifier();
+  if (!n) return;
+  try {
+    const on = elsewhereNow(now);
+    if (on.size === 0) return n.elsewhere(null, []);
+    const { fetchClaudeAccounts } = await import(pathToFileURL(join(PKG_ROOT, "src/server/claude-accounts.mjs")).href);
+    const got = await fetchClaudeAccounts();
+    if (!got?.ok || !Array.isArray(got.accounts)) return;
+    const live = got.accounts.find(a => a?.active === true);
+    if (!live?.email) return n.elsewhere(null, []);
+    const key = accountKey(live.email, live.orgUuid);
+    const name = typeof live.alias === "string" && live.alias.trim() ? live.alias.trim() : live.email;
+    return n.elsewhere({ key, name }, on.get(key) ?? []);
+  } catch {
+    // The roster's own failures are its panel's to say; here there is nothing
+    // to compare this time.
+  }
+}
+
 /**
  * Start reading quota on a timer, from startServer once the port is bound —
  * never at import, because a launcher imports the server module only to ask
@@ -166,4 +264,9 @@ export function startAccountWatch({ providers } = {}) {
   _timer.unref?.();
   const first = setTimeout(() => { watchOnce(providers).catch(() => {}); }, 15_000);
   first.unref?.();
+  // And Local network's word on the account this deck is on, on its own clock:
+  // it costs nothing while no deck is on anything, and it is said whichever of
+  // the quota switches is on.
+  _elsewhereTimer = setInterval(() => { watchElsewhereOnce().catch(() => {}); }, ELSEWHERE_WATCH_MS);
+  _elsewhereTimer.unref?.();
 }

package/src/server/activity.mjs

@@ -9,7 +9,8 @@
 //
 // With no page open there is no reducer, so this keeps the smallest version of
 // it: a session is open from the first event of a turn until the turn ends
-// (`Stop`, `SessionEnd`). SessionStart and Notification move nothing — a CLI
+// (`Stop`, `StopFailure` — the Stop of a turn that ended on an API error —
+// `SessionEnd`). SessionStart and Notification move nothing — a CLI
 // sitting at its prompt is not busy, and the idle reminder arrives after the
 // turn it is about. An open session whose last event is older than
 // OPEN_CAP_MS counts as gone rather than busy: a CLI that crashed never sends
@@ -26,7 +27,7 @@ export function shouldTrackActivity(raw, opts = {}) {
 const OPENS = new Set([
   ...RECOVERIES, "UserPromptSubmit", "PreToolUse", "PostToolUse", "PostToolUseFailure", "SubagentStart", "SubagentStop",
 ]);
-const CLOSES = new Set(["Stop", "SessionEnd"]);
+const CLOSES = new Set(["Stop", "StopFailure", "SessionEnd"]);
 
 /** More turns open at once than any machine runs — the same figure as the
  *  deck's own working limit for the sessions it tracks (MAX_TRACKED_SESSIONS in

package/src/server/args.mjs

@@ -161,17 +161,119 @@ export const ONE_SHOT = Object.freeze([
   "purge",
 ]);
 
+/**
+ * The words the deck answers as commands (#2183), by every spelling it takes.
+ *
+ * Two kinds. A COMMAND is something the flags never did — read the accounts,
+ * switch one, list the sessions — and lands in `command`, answered by
+ * bin/cli/commands.js. A FLAG WORD is a flag that already existed under a
+ * second spelling: `ccdeck stop` is `ccdeck --stop`, set as that very flag, so
+ * the one-shot that answers it cannot tell the two apart and there is one
+ * implementation of each. `start` is the bare start, spelled out by people who
+ * type a verb first, and sets nothing at all.
+ *
+ * `swap` is a switch here, not claude-swap's "exchange two slots": that is the
+ * word the people asking for this used, and a switch is what they meant. Two
+ * account operands are answered with where the slot exchange lives instead
+ * (see bin/cli/commands.js).
+ */
+export const COMMANDS = Object.freeze({
+  accounts: "accounts", account: "accounts", ls: "accounts",
+  switch: "switch", swap: "switch", use: "switch",
+  usage: "usage", quota: "usage",
+  sessions: "sessions", ps: "sessions",
+  open: "open",
+});
+const FLAG_WORDS = Object.freeze({
+  status: "status", stop: "stop", logs: "logs", help: "help", version: "version",
+});
+const BARE_START = "start";
+
+/**
+ * The flags only a START reads. A line carrying one is a deck being started,
+ * whatever else is on it, and its bare words are what they always were —
+ * unknown options, named, and the deck starts — rather than commands.
+ *
+ * Two lines need that and neither can say so any other way. An unquoted path
+ * with a space in it: `--workspace /home/ana/Face Swap` is `--workspace
+ * /home/ana/Face` and a bare `Swap`, which is a switch to whoever reads words
+ * as commands. And the npx relaunch of an upgrade (npxRelaunchArgs in
+ * supervisor.mjs), which replays the user's own argv with `--no-open` added —
+ * an argv an older deck booted on, where `ccdeck myproj` was a warning and a
+ * start, and where a newer parser reading `myproj` as a misspelled command
+ * would end the deck it was upgrading.
+ */
+const START_FLAGS = new Set([
+  "--no-open", "--new", "--foreground", "--at-login", "--workspace", "--scope",
+  "--no-persist", "--history", "--codex", "--no-codex", "--claude", "--no-claude", "--ref",
+]);
+
+/**
+ * Could this token have been meant as a command?
+ *
+ * A word — letters, digits and dashes, starting with a letter. Anything with a
+ * separator, a dot or a tilde in it is a path, and a path in first position is
+ * the old mistake `ccdeck ~/proj`, reported the old way: an unknown option, and
+ * the deck still starts.
+ */
+function wordShaped(token) {
+  return /^[a-z][a-z0-9-]*$/i.test(token);
+}
+
 /** Is this a command line that answers and leaves? */
 export function isOneShot(flags = {}) {
+  // A command, and a word that was not one, answer and leave too: a command
+  // that detached would print its answer into deck.log, and a misspelled one
+  // that started a deck would leave a server behind on a machine reached over
+  // SSH, where there is no tab to show it in.
+  if (typeof flags.command === "string" || typeof flags.unknownCommand === "string") return true;
   return ONE_SHOT.some((k) => flags[k] === true);
 }
 
-export function parseArgs(args) {
+/**
+ * `commands: false` reads every bare word the way the parser did before there
+ * were commands, which is how a RESPAWNED worker reads its argv (bin/deck.js):
+ * the line is one a deck already booted on — perhaps an older deck, for which
+ * `ccdeck serve` was a warning and a start — and a worker that answered it as
+ * a command would exit, and the supervisor would count each exit as a crash.
+ */
+export function parseArgs(args, { commands = true } = {}) {
   const out = { unknown: [], incomplete: [] };
   // END OF OPTIONS. A bare `--` is the POSIX separator, and reporting it as an
-  // unknown option warned about a token the user typed on purpose.
+  // unknown option warned about a token the user typed on purpose. After a
+  // command, what follows it is operands — `ccdeck switch -- -odd-alias` —
+  // which is the separator's whole purpose.
   const end = args.indexOf("--");
   const argv = end === -1 ? args : args.slice(0, end);
+  const afterEnd = end === -1 ? [] : args.slice(end + 1);
+  const words = commands && !argv.some(t => START_FLAGS.has(t.startsWith("--") ? t.split("=")[0] : t));
+  // A bare word, sorted by where it stands. Only the FIRST bare word on a line
+  // can be a command, and it can be one wherever it stands among the flags, so
+  // `ccdeck --json accounts` reads the same as `ccdeck accounts --json`; every
+  // bare word after it is one of its operands. A word-shaped token in first
+  // position that is not a command is a command misspelled — `ccdeck acounts` —
+  // and is refused rather than starting a deck. Any other bare word is what it
+  // always was: an unknown option, named, and the deck starts — so is every
+  // bare word on a start line (START_FLAGS) and behind a word that was not a
+  // command (`ccdeck ~/my swap`).
+  let bare = 0;
+  const positional = (token, first) => {
+    if (out.command) { out.operands.push(token); return; }
+    const word = String(token).toLowerCase();
+    const lead = bare++ === 0;
+    if (lead && word === BARE_START) return;
+    if (lead && words) {
+      if (Object.hasOwn(COMMANDS, word)) {
+        out.command = COMMANDS[word];
+        out.commandWord = word;
+        out.operands = [];
+        return;
+      }
+      if (Object.hasOwn(FLAG_WORDS, word)) { out[FLAG_WORDS[word]] = true; return; }
+      if (first && wordShaped(token)) { out.unknownCommand = token; return; }
+    }
+    out.unknown.push(token);
+  };
   for (let i = 0; i < argv.length; i++) {
     // `--port=4400`, split here so the dispatch below sees the two halves it
     // already knows how to read.
@@ -248,7 +350,15 @@ export function parseArgs(args) {
     // The ccdeck.dev page the command was copied from, for the first install
     // report (install-ref.mjs). A value that is not a ref is dropped there.
     else if (a === "--ref") set("ref", "a page name");
+    // What the commands read (#2183): machine-readable output on stdout, and
+    // the account with the most room rather than a named one.
+    else if (a === "--json") out.json = true;
+    else if (a === "--best") out.best = true;
+    else if (!looksLikeFlag(argv[i])) positional(argv[i], i === 0);
     else out.unknown.push(argv[i]);   // the token as typed, `=` half included
   }
+  for (const token of afterEnd) {
+    if (out.command) out.operands.push(token);
+  }
   return out;
 }