agent-dag 3.2.1 → 3.4.0

package/src/server/codex-usage.mjs

@@ -201,11 +201,33 @@ async function readCompressedTokenSeries(filePath) {
     }
     return null;
   }
+  // THE SOURCE IS HELD, and both halves of that matter.
+  //
+  // `Readable.pipe` attaches its error handling to the DESTINATION. The source
+  // got neither an 'error' listener nor a destroy, so a read that failed — the
+  // file removed between the listing and this call, EACCES, EMFILE — emitted
+  // an unhandled 'error' and took the process down, in a reader whose
+  // uncompressed twin deliberately survives those same errnos. A torn archive
+  // errors on the destination instead, which the catch below swallows while the
+  // source stays open: twenty reads of one corrupt file left twenty handles,
+  // against a sixty-second poll. On Windows a held handle also blocks the
+  // unlink, which is the case the plain path's `finally { await fd?.close() }`
+  // names.
+  let source = null;
   try {
     const series = [];
     const decoder = new StringDecoder("utf8");
     let pending = "";
-    const stream = createReadStream(filePath).pipe(createZstdDecompress());
+    source = createReadStream(filePath);
+    const stream = source.pipe(createZstdDecompress());
+    // THE ERROR HAS TO REACH THE LOOP, not merely be caught. A bare
+    // `on("error", () => {})` here stops the process dying and hangs the read
+    // instead: `pipe` does not forward a source failure to the destination, so
+    // the `for await` below waits forever for an 'end' that cannot come — which
+    // is what a missing file did on the first Windows run of this code, at 30
+    // seconds per poll. Destroying the destination WITH the error makes the
+    // iteration reject, which is what the catch is for.
+    source.on("error", err => { stream.destroy(err); });
     for await (const chunk of stream) {
       pending += decoder.write(chunk);
       let from = 0;
@@ -220,6 +242,7 @@ async function readCompressedTokenSeries(filePath) {
     if (pending) foldTokenLine(series, pending);
     return series.length ? series : null;
   } catch { return null; }
+  finally { source?.destroy(); }
 }
 
 /** The reader, exported under a test-only name. The compressed path cannot be

package/src/server/cswap-admin.mjs

@@ -986,20 +986,6 @@ export async function shareAccounts(nums) {
   };
 }
 
-/**
- * The one-account case, which is a bundle of one and takes the same path.
- *
- * That path PARSES what cswap wrote, where this used to hand its stdout on
- * opaquely — the cost of `shared` being able to promise that the count on the
- * copy button is the count in the blob. So an export shape the fold cannot read
- * now fails the single share too, not just the bundle. Deliberate: one path
- * means the two cannot drift into two envelope shapes, and a share that
- * silently carried something this deck could not account for is the failure
- * the count exists to prevent.
- */
-export async function shareAccount(num) {
-  return shareAccounts([num]);
-}
 
 /**
  * The identities a bundle carries, or `[]` when it cannot be read.

package/src/server/cswap-auto.mjs

@@ -229,7 +229,13 @@ const MODEL_LIST_OK = /^(?!-)[A-Za-z0-9 ,._-]{1,120}$/;
 
 /** Validate against SETTINGS, then hand to `cswap config set`. */
 export async function setCswapConfig(key, value) {
-  const spec = SETTINGS[key];
+  // `Object.hasOwn`, not a bare read. `SETTINGS["constructor"]` is truthy and
+  // its `.type` is undefined, so a prototype member passed the allowlist and
+  // fell through to the free-text branch — reaching `cswap config set
+  // constructor <value>` and skipping the type-specific range check on the way.
+  // Nothing reachable that way was dangerous; an allowlist that does not hold
+  // is.
+  const spec = Object.hasOwn(SETTINGS, key) ? SETTINGS[key] : null;
   if (!spec) return { ok: false, reason: "unknown_setting" };
 
   let str;
@@ -253,6 +259,17 @@ export async function setCswapConfig(key, value) {
   // nothing. The panel reloads this route immediately afterwards and gets a real
   // read; see invalidateCswapAutoCache.
   invalidateCswapAutoCache();
+  // A NEW INTERVAL HAS TO REACH THE TIMER. `tickInterval()` is read once, at
+  // startLoop, so changing this setting used to update what the panel reports
+  // and nothing else: set 3600 with auto-switch on and the panel read back an
+  // hour while the loop kept firing every sixty seconds for the life of the
+  // process — sixty `cswap auto --once` spawns an hour instead of one, against
+  // the shared per-account request budget this subsystem exists to protect.
+  // Lowering it was equally inert.
+  if (r.ok && key === "autoswitch.intervalSeconds" && _enabled) {
+    stopLoop();
+    await startLoop();
+  }
   return r.ok ? { ok: true } : { ok: false, reason: "set_failed", detail: (r.stderr || r.stdout).trim().slice(0, 300) };
 }
 
@@ -291,6 +308,15 @@ function summarise(stdout) {
 /** Evaluate a tick for real. May switch the active account. */
 async function runAutoTick() {
   const r = await run(await cswapBin(), ["auto", "--once", "--json"], { timeout: TICK_TIMEOUT_MS });
+  // A KILLED RUN IS NOT A QUIET ONE. `run`'s timeout path deliberately keeps an
+  // 8 KB tail of whatever the child managed to print, so `!r.ok && !r.stdout`
+  // is false for a tick that emitted its `{"event":"poll"}` line and then
+  // stalled — and the killed run fell through to `ok: true`. The panel then
+  // showed a healthy `no-switch` every two minutes, forever, while the engine
+  // did nothing at all: exactly the trap exec.mjs's own header names.
+  if (r.timedOut) {
+    return { ok: false, reason: "tick_timeout", detail: `cswap auto --once did not finish within ${TICK_TIMEOUT_MS / 1000}s` };
+  }
   if (!r.ok && !r.stdout) {
     return { ok: false, reason: "tick_failed", detail: (r.stderr || "").trim().slice(0, 300) };
   }
@@ -477,6 +503,18 @@ async function runTick() {
     _lastTick = { at: Date.now(), event: "skipped", reason: "external-engine" };
     return;
   }
+  // AND RE-CHECK THE SWITCH ITSELF, after that await. `stopLoop` clears the
+  // interval and nothing else, so a tick already running went on to move the
+  // user's live account seconds after the panel had drawn itself as off. The
+  // await above is not short: ticks are at least fifteen seconds apart against
+  // a ten-second floor, so every one pays a real process-table read — on
+  // Windows a PowerShell Get-CimInstance with an eight-second deadline. The
+  // panel then showed `enabled: false` beside a `lastTick` of
+  // `{event: "switch", from, to}` stamped after the user turned it off.
+  if (!_enabled) {
+    _lastTick = { at: Date.now(), event: "skipped", reason: "disabled" };
+    return;
+  }
   const result = await runAutoTick();
   // Before `_lastTick`, not after. This is the only path in the deck that moves
   // the live account without a click behind it, so nothing else is in a position

package/src/server/cswap-install.mjs

@@ -597,8 +597,13 @@ export async function ensureCswap({ onInstalling = null } = {}) {
     // Installed — the only question left is whether it's stale. One PyPI
     // request a day, and the upgrade itself never blocks startup.
     if (!updateCheckDue()) return { state: "present", version: existing };
-    touchMarker();
+    // The marker is stamped AFTER the request, not before it. Stamped first, a
+    // boot with no network yet — a laptop opened on a train, the ten seconds
+    // before Wi-Fi associates — burned the whole shared 24-hour window on a
+    // check that never reached PyPI, and the next real chance was the day
+    // after. self-update.mjs states this rule for itself in as many words.
     const latest = await latestOnPypi();
+    touchMarker();
     if (latest && existing !== "installed" && isOlder(existing, latest)) {
       // Who owns it, not what is installed on the machine: an upgrade aimed at
       // a tool that never installed this package is refused where runDetached

package/src/server/exec.mjs

@@ -28,6 +28,30 @@
 import { execFile, spawn } from "node:child_process";
 import { existsSync } from "node:fs";
 
+// WINDOWS SEARCHES THE WORKING DIRECTORY FIRST, and this turns that off.
+//
+// libuv's PATH search calls `NeedCurrentDirectoryForExePathW("")`, which is
+// true unless this variable is set — so `spawn("cswap", …)` on Windows tries
+// `.\cswap.exe` before anything on PATH, and the deck's working directory is
+// wherever `npx ccdeck` was run: normally the user's project, often a repo they
+// just cloned. `cswapBin()` probes the bare name before any known install path
+// and memoises whatever answered, so a planted binary would then receive every
+// later `cswap switch` and `cswap export -` — the commands that carry account
+// credentials. The same search reaches py.exe, where.exe, claude.exe and
+// powershell.exe.
+//
+// Set on this process rather than per spawn, because the search is done by the
+// PARENT: one assignment covers every child this deck ever starts, including
+// the ones spawned outside this module. An explicit value in the environment is
+// left alone — someone who set it meant it.
+//
+// POSIX never had this behaviour: execvp does not search `.` unless PATH says
+// so, so this is a no-op there and is skipped rather than written.
+if (process.platform === "win32" && !("NoDefaultCurrentDirectoryInExePath" in process.env)) {
+  process.env.NoDefaultCurrentDirectoryInExePath = "1";
+}
+
+
 // Extensions Windows will execute, most specific first. `.com` is omitted —
 // nothing ships one, and every extra candidate costs a failed spawn.
 const WIN_EXTS = [".exe", ".cmd", ".bat", ""];
@@ -682,6 +706,12 @@ export function run(cmd, args, { timeout = 20_000, maxBuffer = 4 << 20, env } =
         // the shell command it replaced had to end in `< /dev/null`. Closing
         // the pipe is that redirection without a shell to parse it.
         try { cp.stdin?.on("error", () => {}); cp.stdin?.end(); } catch { /* no stdin to close */ }
+        // Decoded as a stream rather than per chunk: a chunk boundary falls
+        // wherever the pipe broke, and a multi-byte character split across two
+        // of them becomes two replacement characters in the tail this keeps for
+        // the timeout message.
+        cp.stdout?.setEncoding?.("utf8");
+        cp.stderr?.setEncoding?.("utf8");
         cp.stdout?.on("data", (d) => { sawOut = (sawOut + d).slice(-TIMEOUT_TAIL); });
         cp.stderr?.on("data", (d) => { sawErr = (sawErr + d).slice(-TIMEOUT_TAIL); });
         // The deadline states the outcome itself and only then kills, which is
@@ -814,6 +844,15 @@ export function runInteractive(cmd, args, { timeout = 300_000, maxOutput = 256 <
       return tryNext(err) ? attempt(i + 1) : finish(-1, err);
     }
     child = proc;
+    // EPIPE ON STDIN IS NOT A CRASH. `write` below is wrapped in a try/catch,
+    // and that catch can never fire for the case that matters: a broken pipe
+    // arrives asynchronously, as an 'error' event on the Writable, and an
+    // unhandled 'error' on a stream is an uncaught exception with no
+    // process-level net anywhere in this deck. `cswap import -` reading a
+    // prefix of a bad bundle and exiting before it drains is exactly that
+    // shape, so a rejected paste in the import dialog took the dashboard down
+    // with it. `run` has carried this same line since it was written.
+    proc.stdin?.on("error", () => {});
     // A spelling that fails to spawn emits 'error' AND THEN 'close' — with code
     // -2 after an ENOENT. Once the error handler has moved on to the next
     // candidate, that trailing 'close' is news about a child nobody is waiting
@@ -845,6 +884,11 @@ export function runInteractive(cmd, args, { timeout = 300_000, maxOutput = 256 <
     // Capped so a runaway child cannot grow the heap without bound; the tail is
     // what carries the error, so the head is what gets dropped.
     const keep = (buf, text) => (buf + text).slice(-maxOutput);
+    // Same reason as `run`'s tails: the login prompt this reader is waiting for
+    // arrives mid-chunk, and a UTF-8 sequence cut by a pipe boundary must not
+    // become two replacement characters in the line it emits.
+    proc.stdout?.setEncoding?.("utf8");
+    proc.stderr?.setEncoding?.("utf8");
     proc.stdout?.on("data", (d) => { if (stale()) return; const t = String(d); stdout = keep(stdout, t); emitLines(t); });
     proc.stderr?.on("data", (d) => { if (stale()) return; const t = String(d); stderr = keep(stderr, t); emitLines(t); });
     proc.on("close", (code) => {

package/src/server/index.mjs

@@ -662,7 +662,7 @@ export const MAX_SCAN_CHUNK = 8 * 1024 * 1024;
 // pointing one POST at something arbitrarily large: the read still terminates,
 // the cursor keeps whatever it reached, and the next throttled pass continues
 // from there.
-export const MAX_SCAN_BYTES_PER_PASS = 256 * 1024 * 1024;
+const MAX_SCAN_BYTES_PER_PASS = 256 * 1024 * 1024;
 
 const NEWLINE = 0x0a;
 
@@ -1458,7 +1458,7 @@ const pendingNameReads = new Set();     // sid currently being read
 /** The naming the cursor has folded so far, or null when the scan has nothing.
  *  Exported beside readContextFromTranscript for the same reason: the rule is
  *  worth pinning directly rather than through a live server. */
-export async function readSessionNamingFromTranscript(path) {
+async function readSessionNamingFromTranscript(path) {
   const state = await scanTranscript(path);
   if (!state) return null;
   if (!state.agentName && !state.aiTitle) return null;
@@ -3470,7 +3470,13 @@ export function replayScope(workspace, platform = process.platform) {
  * that case cheap needs an index of where a workspace's lines are, which is a
  * different change from this one.
  */
-async function replayLog(filePath, workspace = "") {
+/* Exported for the suite, with both ceilings as parameters. The byte budget is
+ * 128 MiB, so a test that wanted to reach it honestly would have to write 128
+ * MiB — which is why the count bound was the only one anything pinned, and why
+ * the byte bound was the one that broke. Production passes neither argument. */
+export async function replayLog(filePath, workspace = "", {
+  maxEvents = MAX_BUFFER, maxChars = MAX_BUFFER_CHARS,
+} = {}) {
   if (!existsSync(filePath)) return 0;
   let skipped = 0;
   let skippedBytes = 0;
@@ -3499,17 +3505,32 @@ async function replayLog(filePath, workspace = "") {
     }
   } else {
     // Newest first, so this is filled back to front and then walked in reverse
-    // to push. Bounded by MAX_BUFFER, which is what makes the memory here a
-    // property of the ring rather than of the file.
+    // to push. Bounded by BOTH of the ring's limits, which is what makes the
+    // memory here a property of the ring rather than of the file.
+    //
+    // The count alone was not enough, and the comment that used to say it was
+    // predates #625. Eviction is the only thing that applies MAX_BUFFER_CHARS,
+    // and eviction happens inside pushEvent — which does not run until this
+    // array is already full. Measured on a 187 MB log of 40 events of 4.9M
+    // characters each, every one of them under the ingest cap: RSS went from
+    // 215 MB to a peak of 505 MB, and the ring that survived held 27 events and
+    // 126 MiB. About 290 MB staged for a ring capped at 128.
+    //
+    // Rotation at 50 MB normally keeps logs well under this, but rotation is
+    // best-effort and its failure is only logged, and this file's own header
+    // records logs reaching gigabytes.
     const newestFirst = [];
+    let stagedChars = 0;
     for await (const line of linesFromEnd(filePath)) {
       if (!line) continue;
       const evt = parse(line);
       if (!usable(evt) || !admits(evt.payload)) continue;
       newestFirst.push(evt);
+      stagedChars += ENVELOPE_CHARS + payloadChars(evt.payload);
       // Everything older than this would be evicted by the events already held,
       // so reading further is work whose only result is throwing it away.
-      if (newestFirst.length >= MAX_BUFFER) break;
+      // Either limit reaching its ceiling means exactly that.
+      if (newestFirst.length >= maxEvents || stagedChars >= maxChars) break;
     }
     for (let i = newestFirst.length - 1; i >= 0; i--) replay(newestFirst[i]);
     count = newestFirst.length;
@@ -4116,7 +4137,7 @@ async function handleBrowserWatchSettings(req, res) {
   try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
   if (!body || typeof body !== "object") return send(res, 400, { ok: false, reason: "bad_request" });
 
-  const { readStore, writeStore, normalise } = await import(
+  const { readStore, updateStore, normalise } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/browser-watch-store.mjs")).href
   );
   const { invalidateBrowserWatchCache, noteWatchSetting } = await import(
@@ -4132,7 +4153,11 @@ async function handleBrowserWatchSettings(req, res) {
   // this field ERASES it. Measured — changing the reaction wiped every
   // dismissal, so every episode the reader had reviewed came straight back on
   // the next poll, from a settings change that had nothing to do with them.
-  await writeStore({ settings, episodes: store.episodes, dismissed: store.dismissed });
+  // Only the settings are this route's to change. `updateStore` re-reads inside
+  // the write queue, so a poll that landed between the read above and this line
+  // cannot have its archive thrown away by a settings change — which is what
+  // writing a whole state read seconds earlier used to do.
+  await updateStore(cur => ({ ...cur, settings }));
   // The one line in the log that is somebody acting rather than the deck
   // reading, which is exactly why it is worth its own entry.
   if (settings.enabled !== store.settings.enabled) {
@@ -4168,7 +4193,7 @@ async function handleBrowserWatchDismiss(req, res) {
   const startMs = typeof body?.startMs === "number" && Number.isFinite(body.startMs) ? body.startMs : null;
   if (host === null || startMs === null) return send(res, 400, { ok: false, reason: "bad_request" });
 
-  const { readStore, writeStore, episodeKey } = await import(
+  const { readStore, updateStore, episodeKey } = await import(
     pathToFileURL(join(PKG_ROOT, "src/server/browser-watch-store.mjs")).href
   );
   const { invalidateBrowserWatchCache, noteWatchSetting } = await import(
@@ -4177,7 +4202,7 @@ async function handleBrowserWatchDismiss(req, res) {
   const store = await readStore();
   const key = episodeKey(host, startMs);
   const dismissed = [...new Set([...(store.dismissed ?? []), key])];
-  await writeStore({ settings: store.settings, episodes: store.episodes, dismissed });
+  await updateStore(cur => ({ ...cur, dismissed }));
   // The reader acting on their own list, which is exactly the kind of line the
   // `act` level exists for.
   noteWatchSetting(`dismissed ${host}`);
@@ -4188,6 +4213,12 @@ async function handleBrowserWatchDismiss(req, res) {
 async function handleBrowserWatch(req, res) {
   const url = new URL(req.url, "http://localhost");
   const force = url.searchParams.get("refresh") === "1";
+  // `live=0` is the badge's five-minute poll saying "the archive is enough".
+  // With the watch OFF that is honoured and no browser is read at all — see
+  // browserWatchSnapshot: the switch used to gate only what was KEPT, so a deck
+  // nobody had switched on still copied every History database every five
+  // minutes. A forced read overrides it, because that is the user pressing ↻.
+  const readBrowsers = force || url.searchParams.get("live") !== "0";
 
   // Numbers from a query string are refused rather than coerced: NaN would
   // silently widen the quiet gate to "everything counts", which is the failure
@@ -4217,6 +4248,7 @@ async function handleBrowserWatch(req, res) {
   const ports = await registeredDeckPorts();
   return send(res, 200, await fetchBrowserWatch({
     force,
+    readBrowsers,
     deckOrigins: deckOwnOrigins(undefined, ports),
     quietMs: minutes("quiet"),
     gapMs: minutes("gap"),
@@ -4676,9 +4708,19 @@ function handleHookChallenge(_req, res, url) {
   send(res, 200, { proof: challengeProof(HOOK_TOKEN, nonce) });
 }
 
+// Signal 0 delivers nothing; it asks whether the pid could be signalled.
+//
+// BOTH ERRNOS, and the second one is the Windows spelling. POSIX `kill(2)`
+// answers EPERM for a process this account may not signal. On Windows
+// `uv_kill` calls `OpenProcess`, a denial is ERROR_ACCESS_DENIED, and libuv
+// maps that to EACCES — so a deck started from an elevated terminal, or under
+// another account, read as DEAD to every probe in this repo. What followed was
+// silent: the live deck's discovery file was unlinked on the next hook fire,
+// rewritten five seconds later by keepDiscovery, and its banner went on
+// claiming it was receiving events it had stopped receiving.
 function isProcessAlive(pid) {
   try { process.kill(pid, 0); return true; }
-  catch (e) { return e && e.code === "EPERM"; }
+  catch (e) { return !!e && (e.code === "EPERM" || e.code === "EACCES"); }
 }
 
 async function sweepStaleDiscovery() {
@@ -4990,6 +5032,72 @@ function isDeckUiRequest({ origin, host, secFetchSite } = {}) {
 // presents nothing at all no longer changes anything — and what is opened is
 // the honest door, so a script of the user's own authenticates by reading the
 // token instead of impersonating a page.
+/**
+ * May this request read the deck's OWN data — the events, the accounts, the
+ * browsing episodes?
+ *
+ * The mutation gate exists because `curl -XPOST localhost:4317/…/admin` handed
+ * a live OAuth refresh token to a sandboxed subprocess with loopback egress.
+ * The same caller could still `curl localhost:4317/api/events` and read the
+ * whole ring — prompt text, the Bash command lines the agent ran, the paths and
+ * contents it wrote, the contents of every file it read back — plus the account
+ * roster and the browsing episodes. The threat model had been applied to half
+ * the surface.
+ *
+ * Same shape as isAuthorizedMutation, with one difference forced by the
+ * browser: a same-origin GET carries no `Origin` header at all, so the UI
+ * cannot be recognised the way a POST is. `Sec-Fetch-Site: same-origin` is what
+ * a page's own fetch and its EventSource both send, on every browser new enough
+ * to run this bundle, and it is a header no non-browser client sends by
+ * accident. A caller that sends neither it nor the token is not a page.
+ *
+ * WHAT STAYS OPEN, deliberately: /api/health (the hook's readiness probe),
+ * /api/hook-challenge (the handshake itself), the static files, and every
+ * measurement route — the machine panel's numbers are about the machine, not
+ * about what the user is doing on it.
+ */
+function isAuthorizedDataRead(req) {
+  const headers = req?.headers ?? {};
+  if (presentsDeckToken(headers)) return true;
+  // Addressed to this machine by a name that can only be this machine — so a
+  // rebound page, which also reports same-origin, does not qualify.
+  if (!isLoopbackHost(headers.host)) return false;
+
+  const site = typeof headers["sec-fetch-site"] === "string"
+    ? headers["sec-fetch-site"].trim().toLowerCase() : "";
+  if (site === "same-origin") return true;
+  // ANY FETCH METADATA AT ALL, AND IT SAID SOMETHING ELSE. `cross-site`,
+  // `same-site` and `none` are all a page that is not this one — or a top-level
+  // navigation typed into the address bar, which has no business reading the
+  // ring.
+  if (site !== "") return false;
+
+  // THE BROWSER THAT SENDS NO FETCH METADATA, and this is the whole reason this
+  // branch exists. Sec-Fetch-Site is Safari 16.4 and newer; Safari 16.0-16.3
+  // runs this bundle perfectly well (Vite's default target is Safari 16) and
+  // sends none of it. Without a fallback those users get an empty canvas and a
+  // 401 they cannot act on — an impediment for a browser that is otherwise
+  // fine.
+  //
+  // Referer is what they do send, on a page's own fetches and on its
+  // EventSource, and it must name THIS origin. A cross-site page's Referer
+  // names its own; a rebound page's names the attacker's host, which is not a
+  // loopback identity. It is forgeable by a non-browser client — and so is
+  // Sec-Fetch-Site, which curl sets as easily; neither is the control that
+  // stops a deliberate local caller. That control is the token, and this only
+  // decides which BROWSERS are recognised as the deck's own page.
+  return originMatchesHost(headers.referer, headers.host);
+}
+
+/** The reads that carry the user's own work, rather than the machine's. */
+const GUARDED_READS = new Set([
+  "/events",
+  "/api/events",
+  "/api/claude-accounts",
+  "/api/claude-accounts/login",
+  "/api/browser-watch",
+]);
+
 function isAuthorizedMutation(req) {
   const headers = req?.headers ?? {};
   if (presentsDeckToken(headers)) return true;
@@ -5200,6 +5308,14 @@ export async function startServer({ port = 4317, host = "127.0.0.1", persist = n
       return send(res, 401, { error: "unauthenticated" });
     }
 
+    // And the reads that carry the same secrets. See isAuthorizedDataRead: the
+    // gate above was written for a sandboxed subprocess with loopback egress,
+    // and that caller was reading the ring through a GET the whole time.
+    if ((req.method === "GET" || req.method === "HEAD")
+      && GUARDED_READS.has(url.pathname) && !isAuthorizedDataRead(req)) {
+      return send(res, 401, { error: "unauthenticated" });
+    }
+
     // `?persist=0` — another deck was elected to write this event to the log
     // the two of them share. Absent, this deck writes it.
     if (req.method === "POST" && url.pathname === "/api/event") return guard(handleEventIngest(req, res, url.searchParams.get("persist") !== "0"), res);

package/src/server/installer.mjs

@@ -353,7 +353,31 @@ async function writeFileAtomic(rawTarget, text) {
     // to stay 600. No-op on Windows, where chmod only toggles the read-only bit.
     const mode = await stat(target).then(s => s.mode, () => null);
     if (mode !== null) await chmod(tmp, mode).catch(() => {});
+    // A READ-ONLY TARGET IS A DEAD END ON WINDOWS, and only there. libuv's
+    // rename is one MoveFileExW(MOVEFILE_REPLACE_EXISTING), which refuses to
+    // replace a destination carrying FILE_ATTRIBUTE_READONLY; POSIX rename(2)
+    // over a 0444 file succeeds, because only the parent directory's write bit
+    // decides. A settings.json picks that attribute up from a OneDrive restore,
+    // a copy off a network share, or read-only media — and EACCES is in the
+    // retry ladder, so the whole ~1.4s was spent before throwing, on every
+    // boot, forever. Every settings writer goes through here, so hooks never
+    // installed and the sound-hook retirement could never repair a stale entry
+    // either.
+    //
+    // chmod on Windows toggles exactly that attribute and nothing else, which
+    // is why this is safe to do unconditionally there: the mode carried above
+    // is re-applied to the new file after the rename, so a file the user marked
+    // read-only stays read-only.
+    // ONLY WHEN THE TARGET IS ACTUALLY READ-ONLY. Two extra syscalls on the
+    // path between the temp write and the rename are not free on Windows:
+    // discovery-live.test.ts hammers writeDiscovery while a reader holds the
+    // destination open, and the wider window turned a rename the retry ladder
+    // used to win into an EPERM it gave up on. The attribute is what this
+    // clears, so a file that does not carry it has nothing to clear.
+    const readOnly = process.platform === "win32" && mode !== null && (mode & 0o200) === 0;
+    if (readOnly) await chmod(target, 0o666).catch(() => {});
     await renameWithRetry(tmp, target);
+    if (readOnly) await chmod(target, mode).catch(() => {});
   } catch (err) {
     // Cleanup covers the write and the fsync as well as the rename: a full disk
     // used to leave the half-written temp file sitting beside the target.
@@ -405,7 +429,7 @@ function dedupeOurEntries(group) {
 }
 
 /** Install hooks for a single provider. Returns {settingsPath, hookPath, events, changed}. */
-export async function installHooks({ provider = "claude" } = {}) {
+export async function installHooks({ provider = "claude", beforeWrite = null } = {}) {
   const cfg = PROVIDERS[provider];
   if (!cfg) throw new Error(`unknown provider: ${provider}`);
   // An uninstall-only provider has no event list. Saying so beats the
@@ -481,7 +505,38 @@ export async function installHooks({ provider = "claude" } = {}) {
   // 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);
+  if (changed) {
+    // COMPARE AGAINST THE FILE, NOT AGAINST THE SNAPSHOT, at the last moment.
+    //
+    // Everything above was computed from bytes read at the top of this
+    // function, and two decks booting together — the ordinary case on a machine
+    // where one was already running — interleave inside that window. The one
+    // that loses is unrecoverable rather than merely stale: deck A restores the
+    // user's own sound hooks from the parked file and deletes the park, and
+    // deck B then writes a settings object computed before that restore, with
+    // an empty park behind it. The user's hook is gone from settings.json and
+    // from the only other copy of it.
+    //
+    // So the file is re-read immediately before the write and, if another
+    // writer has touched it, this pass declines. Declining is safe by
+    // construction: every boot reinstalls, so the next one recomputes against
+    // the new bytes and converges — and the entries this function adds are
+    // identical on both decks, which is why the loser has nothing of its own to
+    // lose.
+    // The seam the suite needs, and the only way to test this deterministically:
+    // the window between the read at the top and the write below is filled with
+    // real fs work, so a test that raced it by wall clock would pass or fail by
+    // how fast the machine is. Production passes nothing.
+    if (beforeWrite) await beforeWrite();
+    const { raw: onDisk } = await readSettingsForWrite(cfg.settingsPath).catch(() => ({ raw: before }));
+    if (onDisk !== before) {
+      return {
+        settingsPath: cfg.settingsPath, hookPath, events: cfg.events, provider,
+        changed: false, raced: true, retire: { ...retire, pending: false },
+      };
+    }
+    await writeFileAtomic(cfg.settingsPath, next);
+  }
   // After the write, never before it: the notify script an older deck installed
   // is what a live session's cached command still names until the new entry is
   // on disk, and deleting it early turns a stale sound into a missing module.
@@ -773,4 +828,4 @@ export { AGENT_DAG_DIR, CLAUDE_DIR, CODEX_DIR };
 // repo for the same reasons settings.json is, and "never rename onto a link" is
 // one rule: codex-auth.mjs called a realpath of its own before this existed, and
 // two spellings of a rule are two things that can drift.
-export { readSettingsForWrite, writeFileAtomic, installScript, renameWithRetry, createTemp, resolveWriteTarget };
+export { readSettingsForWrite, writeFileAtomic, renameWithRetry, createTemp, resolveWriteTarget };

package/src/server/macmon.mjs

@@ -193,11 +193,6 @@ export function macmonAsset(release) {
   return { version: typeof tag === "string" ? tag : "unknown", url: a.browser_download_url, sha256: m[1] };
 }
 
-/** A macmon this function installed earlier, or null. */
-export function existingBootstrappedMacmon() {
-  const bin = join(MACMON_DIR, "macmon");
-  return existsSync(bin) ? bin : null;
-}
 
 /**
  * Download macmon into ~/.agents-deck/tools/macmon.
@@ -210,9 +205,25 @@ export function existingBootstrappedMacmon() {
  * ioreg and never reaches this file at all.
  */
 export async function bootstrapMacmon({
-  platform = process.platform, env = process.env, fetchFn = fetch, dir = MACMON_DIR,
+  platform = process.platform, arch = process.arch, env = process.env,
+  fetchFn = fetch, dir = MACMON_DIR, findBin = macmonBin,
 } = {}) {
   if (platform !== "darwin") return { ok: false, reason: "unsupported_platform" };
+  // ARM64 ONLY, checked rather than merely documented. The release publishes
+  // one asset and it is an arm64 Mach-O, so an Intel Mac downloaded 746 KB it
+  // could not execute and failed its own --version check afterwards. That is
+  // the small half. The larger half is the promise: the README says an Intel
+  // Mac never downloads anything, and this reached api.github.com on any Mac
+  // whose sensors happened to stay silent — which an Intel Mac's do whenever
+  // ioreg publishes no Temperature(C).
+  if (arch !== "arm64") return { ok: false, reason: "unsupported_arch" };
+  // A macmon the user already has is the other thing the README promises to
+  // notice, and until now the skip was emergent rather than checked: a working
+  // copy produces a reading, the reading sets thermalEverAnswered, and the
+  // give-up branch never fires. That chain breaks on a macmon which runs but
+  // reports values this deck rejects as implausible — and then a machine with
+  // macmon on PATH downloaded a second one.
+  if (await findBin()) return { ok: false, reason: "already_installed" };
   // Both switches, for the reason uv-bootstrap has both: downloading an
   // executable is a bigger step than installing a package with a tool the user
   // already chose, so somebody may want the managed installs and not this.

package/src/server/npx.mjs

@@ -194,7 +194,12 @@ export function npxPrefetch(spec, {
     timer.unref?.();
 
     child.on("error", err => settle({ ok: false, error: `could not run npx: ${err?.message ?? err}`, hint: null }));
-    child.on("exit", (code, signal) => {
+    // 'close' rather than 'exit': 'exit' fires when the process ends and says
+    // nothing about its pipes, so past one pipe buffer the tail this kept —
+    // deliberately the TAIL, because npm's reason is on its last lines — was
+    // still only the first 8 KiB when npxFailureSummary read it. 'close' is
+    // emitted after both streams have been drained.
+    child.on("close", (code, signal) => {
       if (code === 0) { settle({ ok: true, error: null, hint: null }); return; }
       settle({
         ok: false,

package/src/server/open-url.mjs

@@ -166,11 +166,31 @@ export function startCommand(url, env = process.env, comspec) {
  * it and `start` would run it.
  */
 export function isOpenable(url) {
+  return normalizeOpenable(url) !== null;
+}
+
+/**
+ * The address to actually hand the desktop, or null when it is not one.
+ *
+ * The guard used to parse into a local `u`, check its protocol and throw the
+ * parse away — so what reached `launchers` was the RAW string. `new URL()`
+ * accepts characters it normalizes only in `href`, a `"` among them, and on
+ * Windows `startCommand` builds `start "" "<url>"` with
+ * `windowsVerbatimArguments: true`, where a quote is syntax. Today the only
+ * caller passes a loopback URL this deck built itself, so nothing is reachable;
+ * the function's own doc says it exists "for the day a second caller passes a
+ * path", and as written it would not have stopped that caller.
+ *
+ * Returning the normalized `href` means the string that was checked is the
+ * string that is launched.
+ */
+export function normalizeOpenable(url) {
   try {
     const u = new URL(String(url));
-    return u.protocol === "http:" || u.protocol === "https:";
+    if (u.protocol !== "http:" && u.protocol !== "https:") return null;
+    return u.href;
   } catch {
-    return false;
+    return null;
   }
 }
 
@@ -183,8 +203,9 @@ export function isOpenable(url) {
  * the same recovery an error row would have offered.
  */
 export function openUrl(url, { platform = process.platform, env = process.env, spawnFn = spawn } = {}) {
-  if (!isOpenable(url)) return;
-  const tries = launchers(url, { platform, env });
+  const href = normalizeOpenable(url);
+  if (href === null) return;
+  const tries = launchers(href, { platform, env });
 
   const attempt = (i) => {
     if (i >= tries.length) return;