slidemind 0.1.7 → 0.1.8

package/src/builders/plan.mjs

@@ -0,0 +1,575 @@
+#!/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,
+  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");
+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("");
+  }
+  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 } = {}) {
+  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.`,
+    "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";
+}
+
+// ---------------------------------------------------------------------------
+// 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 markdown renderer for the live preview, then the overlay script
+// itself. `planMdJs` is the raw plan-md.mjs source — a dependency-free ESM
+// module, so stripping its `export ` keywords makes it plain browser JS; it is
+// wrapped in an IIFE that exposes window.__SLIDEMIND_RENDER_MD__ for the
+// overlay's live re-render. Kept a pure function of its inputs so it's
+// unit-testable without a server.
+export function buildPlanPage({
+  bodyHtml,
+  previousComment,
+  overlayJs,
+  planMdJs,
+  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 rendererSrc = String(planMdJs || "")
+    .replace(/^export\s+/gm, "")
+    .replace(/<\/script>/g, "<\\/script>");
+  const rendererBlock = rendererSrc
+    ? "<script>\n(function () {\n" +
+      rendererSrc +
+      "\nwindow.__SLIDEMIND_RENDER_MD__ = renderPlanMarkdown;\n})();\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,
+  planMdJs,
+  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 planMd = planMdJs ?? fs.readFileSync(PLAN_MD_PATH, "utf8");
+  const bodyHtml = renderPlanMarkdown(body, { lineOffset: bodyStartLine - 1 });
+  const indexHtml = buildPlanPage({
+    bodyHtml,
+    previousComment,
+    overlayJs: overlay,
+    planMdJs: planMd,
+    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") {
+      hb.respond(res);
+      return;
+    }
+
+    if (pathname === "/" || pathname === "/index.html") {
+      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),
+    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,
+  open = openInBrowser,
+} = {}) {
+  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).
+  await serveAndOpen(server, {
+    open,
+    graceMs: prev.decision === "comments" ? GRACE_MS : 0,
+    readyLabel: "Plan review",
+    reuseNoun: "plan tab",
+    openedLine:
+      "Opened your browser — edit the plan or tell the agent what to change; approving starts the build.",
+    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 {
+    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.
+      process.stdout.write(formatPlanPendingForHarness(deckDir, { timeoutMs }));
+      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);
+  });
+}

package/src/builders/resolve-skill.mjs

@@ -176,17 +176,52 @@ export function resolveSkill(skillName, planMeta = {}, opts = {}) {
 // plan.md frontmatter
 // ---------------------------------------------------------------------------
 
+// Split a plan.md into its YAML-ish frontmatter fence and the markdown body,
+// LOSSLESSLY: `frontmatterRaw + body === text` byte-for-byte for every input.
+// Same fence rule as the frontmatter parser: frontmatter exists iff the text
+// starts with "---" and there is a later "\n---". `frontmatterRaw` runs through
+// the END of the closing fence line INCLUDING its trailing newline (or the whole
+// text, with an empty body, when the closing fence is the last line and carries
+// no trailing newline). `bodyStartLine` is the 1-based line the body begins on
+// (= count of "\n" in frontmatterRaw + 1). With no frontmatter the whole text is
+// the body and `bodyStartLine` is 1.
+export function splitPlanFrontmatter(text) {
+  const s = String(text);
+  if (!s.startsWith("---")) {
+    return { frontmatterRaw: "", body: s, bodyStartLine: 1 };
+  }
+  const end = s.indexOf("\n---", 3);
+  if (end < 0) {
+    return { frontmatterRaw: "", body: s, bodyStartLine: 1 };
+  }
+  // The closing fence line starts at end+1 (the first "-"); it ends at the next
+  // newline. frontmatterRaw includes that newline so the body starts clean.
+  const nlAfterFence = s.indexOf("\n", end + 1);
+  let frontmatterRaw;
+  let body;
+  if (nlAfterFence < 0) {
+    frontmatterRaw = s; // closing fence at EOF, no trailing newline
+    body = "";
+  } else {
+    frontmatterRaw = s.slice(0, nlAfterFence + 1);
+    body = s.slice(nlAfterFence + 1);
+  }
+  const bodyStartLine = (frontmatterRaw.match(/\n/g) || []).length + 1;
+  return { frontmatterRaw, body, bodyStartLine };
+}
+
 function readPlanFrontmatter(deckDir) {
   if (!deckDir) return {};
   const file = path.join(deckDir, "plan.md");
   if (!fs.existsSync(file)) return {};
   const text = fs.readFileSync(file, "utf8");
-  if (!text.startsWith("---")) return {};
-  const end = text.indexOf("\n---", 3);
-  if (end < 0) return {};
-  const body = text.slice(3, end);
+  const { frontmatterRaw } = splitPlanFrontmatter(text);
+  if (!frontmatterRaw) return {}; // no frontmatter fence → {}, exactly as before
+  // Parse key: value fields out of the fence block. The two "---" fence lines
+  // never match the field regex, so scanning the whole raw block is equivalent
+  // to scanning strictly between the fences.
   const out = {};
-  for (const line of body.split("\n")) {
+  for (const line of frontmatterRaw.split("\n")) {
     const m = line.match(/^([A-Za-z_][A-Za-z0-9_-]*)\s*:\s*(.+?)\s*$/);
     if (m) out[m[1]] = stripQuotes(m[2]);
   }