slidemind 0.1.7 → 0.1.9

package/src/builders/plan.mjs

@@ -0,0 +1,696 @@
+#!/usr/bin/env node
+// slidemind plan <deck> — the plan sign-off gate, CLI-owned.
+//
+// Serves <deck>/plan.md as a branded editor page (the plan-overlay.js chrome
+// injected): a plain markdown editor on the left, a live rendered preview on
+// the right (collapsible), and the decision in ONE always-visible chat-style
+// composer bar at the bottom (feedback input + send + Approve, whose sub-label
+// says the agent builds the slides next) — no per-block commenting. The live
+// preview runs the same dependency-free renderer the server-side render used
+// (plan-md.mjs), shipped inline to the browser as window.__SLIDEMIND_RENDER_MD__.
+// Opens the browser and BLOCKS until the user approves the plan or requests
+// changes. The browser POSTs the decision to /plan-review, which unblocks this
+// command — no copy-paste round-trip. On a comments round the tab stays open
+// and readable (spinner in the composer) and reloads itself when the next
+// round binds the same port. The verdict is printed to stdout for the harness:
+//   - approved  -> "DECISION: approved" (the agent then authors the slides;
+//                  an edit-and-approve rewrites plan.md first and tells the
+//                  agent to re-read it — the user's words are the plan).
+//   - comments  -> the user's overall feedback (the agent revises plan.md to
+//                  address it and re-runs).
+//
+// Host-free: the plan gate runs BEFORE any slide exists, so it needs no bundle
+// and no open host. A per-brand orb PNG is used when a bundle happens to be
+// materialized (dark variant preferred); otherwise the overlay falls back to
+// its inline embossed slide glyph. Each round's feedback persists to
+// <deck>/plan-review.json so the next run shows it as a read-only note.
+//
+// Port + tab-reuse contract (shared with the preview gate via gate-server.mjs):
+// each run binds a deterministic per-deck plan port (a hash of the deck path,
+// salted "plan", folded into 40000..40999) so a tab left waiting from the
+// previous round reconnects to the same URL. A taken port never fails — it
+// falls back to an OS-assigned port with a stderr notice. On a comments round
+// the browser tab does NOT close: it polls /__plan/heartbeat and reloads itself
+// once the next run binds the same port (matched by the "slidemind-plan"
+// service marker + a fresh round nonce), so a fresh tab isn't opened per round.
+//
+// This mirrors review.mjs's structure and shares its low-level primitives via
+// gate-server.mjs (MIME, serveStaticFile, createDecisionGate, createHeartbeat,
+// listenWithFallback, preferredGatePort, serveAndOpen).
+
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { openInBrowser } from "./build.mjs";
+import { renderPlanMarkdown } from "./plan-md.mjs";
+import { splitPlanFrontmatter } from "./resolve-skill.mjs";
+import {
+  MIME,
+  serveStaticFile,
+  createDecisionGate,
+  createHeartbeat,
+  listenWithFallback,
+  preferredGatePort,
+  serveAndOpen,
+  pendingBrowserLines,
+  GRACE_MS,
+  OPEN_FAILED_GRACE_MS,
+  POLL_MS,
+  POLL_TTL_MS,
+} from "./gate-server.mjs";
+import { resolveBrandAsset } from "../bridge/bundle.mjs";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const OVERLAY_PATH = path.join(__dirname, "plan-overlay.js");
+const PLAN_MD_PATH = path.join(__dirname, "plan-md.mjs");
+// The storyboard/red-thread plan-review modules, bundled into the browser page
+// alongside plan-md.mjs (see bundlePlanModules). Order matters: each file's
+// inter-module imports are stripped, so a module must be concatenated AFTER the
+// module whose exports it references (schema ← storyboard-markdown ← backbone).
+const STORYBOARD_SCHEMA_PATH = path.join(__dirname, "storyboard-schema.mjs");
+const STORYBOARD_MARKDOWN_PATH = path.join(__dirname, "storyboard-markdown.mjs");
+const RED_THREAD_BACKBONE_PATH = path.join(__dirname, "red-thread-backbone.mjs");
+const PLAN_MARKDOWN_EDIT_PATH = path.join(__dirname, "plan-markdown-edit.mjs");
+const PLAN_STATE_FILE = "plan-review.json";
+const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
+
+// Escape a </script> sequence so an inlined JSON/JS blob can't break out of the
+// surrounding <script> tag (copied from review.mjs — that module is off-limits
+// and doesn't export it).
+function safeInlineJson(data) {
+  return JSON.stringify(data).replace(/<\/script>/g, "<\\/script>");
+}
+
+// ---------------------------------------------------------------------------
+// plan-review.json round-trip (previous-round feedback source)
+// ---------------------------------------------------------------------------
+
+export function loadPlanState(deckDir) {
+  const f = path.join(deckDir, PLAN_STATE_FILE);
+  // decision drives the grace-window logic in runPlanReview (a waiting tab can
+  // only exist after a prior comments round), so a fresh/garbage state must
+  // still carry an explicit decision: null — same shape review.mjs uses.
+  if (!fs.existsSync(f)) return { version: 2, decision: null, comment: null };
+  try {
+    const data = JSON.parse(fs.readFileSync(f, "utf8"));
+    // v1 files carried a per-block comments array; fold it into one feedback
+    // text so an old round still shows up as the previous-round note.
+    let comment = typeof data.comment === "string" ? data.comment : null;
+    if (comment == null && Array.isArray(data.comments)) {
+      const joined = data.comments
+        .map((c) => c && c.comment)
+        .filter(Boolean)
+        .join("\n");
+      comment = joined || null;
+    }
+    return {
+      version: 2,
+      decision: data.decision ?? null,
+      comment,
+      edited: data.edited ?? false,
+      planHash: data.planHash ?? null,
+      at: data.at ?? null,
+    };
+  } catch {
+    return { version: 2, decision: null, comment: null };
+  }
+}
+
+export function savePlanState(deckDir, state) {
+  fs.writeFileSync(
+    path.join(deckDir, PLAN_STATE_FILE),
+    JSON.stringify(state, null, 2) + "\n",
+  );
+}
+
+// ---------------------------------------------------------------------------
+// harness output
+// ---------------------------------------------------------------------------
+
+// Render the feedback round for the harness — the plan analog of review.mjs's
+// formatCommentsForHarness, on ONE overall comment instead of per-block pins.
+//
+// The tail is deliberately imperative and stateful: after a comments round the
+// user's browser tab sits on a waiting spinner that ONLY the next `slidemind
+// plan` run releases, so an agent that ends its turn here (or redirects the
+// user "back to the browser") deadlocks the session — the tab waits for the
+// agent while the agent waits for the tab. Spell the next actions out as
+// short, own-line steps so no instruction hides at the end of a long path.
+export function formatPlanFeedbackForHarness(deckDir, comment, { edited = false } = {}) {
+  const out = [];
+  out.push("DECISION: comments");
+  out.push("The user requested changes to the plan. Nothing was authored.");
+  if (edited) {
+    out.push(
+      "The user also edited plan.md directly — re-read it before revising; the " +
+        "feedback below is on top of their edits.",
+    );
+  }
+  out.push("");
+  if (comment) {
+    out.push("Feedback:");
+    for (const line of String(comment).split("\n")) out.push(`  ${line}`);
+    out.push("");
+  } else if (edited) {
+    out.push("(No written feedback — their direct edits to plan.md are the change.)");
+    out.push("");
+  }
+  // Recovery pointer in the tail (truncated captures usually lose the TOP):
+  // the round is persisted before this prints, so a lost capture is recoverable.
+  out.push(
+    `This round (decision + feedback) is also saved verbatim in ` +
+      `${path.join(deckDir, PLAN_STATE_FILE)} — if this output looks truncated, read ` +
+      `that file instead of guessing.`,
+  );
+  out.push("");
+  out.push(
+    "The user's browser tab is still open, on a waiting spinner that says you are",
+  );
+  out.push("revising the plan. They are waiting on YOU now — do both steps in this");
+  out.push("same turn:");
+  out.push(`  1. Edit ${deckDir}/plan.md to address the feedback.`);
+  out.push(`  2. Re-run: slidemind plan ${path.basename(deckDir)}`);
+  out.push("The re-run reopens their same tab with the revised plan. Do NOT end your");
+  out.push("turn and do NOT send the user back to the browser before step 2 — nothing");
+  out.push("happens until the gate runs again.");
+  return out.join("\n") + "\n";
+}
+
+// Render the no-answer outcome for the harness. A timed-out gate is an EXPECTED
+// state (the user stepped away), not a failure — the agent must neither treat
+// it as approval nor abort the task; it wraps up with clear resume instructions.
+export function formatPlanPendingForHarness(deckDir, { timeoutMs, pageLoaded, url } = {}) {
+  const mins = Math.max(1, Math.round((timeoutMs ?? DEFAULT_TIMEOUT_MS) / 60000));
+  const base = path.basename(deckDir);
+  return [
+    "DECISION: pending",
+    `No decision yet — the gate waited ${mins} minutes and the user hasn't answered.`,
+    ...pendingBrowserLines({ pageLoaded, url }),
+    "This is NOT an approval and NOT a rejection. Do not author anything.",
+    "Close out your turn gracefully:",
+    "  1. Tell the user their plan is still waiting for sign-off in the browser.",
+    `  2. Tell them that when they're ready, you'll re-open the gate — then, on`,
+    `     their go-ahead, re-run: slidemind plan ${base}`,
+    "A still-open tab reconnects to the re-run automatically; a closed one just",
+    "gets a fresh window. Nothing is lost by the wait.",
+  ].join("\n") + "\n";
+}
+
+// ---------------------------------------------------------------------------
+// browser bundle
+// ---------------------------------------------------------------------------
+
+// The exact set of names the bundled IIFE hangs off window.__SLIDEMIND_PLAN__ —
+// this is the contract the overlay (plan-overlay.js) reads. Every name here must
+// resolve to a top-level binding in one of the five concatenated modules.
+const PLAN_NAMESPACE_EXPORTS = [
+  "renderPlanMarkdown",
+  "addEditableAttributes",
+  "isEditableKind",
+  "replaceRenderedMarkdownBlock",
+  "splitPlanMarkdownIntoSegments",
+  "replaceStoryboardSegment",
+  "extractRedThreadMessages",
+  "findRedThreadSection",
+  "parseStoryboardCanvas",
+  "serializeStoryboardCanvas",
+  "backboneFromMessages",
+  "parsePlanBackbone",
+  "applyPlanBackbone",
+  "stageStoryIteration",
+  "STORYBOARD_WIDTH",
+  "STORYBOARD_HEIGHT",
+  "BODY_SAFE_AREA",
+  "MIN_BLOCK_WIDTH",
+  "MIN_BLOCK_HEIGHT",
+  "MAX_BLOCKS",
+  "MAX_DESIGN_ELEMENT_LENGTH",
+  "MAX_CONTENT_LENGTH",
+];
+
+// Turn a dependency-free ESM module's source into plain browser JS that runs
+// inside a shared IIFE scope: drop single-line `import … from "…";` statements
+// (all inter-module imports across the plan-review modules are single-line) and
+// strip the leading `export ` keyword from declarations. The imported names are
+// provided by an earlier module in the concatenation, so removing the import
+// line just leaves the reference resolving to that earlier top-level binding.
+export function stripModuleSyntax(src) {
+  return String(src || "")
+    .replace(/^\s*import\s+[^;]*?from\s*["'][^"']+["'];?\s*$/gm, "")
+    .replace(/^export\s+/gm, "");
+}
+
+// Bundle the five plan-review modules into one IIFE for the browser page, in
+// dependency order (schema → storyboard-markdown → backbone → edit → plan-md).
+// The IIFE exposes window.__SLIDEMIND_RENDER_MD__ (back-compat with the old
+// preview) and window.__SLIDEMIND_PLAN__ (the full namespace the overlay reads).
+// Exported so a test can evaluate the output against a stub window and catch a
+// strip-regex miss or a top-level name collision for real.
+export function bundlePlanModules({ schema, storyboardMd, backbone, edit, planMd } = {}) {
+  const body = [schema, storyboardMd, backbone, edit, planMd]
+    .map(stripModuleSyntax)
+    .join("\n");
+  return (
+    "(function () {\n" +
+    body +
+    "\nwindow.__SLIDEMIND_RENDER_MD__ = renderPlanMarkdown;\n" +
+    "window.__SLIDEMIND_PLAN__ = { " +
+    PLAN_NAMESPACE_EXPORTS.join(", ") +
+    " };\n})();\n"
+  );
+}
+
+// Read the five module sources off disk and bundle them. Split from
+// bundlePlanModules so the pure string→string step stays unit-testable.
+export function bundlePlanModulesFromDisk() {
+  return bundlePlanModules({
+    schema: fs.readFileSync(STORYBOARD_SCHEMA_PATH, "utf8"),
+    storyboardMd: fs.readFileSync(STORYBOARD_MARKDOWN_PATH, "utf8"),
+    backbone: fs.readFileSync(RED_THREAD_BACKBONE_PATH, "utf8"),
+    edit: fs.readFileSync(PLAN_MARKDOWN_EDIT_PATH, "utf8"),
+    planMd: fs.readFileSync(PLAN_MD_PATH, "utf8"),
+  });
+}
+
+// ---------------------------------------------------------------------------
+// page
+// ---------------------------------------------------------------------------
+
+// The rendered-markdown chrome for #plan-root (the live preview's content, and
+// the whole page when JS is off). The overlay injects the header / editor /
+// dock CSS itself; this only styles the plan text so it reads as a compact dark
+// document. Hex colours are fine here — src/ is not parity-linted and this
+// palette mirrors the overlay's neutral dark product tones.
+const PAGE_CSS = `
+:root{color-scheme:dark;}
+html,body{margin:0;background:#111113;color:#ededed;}
+body{font-family:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+-webkit-font-smoothing:antialiased;text-rendering:optimizeLegibility;}
+#plan-root{max-width:720px;margin:0 auto;padding:40px 28px 140px;
+line-height:1.65;font-size:15.5px;color:#d6d6d9;}
+#plan-root h1,#plan-root h2,#plan-root h3,#plan-root h4,#plan-root h5,#plan-root h6{
+color:#f4f4f5;font-weight:600;line-height:1.28;margin:1.6em 0 .5em;}
+#plan-root h1{font-size:1.95em;margin-top:.2em;}
+#plan-root h2{font-size:1.5em;padding-bottom:.24em;border-bottom:1px solid #26262b;}
+#plan-root h3{font-size:1.22em;}
+#plan-root h4{font-size:1.05em;}
+#plan-root h5,#plan-root h6{font-size:.95em;color:#c4c4c9;}
+#plan-root p{margin:.7em 0;}
+#plan-root ul,#plan-root ol{margin:.6em 0;padding-left:1.5em;}
+#plan-root li{margin:.3em 0;}
+#plan-root blockquote{margin:.95em 0;padding:.45em 1em;border-left:3px solid #3a3a40;
+color:#a8a8ad;background:rgba(255,255,255,.02);border-radius:0 6px 6px 0;}
+#plan-root code{font-family:ui-monospace,SFMono-Regular,Menlo,Consolas,monospace;
+font-size:.88em;background:#1c1c20;padding:.12em .42em;border-radius:5px;}
+#plan-root pre{background:#0c0c0e;border:1px solid #26262b;border-radius:10px;
+padding:14px 16px;overflow-x:auto;line-height:1.5;}
+#plan-root pre code{background:none;padding:0;font-size:.86em;}
+#plan-root table{border-collapse:collapse;width:100%;margin:1em 0;font-size:.92em;
+display:block;overflow-x:auto;}
+#plan-root th,#plan-root td{border:1px solid #2b2b30;padding:7px 11px;text-align:left;}
+#plan-root th{background:#18181b;font-weight:600;color:#ededed;}
+#plan-root strong{color:#f4f4f5;}
+#plan-root a{color:#a9c2ff;}
+`;
+
+// Build the standalone plan-review page: the rendered markdown in #plan-root
+// (the no-JS fallback and the preview's initial state), the injected overlay
+// config, the bundled plan-review modules, then the overlay script itself.
+// `planModulesJs` is the prebundled IIFE from bundlePlanModules — it already
+// exposes window.__SLIDEMIND_RENDER_MD__ and window.__SLIDEMIND_PLAN__, so this
+// only inlines it verbatim (with the </script> break-out guard). Kept a pure
+// function of its inputs so it's unit-testable without a server.
+export function buildPlanPage({
+  bodyHtml,
+  previousComment,
+  overlayJs,
+  planModulesJs,
+  logoMark,
+  planBody,
+  bodyStartLine,
+  round,
+}) {
+  const cfg = safeInlineJson({
+    endpoint: "/plan-review",
+    heartbeat: "/__plan/heartbeat",
+    round: round ?? null,
+    pollMs: POLL_MS,
+    pollTtlMs: POLL_TTL_MS,
+    previousComment: previousComment ?? null,
+    logoMark: logoMark ?? null,
+    planBody: planBody ?? "",
+    bodyStartLine: bodyStartLine ?? 1,
+  });
+  const overlay = String(overlayJs || "").replace(/<\/script>/g, "<\\/script>");
+  const modulesSrc = String(planModulesJs || "").replace(/<\/script>/g, "<\\/script>");
+  const rendererBlock = modulesSrc ? "<script>\n" + modulesSrc + "\n</script>\n" : "";
+  return (
+    "<!doctype html>\n" +
+    '<html lang="en">\n' +
+    "<head>\n" +
+    '<meta charset="utf-8">\n' +
+    '<meta name="viewport" content="width=device-width, initial-scale=1">\n' +
+    "<title>Plan review</title>\n" +
+    `<style>${PAGE_CSS}</style>\n` +
+    "</head>\n" +
+    "<body>\n" +
+    `<div id="plan-root">${bodyHtml}</div>\n` +
+    `<script>window.__SLIDEMIND_PLAN_REVIEW__ = ${cfg};</script>\n` +
+    rendererBlock +
+    `<script>\n${overlay}\n</script>\n` +
+    "</body>\n" +
+    "</html>\n"
+  );
+}
+
+// ---------------------------------------------------------------------------
+// server
+// ---------------------------------------------------------------------------
+
+// Start the local plan-review server. Returns { url, port, waitForDecision,
+// close }. Serves the rendered plan.md at "/", the per-brand orb at
+// "/brand/logo" (when a bundle asset resolved), and any other deck-local file
+// (traversal-guarded) for completeness.
+export async function createPlanReviewServer({
+  deckDir,
+  body,
+  bodyStartLine,
+  previousComment = null,
+  overlayJs,
+  planModulesJs,
+  logoMark = null,
+  brandAssetPath = null,
+  port = 0,
+}) {
+  const gate = createDecisionGate({
+    timeoutMessage: "plan review timed out — no decision received",
+  });
+  // Own service marker so a tab left waiting on this port only reloads into the
+  // NEXT plan round — never into the preview gate or a foreign app on the port.
+  const hb = createHeartbeat({ service: "slidemind-plan" });
+  const overlay = overlayJs ?? fs.readFileSync(OVERLAY_PATH, "utf8");
+  const planModules = planModulesJs ?? bundlePlanModulesFromDisk();
+  const bodyHtml = renderPlanMarkdown(body, { lineOffset: bodyStartLine - 1 });
+  const indexHtml = buildPlanPage({
+    bodyHtml,
+    previousComment,
+    overlayJs: overlay,
+    planModulesJs: planModules,
+    logoMark,
+    planBody: body,
+    bodyStartLine,
+    round: hb.round,
+  });
+  const deckRoot = path.resolve(deckDir);
+
+  const server = http.createServer((req, res) => {
+    const u = new URL(req.url, "http://127.0.0.1");
+    const pathname = decodeURIComponent(u.pathname);
+
+    if (req.method === "POST" && pathname === "/plan-review") {
+      let raw = "";
+      req.on("data", (chunk) => {
+        raw += chunk;
+        if (raw.length > 5e6) req.destroy();
+      });
+      req.on("end", () => {
+        let payload;
+        try {
+          payload = JSON.parse(raw || "{}");
+        } catch {
+          payload = {};
+        }
+        res.writeHead(200, { "Content-Type": MIME[".json"] });
+        res.end(JSON.stringify({ ok: true }));
+        const commentRaw = typeof payload.comment === "string" ? payload.comment.trim() : "";
+        gate.resolve({
+          decision: payload.decision === "comments" ? "comments" : "approve",
+          comment: commentRaw || null,
+          editedPlan: typeof payload.editedPlan === "string" ? payload.editedPlan : null,
+        });
+      });
+      return;
+    }
+
+    if (req.method !== "GET") {
+      res.writeHead(405);
+      res.end();
+      return;
+    }
+
+    if (pathname === "/__plan/heartbeat") {
+      // `visible`/`round` from the poll drive the reuse-vs-fresh-tab decision:
+      // only a VISIBLE waiting tab may claim reuse (see gate-server.mjs).
+      hb.respond(res, {
+        visible: u.searchParams.get("visible") === "1",
+        tabRound: u.searchParams.get("round"),
+      });
+      return;
+    }
+
+    if (pathname === "/" || pathname === "/index.html") {
+      // A browser fetched the gate page — the end-to-end proof the plan review
+      // actually opened in front of the user (see gate-server's page-load
+      // tracker; serveAndOpen and the pending contract report from it).
+      hb.notePageLoad();
+      res.writeHead(200, { "Content-Type": MIME[".html"] });
+      res.end(indexHtml);
+      return;
+    }
+
+    if (pathname === "/brand/logo") {
+      if (!brandAssetPath) {
+        res.writeHead(404);
+        res.end("not found");
+        return;
+      }
+      fs.readFile(brandAssetPath, (err, data) => {
+        if (err) {
+          res.writeHead(404);
+          res.end("not found");
+          return;
+        }
+        const ext = path.extname(brandAssetPath).toLowerCase();
+        res.writeHead(200, { "Content-Type": MIME[ext] || "application/octet-stream" });
+        res.end(data);
+      });
+      return;
+    }
+
+    if (serveStaticFile({ roots: [deckRoot], pathname, res })) return;
+    res.writeHead(404);
+    res.end("not found");
+  });
+
+  await listenWithFallback(server, port, "127.0.0.1", (wanted, err) => {
+    process.stderr.write(
+      `plan: port ${wanted} unavailable (${err.code}); using an OS-assigned port instead.\n`,
+    );
+  });
+  const addr = server.address();
+  const url = `http://127.0.0.1:${addr.port}/`;
+
+  return {
+    url,
+    port: addr.port,
+    waitForHeartbeat: (ms) => hb.waitForHeartbeat(ms),
+    markOpenedFresh: () => hb.markFresh(),
+    waitForPageLoad: (ms) => hb.waitForPageLoad(ms),
+    pageLoaded: () => hb.pageLoaded(),
+    waitForDecision: (opts) => gate.waitForDecision(opts),
+    close() {
+      try {
+        server.close();
+      } catch {
+        /* already closing */
+      }
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// run
+// ---------------------------------------------------------------------------
+
+// Write the user's direct edit back to plan.md, preserving the frontmatter
+// fence byte-for-byte. A no-op (returns { edited:false } without touching the
+// file) when the user never edited or their text matches the current body.
+// Extracted so the write path is unit-testable without a browser/server.
+export function applyPlanEdit({ planPath, frontmatterRaw, body, editedPlan }) {
+  if (editedPlan == null || editedPlan === body) return { edited: false };
+  fs.writeFileSync(planPath, frontmatterRaw + editedPlan);
+  return { edited: true };
+}
+
+export async function runPlanReview({
+  deckDir,
+  port = null,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  // quiet: serveAndOpen's BROWSER: line owns all open/failed messaging.
+  open = (url) => openInBrowser(url, { quiet: true }),
+  openFailedGraceMs = OPEN_FAILED_GRACE_MS,
+} = {}) {
+  const base = path.basename(deckDir);
+  const planPath = path.join(deckDir, "plan.md");
+  if (!fs.existsSync(planPath)) {
+    process.stderr.write(
+      `no plan.md in ${base} — write the plan first, then re-run: slidemind plan ${base}\n`,
+    );
+    process.exitCode = 1;
+    return;
+  }
+
+  const { frontmatterRaw, body, bodyStartLine } = splitPlanFrontmatter(
+    fs.readFileSync(planPath, "utf8"),
+  );
+
+  // The plan window's logo is the add-in's genuine per-brand orb when a bundle
+  // is materialized (dark variant preferred, matching the dark UI). Absent a
+  // bundle, logoMark is null and the overlay draws its inline slide glyph.
+  const mark = resolveBrandAsset(deckDir, ["logoMarkDark", "logoMark", "logoMarkLight"]);
+  const logoMark = mark ? "/brand/logo" : null;
+  const brandAssetPath = mark?.path ?? null;
+
+  const prev = loadPlanState(deckDir);
+
+  const wantPort = port == null ? preferredGatePort(deckDir, "plan") : port;
+  const server = await createPlanReviewServer({
+    deckDir,
+    body,
+    bodyStartLine,
+    previousComment: prev.comment ?? null,
+    logoMark,
+    brandAssetPath,
+    port: wantPort,
+  });
+  // A waiting tab can only exist when the previous round ended in comments — so
+  // first runs / post-approve runs open the browser immediately (graceMs 0).
+  const browser = await serveAndOpen(server, {
+    open,
+    graceMs: prev.decision === "comments" ? GRACE_MS : 0,
+    readyLabel: "Plan review",
+    reuseNoun: "plan tab",
+    gateNoun: "plan review",
+    waitLine:
+      `Waiting for the user's decision — this command BLOCKS (up to ${Math.round(
+        timeoutMs / 60000,
+      )} min) while they review. A long quiet wait is normal; do not cancel it.`,
+  });
+
+  let decision;
+  try {
+    if (browser.launched === false) {
+      // The opener chain failed outright: the user can only reach the gate via
+      // the printed URL. Give a manually-opened tab a short window, then bail
+      // out with the pending contract (carrying the failed-open status + link)
+      // instead of blocking the agent for the full timeout on an invisible gate.
+      const loaded = await server.waitForPageLoad(openFailedGraceMs);
+      if (!loaded) {
+        const err = new Error("browser never opened — gate unseen");
+        err.code = "GATE_TIMEOUT";
+        throw err;
+      }
+    }
+    decision = await server.waitForDecision({ timeoutMs });
+  } catch (err) {
+    if (err && err.code === "GATE_TIMEOUT") {
+      // Expected outcome, not an error: exit 0 with the pending contract so the
+      // agent wraps up cleanly instead of reading a scary non-zero failure.
+      // pageLoaded is re-checked NOW (not serveAndOpen's early snapshot) so a
+      // tab that opened late still counts as "the user saw the gate".
+      process.stdout.write(
+        formatPlanPendingForHarness(deckDir, {
+          timeoutMs,
+          pageLoaded: server.pageLoaded(),
+          url: server.url,
+        }),
+      );
+      return null;
+    }
+    throw err;
+  } finally {
+    server.close();
+  }
+
+  const { edited } = applyPlanEdit({
+    planPath,
+    frontmatterRaw,
+    body,
+    editedPlan: decision.editedPlan,
+  });
+
+  const planHash = crypto
+    .createHash("sha256")
+    .update(fs.readFileSync(planPath))
+    .digest("hex");
+  savePlanState(deckDir, {
+    version: 2,
+    decision: decision.decision,
+    comment: decision.comment ?? null,
+    edited,
+    planHash,
+    at: new Date().toISOString(),
+  });
+
+  if (decision.decision === "approve") {
+    if (edited) {
+      process.stdout.write(
+        "DECISION: approved\n" +
+          "The user approved the plan — and edited plan.md directly before approving. " +
+          `Re-read ${deckDir}/plan.md: the edited text IS the approved plan. Author from ` +
+          "it, not from your earlier draft.\n",
+      );
+    } else {
+      process.stdout.write(
+        "DECISION: approved\n" +
+          "The user approved the plan. Proceed to author the slides — the plan is agreed.\n",
+      );
+    }
+  } else {
+    process.stdout.write(formatPlanFeedbackForHarness(deckDir, decision.comment, { edited }));
+  }
+  return decision;
+}
+
+function parseArgs(argv) {
+  // port null ⇒ derive the deterministic per-deck plan port; an explicit --port
+  // (incl. --port 0 for OS-random) overrides it.
+  const args = { deck: null, port: null };
+  const usage = "usage: node plan.mjs --deck <dir> [--port <n>]\n";
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--deck" && i + 1 < argv.length) {
+      args.deck = argv[++i];
+    } else if (a === "--port" && i + 1 < argv.length) {
+      args.port = parseInt(argv[++i], 10) || 0;
+    } else if (a === "-h" || a === "--help") {
+      process.stdout.write(usage);
+      process.exit(0);
+    } else {
+      process.stderr.write(`plan: unexpected argument '${a}'\n${usage}`);
+      process.exit(2);
+    }
+  }
+  if (!args.deck) {
+    process.stderr.write(`plan: --deck is required\n${usage}`);
+    process.exit(2);
+  }
+  return args;
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const deckDir = path.resolve(args.deck);
+  await runPlanReview({ deckDir, port: args.port });
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  main().catch((err) => {
+    process.stderr.write(`plan: ${err.message || err}\n`);
+    process.exit(1);
+  });
+}