slidemind 0.1.7 → 0.1.8

package/CLAUDE.md

@@ -78,7 +78,7 @@ slidemind/
 │                                 READ from the bundle's workflow/search.md — owned by the add-in.
 ├── src/                          implementation of the slidemind CLI
 │   ├── bridge/                   add-in local-bridge: client.mjs, bundle.mjs (materialize), build-and-push.mjs (server render; native-slide splicing), engine-download.mjs + recolor.mjs (image/icon fetch + recolour)
-│   ├── builders/                 build.mjs (HTML preview), review.mjs (spatial preview-review gate + local server), resolve-skill.mjs (→ bundle), lint.mjs (runs the add-in's engine)
+│   ├── builders/                 build.mjs (HTML preview), review.mjs (spatial preview-review gate + local server; stable per-deck port, graceful fallback, tab reuse across rounds), plan.mjs (plan sign-off gate) + plan-overlay.js + plan-md.mjs (markdown→HTML) + gate-server.mjs (shared gate primitives), resolve-skill.mjs (→ bundle), lint.mjs (runs the add-in's engine)
 │   └── installers/               per-harness installers: claude.mjs, codex.mjs, opencode.mjs, lib.mjs
 ├── archive/                      retired code/assets (local exporter, icon library, brand design files) — NOT shipped
 ├── decks/                        the user's working decks; sources are slides/*.jsx, design via .bundle-ref.json
@@ -99,6 +99,7 @@ slidemind presentations            # list PowerPoint windows registered with the
 slidemind read [presId]            # pull the current content of an open presentation (--mode summary|raw) (HOST REQUIRED)
 slidemind download-bundle [deck]   # materialize the active corporate design's bundle locally
 slidemind new <name>               # scaffold ./decks/<name>/ (auto-binds to the open design when unambiguous + bundle already materialized; --to/--no-bind)
+slidemind plan <deck>              # plan sign-off gate on <deck>/plan.md; markdown editor + live preview + overall feedback, blocks for approve/comments (host-free)
 slidemind build <deck>             # build self-contained HTML preview
 slidemind review <deck>            # spatial preview-review gate; blocks for approve/comments (host-free)
 slidemind build-pptx <deck>        # render native .pptx via the add-in (HOST REQUIRED)
@@ -146,6 +147,7 @@ Both skills are **brand-agnostic workflow guidance** and must not duplicate any
 ```bash
 slidemind ready <deck>            # do this first: connection ladder + resolve the open design + materialize its bundle + bind the deck (host required)
 slidemind download-bundle <deck>  # lower-level: materialize-only (no connection ladder, no bind) — `ready` now covers this
+slidemind plan <deck>             # plan sign-off gate on <deck>/plan.md; blocks until approve/comments (host-free)
 slidemind build <deck>            # HTML preview (reads the materialized bundle)
 slidemind build <deck> --open     # HTML + open in browser
 slidemind review <deck>           # spatial preview-review gate; blocks until approve/comments (host-free)

package/README.md

@@ -197,6 +197,7 @@ slidemind ready [deck]           One-shot session start: connect + resolve the o
                                  --to <presId> --force --connect-only --json
 slidemind new <name>             Scaffold ./decks/<name>/ (auto-binds to the open design when available)
                                  --to <presId> --no-bind
+slidemind plan <deck>            Plan sign-off gate on <deck>/plan.md; blocks for approve/comments (offline)
 slidemind build <deck>           Build a self-contained HTML preview (offline)
 slidemind review <deck>          Spatial preview review; blocks for approve/comments (offline)
 slidemind build-pptx <deck>      Render a native .pptx via the add-in        (host required)

package/bin/slidemind.mjs

@@ -56,6 +56,10 @@ function printHelp() {
       `  slidemind new <name>             Scaffold ./decks/<name>/ (auto-binds to the open design)\n` +
       `                                     --to <presId>   bind to a specific open window\n` +
       `                                     --no-bind       skip the auto-bind\n` +
+      `  slidemind plan <deck>            Plan sign-off gate on <deck>/plan.md: opens it in the browser\n` +
+      `                                     as a markdown editor + live preview + overall feedback box,\n` +
+      `                                     blocks until the user decides, prints DECISION: approved | comments\n` +
+      `                                     --port <n>          bind a fixed port (default: ephemeral)\n` +
       `  slidemind build <deck>           Build self-contained HTML\n` +
       `  slidemind review <deck>          Open a spatial preview review; blocks until the user\n` +
       `                                     approves or leaves comments (host-free)\n` +
@@ -229,6 +233,15 @@ async function cmdBuild(rest) {
   ]);
 }
 
+async function cmdPlan(rest) {
+  const { deck, passthrough } = splitDeckArg(rest, "plan");
+  await runNode(path.join(BUILDERS_DIR, "plan.mjs"), [
+    "--deck",
+    resolveDeckArg(deck),
+    ...passthrough,
+  ]);
+}
+
 async function cmdReview(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "review");
   await runNode(path.join(BUILDERS_DIR, "review.mjs"), [
@@ -2256,6 +2269,9 @@ async function main(rawArgv) {
     case "build":
       await cmdBuild(rest);
       return 0;
+    case "plan":
+      await cmdPlan(rest);
+      return 0;
     case "review":
       await cmdReview(rest);
       return 0;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Connect Claude Code, Codex & opencode to the slidemind PowerPoint add-in — let your coding agent build and edit native, on-brand PowerPoint decks against your active corporate design, from the terminal.",
   "type": "module",
   "bin": {

package/skills/create-slides/SKILL.md

@@ -21,7 +21,7 @@ The moment this skill activates on an authoring task, **create a todo list of th
 
 1. `slidemind ready` — session preflight (*First step* below)
 2. Clarify with the user — the content **and the output target** (*Intake → plan* below; needs no host, so it can run while `ready` executes)
-3. Plan sign-off
+3. Plan sign-off — `slidemind plan <deck>` (decks; single slides stay in chat)
 4. Author the slides
 5. Draft check — `slidemind view-draft`
 6. Review gate — `slidemind review`, the moment the deck builds clean
@@ -74,7 +74,7 @@ Everything about how a deck is authored, styled, and rendered is shaped by the c
 - **`ambiguous_design`** — several windows with **different** corporate designs are open, so `ready` can't choose. The CLI lists the candidates (each with its `env` and window `title`/`fileName`, plus a design fingerprint); if the deck was last built against one of them it's marked `suggested`. **Ask the user which design to build against, naming the windows by `title`/`fileName` (and `env`) — never by raw id** — and mention the suggested one if present ("this deck was last built against X — continue with it?"). Then re-run `slidemind ready --to <presId>` for the window they pick.
 - **Connection blockers** (`not_paired`, `all_unreachable`, `cli_update_required`, `no_window`, `not_render_ready`) — relay the CLI's `nextAction` verbatim (pair / open PowerPoint / click the pane / run `slidemind update`). Pairing is walked through in *Pairing the CLI with the add-in* above. (`no_window` only ever surfaces for an **unbound** deck or deckless `ready` — a bound deck rides the pane-free rung above instead.)
 
-**The session spine** (= the stage todos you created up front): `slidemind ready` → read `workflow/flow.md` + `design.md` from `bundleDir` → intake/plan (below) → `slidemind new <slug>` (scaffolds **and** auto-binds the deck to the open design — zero extra download, because `ready` already materialized it) → author → `view-draft` → `review` (mandatory, the moment the deck builds clean) → deliver (`push` / `build-pptx`). `slidemind new` best-effort binds when the open design is unambiguous and the bundle is already materialized; if it can't (ambiguous, or no host), it scaffolds anyway and hints to run `slidemind ready <slug>`.
+**The session spine** (= the stage todos you created up front): `slidemind ready` → read `workflow/flow.md` + `design.md` from `bundleDir` → intake/plan (below) → `slidemind new <slug>` (scaffolds **and** auto-binds the deck to the open design — zero extra download, because `ready` already materialized it) → `slidemind plan <slug>` (plan sign-off gate for decks; single slides stay in chat) → author → `view-draft` → `review` (mandatory, the moment the deck builds clean) → deliver (`push` / `build-pptx`). `slidemind new` best-effort binds when the open design is unambiguous and the bundle is already materialized; if it can't (ambiguous, or no host), it scaffolds anyway and hints to run `slidemind ready <slug>`.
 
 **Backgrounded — or closed — PowerPoint is expected to work.** Do not pre-emptively ask the user to focus PowerPoint or the task pane, and never ask them to keep it foregrounded while something runs. The render itself (`build-pptx`, the render half of `push`) **never needs a window** for a bound deck — it captures the slides with a local headless browser and assembles the `.pptx` server-side over the pane-free brand route, streams its own `rendering slide n/m…` progress, and survives arbitrarily long authoring sessions (the old "author 30 minutes and the add-in is gone" failure no longer applies). Only the pane-touching ops (the insert half of `push`, engine search/download, `read`) need a live pane, and the CLI handles that itself: it waits up to ~2 min, prints one *"click the slidemind pane"* line when user help is genuinely needed, and retries safely. If you see that line, relay it once and keep waiting — do not rebuild, re-plan, or babysit. If a `push` can't deliver (pane never woke, or no window at all), the rendered `.pptx` was saved next to the deck (`paneSuspended` + `fallbackFile` in the result) — nothing is lost; re-run the push once a window exists. Reserve the full "open PowerPoint…" instruction for when a command actually reports it as the blocker.
 
@@ -87,7 +87,7 @@ This is your mapping of `workflow/flow.md` stages 1–2 (*clarify* + *plan sign-
 - **Read scope from the wording**, don't ask redundantly: single slide ("make a slide about X"), small set ("add three slides on Y"), or whole deck ("a deck for Friday"). Only ask "one slide, a small set, or a full deck?" when truly ambiguous.
 - **Interview just enough** to pin: audience/goal, the content and its sources (none / pasted / local files / existing deck / web research), and the slide outline (each slide's role + a layout *job* like cover/agenda/section/quote/closing/body — the concrete brand layout is chosen later against the bundle).
 - **Lock the output target — it decides your deliver command.** Into the open PowerPoint (`slidemind push`), or a `.pptx` file (`slidemind build-pptx`) — or an HTML preview / a mix. Infer it when the wording is clear ("add a slide to this deck" → push; "make me a deck I can send around" → a file) and ask only when genuinely ambiguous — but **always confirm the concrete target before delivering** (which window, or which output path).
-- **Replay and get sign-off.** Single slides / tiny sets → a compact in-chat plan. Decks → persist `decks/<slug>/plan.md` (content direction, narrative red thread, sources, per-slide role + layout job — *not* visual shape, *not* brand specifics). A valid existing `decks/<slug>/plan.md` counts as approved; restate what you're building.
+- **Replay and get sign-off.** Single slides / tiny sets → a compact in-chat plan (no gate). Decks → persist `decks/<slug>/plan.md` (content direction, narrative red thread, sources, per-slide role + layout job — *not* visual shape, *not* brand specifics), then run `slidemind plan <deck>`: it opens the plan in a markdown editor with a live rendered preview; the user edits `plan.md` directly and/or leaves overall feedback, and it **blocks until the user decides** — give the shell call a **generous timeout** (the gate waits up to 30 min; if your harness kills the call early, just re-run it — the user's open tab reconnects). Outcomes: `DECISION: approved` → proceed to author; `DECISION: comments` → apply the feedback to `plan.md` and **re-run the gate in the same turn** — after a comments round the user's tab sits on a waiting spinner that only the next `slidemind plan` run releases, so never end your turn, never claim to be "polling", and never send the user back to the browser between rounds (that deadlocks: the tab waits for you while you wait for the tab); `DECISION: pending` → the gate timed out with no answer — not approval, not rejection: don't author; wrap up telling the user the plan still awaits their sign-off and re-run `slidemind plan <deck>` on their go-ahead. Loop until approved. A `plan.md` **approved in a prior gate round and unchanged since** counts as approved (skip straight to authoring); any new or revised plan must pass the gate. When the gate reports the user edited `plan.md` directly, re-read it — the edited text *is* the approved plan; author from it.
 
 Keep planning about intent and content. The bundle is already materialized by `slidemind ready`, so `design.md` is there if you need to sanity-check feasibility — but **don't dive into brand/layout/composition detail until create/edit.**
 
@@ -99,9 +99,10 @@ Keep planning about intent and content. The bundle is already materialized by `s
 2. **Read, then author.** Read the create-stage references together — `workflow/create.md` (the procedure), `workflow/composition.md` (the composition baseline), `workflow/layouts.md` (palette + working area), and `workflow/authoring.md` (the substrate rules) — plus the deck's `design.md` and the specific `layouts/*.jsx` the plan uses. (That is the read set `workflow/create.md` → Context loading prescribes; follow it as written — `workflow/flow.md` you already read after `ready`.) Then write `decks/<slug>/slides/NN-<topic>.jsx` — zero-padded numeric prefix from the first file on (play order is filename order here; see the slide-file row in the command mapping), one default export per slide, composing one bundle layout (Mode A) or a blank-content layout with freeform children (Mode B), exactly as those docs prescribe.
 3. **Imagery from the engine.** Per the `### Brand Image Sources` block in `design.md`, search the brand engine and place results. The engine search/reuse mechanics live in **`slidemind-search`** — use it to find and fetch imagery; the create-only icon-recolour detail is in *Recolouring engine icons* below. To pull in an **existing whole slide** (not just an image), use `slidemind-search`'s `add-slide` — it folds the slide into `decks/<slug>/slides/` as a native `.pptx` that coexists with your JSX in play order and survives re-push.
 4. **Look at your own draft first (you, the agent).** This is the **draft check** in `workflow/build-and-export.md` — your pre-check, *before* any human sees the deck. Run `slidemind view-draft <deck>`: it renders each authored `slides/*.jsx` to a per-slide PNG and hands the images back to you — **nothing is pushed, no `.pptx` is written, no review gate opens**. Read every image the way the audience will, fix anything visibly wrong **in the JSX** (re-express, never delete), and view again until each slide is sound. One round usually suffices. It runs locally against the materialized bundle, so it needs no awake pane and no open host once the bundle has been downloaded once. Two faithful limits to know: a slide on a **purpose-built (Mode A) layout** (cover/divider/agenda) and a **reused native `.pptx`** slide have no freeform region to capture, so they come back as a status line, not an image — judge those at the full-deck `review`/`build` step below. Do this self-check before the human review gate; don't push a draft you haven't looked at.
-5. **The review gate — the moment the deck builds clean.** This is the **review gate** in `workflow/build-and-export.md`; the CLI's gate command is `slidemind review <deck>`. Run it the instant the authored set builds clean — before any deliver, without asking whether the user wants a review. It builds the HTML preview first (the same lint the render enforces, so a gate that *opens* is a clean build; while lint errors remain it exits non-zero — fix and re-run), then opens the browser with a spatial comment overlay and **blocks until the user decides** (host-free — no open PowerPoint needed for the gate). The verdict prints to stdout:
+5. **The review gate — the moment the deck builds clean.** This is the **review gate** in `workflow/build-and-export.md`; the CLI's gate command is `slidemind review <deck>`. Run it the instant the authored set builds clean — before any deliver, without asking whether the user wants a review. It builds the HTML preview first (the same lint the render enforces, so a gate that *opens* is a clean build; while lint errors remain it exits non-zero — fix and re-run), then opens the browser with a spatial comment overlay and **blocks until the user decides** (host-free — no open PowerPoint needed for the gate). **Blocking is the point: give the shell call a generous timeout (the gate waits up to 30 min) and let it sit — a long quiet wait means the user is reviewing, not that something hung. Never cancel it; if your harness kills the call early, just re-run it (the user's open tab reconnects).** The verdict prints to stdout:
    - `DECISION: approved` → proceed to the deliver the user chose at intake: `slidemind push <deck>` (into PowerPoint) or `slidemind build-pptx <deck>` (to a file).
-   - `DECISION: comments` → the user left spatially-anchored notes, each citing a `slides/<file>.jsx:line:col`, the source line, and the click position (plus a readonly-layout note where the click landed on a layout slot). **Edit the cited files in place at the given line**, then **re-run `slidemind review <deck>`** — the prior round shows as read-only ghost pins so the user can confirm each note was addressed. Loop until approved. Nothing is exported on a comments round.
+   - `DECISION: comments` → the user left spatially-anchored notes, each citing a `slides/<file>.jsx:line:col`, the source line, and the click position (plus a readonly-layout note where the click landed on a layout slot). **Edit the cited files in place at the given line and re-run `slidemind review <deck>` in the same turn** — after a comments round the user's tab waits for the next round, so never end your turn, never claim to be "polling", and never send the user back to the browser between rounds. The prior round shows as read-only ghost pins so the user can confirm each note was addressed. Loop until approved. Nothing is exported on a comments round.
+   - `DECISION: pending` → the gate timed out with no answer (the user stepped away). Not approval, not rejection — **do not deliver**. Wrap up your turn: tell the user the preview is still waiting for their review and that on their go-ahead you'll re-run `slidemind review <deck>` (their tab reconnects).
 
    `slidemind review` is the only step that pauses; `push`/`build-pptx` never pause — they render pane-free (local capture + server-side assembly, with live per-slide progress). **CLI exports happen out of the user's sight, so the flow invariant — *the user sees every change before the task is done* — makes re-review mandatory here: every deliver is preceded by an approved review of exactly what it delivers. After any later slide change, the deck re-enters `slidemind review` before it can be pushed or exported again — never deliver an unreviewed change.** If several presentations are open, confirm **which one to push into** first (it can differ from the design source `slidemind ready` locked in). After approval, run the push without asking; it works while PowerPoint is backgrounded, and the CLI itself waits + retries if the pane is needed (see *First step* above). If a push still times out, the rendered `.pptx` is saved next to the deck — re-run `push` after the user clicks the pane, without rebuilding.
 
@@ -127,7 +128,7 @@ The bundle's `workflow/*.md` speak the harness-neutral verbs defined in `workflo
 |---|---|
 | (session setup — a CLI-only stage before the spine) | `slidemind ready [deck]` — the one-shot session start: connection ladder + open-design resolution + bundle materialize + deck bind. **Run it first, every session** (see *First step* above). `slidemind download-bundle` is the lower-level materialize-only command `ready` now covers — you rarely call it directly |
 | **track the stages** | your harness's task tracker — explicitly create the stage todo list before your first command and keep it current (see *Create a todo list* above) |
-| **clarify** / **plan sign-off** | **you** run intake → plan with the user in chat (above); persist `decks/<slug>/plan.md` for decks |
+| **clarify** / **plan sign-off** | intake stays in chat with the user (above); for decks, persist `decks/<slug>/plan.md`, then run `slidemind plan <deck>` — the same blocking `DECISION:` gate contract as `slidemind review`, on the plan (markdown editor + live preview + overall feedback; loop until approved) |
 | **read** / **list** the workspace | read the files from the materialized bundle dir (`<bundle>/…`) and your `decks/<slug>/` |
 | **create / update a slide file** | write `decks/<slug>/slides/NN-<topic>.jsx` on disk with a **zero-padded numeric prefix** (`01-cover.jsx`, `02-agenda.jsx`, …) — over the CLI, "the ordered set you hand to build & push" is expressed as **numeric-aware filename order**; there is no ordered-list channel, so reordering = renaming files |
 | brand reference samples (studied before composing) | **Read** 3 random images from the materialized bundle's `samples/` dir — the Read tool renders them (see *The create flow* step 1) |

package/src/builders/build.mjs

@@ -917,17 +917,59 @@ export async function buildDeck(deckDir, opts = {}) {
   return { out, slideCount: slideFiles.length };
 }
 
-// Open a local file path OR an http URL in the user's default browser. The
-// platform openers (open / start / xdg-open) accept both, so review.mjs reuses
-// this to launch the local review server URL.
+// Detect whether this Linux box is really WSL, so we can hand the target to the
+// Windows-side opener instead of a (usually absent) Linux one. Any read/parse
+// failure just means "not WSL".
+function isWsl() {
+  if (process.platform !== "linux") return false;
+  try {
+    return /microsoft/i.test(fs.readFileSync("/proc/version", "utf8"));
+  } catch {
+    return false;
+  }
+}
+
+// Ordered list of opener candidates to try for the current platform. The
+// platform openers (open / start / xdg-open / wslview) accept both a local file
+// path AND an http URL, so review.mjs reuses this to launch the local review
+// server URL and view-draft passes png paths.
+function openerChain(target) {
+  if (process.platform === "darwin") return [{ cmd: "open", args: [target] }];
+  if (process.platform === "win32")
+    return [{ cmd: "cmd", args: ["/c", "start", "", target] }];
+  if (isWsl())
+    return [
+      { cmd: "wslview", args: [target] },
+      { cmd: "powershell.exe", args: ["-NoProfile", "-Command", "start", target] },
+    ];
+  return [{ cmd: "xdg-open", args: [target] }];
+}
+
+// Open a local file path OR an http URL in the user's default browser, trying
+// each platform opener in turn. This is fire-and-forget and must NEVER crash:
+// if the opener binary is missing (e.g. a headless Linux box with no xdg-open)
+// the spawned child would otherwise emit an unhandled 'error' and take down the
+// whole CLI. We degrade gracefully — on exhausting the chain we just print the
+// target for the user to open manually.
 export function openInBrowser(target) {
-  const opener =
-    process.platform === "darwin"
-      ? { cmd: "open", args: [target] }
-      : process.platform === "win32"
-        ? { cmd: "cmd", args: ["/c", "start", "", target] }
-        : { cmd: "xdg-open", args: [target] };
-  spawn(opener.cmd, opener.args, { stdio: "ignore", detached: true }).unref();
+  const chain = openerChain(target);
+  const tryAt = (i) => {
+    if (i >= chain.length) {
+      process.stderr.write(`couldn't open a browser — open ${target} manually\n`);
+      return;
+    }
+    const { cmd, args } = chain[i];
+    let child;
+    try {
+      child = spawn(cmd, args, { stdio: "ignore", detached: true });
+    } catch {
+      tryAt(i + 1);
+      return;
+    }
+    child.on("error", () => tryAt(i + 1));
+    child.unref();
+  };
+  tryAt(0);
 }
 
 function parseArgs(argv) {

package/src/builders/gate-server.mjs

@@ -0,0 +1,223 @@
+// Shared low-level primitives for the CLI's blocking review gates (the spatial
+// preview gate in review.mjs and the plan sign-off gate in plan.mjs).
+//
+// These were lifted out of review.mjs so both gates share one implementation of
+// the MIME table, the traversal-guarded static responder, the decision promise +
+// timeout wrapper, and the port + tab-reuse machinery: a deterministic per-deck
+// per-gate port (so a tab left waiting from the previous round reconnects to the
+// same URL), a bind that never fails on a taken port (falls back to an
+// OS-assigned one with a stderr notice), and a heartbeat endpoint each gate
+// serves under its own service marker so a waiting tab only ever reloads into
+// its OWN gate's next round — never into the other gate or a foreign app.
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
+// Tab-reuse timing contract, shared by both gates and injected into their
+// overlays as CFG.pollMs / CFG.pollTtlMs:
+//   GRACE_MS  > POLL_MS so a waiting tab always lands one poll inside the
+//              open-browser grace window;
+//   POLL_TTL_MS > the gates' 30-min decision timeout so an abandoned tab stops
+//              polling only after the server side has certainly given up.
+export const GRACE_MS = 1500;
+export const POLL_MS = 1000;
+export const POLL_TTL_MS = 35 * 60 * 1000;
+
+const PORT_BASE = 40000;
+const PORT_SPAN = 1000; // preferred ports live in 40000..40999
+
+// Extension → content-type table (lifted verbatim from review.mjs).
+export const MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+};
+
+// Traversal-guarded static responder, generalized to MULTIPLE roots. `pathname`
+// is expected already URL-decoded (review.mjs decodes once at the top of its
+// request handler and passes the decoded value in). Each root is tried in order:
+// the pathname is resolved within the root and required to stay inside it (via
+// path.sep so the boundary check is correct on Windows). The first root that
+// holds a matching file serves it (200 + MIME, default application/octet-stream)
+// and returns true. If no root matches — file missing everywhere, or a traversal
+// attempt escaped every root — returns false WITHOUT writing a response, leaving
+// the caller to send its own 404.
+export function serveStaticFile({ roots, pathname, res }) {
+  const rel = String(pathname).replace(/^\/+/, "");
+  for (const root of roots || []) {
+    if (!root) continue;
+    const base = path.resolve(root);
+    const resolved = path.resolve(base, rel);
+    if (resolved !== base && !resolved.startsWith(base + path.sep)) {
+      continue; // escaped this root — a later root might still legitimately match
+    }
+    let data;
+    try {
+      const st = fs.statSync(resolved);
+      if (!st.isFile()) continue;
+      data = fs.readFileSync(resolved);
+    } catch {
+      continue; // missing here — try the next root
+    }
+    const ext = path.extname(resolved).toLowerCase();
+    res.writeHead(200, { "Content-Type": MIME[ext] || "application/octet-stream" });
+    res.end(data);
+    return true;
+  }
+  return false;
+}
+
+// The decision promise + timeout wrapper both gates block on. `resolve(value)`
+// settles the internal promise once (a Promise never re-settles, so repeat calls
+// are no-ops). `waitForDecision({ timeoutMs })` returns the promise directly when
+// no/falsy timeout is given, otherwise races it against a setTimeout that rejects
+// with `timeoutMessage`. The timer is cleared the moment the decision wins so the
+// process can exit instead of being held open by a pending timeout.
+//
+// A timeout rejection carries `code: "GATE_TIMEOUT"` so gates can tell "the user
+// never answered" (an expected outcome with its own DECISION: pending contract)
+// apart from a real failure.
+export function createDecisionGate({
+  timeoutMessage = "review timed out — no decision received",
+} = {}) {
+  let resolveDecision;
+  const decisionPromise = new Promise((res) => {
+    resolveDecision = res;
+  });
+  return {
+    resolve(value) {
+      resolveDecision(value);
+    },
+    waitForDecision({ timeoutMs } = {}) {
+      if (!timeoutMs) return decisionPromise;
+      return new Promise((resolve, reject) => {
+        const t = setTimeout(() => {
+          const err = new Error(timeoutMessage);
+          err.code = "GATE_TIMEOUT";
+          reject(err);
+        }, timeoutMs);
+        decisionPromise.then((d) => {
+          clearTimeout(t);
+          resolve(d);
+        });
+      });
+    },
+  };
+}
+
+// Deterministic per-deck, per-gate preferred port so a tab left waiting from
+// the previous round can reconnect to the same URL. Stateless — derived purely
+// from the resolved deck path plus the gate name. The gate name is the salt:
+// the preview and plan gates of the SAME deck get independent ports, so their
+// waiting tabs can never sit on each other's URL.
+export function preferredGatePort(deckDir, gateName) {
+  const key = `${path.resolve(deckDir)}\u0000${gateName}`;
+  const n = crypto.createHash("sha1").update(key).digest().readUInt32BE(0);
+  return PORT_BASE + (n % PORT_SPAN);
+}
+
+// Bind `server` to `port`, falling back to an OS-assigned port when the
+// preferred one is taken or blocked. An http.Server is reusable after a failed
+// listen, so we retry listen(0) on the SAME instance. onFallback runs once,
+// before the retry, so the caller can warn on stderr. EADDRINUSE: port already
+// bound. EACCES: Windows excluded/reserved port range. Anything else (or a
+// fallback-attempt failure) is a real error and rejects.
+export function listenWithFallback(server, port, host, onFallback) {
+  return new Promise((resolve, reject) => {
+    const onFirstError = (err) => {
+      server.removeListener("listening", onFirstListening);
+      if (err && (err.code === "EADDRINUSE" || err.code === "EACCES")) {
+        onFallback(port, err);
+        const onFallbackError = (err2) => {
+          server.removeListener("listening", onFallbackListening);
+          reject(err2);
+        };
+        const onFallbackListening = () => {
+          server.removeListener("error", onFallbackError);
+          resolve();
+        };
+        server.once("error", onFallbackError);
+        server.once("listening", onFallbackListening);
+        server.listen(0, host);
+        return;
+      }
+      reject(err);
+    };
+    const onFirstListening = () => {
+      server.removeListener("error", onFirstError);
+      resolve();
+    };
+    server.once("error", onFirstError);
+    server.once("listening", onFirstListening);
+    server.listen(port, host);
+  });
+}
+
+// Per-run heartbeat state for one gate server. The gate mounts `respond` under
+// its own heartbeat path; a waiting tab polls it and reloads only when BOTH the
+// service marker matches its own gate (a foreign app or the other gate on this
+// port must never trigger a reload) AND the round nonce differs from the one it
+// was served with (same nonce = this run's own orphan — never self-reload).
+// `waitForHeartbeat(ms)` is the server side of the open-browser grace window.
+export function createHeartbeat({ service }) {
+  const round = crypto.randomUUID();
+  let seen = false;
+  const waiters = [];
+  return {
+    round,
+    respond(res) {
+      seen = true;
+      while (waiters.length) waiters.shift()();
+      res.writeHead(200, { "Content-Type": MIME[".json"], "Cache-Control": "no-store" });
+      res.end(JSON.stringify({ ok: true, service, round }));
+    },
+    waitForHeartbeat(ms) {
+      if (seen) return Promise.resolve(true);
+      return new Promise((resolve) => {
+        const t = setTimeout(() => resolve(false), ms);
+        waiters.push(() => {
+          clearTimeout(t);
+          resolve(true);
+        });
+      });
+    },
+  };
+}
+
+// Print the gate URL, then decide whether to open a browser. If a tab left
+// waiting from a previous comments round pings the gate's heartbeat within the
+// grace window, reuse it (it reloads itself) instead of opening a duplicate.
+// Returns true if an existing tab was reused. `open` is required — gates pass
+// their browser opener so this module stays dependency-light and tests inject
+// a fake. The message strings are per-gate; defaults speak the preview gate's.
+export async function serveAndOpen(server, {
+  open,
+  graceMs = GRACE_MS,
+  readyLabel = "Preview review",
+  reuseNoun = "review tab",
+  openedLine = "Opened your browser — leave comments or approve, then return here.",
+  waitLine = null,
+} = {}) {
+  process.stderr.write(`${readyLabel} ready at ${server.url}\n`); // URL always printed first
+  const reused = await server.waitForHeartbeat(graceMs);
+  if (reused) {
+    process.stderr.write(`Reusing your open ${reuseNoun} — no new browser window.\n`);
+  } else {
+    open(server.url);
+    process.stderr.write(`${openedLine}\n`);
+  }
+  // Spoken to the AGENT running this command: blocking here is the designed
+  // behavior, not a hang — don't kill the call because it sits quiet.
+  if (waitLine) process.stderr.write(`${waitLine}\n`);
+  return reused;
+}