ccdeck 3.22.14 → 3.23.0

package/src/server/deck-prefs.mjs

@@ -23,15 +23,26 @@
 // each would be a switch nobody could reason about.
 //
 // The write is the atomic one browser-watch-store.mjs argues for at length —
-// temp file, rename — because the alternative is a truncated JSON document as
-// the only record of what the user chose, and a corrupt file here silently
-// turns the notifications back on.
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+// temp file, fsync, rename — because the alternative is a truncated JSON
+// document as the only record of what the user chose.
+//
+// And the READ is the other half of that sentence, which took #1002 to notice.
+// An atomic write makes a truncated prefs.json rare; it does not make it
+// impossible — a full disk, a power cut, an editor saving garbage — and what
+// the deck did when it met one was read it as "nothing chosen yet" and then
+// write defaults over it, destroying the LAN key every paired machine had
+// pinned. A file that cannot be parsed is now moved aside and said out loud;
+// only a genuinely ABSENT file starts clean. See loadPrefs.
+import { chmod, mkdir, readFile, unlink } from "node:fs/promises";
 // The rename, with the Windows retry ladder installer.mjs wrote for exactly
-// this call. See the note over the write below (#786).
-import { renameWithRetry } from "./installer.mjs";
+// this call. See the note over the write below (#786). `stripBom` and
+// `createTemp` come from the same module for the reason its export block gives:
+// a rule spelled twice is a rule that drifts, and both of these are rules
+// settings.json and auth.json already follow on files with the same stakes.
+import { createTemp, renameWithRetry, stripBom } from "./installer.mjs";
 import { join } from "node:path";
 import { deckDataDir } from "./deck-home.mjs";
+import { PRODUCT } from "./brand.mjs";
 
 /** Set to "1" to keep the deck off the desktop whatever the stored preference
  *  says. Same sheet of switches as AGENTS_DECK_NO_DOWNLOAD and
@@ -89,6 +100,11 @@ export const DEFAULTS = Object.freeze({
     // until somebody ticks a login: the gate that did not change.
     autoAsk: true,
     autoAccept: false,
+    // WHICH ACCOUNT THIS DECK IS ON, told to the decks it is paired with — and
+    // only ever one it shares, so an unticked account is never named. On, so two
+    // of one person's machines show each other where they are working; off, and
+    // paired decks read "current account hidden" instead.
+    shareActive: true,
     // What somebody HERE calls another deck, keyed by its fingerprint. The name
     // a deck gives itself is its owner's to choose; this is the other half.
     aliases: Object.freeze({}),
@@ -102,10 +118,12 @@ export const DEFAULTS = Object.freeze({
  *  machine the default mode hands it to every other account on the box, and
  *  from it they can decrypt any credential that crosses the network.
  *
- *  Passed to `writeFile` rather than applied with a follow-up chmod, and the
+ *  Named on the CREATE rather than applied with a follow-up chmod, and the
  *  difference is the whole point — claude-swap's transfer.py makes the same
- *  argument at length: a write-then-chmod leaves the file readable for the
- *  window between the two, which is exactly when a secret is in it. */
+ *  argument at length: a create-then-chmod leaves the file readable for the
+ *  window between the two, which is exactly when a secret is in it. The chmod
+ *  that does follow the create is not that: it only pins a file the umask may
+ *  have made narrower, and cannot widen one past what the create allowed. */
 export const PREFS_MODE = 0o600;
 
 /** The longest name somebody here may give another deck. The same order as a
@@ -192,6 +210,9 @@ function normaliseLan(raw) {
     // overrides it, because a truthy string from a hand-edited file is not an
     // answer.
     autoAccept: typeof src.autoAccept === "boolean" ? src.autoAccept : DEFAULTS.lan.autoAccept,
+    // Whether paired decks are told which shared account this one is on. Absent
+    // is on — the default above — and only a real boolean turns it off.
+    shareActive: typeof src.shareActive === "boolean" ? src.shareActive : DEFAULTS.lan.shareActive,
   };
 }
 
@@ -210,12 +231,102 @@ export function normalise(raw) {
   };
 }
 
-/** What is on disk, or the defaults. A corrupt or absent file is not an error
- *  the user can act on mid-session, so it reads as "nothing chosen yet". */
-export async function readPrefs(home = deckDataDir(), deps = {}) {
+/** Where the bytes of a prefs.json nothing could parse are put.
+ *
+ *  `Date.now()` rather than an ISO timestamp because a colon is not a legal
+ *  filename character on Windows, and a quarantine that cannot be created on
+ *  the platform it is protecting is not a quarantine. */
+export const quarantinePath = (home = deckDataDir(), at = Date.now()) =>
+  `${prefsPath(home)}.corrupt-${at}`;
+
+/** The refusal `writePrefs` throws rather than merge onto a base it knows is
+ *  not the user's. Shaped like installer.mjs's SETTINGS_UNREADABLE, which is
+ *  the same policy on the other file this deck rewrites: a file we cannot
+ *  reproduce is never treated as an empty one. */
+function unreadablePrefs(path, why) {
+  const err = new Error(
+    `${path} could not be read (${why}). Refusing to overwrite it — this deck's ` +
+    `LAN key and its pairings are in there and cannot be re-derived. Fix the ` +
+    `file or move it aside, then restart ${PRODUCT}.`,
+  );
+  err.code = "PREFS_UNREADABLE";
+  err.prefsPath = path;
+  err.why = why;
+  return err;
+}
+
+/**
+ * Read prefs.json, and say WHICH of four things happened — because three of
+ * them hand back the same object and only one of them means it.
+ *
+ * WHY THE SOURCE IS PART OF THE ANSWER. The old read collapsed "no file yet"
+ * and "a file nothing could parse" into one silent `{ ...DEFAULTS }`, which is
+ * a defensible answer to a question about VALUES and a catastrophic one as the
+ * merge base of a write. A power cut or an OOM kill between the write and the
+ * rename leaves a truncated prefs.json; the next boot read it as "nothing
+ * chosen yet", found an empty `lan.secret`, generated a new identity and wrote
+ * it — over the file that still had the old key, the pairings, the shared
+ * accounts and the dialled addresses legibly in it. Every peer that had pinned
+ * this deck had to accept it again, and nothing anywhere said why.
+ *
+ *   "file"       parsed. These are the user's own settings.
+ *   "missing"    ENOENT, and only ENOENT. Nothing has been chosen yet;
+ *                defaults, silently, which is what a first start is.
+ *   "corrupt"    bytes that are not JSON. Moved aside to `quarantined` BEFORE
+ *                this returns, so nothing can merge over them.
+ *   "unreadable" the read itself failed for some reason other than absence — a
+ *                permission, a directory in the way. The file is still there
+ *                and still unread, which is exactly when a write must not land.
+ *
+ * A BYTE-ORDER MARK IS NOT DAMAGE. Notepad and `Set-Content` write one, and
+ * `JSON.parse` throws on it — so stripping it here is what keeps a perfectly
+ * good hand-edited file out of quarantine. Same call installer.mjs makes on
+ * settings.json for the same reason.
+ */
+export async function loadPrefs(home = deckDataDir(), deps = {}) {
   const read = deps.readFile ?? readFile;
-  try { return normalise(JSON.parse(await read(prefsPath(home), "utf8"))); }
-  catch { return { ...DEFAULTS }; }
+  const warn = deps.warn ?? console.error;
+  const path = prefsPath(home);
+  const defaults = () => ({ ...DEFAULTS });
+
+  let raw;
+  try {
+    raw = await read(path, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return { prefs: defaults(), source: "missing", quarantined: "" };
+    warn(`${PRODUCT}: could not read ${path}: ${err?.message ?? err}. Leaving it alone — settings will not be saved until it can be read.`);
+    return { prefs: defaults(), source: "unreadable", quarantined: "" };
+  }
+
+  try {
+    return { prefs: normalise(JSON.parse(stripBom(raw))), source: "file", quarantined: "" };
+  } catch (err) {
+    const why = err?.message ?? String(err);
+    const mv = deps.rename ?? renameWithRetry;
+    const to = quarantinePath(home);
+    try {
+      await mv(path, to);
+    } catch (moveErr) {
+      // ENOENT means somebody else moved it between the read and the rename —
+      // a second deck booting on the same machine. The bytes are safe, just not
+      // under a name this read chose, and what is at `path` now is nothing.
+      if (moveErr?.code === "ENOENT") return { prefs: defaults(), source: "missing", quarantined: "" };
+      // Anything else and the damaged file is STILL THERE, unread and
+      // unprotected. Saying so is the whole point: `writePrefs` refuses on it.
+      warn(`${PRODUCT}: ${path} could not be read as JSON (${why}), and could not be moved aside either: ${moveErr?.message ?? moveErr}. Settings will not be saved until it is fixed or moved.`);
+      return { prefs: defaults(), source: "corrupt", quarantined: "" };
+    }
+    warn(`${PRODUCT}: ${path} could not be read as JSON (${why}). It has been kept as ${to} and this deck is starting with fresh settings — its LAN key and its pairings are in that file, so do not delete it if you want them back.`);
+    return { prefs: defaults(), source: "corrupt", quarantined: to };
+  }
+}
+
+/** What is on disk, or the defaults — the VALUES alone, for the callers that
+ *  want nothing else. `loadPrefs` is the same read with the answer to "and was
+ *  that really the user's file?" still attached; anything about to write must
+ *  ask that question, and does. */
+export async function readPrefs(home = deckDataDir(), deps = {}) {
+  return (await loadPrefs(home, deps)).prefs;
 }
 
 let _chain = Promise.resolve();
@@ -232,35 +343,140 @@ let _chain = Promise.resolve();
  *
  * Serialized for the same reason the other store is: two pages toggling two
  * different switches in the same second must not lose one of them.
+ *
+ * AND IT REFUSES RATHER THAN MERGE ONTO A BASE THAT IS NOT THE USER'S. The
+ * merge above exists to PRESERVE what the caller did not send; handed the
+ * defaults because `loadPrefs` could not read the file, it preserves nothing
+ * and the write becomes the thing that destroys the key. So the two failures
+ * that read as defaults are separated: a file that was moved aside is safe to
+ * start clean over, and one still sitting there unread is not. See
+ * installer.mjs's readSettingsForWrite, which is this policy on settings.json.
  */
 export async function writePrefs(patch, home = deckDataDir(), deps = {}) {
-  const job = async () => {
-    const mk = deps.mkdir ?? mkdir;
-    const write = deps.writeFile ?? writeFile;
-    // `renameWithRetry`, not `rename` (#786). MoveFileExW refuses while any
-    // handle without FILE_SHARE_DELETE is open on either side, and Defender and
-    // the search indexer open a file the instant it is written — so on Windows
-    // a bare rename fails on a perfectly healthy machine, `POST /api/prefs`
-    // 500s through `guard`, and the notifications switch silently does not
-    // stick. POSIX rename(2) has no such rule, which is why this shipped green.
-    const mv = deps.rename ?? renameWithRetry;
-    const prev = await readPrefs(home, deps);
-    // The LAN section merges rather than replaces, so a page toggling the
-    // switch does not have to send the passphrase back to keep it — and so
-    // nothing has to send a secret it was never given.
-    const merged = { ...prev, ...patch, lan: { ...prev.lan, ...(patch?.lan ?? {}) } };
-    const next = normalise(merged);
-    await mk(prefsDir(home), { recursive: true, mode: 0o700 });
-    const tmp = `${prefsPath(home)}.${process.pid}.tmp`;
-    await write(tmp, JSON.stringify(next, null, 2) + "\n", { encoding: "utf8", mode: PREFS_MODE });
-    await mv(tmp, prefsPath(home));
-    return next;
-  };
+  return queued(() => save(() => patch, home, deps));
+}
+
+/**
+ * Change some of the preferences from what the write is about to READ.
+ *
+ * The twin of `updateStore` in browser-watch-store.mjs, made for the same
+ * reason and shaped the same way: `mutate(prev)` runs INSIDE the queued job,
+ * after that job's own `loadPrefs` and after the two guards that decide whether
+ * this file may be written at all, so the patch is a function of the file
+ * rather than of a copy somebody took earlier — and a caller that computes one
+ * never sees the defaults `loadPrefs` returns for a file it refused to write
+ * over.
+ *
+ * WHICH CALLERS NEED IT, AND WHY A PATCH IS NOT ENOUGH ON ITS OWN. `writePrefs`
+ * already merges field by field, so two writes naming two different fields
+ * cannot lose each other. What it cannot do is merge two writes of the SAME
+ * field, and three callers compute one whole field — `lan.manual` twice and
+ * `lan.aliases` once — out of `index.mjs`'s module-level `_prefs`, which is
+ * refreshed only when a previous write resolves. Two of them in one turn both
+ * read before either job runs, and the second patch is a whole array or a whole
+ * map without the first's entry in it: both answer 200, both panels redraw, one
+ * change is never written.
+ *
+ * Measured against this file in a temp directory, with those exact call shapes,
+ * starting from `manual: ["10.0.0.1:5000"]`:
+ *
+ *     memory manual  = ["10.0.0.1:5000","10.0.0.3:5002"]   # the onDial entry is gone
+ *     disk   manual  = ["10.0.0.1:5000","10.0.0.3:5002"]
+ *
+ * The alias route carried a comment claiming the opposite — "the whole map is
+ * rebuilt from the one on disk rather than sent by the page, so two tabs
+ * renaming two decks cannot undo each other" — which is the sentence this makes
+ * true.
+ *
+ * `mutate` returns a PATCH, not a whole state, so the merge doctrine above is
+ * unchanged: a field nobody mentions keeps its value. It may return nothing,
+ * which means "no change" and still rewrites the file with what it read.
+ */
+export async function updatePrefs(mutate, home = deckDataDir(), deps = {}) {
+  return queued(() => save(mutate, home, deps));
+}
+
+/** One read-modify-write, behind every other one. Both entry points go through
+ *  here so there is a single queue and a single merge. */
+function queued(job) {
   const started = _chain.then(job, job);
   _chain = started.then(() => {}, () => {});
   return started;
 }
 
+async function save(mutate, home, deps) {
+  const mk = deps.mkdir ?? mkdir;
+  const temp = deps.createTemp ?? createTemp;
+  const setMode = deps.chmod ?? chmod;
+  const drop = deps.unlink ?? unlink;
+  // `renameWithRetry`, not `rename` (#786). MoveFileExW refuses while any
+  // handle without FILE_SHARE_DELETE is open on either side, and Defender and
+  // the search indexer open a file the instant it is written — so on Windows
+  // a bare rename fails on a perfectly healthy machine, `POST /api/prefs`
+  // 500s through `guard`, and the notifications switch silently does not
+  // stick. POSIX rename(2) has no such rule, which is why this shipped green.
+  const mv = deps.rename ?? renameWithRetry;
+  const target = prefsPath(home);
+  const { prefs: prev, source, quarantined } = await loadPrefs(home, deps);
+  if (source === "unreadable") throw unreadablePrefs(target, "the read failed");
+  if (source === "corrupt" && !quarantined) {
+    throw unreadablePrefs(target, "it is not JSON and could not be moved aside");
+  }
+  // INSIDE THE JOB, after the read above and after the two guards that
+  // decide whether this file may be written at all — see `updatePrefs`.
+  // `writePrefs` hands over a constant here, which is what makes the two
+  // one function.
+  const patch = await mutate(prev);
+  // The LAN section merges rather than replaces, so a page toggling the
+  // switch does not have to send the passphrase back to keep it — and so
+  // nothing has to send a secret it was never given.
+  const merged = { ...prev, ...patch, lan: { ...prev.lan, ...(patch?.lan ?? {}) } };
+  const next = normalise(merged);
+  await mk(prefsDir(home), { recursive: true, mode: 0o700 });
+  // `createTemp`, not a name built out of the pid alone.
+  //
+  // The splice browser-watch-store.mjs met is NOT the hazard here: `_chain`
+  // above serializes every write in this process, and two decks on one home
+  // have two pids. The hazard is the LEFTOVER. A deck killed between the
+  // create and the rename strands a temp file with this deck's private key
+  // in it under a name derived from its pid, the old code never unlinked one
+  // on failure either — and `writeFile`'s `mode` applies only when the call
+  // CREATES the file, so a later deck the OS hands that pid back adopted the
+  // stranded file whole, keeping whatever permissions it had, and wrote the
+  // key into it. O_EXCL is what turns a taken name into an error the caller
+  // handles instead, and it is also what makes PREFS_MODE binding from the
+  // first byte rather than a hope about what was there before. codex-auth.mjs
+  // argues all of this at length over the one other secret this deck stages
+  // through a temp file.
+  const { tmp, handle } = await temp(target, { mode: PREFS_MODE });
+  let landed = false;
+  try {
+    try {
+      await handle.writeFile(JSON.stringify(next, null, 2) + "\n", "utf8");
+      // The fsync is the half of "atomic" a rename alone does not buy. A
+      // rename orders the directory entry; it does not order the BYTES, so a
+      // machine that loses power just after it can come up with the entry
+      // pointing at a file that was never flushed — which is the truncated
+      // prefs.json this whole read path now exists to survive.
+      await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    // The umask only ever clears bits off the creation mode, so the key is
+    // never wider than 0600 — but it can land narrower, and a prefs.json at
+    // 0400 is one this writer cannot replace next time. On Windows chmod's
+    // only effect is the read-only bit, and a read-only target is one no
+    // rename can replace. Pin it either way.
+    await setMode(tmp, PREFS_MODE);
+    await mv(tmp, target);
+    landed = true;
+  } finally {
+    // A temp left behind holds this deck's private key in cleartext.
+    if (!landed) await drop(tmp).catch(() => {});
+  }
+  return next;
+}
+
 /**
  * May the deck raise a desktop notification right now?
  *

package/src/server/deck-probe.mjs

@@ -30,7 +30,7 @@ import { request as httpRequest } from "node:http";
 // The same deadline hook.js gives a challenge, and for the same reason: a
 // bodyless GET to a loopback port is sub-millisecond when a deck is there and an
 // instant ECONNREFUSED when nothing is.
-export const DECK_CHALLENGE_TIMEOUT_MS = 400;
+const DECK_CHALLENGE_TIMEOUT_MS = 400;
 
 // Signal 0 delivers nothing; it asks whether the pid could be signalled.
 //

package/src/server/exec.mjs

@@ -402,6 +402,81 @@ export function killTree(child, signal) {
   }
 }
 
+/**
+ * Every child this module started and has not yet seen the end of.
+ *
+ * A deadline is not a promise unless something is alive to enforce it, and the
+ * deadlines in this file all live in the parent: `run` states the outcome on a
+ * timer and only then kills, `runInteractive` does the same. Kill the parent
+ * and the timer dies with it, so the very case a deadline exists for — a tool
+ * that has hung — is the one case where nothing is left to stop it.
+ *
+ * Observed (#1012). A sandboxed deck, a quota poll in flight, SIGINT to the
+ * deck at 05:26:22.706. The deck was gone within 200ms; its `claude --print
+ * /usage` child, spawned at 05:26:18.078 under a 15-second deadline, was still
+ * running at 05:26:35.204 — reparented to init, past the deadline the dead
+ * parent would have enforced, and with nothing anywhere that would ever kill
+ * it. A whole Claude Code process, hundreds of MB resident, orphaned by a
+ * Ctrl+C.
+ *
+ * REMOVED ON 'close', NOT ON 'exit', and the difference is Windows'. A batch
+ * candidate runs THROUGH cmd.exe and the tool is a grandchild (see viaCmd and
+ * killTree): the wrapper can exit while the tool underneath goes on holding
+ * the inherited stdio, which is exactly the shape killTree's `taskkill /T`
+ * exists for. 'exit' there means "the wrapper is gone" and 'close' means "and
+ * so is everything it started" — forgetting on the first would drop a tree
+ * that is still running and still reachable. 'error' is the third way a child
+ * ends, and the only one after which 'close' may never come at all.
+ *
+ * `runDetached` is deliberately absent. It is the one function here named for
+ * outliving its call — a sound, or a collection whose result lands in a file
+ * the next poll reads — it holds no deadline, and it unrefs its child on
+ * purpose. Killing those on the way out would be this set overreaching.
+ */
+const live = new Set();
+
+/** Track one child until it ends. Returns it, so it can wrap a spawn inline. */
+function watchChild(cp) {
+  if (!cp) return cp;
+  live.add(cp);
+  const forget = () => { live.delete(cp); };
+  cp.once?.("close", forget);
+  cp.once?.("error", forget);
+  return cp;
+}
+
+/**
+ * The pids of the children this deck still has running.
+ *
+ * Exported for the test below this, and because it is the honest answer to
+ * "what is this deck still doing" that a future `--status` wants. It may
+ * over-report by one in the Windows case above — a wrapper whose 'close' never
+ * arrives stays here — which is the right direction to be wrong in: that entry
+ * names a process that really is still running.
+ */
+export const liveChildPids = () => [...live].map(c => c?.pid).filter(Boolean);
+
+/**
+ * Stop every child this module started, and everything they started.
+ *
+ * Called from shutdown(), where the alternative is the orphan above. It does
+ * not WAIT for the corpses, on purpose: a signal is delivered synchronously on
+ * POSIX, and on Windows killTree's taskkill is a process of its own that
+ * CreateProcess has already started by the time spawn() returns and that
+ * outlives this one. Waiting would buy nothing and would spend the ~200ms exit
+ * that is the rest of shutdown's good behaviour.
+ *
+ * The set is cleared first so a 'close' arriving mid-loop cannot mutate what
+ * is being iterated, and so a second call — shutdown can be reached twice —
+ * has nothing left to do.
+ */
+export function killLiveChildren(signal) {
+  const doomed = [...live];
+  live.clear();
+  for (const cp of doomed) killTree(cp, signal);
+  return doomed.length;
+}
+
 // Reasons to try the next candidate spelling rather than give up. EINVAL and
 // UNKNOWN show up on Windows for a file that exists but cannot be executed the
 // way it was asked for; both mean "not this one", not "no such tool".
@@ -695,8 +770,11 @@ export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20, env } =
       };
 
       try {
-        const cp = execFile(file, argv,
-          { timeout: 0, shell: false, windowsHide: true, maxBuffer, ...(env ? { env } : {}), ...opts }, done);
+        // watchChild: this run's deadline lives in the timer below, in THIS
+        // process, so a shutdown that does not reap it leaves the child with
+        // no deadline at all. See `live` above, and #1012.
+        const cp = watchChild(execFile(file, argv,
+          { timeout: 0, shell: false, windowsHide: true, maxBuffer, ...(env ? { env } : {}), ...opts }, done));
         // Give the child EOF on stdin straight away, which is what this
         // function's contract has always claimed ("run closes stdin", says
         // runInteractive's header) and what execFile does not do: it leaves the
@@ -853,7 +931,10 @@ export function runInteractive(cmd, args, { timeout = 300_000, maxOutput = 256 <
     const { file, args: argv, opts, launch } = candidateSpec(raw, args);
     let proc;
     try {
-      proc = spawn(file, argv, { stdio: ["pipe", "pipe", "pipe"], shell: false, windowsHide: true, ...opts });
+      // Tracked for the same reason `run`'s child is, and with more at stake:
+      // this one's deadline is five minutes and it is a `claude auth login`
+      // blocked on a stdin pipe only this process holds. See `live` above.
+      proc = watchChild(spawn(file, argv, { stdio: ["pipe", "pipe", "pipe"], shell: false, windowsHide: true, ...opts }));
     } catch (err) {
       return tryNext(err) ? attempt(i + 1) : finish(-1, err);
     }

package/src/server/global-install.mjs

@@ -54,6 +54,16 @@ export function readGlobalRoot(out) {
  * is not obvious: a global prefix owned by root needs either sudo or a prefix
  * of the user's own, and "permission denied" alone sends people to sudo when
  * the second is the better answer.
+ *
+ * EEXIST is the other, and it is the one this deck's own history produced. The
+ * retired `agents-deck` and `agent-dag` packages shipped all three commands in
+ * their `bin` map, so a machine that installed either of them owns
+ * `<prefix>/bin/ccdeck` under that package's name. `npm i -g ccdeck` then has a
+ * command file to link and something already sitting on it, and npm refuses
+ * rather than taking a file another package still claims. The raw first stderr
+ * line says `EEXIST` and names a path, which tells a user nothing about the
+ * package that has to come off first — and it is exactly the users of #975,
+ * reaching for the one command that would have got them out of it.
  */
 export function installFailure(out, { pkg = "ccdeck" } = {}) {
   const said = `${out?.stderr ?? ""}\n${out?.stdout ?? ""}`;
@@ -62,6 +72,9 @@ export function installFailure(out, { pkg = "ccdeck" } = {}) {
   if (/EACCES|permission denied/i.test(said)) {
     return `npm cannot write to the global prefix. Either \`sudo npm i -g ${pkg}\`, or point npm at a prefix you own (\`npm config set prefix ~/.npm-global\`) and add its \`bin\` to PATH`;
   }
+  if (/EEXIST/i.test(said)) {
+    return `npm will not overwrite a command another global package owns. This deck's retired names ship the same commands, so remove them first: \`npm rm -g agents-deck agent-dag\`, then \`npm i -g ${pkg}\``;
+  }
   const first = said.split(/\r?\n/).map(s => s.trim()).filter(Boolean)[0];
   return first || `npm exited ${out?.status ?? "non-zero"}`;
 }