agent-dag 1.43.0 → 1.44.1

package/src/server/exec.mjs

@@ -340,13 +340,40 @@ export const tryNext = (err) =>
   Boolean(err) && (err.code === "ENOENT" || err.code === "EACCES" ||
                    err.code === "EINVAL" || err.code === "UNKNOWN");
 
-// The three lines cmd.exe prints when it cannot find what it was asked to run,
-// anchored to a whole line each. First the two-line pair for a bare name, then
-// the one it uses when a directory in an explicit path does not exist.
+// The three lines an ENGLISH cmd.exe prints when it cannot find what it was
+// asked to run, anchored to a whole line each. First the two-line pair for a
+// bare name, then the one it uses when a directory in an explicit path does not
+// exist.
+//
+// These are one signal out of three rather than the whole answer — see
+// looksMissing. Windows ships cmd.exe in every language it ships in, and these
+// sentences are translated with it.
 const CMD_UNKNOWN = /^'(.+)' is not recognized as an internal or external command,?$/i;
 const CMD_UNKNOWN_TAIL = /^operable program or batch file\.?$/i;
 const CMD_NO_PATH = /^the system cannot find the (?:path|file) specified\.?$/i;
 
+// cmd.exe's own errorlevel for a command token it could not resolve — the one
+// signal here that is not a human sentence, and therefore the only one that is
+// the same on a German install as on an English one. It is the number every CI
+// log in the world prints beside "is not recognized".
+//
+// Not every path reports it: some Windows builds answer a bare `cmd /c missing`
+// with a plain 1 instead, which is why this is a sufficient signal and never a
+// necessary one. A number this large cannot arrive from POSIX at all — a process
+// exit status there is masked to 0-255 before Node ever sees it — so nothing
+// outside cmd.exe can reach it by accident.
+const CMD_NOT_FOUND_EXIT = 9009;
+
+/** True when an exit status is cmd.exe saying "no such command", in any locale. */
+export const notFoundExit = (code) => Number(code) === CMD_NOT_FOUND_EXIT;
+
+// Every run of text this line wrapped in quotes. cmd.exe quotes the command
+// token it could not find in EVERY locale, and the quote character is the only
+// part of the message that is not a translation: `'…'` in English and French,
+// `"…"` in German, Spanish, Italian, Portuguese, Polish and Russian.
+const quotedRuns = (line) =>
+  [...String(line).matchAll(/'([^']+)'|"([^"]+)"/g)].map(m => m[1] ?? m[2]);
+
 // cmd.exe echoes the command token exactly as it was given, so an exact match
 // is what we expect; the comparison is only case- and quote-insensitive because
 // Windows paths are.
@@ -409,20 +436,108 @@ const sameCommand = (quoted, name) => {
  *
  * Callers that only have the text (failureText) omit it and get the shape rules
  * alone.
+ *
+ * ── AND NOT ONLY IN ENGLISH (#552) ──────────────────────────────────────────
+ *
+ * Everything above was written against three English sentences, and cmd.exe is
+ * translated. On a German install with cswap genuinely absent it prints
+ *
+ *     Der Befehl "cswap" ist entweder falsch geschrieben oder konnte nicht
+ *     gefunden werden.
+ *
+ * — so this answered false, `run` resolved `{ ok: false, code: 1 }`,
+ * claude-accounts.mjs picked `reason: "switch_failed"` over `"no_cswap"` and the
+ * panel's install affordance never appeared. failureText then fell through to
+ * firstUseful, which puts the LAST line of a localized sentence on screen by
+ * itself: #457's symptom reproduced for every non-English locale. It also
+ * stopped the candidate loop early, so a `.bat` installed after a missing `.cmd`
+ * was never reached.
+ *
+ * Adding the German sentence, and then the French and the Japanese ones, is not
+ * a fix — it is the same defect with a longer list. So two signals that are not
+ * sentences carry the answer instead, and the English text is what remains when
+ * neither is available:
+ *
+ *   1. THE EXIT STATUS. `exitCode` 9009 is cmd.exe's own errorlevel for a
+ *      command token it could not resolve, identical in every language. See
+ *      CMD_NOT_FOUND_EXIT for why it is not required, and the paragraph below
+ *      for the two cases where it is not believed either. It is subject to the
+ *      same "cmd.exe printed nothing else" cap as rule 2, because a status is
+ *      forwarded as easily as a sentence is.
+ *
+ *   2. THE SHAPE. cmd.exe quotes the command it could not find, in every locale,
+ *      and prints that INSTEAD of running anything — so the whole output is at
+ *      most the two lines of one wrapped sentence. Text of at most two lines
+ *      whose FIRST line quotes exactly the spelling we launched is cmd.exe's
+ *      verdict about our command whatever the words around it say.
+ *
+ * Rule 2 needs `name`, and refuses without it. That is the same principle the
+ * paragraphs above argue for and not a limitation bolted on: `Error: "account-9"
+ * does not exist` is one line with a quoted token in it, and read as an absence
+ * it would send the candidate loop back round to re-run `cswap remove 3`. What
+ * makes the rule safe is that the quoted token has to be the exact spelling
+ * cmd.exe was handed — `cswap.cmd`, or the absolute path shimPath found — which
+ * is a string the tool underneath has no reason to print. The two-line cap is
+ * the other half: a Python traceback ending in "The system cannot find the file
+ * specified" is four lines and can never qualify.
+ *
+ * THE SAME TRAP THE ENGLISH RULE ALREADY AVOIDS, NOW FOR THE EXIT STATUS. A
+ * `.cmd` shim is itself a batch file, so a shim that EXISTS and whose payload
+ * interpreter does not — a scoop or npm-style `cswap.cmd` in front of a python
+ * that was uninstalled — has cmd.exe print "is not recognized" about PYTHON and
+ * hands the shim's caller that same 9009. Believed on its own, the deck would
+ * call the tool absent and re-run the command under the next spelling. So a text
+ * that positively names a command OTHER than ours vetoes every rule here,
+ * including the status: the check that made #457 safe, applied one level up.
+ *
+ * What is deliberately still missed: a LOCALIZED "the system cannot find the
+ * path specified", which carries no quoted token and no structure to key off.
+ * That case only arises when shimPath found a shim that then vanished, and it
+ * fails in the safe direction — an honest exit 1 rather than a wrong ENOENT.
  */
-export function looksMissing(text, name = "") {
+export function looksMissing(text, name = "", exitCode = null) {
   const lines = String(text ?? "").split(/\r?\n/).map(l => l.trim()).filter(Boolean);
+  // Whatever cmd.exe named, in whatever language it said the rest — the quoting
+  // is the part that is not a translation.
+  const named = lines.length ? quotedRuns(lines[0]) : [];
+  const namesUs = named.some(q => sameCommand(q, name));
+
+  // The veto, before anything is believed: a message about somebody else's
+  // command is not evidence about ours, and neither is the status that came
+  // with it. See the header — a `.cmd` shim in front of a missing interpreter
+  // forwards both.
+  if (name && named.length > 0 && !namesUs) return false;
+
+  // cmd.exe says this INSTEAD of running anything, so anything longer than one
+  // wrapped sentence came from something that DID run — and that outranks both
+  // signals below. A shim can forward its child's 9009 after printing pages of
+  // its own; a Python traceback is four lines and one of them quotes the very
+  // shim we launched.
+  const saidNothingElse = lines.length <= 2;
+
+  // The signal that is not a sentence. It does not need to READ the text, which
+  // is the whole reason it exists: on a non-English install there may be nothing
+  // in the text this can read.
+  if (saidNothingElse && notFoundExit(exitCode)) return true;
   if (!lines.length) return false;
+
+  // The English shapes, whole-line anchored, exactly as before.
+  let english = true;
   for (const line of lines) {
-    const named = CMD_UNKNOWN.exec(line);
-    if (named) {
-      if (name && !sameCommand(named[1], name)) return false;
+    const unknown = CMD_UNKNOWN.exec(line);
+    if (unknown) {
+      if (name && !sameCommand(unknown[1], name)) return false;
       continue;
     }
     if (CMD_UNKNOWN_TAIL.test(line) || CMD_NO_PATH.test(line)) continue;
-    return false;
+    english = false;
+    break;
   }
-  return true;
+  if (english) return true;
+
+  // Otherwise: cmd.exe in some other language, recognised by its shape and by
+  // the one word in it that is ours.
+  return Boolean(name) && saidNothingElse && namesUs;
 }
 
 // How much of a hung child's output the deadline keeps. The full buffers belong
@@ -485,7 +600,11 @@ export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20, env } =
         // be a shell's verdict rather than the tool's own words — spawned
         // directly, a missing file is a plain ENOENT and anything printed came
         // from a tool that ran.
-        const missing = Boolean(err) && tree && looksMissing(`${stderr ?? ""}\n${stdout ?? ""}`, launch);
+        // `err.code` is the exit STATUS for a child that ran and failed, which
+        // is where cmd.exe's language-independent 9009 arrives; for a spawn
+        // failure it is an errno string, and Number() of that is NaN. Either
+        // way looksMissing is handed what the attempt actually reported.
+        const missing = Boolean(err) && tree && looksMissing(`${stderr ?? ""}\n${stdout ?? ""}`, launch, err.code);
         if (err && (tryNext(err) || missing) && i + 1 < tries.length) return attempt(i + 1);
         // The CANDIDATE is what gets remembered, never the resolved path. The
         // memo is the only entry `candidates` offers afterwards, so recording an
@@ -663,7 +782,7 @@ export function runInteractive(cmd, args, { timeout = 300_000, maxOutput = 256 <
       // batch candidate, which is the only kind launched through a shell, and
       // to output that is cmd.exe's message alone — everything below re-runs
       // the whole command, and these commands remove accounts.
-      if (code !== 0 && isBatch(raw) && looksMissing(`${stderr}\n${stdout}`, launch)) {
+      if (code !== 0 && isBatch(raw) && looksMissing(`${stderr}\n${stdout}`, launch, code)) {
         if (i + 1 < tries.length) {
           stdout = ""; stderr = ""; pending = "";
           child = null;

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

@@ -133,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 — ` +
@@ -144,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;
 }
 
@@ -365,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
@@ -373,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]);
@@ -389,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