karajan-code 2.19.0 → 2.19.2

package/packages/hu-board/src/routes/api.js

@@ -0,0 +1,1271 @@
+import { Router } from 'express';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn as spawnChild } from 'node:child_process';
+import {
+  getDashboardStats,
+  getProjects,
+  getStoriesByProject,
+  getStoryDetail,
+  getSessionsByProject,
+  getSessionDetail,
+  deleteProject,
+  deleteStory,
+  deleteSession,
+  getKjHome,
+  getHuBoardRunsDir,
+  getStoryRow,
+  listPlanIdsForProject,
+  updateStoryStatus,
+  setProjectIsTest,
+} from '../db.js';
+import { fullScan } from '../sync.js';
+import { setHuStatus, setHuFields, markPlanReady, runPlan, renameProject, revertHuFromSnapshot } from '../plan-mutations.js';
+import { getActiveRuns } from '../run-tracker.js';
+import { subscribe as subscribeEvents } from '../event-bus.js';
+import { runKjCommand, listSupportedCommands } from '../command-runner.js';
+import { runPreflight } from '../preflight.js';
+import { readConfig, writeConfigPatch } from '../config-yaml.js';
+import { BOOT_TIME, PKG_VERSION } from '../boot-info.js';
+import { addTombstone, getDb, isTombstoned as isTombstonedFn, removeTombstone, listTombstones } from '../db.js';
+import { publish as publishEvent } from '../event-bus.js';
+
+const router = Router();
+
+/**
+ * GET /api/version - Server version + boot timestamp.
+ * The client polls this every 30s; if `boot_time` differs from the first
+ * response, the server restarted and the client triggers a reload to pick
+ * up any new HTML/JS (KJC-TSK-0379).
+ */
+router.get('/version', (_req, res) => {
+  res.set('Cache-Control', 'no-store');
+  res.json({ version: PKG_VERSION, boot_time: BOOT_TIME });
+});
+
+/**
+ * GET /api/standby — KJC-TSK-0414 PR4. Lista sesiones hibernadas.
+ * Devuelve [{ sessionId, planId, huId, role, cooldownUntil, reason, ... }]
+ * El front renderiza un badge "💤 standby · resume en HH:MM:SS" por sesión.
+ */
+router.get('/standby', async (_req, res) => {
+  try {
+    const { listPendingStandby } = await import('../../../../src/brain/standby-store.js');
+    const sessions = listPendingStandby();
+    res.set('Cache-Control', 'no-store');
+    res.json({ sessions });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * Resolve the hu-stories dir where batch.json files live.
+ */
+function huStoriesDir() {
+  return path.join(getKjHome(), 'hu-stories');
+}
+
+/**
+ * Best-effort removal of the hu-stories/<id>/ directory.
+ */
+function removeBatchDir(batchId) {
+  try {
+    const dir = path.join(huStoriesDir(), batchId);
+    fs.rmSync(dir, { recursive: true, force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * GET /api/dashboard - Global dashboard statistics.
+ */
+router.get('/dashboard', (_req, res) => {
+  try {
+    const stats = getDashboardStats();
+    res.json(stats);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/projects - List all projects with story counts.
+ */
+router.get('/projects', (_req, res) => {
+  try {
+    const projects = getProjects();
+    res.json(projects);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/projects/:id - Project detail.
+ */
+router.get('/projects/:id', (req, res) => {
+  try {
+    const projects = getProjects();
+    const project = projects.find((p) => p.id === req.params.id);
+    if (!project) return res.status(404).json({ error: 'Project not found' });
+    res.json(project);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * PUT /api/projects/:id/name — PR-G: rename a project.
+ *
+ * Updates plan.name on every plan JSON belonging to the project AND
+ * the projects.name column directly so the UI reflects the new name
+ * on the next render. Body: { name: "Linux Assistant Orchestrator" }.
+ */
+router.put('/projects/:id/name', (req, res) => {
+  try {
+    const result = renameProject({ projectId: req.params.id, name: req.body?.name });
+    if (!result.ok) {
+      const code = /no encontrado/i.test(result.error) ? 404 : 400;
+      return res.status(code).json({ error: result.error });
+    }
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * PATCH /api/projects/:id/is-test — KJC-TSK-0371 (board polish #3).
+ *
+ * Sets/clears the per-project ephemeral-cleanup override. The
+ * heuristic (id under tmp_/test_/demo_/kj-test- AND last_activity
+ * older than 24h → auto-delete on next board start) is the default.
+ * `is_test` lets the user override per-project:
+ *   - body { is_test: 1 }    → always treat as ephemeral
+ *   - body { is_test: 0 }    → NEVER auto-clean (keep this one)
+ *   - body { is_test: null } → revert to the default heuristic
+ *
+ * Sending anything else is a 400 — explicit ternary, no truthy/
+ * falsy coercion, because that exact distinction is what the
+ * cleaner relies on.
+ */
+router.patch('/projects/:id/is-test', (req, res) => {
+  const raw = req.body?.is_test;
+  // Accept the three legal sentinel values explicitly — undefined
+  // (key missing) is rejected because this endpoint only exists to
+  // set or clear, not to "leave as-is".
+  const allowed = raw === 0 || raw === 1 || raw === null;
+  if (!allowed) {
+    return res.status(400).json({ error: 'is_test must be 0, 1, or null' });
+  }
+  try {
+    const ok = setProjectIsTest(req.params.id, raw);
+    if (!ok) return res.status(404).json({ error: 'project not found' });
+    res.json({ ok: true, project_id: req.params.id, is_test: raw });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/projects/:id/preflight — Project readiness checks.
+ *
+ * Returns the same shape regardless of the project's state. Each
+ * check carries a status (ok|warn|fail|info), a plain-Spanish
+ * detail and (when relevant) a `consequence` describing what the
+ * user loses if it stays unfixed. Powers both:
+ *   - the panel at the top of the board (always visible)
+ *   - the safety modal that appears before ▶ Run plan / ▶ Run HU
+ *     when there are blockers or warnings
+ *
+ * The route resolves projectDir by reading the first plan it can
+ * find for this project (plans carry projectDir since v2.7.4). If
+ * the project has no plans on disk we still return the env-only
+ * checks (Node, Karajan, agents, config) so the user gets feedback
+ * even before they generate their first plan.
+ */
+router.get('/projects/:id/preflight', async (req, res) => {
+  try {
+    const projectId = req.params.id;
+    let projectDir = null;
+    try {
+      // Plans live at ~/.kj/plans/<slug>/ when KJ_HOME is unset, or
+      // $KJ_HOME/plans/<slug>/ when set. db.js::getKjHome() returns
+      // the .karajan root, NOT the .kj root — they are sister dirs.
+      // Mirror plan-mutations.js::plansRoot() exactly.
+      const plansBase = process.env.KJ_HOME
+        ? path.join(process.env.KJ_HOME, 'plans')
+        : path.join(process.env.HOME || '', '.kj', 'plans');
+      const plansDir = path.join(plansBase, projectId);
+      if (fs.existsSync(plansDir)) {
+        const files = fs.readdirSync(plansDir).filter((f) => f.endsWith('.json'));
+        for (const f of files) {
+          try {
+            const plan = JSON.parse(fs.readFileSync(path.join(plansDir, f), 'utf8'));
+            if (plan?.projectDir) { projectDir = plan.projectDir; break; }
+          } catch { /* try next */ }
+        }
+      }
+    } catch { /* projectDir stays null → preflight will report it */ }
+    const result = await runPreflight({ projectId, projectDir });
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/projects/:id/plans-outcome — Plan-level rollups (PR3).
+ *
+ * Reads every plan JSON for the project and returns the lightweight
+ * shape the board needs to render the "Plan finalizado · 8 done · 2
+ * failed · 15 min" banner. Plans that haven't finished yet have a
+ * null outcome — the front handles that by hiding the banner.
+ */
+router.get('/projects/:id/plans-outcome', (req, res) => {
+  try {
+    const projectId = req.params.id;
+    const plansBase = process.env.KJ_HOME
+      ? path.join(process.env.KJ_HOME, 'plans')
+      : path.join(process.env.HOME || '', '.kj', 'plans');
+    const plansDir = path.join(plansBase, projectId);
+    if (!fs.existsSync(plansDir)) return res.json({ projectId, plans: [] });
+    const out = [];
+    for (const f of fs.readdirSync(plansDir).filter(n => n.endsWith('.json'))) {
+      try {
+        const plan = JSON.parse(fs.readFileSync(path.join(plansDir, f), 'utf8'));
+        if (plan?.version !== 2) continue;
+        out.push({
+          planId: plan.planId,
+          name: plan.name || (plan.task ? plan.task.slice(0, 80) : plan.planId),
+          status: plan.status || 'draft',
+          updatedAt: plan.updatedAt || null,
+          outcome: plan.outcome || null,
+          huCount: Array.isArray(plan.hus) ? plan.hus.length : 0,
+        });
+      } catch { /* skip unreadable plan */ }
+    }
+    res.json({ projectId, plans: out });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/projects/:id/stories - Stories for a project.
+ */
+router.get('/projects/:id/stories', (req, res) => {
+  try {
+    const stories = getStoriesByProject(req.params.id);
+    res.json(stories);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/stories/:id - Story detail with quality scores and context requests.
+ */
+router.get('/stories/:id', (req, res) => {
+  try {
+    const story = getStoryDetail(req.params.id);
+    if (!story) return res.status(404).json({ error: 'Story not found' });
+    res.json(story);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/projects/:id/sessions - Sessions for a project.
+ */
+router.get('/projects/:id/sessions', (req, res) => {
+  try {
+    const sessions = getSessionsByProject(req.params.id);
+    res.json(sessions);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/sessions/:id - Session detail with stages, commits, duration.
+ */
+router.get('/sessions/:id', (req, res) => {
+  try {
+    const session = getSessionDetail(req.params.id);
+    if (!session) return res.status(404).json({ error: 'Session not found' });
+    // Parse JSON fields for the response
+    const parsed = { ...session };
+    for (const field of ['checkpoints', 'llm_calls', 'config_snapshot', 'budget', 'commits', 'stages_completed']) {
+      if (parsed[field] && typeof parsed[field] === 'string') {
+        try { parsed[field] = JSON.parse(parsed[field]); } catch { /* keep as string */ }
+      }
+    }
+    res.json(parsed);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/sessions - All sessions across all projects.
+ */
+router.get('/sessions', (_req, res) => {
+  try {
+    const allProjects = getProjects();
+    const sessions = [];
+    for (const p of allProjects) {
+      sessions.push(...getSessionsByProject(p.id));
+    }
+    // Also get default project sessions
+    sessions.push(...getSessionsByProject('default'));
+    // Deduplicate
+    const seen = new Set();
+    const unique = sessions.filter((s) => {
+      if (seen.has(s.id)) return false;
+      seen.add(s.id);
+      return true;
+    });
+    unique.sort((a, b) => (b.created_at || '').localeCompare(a.created_at || ''));
+    res.json(unique);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * DELETE /api/projects/:id - Cascade delete project + its stories + sessions.
+ * Also removes the hu-stories/<id>/ directory from disk so the next sync
+ * does not re-import it.
+ */
+router.delete('/projects/:id', (req, res) => {
+  try {
+    const id = req.params.id;
+    // Gather filesystem paths to remove BEFORE deleting DB rows so we
+    // can stop the next sync from resurrecting anything.
+    const db = getDb();
+    const storyIds = db.prepare('SELECT id FROM stories WHERE project_id = ?').all(id).map((r) => r.id);
+    const sessionIds = db.prepare('SELECT id FROM sessions WHERE project_id = ?').all(id).map((r) => r.id);
+    // KJC-BUG-0055: honour KJ_PLANS_DIR (the env override the sync /
+    // cleanup-zombies layers already respect). Previously hardcoded to
+    // ~/.kj/plans relative to KJ_HOME's parent, which broke when the
+    // two homes were configured separately and left orphan plan dirs
+    // on disk after a 🗑️ delete.
+    const plansRoot = process.env.KJ_PLANS_DIR
+      || path.join(os.homedir(), '.kj', 'plans');
+    const fsPaths = [
+      ...storyIds.map((sid) => path.join(huStoriesDir(), sid)),
+      ...sessionIds.map((sid) => path.join(getKjHome(), 'sessions', sid)),
+      path.join(plansRoot, id),
+    ];
+
+    const existed = deleteProject(id);
+    if (!existed) return res.status(404).json({ error: 'Project not found' });
+
+    // Tombstone the project AND its children so chokidar / fullScan
+    // can't bring them back via syncStoryFile / syncSessionFile.
+    addTombstone('project', id, { source: 'api', fsPaths });
+    for (const sid of storyIds) addTombstone('story', sid, { source: 'api' });
+    for (const sid of sessionIds) addTombstone('session', sid, { source: 'api' });
+
+    // Best-effort fs cleanup; failure does NOT undo the tombstones.
+    let pathsRemoved = 0;
+    for (const p of fsPaths) {
+      try { fs.rmSync(p, { recursive: true, force: true }); pathsRemoved++; } catch { /* */ }
+    }
+    res.json({ deleted: true, pathsRemoved, tombstoned: 1 + storyIds.length + sessionIds.length });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * DELETE /api/prompts/:promptId - Discard a pending prompt the runner left
+ * behind (KJC-TSK-0380). Removes the RPC files from disk, tombstones the
+ * prompt id so a stale chokidar event can't recreate it, and emits a
+ * `prompt:resolved` event so all open boards close the modal.
+ */
+router.delete('/prompts/:promptId', (req, res) => {
+  try {
+    const promptId = req.params.promptId;
+    const dir = promptsDir();
+    const main = path.join(dir, `${promptId}.json`);
+    const answer = path.join(dir, `${promptId}.answer.json`);
+    let removed = 0;
+    for (const p of [main, answer]) {
+      try { fs.unlinkSync(p); removed++; } catch { /* missing is fine */ }
+    }
+    addTombstone('prompt', promptId, { source: 'api', fsPaths: [main, answer] });
+    // Re-use the same event the runner emits when answered, so any open
+    // modal in any connected board client closes itself.
+    publishEvent({ type: 'prompt-resolved', promptId });
+    res.json({ deleted: true, filesRemoved: removed });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * DELETE /api/stories/:id - Delete a single story.
+ *
+ * Tombstones the story (KJC-TSK-0380) and removes its batch directory
+ * from `~/.karajan/hu-stories/<id>/` so the next sync does NOT re-import
+ * it. Pre-tombstones this endpoint was a DB-only soft hide that the next
+ * chokidar event undid silently.
+ */
+router.delete('/stories/:id', (req, res) => {
+  try {
+    const id = req.params.id;
+    const dir = path.join(huStoriesDir(), id);
+    const ok = deleteStory(id);
+    if (!ok) return res.status(404).json({ error: 'Story not found' });
+    addTombstone('story', id, { source: 'api', fsPaths: [dir] });
+    let dirRemoved = false;
+    try { fs.rmSync(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
+    res.json({ deleted: true, dirRemoved });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * DELETE /api/sessions/:id - Delete a single session.
+ *
+ * Tombstones + removes `~/.karajan/sessions/<id>/` (KJC-TSK-0380).
+ */
+router.delete('/sessions/:id', (req, res) => {
+  try {
+    const id = req.params.id;
+    const dir = path.join(getKjHome(), 'sessions', id);
+    const ok = deleteSession(id);
+    if (!ok) return res.status(404).json({ error: 'Session not found' });
+    addTombstone('session', id, { source: 'api', fsPaths: [dir] });
+    let dirRemoved = false;
+    try { fs.rmSync(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
+    res.json({ deleted: true, dirRemoved });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * DELETE /api/plans/:planId - Delete a single plan file.
+ *
+ * Removes `~/.kj/plans/<projectSlug>/plan-<planId>.json` and tombstones
+ * the plan id so the next watcher event doesn't re-sync it. Does NOT
+ * delete the project: a project can have multiple plans, deleting one
+ * plan only removes that plan's HUs from the board.
+ */
+router.delete('/plans/:planId', (req, res) => {
+  try {
+    const planId = req.params.planId;
+    // Locate the plan file by scanning the plans dir for filename match.
+    const plansRoot = process.env.KJ_PLANS_DIR || path.join(getKjHome(), '..', '.kj', 'plans');
+    let foundPath = null;
+    try {
+      for (const projSlug of fs.readdirSync(plansRoot)) {
+        const candidate = path.join(plansRoot, projSlug, `plan-${planId}.json`);
+        if (fs.existsSync(candidate)) { foundPath = candidate; break; }
+      }
+    } catch { /* plansRoot missing */ }
+    addTombstone('plan', planId, { source: 'api', fsPaths: foundPath ? [foundPath] : [] });
+    if (foundPath) { try { fs.unlinkSync(foundPath); } catch { /* */ } }
+    res.json({ deleted: true, fileRemoved: !!foundPath });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/tombstones - List every active tombstone for diagnostics.
+ *
+ * Returns rows ordered by deleted_at DESC; useful for the diagnostics
+ * pane and for the cleanup script (KJC-TSK-0380 PR-C).
+ */
+router.get('/tombstones', (_req, res) => {
+  try {
+    res.json(listTombstones());
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/tombstones/:type/:id/restore - Bring a buried id back to
+ * life. The next sync will then re-import the resource if its filesystem
+ * source still exists. Idempotent: returns false when nothing to remove.
+ */
+router.post('/tombstones/:type/:id/restore', (req, res) => {
+  try {
+    const removed = removeTombstone(req.params.type, req.params.id);
+    if (!removed) return res.status(404).json({ error: 'Tombstone not found' });
+    res.json({ restored: true });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * PATCH /api/stories/:id - Edit a single HU.
+ *
+ * Accepts two shapes in the same call (both optional, either or both
+ * can be present):
+ *
+ *   { status: "pending" | "certified" | "done" | "needs_context" }
+ *     → changes the lifecycle state (original PATCH semantics).
+ *
+ *   { title?, scope?, task_type?, acceptance_criteria?,
+ *     acceptance_tests?, blocked_by? }
+ *     → edits the user-facing fields in place. Whitelist mirrors
+ *     plan-hu-ops::updateHu so CLI and board stay aligned.
+ *
+ * When both are present we apply status last — the status change
+ * transitions the plan lifecycle and can rewrite plan.status, whereas
+ * field edits are local to the HU and should never fight the status
+ * auto-promotion.
+ *
+ * The row id on the board is `${projectId}::${huId}` — split here to
+ * feed the plan-mutation helpers. The source-of-truth plan JSON is
+ * rewritten before we ack, then re-synced into SQLite, so a reload
+ * renders the committed state.
+ */
+// Status que el USUARIO puede setear manualmente vía el dropdown del
+// modal. NO incluimos coding/reviewing/running — esos son lifecycle
+// del orquestador (settearlos a mano genera zombies). Tampoco
+// incluimos los canonicales (`running`) por la misma razón. `failed`
+// y `blocked` son útiles para que el usuario marque manualmente HUs
+// que no quiere correr ahora.
+// KJC-TSK-0403: 'failed' eliminado — el orquestador estampa result=fail
+// dejando status=pending. Setearlo a mano vía PATCH ya no tiene sentido.
+const ALLOWED_STORY_STATUSES = new Set(['pending', 'certified', 'done', 'blocked', 'needs_context']);
+// KJC-TSK-0406: coder_model y reviewer_model son editables desde el
+// modal del board. Independientes — el usuario puede subir el reviewer
+// y bajar el coder sin afectar al resto del plan.
+const EDITABLE_HU_FIELDS = ['title', 'scope', 'task_type', 'acceptance_criteria', 'acceptance_tests', 'blocked_by', 'coder_model', 'reviewer_model', 'coder_provider', 'reviewer_provider'];
+
+router.patch('/stories/:id', (req, res) => {
+  try {
+    const body = req.body || {};
+    const hasStatus = Object.prototype.hasOwnProperty.call(body, 'status');
+    const fieldPatch = {};
+    for (const k of EDITABLE_HU_FIELDS) {
+      if (Object.prototype.hasOwnProperty.call(body, k)) fieldPatch[k] = body[k];
+    }
+    const hasFieldEdit = Object.keys(fieldPatch).length > 0;
+
+    if (!hasStatus && !hasFieldEdit) {
+      return res.status(400).json({
+        error: `Body must include status or one of: ${EDITABLE_HU_FIELDS.join(', ')}`,
+      });
+    }
+    if (hasStatus && !ALLOWED_STORY_STATUSES.has(body.status)) {
+      return res.status(400).json({
+        error: `status must be one of: ${[...ALLOWED_STORY_STATUSES].join(', ')}`,
+      });
+    }
+
+    const row = getStoryRow(req.params.id);
+    if (!row) return res.status(404).json({ error: 'Story not found' });
+    if (!row.plan_id) {
+      return res.status(409).json({
+        error: 'Story is not backed by a plan file (legacy row). Re-run `kj plan` to re-import it.',
+      });
+    }
+    const huId = req.params.id.includes('::')
+      ? req.params.id.split('::').slice(1).join('::')
+      : req.params.id;
+
+    let updatedHu;
+    if (hasFieldEdit) {
+      const fieldResult = setHuFields({
+        planId: row.plan_id,
+        huId,
+        patch: fieldPatch,
+        projectId: row.project_id,
+      });
+      if (!fieldResult.ok) {
+        // KJC-TSK-0401: validación de blocked_by devuelve 400 con cycle?
+        // info para que el board destaque la cadena en la UI. Resto de
+        // fallos siguen devolviendo 404 (plan / hu no encontrados).
+        if (fieldResult.code === 'INVALID_BLOCKED_BY') {
+          return res.status(400).json({ error: fieldResult.error, cycle: fieldResult.cycle });
+        }
+        return res.status(404).json({ error: fieldResult.error });
+      }
+      updatedHu = fieldResult.hu;
+    }
+
+    let statusResult;
+    if (hasStatus) {
+      statusResult = setHuStatus({
+        planId: row.plan_id,
+        huId,
+        status: body.status,
+        projectId: row.project_id,
+      });
+      if (!statusResult.ok) return res.status(404).json({ error: statusResult.error });
+    }
+
+    res.json({
+      updated: true,
+      id: req.params.id,
+      status: statusResult ? statusResult.status : undefined,
+      planStatus: statusResult ? statusResult.planStatus : undefined,
+      hu: updatedHu,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/stories/:id/undo — KJC-TSK-0408: revert a HU.
+ *
+ * Restaura los ficheros del workspace al snapshot pre-run guardado por
+ * la pipeline. Marca status=pending + result=null + outcome.reverted=true
+ * para que el usuario pueda relanzar la HU con otros modelos.
+ *
+ * Falla con 400 si la HU no tiene snapshot (HUs anteriores al hook).
+ * Falla con 404 si plan/HU no existe.
+ */
+router.post('/stories/:id/undo', async (req, res) => {
+  try {
+    const row = getStoryRow(req.params.id);
+    if (!row) return res.status(404).json({ error: 'Story not found' });
+    if (!row.plan_id) {
+      return res.status(409).json({ error: 'Story sin plan_id — legacy row no soportada.' });
+    }
+    const huId = req.params.id.includes('::')
+      ? req.params.id.split('::').slice(1).join('::')
+      : req.params.id;
+    const result = await revertHuFromSnapshot({ planId: row.plan_id, huId, projectId: row.project_id });
+    if (!result.ok) {
+      const code = /not found|no encontrado/i.test(result.error) ? 404 : 400;
+      return res.status(code).json({ error: result.error });
+    }
+    res.json({ ok: true, id: req.params.id, sha: result.sha });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/plans/:planId/ready - Bulk-certify every pending HU of a plan.
+ * Equivalent to the CLI `kj plan ready <planId>`. Body is optional — if the
+ * client knows the projectId we use it as a fast path, otherwise we fall
+ * back to scanning the plans dir.
+ */
+router.post('/plans/:planId/ready', (req, res) => {
+  try {
+    const { projectId } = req.body || {};
+    const result = markPlanReady({ planId: req.params.planId, projectId });
+    if (!result.ok) return res.status(404).json({ error: result.error });
+    res.json({ ready: true, planId: req.params.planId, count: result.count, planStatus: result.planStatus });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/projects/:id/ready - Sugar: mark every plan of a project ready
+ * in one call. Lets the board expose a single "Mark all certified" button
+ * per project view without the UI having to enumerate plan ids first.
+ */
+router.post('/projects/:id/ready', (req, res) => {
+  try {
+    const planIds = listPlanIdsForProject(req.params.id);
+    if (planIds.length === 0) {
+      return res.status(404).json({ error: 'No plan-backed stories for this project' });
+    }
+    const results = [];
+    for (const planId of planIds) {
+      const r = markPlanReady({ planId, projectId: req.params.id });
+      results.push({ planId, ...r });
+    }
+    const totalCertified = results
+      .filter((r) => r.ok)
+      .reduce((acc, r) => acc + r.count, 0);
+    res.json({
+      ready: true,
+      projectId: req.params.id,
+      plans: results,
+      totalCertified,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * Resolve the prompts directory the runner writes RPC packets to.
+ * Same convention as src/utils/board-prompt-bridge.js on the runner.
+ */
+function promptsDir() {
+  return path.join(getKjHome(), 'prompts');
+}
+
+/**
+ * GET /api/prompts - List currently pending prompts. The runner is
+ * blocked on each one waiting for an answer; the board reads this on
+ * boot to surface modals for prompts that were already pending when
+ * the page loaded (the SSE event fires only on new arrivals).
+ */
+// KJC-BUG-0038: prompts whose runner crashed leave the .json behind in
+// ~/.kj/prompts/. Without a TTL, every board reload re-shows the zombie
+// modal "Karajan needs an answer" with no runner behind it — the user
+// can answer but nothing happens. 30 minutes covers the longest legitimate
+// Solomon escalation; anything older is a crashed runner.
+const PROMPT_ZOMBIE_TTL_MS = 30 * 60 * 1000;
+
+router.get('/prompts', (_req, res) => {
+  try {
+    const dir = promptsDir();
+    if (!fs.existsSync(dir)) return res.json([]);
+    const entries = fs.readdirSync(dir);
+    const result = [];
+    const now = Date.now();
+    for (const name of entries) {
+      if (!name.endsWith('.json') || name.endsWith('.answer.json')) continue;
+      const promptId = name.replace(/\.json$/, '');
+      const mainPath = path.join(dir, name);
+      const answerPath = path.join(dir, `${promptId}.answer.json`);
+      // KJC-TSK-0380 — skip tombstoned prompts and clean their files.
+      if (isTombstonedFn('prompt', promptId)) {
+        try { fs.unlinkSync(mainPath); } catch { /* */ }
+        try { fs.unlinkSync(answerPath); } catch { /* */ }
+        continue;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(fs.readFileSync(mainPath, 'utf-8'));
+      } catch { continue; /* malformed — skip */ }
+      // KJC-BUG-0038: zombie detection. Prefer parsed.createdAt; fall back
+      // to mtime if the runner skipped the timestamp (older formats).
+      const createdMs = Date.parse(parsed?.createdAt || '');
+      const ageRef = Number.isFinite(createdMs) ? createdMs : safeMtime(mainPath);
+      if (ageRef && (now - ageRef) > PROMPT_ZOMBIE_TTL_MS) {
+        try { fs.unlinkSync(mainPath); } catch { /* */ }
+        try { fs.unlinkSync(answerPath); } catch { /* */ }
+        addTombstone('prompt', promptId, { source: 'zombie-ttl', fsPaths: [mainPath, answerPath] });
+        continue;
+      }
+      result.push(parsed);
+    }
+    result.sort((a, b) => (a.createdAt || '').localeCompare(b.createdAt || ''));
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+function safeMtime(p) {
+  try { return fs.statSync(p).mtimeMs; } catch { return 0; }
+}
+
+/**
+ * POST /api/prompts/:promptId/answer - Body { answer }. Writes a
+ * sibling .answer.json the runner is polling for. The runner reads
+ * it, deletes both files, and resolves askQuestion. An answer of
+ * "stop" tells the runner to abort the session.
+ */
+router.post('/prompts/:promptId/answer', (req, res) => {
+  try {
+    const { answer } = req.body || {};
+    if (typeof answer !== 'string') {
+      return res.status(400).json({ error: 'Body must contain an "answer" string' });
+    }
+    const dir = promptsDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const promptPath = path.join(dir, `${req.params.promptId}.json`);
+    if (!fs.existsSync(promptPath)) {
+      return res.status(404).json({ error: `Prompt not found: ${req.params.promptId}` });
+    }
+    const answerPath = path.join(dir, `${req.params.promptId}.answer.json`);
+    fs.writeFileSync(
+      answerPath,
+      JSON.stringify({ answer, answeredAt: new Date().toISOString() }, null, 2),
+      'utf-8'
+    );
+    res.json({ ok: true });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/events - Server-Sent Events stream for live board updates.
+ *
+ * Replaces the old "sync → full page re-render" dance. The chokidar
+ * watcher publishes a small event on every sync (plan/session/batch);
+ * this endpoint pipes those events to every connected client. The
+ * client patches the affected card in place, so scroll position and
+ * any open modal survive the update.
+ *
+ * The connection stays open for the life of the tab. Browsers
+ * auto-reconnect on socket drop — we send a keep-alive comment every
+ * 25s so intermediate proxies don't kill the idle socket.
+ */
+router.get('/events', (req, res) => {
+  res.writeHead(200, {
+    'Content-Type': 'text/event-stream',
+    'Cache-Control': 'no-cache, no-transform',
+    Connection: 'keep-alive',
+    // Disable Express compression on this route — SSE must be a raw
+    // stream, gzip buffers and breaks the "push on every event" model.
+    'X-Accel-Buffering': 'no',
+  });
+  res.flushHeaders?.();
+  // Initial hello so the client knows the stream is open. Useful for
+  // the integration test too: the EventSource-equivalent supertest
+  // client can wait on the first line.
+  res.write('retry: 2000\n');
+  res.write('event: hello\ndata: {"ok":true}\n\n');
+
+  const send = (event) => {
+    try {
+      res.write(`data: ${JSON.stringify(event)}\n\n`);
+    } catch {
+      // Client gone — the close handler will clean up shortly.
+    }
+  };
+  const unsubscribe = subscribeEvents(send);
+
+  // 25s is well under the default 60-90s idle timeout of every sane
+  // reverse proxy, but high enough that it doesn't spam the log.
+  const keepAlive = setInterval(() => {
+    try { res.write(': keep-alive\n\n'); } catch { /* ignore */ }
+  }, 25000);
+
+  req.on('close', () => {
+    clearInterval(keepAlive);
+    unsubscribe();
+    res.end?.();
+  });
+});
+
+/**
+ * GET /api/plans/:planId/log - Tail the detached run's log file.
+ *
+ * Accepts ?offset=N so a polling UI can request only the new bytes
+ * since last read (the "tail -f" UX without SSE). Returns:
+ *
+ *   { content: string, size: number, exists: boolean }
+ *
+ * - `exists` is false when the run hasn't started yet (the log path is
+ *   deterministic, so we know where to look).
+ * - `size` is the current file length; clients pass `offset=size` next
+ *   time to get only the delta.
+ *
+ * Path is the same one that `runPlan` wrote to:
+ *   ~/.karajan/hu-board-runs/<planId>.log (honours KJ_HOME in tests).
+ */
+router.get('/plans/:planId/log', (req, res) => {
+  try {
+    const runsDir = getHuBoardRunsDir(); // KJC-TSK-0421
+    const logPath = path.join(runsDir, `${req.params.planId}.log`);
+    if (!fs.existsSync(logPath)) {
+      return res.json({ exists: false, size: 0, content: '' });
+    }
+    const stat = fs.statSync(logPath);
+    const offset = Math.max(0, Math.min(stat.size, Number(req.query.offset) || 0));
+    // Cap per-request read to 1 MiB so a huge log can't blow up the
+    // response. The client will keep polling and catch up.
+    const MAX_READ = 1024 * 1024;
+    const length = Math.min(MAX_READ, stat.size - offset);
+    let content = '';
+    if (length > 0) {
+      const fd = fs.openSync(logPath, 'r');
+      try {
+        const buf = Buffer.alloc(length);
+        fs.readSync(fd, buf, 0, length, offset);
+        content = buf.toString('utf-8');
+      } finally {
+        fs.closeSync(fd);
+      }
+    }
+    res.json({ exists: true, size: stat.size, content });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/plans/:planId/run - Launch `kj run --plan <planId>` as a
+ * detached child. This is the "Run plan" button's endpoint — the board
+ * no longer requires the user to drop to a terminal to kick off the
+ * pipeline.
+ *
+ * Body: { projectId?: string, task?: string } — both optional. projectId
+ * makes the plan-file lookup O(1); task overrides plan.task as the
+ * pipeline's headline description.
+ *
+ * Returns the child's pid + the log path so a future "tail this run"
+ * viewer can attach.
+ */
+router.post('/plans/:planId/run', (req, res) => {
+  try {
+    const { projectId, task, huIds } = req.body || {};
+    // PR4: callers may pass `huIds: ["hu_x_001"]` to scope the run
+    // to a single HU (or comma-separated subset). When omitted, the
+    // whole plan runs as before.
+    const result = runPlan({
+      planId: req.params.planId,
+      projectId,
+      taskOverride: task,
+      huIds: Array.isArray(huIds) ? huIds : null,
+    });
+    if (!result.ok) {
+      // 404 for "plan not found" (preserves the contract the existing
+      // test asserts on), 400 for validation errors (unknown HU id,
+      // missing projectDir, etc.).
+      const code = /^plan not found/.test(result.error) ? 404 : 400;
+      return res.status(code).json({ error: result.error });
+    }
+    res.json({
+      launched: true,
+      planId: req.params.planId,
+      pid: result.pid,
+      logPath: result.logPath,
+      huIds: Array.isArray(huIds) && huIds.length > 0 ? huIds : null,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/hus/:huId/run — PR4: launch a single HU (or, when the
+ * caller passes additional ids in body.extraHuIds, a small bundle).
+ *
+ * The HU's plan is resolved from the SQLite stories table so the
+ * front doesn't have to know the planId — it only needs the story
+ * id from the card.
+ */
+router.post('/hus/:huId/run', (req, res) => {
+  try {
+    const huId = req.params.huId;
+    const row = getStoryRow(huId);
+    if (!row) return res.status(404).json({ error: `unknown HU: ${huId}` });
+    if (!row.plan_id) return res.status(400).json({ error: `HU ${huId} is not backed by a plan (legacy row)` });
+
+    // Story id on disk uses just the HU local id (hu_<plan>_NNN),
+    // not the "<projectId>::<huId>" composite the board persists.
+    // Strip the prefix back off before forwarding to runPlan.
+    const planLocalHuId = huId.includes('::') ? huId.split('::').pop() : huId;
+    const extraIds = Array.isArray(req.body?.extraHuIds) ? req.body.extraHuIds.map((x) => (x.includes('::') ? x.split('::').pop() : x)) : [];
+    const huIds = [planLocalHuId, ...extraIds];
+
+    const result = runPlan({ planId: row.plan_id, projectId: row.project_id, huIds });
+    if (!result.ok) return res.status(400).json({ error: result.error });
+
+    // Move the launched HU(s) to "coding" in BOTH the SQLite mirror and the
+    // source-of-truth plan JSON. The plan JSON write is what makes it stick
+    // — the next /api/sync re-reads the plan file and would otherwise
+    // overwrite the SQLite update back to "certified". Without this the
+    // card flashes to Running for ~1s and snaps back, which the user reads
+    // as "nothing happened".
+    //
+    // The orchestrator owns the lifecycle once it boots (it'll move the HU
+    // through coding → reviewing → done/failed and persist back to the plan
+    // JSON), so this is just the bootstrap nudge to give the user immediate
+    // visual feedback.
+    const allHuIds = [planLocalHuId, ...extraIds];
+    for (const localId of allHuIds) {
+      try { setHuStatus({ planId: row.plan_id, huId: localId, status: 'coding', projectId: row.project_id }); } catch { /* non-fatal */ }
+      // Also stamp the SQLite row so the next renderBoard() (before any
+      // sync tick) shows it in Running.
+      const compositeId = localId.includes('::') ? localId : `${row.project_id}::${localId}`;
+      try { updateStoryStatus(compositeId, 'coding'); } catch { /* non-fatal */ }
+    }
+
+    res.json({
+      launched: true,
+      planId: row.plan_id,
+      huIds,
+      pid: result.pid,
+      logPath: result.logPath,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/projects/:id/run - Sugar: launch every plan of a project. For
+ * the common case where each project has exactly one active plan this
+ * behaves the same as POST /plans/:planId/run; with multiple plans it
+ * kicks each one in its own detached child.
+ */
+router.post('/projects/:id/run', (req, res) => {
+  try {
+    const planIds = listPlanIdsForProject(req.params.id);
+    if (planIds.length === 0) {
+      return res.status(404).json({ error: 'No plan-backed stories for this project' });
+    }
+    const results = [];
+    for (const planId of planIds) {
+      const r = runPlan({ planId, projectId: req.params.id });
+      results.push({ planId, ...r });
+    }
+    const launched = results.filter((r) => r.ok).length;
+    res.json({ launched, total: planIds.length, results });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/config — read the editable subset of ~/.karajan/kj.config.yml.
+ * Powers the board's settings modal; non-editable keys in the yml are
+ * left untouched on PUT (see writeConfigPatch's whitelist semantics).
+ */
+router.get('/config', (_req, res) => {
+  try {
+    const data = readConfig();
+    res.json(data);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * PUT /api/config — apply a patch to the yml. Body is `{ patch: { key: value } }`
+ * with the keys defined in EDITABLE_FIELDS. Unknown keys are 400'd; type
+ * errors are 400'd; validation errors are 400'd. Writes are atomic
+ * (tmp + rename) and a `.bak` is kept of the previous content.
+ */
+router.put('/config', (req, res) => {
+  try {
+    const patch = req.body?.patch;
+    const result = writeConfigPatch(patch);
+    if (!result.written) {
+      return res.status(400).json({ error: 'No se pudo guardar la configuración', details: result });
+    }
+    res.json(result);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/commands - List the kj commands the board can launch.
+ * The UI uses this to render the Actions panel without hardcoding
+ * the command list on the client.
+ */
+router.get('/commands', (_req, res) => {
+  res.json({ commands: listSupportedCommands() });
+});
+
+/**
+ * POST /api/commands/:command - Spawn a kj <command> as a detached
+ * child. Body fields depend on the command (see command-runner.js
+ * for the per-command input schema). Returns a commandId the client
+ * can pass to GET /api/runs/:commandId/log to tail the output.
+ *
+ * The board never executes free-form arg arrays — the command name
+ * must be in the whitelist and each command builds its argv from a
+ * typed schema. Anything outside that fails 400.
+ */
+router.post('/commands/:command', (req, res) => {
+  try {
+    const result = runKjCommand({ command: req.params.command, input: req.body || {} });
+    if (!result.ok) return res.status(400).json({ error: result.error });
+    res.json({
+      ok: true,
+      commandId: result.commandId,
+      pid: result.pid,
+      logPath: result.logPath,
+    });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/runs/:commandId/log - Generalisation of the per-plan log
+ * tail. The original `/api/plans/:planId/log` reads
+ * `<runsDir>/<planId>.log`; this one reads `<runsDir>/<commandId>.log`
+ * where `commandId` is what `/api/commands/:command` returned.
+ *
+ * Same offset semantics + 1 MiB cap as the plans endpoint.
+ */
+/**
+ * GET /api/runs/:planId/active - Devuelve los runs activos (PIDs vivos)
+ * de un plan. Usado por el frontend para decidir si mostrar el botón
+ * ⏹ Stop. Respuesta: { active: [{pid, huIds, startedAt}, ...] }.
+ *
+ * KJC-TSK-0396.
+ */
+router.get('/runs/:planId/active', (req, res) => {
+  try {
+    const active = getActiveRuns(req.params.planId);
+    res.json({ active });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/runs/:planId/stop - Mata todos los procesos del orquestador
+ * asociados a este plan. SIGTERM primero, espera 5s, escala a SIGKILL
+ * si el proceso no respondió. Devuelve { stopped, killed, errors }.
+ *
+ * Tras matar el proceso, las HUs que estaban en coding/reviewing se
+ * resetean a pending (no a failed) vía hu-zombie-reaper logic — pero
+ * eso lo hace el reaper en el siguiente arranque del board. Para
+ * efecto inmediato, marcamos aquí las HUs running del plan a pending.
+ *
+ * KJC-TSK-0396.
+ */
+router.post('/runs/:planId/stop', async (req, res) => {
+  const { planId } = req.params;
+  const stopTimeoutMs = Number(req.body?.timeoutMs ?? 5000);
+  try {
+    const errors = [];
+    let stopped = 0;
+    let killed = 0;
+    const active = getActiveRuns(planId);
+    // Fase 1: SIGTERM a todos los procesos trackeados (si los hay).
+    for (const run of active) {
+      try { process.kill(run.pid, 'SIGTERM'); stopped += 1; }
+      catch (err) { errors.push({ pid: run.pid, phase: 'SIGTERM', error: err.message }); }
+    }
+    // Fase 2: esperar `stopTimeoutMs` y escalar a SIGKILL los que sigan
+    // vivos. Saltamos la espera si no había nada que matar.
+    if (active.length > 0) {
+      await new Promise((resolve) => setTimeout(resolve, stopTimeoutMs));
+      const stillAlive = getActiveRuns(planId);
+      for (const run of stillAlive) {
+        try { process.kill(run.pid, 'SIGKILL'); killed += 1; }
+        catch (err) { errors.push({ pid: run.pid, phase: 'SIGKILL', error: err.message }); }
+      }
+    }
+    // Fase 3: SIEMPRE reset de HUs en coding/reviewing del plan → pending.
+    // El reset corre aunque no hubiera PIDs trackeados (caso: el run lo
+    // lanzaste manualmente desde la terminal, killeaste tú mismo el
+    // proceso, pero la DB sigue mostrando HUs en coding y necesitas
+    // dejarlas en pending para relanzar limpio).
+    let hu_reset_count = 0;
+    try {
+      const db = getDb();
+      const result = db.prepare(
+        "UPDATE stories SET status = 'pending', updated_at = ? WHERE plan_id = ? AND status IN ('coding', 'reviewing', 'running')"
+      ).run(new Date().toISOString(), planId);
+      hu_reset_count = result.changes;
+    } catch (err) {
+      errors.push({ phase: 'hu_reset', error: err.message });
+    }
+    const out = { stopped, killed, errors, hu_reset_count };
+    if (stopped === 0 && killed === 0 && hu_reset_count === 0) {
+      out.message = 'No active runs and no stuck HUs for this plan.';
+    }
+    res.json(out);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+router.get('/runs/:commandId/log', (req, res) => {
+  try {
+    const runsDir = getHuBoardRunsDir(); // KJC-TSK-0421
+    const logPath = path.join(runsDir, `${req.params.commandId}.log`);
+    if (!fs.existsSync(logPath)) {
+      return res.json({ exists: false, size: 0, content: '' });
+    }
+    const stat = fs.statSync(logPath);
+    const offset = Math.max(0, Math.min(stat.size, Number(req.query.offset) || 0));
+    const MAX_READ = 1024 * 1024;
+    const length = Math.min(MAX_READ, stat.size - offset);
+    let content = '';
+    if (length > 0) {
+      const fd = fs.openSync(logPath, 'r');
+      try {
+        const buf = Buffer.alloc(length);
+        fs.readSync(fd, buf, 0, length, offset);
+        content = buf.toString('utf-8');
+      } finally {
+        fs.closeSync(fd);
+      }
+    }
+    res.json({ exists: true, size: stat.size, content });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/board/restart - Respawn the board server in place. The
+ * server can't truly restart itself (it'd kill its own process), so
+ * we use the detached-child + parent-exit pattern: spawn a copy with
+ * the same argv + cwd + env, unref it, ack the client, then exit
+ * after a 250 ms delay so the response actually flushes.
+ *
+ * The new server overwrites the PID file and bindes the same port
+ * (or the next free one if the old one hasn't released yet — handled
+ * by the existing find-available-port logic in startBoard).
+ *
+ * The browser tab's EventSource auto-reconnects, so the user sees a
+ * brief blip and the board comes back live.
+ */
+/**
+ * POST /api/board/shutdown - Tell the server to exit cleanly. Used
+ * by `kj board stop` as a fallback when the PID file is missing or
+ * stale (typical after the user has been hot-pulling Karajan and
+ * the running server is from a build that didn't write the PID
+ * file). The body of the response is sent before we exit, then a
+ * 250 ms delay to let the response flush, then process.exit(0).
+ */
+router.post('/board/shutdown', (_req, res) => {
+  if (process.env.KJ_BOARD_RESTART_MODE === 'echo') {
+    return res.json({ ok: true, mode: 'echo' });
+  }
+  res.json({ ok: true, shuttingDownInMs: 250 });
+  setTimeout(() => process.exit(0), 250);
+});
+
+router.post('/board/restart', (_req, res) => {
+  // Tests / programmatic callers can short-circuit the actual self-
+  // exec via env so the suite doesn't have its node process killed
+  // mid-test by a misfire.
+  if (process.env.KJ_BOARD_RESTART_MODE === 'echo') {
+    return res.json({ ok: true, restartingInMs: 0, mode: 'echo' });
+  }
+  try {
+    res.json({ ok: true, restartingInMs: 250 });
+    setTimeout(() => {
+      try {
+        const child = spawnChild(
+          process.execPath,
+          process.argv.slice(1),
+          { cwd: process.cwd(), detached: true, stdio: 'ignore', env: process.env }
+        );
+        child.unref();
+      } catch { /* if respawn fails, the user can `kj board start` manually */ }
+      process.exit(0);
+    }, 250);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * POST /api/sync - Force a full re-scan of hu-stories/ and sessions/ on disk.
+ * Useful when chokidar's file watcher misses new subdirectories created after
+ * the board started (known limitation with glob patterns).
+ */
+router.post('/sync', (_req, res) => {
+  try {
+    fullScan();
+    const projects = getProjects();
+    res.json({ synced: true, projects: projects.length });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+export default router;