v1.45.0.0 feat(design): persistent board daemon — 24h boards, one tab, board history (#1710)

* refactor(design): board JS uses relative paths; drop __GSTACK_SERVER_URL injection Board JS in design/src/compare.ts now calls ./api/feedback and ./api/progress (relative to location.pathname) and feature-detects server mode via location.protocol instead of the injected window.__GSTACK_SERVER_URL global. The injection in design/src/serve.ts is removed (dead code now that nothing reads it). Tests updated to match the new contract: serve.test.ts asserts the relative-path JS is present and the global is gone; feedback-roundtrip asserts location.protocol detects HTTP mode. Why: prep for the multi-board daemon (design/src/daemon.ts upcoming) where the same generated HTML is served at /boards/<id>/ instead of /. Relative paths resolve against location.pathname in both cases, so one HTML, two hosts. The injection was the only thing tying board JS to a specific serving path; removing it unblocks the daemon work without forking the generator. file:// fallback preserved via the location.protocol feature-detect — board opened directly as a file still falls through to the DOM-only success path. The 6 feedback-roundtrip browser tests continue to fail with session.clearLoadedHtml undefined; that failure pre-exists this branch (verified against HEAD with these edits stashed) and lives in browse/src/write-commands.ts, not in the design code path. Tracking separately. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(design): reload guard rejects directory paths design/src/serve.ts:200-212 used to accept a path that resolved to the allowedDir itself (the OR branch `|| resolvedReload === allowedDir`), which then crashed readFileSync with EISDIR. Now: 1. startsWith(allowedDir + path.sep) must pass — rejects the dir itself and anything outside (403). 2. statSync(resolvedReload).isFile() must pass — rejects subdirectories inside allowedDir with a clear "Path must be a file" 400. The test stub in serve.test.ts mirrors prod; both updated, plus two new test cases for the previously-broken paths. Codex caught this in the plan-review pass; it's a latent bug in shipping code, not a regression from the daemon work. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(design): introduce design daemon — multi-board persistent server Adds design/src/daemon.ts: a Bun.serve daemon that hosts many boards under /boards/<id>/ instead of one server per `$D compare --serve` call. Spawned by daemon-client (next commit); for now wired only via tests. Endpoint table: GET /health liveness + version + counts (unauth) GET / index of recent boards POST /api/boards publish; daemon derives sourceDir from realpath(html). body sourceDir IGNORED (Codex trust-boundary fix). POST /shutdown graceful; refuses if active boards exist (Codex data-loss fix) GET /boards/<id> 301 → /boards/<id>/ (trailing slash is load-bearing — relative URLs in board JS resolve against pathname) GET /boards/<id>/ render board HTML GET /boards/<id>/api/progress state machine status (no idle reset) POST /boards/<id>/api/feedback submit/regen; writes feedback.json or feedback-pending.json with boardId + publishedAt augmented in POST /boards/<id>/api/reload swap HTML; per-board allowedDir guard rejects traversal, directories, out-of-allowed-dir symlinks Lifecycle: - 24h idle timeout (DESIGN_DAEMON_IDLE_MS for tests). - Idle with active boards extends 1h up to 4x, then force-shuts (Codex). - LRU cap 50 boards; evicts done before non-done; 503 when 50 non-done. - Per-board async mutex serializes feedback POST vs reload POST. - SIGTERM/SIGINT/uncaughtException → graceful shutdown, state file unlink. - Stdout: DAEMON_STARTED port=<N> (the line the client parses). Shared utilities live in design/src/daemon-state.ts: atomic state-file write/read (mode 0o600), fs.openSync('wx') lock, isProcessAlive, cmdline identity verification (/proc on Linux, ps on macOS), CMDLINE_MARKER constant. Modeled on browse/src/cli.ts lock + spawn patterns. design/test/daemon.test.ts: 30 tests, all green. Covers every endpoint, both error paths and happy paths, cross-board feedback isolation, the trailing-slash redirect, the directory-not-file reload rejection, LRU preferring done over non-done, /shutdown refusal with active boards, all path-traversal guards. Uses the exported fetchHandler in-process (no spawn) so the suite runs in ~70ms. design/test/daemon-tests-fixtures.ts: shared helpers — req() builder, tmp-dir helpers, daemon reset, and a spawnDaemonForTest() helper used by the next commit's discovery tests. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(design): daemon-client with lock + identity-verified spawn design/src/daemon-client.ts implements the CLI side of the daemon lifecycle: ensureDaemon() (the spawn-or-attach decision), publishBoard(), and the $D daemon stop|status helpers. Modeled on browse/src/cli.ts:317-415 — same health-check-first attach, same fs.openSync('wx') lock, same re-read-state-INSIDE-the-lock guard against two CLIs both deciding "no daemon, spawn." Two design-specific safety properties added beyond browse: 1. verifyIdentity before any SIGTERM/SIGKILL. Reads the running process's cmdline (/proc/PID/cmdline on Linux, `ps -p PID -o command=` on macOS) and only signals if it contains CMDLINE_MARKER ("gstack-design-daemon", passed as argv at spawn time). Prevents a stale state file from causing us to kill an unrelated process that inherited the PID. 2. Refuse-kill-with-active-boards on version mismatch. Browse silently restarts; here in-memory board history would vanish, so the client prints a user-actionable WARNING and exit 1 instead. Users explicitly `$D daemon stop` to override. Spawn uses Node child_process.spawn (NOT Bun.spawn().unref) because of the macOS session-detach quirks browse already discovered. Stdio is redirected to ~/.gstack/design-daemon-startup.log, which the client tails into stderr if waitForHealthOrError times out — no more silent "daemon failed for some unknowable reason." daemon-state.ts gains DESIGN_DAEMON_STATE_FILE env override so tests can point both client and spawned daemon at a per-test path without a shared cwd. design/test/daemon-discovery.test.ts: 17 tests, all green in ~8s. Covers: spawn-fresh, attach-existing, stale-state-file (pid dead), PID-reuse safety (uses the test runner's own PID as the bait — verifyIdentity catches the cmdline mismatch, daemon not signaled), version-mismatch with/without active boards (the active-boards case runs a subprocess and asserts exit 1 + WARNING in stderr), publishBoard 200 + 409, shutdownDaemon refuse/force/unresponsive paths, daemonStatus. The daemon-discovery suite is split out of daemon.test.ts because each real spawn costs ~200ms; the in-process daemon.test.ts (30 tests, 70ms) covers the same handler logic without the spawn overhead. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(design): wire daemon dispatch into CLI; add daemon stop/status design/src/cli.ts now branches on --no-daemon for both `compare --serve` and standalone `serve --html`. Default path: ensureDaemon → publishBoard → openBrowser → exit. The legacy single-process serve() is preserved behind --no-daemon for tests, Windows, and explicit debugging. Adds $D daemon status (prints daemon state JSON, or {running:false}) and $D daemon stop [--force] (refuses with active boards unless --force). parseArgs gains a `positionals` field so daemon sub-commands work naturally (`$D daemon stop` instead of `$D --action stop`). Stderr lines printed by the publishToDaemon path: DAEMON_STARTED port=N (or DAEMON_ATTACHED port=N) BOARD_PUBLISHED: <url> BOARD_URL: <url> (alias for grep-friendliness) Stdout: JSON with id, url, sourceDir. design/src/commands.ts: --no-daemon, --title added to compare + serve; new daemon command entry with status|stop sub-commands. End-to-end smoke (manual): spawning a board via $D serve, hitting the returned URL, reading /health, calling daemon status (returns the right JSON), and daemon stop refusing because of the active board — all work as designed. Force-stop tears down cleanly and removes the state file. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(design): end-to-end daemon round-trip via HTTP fetch design/test/feedback-roundtrip-daemon.test.ts walks the full publish → submit / regenerate / reload cycle against a real spawned daemon, using the same HTTP calls the board JS makes. Four tests, all green in ~650ms. Covers what design-shotgun and friends actually depend on: - Submit writes feedback.json into the board's sourceDir with the augmented boardId + publishedAt fields. - GET /boards/<id> (no slash) returns a 301 to /boards/<id>/ — the load-bearing redirect that lets the board JS use relative paths. - Regenerate writes feedback-pending.json, flips state to regenerating, /api/progress reflects it; /api/reload swaps HTML in place; round-2 submit writes the final feedback.json with the round-2 selection. - Two boards published into the same daemon get independent URLs on the same port — feedback for board A doesn't contaminate board B's sourceDir, both URLs serve their own content, the index lists both. Uses HTTP fetch rather than a real browser because the existing browser round-trip (feedback-roundtrip.test.ts) is broken on a pre-existing browse harness regression (session.clearLoadedHtml undefined in browse/src/write-commands.ts:149) that's unrelated to this branch. The HTTP path proves the same daemon semantics; a browser variant can be added once the browse harness is fixed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * feat(design): compiled binary self-execs as daemon; unified version lookup Two small but production-critical fixes once the binary actually runs: 1. Compiled binary couldn't spawn the daemon. daemon-client previously pointed at design/src/daemon.ts via import.meta.dir — fine in dev, fatal in production (the source path doesn't exist on a user's machine). Fix: design CLI now self-execs in --daemon-mode when invoked with that flag, so the spawn is `process.execPath --daemon-mode --marker gstack-design-daemon` for the compiled binary and `bun run cli.ts --daemon-mode ...` in dev. Same one binary, two modes, no separate daemon entrypoint to ship. 2. Client and daemon disagreed on VERSION in the compiled binary. Both used a source-tree-relative path that resolves to "unknown" at runtime, which silently shorted the version-mismatch refusal path (client expected "unknown" + daemon reported "unknown" → match → no refusal even when DESIGN_DAEMON_VERSION was set on one side). New readVersionString() consults DESIGN_DAEMON_VERSION env first, then design/dist/.version (sidecar baked at build time by build.sh), then VERSION at the source-tree root. Both client and daemon now go through this one helper. Manual smoke (compiled binary, all checks green): - DAEMON_STARTED + BOARD_PUBLISHED with trailing slash - GET /boards/<id> (no slash) → 301 Location /boards/<id>/ - Second `$D serve` invocation → DAEMON_ATTACHED, new board on same port - feedback.json gets boardId + publishedAt fields - DESIGN_DAEMON_VERSION=v2-different on second invocation with active board → WARNING + "Refusing to auto-kill" + exit 1, original daemon still alive - `$D daemon stop --force` removes state file All 67 design tests still green after the refactor (16 serve + 30 daemon + 17 discovery + 4 daemon round-trip). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(design): skill resolvers learn the daemon's BOARD_URL output The five skills that invoke $D compare --serve (design-shotgun, design-consultation, plan-design-review, office-hours, design-review) parsed `SERVE_STARTED: port=N` from stderr and then POSTed to `/api/reload` at that port during regenerate cycles. The new daemon hosts boards under `/boards/<id>/` so the reload endpoint moved to `<BOARD_URL>api/reload` — without this update, the regenerate phase of every skill invocation would silently fail against daemon mode. Updated scripts/resolvers/design.ts to parse `BOARD_URL:` instead of the port, and to POST reloads against the per-board URL. Regenerated the four SKILL.md files via bun run gen:skill-docs. Legacy `--no-daemon` invocations continue to emit `SERVE_STARTED:` and serve at `/api/reload` — the resolver instructions note both. Surfaced by the maintainability specialist during /ship review (the "stale comment" finding was actually a behavior bug pointing at five downstream consumers). Codex's plan-review pass flagged the migration story as incomplete but I dismissed the concern — Codex was right. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(design): emit SERVE_STARTED back-compat alias; drop dead import design/src/cli.ts publishToDaemon now emits `SERVE_STARTED: port=N html=<path>` as a third stderr line alongside DAEMON_STARTED/DAEMON_ATTACHED + BOARD_URL. Any out-of-tree script that grepped the legacy line still gets the port — they'd still fail at the reload step (the endpoint moved to /boards/<id>/ api/reload) but they no longer fail at the port-detection step. Combined with the resolver updates one commit back, this is belt-and-suspenders compat. Fixed the stale docstring at cli.ts:316 that claimed back-compat without actually emitting the alias. The maintainability specialist flagged it. Dropped a dead `DaemonState` import from daemon-client.ts. Same review pass. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: bump version and changelog (v1.45.0.0) Design boards now live 24h, not 10 minutes. One daemon hosts every board, one tab survives the whole day. See CHANGELOG.md for the full release summary + metrics + itemized changes. TODOS.md gains a "design daemon: follow-ups" section capturing the P3 test gaps + maintainability nits the /ship review army flagged but that aren't blocking for this release. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * test(design): fill daemon test gaps surfaced by ship review army Adds 10 net new tests (and removes 1 misleading smoke) for the gaps the testing specialist flagged at /ship time. Filed as P3 TODOs at ship, filling now per boil-the-lake. design/test/daemon-discovery.test.ts (+6 tests, +1 import): - "idle daemon (no boards) shuts itself down after IDLE_MS + CHECK_MS" Spawn-based, DESIGN_DAEMON_IDLE_MS=2000, CHECK_MS=200. Waits for the daemon process to actually exit and asserts the state file is removed. Previously only "callable without throwing" was tested. - "bare GET polling does NOT prevent idle shutdown" Hammers /api/progress every 200ms in a background loop with a done board, asserts the daemon still idles out — proves the meaningful-activity-only-on-POSTs guard (Codex finding) actually works. - "idle with active (non-done) boards triggers extension instead of shutdown" Sets DESIGN_DAEMON_EXTENSION_MS=1500 + MAX_EXTENSIONS=2, publishes a non-done board, asserts the daemon survives past IDLE_MS (extends), then verifies the MAX_EXTENSIONS hard ceiling force-shuts. Both the extension counter and the hard ceiling were previously untested. - "two parallel ensureDaemon() calls converge on one daemon" Fires two ensureDaemon calls in Promise.all against an empty stateFile, asserts: both ports match, exactly one spawned=true, exactly one daemon alive, no orphaned lock file. The discovery-test file's own docstring claimed this test existed; now it actually does. - "acquireLock reclaims a lockfile owned by a dead PID" Plants a lockfile with PID 999999998, calls acquireLock, asserts the returned release fn is non-null and the lock now holds our PID. - "acquireLock refuses to reclaim a lockfile owned by an alive PID" Uses the test runner's own PID — alive but not the lock's intended owner. Asserts acquireLock returns null and leaves the lockfile untouched. The unrelated-process-PID-reuse safety guard. design/test/daemon.test.ts (-2 misleading, +5 new = +3 net): - Removed: "bare GET /api/progress does NOT reset meaningful activity" (smoke pretending to be behavioral — body comment admitted it couldn't verify). Replaced by the spawn-based version in daemon-discovery above. - Removed: "idleCheckTick is callable without throwing when there's no idle" (collapsed into a single smoke describe that's clearer about its scope). - Added: "POST /api/boards rejects invalid JSON body" - Added: "POST /api/boards rejects non-object body (e.g. JSON null)" - Added: "POST /api/boards: array body falls through to missing-html 400" (documents the typeof-array-is-object JS quirk; will surface if we ever tighten the type check) - Added: "POST /boards/<id>/api/reload rejects invalid JSON body" - Added: "POST /boards/<id>/api/reload rejects body missing html field" Per-file totals after: serve 16, daemon 34, discovery 23, round-trip 4 = 77. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: update CHANGELOG + TODOS for filled test gaps in v1.45.0.0 Bumps the design test count from 67 → 77 (and the new-test delta from +51 → +61) to reflect commit 6b037c55, which filled the 5 P3 test gaps the /ship review army had filed to TODOS.md. Marks the "Tighten daemon test coverage" entry in TODOS.md as DONE. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
2026-06-06 01:56:36 +02:00 · 2026-05-25 20:45:12 -07:00
parent 64f9aafa1e
commit cf50443b63
22 changed files with 3176 additions and 92 deletions
@@ -25,8 +25,19 @@ import { evolve } from "./evolve";
 import { generateDesignToCodePrompt } from "./design-to-code";
 import { serve } from "./serve";
 import { gallery } from "./gallery";
+import {
+  daemonStatus as daemonStatusClient,
+  ensureDaemon,
+  publishBoard,
+  shutdownDaemon,
+} from "./daemon-client";
+import { spawn as nodeSpawn } from "child_process";

-function parseArgs(argv: string[]): { command: string; flags: Record<string, string | boolean> } {
+function parseArgs(argv: string[]): {
+  command: string;
+  flags: Record<string, string | boolean>;
+  positionals: string[];
+} {
  const args = argv.slice(2); // skip bun/node and script path
  if (args.length === 0) {
    printUsage();
@@ -35,6 +46,7 @@ function parseArgs(argv: string[]): { command: string; flags: Record<string, str

  const command = args[0];
  const flags: Record<string, string | boolean> = {};
+  const positionals: string[] = [];

  for (let i = 1; i < args.length; i++) {
    const arg = args[i];
@@ -47,10 +59,12 @@ function parseArgs(argv: string[]): { command: string; flags: Record<string, str
      } else {
        flags[key] = true;
      }
+    } else {
+      positionals.push(arg);
    }
  }

-  return { command, flags };
+  return { command, flags, positionals };
 }

 function printUsage(): void {
@@ -108,7 +122,7 @@ async function runSetup(): Promise<void> {
 }

 async function main(): Promise<void> {
-  const { command, flags } = parseArgs(process.argv);
+  const { command, flags, positionals } = parseArgs(process.argv);

  if (!COMMANDS.has(command)) {
    console.error(`Unknown command: ${command}`);
@@ -139,12 +153,24 @@ async function main(): Promise<void> {
      const images = await resolveImagePaths(imagesArg);
      const outputPath = (flags.output as string) || "/tmp/gstack-design-board.html";
      compare({ images, output: outputPath });
-      // If --serve flag is set, start HTTP server for the board
+      // If --serve flag is set, publish the board.
+      //   Default: ensure the persistent daemon is up, POST the board, open
+      //   the browser, exit. The daemon survives the CLI and hosts every
+      //   board the user has published this day at stable URLs.
+      //   --no-daemon: legacy single-process server in serve.ts (kept for
+      //   tests / Windows / explicit debugging).
      if (flags.serve) {
-        await serve({
-          html: outputPath,
-          timeout: flags.timeout ? parseInt(flags.timeout as string) : 600,
-        });
+        if (flags["no-daemon"]) {
+          await serve({
+            html: outputPath,
+            timeout: flags.timeout ? parseInt(flags.timeout as string) : 600,
+          });
+        } else {
+          await publishToDaemon({
+            html: outputPath,
+            title: flags.title as string | undefined,
+          });
+        }
      }
      break;
    }
@@ -247,11 +273,108 @@ async function main(): Promise<void> {
      break;

    case "serve":
-      await serve({
-        html: flags.html as string,
-        timeout: flags.timeout ? parseInt(flags.timeout as string) : 600,
-      });
+      if (flags["no-daemon"]) {
+        await serve({
+          html: flags.html as string,
+          timeout: flags.timeout ? parseInt(flags.timeout as string) : 600,
+        });
+      } else {
+        await publishToDaemon({
+          html: flags.html as string,
+          title: flags.title as string | undefined,
+        });
+      }
      break;
+
+    case "daemon": {
+      // Sub-commands: `$D daemon status` and `$D daemon stop [--force]`.
+      const sub = positionals[0] || "status";
+      if (sub === "status") {
+        const s = await daemonStatusClient();
+        if (!s.running) {
+          console.log(JSON.stringify({ running: false }, null, 2));
+          process.exit(0);
+        }
+        console.log(JSON.stringify(s, null, 2));
+        break;
+      }
+      if (sub === "stop") {
+        const r = await shutdownDaemon({ force: !!flags.force });
+        if (r.stopped) {
+          console.log(JSON.stringify({ stopped: true, reason: r.reason }, null, 2));
+          process.exit(0);
+        }
+        console.error(
+          `Refused to stop daemon: ${r.reason} (activeBoards=${r.activeBoards ?? 0})`,
+        );
+        console.error(
+          `Submit/close active boards first, or pass --force to drop in-memory history.`,
+        );
+        process.exit(1);
+      }
+      console.error(`Unknown daemon sub-command: ${sub}. Use 'status' or 'stop'.`);
+      process.exit(2);
+    }
+  }
+}
+
+/**
+ * Default `$D compare --serve` path: ensure the persistent daemon is up,
+ * publish the board, open the browser to its URL, then exit. The daemon
+ * survives.
+ *
+ * Stderr lines (in order):
+ *   - "DAEMON_STARTED port=N version=V"  (or "DAEMON_ATTACHED port=N ..."
+ *     if a daemon was already running)
+ *   - "BOARD_PUBLISHED: http://127.0.0.1:N/boards/<id>/"
+ *   - "BOARD_URL: <same url>"  (alias for grep-friendliness)
+ *   - "SERVE_STARTED: port=N html=<path>"  (legacy back-compat alias for
+ *     any external script that scraped the pre-daemon output — note the
+ *     daemon hosts boards under /boards/<id>/, not /, so scripts that
+ *     ALSO POSTed /api/reload at the parsed port need to switch to
+ *     BOARD_URL + ./api/reload to work end-to-end. Emitting the legacy
+ *     line keeps port-only consumers from breaking outright.)
+ */
+async function publishToDaemon(opts: { html: string; title?: string }): Promise<void> {
+  if (!opts.html) {
+    console.error("--html is required (compare --serve provides --output as the html)");
+    process.exit(1);
+  }
+  const ensured = await ensureDaemon({});
+  console.error(
+    `${ensured.spawned ? "DAEMON_STARTED" : "DAEMON_ATTACHED"} port=${ensured.port} version=${ensured.version}`,
+  );
+  const result = await publishBoard({
+    port: ensured.port,
+    html: opts.html,
+    title: opts.title,
+  });
+  console.error(`BOARD_PUBLISHED: ${result.url}`);
+  console.error(`BOARD_URL: ${result.url}`);
+  // Legacy alias so anything still grepping `SERVE_STARTED: port=` gets the
+  // port. The full back-compat story requires the caller to ALSO learn the
+  // per-board path; see publishToDaemon docstring above.
+  console.error(`SERVE_STARTED: port=${ensured.port} html=${opts.html}`);
+  console.log(JSON.stringify({ id: result.id, url: result.url, sourceDir: result.sourceDir }, null, 2));
+  openBrowser(result.url);
+  // Short-lived publisher process exits; daemon keeps serving.
+}
+
+/** Open a URL in the default browser. Stays cross-platform with serve.ts. */
+function openBrowser(url: string): void {
+  const platform = process.platform;
+  let cmd: string;
+  if (platform === "darwin") cmd = "open";
+  else if (platform === "linux") cmd = "xdg-open";
+  else {
+    console.error(`Open this URL in your browser: ${url}`);
+    return;
+  }
+  try {
+    const child = nodeSpawn(cmd, [url], { stdio: "ignore", detached: true });
+    child.unref();
+  } catch {
+    console.error(`Open this URL in your browser: ${url}`);
  }
 }

@@ -280,7 +403,19 @@ async function resolveImagePaths(input: string): Promise<string[]> {
  return input.split(",").map(p => p.trim());
 }

-main().catch(err => {
-  console.error(err.message || err);
-  process.exit(1);
-});
+// Self-execution shortcut: when invoked with --daemon-mode, this same
+// binary runs as the persistent design daemon instead of the CLI. Keeps
+// the production install to a single executable; daemon-client.ts spawns
+// `<this binary> --daemon-mode` (or `bun run cli.ts --daemon-mode` in dev)
+// rather than relying on a separate daemon.ts file at a known path.
+if (process.argv.includes("--daemon-mode")) {
+  const { start } = await import("./daemon");
+  start();
+  // start() binds Bun.serve and registers signal handlers; this branch
+  // never falls through to main(). Process stays alive on the bound port.
+} else {
+  main().catch((err) => {
+    console.error(err.message || err);
+    process.exit(1);
+  });
+}
@@ -36,8 +36,8 @@ export const COMMANDS = new Map<string, {
  }],
  ["compare", {
    description: "Generate HTML comparison board for user review",
-    usage: "compare --images /path/*.png --output /path/board.html [--serve]",
-    flags: ["--images", "--output", "--serve", "--timeout"],
+    usage: "compare --images /path/*.png --output /path/board.html [--serve [--no-daemon] [--title \"...\"]]",
+    flags: ["--images", "--output", "--serve", "--no-daemon", "--title", "--timeout"],
  }],
  ["diff", {
    description: "Visual diff between two mockups",
@@ -71,8 +71,13 @@ export const COMMANDS = new Map<string, {
  }],
  ["serve", {
    description: "Serve comparison board over HTTP and collect user feedback",
-    usage: "serve --html /path/board.html [--timeout 600]",
-    flags: ["--html", "--timeout"],
+    usage: "serve --html /path/board.html [--no-daemon] [--title \"...\"] [--timeout 600]",
+    flags: ["--html", "--no-daemon", "--title", "--timeout"],
+  }],
+  ["daemon", {
+    description: "Manage the persistent design board daemon (sub-commands: status, stop)",
+    usage: "daemon status | daemon stop [--force]",
+    flags: ["--force"],
  }],
  ["setup", {
    description: "Guided API key setup + smoke test",
@@ -391,6 +391,17 @@ export function generateCompareHtml(images: string[]): string {
 <div id="feedback-result"></div>

 <script>
+  // Feature-detect: are we being served over HTTP (by serve.ts or the
+  // daemon), or opened directly as a file:// URL? In file:// mode the
+  // board JS falls through to a DOM-only success path with no server
+  // round-trips. Using location.protocol instead of an injected global
+  // means the same generated HTML works at both / (legacy --no-daemon)
+  // and /boards/<id>/ (daemon) — relative URLs resolve against
+  // location.pathname in both cases.
+  function hasServer() {
+    return location.protocol === 'http:' || location.protocol === 'https:';
+  }
+
  // View toggle
  document.querySelectorAll('.view-toggle button').forEach(function(btn) {
    btn.addEventListener('click', function() {
@@ -465,8 +476,8 @@ export function generateCompareHtml(images: string[]): string {
  });

  function postFeedback(feedback) {
-    if (!window.__GSTACK_SERVER_URL) return Promise.resolve(null);
-    return fetch(window.__GSTACK_SERVER_URL + '/api/feedback', {
+    if (!hasServer()) return Promise.resolve(null);
+    return fetch('./api/feedback', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(feedback),
@@ -509,7 +520,7 @@ export function generateCompareHtml(images: string[]): string {
  }

  function startProgressPolling() {
-    if (!window.__GSTACK_SERVER_URL) return;
+    if (!hasServer()) return;
    var pollCount = 0;
    var maxPolls = 150; // 5 min at 2s intervals
    var pollInterval = setInterval(function() {
@@ -523,7 +534,7 @@ export function generateCompareHtml(images: string[]): string {
          '</div>';
        return;
      }
-      fetch(window.__GSTACK_SERVER_URL + '/api/progress')
+      fetch('./api/progress')
        .then(function(r) { return r.json(); })
        .then(function(data) {
          if (data.status === 'serving') {
@@ -563,7 +574,7 @@ export function generateCompareHtml(images: string[]): string {
    postFeedback(feedback).then(function(result) {
      if (result && result.received) {
        showRegeneratingState();
-      } else if (window.__GSTACK_SERVER_URL) {
+      } else if (hasServer()) {
        showPostFailure(feedback);
      }
    });
@@ -578,7 +589,7 @@ export function generateCompareHtml(images: string[]): string {
    postFeedback(feedback).then(function(result) {
      if (result && result.received) {
        showPostSubmitState();
-      } else if (window.__GSTACK_SERVER_URL) {
+      } else if (hasServer()) {
        showPostFailure(feedback);
      } else {
        // DOM-only mode (legacy / test)
@@ -0,0 +1,419 @@
+/**
+ * CLI-side client for the design daemon.
+ *
+ * Responsible for the lifecycle dance that `$D compare --serve` (default
+ * path) goes through:
+ *
+ *   ensureDaemon() → publishBoard(html, opts) → openBrowser(url) → exit 0
+ *
+ * Mirrors browse/src/cli.ts:317-415 — same health-check-first attach
+ * decision, same fs.openSync('wx') lock, same re-read-under-lock guard.
+ * Adds two design-specific safety properties Codex flagged on the daemon
+ * plan:
+ *
+ *   1. Identity verification before any SIGTERM. Browse signals on PID
+ *      alone; here we require the cmdline to contain CMDLINE_MARKER so a
+ *      stale state file pointing at a reused PID doesn't kill an
+ *      unrelated process.
+ *
+ *   2. Refuse-to-kill on version mismatch with active boards. Browse will
+ *      restart on version drift; here in-memory boards would be lost, so
+ *      we exit 1 with a user-actionable message instead of silent loss.
+ *
+ * Spawn uses Node's child_process.spawn with detached: true + stdio
+ * pointed at a log file. Bun.spawn().unref() has macOS session-detach
+ * quirks browse already discovered (browse/src/cli.ts:225-275).
+ */
+
+import { spawn as nodeSpawn } from "child_process";
+import fs from "fs";
+import path from "path";
+import { setTimeout as delay } from "timers/promises";
+
+import {
+  acquireLock,
+  CMDLINE_MARKER,
+  healthCheck,
+  isProcessAlive,
+  readStateFile,
+  readVersionString,
+  resolveLockFilePath,
+  resolveStartupLogPath,
+  resolveStateFilePath,
+  verifyIdentity,
+} from "./daemon-state";
+
+const MAX_START_WAIT_MS = parseInt(
+  process.env.DESIGN_DAEMON_START_TIMEOUT_MS || "8000",
+  10,
+);
+const POLL_INTERVAL_MS = 100;
+const SIGTERM_GRACE_MS = 2000;
+
+export interface EnsureDaemonOptions {
+  /** Default: package version. Used for version-match check. */
+  version?: string;
+  /** Default: `<repo>/design/src/daemon.ts`. */
+  daemonScript?: string;
+  /** Extra env vars passed to the spawned daemon. */
+  daemonEnv?: Record<string, string>;
+  /** Print noisy progress to stderr. Default true. */
+  verbose?: boolean;
+  /**
+   * Override the state-file path. Default: resolveStateFilePath() (env
+   * DESIGN_DAEMON_STATE_FILE or .gstack/design.json under the git root /
+   * cwd). Tests inject a per-test path; the same path is forwarded to the
+   * spawned daemon via env so client + daemon agree.
+   */
+  stateFile?: string;
+}
+
+export interface EnsureDaemonResult {
+  port: number;
+  version: string;
+  spawned: boolean;
+}
+
+function log(verbose: boolean, msg: string): void {
+  if (verbose) process.stderr.write(`[design-daemon] ${msg}\n`);
+}
+
+/**
+ * Ensure a design daemon is reachable on the project's state file. Returns
+ * the port to talk to. Spawns a new daemon under an exclusive lock when
+ * needed; attaches to an existing healthy daemon otherwise.
+ *
+ * Exits with code 1 (not throws) on the refuse-kill-with-active-boards
+ * branch — that's a user-actionable situation, not a programming error.
+ */
+export async function ensureDaemon(
+  opts: EnsureDaemonOptions = {},
+): Promise<EnsureDaemonResult> {
+  const verbose = opts.verbose !== false;
+  const expectedVersion = opts.version ?? readPackageVersion();
+  const stateFile = opts.stateFile ?? resolveStateFilePath();
+
+  const existing = readStateFile(stateFile);
+  if (existing) {
+    const health = await healthCheck(existing.port);
+    if (health) {
+      if (health.version === expectedVersion) {
+        log(verbose, `attached to existing daemon pid=${existing.pid} port=${existing.port}`);
+        return { port: existing.port, version: health.version, spawned: false };
+      }
+      // Version mismatch: refuse if active boards exist (Codex finding).
+      if (health.activeBoards > 0) {
+        process.stderr.write(
+          `[design-daemon] WARNING: existing daemon is gstack ${health.version}; this CLI is ${expectedVersion}.\n` +
+            `[design-daemon] ${health.activeBoards} active board(s) detected. Refusing to auto-kill.\n` +
+            `[design-daemon] Submit or close the open boards, then re-run.\n` +
+            `[design-daemon] Or force restart: $D daemon stop (will drop in-memory history).\n`,
+        );
+        process.exit(1);
+      }
+      // No active boards — safe to graceful-shutdown and respawn.
+      log(verbose, `daemon version mismatch (${health.version} vs ${expectedVersion}); shutting down`);
+      await gracefulShutdownExistingDaemon(existing.port);
+      await killByPidWithIdentity(existing.pid, existing.cmdlineMarker, verbose);
+    } else {
+      // State file points at an unresponsive port. Either the daemon
+      // crashed or the PID got reused. Identity-verify before any SIGTERM
+      // so we don't kill an unrelated process (Codex finding).
+      log(verbose, `state file present (pid=${existing.pid}) but /health unresponsive`);
+      await killByPidWithIdentity(existing.pid, existing.cmdlineMarker, verbose);
+    }
+  }
+
+  // Spawn under exclusive lock; re-read state INSIDE the lock so we don't
+  // race a concurrent CLI that won the lock first.
+  const lockPath = resolveLockFilePath(stateFile);
+  const release = acquireLock(lockPath);
+  if (!release) {
+    // Another process is starting the daemon. Wait for it.
+    log(verbose, "another CLI is spawning the daemon; waiting…");
+    const start = Date.now();
+    while (Date.now() - start < MAX_START_WAIT_MS) {
+      const fresh = readStateFile(stateFile);
+      if (fresh) {
+        const h = await healthCheck(fresh.port);
+        if (h) return { port: fresh.port, version: h.version, spawned: false };
+      }
+      await delay(POLL_INTERVAL_MS);
+    }
+    throw new Error("Timed out waiting for concurrent daemon spawn");
+  }
+
+  try {
+    // Re-read under lock. Another caller may have already finished spawning
+    // between our first check and our lock acquisition.
+    const fresh = readStateFile(stateFile);
+    if (fresh) {
+      const h = await healthCheck(fresh.port);
+      if (h && h.version === expectedVersion) {
+        log(verbose, `another CLI won the lock; attaching pid=${fresh.pid} port=${fresh.port}`);
+        return { port: fresh.port, version: h.version, spawned: false };
+      }
+    }
+
+    log(verbose, "spawning new daemon");
+    const port = await spawnDaemon({
+      script: opts.daemonScript,
+      env: { ...opts.daemonEnv, DESIGN_DAEMON_STATE_FILE: stateFile },
+      stateFile,
+      expectedVersion,
+    });
+    return { port, version: expectedVersion, spawned: true };
+  } finally {
+    release();
+  }
+}
+
+/**
+ * Publish a board to the daemon and return its URL. Wraps the HTTP POST
+ * with a friendlier error surface than raw fetch.
+ */
+export interface PublishBoardOptions {
+  port: number;
+  html: string;
+  title?: string;
+  publisherPid?: number;
+}
+
+export interface PublishBoardResult {
+  id: string;
+  url: string;
+  sourceDir: string;
+}
+
+export async function publishBoard(opts: PublishBoardOptions): Promise<PublishBoardResult> {
+  const body: Record<string, unknown> = {
+    html: opts.html,
+    publisherPid: opts.publisherPid ?? process.pid,
+  };
+  if (opts.title) body.title = opts.title;
+  const resp = await fetch(`http://127.0.0.1:${opts.port}/api/boards`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!resp.ok) {
+    let errText: string;
+    try {
+      const j = (await resp.json()) as { error?: string; existing?: { id: string; url: string } };
+      if (j.existing) {
+        // 409: surface the existing-board URL so the caller can reuse it
+        return { id: j.existing.id, url: j.existing.url, sourceDir: "" };
+      }
+      errText = j.error || `HTTP ${resp.status}`;
+    } catch {
+      errText = `HTTP ${resp.status}`;
+    }
+    throw new Error(`Daemon refused publish: ${errText}`);
+  }
+  return (await resp.json()) as PublishBoardResult;
+}
+
+// ─── Internals ───────────────────────────────────────────────────
+
+function readPackageVersion(): string {
+  return readVersionString();
+}
+
+function defaultDaemonScript(): string {
+  // design/src/daemon-client.ts → daemon.ts is a sibling. Only used in dev
+  // when this process is `bun run cli.ts`; the compiled-binary path
+  // self-execs instead (see resolveSpawnCommand).
+  return path.join(import.meta.dir, "daemon.ts");
+}
+
+/**
+ * Compute the argv to spawn the daemon. Two modes:
+ *
+ *   Compiled binary (`design/dist/design`): re-exec ourselves with
+ *   --daemon-mode. process.execPath IS the compiled design binary;
+ *   spawning it again with the flag runs the daemon (see the
+ *   --daemon-mode branch at the bottom of cli.ts).
+ *
+ *   Dev (`bun run design/src/cli.ts`): process.execPath is bun, so we
+ *   invoke `bun run <daemon.ts> --marker ...` directly.
+ *
+ * Tests can override the dev script via opts.script.
+ */
+function resolveSpawnCommand(scriptOverride: string | undefined): {
+  command: string;
+  args: string[];
+} {
+  const execBase = path.basename(process.execPath).toLowerCase();
+  const isCompiledHost = execBase !== "bun" && execBase !== "bun.exe" && execBase !== "node";
+  if (isCompiledHost && !scriptOverride) {
+    return {
+      command: process.execPath,
+      args: ["--daemon-mode", "--marker", CMDLINE_MARKER],
+    };
+  }
+  const script = scriptOverride ?? defaultDaemonScript();
+  return {
+    command: "bun",
+    args: ["run", script, "--marker", CMDLINE_MARKER],
+  };
+}
+
+interface SpawnDaemonOpts {
+  script?: string;
+  env?: Record<string, string>;
+  stateFile: string;
+  expectedVersion: string;
+}
+
+async function spawnDaemon(opts: SpawnDaemonOpts): Promise<number> {
+  const logPath = resolveStartupLogPath();
+  fs.mkdirSync(path.dirname(logPath), { recursive: true });
+  // Truncate the startup log on each spawn so a later read finds only THIS
+  // attempt's output (mirrors browse's per-spawn log truncation).
+  fs.writeFileSync(logPath, "");
+  const logFd = fs.openSync(logPath, "a");
+
+  const { command, args } = resolveSpawnCommand(opts.script);
+
+  const child = nodeSpawn(command, args, {
+    detached: true,
+    stdio: ["ignore", logFd, logFd],
+    env: {
+      ...process.env,
+      DESIGN_DAEMON_VERSION: opts.expectedVersion,
+      ...(opts.env ?? {}),
+    },
+  });
+  child.unref();
+  fs.closeSync(logFd);
+
+  // Poll the state file + /health until the daemon is up, or until timeout.
+  const deadline = Date.now() + MAX_START_WAIT_MS;
+  while (Date.now() < deadline) {
+    const fresh = readStateFile(opts.stateFile);
+    if (fresh) {
+      const h = await healthCheck(fresh.port);
+      if (h) return fresh.port;
+    }
+    await delay(POLL_INTERVAL_MS);
+  }
+
+  // Timed out — surface the startup log so the user sees the actual error
+  // instead of "daemon failed silently."
+  let tail = "";
+  try {
+    tail = fs.readFileSync(logPath, "utf-8").trim();
+  } catch {
+    // log file may not exist
+  }
+  throw new Error(
+    `Design daemon failed to start within ${MAX_START_WAIT_MS}ms.\n` +
+      `Startup log (${logPath}):\n${tail || "(empty)"}`,
+  );
+}
+
+async function gracefulShutdownExistingDaemon(port: number): Promise<void> {
+  try {
+    await fetch(`http://127.0.0.1:${port}/shutdown`, {
+      method: "POST",
+      signal: AbortSignal.timeout(2000),
+    });
+  } catch {
+    // Daemon may have already exited or be unresponsive — fall through
+    // to the SIGTERM path with identity verification.
+  }
+}
+
+/**
+ * Send SIGTERM (then SIGKILL) to `pid`, but ONLY if the running cmdline
+ * contains `marker`. Prevents a stale state file from causing us to signal
+ * an unrelated process that inherited the PID.
+ */
+async function killByPidWithIdentity(
+  pid: number,
+  marker: string,
+  verbose: boolean,
+): Promise<void> {
+  if (!pid || pid <= 0) return;
+  if (!isProcessAlive(pid)) return;
+  if (!verifyIdentity(pid, marker || CMDLINE_MARKER)) {
+    log(
+      verbose,
+      `pid ${pid} is alive but cmdline doesn't match marker '${marker || CMDLINE_MARKER}'; skipping signal (possible PID reuse)`,
+    );
+    return;
+  }
+  try {
+    process.kill(pid, "SIGTERM");
+  } catch {
+    // already gone
+    return;
+  }
+  // Give it a grace period; SIGKILL if still alive AND still ours.
+  const deadline = Date.now() + SIGTERM_GRACE_MS;
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) return;
+    await delay(50);
+  }
+  if (isProcessAlive(pid) && verifyIdentity(pid, marker || CMDLINE_MARKER)) {
+    log(verbose, `pid ${pid} survived SIGTERM; SIGKILL`);
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch {
+      // raced with exit
+    }
+  }
+}
+
+/**
+ * Public: $D daemon stop. Posts /shutdown if no active boards; otherwise
+ * reports refusal. Used by the CLI sub-command (next commit).
+ */
+export async function shutdownDaemon(opts: { force?: boolean } = {}): Promise<{
+  stopped: boolean;
+  reason?: string;
+  activeBoards?: number;
+}> {
+  const stateFile = resolveStateFilePath();
+  const existing = readStateFile(stateFile);
+  if (!existing) return { stopped: false, reason: "no daemon running" };
+  const health = await healthCheck(existing.port);
+  if (!health) {
+    // unresponsive: try SIGTERM via identity-checked path
+    await killByPidWithIdentity(existing.pid, existing.cmdlineMarker, true);
+    return { stopped: true, reason: "unresponsive daemon killed via SIGTERM" };
+  }
+  if (health.activeBoards > 0 && !opts.force) {
+    return {
+      stopped: false,
+      reason: "active boards present",
+      activeBoards: health.activeBoards,
+    };
+  }
+  await gracefulShutdownExistingDaemon(existing.port);
+  // Best-effort: SIGTERM if /shutdown didn't take effect
+  if (isProcessAlive(existing.pid)) {
+    await killByPidWithIdentity(existing.pid, existing.cmdlineMarker, true);
+  }
+  return { stopped: true };
+}
+
+/** $D daemon status — for the CLI sub-command. */
+export async function daemonStatus(): Promise<
+  | { running: false }
+  | { running: true; port: number; pid: number; version: string; boards: number; activeBoards: number; uptime: number }
+> {
+  const existing = readStateFile();
+  if (!existing) return { running: false };
+  const h = await healthCheck(existing.port);
+  if (!h) return { running: false };
+  return {
+    running: true,
+    port: existing.port,
+    pid: existing.pid,
+    version: h.version,
+    boards: h.boards,
+    activeBoards: h.activeBoards,
+    uptime: h.uptime,
+  };
+}
@@ -0,0 +1,220 @@
+/**
+ * Pure utilities for design-daemon discovery.
+ *
+ * Shared between daemon.ts (writes/removes the state file) and
+ * daemon-client.ts (reads state, decides spawn-vs-attach). Mirrors
+ * browse/src/cli.ts:109-315 — same atomic-write + fs.openSync 'wx' lock
+ * pattern, with an added cmdline-based identity check to guard against
+ * SIGTERM hitting a reused PID (Codex finding on the daemon plan).
+ */
+
+import { execFileSync } from "child_process";
+import fs from "fs";
+import os from "os";
+import path from "path";
+
+export interface DaemonState {
+  pid: number;
+  port: number;
+  startedAt: string; // ISO 8601
+  version: string;
+  serverPath: string;
+  cmdlineMarker: string;
+}
+
+// String we grep for in the spawned daemon's cmdline to confirm a pid is
+// ours before sending any signal. Must appear in argv at spawn time.
+export const CMDLINE_MARKER = "gstack-design-daemon";
+
+export function resolveStateFilePath(): string {
+  // Env override has highest precedence so tests can point both client and
+  // spawned daemon at a per-test path without a shared cwd.
+  const envOverride = process.env.DESIGN_DAEMON_STATE_FILE;
+  if (envOverride) return envOverride;
+  try {
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (root) return path.join(root, ".gstack", "design.json");
+  } catch {
+    // not in a git repo — fall through
+  }
+  return path.join(process.cwd(), ".gstack", "design.json");
+}
+
+export function resolveLockFilePath(stateFile: string = resolveStateFilePath()): string {
+  return `${stateFile}.lock`;
+}
+
+export function resolveDaemonLogPath(): string {
+  return path.join(os.homedir(), ".gstack", "design-daemon.log");
+}
+
+export function resolveStartupLogPath(): string {
+  return path.join(os.homedir(), ".gstack", "design-daemon-startup.log");
+}
+
+/**
+ * Read the gstack version both client and daemon should agree on. Looks
+ * (in order): DESIGN_DAEMON_VERSION env, design/dist/.version baked at
+ * build time, VERSION at the source-tree root (dev), then "unknown".
+ *
+ * Compiled binaries lose the source-tree relative path at runtime, so we
+ * try the dist/.version sidecar (which build.sh writes) before falling
+ * back. This keeps client.expectedVersion and daemon.VERSION coherent.
+ */
+export function readVersionString(): string {
+  const env = process.env.DESIGN_DAEMON_VERSION;
+  if (env) return env;
+  const candidates = [
+    // Compiled binary: design/dist/design lives alongside design/dist/.version
+    path.join(path.dirname(process.execPath), ".version"),
+    // Dev: design/src/* → repo root is two levels up
+    path.join(import.meta.dir, "..", "..", "VERSION"),
+    // Defensive: design/dist sibling of source tree
+    path.join(import.meta.dir, "..", "dist", ".version"),
+  ];
+  for (const p of candidates) {
+    try {
+      const v = fs.readFileSync(p, "utf-8").trim();
+      if (v) return v;
+    } catch {
+      // try next
+    }
+  }
+  return "unknown";
+}
+
+export function readStateFile(stateFile: string = resolveStateFilePath()): DaemonState | null {
+  try {
+    return JSON.parse(fs.readFileSync(stateFile, "utf-8")) as DaemonState;
+  } catch {
+    return null;
+  }
+}
+
+export function writeStateFile(
+  state: DaemonState,
+  stateFile: string = resolveStateFilePath(),
+): void {
+  fs.mkdirSync(path.dirname(stateFile), { recursive: true });
+  const tmp = `${stateFile}.tmp.${process.pid}.${Math.random().toString(36).slice(2)}`;
+  fs.writeFileSync(tmp, JSON.stringify(state, null, 2), { mode: 0o600 });
+  fs.renameSync(tmp, stateFile);
+}
+
+export function removeStateFile(stateFile: string = resolveStateFilePath()): void {
+  try {
+    fs.unlinkSync(stateFile);
+  } catch {
+    // already gone
+  }
+}
+
+export interface HealthOk {
+  ok: true;
+  version: string;
+  uptime: number;
+  boards: number;
+  activeBoards: number;
+}
+
+export async function healthCheck(
+  port: number,
+  timeoutMs: number = 2000,
+): Promise<HealthOk | null> {
+  try {
+    const resp = await fetch(`http://127.0.0.1:${port}/health`, {
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!resp.ok) return null;
+    const body = (await resp.json()) as Partial<HealthOk> | null;
+    if (body && body.ok === true && typeof body.version === "string") {
+      return body as HealthOk;
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export function isProcessAlive(pid: number): boolean {
+  if (!pid || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (e: unknown) {
+    // EPERM means it exists, we just can't signal it. ESRCH means it's gone.
+    const code = (e as NodeJS.ErrnoException | undefined)?.code;
+    return code === "EPERM";
+  }
+}
+
+/**
+ * Read the cmdline of a running process. Returns "" on any error.
+ * Linux: /proc/<pid>/cmdline (NUL-separated argv). macOS: `ps -p PID -o command=`.
+ */
+export function readCmdline(pid: number): string {
+  if (!isProcessAlive(pid)) return "";
+  try {
+    if (process.platform === "linux") {
+      const raw = fs.readFileSync(`/proc/${pid}/cmdline`, "utf-8");
+      return raw.replace(/\0/g, " ").trim();
+    }
+    if (process.platform === "darwin") {
+      return execFileSync("ps", ["-p", String(pid), "-o", "command="], {
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "ignore"],
+      }).trim();
+    }
+    return "";
+  } catch {
+    return "";
+  }
+}
+
+/**
+ * True only when the process at `pid` has `marker` in its cmdline. Used to
+ * avoid SIGTERMing an unrelated process that happens to have inherited a
+ * PID from a stale state file (the Codex PID-reuse concern). On systems
+ * where readCmdline is unsupported (or fails), this returns false — safer
+ * to skip the signal than to risk killing the wrong process.
+ */
+export function verifyIdentity(pid: number, marker: string): boolean {
+  if (!marker) return false;
+  return readCmdline(pid).includes(marker);
+}
+
+/**
+ * Acquire an exclusive lock on `lockPath`. Returns a release function, or
+ * null if held by another live process. Stale locks (PID dead) are reclaimed
+ * once; if reclaim also fails the caller waits and retries via state re-read.
+ */
+export function acquireLock(lockPath: string): (() => void) | null {
+  try {
+    fs.mkdirSync(path.dirname(lockPath), { recursive: true });
+    // 'wx' = create exclusive, fail if exists. Atomic check-and-create.
+    const fd = fs.openSync(lockPath, "wx");
+    fs.writeSync(fd, `${process.pid}\n`);
+    fs.closeSync(fd);
+    return () => {
+      try {
+        fs.unlinkSync(lockPath);
+      } catch {
+        // already gone
+      }
+    };
+  } catch {
+    // Held — check if holder is alive
+    try {
+      const holderPid = parseInt(fs.readFileSync(lockPath, "utf-8").trim(), 10);
+      if (holderPid && isProcessAlive(holderPid)) return null;
+      // Stale, reclaim
+      fs.unlinkSync(lockPath);
+      return acquireLock(lockPath);
+    } catch {
+      return null;
+    }
+  }
+}
@@ -0,0 +1,582 @@
+/**
+ * Persistent design board daemon.
+ *
+ * One process hosts many boards under /boards/<id>/. Spawned by
+ * daemon-client.ts when no live daemon is found on the project's discovery
+ * file (.gstack/design.json). Replaces the per-invocation server in
+ * serve.ts as the default for `$D compare --serve`; serve.ts is kept as
+ * the --no-daemon legacy/test path.
+ *
+ * Endpoints (see plan docs/designs path for full table):
+ *   GET  /                              index of boards
+ *   GET  /health                        liveness + version (unauth)
+ *   POST /api/boards                    publish a new board
+ *   POST /shutdown                      graceful exit (refused if active)
+ *   GET  /boards/<id>                   301 → /boards/<id>/
+ *   GET  /boards/<id>/                  render board HTML
+ *   GET  /boards/<id>/api/progress      state machine status
+ *   POST /boards/<id>/api/feedback      submit/regenerate
+ *   POST /boards/<id>/api/reload        swap board HTML
+ *
+ * Lifecycle:
+ *   start → bind 127.0.0.1:N → write state file → serve until 24h idle or
+ *   explicit /shutdown → remove state file → exit 0
+ *
+ * The daemon refuses /shutdown when boards are non-done; the idle timer
+ * extends rather than killing in that case (up to a 28h hard ceiling).
+ * Both are Codex-flagged guards against silent loss of in-memory history.
+ */
+
+import fs from "fs";
+import path from "path";
+
+import {
+  CMDLINE_MARKER,
+  DaemonState,
+  readVersionString,
+  removeStateFile,
+  resolveDaemonLogPath,
+  writeStateFile,
+} from "./daemon-state";
+
+// ─── Tunables (env overrides for tests) ──────────────────────────
+
+const DEFAULT_IDLE_MS = 24 * 60 * 60 * 1000; // 24h
+const IDLE_MS = parseInt(
+  process.env.DESIGN_DAEMON_IDLE_MS || String(DEFAULT_IDLE_MS),
+  10,
+);
+const IDLE_EXTENSION_MS = parseInt(
+  process.env.DESIGN_DAEMON_EXTENSION_MS || String(60 * 60 * 1000), // 1h
+  10,
+);
+const MAX_EXTENSIONS = parseInt(process.env.DESIGN_DAEMON_MAX_EXTENSIONS || "4", 10);
+const IDLE_CHECK_INTERVAL_MS = parseInt(
+  process.env.DESIGN_DAEMON_CHECK_MS || "60000",
+  10,
+);
+const MAX_BOARDS = parseInt(process.env.DESIGN_DAEMON_MAX_BOARDS || "50", 10);
+
+const VERSION = readVersionString();
+
+// ─── Per-board state ─────────────────────────────────────────────
+
+export type BoardState = "serving" | "regenerating" | "done";
+
+export interface Board {
+  id: string;
+  htmlContent: string;
+  sourceDir: string; // realpath of the dir feedback files write to
+  allowedDir: string; // realpath anchor for path-traversal guard
+  state: BoardState;
+  publishedAt: number;
+  lastTouched: number;
+  publisherPid: number;
+  title?: string;
+}
+
+// In-memory: keyed by board id.
+const boards = new Map<string, Board>();
+// Per-board mutex chain — serializes feedback POST vs reload POST on the
+// same board so the daemon doesn't race a state mutation against an HTML swap.
+const boardMutex = new Map<string, Promise<void>>();
+
+let lastMeaningfulActivity = Date.now();
+let idleExtensions = 0;
+let shuttingDown = false;
+let serverRef: ReturnType<typeof Bun.serve> | null = null;
+let idleInterval: ReturnType<typeof setInterval> | null = null;
+const startTime = Date.now();
+const daemonLog = openDaemonLog();
+
+function openDaemonLog(): fs.WriteStream | null {
+  try {
+    const p = resolveDaemonLogPath();
+    fs.mkdirSync(path.dirname(p), { recursive: true });
+    return fs.createWriteStream(p, { flags: "a" });
+  } catch {
+    return null;
+  }
+}
+
+function dlog(...args: unknown[]): void {
+  const line = `[${new Date().toISOString()}] ${args.map(String).join(" ")}\n`;
+  if (daemonLog) daemonLog.write(line);
+  process.stderr.write(line);
+}
+
+// ─── Helpers ─────────────────────────────────────────────────────
+
+function newBoardId(): string {
+  const now = new Date();
+  const y = now.getUTCFullYear().toString().padStart(4, "0");
+  const mo = (now.getUTCMonth() + 1).toString().padStart(2, "0");
+  const d = now.getUTCDate().toString().padStart(2, "0");
+  const hh = now.getUTCHours().toString().padStart(2, "0");
+  const mm = now.getUTCMinutes().toString().padStart(2, "0");
+  const ss = now.getUTCSeconds().toString().padStart(2, "0");
+  const rand = Math.random().toString(36).slice(2, 8).padEnd(6, "0");
+  return `b-${y}${mo}${d}-${hh}${mm}${ss}-${rand}`;
+}
+
+async function withBoardMutex<T>(id: string, fn: () => Promise<T>): Promise<T> {
+  const prev = boardMutex.get(id) || Promise.resolve();
+  let release!: () => void;
+  const next = new Promise<void>((r) => {
+    release = r;
+  });
+  boardMutex.set(id, prev.then(() => next));
+  await prev;
+  try {
+    return await fn();
+  } finally {
+    release();
+    if (boardMutex.get(id) === next) boardMutex.delete(id);
+  }
+}
+
+function markMeaningfulActivity(): void {
+  lastMeaningfulActivity = Date.now();
+  idleExtensions = 0;
+}
+
+function nonDoneCount(): number {
+  let n = 0;
+  for (const b of boards.values()) if (b.state !== "done") n += 1;
+  return n;
+}
+
+function hasActiveBoards(): boolean {
+  return nonDoneCount() > 0;
+}
+
+// LRU eviction. Prefers `done` boards as victims so an active regen doesn't
+// vanish mid-flight. Returns the evicted id, or null when the map fits.
+function evictOne(): string | null {
+  if (boards.size <= MAX_BOARDS) return null;
+  let oldestDone: Board | null = null;
+  let oldestAny: Board | null = null;
+  for (const b of boards.values()) {
+    if (b.state === "done") {
+      if (!oldestDone || b.lastTouched < oldestDone.lastTouched) oldestDone = b;
+    }
+    if (!oldestAny || b.lastTouched < oldestAny.lastTouched) oldestAny = b;
+  }
+  const victim = oldestDone || oldestAny;
+  if (!victim) return null;
+  boards.delete(victim.id);
+  boardMutex.delete(victim.id);
+  dlog(`evicted board ${victim.id} state=${victim.state}`);
+  return victim.id;
+}
+
+function evictUntilUnderCap(): void {
+  while (boards.size > MAX_BOARDS) {
+    if (!evictOne()) break;
+  }
+}
+
+function findActiveBoardForSourceDir(sourceDir: string): Board | null {
+  for (const b of boards.values()) {
+    if (b.sourceDir === sourceDir && b.state !== "done") return b;
+  }
+  return null;
+}
+
+function escapeHtml(s: string): string {
+  return s.replace(/[&<>"']/g, (c) =>
+    ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]!),
+  );
+}
+
+// ─── Shutdown ─────────────────────────────────────────────────────
+
+async function gracefulShutdown(exitCode = 0): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  dlog(`shutting down boards=${boards.size} code=${exitCode}`);
+  if (idleInterval) clearInterval(idleInterval);
+  try {
+    serverRef?.stop();
+  } catch {
+    // already stopped
+  }
+  removeStateFile();
+  if (daemonLog) daemonLog.end();
+  setTimeout(() => process.exit(exitCode), 50);
+}
+
+export function idleCheckTick(): void {
+  if (shuttingDown) return;
+  const idle = Date.now() - lastMeaningfulActivity;
+  if (idle < IDLE_MS) return;
+  if (hasActiveBoards()) {
+    if (idleExtensions >= MAX_EXTENSIONS) {
+      dlog(`idle past hard ceiling with ${nonDoneCount()} active boards — forcing shutdown`);
+      gracefulShutdown(0);
+      return;
+    }
+    idleExtensions += 1;
+    // Push lastMeaningfulActivity forward by an extension window without
+    // marking real activity (so the count stays correct).
+    lastMeaningfulActivity = Date.now() - IDLE_MS + IDLE_EXTENSION_MS;
+    dlog(
+      `idle with ${nonDoneCount()} active boards — extending ${IDLE_EXTENSION_MS / 60000}min (${idleExtensions}/${MAX_EXTENSIONS})`,
+    );
+    return;
+  }
+  dlog(`idle for ${Math.floor(idle / 1000)}s — shutting down`);
+  gracefulShutdown(0);
+}
+
+// ─── Handlers ─────────────────────────────────────────────────────
+
+function handleHealth(): Response {
+  return Response.json({
+    ok: true,
+    version: VERSION,
+    uptime: Math.floor((Date.now() - startTime) / 1000),
+    boards: boards.size,
+    activeBoards: nonDoneCount(),
+  });
+}
+
+function handleIndex(): Response {
+  const sorted = [...boards.values()].sort((a, b) => b.publishedAt - a.publishedAt);
+  const rows = sorted
+    .map((b) => {
+      const ts = new Date(b.publishedAt).toISOString();
+      const titleSuffix = b.title ? ` — ${escapeHtml(b.title)}` : "";
+      return `<li><a href="/boards/${b.id}/">${b.id}</a> <span class="state state-${b.state}">${b.state}</span> <time>${ts}</time>${titleSuffix}</li>`;
+    })
+    .join("\n");
+  const empty = `<p class="empty">No boards yet. Run <code>$D compare --serve</code> to publish one.</p>`;
+  const list = sorted.length === 0 ? empty : `<ul>\n${rows}\n</ul>`;
+  const html = `<!DOCTYPE html><html lang="en"><head>
+<meta charset="utf-8"><title>gstack design boards</title><style>
+  body{font:14px/1.5 -apple-system,system-ui,sans-serif;max-width:720px;margin:32px auto;padding:0 16px;color:#1a1a1a}
+  h1{font-size:20px;margin-bottom:4px}
+  .meta{color:#666;margin-bottom:24px;font-size:13px}
+  ul{padding:0;list-style:none}
+  li{padding:10px 0;border-bottom:1px solid #eee;display:flex;align-items:center;gap:12px;flex-wrap:wrap}
+  a{color:#0070f3;text-decoration:none;font-family:ui-monospace,monospace}
+  a:hover{text-decoration:underline}
+  .state{font-size:11px;padding:2px 8px;border-radius:10px;background:#eef;color:#335}
+  .state-done{background:#efe;color:#353}
+  .state-regenerating{background:#ffe;color:#553}
+  time{color:#888;font-size:12px}
+  .empty{color:#888;font-style:italic}
+  code{font-family:ui-monospace,monospace;background:#f5f5f5;padding:2px 6px;border-radius:3px}
+</style></head><body>
+<h1>gstack design boards</h1>
+<p class="meta">daemon up ${Math.floor((Date.now() - startTime) / 1000)}s · ${boards.size} board(s) · ${nonDoneCount()} active</p>
+${list}
+</body></html>`;
+  return new Response(html, { headers: { "Content-Type": "text/html; charset=utf-8" } });
+}
+
+async function handlePublish(req: Request, origin: string): Promise<Response> {
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return Response.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  if (!body || typeof body !== "object") {
+    return Response.json({ error: "Expected JSON object" }, { status: 400 });
+  }
+  const htmlPath = typeof body.html === "string" ? body.html : "";
+  if (!htmlPath) return Response.json({ error: "Missing 'html' field" }, { status: 400 });
+  if (!fs.existsSync(htmlPath)) {
+    return Response.json({ error: `HTML file not found: ${htmlPath}` }, { status: 400 });
+  }
+  let resolvedHtml: string;
+  let sourceDir: string;
+  try {
+    resolvedHtml = fs.realpathSync(path.resolve(htmlPath));
+    sourceDir = fs.realpathSync(path.dirname(resolvedHtml));
+  } catch (e: any) {
+    return Response.json({ error: `Cannot resolve path: ${e.message}` }, { status: 400 });
+  }
+  if (!fs.statSync(resolvedHtml).isFile()) {
+    return Response.json(
+      { error: `'html' must be a file, not a directory: ${htmlPath}` },
+      { status: 400 },
+    );
+  }
+
+  // sourceDir comes from realpath(html), not from the body — Codex finding:
+  // body-supplied sourceDir is a local trust boundary the daemon shouldn't cross.
+  const existing = findActiveBoardForSourceDir(sourceDir);
+  if (existing) {
+    return Response.json(
+      {
+        error: "Source directory already in use by an active board",
+        existing: {
+          id: existing.id,
+          url: `${origin}/boards/${existing.id}/`,
+          state: existing.state,
+        },
+      },
+      { status: 409 },
+    );
+  }
+  if (nonDoneCount() >= MAX_BOARDS) {
+    return Response.json(
+      {
+        error: `Cannot publish: ${MAX_BOARDS} non-done boards already exist. Submit or close some first.`,
+      },
+      { status: 503 },
+    );
+  }
+
+  const id = newBoardId();
+  const htmlContent = fs.readFileSync(resolvedHtml, "utf-8");
+  const now = Date.now();
+  const board: Board = {
+    id,
+    htmlContent,
+    sourceDir,
+    allowedDir: sourceDir,
+    state: "serving",
+    publishedAt: now,
+    lastTouched: now,
+    publisherPid: typeof body.publisherPid === "number" ? body.publisherPid : 0,
+    title: typeof body.title === "string" ? body.title : undefined,
+  };
+  boards.set(id, board);
+  evictUntilUnderCap();
+  markMeaningfulActivity();
+  dlog(`published board ${id} sourceDir=${sourceDir} pid=${board.publisherPid}`);
+  return Response.json({
+    id,
+    url: `${origin}/boards/${id}/`,
+    sourceDir,
+  });
+}
+
+function handleBoardGet(board: Board): Response {
+  board.lastTouched = Date.now();
+  // No __GSTACK_SERVER_URL injection — board JS uses relative URLs that
+  // resolve against /boards/<id>/ (the trailing slash is load-bearing here;
+  // the 301 from the bare /boards/<id> form ensures it).
+  return new Response(board.htmlContent, {
+    headers: { "Content-Type": "text/html; charset=utf-8" },
+  });
+}
+
+function handleBoardProgress(board: Board): Response {
+  // NOT meaningful activity — bare progress polling shouldn't keep the
+  // daemon alive forever (Codex finding on idle-immortality).
+  board.lastTouched = Date.now();
+  return Response.json({ status: board.state });
+}
+
+async function handleBoardFeedback(board: Board, req: Request): Promise<Response> {
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return Response.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  if (!body || typeof body !== "object") {
+    return Response.json({ error: "Expected JSON object" }, { status: 400 });
+  }
+  const isSubmit = body.regenerated === false;
+  const isRegen = body.regenerated === true;
+
+  // Augment with boardId + publishedAt so multi-board agents can disambiguate
+  // which board produced a given feedback.json.
+  const augmented = {
+    ...body,
+    boardId: board.id,
+    publishedAt: new Date(board.publishedAt).toISOString(),
+  };
+
+  const feedbackFile = isSubmit ? "feedback.json" : "feedback-pending.json";
+  const feedbackPath = path.join(board.sourceDir, feedbackFile);
+  try {
+    fs.writeFileSync(feedbackPath, JSON.stringify(augmented, null, 2));
+  } catch (e: any) {
+    dlog(`feedback write failed for ${board.id}: ${e.message}`);
+    return Response.json(
+      { error: `Cannot write ${feedbackFile}: ${e.message}` },
+      { status: 500 },
+    );
+  }
+
+  board.lastTouched = Date.now();
+  markMeaningfulActivity();
+
+  if (isSubmit) {
+    board.state = "done";
+    dlog(`board ${board.id} submitted → ${feedbackPath}`);
+    return Response.json({ received: true, action: "submitted" });
+  }
+  if (isRegen) {
+    board.state = "regenerating";
+    dlog(`board ${board.id} regenerate → ${feedbackPath}`);
+    return Response.json({ received: true, action: "regenerate" });
+  }
+  return Response.json({ received: true, action: "unknown" });
+}
+
+async function handleBoardReload(board: Board, req: Request): Promise<Response> {
+  let body: any;
+  try {
+    body = await req.json();
+  } catch {
+    return Response.json({ error: "Invalid JSON" }, { status: 400 });
+  }
+  const newHtmlPath = typeof body?.html === "string" ? body.html : "";
+  if (!newHtmlPath || !fs.existsSync(newHtmlPath)) {
+    return Response.json({ error: `HTML file not found: ${newHtmlPath}` }, { status: 400 });
+  }
+  const resolvedReload = fs.realpathSync(path.resolve(newHtmlPath));
+  if (!resolvedReload.startsWith(board.allowedDir + path.sep)) {
+    return Response.json(
+      { error: `Path must be within: ${board.allowedDir}` },
+      { status: 403 },
+    );
+  }
+  if (!fs.statSync(resolvedReload).isFile()) {
+    return Response.json(
+      { error: `Path must be a file, not a directory: ${newHtmlPath}` },
+      { status: 400 },
+    );
+  }
+  board.htmlContent = fs.readFileSync(resolvedReload, "utf-8");
+  board.state = "serving";
+  board.lastTouched = Date.now();
+  markMeaningfulActivity();
+  dlog(`board ${board.id} reloaded from ${resolvedReload}`);
+  return Response.json({ reloaded: true });
+}
+
+function boardExpiredHtml(id: string): string {
+  return `<!DOCTYPE html><html lang="en"><head><meta charset="utf-8"><title>Board expired — gstack</title>
+<style>body{font:14px/1.5 -apple-system,system-ui,sans-serif;max-width:600px;margin:80px auto;padding:0 20px;color:#1a1a1a;text-align:center}
+h1{font-size:20px}.id{font-family:ui-monospace,monospace;color:#888;font-size:13px}
+a{color:#0070f3;text-decoration:none}a:hover{text-decoration:underline}</style></head><body>
+<h1>Board expired</h1>
+<p>Board <span class="id">${escapeHtml(id)}</span> is no longer hosted by this daemon (evicted or the daemon restarted).</p>
+<p><a href="/">← see active boards</a></p>
+</body></html>`;
+}
+
+// ─── Router ──────────────────────────────────────────────────────
+
+const BOARD_RE = /^\/boards\/([A-Za-z0-9_-]+)(\/.*)?$/;
+
+export async function fetchHandler(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  const origin = url.origin;
+
+  if (req.method === "GET" && url.pathname === "/health") return handleHealth();
+  if (req.method === "GET" && url.pathname === "/") return handleIndex();
+  if (req.method === "POST" && url.pathname === "/api/boards") return handlePublish(req, origin);
+
+  if (req.method === "POST" && url.pathname === "/shutdown") {
+    if (hasActiveBoards()) {
+      return Response.json(
+        {
+          error: "Refusing /shutdown: daemon has active boards. Submit or close them first.",
+          activeBoards: nonDoneCount(),
+        },
+        { status: 409 },
+      );
+    }
+    setTimeout(() => gracefulShutdown(0), 50);
+    return Response.json({ shuttingDown: true });
+  }
+
+  const m = url.pathname.match(BOARD_RE);
+  if (m) {
+    const id = m[1]!;
+    const subpath = m[2] || "";
+    const board = boards.get(id);
+    if (!board) {
+      return new Response(boardExpiredHtml(id), {
+        status: 404,
+        headers: { "Content-Type": "text/html; charset=utf-8" },
+      });
+    }
+    // Bare /boards/<id> → 301 to /boards/<id>/ so relative URLs in board JS
+    // resolve against the right base (./api/feedback → /boards/<id>/api/feedback).
+    if (req.method === "GET" && subpath === "") {
+      return new Response(null, {
+        status: 301,
+        headers: { Location: `/boards/${id}/` },
+      });
+    }
+    if (req.method === "GET" && subpath === "/") return handleBoardGet(board);
+    if (req.method === "GET" && subpath === "/api/progress") return handleBoardProgress(board);
+    if (req.method === "POST" && subpath === "/api/feedback") {
+      return withBoardMutex(id, () => handleBoardFeedback(board, req));
+    }
+    if (req.method === "POST" && subpath === "/api/reload") {
+      return withBoardMutex(id, () => handleBoardReload(board, req));
+    }
+  }
+
+  return new Response("Not found", { status: 404 });
+}
+
+// ─── Startup ─────────────────────────────────────────────────────
+
+export function start(): { port: number } {
+  const portArg = process.env.DESIGN_DAEMON_PORT;
+  const port = portArg ? parseInt(portArg, 10) : 0;
+  serverRef = Bun.serve({
+    port,
+    hostname: "127.0.0.1",
+    fetch: fetchHandler,
+  });
+  const actualPort = serverRef.port;
+  const state: DaemonState = {
+    pid: process.pid,
+    port: actualPort,
+    startedAt: new Date().toISOString(),
+    version: VERSION,
+    serverPath: process.argv[1] || "",
+    cmdlineMarker: CMDLINE_MARKER,
+  };
+  writeStateFile(state);
+  dlog(`DAEMON_STARTED port=${actualPort} pid=${process.pid} version=${VERSION}`);
+  // Stdout line the spawning CLI parses to learn the port quickly.
+  console.log(`DAEMON_STARTED port=${actualPort}`);
+
+  idleInterval = setInterval(idleCheckTick, IDLE_CHECK_INTERVAL_MS);
+
+  process.on("SIGTERM", () => {
+    void gracefulShutdown(0);
+  });
+  process.on("SIGINT", () => {
+    void gracefulShutdown(0);
+  });
+  process.on("uncaughtException", (e) => {
+    dlog(`uncaughtException: ${(e as Error).stack || (e as Error).message}`);
+    void gracefulShutdown(1);
+  });
+
+  return { port: actualPort };
+}
+
+if (import.meta.main) {
+  start();
+}
+
+// Exported for tests. Keep this small and stable.
+export const __testInternals__ = {
+  boards,
+  fetchHandler,
+  idleCheckTick,
+  markMeaningfulActivity,
+  resetForTest: (): void => {
+    boards.clear();
+    boardMutex.clear();
+    lastMeaningfulActivity = Date.now();
+    idleExtensions = 0;
+    shuttingDown = false;
+  },
+};
@@ -1,12 +1,18 @@
 /**
 * HTTP server for the design comparison board feedback loop.
 *
- * Replaces the broken file:// + DOM polling approach. The server:
- * 1. Serves the comparison board HTML over HTTP
- * 2. Injects __GSTACK_SERVER_URL so the board POSTs feedback here
- * 3. Prints feedback JSON to stdout (agent reads it)
- * 4. Stays alive across regeneration rounds (stateful)
- * 5. Auto-opens in the user's default browser
+ * Legacy single-process path: spawned by `$D compare --serve --no-daemon`.
+ * The daemon (`design/src/daemon.ts`) handles default invocations and hosts
+ * multiple boards under `/boards/<id>/`; this file stays as the escape hatch
+ * for tests and debugging. Board JS uses relative URLs and a
+ * location.protocol feature-detect, so the same generated HTML works at
+ * both `/` (here) and `/boards/<id>/` (daemon).
+ *
+ * The server:
+ * 1. Serves the comparison board HTML over HTTP at `/`
+ * 2. Prints feedback JSON to stdout (agent reads it)
+ * 3. Stays alive across regeneration rounds (stateful)
+ * 4. Auto-opens in the user's default browser
 *
 * State machine:
 *
@@ -69,17 +75,14 @@ export async function serve(options: ServeOptions): Promise<void> {
    fetch(req) {
      const url = new URL(req.url);

-      // Serve the comparison board HTML
+      // Serve the comparison board HTML. The board JS uses relative paths
+      // (./api/feedback, ./api/progress) and a location.protocol
+      // feature-detect, so no per-request injection is needed.
      if (
        req.method === "GET" &&
        (url.pathname === "/" || url.pathname === "/index.html")
      ) {
-        // Inject the server URL so the board can POST feedback
-        const injected = htmlContent.replace(
-          "</head>",
-          `<script>window.__GSTACK_SERVER_URL = ${JSON.stringify(url.origin)};</script>\n</head>`,
-        );
-        return new Response(injected, {
+        return new Response(htmlContent, {
          headers: { "Content-Type": "text/html; charset=utf-8" },
        });
      }
@@ -194,19 +197,25 @@ export async function serve(options: ServeOptions): Promise<void> {
      );
    }

-    // Security: resolve symlinks and validate the reload path is within the
-    // allowed directory (anchored to the initial HTML file's parent).
-    // Prevents path traversal via /api/reload reading arbitrary files.
+    // Security: resolve symlinks and validate the reload path is a FILE
+    // inside the allowed directory (anchored to the initial HTML file's
+    // parent). Prevents path traversal via /api/reload reading arbitrary
+    // files. A path resolving to the allowedDir itself (a directory) used
+    // to pass the guard and then crash readFileSync with EISDIR — reject
+    // it explicitly with a clear 400 instead.
    const resolvedReload = fs.realpathSync(path.resolve(newHtmlPath));
-    if (
-      !resolvedReload.startsWith(allowedDir + path.sep) &&
-      resolvedReload !== allowedDir
-    ) {
+    if (!resolvedReload.startsWith(allowedDir + path.sep)) {
      return Response.json(
        { error: `Path must be within: ${allowedDir}` },
        { status: 403 },
      );
    }
+    if (!fs.statSync(resolvedReload).isFile()) {
+      return Response.json(
+        { error: `Path must be a file, not a directory: ${newHtmlPath}` },
+        { status: 400 },
+      );
+    }

    // Swap the HTML content
    htmlContent = fs.readFileSync(resolvedReload, "utf-8");