karajan-code 4.70.4 → 5.0.0

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

@@ -0,0 +1,267 @@
+// KJC-TSK-0541: the project endpoints of /api, composed by routes/api.js.
+import { Router } from 'express';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  getProjects,
+  deleteProject,
+  getKjHome,
+  getHuBoardPlansDirs,
+  listPlanIdsForProject,
+  setProjectIsTest,
+  getProjectCost,
+  addTombstone,
+  getDb,
+} from '../../db.js';
+import { markPlanReady, renameProject } from '../../plan-mutations.js';
+import { runPreflight } from '../../preflight.js';
+import { projectPlans } from '../../plans-service.js';
+
+const router = Router();
+
+/**
+ * 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;
+    // KJC-BUG-0059 (v2.19.3): scan plans in BOTH the canonical
+    // ~/.karajan/plans/ AND the legacy ~/.kj/plans/ — the legacy
+    // fallback covers users who started the board before running any
+    // `kj` command on a fresh install (so the auto-migrator from
+    // v2.19.0 has not fired yet). Pre-fix, this endpoint hard-coded
+    // ~/.kj/plans/ as the default, missing every plan post-2.19.0
+    // → board card showed "directorio del proyecto: no detectado"
+    // even though the plan on disk had a valid projectDir.
+    try {
+      for await (const plan of projectPlans(projectId)) {
+        if (plan?.projectDir) { projectDir = plan.projectDir; break; }
+      }
+    } 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', async (req, res) => {
+  try {
+    const projectId = req.params.id;
+    // KJC-BUG-0059 (v2.19.3): scan canonical + legacy roots so users
+    // who have not yet run the auto-migrator still see their plans.
+    const out = [];
+    for await (const plan of projectPlans(projectId)) {
+      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,
+        // KJC-TSK-1197: a plan mirroring the shared board says so, with its repo.
+        readonly: plan.readonly || null,
+        repo: plan.readonly ? plan.repo || null : null,
+      });
+    }
+    res.json({ projectId, plans: out });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * GET /api/projects/:id/cost - Aggregated $ cost for a project (KJC-TSK-0516).
+ * Sums stories.cost_usd, groups by plan_id, returns 404 if project missing.
+ */
+router.get('/projects/:id/cost', (req, res) => {
+  try {
+    const cost = getProjectCost(req.params.id);
+    if (!cost) return res.status(404).json({ error: 'Project not found' });
+    res.json(cost);
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+/**
+ * DELETE /api/projects/:id - Cascade delete project + its stories + sessions.
+ * Also removes its session and plan directories from disk so the next sync
+ * does not re-import them.
+ */
+router.delete('/projects/:id', async (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.
+    // KJC-BUG-0059 (v2.19.3): when removing a deleted project's
+    // residual plan dirs, sweep BOTH the canonical and legacy roots
+    // so the cleanup is consistent for users mid-migration.
+    const fsPaths = [
+      ...sessionIds.map((sid) => path.join(getKjHome(), 'sessions', sid)),
+      ...getHuBoardPlansDirs().map((root) => path.join(root, 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 syncSessionFile / syncPlanFile.
+    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 { await fsp.rm(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 });
+  }
+});
+
+/**
+ * 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 });
+  }
+});
+
+export default router;

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

@@ -0,0 +1,135 @@
+// KJC-TSK-0541: the prompt endpoints of /api (questions the runner leaves for the board),
+// composed by routes/api.js.
+import { Router } from 'express';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import { getKjHome, addTombstone, isTombstoned as isTombstonedFn } from '../../db.js';
+import { publish as publishEvent } from '../../event-bus.js';
+import { pathExists } from '../../plans-service.js';
+
+const router = Router();
+
+/**
+ * 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', async (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 { await fsp.unlink(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 });
+  }
+});
+
+/**
+ * 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', async (_req, res) => {
+  try {
+    const dir = promptsDir();
+    if (!(await pathExists(dir))) return res.json([]);
+    const entries = await fsp.readdir(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 { await fsp.unlink(mainPath); } catch { /* */ }
+        try { await fsp.unlink(answerPath); } catch { /* */ }
+        continue;
+      }
+      let parsed;
+      try {
+        parsed = JSON.parse(await fsp.readFile(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 : await safeMtime(mainPath);
+      if (ageRef && (now - ageRef) > PROMPT_ZOMBIE_TTL_MS) {
+        try { await fsp.unlink(mainPath); } catch { /* */ }
+        try { await fsp.unlink(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 });
+  }
+});
+
+async function safeMtime(p) {
+  try { return (await fsp.stat(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', async (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();
+    await fsp.mkdir(dir, { recursive: true });
+    const promptPath = path.join(dir, `${req.params.promptId}.json`);
+    if (!(await pathExists(promptPath))) {
+      return res.status(404).json({ error: `Prompt not found: ${req.params.promptId}` });
+    }
+    const answerPath = path.join(dir, `${req.params.promptId}.answer.json`);
+    await fsp.writeFile(
+      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 });
+  }
+});
+
+export default router;

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

@@ -0,0 +1,95 @@
+// KJC-TSK-0541: the session endpoints of /api, composed by routes/api.js.
+import { Router } from 'express';
+import fsp from 'node:fs/promises';
+import path from 'node:path';
+
+import {
+  getProjects,
+  getSessionsByProject,
+  getSessionDetail,
+  deleteSession,
+  getKjHome,
+  addTombstone,
+} from '../../db.js';
+
+const router = Router();
+
+/**
+ * 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/sessions/:id - Delete a single session.
+ *
+ * Tombstones + removes `~/.karajan/sessions/<id>/` (KJC-TSK-0380).
+ */
+router.delete('/sessions/:id', async (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 { await fsp.rm(dir, { recursive: true, force: true }); dirRemoved = true; } catch { /* */ }
+    res.json({ deleted: true, dirRemoved });
+  } catch (err) {
+    res.status(500).json({ error: err.message });
+  }
+});
+
+export default router;

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

@@ -0,0 +1,183 @@
+// KJC-TSK-0541: the story (HU) endpoints of /api, composed by routes/api.js.
+import { Router } from 'express';
+
+import { getStoriesByProject, getStoryDetail, getStoryRow } from '../../db.js';
+import { setHuStatus, setHuFields } from '../../plan-mutations.js';
+
+const router = Router();
+
+/**
+ * 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 });
+  }
+});
+
+/**
+ * DELETE /api/stories/:id - Refused: stories are never deleted (KJC-TSK-0671).
+ */
+router.delete('/stories/:id', (req, res) => {
+  // KJC-TSK-0671 (absolute product rule): stories are NEVER deleted — the
+  // delete-and-recreate "fix" agents improvise loses history and produced
+  // the field saga this closes. Discard goes through the lifecycle instead.
+  res.status(405).json({
+    error: 'Stories are never deleted. Discard one with: kj hu move <id> skipped '
+      + '(archived, history kept). Dashboard warnings are fixed with the command '
+      + 'they name — see kj brief board.',
+  });
+});
+
+/**
+ * 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.
+ */
+// KJC-TSK-0394 PR6 (AC 6): el PATCH endpoint sólo acepta el modelo
+// canónico {pending, running, done}. Status legacy (`certified`,
+// `coding`, `reviewing`, `failed`, `blocked`, `needs_context`) siguen
+// vivos en plans existentes y los traduce la UI con canonicalStatus(),
+// pero NO pueden ser seteados por escrituras nuevas — devolvemos 400
+// con `suggestion` apuntando al mapping correcto. `running` queda fuera
+// del dropdown del modal (lifecycle del orquestador), pero el endpoint
+// lo acepta por si un programa externo lo necesita.
+const ALLOWED_STORY_STATUSES = new Set(['pending', 'running', 'done']);
+// Mapping canónico para la sugerencia del 400 cuando el caller manda
+// un valor legacy. Mantenemos la regla viva en src/plan/plan-schema.js
+// (mapLegacyStatusToResult) — esta tabla es sólo el subset accionable
+// desde el endpoint (status + result).
+const LEGACY_STATUS_SUGGESTION = {
+  certified: { status: 'done', result: 'pass' },
+  failed: { status: 'pending', result: 'fail' },
+  coding: { status: 'running', result: null },
+  reviewing: { status: 'running', result: null },
+  blocked: { status: 'pending', result: null },
+  needs_context: { status: 'pending', result: null },
+};
+// 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.
+// KJC-PRP-0002 PR6: `assignee` is editable from the board modal when the
+// project is team-shared. The whitelist itself is project-agnostic — the
+// modal hides the input on non-shared projects, but accepting the field
+// here doesn't hurt (sync just stores it).
+const EDITABLE_HU_FIELDS = ['title', 'scope', 'task_type', 'acceptance_criteria', 'acceptance_tests', 'blocked_by', 'coder_model', 'reviewer_model', 'coder_provider', 'reviewer_provider', 'assignee'];
+
+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)) {
+      // KJC-TSK-0394 PR6 (AC 6): si el caller manda un status legacy,
+      // devolvemos un 400 con `suggestion` apuntando al mapping canónico.
+      // Una herramienta externa puede leer el body, aplicar el mapeo y
+      // re-intentar — sin tener que descubrir la tabla por ensayo y error.
+      const suggestion = LEGACY_STATUS_SUGGESTION[body.status] || null;
+      return res.status(400).json({
+        error: `status must be one of: ${[...ALLOWED_STORY_STATUSES].join(', ')}`,
+        suggestion,
+      });
+    }
+
+    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 });
+  }
+});
+
+export default router;