ccdeck 3.29.11 → 3.31.0

package/src/server/session-tracking.mjs

@@ -0,0 +1,242 @@
+// Which sessions the deck still keeps anything for: the least-recently-heard
+// cap every per-session cache is reaped against, the transcript watch that
+// polls the live ones between their hook events, and POST /api/forget, the
+// page telling the deck what left its board.
+//
+// These lived in src/server/index.mjs — the expiry section after the ring's
+// reader, and the forget route after Clear. pushEvent touches a session on
+// every live event and notes its transcript for the watch; a Clear empties
+// the watch; startServer starts it. The caches being reaped are the
+// enrichment's and the Codex watcher's, dropped through their own forget
+// functions. The bodies are unchanged.
+import { readBody, send } from "./http-io.mjs";
+// What a session is producing between its tool calls — the 16.5% of measured
+// time the hooks cannot see. See output-watch.mjs.
+import { createOutputWatch } from "./output-watch.mjs";
+import { forgetEnrichment, onRecapTail } from "./session-enrichment.mjs";
+import { forgetCodexSession } from "./codex-enrichment.mjs";
+// event-pipeline.mjs's pushEvent, reached without importing it — see
+// event-sink.mjs.
+import { pushEvent } from "./event-sink.mjs";
+
+// ─── Per-session cache expiry ────────────────────────────────────────────
+// Every enrichment cache (session-enrichment.mjs, codex-enrichment.mjs) is keyed by
+// session id and nothing ever removed an entry: a deck left up for weeks — the 24/7 use this thing is
+// built for — kept a model string, a subagent signature and four read-throttle
+// stamps for every session it had ever seen, plus the Codex rollout path and
+// model of each. SessionEnd is not a usable eviction signal (a killed CLI
+// never sends one, and Codex has no such hook at all), so entries expire by
+// least-recent use against a cap instead — the same shape pruneTranscriptScans
+// already uses for its per-path state.
+//
+// AND A LIVE SESSION IS NEVER EVICTED, which this comment used to assert on the
+// strength of the cap sitting "far above any plausible number of concurrent
+// sessions". The cap held; the claim around it did not, and the 257th
+// concurrent session is where that showed. forgetSession clears the three
+// read-throttle stamps and pruneTranscriptScans drops the byte cursor, so an
+// evicted session that speaks again does not "simply re-read its transcript" —
+// it re-reads it on EVERY event, and those re-reads are themselves pushEvent
+// calls, so the degradation feeds itself. Measured here, fresh deck per row,
+// 16 events per session, 21 KB transcripts:
+//
+//   N=200  posted=3200  synthetic=600   rchar=6 MB   rps=5614  p50=17ms
+//   N=256  posted=4096  synthetic=768   rchar=7 MB   rps=6341  p50=16ms
+//   N=300  posted=4800  synthetic=9159  rchar=77 MB  rps=2308  p50=97ms
+//
+// A 17% increase in session count: 11.9x the derived events, 11x the transcript
+// reads, ingest down 2.7x, p50 up 6x. Three per SESSION became three per EVENT.
+// A cliff, not a slope, sitting exactly on the constant — and the server's cap
+// (256) sits above the client's AGENT_CAP (200), so the UI cannot warn about a
+// number it will not draw.
+//
+// So the cap reaps only what it was always described as reaping: sessions
+// nothing has been heard from. A session with an event inside
+// OUTPUT_WATCH_WINDOW_MS is live by the same definition outputWatchOnce already
+// uses, and keeping it costs four numbers and a string.
+const sessionTouchedAt = new Map();   // sid -> ms of the last event seen
+const MAX_TRACKED_SESSIONS = 256;
+
+/**
+ * The absolute ceiling, above which even a live session is dropped.
+ *
+ * The age rule alone is unbounded in principle — nothing stops a machine from
+ * having ten thousand sessions inside five minutes — and an unbounded map is
+ * the leak this whole mechanism exists to end. This is a backstop, not the
+ * working limit: reaching it means something is wrong in a way no cache policy
+ * fixes, and dropping the least-recently-seen entries is still the least bad
+ * answer. Eight times the cap, which is forty times the client's AGENT_CAP.
+ */
+export const HARD_TRACKED_SESSIONS = MAX_TRACKED_SESSIONS * 8;
+
+/** The transcript watch, and how far back a session stays worth polling.
+ *
+ *  A session is polled while its last HOOK event is recent — and the window has
+ *  to be generous for exactly the reason this watch exists: a session that is
+ *  thinking has, by definition, not fired a hook. Measured on this machine's
+ *  log, the gaps with no event at all run to p99 53s and 155s at the longest,
+ *  so five minutes clears the whole measured distribution and still keeps the
+ *  polled set to the sessions somebody is actually running. */
+const outputWatch = createOutputWatch();
+const OUTPUT_WATCH_WINDOW_MS = 5 * 60_000;
+const OUTPUT_WATCH_MS = 1_500;
+let outputWatchTimer = null;
+
+/** How long a quiet session is still worth a `stat` for its recap, and how
+ *  often it gets one.
+ *
+ *  The five minutes above are sized to a session that is WORKING. A recap is
+ *  the opposite case: Claude Code writes it once a finished turn has sat three
+ *  minutes AND the terminal has lost focus, so it lands whenever the person
+ *  walks away — a median 3.1 minutes after the turn on this machine, and an
+ *  hour after it for somebody who stayed at the terminal first. A session that
+ *  quiet is producing nothing, so every fourth tick is plenty: a recap reaches
+ *  the deck within six seconds of being written, and a resting session costs a
+ *  `stat` every six seconds rather than every one and a half. */
+const RECAP_WATCH_WINDOW_MS = 12 * 60 * 60_000;
+const RECAP_WATCH_EVERY = 4;
+let outputWatchTicks = 0;
+
+/** One tick: stat the recent sessions' transcripts, read only what grew, and
+ *  say what landed. Everything expensive about this is guarded inside the watch
+ *  — a session that wrote nothing costs one `stat`.
+ *
+ *  Resting sessions ride along on every RECAP_WATCH_EVERY-th tick for their
+ *  recap alone, and their blocks are not reported: this answers for the
+ *  sessions it calls live, and a resting one that starts working again fires a
+ *  hook first, which makes it live the ordinary way.
+ *
+ *  A tick that starts while the last one is still reading gets nothing back:
+ *  the watch refuses the overlap itself, where the offset is — see `poll` in
+ *  output-watch.mjs for what two overlapping ticks used to report (#1089). */
+async function outputWatchOnce() {
+  const now = Date.now();
+  const cutoff = now - OUTPUT_WATCH_WINDOW_MS;
+  const restingCutoff = now - RECAP_WATCH_WINDOW_MS;
+  const withResting = outputWatchTicks++ % RECAP_WATCH_EVERY === 0;
+  const live = new Set();
+  const polled = [];
+  for (const [sid, at] of sessionTouchedAt) {
+    if (at >= cutoff) { live.add(sid); polled.push(sid); }
+    else if (withResting && at >= restingCutoff) polled.push(sid);
+  }
+  if (!polled.length) return;
+  const found = await outputWatch.poll(polled, onRecapTail);
+  for (const f of found) {
+    if (!live.has(f.sid)) continue;
+    pushEvent({
+      hook_event_name: "OutputObserved",
+      session_id: f.sid,
+      kind: f.kind,
+      at: f.at,
+    }, "internal");
+  }
+}
+
+function startOutputWatch() {
+  if (outputWatchTimer) return outputWatchTimer;
+  outputWatchTimer = setInterval(() => { outputWatchOnce().catch(() => {}); }, OUTPUT_WATCH_MS);
+  // Unref'd like the Codex watcher's: a poll must never be the reason the
+  // process stays up.
+  if (outputWatchTimer.unref) outputWatchTimer.unref();
+  return outputWatchTimer;
+}
+
+function forgetSession(sid) {
+  outputWatch.forget(sid);
+  forgetEnrichment(sid);
+  forgetCodexSession(sid);
+}
+
+function touchSession(sid) {
+  if (!sid || typeof sid !== "string") return;
+  // Re-insert so the Map's own insertion order *is* the LRU order and eviction
+  // below is one key read rather than a scan of every session ever seen.
+  sessionTouchedAt.delete(sid);
+  const now = Date.now();
+  sessionTouchedAt.set(sid, now);
+  if (sessionTouchedAt.size <= MAX_TRACKED_SESSIONS) return;
+  // Insertion order IS recency, so the first entry still inside the window
+  // proves every entry after it is too, and the loop stops there rather than
+  // scanning. That is what keeps this O(evicted) and not O(sessions) on the hot
+  // path — which matters most in exactly the case that used to be worst.
+  const idleBefore = now - OUTPUT_WATCH_WINDOW_MS;
+  for (const [oldest, at] of sessionTouchedAt) {
+    if (sessionTouchedAt.size <= MAX_TRACKED_SESSIONS) break;
+    if (at >= idleBefore && sessionTouchedAt.size <= HARD_TRACKED_SESSIONS) break;
+    sessionTouchedAt.delete(oldest);
+    forgetSession(oldest);
+  }
+}
+
+/** The most session ids one press of this may name. A board holding more than
+ *  the server tracks at all cannot be describing anything the server still
+ *  remembers, and a body is not a reason to walk an unbounded list. */
+const MAX_FORGET_IDS = MAX_TRACKED_SESSIONS;
+
+/**
+ * POST /api/forget — the client's own pruners, saying what left the board.
+ *
+ * THE THIRD PLACE THE RULE HAD TO REACH (#1024). `handleClear`'s comment states
+ * it: "anything answering 'has this changed' has to appear in BOTH places that
+ * mean the client no longer has it — here (clearEnrichmentGates), and in
+ * forgetSession (forgetEnrichment)." There was a
+ * third, and the server never heard about it — `pruneDoneSessions` and
+ * `pruneOldAgents` in the page, which run every 250ms at cap 6 / grace 2
+ * minutes, and #445's own measurement says 7 of 20 evicted sessions went on to
+ * emit more events.
+ *
+ * Usage, context and the ROOT model all come back on their own: the first two
+ * are not change-gated, and `pushEvent` stamps `raw.model` on every payload.
+ * `sessionName`/`sessionTitle` and the per-subagent models do not, because
+ * `nameBySession` and `modelBySession` still hold the signature that gates the
+ * emit. Measured against a real deck over a real transcript, sandboxed HOME:
+ *
+ *     SessionNamed while the session was on the board: ["reducer-audit"]
+ *     --- the client prunes S5, and tells nobody ---
+ *     events for S5 after the resume: UserPromptSubmit, UsageObserved,
+ *       UserPromptSubmit, UsageObserved, ContextObserved, …
+ *     SessionNamed among them: false
+ *
+ * A session evicted while idle and then resumed showed as unnamed in the sidebar
+ * and on the card for the rest of the day, with no way to recover but reloading
+ * the tab.
+ *
+ * `forgetSession` is the whole of the answer and it already exists — this route
+ * is the client's half of a call the server has been making to itself since the
+ * LRU cap was added. It drops the read stamps along with the signatures, for the
+ * reason `handleClear` lists them: clearing only the signatures would leave the
+ * next hook event inside MODEL_READ_THROTTLE_MS, so nothing would be re-read and
+ * the name would still be missing.
+ *
+ * NOT DROPPING THE CHANGE GATE INSTEAD, which was the other option in the
+ * report. The gate is what keeps a per-pass emit from becoming ~683 events
+ * saying nothing out of 685 records, and the reducer absorbing repeats correctly
+ * is not a reason to send them.
+ *
+ * Costs nothing when it is wrong. A session named here that the deck is still
+ * hearing from re-reads its transcript once and re-emits what it finds, which
+ * the reducer's assign-don't-append handlers apply idempotently.
+ */
+async function handleForget(req, res) {
+  const raw = await readBody(req).catch(() => null);
+  let body = null;
+  try { body = JSON.parse(raw ?? ""); } catch { /* handled below */ }
+  const ids = Array.isArray(body?.ids) ? body.ids : null;
+  if (!ids) return send(res, 400, { ok: false, reason: "bad_request" });
+  let forgotten = 0;
+  for (const sid of ids.slice(0, MAX_FORGET_IDS)) {
+    if (typeof sid !== "string" || sid === "") continue;
+    // Out of the LRU as well, so the cap is not spent on a session nothing is
+    // tracking any more. A session that speaks again is re-inserted by
+    // `touchSession` as what it now is: one the deck has just heard from.
+    sessionTouchedAt.delete(sid);
+    forgetSession(sid);
+    forgotten++;
+  }
+  return send(res, 200, { ok: true, forgotten });
+}
+
+// What index.mjs calls besides HARD_TRACKED_SESSIONS. Listed rather than
+// marked at each declaration, so the declarations read as they did where they
+// came from.
+export { handleForget, outputWatch, startOutputWatch, touchSession };

package/src/server/sse-clients.mjs

@@ -0,0 +1,222 @@
+// The deck's SSE subscribers, and the one discipline every frame to them is
+// written under: a client too far behind is hung up on rather than buffered
+// for, and a resuming client is waited for rather than dropped.
+//
+// These lived in src/server/index.mjs — the two client sets beside the ring,
+// the backpressure section after the session expiry. The sets are shared, not
+// copied: pushEvent broadcasts over them, the desktop-update routes and the
+// notifier reach the app's tray connections through them, and resumeSse adds a
+// client once its replay is done. The bodies are unchanged.
+
+const sseClients = new Set();       // res handles
+// The desktop app's own connections (#1160): subscribed like any client, so
+// they receive every event, and ALSO kept here so they are never counted as a
+// page. The app reads the stream to draw its tray icon; if that counted as a
+// tab, the deck would believe a page was open whenever the app ran, and the
+// notifications a closed deck raises (block-notify.mjs) would never fire —
+// the one thing the app exists to deliver. See `pageCount`.
+const trayClients = new Set();
+
+/** Pages — deck tabs and the app's window — as opposed to the app's tray
+ *  connection, which is a reader and not somebody looking. */
+function pageCount() {
+  return sseClients.size - trayClients.size;
+}
+
+/** A notification for the desktop app to raise as itself, instead of the OS
+ *  helper raising it as Script Editor (osascript) or PowerShell. */
+function notifyTrays(title, body, { chime = null, who = null } = {}) {
+  // The app names itself above the notification, so the title is the session.
+  const line = `event: notify\ndata: ${JSON.stringify({ title: who ?? title, body, chime })}\n\n`;
+  for (const res of trayClients) writeSse(res, line);
+  return true;
+}
+
+// ─── SSE backpressure ────────────────────────────────────────────────────
+// A client that stops reading without closing its socket — a frozen tab, a
+// suspended machine, a stalled `ssh -L` tunnel — never fires 'close' and never
+// makes write() throw, so the old `try { res.write(line) } catch {}` had no
+// way to notice it. On loopback nothing times the connection out either, so
+// every event (tool responses run to megabytes) queued in that socket's write
+// buffer for as long as the process lived.
+//
+// We drop the client rather than the events. EventSource reconnects after the
+// `retry: 1500` we send on connect and resumes from Last-Event-ID, so the ring
+// 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.
+//
+// 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;
+
+/**
+ * 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 Math.max(own, sock);
+}
+
+/** Hang up on a client we have decided not to keep. `delete` on a response
+ *  that never made it into the set — the resume path (resumeSse, in
+ *  event-routes.mjs) hangs up on clients before they are subscribed — is a
+ *  harmless no-op. */
+function dropSse(res) {
+  sseClients.delete(res);
+  trayClients.delete(res);
+  // Destroying the socket is what makes the request emit 'close', which is
+  // where the ping interval is cleared.
+  try { res.destroy(); } catch {}
+  try { res.socket?.destroy(); } catch {}
+}
+
+/** Write one SSE frame, hanging up on a client too far behind to keep. */
+function writeSse(res, frame) {
+  try {
+    res.write(frame);
+    if (queuedBytes(res) <= MAX_CLIENT_BUFFER_BYTES) return;
+  } catch { /* already dead — drop it below */ }
+  dropSse(res);
+}
+
+// How long a resuming client is given to accept the bytes already queued for
+// it before the deck concludes it is not reading at all. Generous on purpose:
+// what it has to work through is a full MAX_CLIENT_BUFFER_BYTES, the link may
+// be an `ssh -L` tunnel rather than loopback, and dropping a client that is
+// merely slow costs it the whole replay. A tab that is genuinely frozen will
+// 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;
+
+/**
+ * Write one frame of the resume stream under the same ceiling the live path
+ * obeys, waiting rather than dropping when the client is at it. Resolves true
+ * while the client is worth keeping, false once it is not.
+ *
+ * Waiting is the whole difference from writeSse, and the replay is why. The
+ * live path writes one frame per event, so a full buffer there means the
+ * client stopped reading and the only answer is to hang up. Here the burst is
+ * ours: resumeSse's loop hands the socket the entire ring buffer in one turn of
+ * the event loop, so even a client reading at full speed sees its buffer fill
+ * — nothing has drained it yet, because nothing could. Dropping on that would
+ * hang up on healthy clients, and hang up on them again every time they came
+ * back: EventSource reconnects with the same Last-Event-ID, meets the same
+ * oversized replay, and is dropped again 1.5 seconds later, forever. So we
+ * stop writing until the socket has taken what it already has, and only give
+ * 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' 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
+ * hang on a client that goes away.
+ */
+async function writeResume(res, frame) {
+  // Below the cap this is the plain write it has always been. The `await` in
+  // the caller costs a microtask and nothing else: the checkpoint drains
+  // before the loop can accept I/O, so no live event can slip between two
+  // replay frames the way it could across a real wait.
+  if (queuedBytes(res) <= MAX_CLIENT_BUFFER_BYTES) {
+    try { res.write(frame); return true; } catch { return false; }
+  }
+  return new Promise(resolve => {
+    let settled = false;
+    const done = ok => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolve(ok);
+    };
+    // Unref'd so a client that stopped reading can never be the reason the
+    // process stays alive, and cleared on every path out so a completed replay
+    // leaves no timer behind.
+    const timer = setTimeout(() => done(false), REPLAY_DRAIN_MS);
+    timer.unref?.();
+    try { res.write(frame, () => done(!res.destroyed)); }
+    catch { done(false); }
+  });
+}
+
+// What the server's other modules call besides the two exported above —
+// pushEvent's fan-out, the event routes, health and the desktop-update routes.
+// Listed rather than marked at each declaration, so the declarations read as
+// they did where they came from.
+export { dropSse, notifyTrays, pageCount, sseClients, trayClients, writeResume, writeSse };

package/src/server/stale-discovery.mjs

@@ -0,0 +1,30 @@
+// The discovery records of decks that are no longer running, removed as a
+// deck starts.
+//
+// This lived in src/server/index.mjs, after the hook challenge; startServer
+// calls it once, before it reads the log. Whether a record's process is alive
+// is deck-probe.mjs's question. The body is unchanged.
+import { readFile, readdir, unlink } from "node:fs/promises";
+import { join } from "node:path";
+import { claudeConfigDir } from "./claude-dir.mjs";
+import { isProcessAlive } from "./deck-probe.mjs";
+
+export async function sweepStaleDiscovery() {
+  // Same directory the installer writes and the hooks read — see claude-dir.mjs.
+  const dir = join(claudeConfigDir(), "agent-dag");
+  let files;
+  try { files = await readdir(dir); } catch { return 0; }
+  let removed = 0;
+  for (const f of files) {
+    if (!f.endsWith(".json")) continue;
+    const p = join(dir, f);
+    try {
+      const d = JSON.parse(await readFile(p, "utf8"));
+      if (d && typeof d.pid === "number" && !isProcessAlive(d.pid)) {
+        await unlink(p).catch(() => {});
+        removed++;
+      }
+    } catch { /* corrupt — leave it */ }
+  }
+  return removed;
+}

package/src/server/static-serve.mjs

@@ -0,0 +1,81 @@
+// The deck's own page: dist/web served off disk, compressed and cached by name
+// (#883), with index.html standing in for any path a client-side route owns.
+//
+// This lived in src/server/index.mjs — the type table near the top, the
+// handler after the event stream's writers. It reads nothing of the server's,
+// so it moved whole; the route table still decides what reaches it. The
+// handler is unchanged.
+import { readFile, stat } from "node:fs/promises";
+import { dirname, extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { send } from "./http-io.mjs";
+import { cacheControlFor, encodedBody, pickEncoding } from "./static-cache.mjs";
+
+// Resolved the way pinned-build.mjs resolves its package root, from a file in
+// the same directory.
+const PKG_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
+const WEB_DIST = resolve(PKG_ROOT, "dist", "web");
+
+const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js":   "application/javascript; charset=utf-8",
+  ".mjs":  "application/javascript; charset=utf-8",
+  ".css":  "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg":  "image/svg+xml",
+  // The type is the whole of how a browser recognises a manifest: served as
+  // application/octet-stream — which is what the fallback below hands anything
+  // unlisted — Chrome fetches it, declines to parse it, and offers no install,
+  // with nothing in the console that names the reason.
+  ".webmanifest": "application/manifest+json; charset=utf-8",
+  ".png":  "image/png",
+  ".jpg":  "image/jpeg",
+  ".woff2": "font/woff2",
+  ".map":  "application/json",
+};
+
+async function serveStatic(req, res, url) {
+  // Strip leading slash, default to index.html
+  let rel = url.pathname.replace(/^\/+/, "");
+  if (rel === "" || rel.endsWith("/")) rel = `${rel}index.html`;
+  const filePath = join(WEB_DIST, rel);
+  if (!filePath.startsWith(WEB_DIST)) return send(res, 403, { error: "forbidden" });
+
+  try {
+    const s = await stat(filePath);
+    if (s.isDirectory()) return send(res, 404, { error: "not found" });
+    const buf = await readFile(filePath);
+    const ext = extname(filePath).toLowerCase();
+    // Compressed when the browser takes it, and cached for good when the name
+    // is a content hash (#883) — see static-cache.mjs. `rel` is the URL's own
+    // spelling, forward slashes on every platform, which is what the hash
+    // pattern reads; `filePath` is only the cache key.
+    const encoding = pickEncoding(req.headers["accept-encoding"], ext);
+    const body = encoding ? encodedBody(filePath, s.mtimeMs, buf, encoding) : buf;
+    res.writeHead(200, {
+      "Content-Type": MIME[ext] ?? "application/octet-stream",
+      "Cache-Control": cacheControlFor(rel),
+      "Vary": "Accept-Encoding",
+      "Content-Length": body.length,
+      ...(encoding ? { "Content-Encoding": encoding } : {}),
+    });
+    res.end(body);
+  } catch {
+    // SPA fallback to index.html for client-side routes
+    try {
+      const idx = await readFile(join(WEB_DIST, "index.html"));
+      // Same no-cache as the normal path above, which this used to omit. It
+      // matters more since the deck upgrades itself: index.html is the file
+      // naming the hashed bundle, so a heuristically-cached copy sends the tab
+      // back to the OLD assets after an update and the reload achieves nothing.
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache" });
+      res.end(idx);
+    } catch {
+      send(res, 404, { error: "ui not built. run `pnpm build` or `npm run build`." });
+    }
+  }
+}
+
+// What the route table calls. Listed rather than marked at the declaration, so
+// the declaration reads as it did where it came from.
+export { serveStatic };