@tenonhq/dovetail-dashboard 0.0.29 → 0.0.30

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog — @tenonhq/dovetail-dashboard
+
+## Unreleased — Phase E (claude-plans v2 bidirectional surfaces)
+
+- **New dependency** `@tenonhq/dovetail-claude-plans` (workspace) — write routes call directly into the package's storage layer so the state machine, conflict rule, and dispatch-token lifecycle are enforced in exactly one place.
+- **Three new POST routes** under `/api/claude-plans/:slug/`:
+  - `answers` → `recordAnswer()`. Forces `answered_by: "dashboard"` by default.
+  - `stage` → `setStage()`. Forces `source: "dashboard"` so the conflict rule (design doc §4) treats operator moves as authoritative.
+  - `dispatch` → `dispatchStage()`. Pass-through; dashboard sends dry-run first, then confirm+token.
+- **Typed error envelope** — every error response carries `{ error: <code>, name: <ClassName>, message }`. HTTP status reflects the failure mode: 400 (validation / no-token), 404 (plan-not-found), 409 (illegal transition / conflict), 410 (stale token), 424 (missing agent), 500 (spawn / internal).
+- **Stage Map strip** on the plan detail page — 10 stage pills with current-stage highlight, click-to-set_stage, per-stage Dispatch (▶) button, and a ⚠ marker for stages whose agent hasn't shipped yet (test-first, test-reality).
+- **Dispatch dialog** — opens on Dispatch click, POSTs dry-run first, renders the resolved command + cwd, then the operator confirms to fire a live dispatch (which consumes the cached `set_stage` token).
+- **Questions & Answers tab** — lists `plan.questions`, lets the operator answer each one (free-form input + clickable suggested options); SSE plan upsert re-renders the tab automatically.
+- **Per-plan token cache** — the most recent `set_stage` response is held client-side per plan so the Dispatch button has a token to consume. Cache is cleared on plan switch.
+- **Rate limited** — all three new routes share `claudePlansLimiter` (60 req / 15 min / IP), same as the existing destructive delete route.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tenonhq/dovetail-dashboard",
-  "version": "0.0.29",
+  "version": "0.0.30",
   "description": "Update Set Dashboard for Dovetail",
   "main": "server.js",
   "scripts": {
@@ -9,6 +9,7 @@
     "postpublish": "npm run version:bump"
   },
   "dependencies": {
+    "@tenonhq/dovetail-claude-plans": "*",
     "axios": "^1.5.1",
     "axios-cookiejar-support": "^4.0.7",
     "chokidar": "^3.6.0",

package/public/claude-plans.css

@@ -1311,3 +1311,175 @@
 .cp-topic-chip--active .cp-topic-chip-count {
   background: color-mix(in srgb, var(--accent-fg) 20%, transparent);
 }
+
+/* ===========================================================================
+ * v2 — Stage Map, Questions tab, Dispatch dialog (Phase E)
+ * Lightweight additions on top of the existing token system.
+ * ========================================================================= */
+
+.cp-stage-map {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  padding: 12px 0;
+  margin-bottom: 12px;
+  border-bottom: 1px solid var(--border, #e5e7eb);
+}
+.cp-stage {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  padding: 6px 10px;
+  border: 1px solid var(--border, #d1d5db);
+  border-radius: 999px;
+  background: var(--bg-elevated, #fff);
+  font-size: 12px;
+  font-weight: 500;
+  cursor: pointer;
+  user-select: none;
+}
+.cp-stage:hover { background: var(--bg-hover, #f3f4f6); }
+.cp-stage--current {
+  background: var(--accent-bg, #2563eb);
+  color: var(--accent-fg, #fff);
+  border-color: var(--accent-bg, #2563eb);
+}
+.cp-stage--illegal {
+  opacity: 0.4;
+  cursor: not-allowed;
+}
+.cp-stage--missing-agent::after {
+  content: "⚠";
+  font-size: 11px;
+  margin-left: 4px;
+}
+.cp-stage-dispatch {
+  margin-left: 4px;
+  padding: 0 6px;
+  font-size: 11px;
+  background: transparent;
+  border: 1px solid currentColor;
+  border-radius: 4px;
+  cursor: pointer;
+  color: inherit;
+}
+.cp-stage-dispatch:hover { background: color-mix(in srgb, currentColor 12%, transparent); }
+
+.cp-question {
+  padding: 12px;
+  border: 1px solid var(--border, #e5e7eb);
+  border-radius: 8px;
+  margin-bottom: 12px;
+  background: var(--bg-elevated, #fff);
+}
+.cp-question--answered { opacity: 0.78; }
+.cp-question-header {
+  display: flex;
+  gap: 8px;
+  align-items: center;
+  margin-bottom: 6px;
+  font-size: 11px;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--text-muted, #6b7280);
+}
+.cp-question-stage {
+  padding: 2px 6px;
+  border-radius: 4px;
+  background: color-mix(in srgb, currentColor 10%, transparent);
+}
+.cp-question-q { font-size: 14px; margin-bottom: 10px; font-weight: 500; }
+.cp-question-options {
+  display: flex; flex-wrap: wrap; gap: 6px;
+  margin-bottom: 10px;
+}
+.cp-question-option {
+  padding: 4px 8px;
+  border: 1px solid var(--border, #d1d5db);
+  border-radius: 4px;
+  background: var(--bg-elevated, #fff);
+  font-size: 12px;
+  cursor: pointer;
+}
+.cp-question-option:hover { background: var(--bg-hover, #f3f4f6); }
+.cp-question-answer-form { display: flex; gap: 6px; }
+.cp-question-answer-input {
+  flex: 1;
+  padding: 6px 8px;
+  border: 1px solid var(--border, #d1d5db);
+  border-radius: 4px;
+  font: inherit;
+}
+.cp-question-answer-submit {
+  padding: 6px 12px;
+  border: 1px solid var(--accent-bg, #2563eb);
+  background: var(--accent-bg, #2563eb);
+  color: var(--accent-fg, #fff);
+  border-radius: 4px;
+  cursor: pointer;
+}
+.cp-question-recorded {
+  font-size: 13px;
+  padding: 8px 10px;
+  background: color-mix(in srgb, var(--accent-bg, #2563eb) 10%, transparent);
+  border-radius: 4px;
+}
+.cp-question-recorded-meta {
+  font-size: 11px;
+  color: var(--text-muted, #6b7280);
+  margin-top: 4px;
+}
+
+.cp-dispatch-dialog {
+  position: fixed;
+  inset: 0;
+  background: rgba(0,0,0,0.4);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: 1000;
+}
+.cp-dispatch-dialog-inner {
+  background: var(--bg-elevated, #fff);
+  border-radius: 8px;
+  padding: 20px;
+  max-width: 640px;
+  width: 90%;
+  font-size: 14px;
+  box-shadow: 0 10px 30px rgba(0,0,0,0.2);
+}
+.cp-dispatch-dialog h3 { margin-top: 0; }
+.cp-dispatch-dialog pre {
+  background: var(--bg, #f9fafb);
+  border-radius: 4px;
+  padding: 10px;
+  overflow-x: auto;
+  font-size: 12px;
+}
+.cp-dispatch-dialog-actions {
+  display: flex;
+  gap: 8px;
+  margin-top: 14px;
+  justify-content: flex-end;
+}
+.cp-dispatch-dialog-actions button {
+  padding: 6px 14px;
+  border: 1px solid var(--border, #d1d5db);
+  border-radius: 4px;
+  background: var(--bg-elevated, #fff);
+  cursor: pointer;
+}
+.cp-dispatch-dialog-actions button.cp-dispatch-confirm {
+  background: var(--accent-bg, #2563eb);
+  color: var(--accent-fg, #fff);
+  border-color: var(--accent-bg, #2563eb);
+}
+.cp-dispatch-error {
+  color: #b91c1c;
+  background: #fee2e2;
+  padding: 8px 10px;
+  border-radius: 4px;
+  margin-top: 10px;
+  font-size: 13px;
+}

package/public/claude-plans.html

@@ -104,6 +104,9 @@
           <span class="cp-status-pill" id="cp-detail-status"></span>
           <span class="cp-stamp" id="cp-detail-stamp"></span>
         </header>
+        <!-- v2 Stage Map: 10-stage pipeline strip; clicking a stage triggers
+             POST /stage (subject to state-machine + conflict rules). -->
+        <div class="cp-stage-map" id="cp-stage-map" hidden></div>
         <nav class="cp-tabs">
           <button class="cp-tab active" data-tab="plan">Plan</button>
           <button class="cp-tab" data-tab="prompts">
@@ -112,10 +115,14 @@
           <button class="cp-tab" data-tab="artifacts">
             Artifacts <span class="cp-tab-count" id="cp-artifact-count">0</span>
           </button>
+          <button class="cp-tab" data-tab="questions">
+            Q&amp;A <span class="cp-tab-count" id="cp-question-count">0</span>
+          </button>
         </nav>
         <div class="cp-tab-panel" id="cp-tab-plan"></div>
         <div class="cp-tab-panel" id="cp-tab-prompts" hidden></div>
         <div class="cp-tab-panel" id="cp-tab-artifacts" hidden></div>
+        <div class="cp-tab-panel" id="cp-tab-questions" hidden></div>
       </article>
     </section>
   </main>

package/public/claude-plans.js

@@ -60,6 +60,9 @@
     planPanel: document.getElementById("cp-tab-plan"),
     artifactsPanel: document.getElementById("cp-tab-artifacts"),
     promptsPanel: document.getElementById("cp-tab-prompts"),
+    questionsPanel: document.getElementById("cp-tab-questions"),
+    questionCount: document.getElementById("cp-question-count"),
+    stageMap: document.getElementById("cp-stage-map"),
     tabs: document.querySelectorAll(".cp-tab"),
     topics: document.getElementById("cp-topics"),
     topicsCloud: document.getElementById("cp-topics-cloud"),
@@ -592,6 +595,10 @@
       renderMarkdown(plan.content_md, els.planPanel);
     }
 
+    // v2 surfaces — Stage Map strip + Questions tab.
+    renderStageMap(plan);
+    renderQuestions(plan);
+
     addPlanSectionCopyBtns();
     addTabsCopyAll(plan, artifacts, prompts);
 
@@ -706,6 +713,275 @@
     els.planPanel.hidden = tab !== "plan";
     els.artifactsPanel.hidden = tab !== "artifacts";
     if (els.promptsPanel) els.promptsPanel.hidden = tab !== "prompts";
+    if (els.questionsPanel) els.questionsPanel.hidden = tab !== "questions";
+  }
+
+  /* ─── v2 bidirectional pipeline (Phase E) ──────────────────────────────────
+   * Stage Map, Questions tab, Dispatch dialog. Server enforces every safety
+   * rule (state machine, conflict resolution, dispatch token); the client
+   * just renders state and POSTs intents. The latest set_stage token is
+   * cached per-plan so the Dispatch button can hand it back to the live call
+   * without a round-trip.
+   * ─────────────────────────────────────────────────────────────────────── */
+
+  var PIPELINE_STAGES = [
+    "research",
+    "pre-stage-improve",
+    "planning",
+    "post-plan-improve",
+    "test-first",
+    "code",
+    "per-step-review",
+    "architectural-review",
+    "test-reality",
+    "documentation"
+  ];
+
+  // Stages whose driving agent isn't shipped yet (matches dispatch.ts).
+  // dispatch_stage will raise MissingAgentError for these; the UI greys
+  // them out and adds a ⚠ marker.
+  var STAGES_MISSING_AGENT = { "test-first": true, "test-reality": true };
+
+  // Per-plan cache of the most recent setStage response. The dispatch
+  // button reads token from here. Cleared on plan switch.
+  var stageTokenCache = {};
+
+  function v2ApiPath(slug, leaf) { return "/api/claude-plans/" + slug + "/" + leaf; }
+
+  function v2Post(slug, leaf, body) {
+    return fetch(v2ApiPath(slug, leaf), {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body || {})
+    }).then(function (r) {
+      return r.json().then(function (json) {
+        if (!r.ok) {
+          var err = new Error(json.message || json.error || ("HTTP " + r.status));
+          err.code = json.error;
+          err.name = json.name || "ServerError";
+          err.status = r.status;
+          err.payload = json;
+          throw err;
+        }
+        return json;
+      });
+    });
+  }
+
+  function renderStageMap(plan) {
+    var map = els.stageMap;
+    if (!map) return;
+    map.hidden = false;
+    map.innerHTML = "";
+    var current = plan.stage || null;
+    PIPELINE_STAGES.forEach(function (stage) {
+      var pill = document.createElement("button");
+      pill.className = "cp-stage";
+      if (stage === current) pill.classList.add("cp-stage--current");
+      if (STAGES_MISSING_AGENT[stage]) pill.classList.add("cp-stage--missing-agent");
+      pill.textContent = stage;
+      pill.title = STAGES_MISSING_AGENT[stage]
+        ? stage + " — agent not shipped yet (PR #160); dispatch will raise MissingAgentError"
+        : stage + " — click to move plan here";
+      pill.addEventListener("click", function () {
+        v2Post(plan.slug, "stage", { to: stage }).then(function (res) {
+          stageTokenCache[plan.slug] = res.token;
+          showToast("Stage → " + res.stage + " (token issued)");
+        }).catch(function (err) {
+          showToast(err.code === "ILLEGAL_TRANSITION"
+            ? "Illegal move: " + err.message
+            : "Stage move failed: " + err.message);
+        });
+      });
+      // Per-stage Dispatch button (Phase E §3).
+      var dispatchBtn = document.createElement("button");
+      dispatchBtn.className = "cp-stage-dispatch";
+      dispatchBtn.textContent = "▶";
+      dispatchBtn.title = "Dispatch a Claude Code session at " + stage;
+      dispatchBtn.addEventListener("click", function (e) {
+        e.stopPropagation();
+        openDispatchDialog(plan, stage);
+      });
+      pill.appendChild(dispatchBtn);
+      map.appendChild(pill);
+    });
+  }
+
+  function openDispatchDialog(plan, stage) {
+    // Step 1 — dry-run dispatch. Render the resolved command, then offer
+    // a "Confirm live" button that re-POSTs with confirm:true + the
+    // cached token for this plan.
+    v2Post(plan.slug, "dispatch", { target_stage: stage }).then(function (dryRun) {
+      var backdrop = document.createElement("div");
+      backdrop.className = "cp-dispatch-dialog";
+      var inner = document.createElement("div");
+      inner.className = "cp-dispatch-dialog-inner";
+      inner.innerHTML =
+        "<h3>Dispatch &rarr; " + stage + "</h3>" +
+        "<p>Dry-run resolved the following spawn. Confirm to launch a real Claude Code session.</p>" +
+        "<pre>" +
+          "<strong>command:</strong> " + escapeHtml(dryRun.command) + "\n" +
+          "<strong>cwd:</strong>     " + escapeHtml(dryRun.cwd) + "\n" +
+          "<strong>plan:</strong>    " + escapeHtml(dryRun.plan_slug) + "\n" +
+          "<strong>stage:</strong>   " + escapeHtml(dryRun.target_stage) +
+        "</pre>";
+      var errorEl = document.createElement("div");
+      errorEl.className = "cp-dispatch-error";
+      errorEl.hidden = true;
+      inner.appendChild(errorEl);
+
+      var actions = document.createElement("div");
+      actions.className = "cp-dispatch-dialog-actions";
+      var cancel = document.createElement("button");
+      cancel.textContent = "Cancel";
+      cancel.addEventListener("click", function () { document.body.removeChild(backdrop); });
+      var confirm = document.createElement("button");
+      confirm.className = "cp-dispatch-confirm";
+      confirm.textContent = "Confirm live dispatch";
+      confirm.addEventListener("click", function () {
+        var token = stageTokenCache[plan.slug];
+        if (!token || !token.token) {
+          errorEl.hidden = false;
+          errorEl.textContent =
+            "No fresh dispatch token cached for this plan. Click the stage on the Stage Map first " +
+            "to mint one (tokens are 5-min, single-use, stage-bound).";
+          return;
+        }
+        if (token.issued_for_stage !== stage) {
+          errorEl.hidden = false;
+          errorEl.textContent =
+            "Cached token was issued for " + token.issued_for_stage +
+            ", not " + stage + ". Click " + stage + " on the Stage Map to issue a matching token.";
+          return;
+        }
+        confirm.disabled = true;
+        v2Post(plan.slug, "dispatch", {
+          target_stage: stage,
+          confirm: true,
+          token: token.token
+        }).then(function (live) {
+          document.body.removeChild(backdrop);
+          showToast("Live dispatch launched (pid=" + live.pid + ")");
+          delete stageTokenCache[plan.slug];
+        }).catch(function (err) {
+          confirm.disabled = false;
+          errorEl.hidden = false;
+          errorEl.textContent = (err.code || "Error") + ": " + err.message;
+        });
+      });
+      actions.appendChild(cancel);
+      actions.appendChild(confirm);
+      inner.appendChild(actions);
+      backdrop.appendChild(inner);
+      document.body.appendChild(backdrop);
+    }).catch(function (err) {
+      if (err.code === "MISSING_AGENT") {
+        showToast(stage + ": " + err.message);
+      } else {
+        showToast("Dispatch dry-run failed: " + err.message);
+      }
+    });
+  }
+
+  function escapeHtml(s) {
+    return String(s == null ? "" : s)
+      .replace(/&/g, "&amp;")
+      .replace(/</g, "&lt;")
+      .replace(/>/g, "&gt;");
+  }
+
+  function renderQuestions(plan) {
+    if (!els.questionsPanel) return;
+    var questions = plan.questions || [];
+    els.questionsPanel.innerHTML = "";
+    if (els.questionCount) els.questionCount.textContent = String(questions.length);
+    if (questions.length === 0) {
+      var empty = document.createElement("div");
+      empty.className = "cp-detail-empty";
+      empty.style.padding = "40px 0";
+      empty.textContent = "No questions yet. Call push_question from Claude (or /qa park).";
+      els.questionsPanel.appendChild(empty);
+      return;
+    }
+    questions.forEach(function (q) {
+      var card = document.createElement("div");
+      card.className = "cp-question" + (q.answer ? " cp-question--answered" : "");
+
+      var header = document.createElement("div");
+      header.className = "cp-question-header";
+      if (q.stage) {
+        var stageTag = document.createElement("span");
+        stageTag.className = "cp-question-stage";
+        stageTag.textContent = q.stage;
+        header.appendChild(stageTag);
+      }
+      if (q.asked_by) {
+        var by = document.createElement("span");
+        by.textContent = "asked by " + q.asked_by;
+        header.appendChild(by);
+      }
+      card.appendChild(header);
+
+      var qText = document.createElement("div");
+      qText.className = "cp-question-q";
+      qText.textContent = q.question;
+      card.appendChild(qText);
+
+      if (q.answer) {
+        var recorded = document.createElement("div");
+        recorded.className = "cp-question-recorded";
+        recorded.textContent = q.answer;
+        var meta = document.createElement("div");
+        meta.className = "cp-question-recorded-meta";
+        meta.textContent = "answered " +
+          (q.answered_by ? "by " + q.answered_by + " " : "") +
+          (q.answered_at ? "at " + fmtTime(q.answered_at) : "");
+        recorded.appendChild(meta);
+        card.appendChild(recorded);
+      } else {
+        if (q.options && q.options.length) {
+          var optsRow = document.createElement("div");
+          optsRow.className = "cp-question-options";
+          q.options.forEach(function (opt) {
+            var b = document.createElement("button");
+            b.className = "cp-question-option";
+            b.textContent = opt;
+            b.addEventListener("click", function () { submitAnswer(plan.slug, q.id, opt); });
+            optsRow.appendChild(b);
+          });
+          card.appendChild(optsRow);
+        }
+        var form = document.createElement("form");
+        form.className = "cp-question-answer-form";
+        var input = document.createElement("input");
+        input.className = "cp-question-answer-input";
+        input.placeholder = "Type an answer…";
+        input.required = true;
+        var submit = document.createElement("button");
+        submit.type = "submit";
+        submit.className = "cp-question-answer-submit";
+        submit.textContent = "Answer";
+        form.appendChild(input);
+        form.appendChild(submit);
+        form.addEventListener("submit", function (e) {
+          e.preventDefault();
+          if (!input.value.trim()) return;
+          submitAnswer(plan.slug, q.id, input.value.trim());
+        });
+        card.appendChild(form);
+      }
+
+      els.questionsPanel.appendChild(card);
+    });
+  }
+
+  function submitAnswer(slug, questionId, answer) {
+    v2Post(slug, "answers", { question_id: questionId, answer: answer }).then(function () {
+      showToast("Answer recorded.");
+      // SSE will fan out the plan upsert and re-render naturally.
+    }).catch(function (err) {
+      showToast("record_answer failed: " + err.message);
+    });
   }
 
   function selectPlan(slug) {
@@ -714,6 +990,12 @@
       var url = window.location.pathname + "?plan=" + encodeURIComponent(slug);
       window.history.replaceState(null, "", url);
     }
+    // Tokens are stage+plan bound — switching plans should not retain
+    // tokens from elsewhere (they'd be rejected on the server anyway,
+    // but better not to surface a stale token to the operator).
+    Object.keys(stageTokenCache).forEach(function (k) {
+      if (k !== slug) delete stageTokenCache[k];
+    });
     renderRail();
     renderDetail();
   }

package/server.js

@@ -1118,6 +1118,101 @@ app.get("/api/claude-plans/:slug", function (req, res) {
   }
 });
 
+// --- v2 bidirectional pipeline write routes (Phase E) ---
+// All three call into @tenonhq/dovetail-claude-plans' storage layer so
+// the state machine, conflict rule, and token lifecycle are enforced in
+// exactly one place. Errors surface their typed `code` and `name` to the
+// client so the dashboard can branch on them.
+const claudePlansLib = require("@tenonhq/dovetail-claude-plans/dist/storage");
+
+function sendTypedError(res, err) {
+  // ZodError (input validation) is a 400. Storage's typed errors expose
+  // a `code` (e.g. ILLEGAL_TRANSITION, MISSING_AGENT). Anything else is
+  // a 500 with the message.
+  if (err && err.name === "ZodError") {
+    return res.status(400).json({ error: "validation_failed", details: err.issues });
+  }
+  if (err && typeof err.code === "string") {
+    var status = 409;
+    if (err.code === "MISSING_AGENT") status = 424;
+    if (err.code === "NO_TOKEN") status = 400;
+    if (err.code === "STALE_TOKEN") status = 410;
+    if (err.code === "SPAWN_ERROR") status = 500;
+    return res.status(status).json({
+      error: err.code,
+      name: err.name,
+      message: err.message
+    });
+  }
+  if (err && /plan not found/.test(err.message || "")) {
+    return res.status(404).json({ error: "plan_not_found", message: err.message });
+  }
+  return res.status(500).json({ error: "internal", message: (err && err.message) || String(err) });
+}
+
+// POST /api/claude-plans/:slug/answers — record an answer to a question.
+// Body: { question_id, answer, answered_by? }
+app.post("/api/claude-plans/:slug/answers", claudePlansLimiter, express.json(), function (req, res) {
+  try {
+    var slug = req.params.slug;
+    if (!isValidSlug(slug)) return res.status(400).json({ error: "invalid slug" });
+    var body = req.body || {};
+    var result = claudePlansLib.recordAnswer({
+      plan_slug: slug,
+      question_id: body.question_id,
+      answer: body.answer,
+      answered_by: body.answered_by || "dashboard"
+    });
+    res.json(result);
+  } catch (e) {
+    sendTypedError(res, e);
+  }
+});
+
+// POST /api/claude-plans/:slug/stage — move the plan to a new stage.
+// Body: { to: PipelineStage, by? }
+// Source is forced to 'dashboard' so the conflict-resolution rule
+// (docs/v2-design.md §4) treats dashboard moves as authoritative.
+app.post("/api/claude-plans/:slug/stage", claudePlansLimiter, express.json(), function (req, res) {
+  try {
+    var slug = req.params.slug;
+    if (!isValidSlug(slug)) return res.status(400).json({ error: "invalid slug" });
+    var body = req.body || {};
+    var result = claudePlansLib.setStage({
+      plan_slug: slug,
+      to: body.to,
+      by: body.by || "dashboard",
+      source: "dashboard"
+    });
+    res.json(result);
+  } catch (e) {
+    sendTypedError(res, e);
+  }
+});
+
+// POST /api/claude-plans/:slug/dispatch — dry-run or live dispatch.
+// Body: { target_stage, confirm?, token?, by? }
+// The dashboard's flow is: POST without confirm (dry-run) → show
+// resolved command in the UI → POST with confirm:true + token from
+// set_stage response → live spawn.
+app.post("/api/claude-plans/:slug/dispatch", claudePlansLimiter, express.json(), function (req, res) {
+  try {
+    var slug = req.params.slug;
+    if (!isValidSlug(slug)) return res.status(400).json({ error: "invalid slug" });
+    var body = req.body || {};
+    var result = claudePlansLib.dispatchStage({
+      plan_slug: slug,
+      target_stage: body.target_stage,
+      confirm: body.confirm === true,
+      token: body.token,
+      by: body.by || "dashboard"
+    });
+    res.json(result);
+  } catch (e) {
+    sendTypedError(res, e);
+  }
+});
+
 app.delete("/api/claude-plans/:slug", claudePlansLimiter, function (req, res) {
   try {
     var slug = req.params.slug;