agent-dag 1.43.0 → 1.44.1

package/src/server/self-update.mjs

@@ -26,7 +26,7 @@ import { accessSync, constants as FS, existsSync, mkdirSync, readdirSync, readFi
 import { spawn } from "node:child_process";
 import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { killTree } from "./exec.mjs";
+import { killTree, shimPath, spawnSpec } from "./exec.mjs";
 
 // Once an hour, not once a day.
 //
@@ -67,6 +67,68 @@ const LEGACY_MARKER = join(MARKER_DIR, ".self-update-check");
 // names are two different questions and must not be answered with one answer.
 const _inflight = new Map();
 
+// ── what a forced check may cost ─────────────────────────────────────────────
+//
+// `_inflight` deduplicates callers that OVERLAP and nothing else. `checkDue`
+// answers `true` on `force` before it asks anything else, so a caller that
+// waited for one check to settle and then asked again got a fresh
+// `https://registry.npmjs.org/…/dist-tags` every time. Reads on this server are
+// deliberately open — `isTrustedRead` does not apply the `Sec-Fetch-Site` test
+// that `isTrustedMutation` does, because a cross-site read of
+// `http://127.0.0.1:4317` is an ordinary top-level navigation — so
+//
+//     (async function spin() {
+//       for (;;) await fetch("http://127.0.0.1:4317/api/version?refresh=1",
+//                            { mode: "no-cors" });
+//     })();
+//
+// from any page the user had open was one registry request per turn, as fast as
+// the round trip allows, and every so often two of them: `runCheck` confirms a
+// tag it has not seen before against the version document. The requests are
+// small — the whole reason the dist-tags endpoint is used here rather than the
+// packument — but they leave the user's address, carrying the user-agent this
+// deck sets, and they are aimed at a third party rather than at the machine the
+// loop is running on. That makes it #580's shape with the cost pointed
+// outwards, which if anything is the worse direction.
+//
+// Nothing above this line was going to stop it. The hour is written to a marker
+// FILE, and `force` walks past it; `first` walks past it too; and on a machine
+// where `~/.agents-deck` cannot be written `writeMarker` swallows the failure,
+// so `checkDue` sees "never checked" on every single call and the hour is not
+// really there at all.
+//
+// So the floor sits under all of it, in this process's own memory, between the
+// last rule that admitted a check and the request it admitted. It is quota.mjs's
+// number and codex-quota.mjs's and codex-usage.mjs's — the five routes in this
+// deck's router that accept `?refresh=1` and can pay for it have no business
+// disagreeing about what it costs.
+const FORCE_POLL_MS = 60_000;
+
+// Stamped when a check STARTS rather than when npm answers, because what the
+// floor rations is the request. Per package name, like `_inflight` and like the
+// markers: two names are two different questions, and one of them being asked
+// is not a reason to refuse the other. Deliberately in memory rather than on
+// disk — the marker is shared by every deck running that package and this is
+// about what THIS process is sending.
+const _lastAskAt = new Map();
+
+/**
+ * Whether we may spend a registry request right now.
+ *
+ * Exported for tests, for the same reason quota.mjs exports `maySelfPoll`,
+ * codex-quota.mjs `mayFetchQuota` and codex-usage.mjs `mayScanUsage`: this is
+ * the rule, it is pure, and it is worth pinning down away from the request it
+ * guards.
+ */
+export function mayAskNpm({ now, lastAskAt }) {
+  // A stamp from the future is a clock that moved, not a check that just ran —
+  // the same case `checkDue` answers twice below with `> now`, and the same
+  // answer. Without it, a machine whose clock corrects backwards by an hour
+  // would go an hour without a version check.
+  if (lastAskAt > now) return true;
+  return now - lastAskAt >= FORCE_POLL_MS;
+}
+
 // ── version comparison ───────────────────────────────────────────────────────
 
 /** True when `a` sorts before `b`. Numeric-segment compare — non-numeric
@@ -113,9 +175,24 @@ function readManifest(dir) {
 
 /** Version currently written in the package's own package.json. Deliberately
  *  read fresh on every call: that is the whole point — it changes under a
- *  running process when npm replaces the install. */
+ *  running process when npm replaces the install.
+ *
+ *  And sometimes the directory changes with it. A `npm i -g ccdeck` performed
+ *  before #340 left the deck nested inside a launcher package; upgrading such an
+ *  install now writes the flat tarball over that launcher, and npm's reify takes
+ *  the nested copy — the one this process is running out of — with it. Reading
+ *  our own manifest then answers null, which pickNotice reads as "nothing is
+ *  installed" and turns into the same upgrade offered forever, with the restart
+ *  notice this module exists for never firing at all.
+ *
+ *  The version is not lost, it moved one directory up. successorRoot is where
+ *  to, and it answers null in every layout where nothing moved — so the normal
+ *  case still reads exactly one manifest. */
 export function installedVersion(pkgRoot) {
-  const v = readManifest(pkgRoot)?.version;
+  const own = readManifest(pkgRoot);
+  if (typeof own?.version === "string") return own.version;
+  const moved = successorRoot(pkgRoot);
+  const v = moved ? readManifest(moved)?.version : null;
   return typeof v === "string" ? v : null;
 }
 
@@ -139,7 +216,16 @@ export function isNpxInstall(pkgRoot) {
  *  returning "git pull && npm run build", `upgradeName` refusing to move a
  *  checkout onto a published alias, and `startUpgrade` refusing with
  *  `git_checkout`. A test importing the predicate would restate what those three
- *  already prove, one level further from the behaviour a user can see. */
+ *  already prove, one level further from the behaviour a user can see.
+ *
+ *  `existsSync` and not a directory test, deliberately (#587). Git writes `.git`
+ *  as a directory only for an ordinary clone; a linked worktree and a submodule
+ *  each get a FILE whose whole content is one `gitdir:` line, and all three are
+ *  checkouts nobody may install over. Nothing here reads that line, which is
+ *  also what keeps the rule identical on Windows, where the path inside it
+ *  carries a drive letter and backslashes. Both shapes are covered in
+ *  worktree-git-file-587.test.ts and beside every checkout fixture in the
+ *  suite — narrowing this to `.isDirectory()` fails them. */
 function isGitCheckout(pkgRoot) {
   try { return existsSync(join(pkgRoot, ".git")); } catch { return false; }
 }
@@ -245,8 +331,9 @@ export function npxRestartSpec(pkgRoot, name = "agents-deck") {
 /** Every name this deck is published under.
  *
  *  `agents-deck` and `agent-dag` are one tarball published twice — see
- *  .github/workflows/publish.yml, which renames it between the two — and
- *  `ccdeck` is the stub that depends on it. The same three strings as
+ *  .github/workflows/publish.yml, which renames it between the two — and since
+ *  #340 `ccdeck` is a third rename of the same tarball rather than a launcher
+ *  package in front of it. The same three strings as
  *  invoked-as.mjs's COMMANDS, and deliberately not that list: this is the set
  *  of npm PACKAGES a `npm i -g` may name, that is the set of bin commands a
  *  user may type. They are equal only because the rename made them so, and a
@@ -330,6 +417,43 @@ export function hostPackage(pkgRoot, name = "agents-deck") {
   return host ? { root, name: host } : null;
 }
 
+/**
+ * The directory that holds this install's code AFTER an upgrade replaced it,
+ * or null when nothing has been replaced.
+ *
+ * One layout produces this and it is a transitional one. Before #340, `npm i -g
+ * ccdeck` installed a launcher package with the deck nested inside it:
+ *
+ *     <prefix>/lib/node_modules/ccdeck/                     the launcher
+ *     <prefix>/lib/node_modules/ccdeck/node_modules/agents-deck/   pkgRoot
+ *
+ * upgradeName reads the host's declared dependency and correctly answers
+ * `ccdeck`, so the upgrade runs `npm i -g ccdeck@latest` — which since #340
+ * installs the deck itself over the host directory and removes everything that
+ * was under it, including pkgRoot. The process keeps running (POSIX keeps an
+ * open inode alive, and the modules are already loaded) out of a directory that
+ * no longer exists.
+ *
+ * Deliberately NOT hostPackage. That function recognises a host by the
+ * dependency it declares on us, and the whole point here is that the host has
+ * just stopped declaring one — it is no longer a launcher, it is the deck. What
+ * identifies it instead is its name, confined to the three we publish, for the
+ * same reason installedName confines its answer: this decides what a version
+ * report says about the user's machine, and a directory that merely happens to
+ * sit above us is not evidence.
+ *
+ * Guarded on our own manifest being unreadable, so nothing changes for an
+ * install that is intact — including the ordinary nested layout before it is
+ * upgraded, where pkgRoot answers for itself and this is never consulted.
+ */
+export function successorRoot(pkgRoot) {
+  if (readManifest(pkgRoot)) return null;
+  const root = hostRoot(pkgRoot);
+  if (!root) return null;
+  const name = readManifest(root)?.name;
+  return typeof name === "string" && ALIAS_PACKAGES.includes(name) ? root : null;
+}
+
 /** The package an upgrade would actually install here — the only package worth
  *  asking npm about.
  *
@@ -372,7 +496,21 @@ export function upgradeName(pkgRoot, name = "agents-deck") {
   // the deck is nested one level down inside a package it is not named after,
   // and this build's own name for `npm i -g agents-deck` and `npm i -g
   // agent-dag`, where the deck IS the whole package and nothing is above it.
-  return hostPackage(pkgRoot, self)?.name ?? self;
+  //
+  // successorRoot is the third case, and it is the second half of the same
+  // question. Once that stub install HAS been upgraded, the host has stopped
+  // declaring a dependency on us — which is the only thing hostPackage
+  // recognises a host by — so this fell through to `self`, and `self` is the
+  // fallback `agents-deck` because our own manifest went with the directory.
+  // The user was then shown `npm i -g agents-deck@latest`: a different package,
+  // a second global tree, and their `ccdeck` binary left exactly where it was.
+  // That is #358 verbatim, arriving through the upgrade that was supposed to be
+  // the end of it. The successor's own manifest names it, and that name is what
+  // the next upgrade has to install.
+  const host = hostPackage(pkgRoot, self)?.name;
+  if (host) return host;
+  const moved = successorRoot(pkgRoot);
+  return moved ? installedName(moved, self) : self;
 }
 
 /** The exact line the user can paste, for the way THIS copy was installed. */
@@ -602,7 +740,8 @@ export function checkDue({ at, failedAt, pendingAt, now, first = false, force =
  *  cached answer immediately when the window has not elapsed.
  *
  *  `force` skips the window: the first call in this process, and an explicit
- *  "check now" from the UI. */
+ *  "check now" from the UI. What it does not skip is FORCE_POLL_MS — see
+ *  mayAskNpm, and the note above it for what a forced call used to cost. */
 async function latestOnNpm(name, now, force = false) {
   const m = readMarker(name);
   const key = markerFileName(name);
@@ -611,8 +750,18 @@ async function latestOnNpm(name, now, force = false) {
   if (!checkDue({ at: m?.at, failedAt: m?.failedAt, pendingAt: m?.pendingAt, now, first, force })) {
     return m?.version ?? null;
   }
+  // Offered before the floor: a check that has not answered yet is a lookup
+  // newer than the marker, which is what refresh asked for, and joining it costs
+  // nothing.
   const inflight = _inflight.get(key);
   if (inflight) return inflight;
+  // The floor, under every rule above it. A refused check is answered with the
+  // version we already hold — the same string an ordinary cached call returns,
+  // carrying the marker's own `checkedAt` rather than the moment of the read
+  // that was refused, so /api/version reports exactly what it reported a moment
+  // ago and no surface learns a new failure mode from being asked twice.
+  if (!mayAskNpm({ now, lastAskAt: _lastAskAt.get(key) ?? 0 })) return m?.version ?? null;
+  _lastAskAt.set(key, now);
   const run = runCheck(name, m, now)
     // Record the outcome, not just the moment, and record it against THIS
     // package: only an answer stamps `at`; a failure takes the short retry
@@ -663,13 +812,50 @@ export function pickNotice({ running, installed, latest }) {
 
 // ── installing ───────────────────────────────────────────────────────────────
 
-// npm is a .cmd shim on Windows, which spawn can only launch through a shell.
-// Everywhere else shell:false — with a shell, Node warns that arguments are
-// concatenated rather than escaped. Same pair the ccusage installer uses.
-const NPM = process.platform === "win32" ? "npm.cmd" : "npm";
-const NPM_SHELL = process.platform === "win32";
 const INSTALL_TIMEOUT_MS = 300_000; // a cold global install on a slow line
 
+/**
+ * What `spawn` gets for `npm install -g <target>@latest`.
+ *
+ * This was the last caller still spelling it the way #362 and #456 were written
+ * to remove: `spawn("npm.cmd", args, { shell: true })`, with a comment claiming
+ * it was "the same pair the ccusage installer uses". ccusage stopped using that
+ * pair when #456 fixed it, and this one was never revisited — it does not go
+ * through `run`/`runInteractive`/`runDetached`, so #457's sweep of their callers
+ * could not see it and exec-shim-callers.test.ts never listed it.
+ *
+ * Both halves of the old spelling were wrong on Windows and only one of them
+ * bites today.
+ *
+ * The one that bites: a `.cmd` shim locates its payload relative to `%~dp0`,
+ * the drive and path of the command token cmd.exe was handed, and a BARE
+ * `npm.cmd` carries no directory — so `%~dp0` came out as the deck's working
+ * directory and npm's shim went looking for `node_modules\npm\bin\npm-cli.js`
+ * underneath it. A user with a global install, deck started from
+ * `C:\Users\vceban`, clicks Update now and npm dies with `Cannot find module
+ * 'C:\Users\vceban\node_modules\npm\bin\npm-cli.js'` — on a machine whose npm
+ * is perfectly healthy, and where typing the same command at the same prompt
+ * works. shimPath is the answer, and `?? "npm.cmd"` keeps a layout it cannot see
+ * exactly as well off as it was.
+ *
+ * The one that does not, yet: `shell: true` makes Node join file and args with
+ * single spaces and no quoting. These arguments contain no spaces, so it has
+ * never mattered here — but it is the #362 defect sitting one argument away, and
+ * spawnSpec removes it by quoting every token into the cmd.exe line.
+ *
+ * POSIX is untouched: `npm` there is a real executable, isBatch is false, and
+ * the vector goes to spawn exactly as it always has.
+ *
+ * Exported for tests: the platform is a parameter so the Windows command line
+ * can be checked from any OS, and `deps` stands in for the Windows filesystem
+ * the shim lookup asks about. The same shape ccusage.mjs's installSpec has.
+ */
+export function upgradeSpec(target, platform = process.platform, deps) {
+  const args = ["install", "-g", `${target}@latest`, "--no-audit", "--no-fund", "--loglevel", "error"];
+  const file = platform === "win32" ? (shimPath("npm.cmd", deps) ?? "npm.cmd") : "npm";
+  return { ...spawnSpec(file, args, platform), plain: args };
+}
+
 /**
  * Why an in-app upgrade would be wrong here, or null when it is fine.
  *
@@ -725,7 +911,15 @@ export function upgradeBlock(pkgRoot) {
   // reason upgradeName is: the host is recognised by the dependency it declares
   // on us, and "us" is whatever the manifest here says — `agents-deck` under the
   // stub npm publishes today, but nothing in this rule should assume that.
-  const target = hostPackage(pkgRoot, installedName(pkgRoot))?.root ?? pkgRoot;
+  //
+  // successorRoot covers the case after such an upgrade has run: pkgRoot is
+  // gone, so hostPackage cannot recognise a host that no longer declares us,
+  // and asking accessSync about a deleted directory answers ENOENT — which this
+  // function reported as `not_writable`, telling the user their npm prefix was
+  // read-only when it was not.
+  const target = hostPackage(pkgRoot, installedName(pkgRoot))?.root
+    ?? successorRoot(pkgRoot)
+    ?? pkgRoot;
   return upgradeBlockedReason({
     git: isGitCheckout(pkgRoot),
     npx: isNpxInstall(pkgRoot),
@@ -934,13 +1128,17 @@ export function startUpgrade({ pkgRoot, name = "agents-deck" }) {
   // there wrote a tree this process never reads, so the version on disk never
   // moved and the same update was offered forever.
   const target = upgradeName(pkgRoot, name);
-  const args = ["install", "-g", `${target}@latest`, "--no-audit", "--no-fund", "--loglevel", "error"];
-  const command = `npm ${args.join(" ")}`;
+  const spec = upgradeSpec(target);
+  // The LOGICAL vector, not the cmd.exe line: this string is shown to the user
+  // and is the one they can paste. `cmd /d /s /c "…"` is an implementation
+  // detail of how this platform reaches npm, and pasting it would be advice
+  // about the deck rather than about their install.
+  const command = `npm ${spec.plain.join(" ")}`;
   _upgrade = { state: "running", command, error: null, at: Date.now() };
 
   let child;
   try {
-    child = spawn(NPM, args, { shell: NPM_SHELL, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+    child = spawn(spec.file, spec.args, { ...spec.opts, windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
   } catch (err) {
     _upgrade = { state: "failed", command, error: err?.message ?? String(err), at: Date.now() };
     return { ok: false, reason: "spawn_failed", command };
@@ -955,7 +1153,7 @@ export function startUpgrade({ pkgRoot, name = "agents-deck" }) {
 
   // The deadline states the outcome itself, and only then kills.
   //
-  // npm is a .cmd shim on Windows and is therefore spawned through a shell, so
+  // npm is a .cmd shim on Windows and is therefore spawned through cmd.exe, so
   // `child` is cmd.exe and npm itself is a grandchild — a plain kill would
   // report the install as timed out while it carried on writing to
   // node_modules. killTree is what reaches it (taskkill /T there, the same
@@ -1008,12 +1206,55 @@ export function startUpgrade({ pkgRoot, name = "agents-deck" }) {
   return { ok: true, command };
 }
 
-/** npm's real complaint is usually the last non-empty, non-decorative line. */
+// The furniture around a Node crash, none of which is the reason anything
+// failed. npm's own log needs none of this — it is `npm ERR!` lines and a rule —
+// but the two get mixed the moment the thing npm's shim tried to load is
+// missing, which is what #535's bare `npm.cmd` produced on every attempt.
+const CRASH_NOISE = [
+  /^\s*at\s/,                                  // stack frames
+  /^\s*\^+\s*$/,                                // the caret under the throw
+  /^node:internal\//,                           // the frame node leads with
+  /^\s*throw\s/,
+  /^Node\.js v/,                                // the last line, and the one that was quoted
+  /^\s*[{}]\s*$/,                               // the error object's braces
+  /^\s*(code|errno|syscall|path|requireStack|stack):/,
+  /^Require stack:/,
+  /^-+$/,
+  /^A complete log/,
+];
+
+/** npm's real complaint, for the banner: the last line that is not furniture.
+ *
+ *  Last rather than first, and that is the whole reason this is not npx.mjs's
+ *  summariser under another name. The two read different documents. npm's log
+ *  opens with its codes — `code EACCES`, `syscall mkdir` — and ends with the
+ *  sentence a person can act on, so the last line wins. An npx failure is a Node
+ *  crash dump, which opens with the sentence and ends with a stack, a brace and
+ *  a version banner, so the first signal line wins there. Sharing one function
+ *  would mean picking one of those and being wrong about the other half the
+ *  time; sharing the NOISE list would be the copy this comment exists instead
+ *  of.
+ *
+ *  What was wrong was not the rule but its list. `lastMeaningfulLine` dropped
+ *  `npm ERR!` prefixes, rules and "A complete log", and nothing else — so when
+ *  #535's spawn failed with a MODULE_NOT_FOUND dump, the last surviving line was
+ *  `Node.js v22.11.0`, and that string was the entire explanation the UI gave
+ *  for a failed upgrade. */
 export function lastMeaningfulLine(text) {
   const lines = String(text ?? "").split(/\r?\n/)
     .map(l => l.replace(/^npm (ERR!|WARN)\s*/, "").trim())
-    .filter(l => l && !/^-+$/.test(l) && !/^A complete log/.test(l));
-  return lines.length ? lines[lines.length - 1].slice(0, 300) : "";
+    .filter(l => l && !CRASH_NOISE.some(re => re.test(l)));
+  if (!lines.length) return "";
+  // A line that names an error outranks a later line that does not, because
+  // what survives the filter after one is usually its context rather than its
+  // successor: `Require stack:` is furniture, but the paths listed under it are
+  // not shaped like furniture and would otherwise be the last thing standing.
+  // Still the LAST such line, not the first — npm's own log builds up to its
+  // sentence, and picking the first would answer `code EACCES` where the next
+  // line says which directory and why.
+  const named = lines.filter(l => /(^|\s)[A-Za-z]*Error:/.test(l));
+  const pick = named.length ? named[named.length - 1] : lines[lines.length - 1];
+  return pick.slice(0, 300);
 }
 
 /** Full answer for GET /api/version. Never throws, and answers the local half

package/src/server/sound-hook.mjs

@@ -4,7 +4,7 @@
 // command — `afplay …` on macOS, a PowerShell one-liner on Windows — ending in
 // `|| true`. Each is a silent no-op on every other machine, so a settings.json
 // synced across devices ends up with several of them stacked, none of which
-// work everywhere. This installs a single entry pointing at notify.js, which
+// work everywhere. This installs a single entry pointing at notify.mjs, which
 // picks its own player at run time.
 //
 // Only ever touches its own entry, tagged `__agent-dag-sound`. Hooks the user
@@ -21,7 +21,7 @@
 // learn a second provider, src/web/provider-copy.ts's finishSoundTitle is the
 // sentence that has to move with it, and finish-sound-scope.test.ts fails until
 // it does (#394).
-import { readFile, mkdir } from "node:fs/promises";
+import { readFile, mkdir, rm } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { homedir } from "node:os";
@@ -34,7 +34,32 @@ const PKG_ROOT      = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
 const CLAUDE_DIR    = claudeConfigDir();
 const SETTINGS_PATH = join(CLAUDE_DIR, "settings.json");
 const INSTALL_DIR   = join(CLAUDE_DIR, "agent-dag");
-const NOTIFY_PATH   = join(INSTALL_DIR, "notify.js");
+
+// `.mjs`, and the extension is the whole feature on the machines it matters on.
+//
+// This script is ESM — `import { spawn } from "node:child_process"` on its first
+// executable line — and in the package that is settled by package.json's
+// `"type": "module"` two directories up. Installed, it lands in <claude config
+// dir>/agent-dag/, where there is normally no package.json between it and the
+// filesystem root, so the extension alone decides the format and a `.js` with
+// nothing above it is CommonJS. Node's module-syntax detection rescued that, but
+// only where detection is on by default: v20.19.0 and v22.7.0 and later. The
+// package's own `engines` says `>=18`, and on 18.x, 19.x, 20.0–20.18.x, 21.x and
+// 22.0–22.6.x the Stop hook was a `SyntaxError: Cannot use import statement
+// outside a module` printed at the end of every turn instead of a sound.
+//
+// `.mjs` is ESM on every Node that has ever had ESM, with nothing above it
+// consulted and no detection involved. A package.json beside the script would
+// have been the other spelling of the fix and is the wrong one here: hook.js
+// lives in this same directory, is deliberately CommonJS because that is what
+// this directory's layout means, and a `{"type":"module"}` next to it would
+// break the event forwarder to fix the sound.
+const NOTIFY_NAME     = "notify.mjs";
+const PACKAGED_NOTIFY = join(PKG_ROOT, "hook", NOTIFY_NAME);
+const NOTIFY_PATH     = join(INSTALL_DIR, NOTIFY_NAME);
+// What the same script was called before it declared its own format. Swept once
+// the entry that named it has been rewritten — see sweepLegacySoundScript.
+const LEGACY_NOTIFY_PATH = join(INSTALL_DIR, "notify.js");
 
 const MARK = "__agent-dag-sound";
 const EVENT = "Stop";
@@ -287,7 +312,7 @@ export async function restoreParkedSoundHooks() {
  * Take the toggle off the machine entirely, for `agents-deck --uninstall`.
  *
  * uninstallHooks only knows the `__agent-dag` mark the event forwarders carry;
- * this entry is marked `__agent-dag-sound` and its command points at notify.js,
+ * this entry is marked `__agent-dag-sound` and its command points at notify.mjs,
  * so it used to survive an uninstall and keep playing a sound on every turn. The
  * user's own hooks were the worse half: parked here when the toggle went on,
  * they stayed in a file under ~/.agents-deck that nothing left on the machine
@@ -320,6 +345,116 @@ export async function uninstallSoundHook() {
   return { ok: true, removed, restored: restore.restored ?? 0 };
 }
 
+/**
+ * Our Stop entry, built fresh from this machine's node and this machine's paths.
+ *
+ * One function rather than an object literal in each writer, because the entry
+ * has to be IDENTICAL wherever it comes from: reassertSoundHook decides whether
+ * to rewrite by comparing what is in settings.json against what this returns, so
+ * a second copy of the shape that drifted by a field would make every boot look
+ * like a change and rewrite the user's settings.json forever.
+ */
+function soundHookEntry() {
+  return {
+    [MARK]: true,
+    hooks: [{
+      type: "command",
+      // Absolute node path, matching how the event hooks are installed: the
+      // shell a hook runs in does not necessarily have the user's PATH. And
+      // properly escaped for that shell, for the reason installer.mjs's
+      // hookCommand spells out — NOTIFY_PATH is built from $CLAUDE_CONFIG_DIR,
+      // double quotes do not suppress `$(…)` or a backtick on POSIX, and this
+      // string is executed at the end of every turn.
+      command: soundHookCommand(NOTIFY_PATH),
+      timeout: 5,
+    }],
+  };
+}
+
+/**
+ * Bring the installed sound hook back up to the packaged one, in a settings
+ * object the caller is about to write.
+ *
+ * The forwarder gets this for free: installHooks re-asserts hook.js on every
+ * boot, so a machine that upgrades the deck upgrades the script Claude Code
+ * actually executes. notify.js had exactly one installer — setSoundHook(true) —
+ * so the copy on disk was whatever shipped in the release the user last TOGGLED
+ * THE SOUND ON WITH, and every later release stopped at the package directory.
+ * That is not a theoretical drift: #548 replaced a `printf "\a"` player that
+ * spawned a BEL into `stdio: "ignore"` — silent by construction — and could not
+ * reach a single machine that already had the toggle on, which is precisely the
+ * set of machines it was written for.
+ *
+ * The presence of our entry in settings.json is the whole of the permission
+ * check, and it is deliberately the only one. A user who turned the sound OFF
+ * has no entry, so nothing here writes a script into their config dir on a boot
+ * they asked nothing of; a user who has it ON has already consented to this file
+ * existing, and keeping it current is the deck's job rather than theirs.
+ *
+ * The entry is rebuilt rather than inspected, which is the other half of the
+ * report. settings.json is commonly synced between machines and the command
+ * bakes in `process.execPath` and this machine's $CLAUDE_CONFIG_DIR — so a file
+ * carried over from a laptop names that laptop's node binary inside that
+ * laptop's home directory, soundHookStatus reports `enabled: true`, and the turn
+ * ends in an ENOENT nobody sees. Rewriting it from soundHookEntry() re-derives
+ * both against the machine the deck is running on.
+ *
+ * Mutates `settings` and returns what it did; the caller owns the write, so a
+ * boot that would otherwise change nothing still changes nothing.
+ */
+export async function reassertSoundHook(settings) {
+  const group = settings?.hooks?.[EVENT];
+  if (!Array.isArray(group) || !group.some(isOurs)) return { present: false, script: false, entry: false };
+
+  if (!existsSync(INSTALL_DIR)) await mkdir(INSTALL_DIR, { recursive: true });
+  // Same reason the event forwarder is installed this way: the Stop hook fires
+  // this file from sessions that are already running, so replacing it must not
+  // leave one of them executing a half-copied program. installScript renames a
+  // finished copy over the name, and skips the write entirely when the bytes
+  // already match — which is every boot after the first.
+  const script = await installScript(PACKAGED_NOTIFY, NOTIFY_PATH);
+
+  const rebuilt = soundHookEntry();
+  const wanted = JSON.stringify(rebuilt);
+  const next = [];
+  let entry = false;
+  let kept = false;
+  for (const g of group) {
+    if (!isOurs(g)) { next.push(g); continue; }
+    // More than one of ours is a settings.json that has been merged by hand or
+    // by a sync tool. One sound per turn, so the extras are dropped rather than
+    // rewritten alongside the first.
+    if (kept) { entry = true; continue; }
+    kept = true;
+    if (JSON.stringify(g) !== wanted) entry = true;
+    next.push(rebuilt);
+  }
+  settings.hooks[EVENT] = next;
+  return { present: true, script, entry };
+}
+
+/**
+ * Delete the `notify.js` an older deck installed, now that nothing names it.
+ *
+ * Called AFTER settings.json has been written, and that ordering is the point:
+ * until the new entry is on disk the old command is still what a live Claude
+ * Code session will run at the end of its next turn, and deleting the file it
+ * names would turn a stale sound into a "Cannot find module" in the user's
+ * session. Best-effort on the way out — a Windows lock or a read-only config dir
+ * leaves one stale file behind, which is litter, not a failure worth reporting
+ * over a hook that is now installed correctly.
+ */
+export async function sweepLegacySoundScript() {
+  if (LEGACY_NOTIFY_PATH === NOTIFY_PATH) return false;
+  try {
+    if (!existsSync(LEGACY_NOTIFY_PATH)) return false;
+    await rm(LEGACY_NOTIFY_PATH, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 export async function setSoundHook(enabled) {
   // Read before anything else. A file we cannot parse stops the toggle here,
   // with nothing parked, nothing copied and settings.json untouched.
@@ -356,24 +491,10 @@ export async function setSoundHook(enabled) {
   if (enabled) {
     if (!existsSync(INSTALL_DIR)) await mkdir(INSTALL_DIR, { recursive: true });
     // Same reason the event forwarder is installed this way: the Stop hook fires
-    // notify.js from sessions that are already running, and toggling the sound
+    // notify.mjs from sessions that are already running, and toggling the sound
     // on must not leave one of them executing a half-copied file.
-    await installScript(join(PKG_ROOT, "hook", "notify.js"), NOTIFY_PATH);
-    others.push({
-      [MARK]: true,
-      hooks: [{
-        type: "command",
-        // Absolute node path, matching how the event hooks are installed: the
-        // shell a hook runs in does not necessarily have the user's PATH. And
-        // properly escaped for that shell, for the reason installer.mjs's
-        // hookCommand spells out — NOTIFY_PATH is built from
-        // $CLAUDE_CONFIG_DIR, double quotes do not suppress `$(…)` or a
-        // backtick on POSIX, and this string is executed at the end of every
-        // turn.
-        command: soundHookCommand(NOTIFY_PATH),
-        timeout: 5,
-      }],
-    });
+    await installScript(PACKAGED_NOTIFY, NOTIFY_PATH);
+    others.push(soundHookEntry());
     settings.hooks[EVENT] = others;
   } else if (others.length) {
     settings.hooks[EVENT] = others;
@@ -382,9 +503,16 @@ export async function setSoundHook(enabled) {
   }
 
   await writeSettings(settings);
+  // Last, and after the write, for the reason sweepLegacySoundScript gives: the
+  // file an older deck installed is only safe to delete once nothing in
+  // settings.json still points at it.
+  if (enabled) await sweepLegacySoundScript();
   return { ok: true, enabled };
 }
 
-// Both paths are exported so a test can prove it is pointed at a sandbox
-// before it writes anything — the real ones are the user's own settings.
-export { SETTINGS_PATH, PARKED_PATH };
+// All four paths are exported so a test can prove it is pointed at a sandbox
+// before it writes anything — the real ones are the user's own settings. The two
+// script paths are also the only honest way for a test to ask where the sound
+// hook ACTUALLY lands: rebuilding `<config dir>/agent-dag/notify.mjs` in the test
+// would keep passing on the day this module started installing somewhere else.
+export { SETTINGS_PATH, PARKED_PATH, NOTIFY_PATH, LEGACY_NOTIFY_PATH };

package/src/server/supervisor.mjs

@@ -97,6 +97,42 @@ export function signalExitAction(signal, platform = process.platform, numbers =
  *
  * `proc` is a parameter so the whole sequence can be driven in a test child.
  */
+/**
+ * What to say when the upgrade that just succeeded took this install with it,
+ * or null when that is not what happened.
+ *
+ * `npm i -g ccdeck` performed before #340 nests the deck inside a launcher
+ * package. Upgrading such an install now writes the deck itself over that
+ * launcher, and npm's reify removes everything that was underneath — including
+ * the directory this supervisor and its worker are running from. The process
+ * survives, because everything it needs is already loaded. The next spawn does
+ * not: bin/deck.js is a path, and npm has just deleted it.
+ *
+ * That reached the user as `could not start …/bin/deck.js: ENOENT` and an exit
+ * 1 — a dead deck and an errno, one click after an upgrade that reported
+ * success. Nothing was broken. The new version is on the machine, and the
+ * command they typed already points at it, because npm rewrote the bin shim in
+ * the same install. The only thing missing was a sentence saying so.
+ *
+ * Deliberately not a hand-off. This process could spawn the successor's worker
+ * instead, and that would be a new worker under an old supervisor — a pair
+ * nothing has ever tested together, decided at the worst possible moment. One
+ * command the user runs themselves is the smaller promise and the one that
+ * cannot go wrong.
+ *
+ * Pure, and given its two filesystem answers rather than asking for them,
+ * because the state it describes only ever exists in a process whose own files
+ * were deleted after it started — which no test can produce by spawning one.
+ */
+export function replacedNote({ workerExists, moved, product = "ccdeck", command = "ccdeck" }) {
+  if (workerExists || !moved) return null;
+  return [
+    `${product}: the upgrade replaced this install, so it cannot restart in place.`,
+    `  the new version is in ${moved}`,
+    `  run \`${command}\` again to start it`,
+  ].join("\n");
+}
+
 export function dieOfSignal(signal, proc = process) {
   const { reraise, code } = signalExitAction(signal, proc.platform);
   if (reraise) {