ccdeck 1.42.0 → 1.44.1

package/src/server/installer.mjs

@@ -0,0 +1,674 @@
+// 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 } 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(() => {});
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+async function writeFileAtomic(target, text) {
+  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(() => {});
+    await renameWithRetry(tmp, target);
+  } 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" } = {}) {
+  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;
+  }
+
+  // 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.
+  //
+  // 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;
+  if (provider === "claude") {
+    const soundHook = await import("./sound-hook.mjs");
+    sweepLegacySoundScript = soundHook.sweepLegacySoundScript;
+    sound = await soundHook.reassertSoundHook(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) 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 };
+}
+
+/**
+ * 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: uninstallSoundHook reads through
+ * readSettingsForWrite and says 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" } = {}) {
+  const cfg = PROVIDERS[provider];
+  if (!cfg) throw new Error(`unknown provider: ${provider}`);
+  let current;
+  try {
+    ({ 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
+    // 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) 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 }) {
+  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,
+    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 or Codex
+ * setting — 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 }) {
+  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)) {
+      return { file, rewritten: false };
+    }
+  } catch { /* missing, unreadable or corrupt — rewritten below */ }
+  await writeDiscovery({ port, workspace, token, persist, codex });
+  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, 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 });
+      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.
+export { readSettingsForWrite, writeFileAtomic, installScript, renameWithRetry, createTemp };