@promptctl/cc-candybar 1.0.0

package/src/daemon/server.ts

@@ -0,0 +1,1103 @@
+import fs from "node:fs";
+import net from "node:net";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import {
+  daemonDir,
+  ensureSocketParentSafe,
+  pidPath,
+  socketPath,
+  sessionStatePath,
+} from "./paths";
+import { dlog, closeLog } from "./log";
+import {
+  PROTOCOL_VERSION,
+  encodeFrame,
+  makeFrameReader,
+  sanitizeTermCols,
+} from "./protocol";
+import type { Request, Response } from "./protocol";
+import { GitDataProvider } from "./cache/git";
+import { SessionUsageStore } from "./cache/session-usage-store";
+import { RenderCache } from "./cache/render";
+import { WatcherRegistry } from "./cache/watchers";
+import { RuntimeStats } from "./stats";
+import { makeLimits, realLimitsDeps, type LimitsHandle } from "./limits";
+import { armParentWatchdog, anchorFromEnv, pidAlive } from "./parent-watchdog";
+import { SessionState } from "./session-state";
+import { FileSessionStorage } from "./session-state-file";
+import { VERBS, BadVerbArgs, SESSION_CONFIG_OVERRIDE_KEY } from "./verbs";
+import {
+  effectsUrl,
+  VERB_SHOW_CONFIG_ERROR,
+  VERB_SHOW_CONFIG_WARNING,
+} from "../click/wire.js";
+import { validateHookData } from "../utils/schema-validator.js";
+import { setLaunchStats } from "../proc/launch";
+import { buildDebugSnapshot } from "./debug";
+import { DEBUG_WHATS, isDebugWhat } from "./debug-types";
+import { expandHome } from "../config/dsl-loader.js";
+import { renderDsl } from "../dsl/render.js";
+import { effectiveThemeName, resolverForThemeName } from "../themes/index.js";
+import {
+  renderStripCells,
+  DEFAULT_TERMINAL_WIDTH,
+  type BuildLineOptions,
+} from "../render/strip.js";
+import { applyClaudeCodeReserve } from "../utils/terminal-width.js";
+import type { RichText } from "@promptctl/rich-js";
+import { buildRenderPayload } from "./render-payload.js";
+import { ContextProvider } from "../segments/context.js";
+import { MetricsProvider } from "../segments/metrics.js";
+import { TmuxService } from "../segments/tmux.js";
+import { sanitizeAndTruncate } from "../render/diagnostic-text.js";
+import {
+  ANSI_RESET,
+  DIAGNOSTIC_ERROR_BG,
+  DIAGNOSTIC_ERROR_FG,
+  DIAGNOSTIC_WARNING_BG,
+  DIAGNOSTIC_WARNING_FG,
+} from "../render/diagnostic-style.js";
+
+// [LAW:one-source-of-truth] one cache instance per daemon process — multiple
+// instances would defeat the share-across-sessions invariant.
+const stats = new RuntimeStats();
+// [LAW:single-enforcer] Route all child_process spawns through src/proc/launch.
+// Installing the metering handle here makes subprocess counts visible in
+// daemon-stats.
+setLaunchStats(stats.launchStats);
+// [LAW:single-enforcer] The daemon injects `dlog` into both registries so
+// cache + watcher lifecycle events land in daemon.log at the right level.
+// Non-daemon consumers (var-system tests, future library use) take the
+// default debug-routed loggers and never write to daemon log files.
+const watcherRegistry = new WatcherRegistry({
+  counters: stats,
+  logger: dlog,
+});
+const gitService = new GitDataProvider({
+  watchers: watcherRegistry,
+  logger: dlog,
+});
+const usageStore = new SessionUsageStore();
+// [LAW:locality-or-seam] Constructed ephemeral so importing this module (CLI
+// relay, subcommands) does no disk I/O. The daemon binds the file-backed
+// storage in runDaemon(), making it the sole reader/writer of the state file.
+const sessionState = new SessionState();
+// [LAW:one-source-of-truth] One provider per data shape, shared across every
+// render in this daemon. The render cache owns DSL-state-per-config; these
+// providers serve the augmented payload that flows through every render.
+const contextProvider = new ContextProvider();
+const metricsProvider = new MetricsProvider();
+const tmuxService = new TmuxService();
+const renderCache = new RenderCache({
+  gitService,
+  sessionState,
+  watchers: watcherRegistry,
+});
+
+const REQUEST_TIMEOUT_MS = 200;
+const BIN_CHECK_INTERVAL_MS = 60 * 1000;
+
+// Daemon entry point. Tries to bind the Unix socket — atomic bind() is the
+// single-instance enforcer (two daemons cannot both bind the same path; the
+// kernel makes duplicate-daemon unrepresentable). Listens for one request per
+// connection. Any uncaught error exits non-zero; the next client obtains a
+// fresh daemon via obtainDaemonKick() (fire-and-forget caller) or
+// obtainDaemon() (caller waits for readiness) in src/daemon/acquire.ts.
+export function runDaemon(): void {
+  fs.mkdirSync(daemonDir(), { recursive: true });
+  // [LAW:single-enforcer] Verify the socket parent is uid==me + mode 0700 +
+  // not a symlink before we bind. Without this check, a same-host attacker
+  // could pre-create the predictable `/tmp/cc-candybar-<uid>` directory and
+  // squat the socket name. The check applies regardless of CC_CANDYBAR_SOCKET
+  // location — every bind path goes through the same trust precondition.
+  // No symmetric client-side check: the daemon is the sole creator, so a
+  // successful bind already proves the parent is trusted. Failure here surfaces
+  // as a daemon exit; the client falls back to the last cached render.
+  ensureSocketParentSafe(socketPath());
+
+  // Bind disk persistence now that we know we are the daemon process — load
+  // prior session state and become the sole writer of the state file.
+  sessionState.useStorage(
+    new FileSessionStorage(sessionStatePath(), 500, dlog),
+  );
+
+  // Catch-alls log + exit so the supervisor (the next client) can restart us.
+  // [LAW:no-defensive-null-guards] These are *trust boundaries* — we are
+  // catching all of unknown space, not skipping known optional values.
+  process.on("uncaughtException", (err) => {
+    dlog("error", `uncaughtException: ${err.stack || err.message}`);
+    shutdown(1);
+  });
+  process.on("unhandledRejection", (reason) => {
+    dlog("error", `unhandledRejection: ${String(reason)}`);
+    shutdown(1);
+  });
+  for (const sig of ["SIGINT", "SIGTERM", "SIGHUP"] as const) {
+    process.on(sig, () => {
+      dlog("info", `received ${sig}, shutting down`);
+      shutdown(0);
+    });
+  }
+
+  // [LAW:single-enforcer] Same death funnel as the signals and the RSS backstop:
+  // the watchdog calls shutdown(0), it never exits on its own. A production
+  // daemon has no spawner to outlive (env unset) and arms an inert handle; only
+  // a test-spawned daemon is anchored, so this is invisible to the real daemon.
+  armParentWatchdog({
+    anchor: anchorFromEnv(process.env),
+    isAlive: pidAlive,
+    onOrphaned: (reason) => {
+      dlog("info", `parent watchdog: ${reason}; shutting down`);
+      shutdown(0);
+    },
+  });
+
+  const server = net.createServer({ allowHalfOpen: false }, (sock) => {
+    handleConnection(sock);
+  });
+
+  // [LAW:single-enforcer] The atomic bind() is the daemon-singleton enforcer.
+  // Two daemons cannot both bind the same Unix socket path; the kernel makes
+  // duplicate-daemon unrepresentable. The pidfile is diagnostic only — never
+  // load-bearing for exclusion.
+  bindOrAttachAndExit(server, socketPath(), /* retried */ false);
+}
+
+// [LAW:dataflow-not-control-flow] One operation ("bring this server up or
+// discover an existing one"). The bind result is the data that decides the
+// next step; callers do not get to choose whether to spawn.
+function bindOrAttachAndExit(
+  server: net.Server,
+  sockPath: string,
+  retried: boolean,
+): void {
+  server.removeAllListeners("error");
+  server.once("error", (err) => {
+    const code = (err as NodeJS.ErrnoException).code;
+    if (code !== "EADDRINUSE") {
+      dlog("error", `server error: ${err.message}`);
+      shutdown(1);
+      return;
+    }
+    if (retried) {
+      // Lost a rebind race with another duplicate. The kernel arbitrated; we
+      // are the loser. Exit cleanly so the winner serves.
+      dlog("info", "lost rebind race; another daemon is alive — exiting");
+      process.exit(0);
+      return;
+    }
+    void handleAddressInUse(server, sockPath);
+  });
+  server.listen(sockPath, () => onListening(sockPath));
+}
+
+async function handleAddressInUse(
+  server: net.Server,
+  sockPath: string,
+): Promise<void> {
+  // EADDRINUSE: either a live daemon (we are a duplicate — exit), or a stale
+  // socket file from a crashed prior daemon (unlink + rebind).
+  const alive = await isSocketAlive(sockPath);
+  if (alive) {
+    dlog("info", "another daemon is listening on socket — exiting");
+    process.exit(0);
+  }
+  // Race-window guard: between our first `isSocketAlive` returning false and
+  // our `unlinkSync` running, another concurrent recoverer could unlink+bind
+  // the path. Without re-checking, our unlink would remove their *live*
+  // socket, leaving two daemons (one orphaned-but-listening, one freshly
+  // bound). Re-check immediately before unlink. If a live listener appeared
+  // between checks, exit instead of stomping on it.
+  if (await isSocketAlive(sockPath)) {
+    dlog(
+      "info",
+      "race: another daemon claimed the socket during recovery — exiting",
+    );
+    process.exit(0);
+  }
+  dlog("warn", "stale socket from crashed daemon — unlinking and rebinding");
+  // [LAW:no-defensive-null-guards] If unlink fails (permissions, read-only
+  // FS), the retry will hit EADDRINUSE again, exit 0, and leave the system
+  // in the worst state: no daemon + stale socket blocking future starts.
+  // Surface unrecoverable failures loudly. ENOENT is fine — the goal was
+  // "make the path bindable" and a missing path already satisfies that.
+  try {
+    fs.unlinkSync(sockPath);
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code !== "ENOENT") {
+      dlog(
+        "error",
+        `cannot unlink stale socket ${sockPath}: ${(e as Error).message}`,
+      );
+      shutdown(1);
+      return;
+    }
+  }
+  bindOrAttachAndExit(server, sockPath, /* retried */ true);
+}
+
+// [LAW:no-defensive-null-guards] Three-state outcome distinguishes
+// "definitely no listener" from "probably alive but slow." Callers that
+// might destroy state on "no listener" (the stale-socket unlink path) must
+// treat "unknown" as alive to avoid stomping on a slow live daemon.
+type SocketAliveness = "alive" | "dead" | "unknown";
+
+function probeSocket(sockPath: string): Promise<SocketAliveness> {
+  return new Promise((resolve) => {
+    const sock = net.connect(sockPath);
+    let settled = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const done = (result: SocketAliveness): void => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      sock.removeAllListeners();
+      sock.destroy();
+      resolve(result);
+    };
+    sock.once("connect", () => done("alive"));
+    sock.once("error", (err) => {
+      // Only these error codes definitively mean "no listener at this path":
+      //   ECONNREFUSED — socket file present, kernel rejected connect
+      //   ENOENT       — socket file absent
+      //   ENOTSOCK     — path exists but isn't a socket
+      // Anything else (EPERM, EACCES, EAGAIN, …) is ambiguous — assume the
+      // daemon is alive to avoid destructive false negatives.
+      const code = (err as NodeJS.ErrnoException).code;
+      const dead =
+        code === "ECONNREFUSED" || code === "ENOENT" || code === "ENOTSOCK";
+      done(dead ? "dead" : "unknown");
+    });
+    // 50ms is generous; localhost AF_UNIX connect is sub-ms when a listener
+    // exists. Timeout means "we couldn't tell" — treat as unknown so the
+    // stale-socket recovery path doesn't unlink a live (but slow) daemon's
+    // socket.
+    timer = setTimeout(() => done("unknown"), 50);
+    timer.unref();
+  });
+}
+
+// Convenience: callers that just want "is something listening" treat
+// "unknown" as alive (conservative — used by the EADDRINUSE attach branch).
+async function isSocketAlive(sockPath: string): Promise<boolean> {
+  const result = await probeSocket(sockPath);
+  return result !== "dead";
+}
+
+function onListening(sockPath: string): void {
+  try {
+    fs.chmodSync(sockPath, 0o600);
+  } catch (e) {
+    dlog("warn", `chmod socket failed: ${(e as Error).message}`);
+  }
+  writePidfileDiagnostic();
+  dlog(
+    "info",
+    `daemon up: pid=${process.pid} v=${PROTOCOL_VERSION} sock=${sockPath}`,
+  );
+  armBinaryWatch();
+  armLimits();
+}
+
+// --- binary-mtime self-restart ---
+//
+// If the daemon's compiled output changes on disk (rebuild, upgrade, edit),
+// exit at the next sample so the next client respawns from the fresh code.
+// Cheap (one statSync/min) and avoids the user having to manually kill the
+// daemon during development. unref() so this timer doesn't hold the process alive.
+function armBinaryWatch(): void {
+  // Watch the resolved entry point, not the bin shim — npm run build updates
+  // dist/index.mjs but the bin/cc-candybar shim never changes.
+  const entryUrl = import.meta.url;
+  const targets: string[] = [];
+  if (entryUrl.startsWith("file://")) {
+    targets.push(fileURLToPath(entryUrl));
+  }
+  // Also watch argv[1] as fallback (covers global installs, symlinks, etc.)
+  if (process.argv[1]) targets.push(process.argv[1]!);
+
+  const originalMtimes = new Map<string, number>();
+  for (const t of targets) {
+    try {
+      originalMtimes.set(t, fs.statSync(t).mtimeMs);
+    } catch {
+      // File may not exist yet — skip it.
+    }
+  }
+  if (originalMtimes.size === 0) return;
+
+  const timer = setInterval(() => {
+    for (const [t, originalMtime] of originalMtimes) {
+      try {
+        const nowMtime = fs.statSync(t).mtimeMs;
+        if (nowMtime !== originalMtime) {
+          dlog("info", `binary mtime changed (${t}); shutting down`);
+          clearInterval(timer);
+          shutdown(0);
+          return;
+        }
+      } catch (e) {
+        dlog("warn", `bin stat failed: ${(e as Error).message}`);
+      }
+    }
+  }, BIN_CHECK_INTERVAL_MS);
+  timer.unref();
+}
+
+// --- self-shutdown on RSS / age ---
+let limits: LimitsHandle | null = null;
+function armLimits(): void {
+  limits = makeLimits(
+    realLimitsDeps(stats.startedAt.getTime(), (code) => shutdown(code)),
+  );
+  limits.arm();
+}
+
+// --- diagnostic pidfile ---
+//
+// [LAW:one-source-of-truth] The pidfile is *diagnostic only*. It records who
+// the running daemon is so `daemon-stats` can report it; it plays no role in
+// exclusion. Exclusion is the atomic bind() in bindOrAttachAndExit().
+//
+// Overwrite-on-write (no EEXIST check). If a stale pidfile exists from a
+// crashed prior daemon, we replace it. The bind() above already proved no
+// other daemon is alive.
+
+function writePidfileDiagnostic(): void {
+  const payload = JSON.stringify({
+    pid: process.pid,
+    version: PROTOCOL_VERSION,
+    binPath: process.argv[1],
+    startedAt: new Date().toISOString(),
+  });
+  try {
+    fs.writeFileSync(pidPath(), payload, { mode: 0o600 });
+    // [LAW:single-enforcer] writeFileSync's `mode` only applies when the file
+    // is created. If a stale pidfile from a prior run was left with broader
+    // permissions, the write above won't tighten them — chmod explicitly so
+    // 0600 is the invariant regardless of prior state.
+    fs.chmodSync(pidPath(), 0o600);
+  } catch (e) {
+    // Diagnostic only — failure does not block the daemon from serving.
+    dlog("warn", `pidfile write failed: ${(e as Error).message}`);
+  }
+}
+
+function removePidfileDiagnostic(): void {
+  try {
+    fs.unlinkSync(pidPath());
+  } catch {}
+}
+
+let inFlight = 0;
+
+// --- shutdown ---
+
+let shuttingDown = false;
+function shutdown(code: number): void {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  // [LAW:single-enforcer] Arm the SIGKILL backstop FIRST, before any cleanup.
+  // The 452-daemon incident: shut-down daemons logged "shutting down" but
+  // held the bound socket FD 42 minutes later — process.exit() reached the
+  // call site but never completed because some active handle kept libuv's
+  // event loop alive past exit's teardown. The prior shape had `.unref()`
+  // on the SIGKILL timer, so the timer itself did NOT keep the loop alive
+  // — leaving the loop's only remaining live handles to win the race.
+  //
+  // What this timer guarantees: as long as the event loop can still run
+  // (handles that won't drop, async cleanup that schedules but never
+  // completes — the realistic failure modes for the incident class), the
+  // setTimeout callback fires within 500ms and SIGKILL terminates the
+  // process from outside the loop's bookkeeping. Critically the timer is
+  // NOT unref'd, so it is itself an active handle that keeps the loop
+  // alive long enough for itself to fire.
+  //
+  // What this timer cannot do: rescue a truly synchronous thread block
+  // (a C++ binding that never returns to JS, an infinite sync loop). No
+  // JS timer can fire while the main thread is blocked; only an external
+  // signal recovers that case. The realistic 452-corpse mode was async-
+  // handle retention, not a synchronous block, so the backstop is
+  // load-bearing for the observed failure pattern.
+  setTimeout(() => process.kill(process.pid, "SIGKILL"), 500);
+  // [LAW:single-enforcer] The atomic bind() on the unix socket path is the
+  // ONLY mutex preventing duplicate daemons. The previous shape unlinked
+  // the socket file FIRST, then spent O(100ms) closing watchers, flushing
+  // session state, and tearing down log streams before process.exit().
+  // The unlink frees the path the instant it runs; the listening FD stays
+  // held only until process.exit. In between, Claude Code's next render
+  // tick can spawn a fresh daemon that bind()s the same path and starts
+  // serving while we are still finishing cleanup. Under OOM cycles the
+  // overlap compounds — 12 daemons stacked up in the wild was the
+  // observed symptom. Do NOT unlink here. The kernel releases the FD on
+  // process.exit; the stale path that remains is recovered by the
+  // existing handleAddressInUse logic on the next daemon's startup
+  // (probe → dead → unlink + rebind, ~50ms one-shot cost).
+  try {
+    gitService.close();
+  } catch (e) {
+    dlog("warn", `gitService close failed: ${(e as Error).message}`);
+  }
+  try {
+    usageStore.close();
+  } catch (e) {
+    dlog("warn", `usageStore close failed: ${(e as Error).message}`);
+  }
+  try {
+    watcherRegistry.closeAll();
+  } catch (e) {
+    dlog("warn", `watcherRegistry close failed: ${(e as Error).message}`);
+  }
+  try {
+    sessionState.flush();
+  } catch (e) {
+    dlog("warn", `sessionState flush failed: ${(e as Error).message}`);
+  }
+  removePidfileDiagnostic();
+  closeLog();
+  process.exit(code);
+}
+
+// --- per-connection handler ---
+
+function handleConnection(sock: net.Socket): void {
+  inFlight++;
+  stats.inFlight = inFlight;
+  let responded = false;
+
+  // [LAW:no-ambient-temporal-coupling] respond owns the response→exit
+  // ordering. exitAfterFlush (an exit code; null = stay up) is performed
+  // by sock.end's completion callback, which Node invokes on 'finish' OR
+  // 'error' — a total signal. A peer that vanished mid-flush still settles,
+  // so the exit wish can never be stranded on a dead socket, and a live
+  // peer always has the frame in the kernel buffer before process.exit
+  // (unix-socket data survives writer exit). No fixed sleep stands between
+  // respond and exit; the SIGKILL backstop inside shutdown() is the
+  // unrelated last-resort safety.
+  const respond = (resp: Response, exitAfterFlush: number | null): void => {
+    if (responded) {
+      // First responder owns the flush. Reaching here with an exit wish is
+      // unreachable today (both exit-carrying arms resolve synchronously,
+      // far inside the request timeout) — but if it ever happens, say so
+      // instead of silently leaving a daemon up that was told to exit.
+      // [LAW:no-silent-failure]
+      if (exitAfterFlush !== null) {
+        dlog(
+          "warn",
+          "exit-after-flush dropped: an earlier responder settled this socket",
+        );
+      }
+      return;
+    }
+    responded = true;
+    const settle =
+      exitAfterFlush === null
+        ? undefined
+        : (): void => shutdown(exitAfterFlush);
+    try {
+      sock.end(encodeFrame(resp), settle);
+    } catch (e) {
+      // [LAW:no-silent-failure] The response is lost (socket already torn
+      // down), but the exit wish must not be.
+      dlog("warn", `response write failed: ${(e as Error).message}`);
+      settle?.();
+    }
+  };
+
+  // Per-request timeout protects the daemon from a single slow request
+  // (e.g. a hung git call) blocking subsequent connections. It abandons the
+  // RESPONSE, not the work — the handler promise keeps running.
+  //
+  // [LAW:one-source-of-truth] That is safe for the transcript-fs path because
+  // the work is bounded + shared, not orphaned: the today aggregate and
+  // per-session usage compute behind a SingleFlight (src/utils/single-flight.ts),
+  // so a timed-out render that abandoned its await leaves behind the ONE
+  // canonical in-flight scan, which the next render coalesces onto rather than
+  // duplicating. A timeout therefore adds zero new fs work — there is never
+  // more than one scan per key to orphan. Cancellation would be both messier
+  // and wasteful here (the in-flight scan is exactly what the next tick needs).
+  const timer = setTimeout(() => {
+    stats.requestsTimedOut++;
+    respond(
+      {
+        ok: false,
+        error: "request exceeded 200ms",
+        code: "TIMEOUT",
+        daemonV: PROTOCOL_VERSION,
+      },
+      null,
+    );
+  }, REQUEST_TIMEOUT_MS);
+
+  const reader = makeFrameReader(
+    (frame) => {
+      void handleRequest(frame as Request)
+        .then((r) => respond(r.resp, r.exitAfterFlush))
+        .catch((err) => {
+          dlog("error", `handler threw: ${err?.stack || err}`);
+          respond(
+            {
+              ok: false,
+              error: String(err?.message || err),
+              code: "RENDER_FAILED",
+              daemonV: PROTOCOL_VERSION,
+            },
+            null,
+          );
+        });
+    },
+    (err) => {
+      dlog("warn", `frame parse failed: ${err.message}`);
+      respond(
+        {
+          ok: false,
+          error: err.message,
+          code: "BAD_REQUEST",
+          daemonV: PROTOCOL_VERSION,
+        },
+        null,
+      );
+    },
+  );
+
+  sock.on("data", reader);
+  sock.on("error", (err) => {
+    dlog("warn", `socket error: ${err.message}`);
+  });
+  sock.on("close", () => {
+    clearTimeout(timer);
+    inFlight = Math.max(0, inFlight - 1);
+    stats.inFlight = inFlight;
+  });
+}
+
+// [LAW:no-ambient-temporal-coupling] A request whose semantics include "then
+// exit" (the shutdown verb, the stale-binary version mismatch) must not exit
+// until its response has flushed — but handleRequest cannot see the socket.
+// So the exit is returned as DATA (the exit code; null = stay up) and the
+// connection boundary, which owns the flush, sequences shutdown on the write
+// completion. No timer stands between respond and exit.
+// [LAW:effects-at-boundaries] handleRequest computes the description; the
+// socket boundary performs it.
+interface HandledRequest {
+  resp: Response;
+  exitAfterFlush: number | null;
+}
+
+const stay = (resp: Response): HandledRequest => ({
+  resp,
+  exitAfterFlush: null,
+});
+
+async function handleRequest(req: Request): Promise<HandledRequest> {
+  if (
+    !req ||
+    typeof req !== "object" ||
+    typeof (req as Request).v !== "number"
+  ) {
+    return stay({
+      ok: false,
+      error: "malformed request",
+      code: "BAD_REQUEST",
+      daemonV: PROTOCOL_VERSION,
+    });
+  }
+
+  if (req.v !== PROTOCOL_VERSION) {
+    // [LAW:types-are-the-program] The asymmetry is data, not control flow.
+    //   client > daemon: the *binary* probably upgraded under us. Exit so the
+    //     next client respawns from the current artifact.
+    //   client < daemon: the *client* is stale. Respawning daemon does not
+    //     help (the new daemon will have the same version). Stay up and
+    //     return VERSION_MISMATCH — the client is responsible for surfacing
+    //     the diagnostic and refusing to kick. Shutting down here was the
+    //     load-bearing half of the 452-corpse spiral (kz8.5).
+    if (req.v > PROTOCOL_VERSION) {
+      dlog(
+        "info",
+        `version mismatch: client=${req.v} > daemon=${PROTOCOL_VERSION}; binary likely upgraded — exiting after the response flushes`,
+      );
+    } else {
+      dlog(
+        "info",
+        `version mismatch: client=${req.v} < daemon=${PROTOCOL_VERSION}; client is stale — staying up`,
+      );
+    }
+    return {
+      resp: {
+        ok: false,
+        error: `protocol v${req.v} not supported (daemon at v${PROTOCOL_VERSION})`,
+        code: "VERSION_MISMATCH",
+        daemonV: PROTOCOL_VERSION,
+      },
+      // [LAW:dataflow-not-control-flow] The asymmetry above is this value.
+      // Exit is sequenced on the response flush, so the client always sees
+      // the VERSION_MISMATCH diagnostic — never a dead socket.
+      exitAfterFlush: req.v > PROTOCOL_VERSION ? 0 : null,
+    };
+  }
+
+  if (req.kind === "shutdown") {
+    return { resp: { ok: true, output: "" }, exitAfterFlush: 0 };
+  }
+
+  if (req.kind === "stats") {
+    // [LAW:single-enforcer] Stats requests do NOT bump request counters —
+    // observability shouldn't pollute the metric being observed.
+    return stay({
+      ok: true,
+      stats: stats.snapshot({
+        gitCache: gitService.getStats(),
+        usageCache: usageStore.getStats(),
+        renderCacheSize: renderCache.size,
+        watchersActive: watcherRegistry.size(),
+        nextRestartReason: limits?.describeNextRestart() ?? null,
+      }),
+    });
+  }
+
+  if (req.kind === "render") {
+    stats.requestsTotal++;
+    const t0 = Date.now();
+    try {
+      // [LAW:single-enforcer] One trust-boundary check for incoming hookData.
+      // The validator reports missing/wrong-typed required fields and unknown
+      // top-level keys. Required-field problems are *protocol* failures
+      // (Claude Code's schema guarantees these — their absence means the
+      // sender is broken or malicious); unknown fields are advisory (Anthropic
+      // may have added something).
+      const { report } = validateHookData(req.hookData as unknown);
+      for (const field of report.unknownTopLevelFields) {
+        dlog(
+          "info",
+          `schema: unknown field '${field}' — Anthropic may have added it`,
+        );
+      }
+      // [LAW:no-silent-fallbacks][LAW:types-are-the-program] Gate hard on
+      // schema violations. Continuing with `workspace?.project_dir` would
+      // collapse "absent" into an empty-string cache key — silently sharing
+      // one entry across every malformed request — and downstream code would
+      // have to defend against an empty projectDir forever. Reject here so
+      // the types downstream carry the strongest true theorem: by the time
+      // a cache entry is built, projectDir/cwd are real non-empty strings.
+      const wireProblems: string[] = [];
+      for (const path of report.missingRequired) {
+        wireProblems.push(`missing required field '${path}'`);
+      }
+      for (const { path, expected, got } of report.typeMismatches) {
+        wireProblems.push(`field '${path}' expected ${expected}, got ${got}`);
+      }
+      if (req.cwd === "") {
+        wireProblems.push("request 'cwd' is empty");
+      }
+      if (wireProblems.length > 0) {
+        stats.requestsErrored++;
+        dlog("warn", `BAD_REQUEST: ${wireProblems.join("; ")}`);
+        return stay({
+          ok: false,
+          error: `malformed hookData: ${wireProblems.join("; ")}`,
+          code: "BAD_REQUEST",
+          daemonV: PROTOCOL_VERSION,
+        });
+      }
+      const projectDir = req.hookData.workspace.project_dir;
+      // [LAW:dataflow-not-control-flow] thread the *request's* cwd, not the
+      // daemon's process.cwd(), so config resolution depends only on request
+      // data — the daemon's own working directory must not influence output.
+      const { configFile, unknownFlagsError } = parseRenderArgs(req.args);
+      // [LAW:effects-at-boundaries] The load-config verb writes per-session
+      // config overrides into SessionState; this is the one read point.
+      const sessionId = req.hookData.session_id;
+      const sessionConfigFile =
+        sessionState.get(sessionId, SESSION_CONFIG_OVERRIDE_KEY) ?? configFile;
+      const entry = renderCache.getOrCreate(
+        projectDir,
+        req.cwd,
+        sessionConfigFile,
+      );
+      // [LAW:single-enforcer] Width capture lives at the wire boundary.
+      // The client (Rust + TTY) is the only process that can see the real
+      // terminal; the daemon is detached. We do NOT consult getTerminalWidth's
+      // env/stderr fallbacks here — they would let the daemon's stale
+      // launch-time COLUMNS env shape rendering for a different terminal,
+      // which is exactly the wrong source.
+      // [LAW:one-source-of-truth] Both branches feed raw cols through
+      // applyClaudeCodeReserve, so `width` always means "usable cells
+      // post-reserve" with no semantic split between wire-supplied and
+      // fallback values.
+      const termCols = sanitizeTermCols(req.termCols);
+      const width = applyClaudeCodeReserve(termCols ?? DEFAULT_TERMINAL_WIDTH);
+      const renderOpts: BuildLineOptions = { ...RENDER_OPTS_BASE, width };
+      // [LAW:dataflow-not-control-flow] Two outcomes fall out of one rule:
+      // body = state ? renderDsl(state) : "" ; output = body + icon
+      // No special-case branches — same composition every render.
+      let body = "";
+      if (entry.state !== null) {
+        const payload = await buildRenderPayload(
+          req.hookData,
+          payloadDeps,
+          req.cwd,
+          entry.state.neededInputPaths,
+        );
+        // [LAW:one-source-of-truth][LAW:dataflow-not-control-flow] basePalette
+        // is derived per render from the effective theme — the session's chosen
+        // theme (SessionState) over the config default — so a theme click
+        // recolors the whole bar on the next render. Not frozen on the cache
+        // entry (one entry serves many sessions). resolverForThemeName memoizes,
+        // so the per-render cost is one Map lookup once the theme is warm.
+        const basePalette = resolverForThemeName(
+          effectiveThemeName(
+            sessionState.get(req.hookData.session_id, "theme"),
+            entry.state.config.globals.palette,
+          ),
+        );
+        // [LAW:single-enforcer] renderDsl internally calls
+        // `registry.applyInput(payload)` as its first step (see step 1 in
+        // src/dsl/render.ts). The daemon must not pre-apply — doing so
+        // would run the MobX action twice per render and clear last_error
+        // diagnostics on the round trip.
+        body = renderDsl(
+          entry.state.config,
+          entry.state.compiled,
+          entry.state.store,
+          entry.state.registry,
+          payload,
+          basePalette,
+          renderOpts,
+          // [LAW:single-enforcer] The per-segment StripCell sink for the
+          // `debug segments` projection. Its identity stays stable for the
+          // cache entry's lifetime; renderDsl clears + repopulates it
+          // in place. Cells are cheap (already computed during the render);
+          // the per-segment ANSI serialization happens lazily inside the
+          // debug handler so normal renders pay no extra serializer cost.
+          entry.state.lastRenderCellsBySegment,
+        );
+      }
+      // [LAW:one-source-of-truth] Consume the transient click error written by
+      // dispatch on partial/total effect failure, then clear it so it shows
+      // exactly once. Only called when non-null to avoid a no-op persist+MobX
+      // tick on every render.
+      const clickError = sessionState.get(
+        req.hookData.session_id,
+        "click.error",
+      );
+      if (clickError)
+        sessionState.clear(req.hookData.session_id, "click.error");
+      const combinedError =
+        [unknownFlagsError, entry.lastError, clickError]
+          .filter(Boolean)
+          .join("\n") || null;
+      const output = composeWithDiagnostics(
+        body,
+        combinedError,
+        entry.lastWarning,
+      );
+      const ms = Date.now() - t0;
+      const g = gitService.getStats();
+      const u = usageStore.getStats();
+      dlog(
+        "info",
+        `render sid=${req.hookData.session_id ?? "?"} took=${ms}ms termCols=${termCols ?? "?"} width=${width} git=${g.size}/${g.hits}h/${g.misses}m usage=${u.size}/${u.hits}h/${u.misses}m err=${entry.lastError ? "Y" : "N"} warn=${entry.lastWarning ? "Y" : "N"}`,
+      );
+      return stay({ ok: true, output: output + "\n" });
+    } catch (e) {
+      stats.requestsErrored++;
+      throw e;
+    }
+  }
+
+  if (req.kind === "click") {
+    return stay(await handleClick(req.verb, req.value));
+  }
+
+  if (req.kind === "debug") {
+    // [LAW:single-enforcer] One trust-boundary check at the wire edge —
+    // `what` is untrusted JSON. isDebugWhat narrows it to the discriminated
+    // union the introspector consumes; an invalid value short-circuits
+    // here, not deep inside buildDebugSnapshot.
+    if (!isDebugWhat(req.what)) {
+      return stay({
+        ok: false,
+        // [LAW:errors-context-in-errors] Include the allowed values so a
+        // CLI consumer (or operator) sees what is supported without
+        // grep — same pattern as the set-state verb's unknown-key error
+        // in src/daemon/verbs/state-validators.ts.
+        error: `unknown debug 'what': ${String(req.what)} (have: ${DEBUG_WHATS.join(", ")})`,
+        code: "BAD_REQUEST",
+        daemonV: PROTOCOL_VERSION,
+      });
+    }
+    // [LAW:dataflow-not-control-flow] The debug projection samples whatever
+    // DSL state the cache currently holds. With cache keys scoped on
+    // (projectDir, cwd) and the debug request carrying neither, we sample
+    // the first populated existing entry — sufficient for `debug vars`,
+    // `debug segments`, `debug config` against the active workload.
+    // firstPopulatedState iterates existing entries only; it does NOT
+    // create a fresh one, so debug introspection never has the side effect
+    // of standing up a new (projectDir=undefined) cache entry tied to the
+    // daemon's own process.cwd(). A future debug-target selector would
+    // thread (projectDir, cwd) through the wire.
+    const dbgEntry = renderCache.firstPopulatedState();
+    // [LAW:dataflow-not-control-flow] Lazy per-segment serialization: the
+    // cache stores StripCell arrays (cheap, written by renderDsl).
+    // The debug projection needs strings, so serialize only for the
+    // `segments` projection (`vars` and `config` don't need it) and only
+    // when this request actually fires. Normal renders pay no per-segment
+    // serializer cost — that work shifts to debug-request time, which is
+    // operator-driven and rare.
+    const dbgState =
+      dbgEntry === null
+        ? null
+        : {
+            store: dbgEntry.store,
+            registry: dbgEntry.registry,
+            config: dbgEntry.config,
+            compiled: dbgEntry.compiled,
+            lastRenderBySegment:
+              req.what === "segments"
+                ? serializeSegmentCells(dbgEntry.lastRenderCellsBySegment)
+                : EMPTY_RENDER_MAP,
+          };
+    return stay({ ok: true, debug: buildDebugSnapshot(req.what, dbgState) });
+  }
+
+  return stay({
+    ok: false,
+    error: "unknown kind",
+    code: "BAD_REQUEST",
+    daemonV: PROTOCOL_VERSION,
+  });
+}
+
+// --- diagnostics composition ---
+//
+// [LAW:no-silent-fallbacks] Bad config can't quietly degrade output. The
+// render pipeline carries two independent diagnostic channels:
+//   error   — load-fatal: parse/validation failed; bar is last-known-good
+//             or empty. Rendered red.
+//   warning — advisory: load succeeded but something needs attention (e.g.
+//             same-location .json5 + .json collision). Rendered amber.
+// Either way the failure is visible at the point of impact, and each
+// channel has its own click verb (show-config-error / show-config-warning)
+// so the operator can copy the message to clipboard for inspection.
+//
+// [LAW:one-type-per-behavior] Two severities → two channels. The
+// composer's signature carries both; severity is encoded in WHICH
+// argument is non-null, not in a string prefix or a tag inside the
+// message. The two icons render independently — both can show at once.
+//
+// [LAW:types-are-the-program] The diagnostic's visible text IS (a
+// projection of) the underlying message — not a constant label that hides
+// the content behind a click. The leading ⚠ + background color carry
+// severity; the rest of the cell is the actual error/warning, sanitized
+// and clipped to a single-line budget. A label divorced from the message
+// would be the type lying about what's in the channel.
+// [LAW:one-source-of-truth] Style constants come from the shared leaf
+// (src/render/diagnostic-style.ts) — the same visual identity the client's
+// permanent glyph uses. Only the OSC-8 link plumbing is local here.
+const OSC8_OPEN = "\x1b]8;;";
+const OSC8_CLOSE = "\x1b]8;;\x1b\\";
+const ST = "\x1b\\";
+
+// [LAW:single-enforcer][LAW:no-silent-fallbacks] Parse render-path args with
+// the standard util at the trust boundary. `--config <path>` is the sole
+// valid render flag; every other flag is surfaced as a render-time
+// diagnostic icon (caller composes it alongside config errors). The
+// `--config` value is `~`-expanded here, so every consumer downstream
+// receives a literal path — no caller has to remember to expand it.
+//
+// `tokens: true, strict: false, allowPositionals: true` together let the
+// parser emit a token entry for every flag (known or unknown) without
+// throwing on unknown ones, and without mis-classifying their values as
+// positionals.
+function parseRenderArgs(args: string[]): {
+  configFile: string | undefined;
+  unknownFlagsError: string | null;
+} {
+  const { values, tokens } = parseArgs({
+    args: args.slice(1), // skip binary path
+    options: { config: { type: "string" } },
+    strict: false,
+    tokens: true,
+    allowPositionals: true,
+  });
+  const unknown = [
+    ...new Set(
+      (tokens ?? [])
+        .filter(
+          (t): t is Extract<typeof t, { kind: "option" }> =>
+            t.kind === "option" && t.name !== "config",
+        )
+        .map((t) => `--${t.name}`),
+    ),
+  ];
+  const rawConfig = values.config as string | undefined;
+  return {
+    configFile: rawConfig === undefined ? undefined : expandHome(rawConfig),
+    unknownFlagsError:
+      unknown.length > 0 ? `Unknown flags: ${unknown.join(", ")}` : null,
+  };
+}
+
+// Per-line visible budget and max rows for multi-line diagnostic blocks.
+// Messages from the config validator (formatIssues) are already structured
+// as one line per issue, so splitting there is the natural unit of display.
+// Deliberately decoupled from DEFAULT_TERMINAL_WIDTH: that constant means
+// "raw terminal cols we assume" and is reserved-against before reaching the
+// renderer; this one is a direct visible-char cap on already-rendered
+// diagnostic text. They happen to share the value 120 today but have
+// different semantic intents.
+const MAX_DIAGNOSTIC_LINE_LEN = 120;
+const MAX_DIAGNOSTIC_LINES = 8;
+
+function makeDiagnosticLink(
+  verb: typeof VERB_SHOW_CONFIG_ERROR | typeof VERB_SHOW_CONFIG_WARNING,
+  message: string,
+  bg: string,
+  fg: string,
+): string {
+  // Full message in the OSC-8 URL (clipboard-copy on click) — truncation
+  // only affects what is visible, never what is accessible. [LAW:single-enforcer]
+  // The click URL is born through effectsUrl like every other click — one
+  // single-effect dispatch list, no second URL-format in the codebase.
+  const url = effectsUrl([{ verb, args: [message] }]);
+  // [LAW:dataflow-not-control-flow] Split on natural line boundaries from
+  // the source message (config validator emits one issue per line), sanitize
+  // each line individually, then render each as a separate styled row.
+  // This preserves structured multi-line output instead of collapsing N
+  // issues into a single truncated string the user cannot read.
+  const lines = message
+    .split(/\r\n|\r|\n/)
+    .map((l) => sanitizeAndTruncate(l, MAX_DIAGNOSTIC_LINE_LEN))
+    .filter(Boolean)
+    .slice(0, MAX_DIAGNOSTIC_LINES);
+  if (lines.length === 0) return "";
+  const first = `${OSC8_OPEN}${url}${ST}${bg}${fg} ⚠ ${lines[0]} ${ANSI_RESET}${OSC8_CLOSE}`;
+  const rest = lines
+    .slice(1)
+    .map(
+      (l) =>
+        `${OSC8_OPEN}${url}${ST}${bg}${fg}   ${l} ${ANSI_RESET}${OSC8_CLOSE}`,
+    );
+  return [first, ...rest].join("\n");
+}
+
+function composeWithDiagnostics(
+  body: string,
+  error: string | null,
+  warning: string | null,
+): string {
+  // [LAW:dataflow-not-control-flow] Diagnostics list is data; the
+  // composer walks it. Each non-null channel contributes one or more prefix
+  // rows (makeDiagnosticLink returns a \n-joined multi-line block when the
+  // message has natural line breaks). Order is error-first (more severe),
+  // then warning, then body.
+  const prefixes: string[] = [];
+  if (error) {
+    prefixes.push(
+      makeDiagnosticLink(
+        VERB_SHOW_CONFIG_ERROR,
+        error,
+        DIAGNOSTIC_ERROR_BG,
+        DIAGNOSTIC_ERROR_FG,
+      ),
+    );
+  }
+  if (warning) {
+    prefixes.push(
+      makeDiagnosticLink(
+        VERB_SHOW_CONFIG_WARNING,
+        warning,
+        DIAGNOSTIC_WARNING_BG,
+        DIAGNOSTIC_WARNING_FG,
+      ),
+    );
+  }
+  if (prefixes.length === 0) return body;
+  // No body → emit the diagnostic strip alone (startup-error case). Body
+  // present → prepend on its own line so it's visible regardless of bar
+  // width. Multiple diagnostics stack on their own lines.
+  const strip = prefixes.join("\n");
+  return body ? `${strip}\n${body}` : strip;
+}
+
+// --- click verb dispatch ---
+// [LAW:dataflow-not-control-flow] The dispatcher is a table lookup. The verb
+// table (src/daemon/verbs/index.ts) is the single canonical list of supported
+// verbs — handlers live there, the dispatcher only routes.
+//
+// [LAW:types-are-the-program] The error class on the throw determines the
+// response code: BadVerbArgs (invalid input shape) becomes BAD_REQUEST; any
+// other Error (operational failure) becomes RENDER_FAILED. No string matching.
+
+const verbCtx = { sessionState, dlog };
+
+// [LAW:single-enforcer] Style + color compatibility shared by the render
+// path and the lazy debug-side per-segment serializer. Per-request `width`
+// is composed on top at the wire boundary (handleRequest("render")) and
+// passed through as renderOpts. Debug serialization composes its own
+// per-segment opts with width: Number.POSITIVE_INFINITY since each segment
+// is rendered standalone (wrap doesn't apply to a one-segment projection).
+const RENDER_OPTS_BASE = {
+  style: "powerline" as const,
+  colorCompatibility: "truecolor" as const,
+};
+const DEBUG_RENDER_OPTS: BuildLineOptions = {
+  ...RENDER_OPTS_BASE,
+  width: Number.POSITIVE_INFINITY,
+};
+
+// [LAW:no-defensive-null-guards] Reused empty map for the `vars` /
+// `config` debug projections — they don't read lastRenderBySegment but
+// the DaemonDslState type requires the field.
+const EMPTY_RENDER_MAP = new Map<string, string>();
+
+function serializeSegmentCells(
+  cells: ReadonlyMap<string, readonly RichText[]>,
+): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const [name, segCells] of cells) {
+    out.set(name, renderStripCells(segCells, DEBUG_RENDER_OPTS));
+  }
+  return out;
+}
+
+// [LAW:single-enforcer] The payload-builder dependency bundle. One value
+// passed through every render — the data the daemon brings to each tick.
+const payloadDeps = {
+  gitProvider: gitService,
+  usageStore,
+  contextProvider,
+  metricsProvider,
+  tmuxService,
+  sessionState,
+  // [LAW:single-enforcer] buildRenderPayload is the one log site for the
+  // outcome-carrying provider lanes (git, cache).
+  log: dlog,
+};
+
+function handleClick(verb: string, value: string): Response {
+  const handler = VERBS.get(verb);
+  if (!handler) {
+    return {
+      ok: false,
+      error: `unknown click verb: ${verb}`,
+      code: "BAD_REQUEST",
+      daemonV: PROTOCOL_VERSION,
+    };
+  }
+  try {
+    handler(value, verbCtx);
+    return { ok: true, output: "" };
+  } catch (e) {
+    const code = e instanceof BadVerbArgs ? "BAD_REQUEST" : "RENDER_FAILED";
+    return {
+      ok: false,
+      error: String(e instanceof Error ? e.message : e),
+      code,
+      daemonV: PROTOCOL_VERSION,
+    };
+  }
+}