slidemind 0.3.20 → 0.4.1

package/src/builders/review.mjs

@@ -46,9 +46,10 @@ import path from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { buildDeck, openInBrowser } from "./build.mjs";
-import { draftCheckBlocker, verdictBlocker } from "./draft-check.mjs";
+import { draftCheckBlocker } from "./draft-check.mjs";
+import { isEditRouteDeck } from "./edit-route.mjs";
 import { resolveSkillForDeck } from "./resolve-skill.mjs";
-import { resolveBrandAsset } from "../bridge/bundle.mjs";
+import { resolveBrandAsset, resolveBundleDirForDeck } from "../bridge/bundle.mjs";
 import {
   MIME,
   serveStaticFile,
@@ -66,10 +67,16 @@ import {
   POLL_MS,
   POLL_TTL_MS,
 } from "./gate-server.mjs";
+import {
+  bundleOwnedFiles,
+  deckSlug,
+  previewPath,
+  statePath,
+} from "../lib/deck-paths.mjs";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
-const OVERLAY_PATH = path.join(__dirname, "review-overlay.js");
+export const OVERLAY_PATH = path.join(__dirname, "review-overlay.js");
 const REVIEW_STATE_FILE = "review.json";
 // No decision timeout: the gate returns only on the user's decision (or when
 // no browser could be opened at all — see openFailedGraceMs). An agent cannot
@@ -78,6 +85,36 @@ const REVIEW_STATE_FILE = "review.json";
 // lands. Pass timeoutMs explicitly to cap the wait (tests).
 const DEFAULT_TIMEOUT_MS = null;
 
+// The bundle's assets dir, or null when no design is materialized for the deck
+// (the preview then carries no brand chrome and the page has nothing to rewrite).
+export function brandAssetsDirForDeck(deckDir) {
+  try {
+    const dir = resolveSkillForDeck(deckDir)?.brand?.assetsDir;
+    return dir && fs.existsSync(dir) ? dir : null;
+  } catch {
+    return null;
+  }
+}
+
+// A browser on an http page may not load file: subresources, so the absolute
+// bundle URLs buildDeck wrote for the disk view (chrome-*, logos, decor) become
+// `route`, which the serving page answers from that same directory. Both the
+// standalone review server and the workspace serve the page through this.
+export function routeBrandAssets(pageHtml, brandAssetsDir, route) {
+  if (!brandAssetsDir) return pageHtml;
+  const brandUrl = pathToFileURL(brandAssetsDir).href.replace(/\/$/, "");
+  return pageHtml.split(brandUrl).join(route);
+}
+
+// The review window's logo is the add-in's genuine per-brand orb: a PNG
+// shipped on the bundle as a role-keyed asset, served from the bundle cache
+// (never copied into the deck). The UI is dark, so prefer the dark variant. When absent
+// (brand predates the feature / bundle not re-materialized), the overlay shows
+// a plain slide glyph — the CLI no longer re-derives an orb.
+export function reviewLogoFile(deckDir) {
+  return resolveBrandAsset(deckDir, ["logoMarkDark", "logoMark", "logoMarkLight"])?.filename ?? null;
+}
+
 function clamp01(n) {
   return n < 0 ? 0 : n > 1 ? 1 : n;
 }
@@ -196,7 +233,7 @@ export function formatCommentsForHarness(deckDir, comments) {
   // persisted round is what survives.
   out.push(
     `This round (all ${n} comment${n === 1 ? "" : "s"}) is also saved verbatim in ` +
-      `${path.join(deckDir, REVIEW_STATE_FILE)} — if this output looks truncated or ` +
+      `${statePath(deckDir, REVIEW_STATE_FILE)} — if this output looks truncated or ` +
       `you can't see every numbered comment above, read that file for the full list ` +
       `instead of guessing or asking the user to re-type anything.`,
   );
@@ -204,22 +241,58 @@ export function formatCommentsForHarness(deckDir, comments) {
   // Imperative, stateful tail (mirrors plan.mjs's formatPlanCommentsForHarness):
   // the reviewer's tab is waiting on the next `slidemind review` run — nothing
   // reaches them until it runs. An agent that ends its turn here strands them.
+  // The draft check sits between edit and re-run because `review` refuses a
+  // slide edited since its last draft check (`[draft:stale]`, draft-check.mjs):
+  // telling the agent to re-run `review` straight away costs a refused call.
+  const slug = deckSlug(deckDir);
+  const cited = [
+    ...new Set(
+      rows
+        .map((c) => c.jsxPath)
+        .filter((p) => p.startsWith("slides/") && p.endsWith(".jsx"))
+        .map((p) => path.basename(p)),
+    ),
+  ];
   out.push("Fix exactly what the comments ask for at the cited lines — read the file");
   out.push("before you edit. Then re-run the gate in the same turn:");
   out.push("  1. Edit the cited slides/*.jsx file(s) at the given lines.");
-  out.push(`  2. Re-run: slidemind review ${path.basename(deckDir)}`);
+  out.push(
+    `  2. Draft-check every slide you edited: slidemind view-draft ${slug}` +
+      (cited.length ? ` --only ${cited.join(",")}` : "") +
+      " — and fix what it measures (review refuses a slide edited since its last draft check).",
+  );
+  out.push(`  3. Re-run: slidemind review ${slug}`);
   out.push("The re-run rebuilds the preview and reopens their same tab (addressed pins");
   out.push("show as ghost pins), and the user reviews again — several rounds are normal.");
   out.push("Do NOT end your turn, do NOT export anything, and do NOT send the user back");
-  out.push("to the browser before step 2.");
+  out.push("to the browser before step 3.");
   return out.join("\n") + "\n";
 }
 
+const REVIEW_APPROVED_TEXT =
+  "DECISION: approved\n" +
+  "The user approved the preview. Proceed to produce the output they asked " +
+  "for (slidemind push / slidemind build-pptx). One approval covers the task.\n";
+
+/**
+ * A workspace task's answer, printed exactly as the standalone gate prints its
+ * own: the pins come from the gate record the answer wrote (review.json, the
+ * same operation), else the task's own comment text.
+ */
+export function formatReviewTaskDecision(deckDir, task, { note = null } = {}) {
+  const head = note ? `NOTE: ${note}\n` : "";
+  if (task?.response?.action === "approve") return head + REVIEW_APPROVED_TEXT;
+  const state = loadReviewState(deckDir);
+  const mine = Boolean(state.operationId) && task?.response?.operationId === state.operationId;
+  const comments = mine ? state.comments : task?.response?.comment ? [{ text: task.response.comment }] : [];
+  return head + formatCommentsForHarness(deckDir, comments);
+}
+
 // Render the no-answer outcome for the harness — same contract as plan.mjs's
 // formatPlanPendingForHarness: an expected state with resume instructions, not
 // a failure and never an implicit approval.
 export function formatReviewPendingForHarness(deckDir, { timeoutMs, pageLoaded, url } = {}) {
-  const base = path.basename(deckDir);
+  const base = deckSlug(deckDir);
   const waited = timeoutMs
     ? `the gate waited ${Math.max(1, Math.round(timeoutMs / 60000))} minutes and the user hasn't answered.`
     : "the gate closed without an answer from the user.";
@@ -237,7 +310,7 @@ export function formatReviewPendingForHarness(deckDir, { timeoutMs, pageLoaded,
   ].join("\n") + "\n";
 }
 
-function injectReview(html, cfgExtra, overlayJs, logoMark = null, round = null) {
+export function injectReview(html, cfgExtra, overlayJs, logoMark = null, round = null) {
   const cfg = safeInlineJson({
     endpoint: "/review",
     heartbeat: "/__review/heartbeat",
@@ -264,7 +337,7 @@ const EMPTY_STATE = { version: 2, decision: null, comments: [] };
 // drives the tab-reuse grace window in runReview (a waiting tab can only exist
 // after a prior comments round).
 export function loadReviewState(deckDir) {
-  const f = path.join(deckDir, REVIEW_STATE_FILE);
+  const f = statePath(deckDir, REVIEW_STATE_FILE);
   if (!fs.existsSync(f)) return { ...EMPTY_STATE };
   try {
     const data = JSON.parse(fs.readFileSync(f, "utf8"));
@@ -275,19 +348,41 @@ export function loadReviewState(deckDir) {
       comments: normalizeReviewComments(data.comments),
       deckHash: data.deckHash ?? null,
       at: data.at ?? null,
+      // Workspace provenance (respondPreview): which operation wrote this round
+      // and who answered. Absent on rounds the standalone gate recorded.
+      operationId: typeof data.operationId === "string" ? data.operationId : null,
+      actor: data.actor ?? null,
+      approval: readApproval(data),
     };
   } catch {
     return { ...EMPTY_STATE };
   }
 }
 
+// The deck's standing sign-off: the round that approved, carried through any
+// later comments round (respondPreview writes it forward). An approving round
+// is its own record, so only a later round stores the field.
+function readApproval(data) {
+  const a = data.approval;
+  if (a && typeof a === "object" && typeof a.deckHash === "string") {
+    return { at: a.at ?? null, deckHash: a.deckHash, actor: a.actor ?? null };
+  }
+  if (data.decision === "approve") return { at: data.at ?? null, deckHash: data.deckHash ?? null, actor: data.actor ?? null };
+  return null;
+}
+
 // What the user reviewed: every file under slides/ (jsx + reused native .pptx)
-// and assets/ (downloaded imagery), hashed by path + bytes. Recorded with the
-// decision and re-checked by push/build-pptx, so an approval binds to exactly
-// the content the user saw — any edit after the checkmark sends the deck back
-// through the gate.
+// and DECK-OWNED assets/ (downloaded imagery), hashed by path + bytes. Copies of
+// the bundle a pre-workspace deck still carries are skipped — verified copies, by
+// bundle manifest and byte identity, so re-materializing the design with the same
+// content cannot invalidate an approval while a user's own `master-data.png` still
+// counts. Recorded with the decision, so a round binds to exactly the content the
+// user saw: an answer on since-edited slides is refused as stale, and a gate
+// asked again on unchanged slides answers at once. It does not gate delivery
+// after the approval — see requireReviewApproved.
 export function hashDeckContent(deckDir) {
   const h = crypto.createHash("sha256");
+  const bundleOwned = bundleOwnedFiles(deckDir, resolveBundleDirForDeck(deckDir));
   const walk = (dir) => {
     let entries = [];
     try {
@@ -299,7 +394,9 @@ export function hashDeckContent(deckDir) {
       const p = path.join(dir, e.name);
       if (e.isDirectory()) walk(p);
       else if (e.isFile()) {
-        h.update(path.relative(deckDir, p).split(path.sep).join("/"));
+        const rel = path.relative(deckDir, p).split(path.sep).join("/");
+        if (bundleOwned.has(rel)) continue;
+        h.update(rel);
         h.update("\0");
         h.update(fs.readFileSync(p));
         h.update("\0");
@@ -311,31 +408,115 @@ export function hashDeckContent(deckDir) {
 }
 
 // The human checkmark push/build-pptx require — enforced by the CLI, not by the
-// skill's prose. null = approved and unchanged since; otherwise the agent-facing
+// skill's prose. ONE per deck: the approval builds the deck, and every change
+// after it (an edit, a comment on the delivered deck, a reconcile fold, a
+// repair) goes straight into the .pptx, where the user sees it, without a second
+// review. So this asks whether the deck ever passed the review, never whether
+// the slides still match it. A deck adopted from the user's own .pptx (the edit
+// route) never asks at all: it was a deck before any agent touched it, so its
+// edits are already "afterwards". null = passed; otherwise the agent-facing
 // reason plus the command that clears it.
 export function requireReviewApproved(deckDir) {
-  const base = path.basename(deckDir);
+  if (loadReviewState(deckDir).approval) return null;
+  if (isEditRouteDeck(deckDir)) return null;
+  const base = deckSlug(deckDir);
+  return (
+    `${base} has not passed the preview review — a human must approve it first: ` +
+    `run \`slidemind review ${base}\` and wait for DECISION: approved.`
+  );
+}
+
+// The latest round approved exactly these slides: a gate asked again on
+// unchanged content answers at once instead of asking the user twice.
+export function previewApprovedAsIs(deckDir) {
   const state = loadReviewState(deckDir);
-  if (state.decision !== "approve") {
-    return (
-      `${base} has not passed the preview review — a human must approve it first: ` +
-      `run \`slidemind review ${base}\` and wait for DECISION: approved.`
-    );
-  }
-  if (state.deckHash !== hashDeckContent(deckDir)) {
-    return (
-      `${base}'s slides changed since the user approved the preview — ` +
-      `re-run \`slidemind review ${base}\` for a fresh sign-off.`
-    );
-  }
-  return null;
+  return state.decision === "approve" && state.deckHash === hashDeckContent(deckDir);
 }
 
-function saveReviewState(deckDir, state) {
-  fs.writeFileSync(
-    path.join(deckDir, REVIEW_STATE_FILE),
-    JSON.stringify(state, null, 2) + "\n",
-  );
+// Sidecar write as temp + rename: a gate record is either the whole round or
+// absent — a crash mid-write must not leave a half-parsed approval behind.
+export function writeStateAtomic(deckDir, name, contents) {
+  const file = statePath(deckDir, name);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString("hex")}.tmp`;
+  fs.writeFileSync(tmp, contents);
+  fs.renameSync(tmp, file);
+  return file;
+}
+
+export function saveReviewState(deckDir, state) {
+  writeStateAtomic(deckDir, REVIEW_STATE_FILE, JSON.stringify(state, null, 2) + "\n");
+}
+
+/** The preview subject as the workspace names it: `sha256:<hashDeckContent>`. */
+export function previewHash(deckDir) {
+  return "sha256:" + hashDeckContent(deckDir);
+}
+
+function bareHash(h) {
+  return typeof h === "string" ? h.replace(/^sha256:/, "") : null;
+}
+
+function refusal(status, code, message, details) {
+  return { status, body: { ok: false, error: { code, message, retryable: false, ...(details ? { details } : {}) } } };
+}
+
+// The ONE write path of a preview decision — the standalone gate's tail and the
+// workspace task response both land here, so review.json carries the same
+// evidence whichever page answered. `expectedHash` is the subject the reviewer
+// saw (`previewHash` or its bare hex); a deck edited since is refused, never
+// approved by accident. `operationId` makes a repeat idempotent: the recorded
+// round comes back unchanged, and a different decision under the same id is
+// refused. `write` is the seam a crash test injects; the record is written last
+// and atomically, so a throw here leaves no approval behind.
+export function respondPreview(
+  deckDir,
+  {
+    action,
+    expectedHash = null,
+    payload = {},
+    actor = null,
+    operationId = null,
+    at = new Date().toISOString(),
+    write = saveReviewState,
+  } = {},
+) {
+  const decision =
+    action === "approve" ? "approve" : action === "comment" || action === "comments" ? "comments" : null;
+  if (!decision) return refusal(422, "validation_failed", `unknown preview action '${action}'`);
+  const prev = loadReviewState(deckDir);
+  if (operationId && prev.operationId === operationId) {
+    if (prev.decision !== decision || (expectedHash != null && bareHash(expectedHash) !== prev.deckHash)) {
+      return refusal(409, "operation_mismatch", "this operation id already recorded a different response");
+    }
+    return {
+      status: 200,
+      body: { ok: true, decision: prev.decision, comments: prev.comments, deckHash: prev.deckHash, hash: "sha256:" + prev.deckHash, at: prev.at, replayed: true },
+    };
+  }
+  const deckHash = hashDeckContent(deckDir);
+  if (expectedHash != null && bareHash(expectedHash) !== deckHash) {
+    return refusal(409, "stale_subject", "the slides changed since this preview was reviewed", {
+      expected: expectedHash,
+      current: "sha256:" + deckHash,
+    });
+  }
+  const comments = decision === "comments" ? normalizeReviewComments(payload?.comments) : [];
+  // A comments round after the approval keeps it: the review is one-time per
+  // deck, and asking for a change is not taking the sign-off back.
+  const kept = decision === "comments" ? prev.approval : null;
+  const state = {
+    version: 2,
+    decision,
+    comments,
+    deckHash,
+    at,
+    ...(kept ? { approval: { at: kept.at, deckHash: kept.deckHash, ...(kept.actor ? { actor: kept.actor } : {}) } } : {}),
+    ...(operationId ? { operationId } : {}),
+    ...(actor ? { actor } : {}),
+  };
+  write(deckDir, state);
+  return { status: 200, body: { ok: true, decision, comments, deckHash, hash: "sha256:" + deckHash, at } };
 }
 
 // Deterministic per-deck port so a tab left waiting from the previous round can
@@ -347,12 +528,13 @@ export function preferredPortForDeck(deckDir) {
 }
 
 // Start the local review server. Returns { url, port, waitForDecision, waitForHeartbeat, close }.
-// presentation.html must already exist in deckDir (build it first).
+// preview/presentation.html must already exist in the workspace (build it first).
 export async function createReviewServer({
   deckDir,
   ledgerSeed = [],
   overlayJs,
   logoMark = null,
+  brandAssetsDir = null,
   port = 0,
 }) {
   const gate = createDecisionGate();
@@ -362,8 +544,11 @@ export async function createReviewServer({
   const hb = createHeartbeat({ service: "slidemind-review" });
   const overlay =
     overlayJs ?? fs.readFileSync(OVERLAY_PATH, "utf8");
+  // The bundle's file: URLs become /brand/assets, served below from the same
+  // directory. The deck itself still carries no copy.
+  const pageHtml = fs.readFileSync(previewPath(deckDir, "presentation.html"), "utf8");
   const indexHtml = injectReview(
-    fs.readFileSync(path.join(deckDir, "presentation.html"), "utf8"),
+    routeBrandAssets(pageHtml, brandAssetsDir, "/brand/assets"),
     {
       // deck: the sessionStorage namespace for this deck's pin ledger.
       // ledgerSeed: the previous round's pins — a FRESH tab (no session) renders
@@ -372,14 +557,14 @@ export async function createReviewServer({
       // a content hash: a fix round that edited nothing hashes identically, and
       // an unreadable slides/ dir hashed to "" — both made the transition
       // undetectable, which stranded pins in "sent" forever.
-      deck: path.basename(path.resolve(deckDir)),
+      deck: deckSlug(deckDir),
       ledgerSeed: normalizeReviewComments(ledgerSeed),
     },
     overlay,
     logoMark,
     hb.round,
   );
-  const deckRoot = path.resolve(deckDir);
+  const workspaceRoot = path.resolve(deckDir);
 
   const server = http.createServer((req, res) => {
     const u = new URL(req.url, "http://127.0.0.1");
@@ -437,10 +622,27 @@ export async function createReviewServer({
       return;
     }
 
-    // Traversal-guarded static serving from the deck root; a miss or an escape
+    // Traversal-guarded static serving from the workspace root; a miss or an escape
     // attempt falls through to the caller's 404 (serveStaticFile never writes on
     // a non-match).
-    if (serveStaticFile({ roots: [deckRoot], pathname, res })) return;
+    // Brand files come from the bundle cache; everything else (slides/, the
+    // deck's own assets/, preview/fonts/) from the workspace.
+    if (pathname.startsWith("/brand/assets/")) {
+      if (
+        brandAssetsDir &&
+        serveStaticFile({
+          roots: [brandAssetsDir],
+          pathname: pathname.slice("/brand/assets".length),
+          res,
+        })
+      ) {
+        return;
+      }
+      res.writeHead(404);
+      res.end("not found");
+      return;
+    }
+    if (serveStaticFile({ roots: [workspaceRoot], pathname, res })) return;
     res.writeHead(404);
     res.end("not found");
   });
@@ -503,23 +705,23 @@ export async function runReview({
   // quiet: serveAndOpen's BROWSER: line owns all open/failed messaging.
   open = (url) => openInBrowser(url, { quiet: true }),
   openFailedGraceMs = OPEN_FAILED_GRACE_MS,
-  allowDraftDefects = false,
+  // null = decide (gateUsesWorkspace); tests force either path
+  useWorkspace = null,
 } = {}) {
-  await buildDeck(deckDir);
-
-  // The gate does not open on defects the last draft check MEASURED (fill
-  // bands, dropped connectors, unused assets) while the slide files are
-  // unchanged since: a warning printed after "task done" is a warning nobody
-  // acts on. Editing the slide re-arms the check; --allow-draft-defects is
-  // the explicit override.
-  if (!allowDraftDefects) {
-    const standing = draftCheckBlocker(deckDir) ?? verdictBlocker(deckDir);
-    if (standing) {
-      throw new Error(
-        `review not opened — ${standing}\n` +
-          "(pass --allow-draft-defects to open the gate anyway)",
-      );
-    }
+  const gate = await import("../workspace/gate-client.mjs");
+  const viaWorkspace = useWorkspace ?? gate.gateUsesWorkspace(deckDir, "preview-review");
+  // Asked again about this exact, still-current build (the build and its checks
+  // passed when it was asked — the user said "continue" without answering yet),
+  // or receiving an answer the user already gave: nothing to rebuild first.
+  const resuming = viaWorkspace && ((await gate.previewAnswerWaiting(deckDir)) || (await gate.openPreviewQuestionIsCurrent(deckDir)));
+  if (!resuming) await buildDeck(deckDir);
+
+  // The user reviews only slides the draft check passed: every slide checked
+  // at its current bytes, no defect of the shared table (draft-lines.mjs)
+  // standing. There is no override — the same rule holds delivery.
+  if (!resuming) {
+    const standing = draftCheckBlocker(deckDir);
+    if (standing) throw new Error(`review not opened — ${standing}`);
   }
 
   // Headless simulation runs (scripts/codex-sim.mjs): approve without a browser.
@@ -540,23 +742,38 @@ export async function runReview({
     return { decision: "approve", comments: [] };
   }
 
+  // The human answers in the workspace: the preview built above is what the page
+  // shows; ask there and return at once (ASK + SAY; the agent ends its turn). The
+  // user's pasted message names this command again, which hands their answer
+  // over. A workspace that cannot be used is a blocker — never a second,
+  // standalone page (doc 21).
+  if (viaWorkspace) {
+    const r = await gate.runWorkspaceGate({
+      deckDir,
+      kind: "preview-review",
+      approvedNow: () => previewApprovedAsIs(deckDir),
+      format: (task, { note }) => process.stdout.write(formatReviewTaskDecision(deckDir, task, { note })),
+    });
+    if (r.blocked) {
+      process.stdout.write(`BLOCKED: ${r.blocked.code}\n${r.blocked.message}\n`);
+      process.exitCode = 2;
+      return null;
+    }
+    return r.decision === "pending" ? null : { decision: r.decision };
+  }
+
   const prev = loadReviewState(deckDir);
-  // Hashed after buildDeck (it copies brand assets into assets/) and before the
-  // gate opens: the agent is blocked while the user reviews, so this IS the
-  // content the decision refers to.
+  // Hashed before the gate opens: the agent is blocked while the user reviews,
+  // so this IS the content the decision refers to.
   const deckHash = hashDeckContent(deckDir);
-  // The review window's logo is the add-in's genuine per-brand orb: a PNG
-  // shipped on the bundle as a role-keyed asset (copied into the deck by
-  // buildDeck). The review UI is dark, so prefer the dark variant. When absent
-  // (brand predates the feature / bundle not re-materialized), the overlay shows
-  // a plain slide glyph — the CLI no longer re-derives an orb.
-  const mark = resolveBrandAsset(deckDir, ["logoMarkDark", "logoMark", "logoMarkLight"]);
-  const logoMark = mark ? "/assets/" + mark.filename : null;
+  const mark = reviewLogoFile(deckDir);
+  const logoMark = mark ? "/brand/assets/" + mark : null;
   const wantPort = port == null ? preferredPortForDeck(deckDir) : port;
   const server = await createReviewServer({
     deckDir,
     ledgerSeed: prev.comments || [],
     logoMark,
+    brandAssetsDir: brandAssetsDirForDeck(deckDir),
     port: wantPort,
   });
   // A waiting tab can only exist when the previous round ended in comments — so
@@ -604,21 +821,20 @@ export async function runReview({
     server.close();
   }
 
-  const comments = normalizeReviewComments(decision.comments);
-  saveReviewState(deckDir, {
-    version: 2,
-    decision: decision.decision,
-    comments,
-    deckHash,
-    at: new Date().toISOString(),
+  // No `expectedHash` here, exactly as `runPlanReview` does it. The hash binds the
+  // gate's ROUND (the page the user answered); binding the write too would make
+  // any write into slides/ or assets/ during the review refuse with stale_subject
+  // and throw away the comments the user just typed. The agent is blocked while
+  // the user reviews, so the hash this call records is the content they answered.
+  const answered = respondPreview(deckDir, {
+    action: decision.decision,
+    payload: { comments: decision.comments },
   });
+  if (answered.status !== 200) throw new Error(answered.body.error.message);
+  const comments = answered.body.comments;
 
   if (decision.decision === "approve") {
-    process.stdout.write(
-      "DECISION: approved\n" +
-        "The user approved the preview. Proceed to produce the output they asked " +
-        "for (slidemind push / slidemind build-pptx). One approval covers the task.\n",
-    );
+    process.stdout.write(REVIEW_APPROVED_TEXT);
   } else {
     process.stdout.write(
       formatCommentsForHarness(deckDir, comments),
@@ -630,19 +846,24 @@ export async function runReview({
 function parseArgs(argv) {
   // port null ⇒ derive the deterministic per-deck port; an explicit --port
   // (incl. --port 0 for OS-random) overrides it.
-  const args = { deck: null, port: null, allowDraftDefects: false };
+  const args = { deck: null, port: null, wait: null };
   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 === "--allow-draft-defects") {
-      args.allowDraftDefects = true;
+    } else if (a === "--wait" && i + 1 < argv.length) {
+      // retired with the bounded wait (a question returns at once); accepted so a
+      // stale skill or script that still passes it does not fail
+      i++;
+    } else if (a === "--json") {
+      // Accepted like every deck command's --json (SKILL.md); the gate's
+      // output already is its machine contract — the one DECISION: line.
     } else if (a === "-h" || a === "--help") {
       process.stdout.write(
-        "Usage: slidemind review <deck> [--port <n>] [--allow-draft-defects]\n" +
-          "       node src/builders/review.mjs --deck <deck> [--port <n>] [--allow-draft-defects]\n",
+        "Usage: slidemind review <deck> [--port <n>]\n" +
+          "       node src/builders/review.mjs --deck <deck> [--port <n>]\n",
       );
       process.exit(0);
     } else {
@@ -660,7 +881,7 @@ function parseArgs(argv) {
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const deckDir = path.resolve(args.deck);
-  await runReview({ deckDir, port: args.port, allowDraftDefects: args.allowDraftDefects });
+  await runReview({ deckDir, port: args.port });
 }
 
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {