agent-dag 3.22.0 → 3.22.3

package/src/server/installer.mjs

@@ -1,912 +0,0 @@
-// Idempotent hook installer. One provider installs, two uninstall:
-//  - "claude"  → $CLAUDE_CONFIG_DIR/settings.json (Claude Code, ~/.claude by default)
-//  - "codex"   → $CODEX_HOME/hooks.json           (uninstall only — see PROVIDERS)
-// Hooks post to the discovery dir at <claude config dir>/agent-dag/, and Codex
-// 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, 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";
-import { fileURLToPath } from "node:url";
-import { claudeConfigDir } from "./claude-dir.mjs";
-import { CODEX_HOME } from "./codex-dir.mjs";
-import { shellQuoteArg } from "./exec.mjs";
-import { PRODUCT } from "./brand.mjs";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const PKG_ROOT = resolve(__dirname, "..", "..");
-
-// Honours CLAUDE_CONFIG_DIR, exactly as CODEX_DIR honours CODEX_HOME below.
-// Without it the hooks land in a settings.json Claude Code never opens.
-const CLAUDE_DIR = claudeConfigDir();
-// Both directories now come from the module that owns the rule rather than from
-// a copy of it here — claude-dir.mjs and codex-dir.mjs. The local name stays
-// because CODEX_DIR is what the rest of this file and its tests call it, and it
-// says what the value is FOR here: the directory hooks.json is taken out of.
-const CODEX_DIR = CODEX_HOME;
-
-// Single shared discovery dir — both providers' hook scripts post here so one
-// running agent-dag server can match either ecosystem's events. It follows the
-// Claude config dir, so hook/hook.js has to resolve that dir the same way: it
-// reads what this writes, and a disagreement means the hooks find no server.
-const AGENT_DAG_DIR = join(CLAUDE_DIR, "agent-dag");
-
-const CLAUDE_EVENTS = [
-  "SessionStart",
-  "UserPromptSubmit",
-  "PreToolUse",
-  "PostToolUse",
-  "PostToolUseFailure",
-  "SubagentStart",
-  "SubagentStop",
-  "Stop",
-  "SessionEnd",
-  "Notification",
-];
-
-const PROVIDERS = {
-  claude: {
-    settingsPath: join(CLAUDE_DIR, "settings.json"),
-    hookInstallDir: join(CLAUDE_DIR, "agent-dag"),
-    events: CLAUDE_EVENTS,
-    ensureDir: CLAUDE_DIR,
-  },
-  // Uninstall-only. Codex hooks do not fire reliably on Windows, so the deck
-  // stopped installing them and reads Codex's rollout files instead — nothing
-  // calls installHooks with this provider any more. The entry stays because a
-  // machine that ran an older deck still has our forwarders in hooks.json, and
-  // uninstallHooks needs the path to take them back out. It reads nothing else:
-  // it walks the events already in the file rather than a list of our own.
-  codex: {
-    settingsPath: join(CODEX_DIR, "hooks.json"),
-  },
-};
-
-const MARK_KEY = "__agent-dag";
-// Legacy marks from earlier names — purged on every install/uninstall so
-// duplicate forwarders don't pile up when the project gets renamed.
-const LEGACY_MARKS = ["__ccgraph", "__agent-flow"];
-const LEGACY_DIRS = ["ccgraph", "agent-flow", "agent-dag"];
-
-/**
- * The `command` string Claude Code stores for our forwarder, and runs THROUGH A
- * SHELL on every tool call.
- *
- * The settings.json hook format is a string, not an argv, so this is one of the
- * two places in the codebase that has to build a shell command line by hand —
- * see shellQuoteArg, which is where the escaping rules and their one Windows
- * residual are written down.
- *
- * It used to wrap both paths in double quotes, which on POSIX escapes nothing:
- * `$(…)`, a backtick and `\` are all still live inside them. Both paths come
- * from outside — `installedHookPath` is built from $CLAUDE_CONFIG_DIR (resolved,
- * never validated) or homedir(), and `node` is process.execPath — so a config
- * dir called `/tmp/a$(id)b` was shell code, written into the user's own settings
- * file and executed on every hook fire for as long as it stayed there. The
- * quieter half of the same bug cost nothing but the feature: an ordinary `$` in
- * a path expanded to nothing, the hook pointed at a file that was not there, and
- * hooks stopped firing with no error to explain it.
- *
- * `provider` is a key of PROVIDERS — "claude" or "codex", never anything a
- * caller chose — and is quoted anyway, because that is not a property worth
- * re-deriving at every reading.
- *
- * Exported, with the node path AND the platform injectable, so the escaping can
- * be checked against a path the test names rather than against whatever ran the
- * suite — and against the rule of a platform that suite is not running on. The
- * two rules are genuinely different (POSIX single quotes, cmd.exe doubled
- * double quotes), so without the second parameter the only assertion a test can
- * make is the one its own OS happens to produce, which is how this went five
- * releases with the Windows half of it never once executed.
- */
-export function hookCommand(installedHookPath, provider, node = process.execPath,
-                            platform = process.platform) {
-  const q = (s) => shellQuoteArg(s, platform);
-  return `${q(node)} ${q(installedHookPath)} --provider ${q(provider)}`;
-}
-
-function isOurEntry(g) {
-  if (!g || typeof g !== "object") return false;
-  if (g[MARK_KEY] === true) return true;
-  for (const k of LEGACY_MARKS) if (g[k] === true) return true;
-  const cmds = Array.isArray(g.hooks) ? g.hooks : [];
-  for (const h of cmds) {
-    const c = typeof h?.command === "string" ? h.command : "";
-    for (const dir of LEGACY_DIRS) {
-      if (c.includes(`.claude/${dir}/hook.js`) || c.includes(`.claude\\${dir}\\hook.js`)) return true;
-      if (c.includes(`.codex/${dir}/hook.js`) || c.includes(`.codex\\${dir}\\hook.js`)) return true;
-    }
-  }
-  return false;
-}
-
-async function ensureDir(p) {
-  if (!existsSync(p)) await mkdir(p, { recursive: true });
-}
-
-// Notepad and PowerShell's Set-Content write UTF-8 with a byte-order mark, and
-// JSON.parse throws on it when the file is read as utf8. A BOM is not damage —
-// the JSON behind it is fine — so it never gets to look like a corrupt file.
-function stripBom(text) {
-  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
-}
-
-function unreadableSettings(p, why) {
-  const err = new Error(
-    `${p} could not be read as JSON (${why}). Refusing to overwrite it — ` +
-    `fix the file or move it aside, then run ${PRODUCT} again.`,
-  );
-  err.code = "SETTINGS_UNREADABLE";
-  err.settingsPath = p;
-  // The bare reason, without the path and without the remedy sentence, so a
-  // caller that wants to phrase its own advice — `--uninstall` does; "run
-  // ccdeck again" is the wrong instruction there — does not have to take this
-  // message apart with a regex to get at the only part it cannot re-derive.
-  err.why = why;
-  return err;
-}
-
-/**
- * Read settings we are about to rewrite. Only ENOENT means "nothing there yet";
- * every other failure is a file whose contents we cannot reproduce — a stray
- * comma, a half-written file from another process, a permission error — and
- * writing our hooks over it would destroy every setting the user has. So the
- * install refuses instead, loudly, and leaves the file exactly as it found it.
- */
-async function readSettingsForWrite(p) {
-  let raw;
-  try {
-    raw = await readFile(p, "utf8");
-  } catch (err) {
-    if (err?.code === "ENOENT") return { settings: {}, raw: null };
-    throw unreadableSettings(p, err?.message ?? String(err));
-  }
-  let parsed;
-  try {
-    parsed = JSON.parse(stripBom(raw));
-  } catch (err) {
-    throw unreadableSettings(p, err?.message ?? String(err));
-  }
-  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
-    throw unreadableSettings(p, "top level is not a JSON object");
-  }
-  return { settings: parsed, raw };
-}
-
-// Rename over an open file is the one thing Windows does differently here.
-// libuv's rename is one MoveFileExW with MOVEFILE_REPLACE_EXISTING and nothing
-// else — no retry, no MOVEFILE_COPY_ALLOWED — and MoveFileEx honours share
-// modes: it fails outright while ANY other handle is open on the source or the
-// target without FILE_SHARE_DELETE. A virus scanner or the search indexer opens
-// files the instant they are written, so the target is briefly untouchable on a
-// perfectly healthy machine. Node has declined to paper over this (nodejs/node
-// #29481, closed wontfix: "not something that's really under Node's or libuv's
-// control"), and libuv reverted its own four-attempt ladder for the same
-// reason. So the policy lives here, where the stakes are known.
-//
-// The ladder is 10 attempts over ~1.4s, and the second number is the one that
-// matters. It used to be 5 over 200ms, which is comfortably enough for the
-// indexer and not enough for a scanner: the argument on libuv#2098 for
-// reverting their retry was in part that an AV hold can outlast 2s, and 200ms
-// of patience on a hold like that is the same as none.
-//
-// What that thinness cost is not an install. codex-auth.mjs stages a REFRESH
-// TOKEN through this call, the old one is spent server-side by the time it runs,
-// and a rename that gives up too early destroys the only copy of the new
-// credential — the deck reports refresh_rejected and the user has to run
-// `codex login` again. Trading a second of latency against that is not close.
-// The comparison points: steno retries a rename 10 times at 100ms, npm's
-// bin-links 5 times at 500ms exponential, and write-file-atomic does not retry
-// at all (npm/write-file-atomic#227).
-//
-// POSIX never hits this path, and a genuinely permanent permission error costs
-// that second and a half once, on a path that was already failing.
-const RENAME_RETRY_CODES = new Set(["EPERM", "EACCES", "EBUSY"]);
-
-async function renameWithRetry(from, to, attempts = 10) {
-  for (let attempt = 1; ; attempt++) {
-    try {
-      await rename(from, to);
-      return;
-    } catch (err) {
-      if (attempt >= attempts || !RENAME_RETRY_CODES.has(err?.code)) throw err;
-      // Linear: 30, 60, 90 … 270ms, ~1.4s across the nine waits. Linear rather
-      // than exponential because the holds this exists for are short and
-      // frequent, and a doubling ladder spends its whole budget on the last
-      // two waits.
-      await delay(30 * attempt);
-    }
-  }
-}
-
-// Counts writes, not processes. The pid alone gave every call in one deck the
-// same temp path, and there is more than one writer in a deck now: the sound
-// toggle rewrites settings.json from a request handler, so two clients toggling
-// within the same few milliseconds both opened that one path with O_TRUNC and
-// both wrote their own JSON at offset zero. What got renamed over settings.json
-// was the shorter payload with the tail of the longer one still behind it —
-// unparseable, and readSettingsForWrite turns unparseable into a permanent
-// SETTINGS_UNREADABLE refusal for every later toggle and install. The loser then
-// found its temp file already renamed away and threw ENOENT on top of it.
-let tmpSeq = 0;
-
-/**
- * Create the temp file for one write, never sharing it with another writer.
- *
- * "wx" is the point of it: a name that already exists is an error here rather
- * than a silently truncated file two writers are both filling in. The only way
- * to meet a taken name is a deck killed between the write and the rename whose
- * pid the OS has since handed out again — that writer is gone by definition, so
- * the leftover is deleted and the next counter tried. Which is also the whole
- * story on litter: the names come from a small space, this pid crossed with the
- * first few counters, because a deck writes these files a handful of times per
- * run. Later runs walk the same names and sweep what they find instead of
- * piling fresh ones beside it. Digits and hyphens only — a legal filename
- * everywhere, Windows included.
- *
- * `mode` is the mode the file is created with, which matters when the bytes are
- * secret: codex-auth stages a rotated Codex refresh token here, and a temp file
- * that starts at the umask default is readable by every other account on the
- * box for as long as the write takes, whatever chmod follows it. O_EXCL is what
- * makes the mode binding — a create honours it only when it is the call that
- * makes the file, so adopting a leftover would keep the leftover's permissions.
- */
-async function createTemp(target, { mode = 0o666, attempts = 5 } = {}) {
-  for (let attempt = 1; ; attempt++) {
-    const tmp = `${target}.agent-dag-${process.pid}-${tmpSeq++}.tmp`;
-    try {
-      return { tmp, handle: await open(tmp, "wx", mode) };
-    } catch (err) {
-      if (attempt >= attempts || err?.code !== "EEXIST") throw err;
-      await unlink(tmp).catch(() => {});
-    }
-  }
-}
-
-// 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.
- *
- * The temp file is created beside the target rather than in $TMPDIR, because
- * rename is only atomic within one filesystem and the two are routinely on
- * 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(rawTarget, text) {
-  const target = await resolveWriteTarget(rawTarget);
-  const { tmp, handle } = await createTemp(target);
-  try {
-    try {
-      await handle.writeFile(text, "utf8");
-      await handle.sync();
-    } finally {
-      await handle.close();
-    }
-    // A rename creates a fresh directory entry, so the old file's mode does not
-    // come with it. Carry it over — a settings.json the user chmod'ed to 600 has
-    // to stay 600. No-op on Windows, where chmod only toggles the read-only bit.
-    const mode = await stat(target).then(s => s.mode, () => null);
-    if (mode !== null) await chmod(tmp, mode).catch(() => {});
-    // A READ-ONLY TARGET IS A DEAD END ON WINDOWS, and only there. libuv's
-    // rename is one MoveFileExW(MOVEFILE_REPLACE_EXISTING), which refuses to
-    // replace a destination carrying FILE_ATTRIBUTE_READONLY; POSIX rename(2)
-    // over a 0444 file succeeds, because only the parent directory's write bit
-    // decides. A settings.json picks that attribute up from a OneDrive restore,
-    // a copy off a network share, or read-only media — and EACCES is in the
-    // retry ladder, so the whole ~1.4s was spent before throwing, on every
-    // boot, forever. Every settings writer goes through here, so hooks never
-    // installed and the sound-hook retirement could never repair a stale entry
-    // either.
-    //
-    // chmod on Windows toggles exactly that attribute and nothing else, which
-    // is why this is safe to do unconditionally there: the mode carried above
-    // is re-applied to the new file after the rename, so a file the user marked
-    // read-only stays read-only.
-    // ONLY WHEN THE TARGET IS ACTUALLY READ-ONLY. Two extra syscalls on the
-    // path between the temp write and the rename are not free on Windows:
-    // discovery-live.test.ts hammers writeDiscovery while a reader holds the
-    // destination open, and the wider window turned a rename the retry ladder
-    // used to win into an EPERM it gave up on. The attribute is what this
-    // clears, so a file that does not carry it has nothing to clear.
-    const readOnly = process.platform === "win32" && mode !== null && (mode & 0o200) === 0;
-    if (readOnly) await chmod(target, 0o666).catch(() => {});
-    await renameWithRetry(tmp, target);
-    if (readOnly) await chmod(target, mode).catch(() => {});
-  } catch (err) {
-    // Cleanup covers the write and the fsync as well as the rename: a full disk
-    // used to leave the half-written temp file sitting beside the target.
-    await unlink(tmp).catch(() => {});
-    throw err;
-  }
-}
-
-/**
- * Install one of the packaged hook scripts without ever exposing a partial one.
- *
- * copyFile truncates the destination and then fills it, and the destination here
- * is a script every live Claude Code session runs on each tool call. Starting the
- * deck while sessions are open — the normal way this is used — puts a hook
- * invocation inside that window sooner or later, and what it executes is an
- * empty or half-written program: a dropped event at best, a SyntaxError in the
- * user's session at worst. Renaming a finished copy over the name closes it, so
- * a session opens either the old script or the new one and both are whole.
- *
- * Re-installs are the common case and almost always produce the same bytes, so
- * identical content skips the write and the file is not replaced at all.
- */
-async function installScript(src, dst) {
-  const text = await readFile(src, "utf8");
-  const current = await readFile(dst, "utf8").catch(() => null);
-  if (current === text) return false;
-  await writeFileAtomic(dst, text);
-  return true;
-}
-
-async function installHookScript(installDir) {
-  await ensureDir(installDir);
-  const src = join(PKG_ROOT, "hook", "hook.js");
-  const dst = join(installDir, "hook.js");
-  await installScript(src, dst);
-  return dst;
-}
-
-function buildHookEntry(command) {
-  return {
-    [MARK_KEY]: true,
-    hooks: [{ type: "command", command, timeout: 2 }],
-  };
-}
-
-function dedupeOurEntries(group) {
-  if (!Array.isArray(group)) return [];
-  return group.filter(g => !isOurEntry(g));
-}
-
-/** Install hooks for a single provider. Returns {settingsPath, hookPath, events, changed}. */
-export async function installHooks({ provider = "claude", beforeWrite = null } = {}) {
-  const cfg = PROVIDERS[provider];
-  if (!cfg) throw new Error(`unknown provider: ${provider}`);
-  // An uninstall-only provider has no event list. Saying so beats the
-  // TypeError that installing an undefined list would otherwise raise several
-  // frames deep, after the hook script had already been written to disk.
-  if (!cfg.events) throw new Error(`provider ${provider} is uninstall-only: hooks are not installed for it`);
-
-  // Read before writing anything, so a settings file we cannot parse aborts
-  // the install without leaving half of it behind.
-  const { settings: current, raw: before } = await readSettingsForWrite(cfg.settingsPath);
-
-  const hookPath = await installHookScript(cfg.hookInstallDir);
-  const command = hookCommand(hookPath, provider);
-  await ensureDir(cfg.ensureDir);
-  // Discovery dir is shared across providers — always make sure it exists.
-  await ensureDir(AGENT_DAG_DIR);
-
-  current.hooks = current.hooks ?? {};
-
-  for (const evt of cfg.events) {
-    const cleaned = dedupeOurEntries(current.hooks[evt]);
-    cleaned.push(buildHookEntry(command));
-    current.hooks[evt] = cleaned;
-  }
-
-  // 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.
-  //
-  // 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 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
-  // there and identical. Writing anyway is pure downside: it is one more chance
-  // to be interrupted mid-write, and one more window in which a change Claude
-  // Code made to the file between our read and our write gets discarded. So
-  // compare against the exact bytes we read and, when they match, do nothing.
-  const next = JSON.stringify(current, null, 2) + "\n";
-  const changed = next !== before;
-  if (changed) {
-    // COMPARE AGAINST THE FILE, NOT AGAINST THE SNAPSHOT, at the last moment.
-    //
-    // Everything above was computed from bytes read at the top of this
-    // function, and two decks booting together — the ordinary case on a machine
-    // where one was already running — interleave inside that window. The one
-    // that loses is unrecoverable rather than merely stale: deck A restores the
-    // user's own sound hooks from the parked file and deletes the park, and
-    // deck B then writes a settings object computed before that restore, with
-    // an empty park behind it. The user's hook is gone from settings.json and
-    // from the only other copy of it.
-    //
-    // So the file is re-read immediately before the write and, if another
-    // writer has touched it, this pass declines. Declining is safe by
-    // construction: every boot reinstalls, so the next one recomputes against
-    // the new bytes and converges — and the entries this function adds are
-    // identical on both decks, which is why the loser has nothing of its own to
-    // lose.
-    // The seam the suite needs, and the only way to test this deterministically:
-    // the window between the read at the top and the write below is filled with
-    // real fs work, so a test that raced it by wall clock would pass or fail by
-    // how fast the machine is. Production passes nothing.
-    if (beforeWrite) await beforeWrite();
-    // A READ THE GUARD COULD NOT PERFORM IS NOT PROOF NOTHING CHANGED (#788).
-    // This used to be `.catch(() => ({ raw: before }))`, which substituted the
-    // snapshot and so answered "unchanged" for every failed re-read. ENOENT is
-    // the one case that substitution would be right for, and it does not reach
-    // here at all — readSettingsForWrite returns `{ raw: null }` for it without
-    // throwing. What does reach here is EACCES/EBUSY on a file written
-    // microseconds ago, which is the condition this module's own header names:
-    // "a virus scanner or the search indexer opens files the instant they are
-    // written, so the target is briefly untouchable on a perfectly healthy
-    // machine". Precisely when another deck has just written it.
-    //
-    // So an unreadable re-read declines, like a changed one. Declining is safe
-    // for the reason above: every boot reinstalls and the next pass converges.
-    // Being wrong the other way is not — it is the lost update this guard
-    // exists to prevent, with the user's own sound hook gone from settings.json
-    // and from the park that was its only other copy.
-    let onDisk;
-    let unreadable = false;
-    try { ({ raw: onDisk } = await readSettingsForWrite(cfg.settingsPath)); }
-    catch { unreadable = true; }
-    if (unreadable || onDisk !== before) {
-      return {
-        settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider,
-        changed: false, raced: true, retire: { ...retire, pending: false },
-      };
-    }
-    await writeFileAtomic(cfg.settingsPath, next);
-  }
-  // 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 };
-}
-
-/**
- * Take our forwarders back out of one provider's settings file.
- *
- * Returns `{ok: true, changed}` when the file was read — `changed` says whether
- * anything of ours was in it — and `{ok: false, reason: "settings_unreadable"}`
- * when it was not. Callers must look at `ok` FIRST: `changed: false` on a
- * refusal is the literal truth about the disk and a lie about the question
- * being asked, because the hooks are still in there.
- *
- * That conflation is what this used to ship. The read was readJsonSafe, which
- * turned every parse and IO failure into `null`, so a settings.json with one
- * stray comma — the exact file readSettingsForWrite was written to protect —
- * came back indistinguishable from a clean machine with none of our hooks in
- * 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: 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
- * file we cannot parse is a file whose contents we cannot reproduce, and this
- * function rewrites the whole thing — every permission, env var, model pin and
- * hand-written hook in it. Refusing leaves it byte for byte as it was found and
- * hands the user something they can act on; guessing would either destroy it or
- * quietly do nothing. Only ENOENT is genuinely empty, and readSettingsForWrite
- * already answers that with `{}`, which falls through to `changed: false`.
- */
-export async function uninstallHooks({ provider = "claude", beforeWrite = null } = {}) {
-  const cfg = PROVIDERS[provider];
-  if (!cfg) throw new Error(`unknown provider: ${provider}`);
-  let current;
-  let before;
-  try {
-    ({ settings: current, raw: before } = await readSettingsForWrite(cfg.settingsPath));
-  } catch (err) {
-    if (err?.code !== "SETTINGS_UNREADABLE") throw err;
-    // 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 {
-      ok: false,
-      reason: "settings_unreadable",
-      changed: false,
-      provider,
-      settingsPath: cfg.settingsPath,
-      why: err.why ?? err.message,
-      message: err.message,
-    };
-  }
-  if (!current?.hooks) return { ok: true, changed: false, provider, settingsPath: cfg.settingsPath };
-  let changed = false;
-  for (const evt of Object.keys(current.hooks)) {
-    const cleaned = dedupeOurEntries(current.hooks[evt]);
-    if (cleaned.length !== (current.hooks[evt]?.length ?? 0)) changed = true;
-    if (cleaned.length === 0) delete current.hooks[evt];
-    else current.hooks[evt] = cleaned;
-  }
-  if (changed) {
-    // THE SAME GUARD ITS SIBLING HAS, for the same file (#788). `installHooks`
-    // grew a compare-against-the-file check at the last moment and this
-    // function — which rewrites the same settings.json from a snapshot read
-    // just as long ago — never got one.
-    //
-    // The race is `ccdeck --uninstall` against a deck that is starting.
-    // Uninstall reads settings.json with the user's own hooks still parked. In
-    // the window before its write — resolveWriteTarget, temp create, write,
-    // fsync, stat, rename — the booting deck restores those hooks and deletes
-    // the park. Uninstall then writes its stale object over the restore,
-    // bin/deck.js re-reads the clobbered file, readParked hits ENOENT, and it
-    // reports `restored: 0`. The hooks are gone from both copies and the CLI
-    // exits 0 saying the uninstall succeeded.
-    //
-    // Declining here is not as cheap as declining an install — nothing retries
-    // an uninstall — so it says so in the result rather than answering `ok`
-    // with `changed: false`, which would read as "there was nothing to remove".
-    // The seam the suite needs, and `installHooks` states the argument for it:
-    // the window this guard covers is filled with real fs work, so a test that
-    // raced it by wall clock would pass or fail by how fast the machine is.
-    // Production passes nothing.
-    if (beforeWrite) await beforeWrite();
-    let onDisk;
-    let unreadable = false;
-    try { ({ raw: onDisk } = await readSettingsForWrite(cfg.settingsPath)); }
-    catch { unreadable = true; }
-    if (unreadable || onDisk !== before) {
-      return {
-        ok: false, reason: "raced", changed: false, provider,
-        settingsPath: cfg.settingsPath,
-        why: "another writer changed settings.json while the uninstall was running",
-        message: `${cfg.settingsPath} changed while uninstalling — nothing was removed. Run --uninstall again.`,
-      };
-    }
-    await writeFileAtomic(cfg.settingsPath, JSON.stringify(current, null, 2) + "\n");
-  }
-  return { ok: true, changed, provider, settingsPath: cfg.settingsPath };
-}
-
-/** True when ~/.codex/ exists — the CLI's default answer to whether the Codex
- *  rollout watcher is worth starting, and whether there are hooks to remove. */
-export function hasCodexInstalled() {
-  return existsSync(CODEX_DIR);
-}
-
-/**
- * The events log as the record spells it: an absolute path, or null when this
- * deck writes none. Shared by the writer and by ensureDiscovery's comparison,
- * so a file this process wrote can never read back as somebody else's.
- */
-function persistField(persist) {
-  return typeof persist === "string" && persist !== "" ? persist : null;
-}
-
-// Every deck's token lives in this directory, and writeFileAtomic's temp file is
-// created beside its target with whatever the umask allows — 0644 on most
-// machines — so for the moment before the rename the token would sit in a
-// world-readable file. 0700 on the directory closes that window from the outside:
-// another user cannot traverse into it whatever the mode of a file inside says.
-// The dir usually predates this code, so the mode is re-asserted rather than only
-// set at creation, where it would be masked by the umask anyway. Windows ignores
-// both — NTFS ACLs inherit from the per-user profile directory.
-async function ensureDiscoveryDir() {
-  if (!existsSync(AGENT_DAG_DIR)) await mkdir(AGENT_DAG_DIR, { recursive: true, mode: 0o700 });
-  await chmod(AGENT_DAG_DIR, 0o700).catch(() => {});
-}
-
-/**
- * Register this deck, in one step no reader can land inside.
- *
- * The record used to go down with a plain writeFile, which truncates the target
- * and then fills it, so the file existed and was empty for a moment on every
- * rewrite. Everything that reads this directory parses each record whole —
- * electWriters in hook/hook.js, readLiveDecks and sweepStaleDiscovery in
- * index.mjs — and a record that fails to parse is a deck missing from that
- * cycle: the event it should have logged is either logged by nobody or logged
- * twice by the decks that remain, which is the exact failure the single-writer
- * election exists to prevent, reached through the file the election reads. A
- * rename is atomic on Linux, macOS and Windows alike, so a reader now sees the
- * previous record or the new one and never half of either.
- *
- * The token is the deck's proof of identity, so the file holding it is the
- * deck's key material: readable and writable by its owner, nobody else. The mode
- * is pinned after the write because writeFileAtomic can only carry over a mode
- * the target already had — a first registration, or one left by an earlier run
- * under a recycled pid, would otherwise keep whatever the umask handed it.
- */
-export async function writeDiscovery({ port, workspace, token, persist = null, codex = true, claude = true, version = "", parent = null }) {
-  await ensureDiscoveryDir();
-  const file = discoveryPath();
-  const data = {
-    pid: process.pid,
-    port,
-    workspace: workspace ?? "",
-    // Without this the hooks refuse to post: a file naming a port it cannot
-    // authenticate is exactly the stale-file case they now decline to trust.
-    token: token ?? "",
-    // Absolute path of the events log this deck appends to, or null under
-    // --no-persist. The hook reads it to elect a single writer per file:
-    // several decks receive the same event by design, and without this they
-    // each appended their own copy to the one log they share. See
-    // electWriters in hook/hook.js.
-    persist: persistField(persist),
-    // Is this deck tailing Codex's rollout files? Those events never pass
-    // through a hook, so the decks elect a writer for them among themselves —
-    // and a deck running --no-codex must be left out of that election rather
-    // than win it and record a rollout it is not even reading. See
-    // writesCodexLog in src/server/log-writer.mjs.
-    codex: codex !== false,
-    // Does this deck run Browser Watch? The watch elects a single writer among
-    // the decks on a machine, and it elected on port alone — so an older ccdeck
-    // that predates the feature won the election by having the lower port and
-    // then wrote nothing, while the deck that HAS the watch stood down. Measured
-    // on this machine: a v1.46 deck from an npx cache held 4317, answered the
-    // watch route with the SPA's index.html, and Browser Watch silently
-    // recorded nothing for as long as both were up. No error, no log line — the
-    // panel showed findings on screen and the disk stayed empty.
-    //
-    // Same shape as `codex` above, and for the same reason: a deck that is not
-    // doing the work must be left out of the election rather than win it. An
-    // older deck has no such field, so it is excluded by construction.
-    watch: true,
-    // Is the Claude side of this deck switched on? Same shape as `codex` above
-    // and there for a second reader: a bare `ccdeck` that finds this deck
-    // running attaches to it instead of starting a rival, and it may only do
-    // that when the deck on the port is the deck it would itself have built. A
-    // `--no-claude` deck has no hooks, no accounts panel and no switcher, and
-    // until this field existed it was indistinguishable from one that has all
-    // three. An older deck has no such field, so it is excluded by
-    // construction — see runningDeck.
-    claude: claude !== false,
-    // What this deck IS, so a launcher that attaches can say whether the deck
-    // it found is the version the user just asked for. Never a decision: a
-    // rival deck on a random port is worse than an older deck said out loud.
-    version: typeof version === "string" ? version : "",
-    // The supervisor above this worker, or null when nothing is supervising.
-    //
-    // Only `ccdeck --stop` reads it, and only on the path where the polite
-    // request failed. A worker killed on its own leaves its supervisor alive,
-    // and a supervisor that puts crashed workers back would answer that kill by
-    // starting the deck again — so the ladder has to end the parent first and
-    // the child second, which it cannot do without being told who the parent is.
-    parent: Number.isInteger(parent) ? parent : null,
-    startedAt: new Date().toISOString(),
-  };
-  await writeFileAtomic(file, JSON.stringify(data, null, 2) + "\n");
-  await chmod(file, 0o600).catch(() => {});
-  return file;
-}
-
-export async function removeDiscovery(file) {
-  try { await unlink(file); } catch {}
-}
-
-/** Where this process registers itself. One file per deck, named by pid. */
-export function discoveryPath() {
-  return join(AGENT_DAG_DIR, `${process.pid}.json`);
-}
-
-/**
- * Make sure this deck's discovery file is on disk and says what it should.
- *
- * Registration was a single write at boot, so anything that took the file away
- * afterwards — a sweep on another machine's clock, a half-finished restart, a
- * user tidying the directory — left a deck that was listening, serving and
- * completely invisible: hook.js enumerates this directory and nothing else, so
- * the deck received zero events while looking perfectly healthy. Re-asserting
- * is cheap (one small read), so the deck checks rather than assumes.
- *
- * A file this process wrote is left alone, mode included. Anything else — no
- * file, unreadable, another pid, a stale port, token, events log, Codex or
- * Claude setting, or a version left by the deck this process replaced — is
- * replaced. Every field another deck decides by is compared, the
- * log path included: leave one out and a record missing it would pass as ours
- * forever, which for the log path means no deck can tell which of them share a
- * file and they all write their own copy of every event again.
- */
-export async function ensureDiscovery({ port, workspace, token, persist = null, codex = true, claude = true, version = "", parent = null }) {
-  const file = discoveryPath();
-  try {
-    const d = JSON.parse(stripBom(await readFile(file, "utf8")));
-    if (d
-      && d.pid === process.pid
-      && d.port === port
-      && (d.workspace ?? "") === (workspace ?? "")
-      && (d.token ?? "") === (token ?? "")
-      && (d.persist ?? null) === persistField(persist)
-      && d.codex === (codex !== false)
-      && d.claude === (claude !== false)
-      && (d.version ?? "") === (typeof version === "string" ? version : "")
-      && (d.parent ?? null) === (Number.isInteger(parent) ? parent : null)) {
-      return { file, rewritten: false };
-    }
-  } catch { /* missing, unreadable or corrupt — rewritten below */ }
-  await writeDiscovery({ port, workspace, token, persist, codex, claude, version, parent });
-  return { file, rewritten: true };
-}
-
-/**
- * Keep this deck registered for as long as it runs, and tell the caller when
- * that stops being true.
- *
- * `onState` hears the first outcome, every change of health, and every
- * re-registration after the first — never a steady state. A deck that cannot
- * write the file has to say so: silently listening while no hook can find it
- * is the failure this exists to end, not a state worth hiding.
- *
- * The interval is unref'd, so it never keeps a finished process alive, and
- * `stop()` must be called before the file is removed on shutdown — otherwise
- * the next tick would put it straight back.
- *
- * `stop()` ANSWERS WITH THE CHECK ALREADY IN FLIGHT, and shutdown has to await
- * it. Clearing the interval stops the next tick; it does nothing about the one
- * that started a moment ago and is currently inside writeFileAtomic. That tick
- * finishes after the unlink and re-creates the file — exactly the "leave the
- * file behind for the hooks to find once nothing is listening" that stopping
- * first is supposed to prevent, reached by the one route stopping first does
- * not cover. The window is a rename and an fsync on POSIX; on Windows it is
- * that plus renameWithRetry's ladder, up to 200ms of sleeping while a scanner
- * holds the target — the platform the retry was written for is the platform
- * where the race is twenty times wider.
- *
- * `run()` never rejects (every failure is a state), so awaiting this cannot
- * throw and cannot outlast one bounded check.
- */
-export function keepDiscovery({ port, workspace, token, persist = null, codex = true, claude = true, version = "", parent = null, intervalMs = 5000, onState = null } = {}) {
-  // null until the first outcome, which therefore always differs and is always
-  // reported — the caller learns where it stands before anything else happens.
-  let healthy = null;
-
-  const run = async () => {
-    let state;
-    try {
-      const { rewritten } = await ensureDiscovery({ port, workspace, token, persist, codex, claude, version, parent });
-      state = { ok: true, rewritten, file: discoveryPath(), error: null };
-    } catch (err) {
-      state = { ok: false, rewritten: false, file: discoveryPath(), error: err };
-    }
-    const worthSaying = healthy !== state.ok || state.rewritten;
-    healthy = state.ok;
-    if (worthSaying && onState) { try { onState(state); } catch { /* not our problem */ } }
-    return state;
-  };
-
-  // One check at a time. Registration is a write and a write is now a rename,
-  // which costs an fsync — long enough that a tick can land inside the boot-time
-  // check bin/deck.js runs by hand. That second check reads a file the first has
-  // not renamed into place yet, concludes the deck is unregistered and writes it
-  // again, and the two writes race over one record: the deck reports itself
-  // unregistered on a machine where nothing whatsoever is wrong. A caller that
-  // asks mid-check gets the answer the check already in flight is fetching.
-  let inFlight = null;
-  const check = () => (inFlight ??= run().finally(() => { inFlight = null; }));
-
-  const timer = setInterval(() => { check(); }, intervalMs);
-  timer.unref?.();
-
-  const stop = () => {
-    clearInterval(timer);
-    return inFlight ?? Promise.resolve(null);
-  };
-
-  return { file: discoveryPath(), check, stop };
-}
-
-// CLAUDE_EVENTS used to ride along here (#383). It is the events list of the
-// `claude` entry in PROVIDERS and has never had a reader outside this file; it
-// was easy to miss because the three directories beside it ARE imported and
-// because the long justification below belongs to the SECOND export, not this
-// one. Which events the deck asks Claude Code for is answered by installHooks
-// writing settings.json, which is what the tests read.
-export { AGENT_DAG_DIR, CLAUDE_DIR, CODEX_DIR };
-// Exported for the other modules that rewrite settings.json — the sound toggle
-// today. Every one of them needs the same two guarantees: a file we cannot
-// parse is never treated as an empty one, and the replacement is a single
-// rename rather than a truncate a reader can land inside. installScript carries
-// the same guarantee to the hook scripts themselves, which are the files live
-// sessions are actually executing, and renameWithRetry goes out on its own for
-// the files writeFileAtomic cannot write — the fetched uv binary in
-// uv-bootstrap.mjs — which still need the Windows retry. createTemp goes out for
-// 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.
-// 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, renameWithRetry, createTemp, resolveWriteTarget };