agent-dag 1.44.1 → 1.45.0

package/src/server/installer.mjs

@@ -5,7 +5,7 @@
 // sessions reach the same server through the rollout watcher instead, so one
 // running server still sees both CLIs. Re-runs are safe; entries are tagged
 // with __agent-dag and de-duped.
-import { readFile, mkdir, unlink, rename, open, stat, chmod } from "node:fs/promises";
+import { readFile, mkdir, unlink, rename, open, stat, chmod, realpath, readlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
 import { join, resolve, dirname } from "node:path";
 import { setTimeout as delay } from "node:timers/promises";
@@ -265,6 +265,66 @@ async function createTemp(target, { mode = 0o666, attempts = 5 } = {}) {
   }
 }
 
+// A chain longer than this is a loop, or something no real setup has: stow and
+// chezmoi produce one hop, an encrypted volume two. The number is a bound on the
+// walk below, not a promise about how deep a legitimate link goes.
+const MAX_LINK_HOPS = 8;
+
+/**
+ * The file a name is really asking for — the one the links under it end at.
+ *
+ * A rename replaces the DIRECTORY ENTRY it is handed. Handed a symlink, it
+ * deletes the link and leaves an ordinary file where it was, and
+ * `~/.claude/settings.json` is a symlink on a great many machines: into a
+ * dotfiles repo, a stow or chezmoi target, an encrypted volume. The content
+ * survives — we write back what we read — so nothing looks wrong and nothing
+ * says anything. The repo copy keeps what it said before, never goes dirty, and
+ * from then on the user's edits there reach nobody while every launch rewrites
+ * the detached file and widens the gap. This is a file the deck did not create
+ * and does not own; quietly cutting it loose from the thing that manages it is
+ * worse than failing to write it at all.
+ *
+ * persistAuth in codex-auth.mjs has resolved for exactly this reason since it
+ * was written, on the file that is LESS often linked. This is the same rule at
+ * the helper every settings writer in the deck goes through — and the same
+ * function, so there is one of it rather than two that can drift.
+ *
+ * Resolving also decides which filesystem the temp file is staged on, and it has
+ * to be the target's. A rename is atomic within one filesystem and fails with
+ * EXDEV across two, so staging beside the LINK — a link into a dotfiles repo on
+ * a separate volume — is a write that cannot land at all.
+ *
+ * A DANGLING link is the case realpath alone cannot answer: the target not
+ * created yet, the encrypted volume not mounted. Answering it with the raw path
+ * is the bug again, because that is precisely when the link gets replaced — so
+ * the walk falls back to readlink, which reads a link without needing its target
+ * to exist, and follows it the way opening the name for writing would.
+ * `printf x > link` creates the target; it does not replace the link. If the
+ * target's directory is gone the write then fails, which is the honest answer:
+ * the bytes did not reach the file the user's setup points at.
+ *
+ * The ordinary case — a plain file, no link anywhere — is one realpath and the
+ * first return.
+ */
+async function resolveWriteTarget(raw) {
+  let at = raw;
+  for (let hop = 0; hop < MAX_LINK_HOPS; hop++) {
+    // Resolves every link on the path at once, when all of them lead somewhere.
+    const real = await realpath(at).catch(() => null);
+    if (real !== null) return real;
+    const to = await readlink(at).catch(() => null);
+    // Not a link, so nothing exists at this name yet and this name is the
+    // answer: a first install, or the far end of a chain we have just followed.
+    if (to === null) return at;
+    at = resolve(dirname(at), to);
+  }
+  // Only a cycle gets here. Say so rather than pick a link out of it and
+  // destroy that one — the OS answers a write through such a name the same way.
+  const err = new Error(`too many symbolic links resolving ${raw}`);
+  err.code = "ELOOP";
+  throw err;
+}
+
 /**
  * Replace a file in a single step readers cannot land inside.
  *
@@ -273,8 +333,13 @@ async function createTemp(target, { mode = 0o666, attempts = 5 } = {}) {
  * different ones. It is fsync'd before the rename so that a crash or power loss
  * just after a successful install cannot leave the new directory entry pointing
  * at blocks that were never flushed — the classic file-of-zero-bytes.
+ *
+ * "Beside the target" means beside the file the name resolves to, not beside the
+ * name: see resolveWriteTarget, which is what keeps a symlinked settings.json a
+ * symlink.
  */
-async function writeFileAtomic(target, text) {
+async function writeFileAtomic(rawTarget, text) {
+  const target = await resolveWriteTarget(rawTarget);
   const { tmp, handle } = await createTemp(target);
   try {
     try {
@@ -366,27 +431,47 @@ export async function installHooks({ provider = "claude" } = {}) {
     current.hooks[evt] = cleaned;
   }
 
-  // The finish sound is the deck's second installed script, and until this line
-  // it was the only one nothing ever re-installed. dedupeOurEntries does not
-  // touch it — isOurEntry knows `__agent-dag` and the entry is marked
-  // `__agent-dag-sound` — so the loop above carried a stale entry straight
-  // through, and nothing anywhere looked at the file that entry names. See
-  // reassertSoundHook: it re-asserts the script only where our Stop entry is
-  // already present, so a user who turned the sound off does not get it back,
-  // and it mutates `current` rather than writing, so the comparison below is
-  // still what decides whether settings.json is touched at all.
+  // Retiring the finish-sound hook rides in here, on this read and this write,
+  // and this is the seam it needs rather than a convenient one. #704 moved the
+  // sound into the browser and deleted the script the old `Stop` entry ran, so
+  // an install that upgrades a machine which HAS that entry leaves a hook
+  // pointing at a file that is no longer in the package — an error at the end of
+  // every turn, on a machine that was working before the upgrade. It therefore
+  // has to happen without the user asking for it, and a normal boot is the only
+  // moment that qualifies.
   //
-  // Imported here rather than at the top of the file because sound-hook.mjs
-  // imports this module — installScript, writeFileAtomic and readSettingsForWrite
-  // all live here — and a static import would close that into a cycle. Claude
-  // only: the sound entry is one line in Claude Code's settings.json and there
-  // is no Codex equivalent.
-  let sound = { present: false };
-  let sweepLegacySoundScript = null;
+  // Riding along buys the two properties it would otherwise have to invent.
+  // There is ONE write of settings.json on the boot that retires, compared
+  // against the exact bytes read a few lines up — so a second deck doing the
+  // same work at the same time writes the same payload, and every later boot
+  // finds nothing to do and changes nothing. And the mutate-then-let-the-caller-
+  // write split is what keeps the script deletion after the write: until the new
+  // file has landed, a live Claude Code session's next turn still runs the old
+  // command.
+  //
+  // Imported here rather than at the top of the file because retire-sound-hook.mjs
+  // imports this module — writeFileAtomic and readSettingsForWrite live here —
+  // and a static import would close that into a cycle. Claude only: the entry
+  // was one line in Claude Code's settings.json and there was never a Codex one.
+  //
+  // The equality test is not ceremony. Retirement DELETES two files — the parked
+  // hooks and the installed script — at absolute paths it resolved for itself,
+  // from claudeConfigDir() and os.homedir(), at its own import. This function
+  // writes `cfg.settingsPath`. In the product those are the same settings.json
+  // and the paths belong together. When they are not the same file, the two
+  // modules are looking at different homes, and acting on that difference means
+  // deleting files belonging to a machine this install is not writing to. That
+  // is not hypothetical: it happened to the author's own ~/.agents-deck while
+  // this very change was being written, from a test whose environment teardown
+  // ran a describe too early. Disagreement is a reason to do nothing.
+  let retire = { pending: false, changed: false, removed: 0, restored: 0 };
+  let completeSoundHookRetirement = null;
   if (provider === "claude") {
-    const soundHook = await import("./sound-hook.mjs");
-    sweepLegacySoundScript = soundHook.sweepLegacySoundScript;
-    sound = await soundHook.reassertSoundHook(current);
+    const retirement = await import("./retire-sound-hook.mjs");
+    if (retirement.SETTINGS_PATH === cfg.settingsPath) {
+      completeSoundHookRetirement = retirement.completeSoundHookRetirement;
+      retire = await retirement.retireSoundHookIn(current);
+    }
   }
 
   // Every launch reinstalls, and on all but the first the entries are already
@@ -397,11 +482,11 @@ export async function installHooks({ provider = "claude" } = {}) {
   const next = JSON.stringify(current, null, 2) + "\n";
   const changed = next !== before;
   if (changed) await writeFileAtomic(cfg.settingsPath, next);
-  // After the write, never before it: the `notify.js` an older deck installed is
-  // what a live session's cached command still names until the new entry is on
-  // disk, and deleting it early turns a stale sound into a missing module.
-  if (sound.present) await sweepLegacySoundScript();
-  return { settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider, changed, sound };
+  // After the write, never before it: the notify script an older deck installed
+  // is what a live session's cached command still names until the new entry is
+  // on disk, and deleting it early turns a stale sound into a missing module.
+  if (retire.pending) await completeSoundHookRetirement(retire, current);
+  return { settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider, changed, retire };
 }
 
 /**
@@ -420,8 +505,8 @@ export async function installHooks({ provider = "claude" } = {}) {
  * it. `--uninstall` printed "no Claude hooks to remove" and exited 0 while all
  * ten `__agent-dag` entries sat in the file, spawning node on every tool call
  * of every session, for a deck the user had been told was gone. The other half
- * of the same command already knew better: uninstallSoundHook reads through
- * readSettingsForWrite and says so out loud, so one command gave two opposite
+ * of the same command already knew better: the sound-hook half read through
+ * readSettingsForWrite and said so out loud, so one command gave two opposite
  * verdicts about one file and the load-bearing one was the one that lied.
  *
  * So the read is the same read the install does, and for the same reason. A
@@ -440,7 +525,7 @@ export async function uninstallHooks({ provider = "claude" } = {}) {
     ({ settings: current } = await readSettingsForWrite(cfg.settingsPath));
   } catch (err) {
     if (err?.code !== "SETTINGS_UNREADABLE") throw err;
-    // Same shape uninstallSoundHook answers with, so bin/deck.js reports both
+    // Same shape retireSoundHook answers with, so bin/deck.js reports both
     // halves of `--uninstall` the same way instead of one of them inventing a
     // second vocabulary for the identical condition on the identical file.
     return {
@@ -671,4 +756,8 @@ export { AGENT_DAG_DIR, CLAUDE_DIR, CODEX_DIR };
 // the same reason one step lower: codex-auth.mjs needs the collision-free temp
 // name but not writeFileAtomic's mode handling, which carries over the target's
 // mode and so would leave a brand-new auth.json at whatever the umask allows.
-export { readSettingsForWrite, writeFileAtomic, installScript, renameWithRetry, createTemp };
+// resolveWriteTarget goes with them, because auth.json is linked into a dotfiles
+// repo for the same reasons settings.json is, and "never rename onto a link" is
+// one rule: codex-auth.mjs called a realpath of its own before this existed, and
+// two spellings of a rule are two things that can drift.
+export { readSettingsForWrite, writeFileAtomic, installScript, renameWithRetry, createTemp, resolveWriteTarget };

package/src/server/retire-sound-hook.mjs

@@ -0,0 +1,315 @@
+// Takes the deck's old finish-sound hook back off a machine that already has it.
+//
+// Until #704 the deck played its "turn finished" sound by writing a `Stop` entry
+// into the user's settings.json whose command ran `notify.mjs` out of the deck's
+// own install directory. The deck plays that sound itself now, from the `Stop`
+// and `Notification` envelopes it already receives, and the script is gone from
+// the package — so an entry naming it is a hook pointing at a file that does not
+// exist, and Claude Code runs it at the end of every turn. On a machine that was
+// working yesterday. That is what this module exists to prevent, and it is the
+// whole of what is left here: there is no installer, no toggle, no status
+// reporter and no re-assert. Only the removal, and the promise the removal owes.
+//
+// THE PROMISE. Turning the sound on used to PARK any sound hook the user had
+// written themselves — an `afplay` line, a PowerShell one — in
+// ~/.agents-deck/parked-sound-hooks.json, so that "off" produced actual silence
+// and "on" did not play twice. Those hooks are the user's, the deck is the only
+// thing that knows where they went, and this is the last code that will ever be
+// in a position to hand them back. So retirement is not "delete our entry": it
+// is "delete our entry and put theirs back where they wrote it".
+//
+// WHAT COUNTS AS OURS. Two rules, and they cover different machines.
+//
+//   The `__agent-dag-sound` mark is what this deck wrote, and it survives a
+//   settings.json synced from another computer — where every path in the command
+//   belongs to that computer and matches nothing here.
+//
+//   An entry whose command names one of our installed scripts is ours too, mark
+//   or no mark. <claude config dir>/agent-dag/ is a directory this deck creates
+//   and fills; nobody hand-writes a Stop hook that runs `node
+//   ~/.claude/agent-dag/notify.mjs`. The author's own machine is the case: two
+//   Stop entries naming the installed notify.js with the mark missing from both,
+//   which the mark rule alone would have left behind — playing a sound with no
+//   switch anywhere that could stop it, or crashing once the script was swept.
+//
+// Everything else in the file is the user's and is not touched. `afplay …` stays
+// exactly where they put it, and this module has no idea what it does.
+//
+// EXACTLY ONCE, without a stamp. Retirement is triggered by the state it
+// removes: our entry in settings.json, a parked file, or one of our scripts on
+// disk. When it has run there is none of that left, so the next boot asks three
+// `existsSync` questions, gets three noes, and writes nothing — the same answer
+// every boot after it, forever. A "retirement done" marker file would have been
+// the other spelling and is the wrong one: a marker can say done about a machine
+// whose settings.json was later restored from a backup carrying the old entry,
+// and then the broken hook lives there permanently. State that describes itself
+// cannot drift from itself.
+//
+// A DECK THAT CANNOT WRITE. Nothing here is done speculatively and nothing is
+// recorded as done that was not. A settings.json that will not parse stops
+// retirement with the file byte for byte as it was found (see
+// readSettingsForWrite: this rewrites the whole file, so treating a damaged one
+// as `{}` would replace every permission, env var and hook in it with nothing).
+// An unwritable one throws out of the write and the boot reports it. A parked
+// file that will not read leaves the park alone and still removes our entry,
+// because those are two independent repairs and only one of them is urgent.
+// In every one of those cases the trigger state is still on disk, so the next
+// boot tries again. There is nothing to reset.
+//
+// TWO DECKS BOOTING AT ONCE. Both read the same settings, both compute the same
+// result, and both write it through writeFileAtomic — a rename, so the file is
+// one whole payload whichever lands second. The park is the part that could
+// have gone wrong: deck B reading the park before A deleted it and settings
+// after A wrote it would put the user's hooks back a second time, on top of the
+// copy A had just restored. So a parked entry is spliced back only when an
+// identical one is not already in the group. Restoring is idempotent, and the
+// race stops being one.
+import { readFile, rm } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { claudeConfigDir } from "./claude-dir.mjs";
+import { readSettingsForWrite, writeFileAtomic } from "./installer.mjs";
+
+const CLAUDE_DIR    = claudeConfigDir();
+const SETTINGS_PATH = join(CLAUDE_DIR, "settings.json");
+const INSTALL_DIR   = join(CLAUDE_DIR, "agent-dag");
+
+// Both names the sound script ever had. `.js` is the pre-#577 spelling, which
+// was CommonJS-by-default in a directory with no package.json above it and so a
+// `SyntaxError: Cannot use import statement` at the end of every turn on the
+// older half of this package's `engines` range; `.mjs` is what replaced it.
+// Retirement has to know both, because a machine that never upgraded past #577
+// is exactly the kind of machine this runs on.
+const NOTIFY_PATH        = join(INSTALL_DIR, "notify.mjs");
+const LEGACY_NOTIFY_PATH = join(INSTALL_DIR, "notify.js");
+const OUR_SCRIPTS = [NOTIFY_PATH, LEGACY_NOTIFY_PATH];
+
+const MARK  = "__agent-dag-sound";
+const EVENT = "Stop";
+// Where the user's own sound hooks were put while the toggle was on. Nothing
+// writes this any more; retirement reads it once and deletes it.
+const PARKED_PATH = join(homedir(), ".agents-deck", "parked-sound-hooks.json");
+
+const commandsOf = (entry) =>
+  (entry?.hooks ?? []).map(h => (typeof h?.command === "string" ? h.command : ""));
+
+/** An entry this deck put there: by its mark, or by the script it runs. */
+function isOurs(entry) {
+  if (entry?.[MARK] === true) return true;
+  return commandsOf(entry).some(cmd => OUR_SCRIPTS.some(p => cmd.includes(p)));
+}
+
+/** Anywhere in the file — not just `Stop` — that still runs one of our scripts.
+ *  The sweep below asks this before deleting them: a stale sound is survivable
+ *  and a hook pointing at nothing is not. */
+function anythingStillNamesOurScripts(settings) {
+  const groups = settings?.hooks;
+  if (!groups || typeof groups !== "object") return false;
+  for (const group of Object.values(groups)) {
+    if (!Array.isArray(group)) continue;
+    for (const entry of group) {
+      if (commandsOf(entry).some(cmd => OUR_SCRIPTS.some(p => cmd.includes(p)))) return true;
+    }
+  }
+  return false;
+}
+
+function parkedError(why) {
+  const err = new Error(
+    `${PARKED_PATH} could not be read as JSON (${why}). It holds sound hooks you wrote yourself, so it ` +
+    `is not being treated as empty and it has not been deleted — repair it or move it aside, and the ` +
+    `deck will hand them back on its next start.`,
+  );
+  err.code = "PARKED_UNREADABLE";
+  err.parkedPath = PARKED_PATH;
+  return err;
+}
+
+/**
+ * The hooks the toggle set aside, or a refusal.
+ *
+ * Only ENOENT is genuinely empty. A truncated file — a kill mid-write, a full
+ * disk — used to read as "nothing was ever parked", and this is the only copy of
+ * hooks a user wrote by hand: answering "restored: 0" about a file with their
+ * work in it, and then deleting it, is the one unrecoverable thing in this
+ * module. A JSON object rather than an array is a file that is not ours.
+ */
+async function readParked() {
+  let raw;
+  try {
+    raw = await readFile(PARKED_PATH, "utf8");
+  } catch (err) {
+    if (err?.code === "ENOENT") return [];
+    throw parkedError(err?.message ?? String(err));
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    throw parkedError(err?.message ?? String(err));
+  }
+  if (!Array.isArray(parsed)) throw parkedError("top level is not a JSON array");
+  return parsed;
+}
+
+/** Is there anything of the retired mechanism left on this machine? Three
+ *  `existsSync` calls and a scan of a settings object the caller already read —
+ *  which is the whole cost of retirement on every boot after the first. */
+function anythingToRetire(settings) {
+  const group = settings?.hooks?.[EVENT];
+  if (Array.isArray(group) && group.some(isOurs)) return true;
+  if (existsSync(PARKED_PATH)) return true;
+  return OUR_SCRIPTS.some(existsSync);
+}
+
+/** Nothing here, and nothing for the caller to do afterwards. */
+const NOTHING = Object.freeze({ pending: false, changed: false, removed: 0, restored: 0, parkError: null });
+
+/**
+ * Retire the sound hook inside a settings object the caller is about to write.
+ *
+ * Mutates `settings` and returns what it did; the caller owns the write, so a
+ * boot that would otherwise change nothing still changes nothing. Call
+ * `completeSoundHookRetirement` with the result AFTER settings.json is on disk —
+ * that ordering is the point of the split. Until the new file has landed, the
+ * old command is still what a live Claude Code session will run at the end of
+ * its next turn, and deleting the script it names turns a stale sound into a
+ * "Cannot find module" in the user's session.
+ *
+ * Never throws over the parked file. A corrupt ~/.agents-deck must not stop the
+ * deck from booting, and it must not stop the urgent half either: our entry
+ * points at a script that is about to be deleted, and taking it out is worth
+ * doing whether or not the user's own hooks can be handed back in the same pass.
+ */
+export async function retireSoundHookIn(settings) {
+  if (!anythingToRetire(settings)) return NOTHING;
+
+  let parked = [];
+  let parkError = null;
+  try {
+    parked = await readParked();
+  } catch (err) {
+    if (err?.code !== "PARKED_UNREADABLE") throw err;
+    parkError = { reason: "parked_unreadable", parkedPath: PARKED_PATH, message: err.message };
+  }
+
+  const group = Array.isArray(settings?.hooks?.[EVENT]) ? settings.hooks[EVENT] : [];
+  const theirs = group.filter(g => !isOurs(g));
+  const removed = group.length - theirs.length;
+
+  // Identical entries are not restored twice — see the note on two decks at the
+  // top. `theirs` is what will be in the file, so a hook already back from an
+  // earlier attempt (or from the other deck, a millisecond ago) is recognised.
+  //
+  // And an entry that is OURS is never restored, wherever it was found. The park
+  // is not supposed to contain one — the old toggle set aside hooks that looked
+  // hand-written and skipped its own — but "supposed to" is doing all the work
+  // in that sentence: the file is years old on some machines, it is synced
+  // between them, and the unmarked entries naming our installed script are
+  // exactly the shape a hand-written-hook filter would have swept up. Restoring
+  // one would put back the hook this whole module exists to remove, pointing at
+  // a script this release deletes, on the boot that was supposed to repair it.
+  const seen = new Set(theirs.map(g => JSON.stringify(g)));
+  const putBack = [];
+  for (const entry of parked) {
+    if (isOurs(entry)) continue;
+    const key = JSON.stringify(entry);
+    if (seen.has(key)) continue;
+    seen.add(key);
+    putBack.push(entry);
+  }
+
+  const next = [...putBack, ...theirs];
+  let changed = false;
+  if (removed > 0 || putBack.length > 0) {
+    changed = true;
+    settings.hooks ??= {};
+    if (next.length) settings.hooks[EVENT] = next;
+    else delete settings.hooks[EVENT];        // don't leave an empty array behind
+  }
+
+  return {
+    pending: true,
+    changed,
+    removed,
+    restored: putBack.length,
+    // Only when the whole park was accounted for. A read that refused leaves the
+    // file for repair, and the next boot tries again.
+    clearPark: parkError === null && existsSync(PARKED_PATH),
+    parkError,
+  };
+}
+
+/**
+ * The half of retirement that must happen after settings.json is on disk.
+ *
+ * Deleting the parked file is safe here and only here: its contents are in the
+ * file Claude Code reads. If the delete fails — a read-only ~/.agents-deck, a
+ * Windows lock — the next boot reads the same park and restores nothing, because
+ * the hooks it names are already in the group. That is the whole reason the
+ * restore de-duplicates.
+ *
+ * The scripts go last, and only when nothing in settings.json still names them.
+ * Retirement removes every entry that does, so the guard is normally already
+ * satisfied; it exists for the file that puts one under some other event, where
+ * leaving a stale sound is right and leaving a missing module is not.
+ */
+export async function completeSoundHookRetirement(plan, settings) {
+  if (!plan?.pending) return { parkCleared: false, scripts: [] };
+  let parkCleared = false;
+  if (plan.clearPark) {
+    parkCleared = await rm(PARKED_PATH, { force: true }).then(() => true, () => false);
+  }
+  const scripts = [];
+  if (!anythingStillNamesOurScripts(settings)) {
+    for (const path of OUR_SCRIPTS) {
+      if (!existsSync(path)) continue;
+      if (await rm(path, { force: true }).then(() => true, () => false)) scripts.push(path);
+    }
+  }
+  return { parkCleared, scripts };
+}
+
+/**
+ * Retirement for a caller that holds no settings object: `agents-deck
+ * --uninstall`, which is taking the deck off the machine rather than upgrading
+ * it, and where there is no hook install to ride along with.
+ *
+ * Same three steps in the same order — read, mutate, write, then clean up — so
+ * there is one description of what retirement is rather than two that can drift.
+ */
+export async function retireSoundHook() {
+  let settings;
+  try {
+    ({ settings } = await readSettingsForWrite(SETTINGS_PATH));
+  } catch (err) {
+    if (err?.code !== "SETTINGS_UNREADABLE") throw err;
+    // A file we cannot parse is a file whose contents we cannot reproduce, and
+    // this rewrites the whole of it. Left exactly as found, parked hooks still
+    // parked, and the user told which file and why.
+    return {
+      ok: false,
+      reason: "settings_unreadable",
+      settingsPath: SETTINGS_PATH,
+      why: err.why ?? err.message,
+      message: err?.message ?? String(err),
+      removed: 0,
+      restored: 0,
+    };
+  }
+
+  const plan = await retireSoundHookIn(settings);
+  if (plan.changed) await writeFileAtomic(SETTINGS_PATH, JSON.stringify(settings, null, 2) + "\n");
+  await completeSoundHookRetirement(plan, settings);
+
+  if (plan.parkError) return { ok: false, ...plan.parkError, removed: plan.removed, restored: plan.restored };
+  return { ok: true, removed: plan.removed, restored: plan.restored };
+}
+
+// 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 and the user's own hooks.
+// The script paths are also the only honest way to ask where the retired script
+// ACTUALLY lived: rebuilding `<config dir>/agent-dag/notify.mjs` inside a test
+// would keep passing on the day this module started looking somewhere else.
+export { SETTINGS_PATH, PARKED_PATH, NOTIFY_PATH, LEGACY_NOTIFY_PATH };

package/src/server/supervisor.mjs

@@ -233,3 +233,70 @@ export function upgradeRefusalText({ reason, waitMs = 0, attempt = 0 } = {}, tar
   const left = waitMs >= 60_000 ? `${Math.ceil(waitMs / 60_000)}m` : `${Math.max(1, Math.ceil(waitMs / 1000))}s`;
   return `${what} failed to fetch a moment ago — waiting ${left} before trying again`;
 }
+
+/**
+ * Die when the process that started this one does — on all three operating
+ * systems (#702).
+ *
+ * The deck is two processes: bin/agent-dag.js supervises, bin/deck.js serves.
+ * The supervisor kills the worker on every path it knows about — a restart, an
+ * upgrade, a Ctrl+C, its own exit — and cannot kill it on the one path it never
+ * gets to run: being killed itself. SIGKILL cannot be handled, a crash runs no
+ * handler, and a `taskkill` without `/T` reaches only the process it names. On
+ * POSIX the worker is then re-parented to init and keeps its port, its temp
+ * directory and its 40-60 MB of RSS forever. 310 of those were alive on one
+ * development machine, the oldest a day and four hours old, every one a worker
+ * whose supervisor a test's teardown had SIGKILLed.
+ *
+ * WHY THE IPC CHANNEL, AND NOT ANY OF THE OBVIOUS ALTERNATIVES. The requirement
+ * is one signal meaning "whoever started me is gone", and the usual answers are
+ * each missing a platform:
+ *
+ *   • `process.ppid === 1` — POSIX re-parents an orphan to init, so polling ppid
+ *     works there and answers nothing on Windows, which does not re-parent at
+ *     all: the ppid goes on naming a pid that no longer exists.
+ *   • process groups and `kill(-pgid)` — a POSIX concept. Windows job objects
+ *     are the nearest equivalent and Node exposes none of it.
+ *   • a SIGTERM the parent sends on its way out — Windows delivers no signals to
+ *     a Node process, so `process.on("SIGTERM")` there never fires; and a parent
+ *     that was killed sends nothing anywhere.
+ *
+ * The channel is the one mechanism that behaves the same everywhere, because
+ * Node normalises it: a Unix socketpair on POSIX, a named pipe on Windows, both
+ * closed by the kernel when the process holding the other end stops existing,
+ * however it stopped. Node turns that close into a single `disconnect` event on
+ * the child's own `process`, and it arrives for a SIGKILL, a crash, a
+ * `taskkill /F`, a closed console window and an ordinary exit alike. That is the
+ * same reasoning the header above gives for Ctrl+C: what differs between
+ * platforms is how a process dies, not that this notices.
+ *
+ * The channel is not created for this. It already carries `{type:"listening"}`
+ * and the upgrade handshake; this only says what its closure means.
+ *
+ * ARMED ONLY WHERE THERE IS A PARENT TO DIE WITH — `process.send` is a function
+ * exactly when a channel was given. `node bin/deck.js` run by hand has none, and
+ * that is the same question `SUPERVISED` in bin/deck.js already asks before it
+ * offers /api/restart.
+ *
+ * WHAT IT DELIBERATELY DOES NOT COVER: a parent that calls `child.disconnect()`
+ * and stays alive would look identical from here. Nothing in this repo does
+ * that, and the alternative — an "are you still there" ping — is a second
+ * protocol to keep correct in exchange for a case that does not exist.
+ *
+ * Returns whether a leash was armed, so a caller can state it rather than infer
+ * it. `proc` is a parameter for the reason `workerExitAction` takes `stopping`:
+ * the behaviour has to be checkable without a second process.
+ */
+export function dieWithParent(stop, proc = process) {
+  if (!proc || typeof proc.once !== "function" || typeof proc.send !== "function") return false;
+  let done = false;
+  proc.once("disconnect", () => {
+    if (done) return;
+    done = true;
+    // A stop that throws must still end the process: the whole point is that
+    // nothing is left behind, and there is no parent left to notice a child
+    // that failed to leave.
+    try { stop(); } catch { proc.exit?.(0); }
+  });
+  return true;
+}