agent-dag 1.42.0 → 1.44.1

package/src/server/index.mjs

@@ -609,7 +609,7 @@ function maybeResolveUsage(payload) {
 // The emit is what is actually kept rare, and it is gated on a CHANGE: with 685
 // records carrying 2 distinct values, a per-pass emit would be ~683 events
 // saying nothing. Sessions that never get named emit nothing at all.
-const nameBySession = new Map();        // sid -> `${agentName}${aiTitle}`
+const nameBySession = new Map();        // sid -> `${agentName}\0${aiTitle}`
 const lastNameReadAt = new Map();       // sid -> ms timestamp
 const pendingNameReads = new Set();     // sid currently being read
 
@@ -637,7 +637,7 @@ function maybeResolveSessionName(payload) {
   readSessionNamingFromTranscript(tp)
     .then(naming => {
       if (!naming) return;
-      const sig = `${naming.agentName ?? ""}${naming.aiTitle ?? ""}`;
+      const sig = `${naming.agentName ?? ""}\u0000${naming.aiTitle ?? ""}`;
       if (nameBySession.get(sid) === sig) return;
       nameBySession.set(sid, sig);
       pushEvent({
@@ -1701,6 +1701,18 @@ const MAX_TRACKED_SESSIONS = 256;
 
 function forgetSession(sid) {
   modelBySession.delete(sid);
+  // The two the session-naming work added (#520/#522) and did not list here.
+  // Both are keyed by session id and nothing else ever removed an entry, which
+  // is the exact leak the comment above says this mechanism exists to end —
+  // every sibling cache is capped at MAX_TRACKED_SESSIONS and these two were
+  // not. The functional half is worse than the leak: nameBySession gates the
+  // SessionNamed emit on "has this changed", so a live session evicted past the
+  // cap and then heard from again re-emits its model (modelBySession was
+  // cleared) and never re-emits its name. A tab that connects after the event
+  // ring has rolled past the original SessionNamed shows that session unnamed
+  // for the rest of its life.
+  nameBySession.delete(sid);
+  lastNameReadAt.delete(sid);
   modelLastReadAt.delete(sid);
   lastUsageReadAt.delete(sid);
   lastContextReadAt.delete(sid);
@@ -1737,14 +1749,77 @@ function touchSession(sid) {
 // buffer replays whatever it missed. Dropping individual events instead would
 // leave a hole the resume path cannot even see, the client's last id having
 // moved past it.
-const MAX_CLIENT_BUFFER_BYTES = 8 * 1024 * 1024;
+//
+// The ceiling has to clear the largest SINGLE frame the deck can emit, because
+// one write() of such a frame puts the whole of it in the queue with nothing
+// having had the chance to drain any of it — a client reading at full speed
+// looks, for that instant, exactly like a frozen tab. #588 was exactly that
+// failure: queuedBytes below doubled every reading, so the real ceiling was
+// 4 MiB and one 4 MiB tool response hung up on every subscribed tab at once.
+//
+// So the number is checked against what `POST /api/event` admits rather than
+// left to feel. handleEventIngest caps a body at 5,000,000 CHARACTERS. The
+// event is re-serialized before it goes out, and re-serializing a value that
+// came from JSON.parse of an N-character document cannot exceed N characters —
+// every escape the output needs was already paid for in the input, and \uXXXX
+// input comes back shorter — so one frame is at most 5,000,000 characters, plus
+// this deck's envelope, measured at 127, plus the id/event/data framing. 8 MiB
+// clears that by a little over 1.6x, and is the number this constant has always
+// named; what #588 changed is that it now means it.
+//
+// Characters, not bytes, which is the one misleading thing left in the name.
+// writeSse and writeResume write STRINGS, and a Writable with decodeStrings
+// false — which both an OutgoingMessage and the net.Socket under it are — adds
+// `chunk.length`, i.e. UTF-16 units, to its queue. Measured on Node 22.14: a
+// 4,800,000-character Read of CJK text is 14,400,184 bytes on the wire and
+// `res.writableLength` reports 4,800,311. That is why comparing this against a
+// character-denominated ingest limit is the right comparison and comparing it
+// against a byte count would not be — and it is worth stating plainly, because
+// assuming a unit for writableLength instead of measuring it is the whole
+// shape of the bug this comment exists to explain. The memory behind a full
+// buffer is larger than the number says, up to two bytes per unit while it is
+// held as a string; that is not what the cap is for, which is noticing a client
+// that has stopped reading at all.
+//
+// Exported, with queuedBytes, so the arithmetic can be asserted directly. #588
+// survived because it could only be observed through a live socket, where the
+// existing tests' tolerances were wider than the error.
+export const MAX_CLIENT_BUFFER_BYTES = 8 * 1024 * 1024;
 
-/** Bytes queued for a client: what the response has not handed to the socket
- *  yet, plus what the socket has not handed to the kernel. */
-function queuedBytes(res) {
+/**
+ * What this response has accepted and not yet handed to the kernel, in the
+ * units writableLength reports it in — see MAX_CLIENT_BUFFER_BYTES above, which
+ * is the number this is compared against.
+ *
+ * NOT the sum of the two writableLengths, which is what #588 was: Node's
+ * `OutgoingMessage.writableLength` getter is `outputSize + this[kChunkedLength]
+ * + (socket ? socket.writableLength : 0)`, so the socket's queue is already
+ * inside it. For an SSE response, whose outputSize is zero from the moment the
+ * headers flush, the two readings are the same number exactly — measured on
+ * Node 22.14 against a paused reader, `res.writableLength=4194615
+ * socket.writableLength=4194615` — so adding them reported exactly twice the
+ * real backlog and made an 8 MiB constant behave as a 4 MiB one.
+ *
+ * Why max and not simply `res.writableLength`, which is today's whole answer.
+ * That composition is a Node implementation detail and it has moved before, so
+ * the expression is chosen to survive it moving again. Read the two as an
+ * overlapping pair and take the larger:
+ *   - composed as it is today, `own` already contains `sock`, so `own >= sock`
+ *     and max is `own` — the exact total;
+ *   - were the getter to stop including the socket term, `own` for a flushed
+ *     SSE response is zero and max is `sock` — again the exact total;
+ *   - with the socket detached (`res.socket` null, which happens between the
+ *     response ending and the handle being released) max is `own`, the only
+ *     reading there is.
+ * Every case is right, and the failure mode if some future composition makes
+ * both terms non-zero and disjoint is under-counting by at most 2x — a client
+ * held a little longer than intended, which is the harmless direction. Summing
+ * fails the other way, and dropping readers that are not behind is the bug.
+ */
+export function queuedBytes(res) {
   const own = typeof res.writableLength === "number" ? res.writableLength : 0;
   const sock = res.socket && typeof res.socket.writableLength === "number" ? res.socket.writableLength : 0;
-  return own + sock;
+  return Math.max(own, sock);
 }
 
 /** Hang up on a client we have decided not to keep. `delete` on a response
@@ -1775,6 +1850,14 @@ function writeSse(res, frame) {
 // not accept a byte in any budget, so the only thing a long one buys it is a
 // few more seconds of holding its own buffer. The environment override exists
 // so the tests can pin the drop without sitting through the real budget.
+//
+// It is a budget per awaited frame, and what that frame waits on is everything
+// queued ahead of it draining — a full MAX_CLIENT_BUFFER_BYTES, by
+// construction, since that is what the loop fills to before it stops. So this
+// states a minimum rate a resuming client has to manage, and #588 doubled that
+// flush in practice without touching this line: the cap it is sized against was
+// really 4 MiB and is now the 8 MiB it always said. Still generous — measured
+// on loopback a full cap flushes in about a quarter of a second.
 const REPLAY_DRAIN_MS = Number(process.env.AGENTS_DECK_REPLAY_DRAIN_MS) > 0
   ? Number(process.env.AGENTS_DECK_REPLAY_DRAIN_MS)
   : 30_000;
@@ -1797,10 +1880,12 @@ const REPLAY_DRAIN_MS = Number(process.env.AGENTS_DECK_REPLAY_DRAIN_MS) > 0
  * up on a client that takes nothing at all for REPLAY_DRAIN_MS.
  *
  * The wait is on write()'s completion callback rather than on a 'drain' event:
- * 'drain' only follows a write that was answered false, and a frame can push
- * queuedBytes past the cap while still being answered true, the socket's own
- * pending bytes being one of the two terms in that sum. The callback fires
- * once this chunk —
+ * 'drain' fires only after a write that was answered false, so waiting on it
+ * means depending on an answer this call may never have seen. The cap sits far
+ * above the stream's own 16 KiB high-water mark, so by the time queuedBytes is
+ * at the cap the `false` that a 'drain' would eventually answer belongs to some
+ * frame long since written, and its drain may already have come and gone. The
+ * callback fires once this chunk —
  * and therefore everything queued ahead of it — has reached the OS, which is
  * exactly the condition being waited for. It also fires, with an error we do
  * not need to read, if the response is destroyed underneath us, so this cannot
@@ -3086,16 +3171,102 @@ export function sendInternalError(res, err, log = console.error) {
   else res.end();
 }
 
+// One attempt, leaving the server with no more listeners on it than it started
+// with. `server.listen(port, host, cb)` registers `cb` for a 'listening' event
+// that a failed bind never emits, so the previous shape left one behind per
+// attempt — eleven candidates printed Node's "MaxListenersExceededWarning:
+// 11 listening listeners added to [Server]" into the middle of a boot that was
+// already going wrong. Both sides are removed by whichever fires first.
 async function tryListen(server, port, host) {
   return new Promise((res, rej) => {
-    server.once("error", rej);
-    server.listen(port, host, () => {
-      server.removeListener("error", rej);
-      res();
-    });
+    const onListening = () => { server.removeListener("error", onError); res(); };
+    const onError = (err) => { server.removeListener("listening", onListening); rej(err); };
+    server.once("error", onError);
+    server.once("listening", onListening);
+    server.listen(port, host);
   });
 }
 
+/**
+ * Whether another PORT could fix this failed `listen`.
+ *
+ * startServer builds ten random fallback candidates and they exist for exactly
+ * one situation: "this port is unavailable". Until #552 only EADDRINUSE reached
+ * them, which is the POSIX spelling of that answer and not the only one.
+ *
+ * WINDOWS. `winnat` hands out contiguous TCP blocks to Hyper-V, WSL2 and Docker
+ * Desktop, and a bind INSIDE one of those reserved exclusion ranges — the ones
+ * `netsh interface ipv4 show excludedportrange protocol=tcp` prints — is refused
+ * with WSAEACCES, which libuv reports as EACCES. Any machine with containers or
+ * WSL on it can therefore have 4317 blocked without a single socket being open
+ * on it. The loop rethrew on the first candidate, bin/deck.js printed
+ * `server failed: listen EACCES: permission denied 127.0.0.1:4317`, and the deck
+ * exited 1 with the fallback range untouched.
+ *
+ * On POSIX the same code is what a bind below 1024 gets without privilege.
+ * Retrying is right there too: 4317 and the whole fallback range are above 1024,
+ * so a random candidate is a port the user can actually have — and the deck
+ * coming up on 4322 beats it refusing to come up at all, which is already how
+ * EADDRINUSE on a privileged port behaves today.
+ *
+ * The other direction is the half that keeps this honest. EADDRNOTAVAIL,
+ * ENOTFOUND, EAI_AGAIN and EAFNOSUPPORT are about the HOST, not the port: the
+ * address does not exist on this machine or does not resolve, and no candidate
+ * can help. Walking eleven of them only delays the one sentence that would have
+ * explained it, so anything not named here stops the loop.
+ */
+export const portRetryable = (err) =>
+  Boolean(err) && (err.code === "EADDRINUSE" || err.code === "EACCES");
+
+/**
+ * The sentence that goes beside a listen errno, or "" when the errno says it
+ * all.
+ *
+ * Pure, and the platform is a parameter, for the reason every Windows answer in
+ * this repo is written that way: the branch that matters most is the one the
+ * author cannot run. A raw `listen EACCES: permission denied 127.0.0.1:4317` is
+ * true and useless — the thing the user needs is the name of the command that
+ * lists the ranges their machine has reserved.
+ */
+export function listenHint(code, { host = "", port = 0, platform = process.platform } = {}) {
+  if (code === "EACCES") {
+    if (platform === "win32") {
+      return "a reserved port range is the usual cause on Windows: Hyper-V, WSL2 and Docker Desktop have winnat hold contiguous TCP blocks. Run `netsh interface ipv4 show excludedportrange protocol=tcp` to see them, then pass --port with a number outside every range";
+    }
+    if (port > 0 && port < 1024) return "ports below 1024 need root — pass --port with a number above 1024";
+    return "the OS refused the bind; a sandbox or a security policy is the usual cause";
+  }
+  if (code === "EADDRNOTAVAIL") {
+    return `no interface on this machine holds ${host || "that address"}, so no other port can help — pass --host with an address it does hold, or 127.0.0.1 for local only`;
+  }
+  if (code === "ENOTFOUND" || code === "EAI_AGAIN") {
+    return `${host || "that host"} does not resolve, so no other port can help — pass --host with an address rather than a name`;
+  }
+  return "";
+}
+
+/**
+ * The error startServer throws, with the hint already in it.
+ *
+ * `exhausted` is the difference between "every candidate was refused" and "this
+ * one was refused for a reason more candidates cannot fix". The exhausted
+ * message keeps its opening words — bin/deck.js prints them and
+ * boot-listen-before-report.test.ts reads them — and now names the LAST errno
+ * rather than asserting EADDRINUSE, which was a lie the moment EACCES could
+ * reach the end of the loop.
+ */
+export function listenFailure(err, { host = "", port = 0, platform = process.platform, exhausted = false } = {}) {
+  const code = err?.code;
+  const head = exhausted
+    ? `all ports tried — none available (last: ${code ?? "unknown"} on ${host}:${port})`
+    : String(err?.message ?? err ?? "listen failed");
+  const hint = listenHint(code, { host, port, platform });
+  const out = new Error(hint ? `${head} — ${hint}` : head);
+  if (code !== undefined) out.code = code;
+  if (err) out.cause = err;
+  return out;
+}
+
 // Set from startServer's options. The server cannot restart itself — the
 // process lifecycle belongs to the supervisor in bin/agent-dag.js, which is the
 // only thing that can bring a replacement up on the same port without racing
@@ -3217,6 +3388,31 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
     if (req.method === "POST" && url.pathname === "/api/clear") {
       events.length = 0;
       if (persistPath) truncate(persistPath, 0).catch(() => {});
+      // Drop the caches that gate an emit on "has this changed", because the
+      // client is about to forget what they are comparing against: __clear makes
+      // the reducer return a fresh state, so every session's name and every
+      // subagent's model label go with it. maybeResolveSessionName then computes
+      // the same signature, takes its early return, and emits nothing — so the
+      // card falls back to cwd/prompt for the rest of that session while the
+      // server is sitting on the name.
+      //
+      // The root model survives without help because pushEvent stamps
+      // `raw.model` on every payload; there is no equivalent stamp for the name
+      // or for a subagent's model, which is why those two are listed and the
+      // rest of the per-session state is not.
+      //
+      // The rule, for the next cache that gates an emit: anything answering
+      // "has this changed" has to appear in BOTH places that mean the client no
+      // longer has it — here, and in forgetSession.
+      nameBySession.clear();
+      modelBySession.clear();
+      // The read stamps go with them. Clearing only the signatures would leave
+      // the next hook event inside MODEL_READ_THROTTLE_MS, so the transcript
+      // would not be re-read at all and the name would stay missing until the
+      // throttle expired — a clear followed by a keystroke is exactly when a
+      // user is watching.
+      lastNameReadAt.clear();
+      modelLastReadAt.clear();
       pushEvent({ hook_event_name: "__clear", cwd: "" }, "internal");
       return send(res, 200, { ok: true });
     }
@@ -3229,6 +3425,11 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
   const candidates = [port];
   for (let i = 0; i < 10; i++) candidates.push(randomPort(portRange[0], portRange[1]));
 
+  // The errno the exhaustion message ends up naming, and the port it happened
+  // on. Kept because the last candidate's reason is the only one still worth
+  // saying by then — the nine before it were random ports nobody asked for.
+  let lastErr = null;
+  let lastPort = port;
   for (const candidate of candidates) {
     try {
       await tryListen(server, candidate, host);
@@ -3241,11 +3442,17 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
       cswapAutoModule().then(m => m.initCswapAuto()).catch(() => {});
       return server;
     } catch (err) {
-      if (err && err.code === "EADDRINUSE") continue;
-      throw err;
+      lastErr = err;
+      lastPort = candidate;
+      // "This port is unavailable" — which Windows spells EACCES for a port
+      // inside a reserved exclusion range. See portRetryable.
+      if (portRetryable(err)) continue;
+      // Anything else is about the host or the socket, and the next candidate
+      // would fail identically. Say why instead of trying ten more times.
+      throw listenFailure(err, { host, port: candidate });
     }
   }
-  throw Object.assign(new Error(`all ports tried — none available`), { code: "EADDRINUSE" });
+  throw listenFailure(lastErr, { host, port: lastPort, exhausted: true });
 }
 
 // Allow running this file directly for dev (`npm run dev:server`). The port

package/src/server/installer.mjs

@@ -93,11 +93,17 @@ const LEGACY_DIRS = ["ccgraph", "agent-flow", "agent-dag"];
  * caller chose — and is quoted anyway, because that is not a property worth
  * re-deriving at every reading.
  *
- * Exported, with the node path injectable, so the escaping can be checked
- * against a path the test names rather than against whatever ran the suite.
+ * 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) {
-  const q = (s) => shellQuoteArg(s);
+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)}`;
 }
 
@@ -127,10 +133,6 @@ function stripBom(text) {
   return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
 }
 
-async function readJsonSafe(p) {
-  try { return JSON.parse(stripBom(await readFile(p, "utf8"))); } catch { return null; }
-}
-
 function unreadableSettings(p, why) {
   const err = new Error(
     `${p} could not be read as JSON (${why}). Refusing to overwrite it — ` +
@@ -138,6 +140,11 @@ function unreadableSettings(p, why) {
   );
   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;
 }
 
@@ -168,23 +175,48 @@ async function readSettingsForWrite(p) {
   return { settings: parsed, raw };
 }
 
-// Rename over an open file is the one thing Windows does differently here. The
-// call itself is atomic (MoveFileEx with MOVEFILE_REPLACE_EXISTING), but it
-// fails outright while another process holds the target open — and a virus
-// scanner or the search indexer opens files the instant they are written, for a
-// few milliseconds at a time. Retrying a sharing violation a handful of times
-// turns that into a successful install. POSIX never hits this path, and a real
-// permission error just costs an extra fraction of a second before it surfaces.
+// 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 = 5) {
+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;
-      await delay(20 * attempt);
+      // 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);
     }
   }
 }
@@ -334,6 +366,29 @@ 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.
+  //
+  // 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
@@ -342,14 +397,63 @@ 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);
-  return { settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider, changed };
+  // 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}`);
-  const current = await readJsonSafe(cfg.settingsPath);
-  if (!current?.hooks) return { changed: false, 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]);
@@ -358,7 +462,7 @@ export async function uninstallHooks({ provider = "claude" } = {}) {
     else current.hooks[evt] = cleaned;
   }
   if (changed) await writeFileAtomic(cfg.settingsPath, JSON.stringify(current, null, 2) + "\n");
-  return { changed, provider, settingsPath: cfg.settingsPath };
+  return { ok: true, changed, provider, settingsPath: cfg.settingsPath };
 }
 
 /** True when ~/.codex/ exists — the CLI's default answer to whether the Codex
@@ -494,6 +598,20 @@ export async function ensureDiscovery({ port, workspace, token, persist = null,
  * 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
@@ -527,7 +645,12 @@ export function keepDiscovery({ port, workspace, token, persist = null, codex =
   const timer = setInterval(() => { check(); }, intervalMs);
   timer.unref?.();
 
-  return { file: discoveryPath(), check, stop: () => clearInterval(timer) };
+  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

package/src/server/invoked-as.mjs

@@ -1,11 +1,11 @@
 // Which of the three published commands the user typed — and nothing else.
 //
-// The deck is on npm three times over: `agents-deck` (what this repo publishes),
-// `agent-dag` (the same tarball under the name it shipped as first) and
-// `ccdeck` (a stub that depends on agents-deck and spawns its bin). Every
-// surface a human reads says ccdeck now, and 95% of the downloads are still on
-// the other two, so nothing closes that split on its own. This file is the
-// evidence behind saying so — once in the terminal, once in the browser.
+// The deck is on npm three times over — `ccdeck`, `agents-deck` and `agent-dag`
+// — and since #340 all three are literally the same tarball, published with
+// `name` set to each in turn. Every surface a human reads says ccdeck now, and
+// most of the downloads are still on the other two, so nothing closes that split
+// on its own. This file is the evidence behind saying so — once in the terminal,
+// once in the browser.
 //
 // Two rules make that safe, and they are the whole of the file.
 //
@@ -15,13 +15,15 @@
 // dead on the one machine where the deck was the thing that would have
 // explained why.
 //
-// And it is never asked of the PACKAGE. `ccdeck/package.json` depends on
-// `agents-deck`, and `ccdeck/bin/ccdeck.js` spawns
-// `../../agents-deck/bin/agent-dag.js` — so "is this build agents-deck?" is
-// true inside every ccdeck run, and a notice keyed on it would scold exactly
-// the people who did what we asked. The question is which name the USER TYPED.
-// That is a different question, with a different answer, and on one platform
-// with no answer at all:
+// And it is never asked of the PACKAGE. That was unarguable while ccdeck was a
+// stub — it depended on `agents-deck` and spawned its bin, so "is this build
+// agents-deck?" was true inside every ccdeck run, and a notice keyed on it would
+// have scolded exactly the people who did what we asked. #340 removed the stub
+// and the rule outlived it, because the three names are now ONE tarball: asking
+// the package what it is gets you whichever name the publish step happened to
+// set last, which is not evidence about the user at all. The question is which
+// name the USER TYPED. That is a different question, with a different answer,
+// and on one platform with no answer at all:
 //
 //   npx, everywhere — npm writes the literal spec into
 //     `_npx/<hash>/package.json` as `_npx.packages`, which npxRestartSpec
@@ -37,7 +39,7 @@
 //
 //   a global install on Windows — nowhere. npm writes <name>.cmd, <name>.ps1
 //     and an extensionless sh shim, each of which runs
-//     `node "…\node_modules\agents-deck\bin\agent-dag.js" %*` (npm's cmd-shim).
+//     `node "…\node_modules\<pkg>\bin\agent-dag.js" %*` (npm's cmd-shim).
 //     The typed name is the shim's FILENAME and never becomes an argument, and
 //     there is no other carrier — npm_config_user_agent and friends are not set
 //     for a direct bin invocation. So Windows answers null.