agent-dag 3.18.3 → 3.20.0

package/dist/web/index.html

@@ -40,8 +40,8 @@
         document.documentElement.setAttribute("data-theme", stored === "light" ? "light" : "dark");
       })();
     </script>
-    <script type="module" crossorigin src="/assets/index-gg-y6G2I.js"></script>
-    <link rel="stylesheet" crossorigin href="/assets/index-BeMPJP5g.css">
+    <script type="module" crossorigin src="/assets/index-Dr-bVaHM.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-DVj_M279.css">
   </head>
   <body>
     <div id="root"></div>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-dag",
-  "version": "3.18.3",
+  "version": "3.20.0",
   "description": "Live deck of Claude Code and Codex agents — watch tool calls, token spend and every Claude Code subagent on one calm canvas. Run it with npx ccdeck.",
   "type": "module",
   "bin": {

package/release-notes.json

@@ -31,6 +31,18 @@
     "about a defect in the type, and the suite refuses both it and no space at",
     "all."
   ],
+  "3.20.0": [
+    {
+      "title": "🟢 The deck keeps running after you close the terminal",
+      "body": "`ccdeck` prints the same boot report and gives you the prompt back. The deck stays up, and starts again when you log in.\n\n🛑 **`ccdeck --stop` is the off switch now** — Ctrl+C only cancels a start that is still printing. `--status` says what is running, `--logs` shows what the deck wrote while you were away, and `--foreground` holds the terminal the way every version before this one did.\n\n🔁 Typing `ccdeck` beside a deck that is already up opens **that deck's tab** instead of building a second one. `ccdeck --stop --all` clears any older deck still running from before this version. An `npx` run cannot start at login — `npx ccdeck --install` puts it on your PATH and sets that up.\n\n🔑 An account that will not collect now says which of three things is wrong: **no stored login**, a **login that expired**, or a **keychain the deck cannot open** — with the fix beside it. One with no stored login is filled over the local network by a paired deck that has it.\n\n📡 And decks find each other again on a machine with a VPN up: the beacon was going to an address that never left the machine, so this deck could hear colleagues and none of them could hear it."
+    }
+  ],
+  "3.19.0": [
+    {
+      "title": "🟢 Local network: fixes and improvements",
+      "body": "The list of decks is quiet now. A deck that is **on**, with nothing to repair, is a name and a green mark — no sentence under it. Every healthy row used to carry the same words, so the one row worth reading looked like all the others. A failure, a login that arrived, a machine that is away, still say so, and they are now the only rows with anything written on them.\n\n`unpair` arrives when you point at a row rather than sitting on every one of them, two machines that share a name show their addresses, and the ↻ turns while a round is out.\n\n**Add a deck** is two ways in — by address, or with an invite — with `make one to send` beside the invite heading instead of under the paste field, where it read as that field's button. A refused address now says which mistake it was, and an invite that will not work says whether it ran out, was not an invite, or reached nothing.\n\nSwitching **Local network** on opens your name and shared logins, every time, so nothing goes on the network without you having just seen what goes with it."
+    }
+  ],
   "3.18.3": [
     {
       "title": "🟢 The list shows what is on, and folds the rest",

package/src/server/args.mjs

@@ -110,6 +110,25 @@ export function isPortValue(raw) {
  * C:\Users\John Smith\proj` reaches the parser as two arguments, and the second
  * one used to be dropped in silence (see launchNpx in bin/agent-dag.js).
  */
+/**
+ * The flags that do a thing and exit, rather than starting a deck.
+ *
+ * bin/agent-dag.js reads this before it decides whether to detach, and that is
+ * the whole reason it exists as a list rather than as a condition written out
+ * at the call site: a one-shot that detached would print its answer into a log
+ * file and hand the terminal back empty. `ccdeck --version` detaching itself is
+ * the shape of the bug this prevents.
+ */
+export const ONE_SHOT = Object.freeze([
+  "help", "version", "uninstall", "stop", "status", "logs",
+  "install", "installService", "uninstallService",
+]);
+
+/** Is this a command line that answers and leaves? */
+export function isOneShot(flags = {}) {
+  return ONE_SHOT.some((k) => flags[k] === true);
+}
+
 export function parseArgs(args) {
   const out = { unknown: [], incomplete: [] };
   for (let i = 0; i < args.length; i++) {
@@ -140,6 +159,14 @@ export function parseArgs(args) {
     else if (a === "-v" || a === "--version") out.version = true;
     else if (a === "-p" || a === "--port") set("port", "a port number");
     else if (a === "--no-open") out.noOpen = true;
+    else if (a === "--new") out.new = true;
+    else if (a === "--foreground") out.foreground = true;
+    else if (a === "--stop") out.stop = true;
+    else if (a === "--status") out.status = true;
+    else if (a === "--logs") out.logs = true;
+    else if (a === "--install") out.install = true;
+    else if (a === "--install-service") out.installService = true;
+    else if (a === "--uninstall-service") out.uninstallService = true;
     else if (a === "--uninstall") out.uninstall = true;
     else if (a === "--workspace") set("workspace", "a path");
     else if (a === "--scope") out.scope = true;

package/src/server/claude-accounts.mjs

@@ -151,6 +151,27 @@ function heldReading(now) {
 // without a marker would misrepresent them (its own trust ceiling is 3600s).
 const STALE_AFTER_MS = 15 * 60_000;
 
+/**
+ * How long a collector may produce nothing before that is a fault rather than a
+ * cadence.
+ *
+ * TWELVE HOURS, and the number is chosen from what the failure actually looks
+ * like rather than from taste. Measured on the machine that reported this: three
+ * accounts last collected 21 hours, 40 hours and 28 days ago, every one of them
+ * with `consecutiveFailures: 0` — because the thing stopping them was
+ * `keychain_unavailable`, which is claude-swap failing to OPEN the credential
+ * rather than having it rejected, and which never touches that counter.
+ *
+ * Long enough that a laptop closed overnight does not trip it. Short enough that
+ * an account nobody can read stops being advertised to the group as one they
+ * can. And the cost of being wrong is deliberately lopsided: a false "not
+ * collecting" asks a peer for a blob that `cswap import` then declines, because
+ * a plain import skips an account that is present and healthy — while the false
+ * negative this replaces is an account that is never repaired by anything, ever,
+ * and is published to every paired deck as good.
+ */
+const COLLECTION_STOPPED_AFTER_MS = 12 * 60 * 60_000;
+
 // Nudging the collector.
 //
 // Two throttles, because the cost of asking is not the cost of fetching. When
@@ -289,6 +310,94 @@ export function nextReadAt(row, matches, fetchedAtMs, isActive, now) {
  * Either way claude-swap decides whether a network call actually happens, and
  * this is throttled on top of that.
  */
+/**
+ * What claude-swap says about each slot, in its own words.
+ *
+ * `usage.json` records numbers and a failure COUNTER; `cswap list --json`
+ * records a per-slot VERDICT, and the two answer different questions. Measured
+ * on the machine this was written for, at one instant, for the same account:
+ *
+ *   usage.json  ->  consecutiveFailures: 0, lastError: null
+ *   cswap list  ->  usageStatus: "no_credentials"
+ *
+ * Three verdicts, three different things for a person to do — `no_credentials`
+ * is an account to receive or re-add, `relogin_required` is one to sign into,
+ * `keychain_unavailable` is not about the account at all but about the process
+ * asking. The counter can tell none of them apart, and for two of the three it
+ * reads zero.
+ *
+ * WHERE IT COMES FROM COSTS NOTHING EXTRA. nudgeCollector already spawns
+ * `cswap list` when a collection is due, and threw the output away. It now asks
+ * for `--json` and keeps the verdicts. Still not awaited by anyone — the nudge
+ * stays synchronous for its callers — and still one child at a time.
+ */
+let _verdicts = { at: 0, byNum: {} };
+/** Stale after this, because a verdict that outlives its cause is worse than no
+ *  verdict: "no credentials" under an account somebody has since signed into is
+ *  a sentence that sends them to fix what is already fixed. */
+const VERDICT_TTL_MS = 10 * 60_000;
+/** One `cswap list --json` at a time. A collection can take a while on a cold
+ *  network, and a nudge landing inside one must not start a second. */
+let _verdictInFlight = false;
+
+/**
+ * Ask claude-swap about one account RIGHT NOW, rather than reading the cache.
+ *
+ * The cached verdicts are ten minutes old at worst, which is right for a label
+ * and wrong for a decision that writes a credential: somebody who signed in two
+ * minutes ago still reads as `no_credentials` there, and acting on that would
+ * replace the login they just created with a peer's.
+ *
+ * Matched on IDENTITY rather than on the slot number, because a number is a
+ * position in one machine's store and the caller is holding an account.
+ *
+ * Returns null when the question cannot be answered — no claude-swap, a refusal,
+ * an account it does not know. Null is not `no_credentials`, and the one caller
+ * treats it as "do not act".
+ */
+export async function verdictNow(email, org, { runner = run, bin = cswapBin } = {}) {
+  const want = String(email ?? "").trim().toLowerCase();
+  if (!want) return null;
+  try {
+    const out = await runner(await bin(), ["list", "--json"], { timeout: VERDICT_TIMEOUT_MS });
+    if (!out?.ok) return null;
+    const d = JSON.parse(out.stdout);
+    // The same freshly-read answer feeds the cache the panel draws from, since
+    // it cost a subprocess either way.
+    const byNum = readVerdicts(out.stdout);
+    if (Object.keys(byNum).length) _verdicts = { at: Date.now(), byNum };
+    for (const a of Array.isArray(d?.accounts) ? d.accounts : []) {
+      if (String(a?.email ?? "").trim().toLowerCase() !== want) continue;
+      if ((a?.organizationUuid ?? "") !== (org ?? "")) continue;
+      return typeof a?.usageStatus === "string" ? a.usageStatus : null;
+    }
+    return null;
+  } catch { return null; }
+}
+
+/** claude-swap's verdict for a slot, or null when there is none fresh enough. */
+function verdictFor(num, now) {
+  if (now - _verdicts.at > VERDICT_TTL_MS) return null;
+  const v = _verdicts.byNum[String(num)];
+  return typeof v === "string" && v !== "" ? v : null;
+}
+
+/** Read the verdicts out of a `cswap list --json` payload. Tolerant by
+ *  construction: this is another tool's output, and a shape we do not recognise
+ *  means no verdicts rather than a thrown boot. */
+export function readVerdicts(stdout) {
+  try {
+    const d = JSON.parse(stdout);
+    const out = {};
+    for (const a of Array.isArray(d?.accounts) ? d.accounts : []) {
+      if (typeof a?.number === "number" && typeof a?.usageStatus === "string") {
+        out[String(a.number)] = a.usageStatus;
+      }
+    }
+    return out;
+  } catch { return {}; }
+}
+
 function nudgeCollector(rows, slots, now, activeNum) {
   // Did the last ask accomplish anything? Cheap proxy: the newest collection
   // timestamp in the store.
@@ -307,12 +416,35 @@ function nudgeCollector(rows, slots, now, activeNum) {
   if (!due && !freshen) return;
 
   _lastNudge = now;
-  const args = due ? ["list"] : ["auto", "--once", "--dry-run", "--json"];
+  // The due path asks for JSON and KEEPS it — see _verdicts. The dry-run path
+  // stays detached: it is the engine's own collect pass, its JSON is a different
+  // shape, and nothing here reads it.
+  if (!due) {
+    cswapBin().then(bin => runDetached(bin, ["auto", "--once", "--dry-run", "--json"])).catch(() => {});
+    return;
+  }
+  if (_verdictInFlight) return;
+  _verdictInFlight = true;
   // Fire-and-forget: this function is deliberately synchronous so callers never
-  // wait on it, and resolving the binary is the only async part.
-  cswapBin().then(bin => runDetached(bin, args)).catch(() => {});
+  // wait on it, and resolving the binary is the only async part. `run` rather
+  // than `runDetached` only so the output can be read; the caller is no more
+  // aware of it than before.
+  cswapBin()
+    .then(bin => run(bin, ["list", "--json"], { timeout: VERDICT_TIMEOUT_MS }))
+    .then(out => {
+      const byNum = out?.ok ? readVerdicts(out.stdout) : {};
+      // Replaced whole rather than merged. A slot that has gone away must not
+      // keep the verdict it had when it was last seen.
+      if (Object.keys(byNum).length) _verdicts = { at: Date.now(), byNum };
+    })
+    .catch(() => {})
+    .finally(() => { _verdictInFlight = false; });
 }
 
+/** Long enough for a cold collection over a slow network, short enough that a
+ *  wedged claude-swap does not hold a child for the rest of the day. */
+const VERDICT_TIMEOUT_MS = 90_000;
+
 async function readJson(path) {
   try {
     const parsed = JSON.parse(await readFile(path, "utf8"));
@@ -449,7 +581,9 @@ async function readRoster(now, gen) {
 
     const fetchedAtMs = matches && typeof row.fetchedAt === "number" ? row.fetchedAt * 1000 : null;
     const isActive = String(seq.activeAccountNumber) === num;
-    const trouble = authTrouble(row, { matches, isActive, identity, email: acct.email });
+    const trouble = authTrouble(row, {
+      matches, isActive, identity, email: acct.email, fetchedAt: fetchedAtMs, now,
+    });
 
     const lanes = [
       lane("five_hour", "5h", good?.five_hour),
@@ -502,6 +636,17 @@ async function readRoster(now, gen) {
       // in as it anyway. The panel says so quietly instead of offering to log
       // them in again.
       staleCopy: trouble?.kind === "stale-copy",
+      // Nothing has been collected for this account in half a day, and nothing
+      // says why. Its own word because the two existing ones would both be
+      // wrong: `error` claims a rejection that was never reported, and
+      // `staleCopy` promises the user is signed in as it, which is only
+      // knowable for the active account.
+      stopped:   trouble?.kind === "stopped",
+      // claude-swap's own verdict for this slot, when there is a fresh one:
+      // "no_credentials", "relogin_required", "keychain_unavailable", … It is
+      // what turns "not collecting" into a sentence with a next step in it, and
+      // it is null on every machine where the collector has not been asked yet.
+      collector: verdictFor(num, now),
     });
   }
 
@@ -541,8 +686,24 @@ async function readRoster(now, gen) {
  * evidence of anything, so the stored verdict stands: refusing to show a real
  * expiry because a subprocess failed is the opposite mistake.
  */
-export function authTrouble(row, { matches, isActive, identity, email } = {}) {
-  if (!matches || !((row?.consecutiveFailures ?? 0) > 0)) return null;
+export function authTrouble(row, {
+  matches, isActive, identity, email,
+  fetchedAt = null, now = Date.now(), stoppedAfterMs = COLLECTION_STOPPED_AFTER_MS,
+} = {}) {
+  if (!matches) return null;
+  const failing = (row?.consecutiveFailures ?? 0) > 0;
+  // A COLLECTOR THAT HAS PRODUCED NOTHING IN HALF A DAY IS FAILING, whatever
+  // its counter says — see COLLECTION_STOPPED_AFTER_MS. `consecutiveFailures`
+  // counts rejections, and the failure found on the reporting machine was not a
+  // rejection: `cswap list` answered `usageStatus: keychain_unavailable` for
+  // three accounts whose counters all read zero.
+  //
+  // `fetchedAt == null` is deliberately NOT this. That is an account nobody has
+  // ever collected — usually one added a minute ago — and the panel already has
+  // a word for it. Calling a new account broken is a worse first impression than
+  // saying nothing.
+  const stopped = !failing && fetchedAt != null && now - fetchedAt > stoppedAfterMs;
+  if (!failing && !stopped) return null;
 
   const signedInHere = isActive
     && identity
@@ -555,6 +716,12 @@ export function authTrouble(row, { matches, isActive, identity, email } = {}) {
     // fix under a red badge, and it must not offer to sign them in again.
     return { kind: "stale-copy", error: null };
   }
+  // A SILENCE, NOT A DIAGNOSIS. All that is known is that nothing has been
+  // collected for half a day; the reason lives in claude-swap and may be a dead
+  // login, a keychain it cannot open, or a machine that was off. Putting
+  // `invalid_grant` on it would be inventing evidence, and the panel would then
+  // offer "sign in again" for a problem that may not be a sign-in at all.
+  if (stopped) return { kind: "stopped", error: null };
   return { kind: "auth", error: row.lastError ?? "error" };
 }
 

package/src/server/cswap-admin.mjs

@@ -987,6 +987,23 @@ export async function shareAccounts(nums) {
 }
 
 
+/**
+ * Did anything actually arrive in the store?
+ *
+ * THREE STATES MEAN YES AND THEY ARE NOT INTERCHANGEABLE. `imported` is a slot
+ * that did not exist; `healed` and `updated` are one that did and was rewritten,
+ * which is what a forced import produces and what `added` — counting `imported`
+ * alone — reports as nothing having happened. A caller that asked for a replace
+ * and read `added` would conclude its own success had failed.
+ *
+ * `present` is the decline: claude-swap kept what it had. `failed` is the
+ * refusal. Neither is an arrival.
+ */
+export function landed(results) {
+  return (Array.isArray(results) ? results : [])
+    .some(r => r?.state === "imported" || r?.state === "healed" || r?.state === "updated");
+}
+
 /**
  * The identities a bundle carries, or `[]` when it cannot be read.
  *

package/src/server/deck-home.mjs

@@ -0,0 +1,243 @@
+// Where the deck keeps its OWN things, as opposed to where Claude Code keeps
+// its things.
+//
+// For a year those were one directory. `~/.claude/agent-dag/` held the hook
+// Claude Code reads, the deck's private key, its pairings, its port registry
+// and a hundred megabytes of event log — and the only reason was that the deck
+// already knew that path, because it has to read `~/.claude` to do its job at
+// all.
+//
+// THREE THINGS THAT COST, and none of them is tidiness:
+//
+//   A person who deletes ~/.claude to fix Claude Code deletes this deck's
+//   identity. The key is what every paired machine has pinned, so it is not a
+//   setting that comes back — every colleague has to accept this deck again.
+//
+//   CLAUDE_CONFIG_DIR is Claude Code's knob for keeping a second profile, and
+//   pointing it somewhere gave the deck a brand new identity and no pairings,
+//   silently. That is a footgun with a fifty-machine blast radius and no error
+//   message anywhere.
+//
+//   The event log is a hundred megabytes of the deck's data inside another
+//   application's configuration directory. Nothing about a rotating log is
+//   configuration.
+//
+// So the deck's own state moves to where this platform keeps application data,
+// and the two things that CANNOT move stay where they are: `hook.js`, because
+// Claude Code reads it from there, and the per-pid port registry, because a
+// deck of any version has to be able to list the others — see
+// registeredDeckPorts, which reads that directory by name.
+//
+// The layout is env-paths', which is what Node command-line tools converge on,
+// and its rule is the one worth repeating: XDG is a Linux specification, so it
+// applies on Linux and nowhere else. macOS has Application Support and Logs;
+// Windows has LocalAppData. A tool that puts ~/.config on a Mac is a tool that
+// read half the page.
+//
+// NOTHING IS DELETED BY THE MOVE. Every file is COPIED to its new home and the
+// original left where it was, so a deck downgraded to the version before this
+// one finds exactly what it had. See migrateDeckFiles.
+import { homedir } from "node:os";
+import { join, posix as posixPath, win32 as winPath } from "node:path";
+import { claudeConfigDir } from "./claude-dir.mjs";
+// The Windows ladder, not `rename` (#786). MoveFileExW refuses while any other
+// process holds the destination open — a scanner, the indexer, a backup agent —
+// and the file this one renames into place is a private key. Losing that rename
+// to a virus scanner would be a deck with no identity, which is the one outcome
+// this whole module is written to prevent.
+import { renameWithRetry } from "./installer.mjs";
+
+/** The name this deck files itself under. No `-nodejs` suffix, which env-paths
+ *  adds to keep a script from colliding with a native app of the same name —
+ *  there is no other ccdeck on any of these platforms. */
+const APP = "ccdeck";
+
+/** Point the deck's whole home somewhere else in one variable. The escape
+ *  hatch for a portable install, a test, or anybody who simply wants it
+ *  elsewhere; it wins over every rule below. */
+export const HOME_ENV = "CCDECK_HOME";
+
+/** Where the deck kept everything before this, and where two of its files still
+ *  live. Also the place a migration reads from. */
+export function legacyDeckDir(env = process.env, home = homedir(), platform = process.platform) {
+  const { join } = platform === "win32" ? winPath : posixPath;
+  return join(claudeConfigDir(env, home), "agent-dag");
+}
+
+/**
+ * The deck's own durable state: its key, its pairings, the accounts it offers.
+ *
+ * CLAUDE_CONFIG_DIR IS HONOURED RATHER THAN OVERRIDDEN, and that is deliberate.
+ * Somebody who set it has asked for a separate Claude profile and has been
+ * getting a separate deck along with it for a year — separate identity,
+ * separate pairings, separate share list. Moving those people to one
+ * machine-wide deck would collapse two profiles into one on upgrade, which is
+ * exactly the kind of silent change this file exists to stop. They keep what
+ * they have; everybody else moves.
+ */
+export function deckDataDir(platform = process.platform, env = process.env, home = homedir()) {
+  // THE TARGET PLATFORM'S SEPARATOR, NOT THE HOST'S — the same reason
+  // claudeCliCandidates does it, which is that the only way a Windows answer
+  // stays right is if it can be checked from a Mac. `node:path` joins with
+  // whatever the machine running the code uses, so a bare `join` here answers
+  // `\home\u\Library\...` on Windows for a question about macOS.
+  // `resolve` for the same reason as `join` just below it: it is host-bound
+  // too, so a posix path resolved on a Windows runner comes back with the
+  // runner's drive letter glued to the front of it.
+  const { join, resolve } = platform === "win32" ? winPath : posixPath;
+  const forced = env[HOME_ENV]?.trim();
+  if (forced) return resolve(forced);
+  if (env.CLAUDE_CONFIG_DIR?.trim()) return legacyDeckDir(env, home, platform);
+  if (platform === "darwin") return join(home, "Library", "Application Support", APP);
+  if (platform === "win32") return join(localAppData(env, home, platform), APP, "Data");
+  return join(env.XDG_DATA_HOME?.trim() || join(home, ".local", "share"), APP);
+}
+
+/**
+ * Where a log belongs, which is not where a preference belongs.
+ *
+ * On Linux that is the state directory rather than the data one: XDG separates
+ * "data the user would miss" from "state the program can rebuild", and an event
+ * log that rotates at 50 MB is the second. macOS and Windows have a named place
+ * for logs and this uses it.
+ */
+export function deckLogDir(platform = process.platform, env = process.env, home = homedir()) {
+  const { join, resolve } = platform === "win32" ? winPath : posixPath;
+  const forced = env[HOME_ENV]?.trim();
+  if (forced) return resolve(forced);
+  if (env.CLAUDE_CONFIG_DIR?.trim()) return legacyDeckDir(env, home, platform);
+  if (platform === "darwin") return join(home, "Library", "Logs", APP);
+  if (platform === "win32") return join(localAppData(env, home, platform), APP, "Log");
+  return join(env.XDG_STATE_HOME?.trim() || join(home, ".local", "state"), APP);
+}
+
+/** %LOCALAPPDATA%, or the path it points at on every Windows since Vista. The
+ *  fallback is not decoration: a service account or a stripped environment can
+ *  reach this code with the variable unset, and a deck that throws there is a
+ *  deck that will not start. */
+function localAppData(env = process.env, home = homedir(), platform = process.platform) {
+  const { join } = platform === "win32" ? winPath : posixPath;
+  return env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local");
+}
+
+/**
+ * WHAT MOVES, and the two things that do not.
+ *
+ * `hook.js` stays: Claude Code reads it out of ~/.claude/agent-dag and would
+ * find nothing if it moved. The per-pid `NNNNN.json` files stay: a deck lists
+ * that directory to find the other decks on this machine, and a deck of the
+ * previous version reads it by name — move them and two versions running side
+ * by side stop seeing each other.
+ *
+ * `mode` is the file's, not the directory's, and 0600 on the preferences is
+ * load-bearing: it is the one file with a private key in it.
+ */
+export const MOVED = Object.freeze([
+  Object.freeze({ name: "prefs.json", where: "data", mode: 0o600 }),
+  Object.freeze({ name: "events.jsonl", where: "log", mode: 0o644 }),
+  Object.freeze({ name: "events.jsonl.1", where: "log", mode: 0o644 }),
+]);
+
+/**
+ * Bring a deck's files to their new home, once, and never at the cost of one.
+ *
+ * FOUR RULES, and each one is a way this could have lost somebody's key:
+ *
+ *   A destination that already exists is never touched. That is what makes
+ *   this safe to run at every boot, and it is also what stops a stale copy in
+ *   the old directory from overwriting live state later.
+ *
+ *   The copy lands on a temp file in the destination directory and is renamed
+ *   into place. A copy interrupted half-way is a truncated prefs.json, and a
+ *   truncated prefs.json is a deck with no key — which is the whole thing this
+ *   is trying not to do.
+ *
+ *   The original is LEFT WHERE IT IS. Somebody who downgrades finds what they
+ *   had. It costs four kilobytes and a hundred megabytes of log that was
+ *   already there, and it buys a move nobody can be hurt by.
+ *
+ *   A failure is reported and swallowed. A read-only home, a full disk, a
+ *   permission the installer never had — none of those is a reason for the
+ *   deck not to start, and the caller falls back to reading the old path.
+ *
+ * Returns what it did, so the caller can say so once rather than every boot.
+ */
+export async function migrateDeckFiles({
+  from,
+  data,
+  log,
+  fs,
+  /** Separate from `fs` because it is not `fs.rename`: see the import above. */
+  rename = renameWithRetry,
+  onError,
+} = {}) {
+  const moved = [];
+  const failed = [];
+  for (const file of MOVED) {
+    const dir = file.where === "log" ? log : data;
+    const src = join(from, file.name);
+    const dst = join(dir, file.name);
+    if (src === dst) continue;
+    try {
+      // Both questions asked before anything is written: there is something to
+      // move, and there is nothing already there.
+      if (!(await exists(fs, src))) continue;
+      if (await exists(fs, dst)) continue;
+      await fs.mkdir(dir, { recursive: true, mode: 0o700 });
+      const tmp = `${dst}.${process.pid}.migrating`;
+      await fs.copyFile(src, tmp);
+      await fs.chmod(tmp, file.mode).catch(() => {});
+      await rename(tmp, dst);
+      moved.push(file.name);
+    } catch (err) {
+      failed.push(file.name);
+      onError?.(file.name, err);
+    }
+  }
+  return { moved, failed };
+}
+
+async function exists(fs, path) {
+  try { await fs.stat(path); return true; } catch { return false; }
+}
+
+/** An hour. A temp file younger than this may belong to a write happening in
+ *  another deck right now, and deleting one of those turns an atomic write into
+ *  a lost one. Nothing legitimate is an hour old: the rename that retires a
+ *  temp file happens within milliseconds of its creation. */
+export const TEMP_STALE_MS = 60 * 60 * 1000;
+
+/**
+ * The litter an atomic write leaves when the process is killed between the
+ * write and the rename.
+ *
+ * Ninety-seven of them were found in one directory, the oldest six days old:
+ * two waves, one from decks that crashed and one from decks killed by hand
+ * mid-write. Nothing has ever swept them, because the code that makes them is
+ * the code that is not running any more when they are made.
+ *
+ * So the sweep belongs at START, where a process that is alive can clean up
+ * after the ones that are not — and it is deliberately blind to WHICH deck made
+ * a file, because it cannot know: it goes by age instead, which is a fact about
+ * the file rather than a guess about a pid.
+ */
+export async function sweepTempFiles({ dirs, fs, now = Date.now(), onError } = {}) {
+  let removed = 0;
+  for (const dir of dirs ?? []) {
+    let names;
+    try { names = await fs.readdir(dir); } catch { continue; }
+    for (const name of names) {
+      if (!name.endsWith(".tmp") && !name.endsWith(".migrating")) continue;
+      const path = join(dir, name);
+      try {
+        const st = await fs.stat(path);
+        if (now - st.mtimeMs < TEMP_STALE_MS) continue;
+        await fs.unlink(path);
+        removed++;
+      } catch (err) {
+        onError?.(path, err);
+      }
+    }
+  }
+  return removed;
+}