@karajan-family/code 4.21.0

package/packages/hu-board/public/utils/story-edit-form.js

@@ -0,0 +1,271 @@
+// KJC-TSK-0501 step 8c/8 — Story edit form (inline editor for the HU modal).
+//
+// Classic script (no exports). Loaded by index.html before app.js so the
+// top-level `function` declarations are hoisted into the shared realm and
+// `showStoryDetail` (story-detail-view.js) can call `renderStoryEditForm`
+// when the user hits ✎ on a story.
+//
+// Globals consumed from earlier scripts / app.js:
+//   - esc()                  (app.js)
+//   - shortStoryId()         (utils/formatters.js)
+//   - projectInitialsCache   (mutable in app.js — assignment crosses
+//                             scripts transparently)
+//   - showStoryDetail()      (utils/story-detail-view.js)
+//   - showError()            (utils/modals.js)
+//   - closeModal()           (app.js → window.closeModal, used by
+//                             inline onclick on the modal close button)
+//   - renderBoard()          (app.js)
+
+/**
+ * Swap the story modal into an inline edit form. Accepts the full story
+ * record that `showStoryDetail` just rendered so we don't re-fetch —
+ * the user's intent is "edit what I'm looking at".
+ *
+ * Cancel restores the read-only view via `showStoryDetail`; Save posts a
+ * PATCH and, on success, re-opens in read-only with the refreshed row.
+ *
+ * @param {object} story
+ */
+function renderStoryEditForm(story) {
+  const content = document.getElementById('modal-content');
+  const initials = projectInitialsCache[story.project_id] || 'kj';
+  const shortId = shortStoryId(story, initials);
+
+  const rawAc = story.acceptance_criteria ? JSON.parse(story.acceptance_criteria) : [];
+  // Represent AC as text: plain strings go verbatim, Gherkin objects
+  // collapse to "Given … | When … | Then …". On save we parse back —
+  // if the line matches the pattern we treat it as Gherkin, otherwise
+  // a free-form string.
+  const acInitial = rawAc
+    .map((c) => typeof c === 'string' ? c : (c.given ? `Given ${c.given} | When ${c.when} | Then ${c.then}` : JSON.stringify(c)))
+    .join('\n');
+
+  // Tests-first editor: one block per test with a type selector
+  // (shell | gherkin), the content textarea, optional file path, and
+  // a remove button. Save collects them into the structured v2.7.5
+  // array shape. Plain strings in the existing data are treated as
+  // legacy shell tests and auto-upgraded to the structured form.
+  const rawTests = story.acceptance_tests ? JSON.parse(story.acceptance_tests) : [];
+  const testsInitial = rawTests.map((t) => {
+    if (typeof t === 'string') return { type: 'shell', content: t, file: '' };
+    if (t && typeof t === 'object') {
+      return {
+        type: t.type === 'gherkin' ? 'gherkin' : 'shell',
+        content: typeof t.content === 'string' ? t.content : JSON.stringify(t),
+        file: typeof t.file === 'string' ? t.file : '',
+      };
+    }
+    return { type: 'shell', content: String(t ?? ''), file: '' };
+  });
+
+  const scopeInitial = story.original_text || story.certified_want || '';
+  const TASK_TYPES = ['sw', 'infra', 'doc', 'add-tests', 'refactor'];
+
+  content.innerHTML = `
+    <div class="modal__header">
+      <div>
+        <div class="modal__title" title="${esc(story.id)}">${esc(shortId)} <span style="font-size:0.75rem;color:var(--text-muted);font-weight:normal">(editing)</span></div>
+        <div class="modal__subtitle" style="font-size:0.75rem;color:var(--text-muted);font-family:monospace;margin-top:2px">${esc(story.id)}</div>
+      </div>
+      <button class="modal__close" onclick="closeModal()">&times;</button>
+    </div>
+
+    <form id="hu-edit-form" onsubmit="return false" style="display:flex;flex-direction:column;gap:14px;padding:8px 0">
+      <label style="display:flex;flex-direction:column;gap:4px;font-size:0.85rem">
+        <span style="color:var(--text-muted)">Title</span>
+        <input type="text" id="edit-title" value="${esc(story.title || '')}"
+               style="padding:8px;border:1px solid var(--border);background:var(--bg-primary);color:var(--text);border-radius:var(--radius-sm);font-size:0.95rem"
+               maxlength="200" required>
+      </label>
+
+      <label style="display:flex;flex-direction:column;gap:4px;font-size:0.85rem">
+        <span style="color:var(--text-muted)">Scope</span>
+        <textarea id="edit-scope" rows="4"
+                  style="padding:8px;border:1px solid var(--border);background:var(--bg-primary);color:var(--text);border-radius:var(--radius-sm);font-family:inherit;font-size:0.9rem;line-height:1.5;resize:vertical">${esc(scopeInitial)}</textarea>
+      </label>
+
+      <label style="display:flex;flex-direction:column;gap:4px;font-size:0.85rem">
+        <span style="color:var(--text-muted)">Task type</span>
+        <select id="edit-task-type"
+                style="padding:8px;border:1px solid var(--border);background:var(--bg-primary);color:var(--text);border-radius:var(--radius-sm);font-size:0.9rem">
+          ${TASK_TYPES.map((t) => `<option value="${t}">${t}</option>`).join('')}
+        </select>
+      </label>
+
+      <label style="display:flex;flex-direction:column;gap:4px;font-size:0.85rem">
+        <span style="color:var(--text-muted)">
+          Acceptance criteria — one per line.
+          Gherkin: <code>Given X | When Y | Then Z</code>
+        </span>
+        <textarea id="edit-ac" rows="6"
+                  style="padding:8px;border:1px solid var(--border);background:var(--bg-primary);color:var(--text);border-radius:var(--radius-sm);font-family:var(--font-mono, monospace);font-size:0.85rem;line-height:1.5;resize:vertical">${esc(acInitial)}</textarea>
+      </label>
+
+      <fieldset style="border:1px solid var(--border);border-radius:var(--radius-sm);padding:10px 12px;margin:0">
+        <legend style="color:var(--text-muted);font-size:0.85rem;padding:0 6px">
+          Acceptance tests — the contract the coder must satisfy
+        </legend>
+        <div id="edit-tests-list" style="display:flex;flex-direction:column;gap:8px"></div>
+        <button type="button" id="edit-tests-add"
+                style="margin-top:8px;padding:4px 10px;font-size:0.8rem;background:var(--bg-primary);color:var(--text);border:1px solid var(--border);border-radius:var(--radius-sm);cursor:pointer">
+          + Add test
+        </button>
+      </fieldset>
+
+      <div style="display:flex;justify-content:flex-end;gap:8px;margin-top:8px;padding-top:12px;border-top:1px solid var(--border)">
+        <button type="button" id="edit-cancel" class="control-btn"
+                style="padding:6px 14px;border:1px solid var(--border);background:var(--bg-primary);color:var(--text);border-radius:var(--radius-sm);cursor:pointer">
+          Cancel
+        </button>
+        <button type="button" id="edit-save" class="control-btn"
+                style="padding:6px 14px;border:none;background:var(--color-green);color:#fff;border-radius:var(--radius-sm);cursor:pointer;font-weight:600">
+          Save
+        </button>
+      </div>
+    </form>
+  `;
+
+  // Tests editor state + renderers. Kept on the function scope (not
+  // on window) so reopening the form gives a fresh copy.
+  let testRows = [...testsInitial];
+  const listEl = document.getElementById('edit-tests-list');
+
+  function renderTestsEditor() {
+    listEl.innerHTML = testRows.map((t, i) => `
+      <div class="edit-test-row" data-idx="${i}"
+           style="display:grid;grid-template-columns:auto 1fr auto;gap:6px;align-items:start;padding:8px;border:1px solid var(--border);border-radius:var(--radius-sm);background:var(--bg-primary)">
+        <select data-field="type"
+                style="padding:4px 6px;border:1px solid var(--border);background:var(--bg-secondary);color:var(--text);border-radius:var(--radius-sm);font-size:0.8rem">
+          <option value="shell"${t.type === 'shell' ? ' selected' : ''}>shell</option>
+          <option value="gherkin"${t.type === 'gherkin' ? ' selected' : ''}>gherkin</option>
+        </select>
+        <div style="display:flex;flex-direction:column;gap:4px">
+          <textarea data-field="content" rows="${t.type === 'gherkin' ? 3 : 2}"
+                    placeholder="${t.type === 'gherkin' ? 'Given …\\nWhen …\\nThen …' : 'npx vitest run test/foo.test.js'}"
+                    style="padding:6px 8px;border:1px solid var(--border);background:var(--bg-secondary);color:var(--text);border-radius:var(--radius-sm);font-family:var(--font-mono, monospace);font-size:0.82rem;line-height:1.4;resize:vertical">${esc(t.content)}</textarea>
+          <input type="text" data-field="file" placeholder="Optional: file path (e.g. tests/login.test.ts)" value="${esc(t.file || '')}"
+                 style="padding:4px 8px;border:1px solid var(--border);background:var(--bg-secondary);color:var(--text);border-radius:var(--radius-sm);font-family:var(--font-mono, monospace);font-size:0.75rem">
+        </div>
+        <button type="button" data-field="remove" title="Remove this test"
+                style="align-self:start;padding:4px 8px;background:transparent;border:1px solid var(--border);color:var(--text-muted);border-radius:var(--radius-sm);cursor:pointer;font-size:0.8rem">✕</button>
+      </div>
+    `).join('');
+
+    // Bind the edit events. We re-bind on every render — cheap, and
+    // keeps the state → DOM mapping simple.
+    listEl.querySelectorAll('.edit-test-row').forEach((row) => {
+      const idx = Number(row.dataset.idx);
+      row.querySelector('[data-field="type"]').addEventListener('change', (e) => {
+        testRows[idx].type = e.target.value;
+        renderTestsEditor();            // re-render so placeholder updates
+      });
+      row.querySelector('[data-field="content"]').addEventListener('input', (e) => {
+        testRows[idx].content = e.target.value;
+      });
+      row.querySelector('[data-field="file"]').addEventListener('input', (e) => {
+        testRows[idx].file = e.target.value;
+      });
+      row.querySelector('[data-field="remove"]').addEventListener('click', () => {
+        testRows.splice(idx, 1);
+        renderTestsEditor();
+      });
+    });
+  }
+
+  renderTestsEditor();
+
+  document.getElementById('edit-tests-add').addEventListener('click', () => {
+    testRows.push({ type: 'shell', content: '', file: '' });
+    renderTestsEditor();
+  });
+
+  document.getElementById('edit-cancel').addEventListener('click', () => showStoryDetail(story.id));
+  document.getElementById('edit-save').addEventListener('click', () => saveStoryEdits(story, () => testRows));
+}
+
+/**
+ * Collect the form values, compute the diff against the story as it
+ * was on modal open, and PATCH only the changed fields. Empty diff is
+ * a no-op (close out of edit mode without an API call).
+ * @param {object} story
+ */
+async function saveStoryEdits(story, getTestRows) {
+  const title = document.getElementById('edit-title').value.trim();
+  const scope = document.getElementById('edit-scope').value;
+  const taskType = document.getElementById('edit-task-type').value;
+  const acRaw = document.getElementById('edit-ac').value;
+
+  if (!title) {
+    await showError('Title cannot be empty.', { title: 'Invalid input' });
+    return;
+  }
+
+  // Parse AC: one per line; a line with "Given X | When Y | Then Z"
+  // (case-insensitive) becomes Gherkin; everything else stays a string.
+  // Blank lines are dropped.
+  const acceptance_criteria = acRaw.split('\n')
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const m = /^Given\s+(.*?)\s*\|\s*When\s+(.*?)\s*\|\s*Then\s+(.*)$/i.exec(line);
+      if (m) return { given: m[1].trim(), when: m[2].trim(), then: m[3].trim() };
+      return line;
+    });
+
+  // Collect the structured acceptance_tests from the editor state,
+  // dropping rows the user left empty.
+  const testRows = typeof getTestRows === 'function' ? getTestRows() : [];
+  const acceptance_tests = testRows
+    .map((t) => ({
+      type: t.type === 'gherkin' ? 'gherkin' : 'shell',
+      content: (t.content || '').trim(),
+      file: (t.file || '').trim(),
+    }))
+    .filter((t) => t.content.length > 0)
+    .map((t) => (t.file ? t : { type: t.type, content: t.content }));
+
+  // Diff against the original so we don't send untouched fields and
+  // let the server's COALESCE keep existing values.
+  const patch = {};
+  const originalScope = story.original_text || story.certified_want || '';
+  if (title !== (story.title || '')) patch.title = title;
+  if (scope !== originalScope) patch.scope = scope;
+  if (taskType && taskType !== 'sw') patch.task_type = taskType;
+  const prevAcStr = story.acceptance_criteria || '[]';
+  const nextAcStr = JSON.stringify(acceptance_criteria);
+  if (nextAcStr !== prevAcStr) patch.acceptance_criteria = acceptance_criteria;
+  const prevTestsStr = story.acceptance_tests || '[]';
+  const nextTestsStr = JSON.stringify(acceptance_tests);
+  if (nextTestsStr !== prevTestsStr) patch.acceptance_tests = acceptance_tests;
+
+  if (Object.keys(patch).length === 0) {
+    showStoryDetail(story.id);
+    return;
+  }
+
+  try {
+    const res = await fetch(`/api/stories/${encodeURIComponent(story.id)}`, {
+      method: 'PATCH',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(patch),
+    });
+    if (!res.ok) {
+      if (res.status === 404) {
+        await showError(
+          'The board server does not recognise the extended PATCH endpoint.\n\n'
+          + 'Restart it to pick up v2.7.5+:\n\n'
+          + '    kj board stop && kj board start',
+          { title: 'Board out of date' }
+        );
+        return;
+      }
+      const msg = (await res.json().catch(() => ({}))).error || `HTTP ${res.status}`;
+      await showError(msg, { title: 'Could not save HU' });
+      return;
+    }
+    await renderBoard();               // card shows new title/counts
+    await showStoryDetail(story.id);   // reopen modal with fresh data
+  } catch (err) {
+    await showError(err.message, { title: 'Could not save HU' });
+  }
+}

package/packages/hu-board/public/wiki.html

@@ -0,0 +1,32 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Karajan Wiki · QMD semantic search</title>
+  <link rel="stylesheet" href="/styles.css">
+</head>
+<body>
+  <header class="header">
+    <div class="header__logo"><div><div class="header__title">Karajan Wiki</div><div class="header__subtitle">QMD semantic search</div></div></div>
+    <nav class="header__nav">
+      <a class="nav-btn" href="/">← Board</a>
+      <a class="nav-btn" href="/rag.html">RAG</a>
+      <button class="nav-btn active">Wiki</button>
+    </nav>
+  </header>
+  <main class="main" id="wiki-app">
+    <section class="wiki-search">
+      <form id="wiki-form" class="wiki-form" autocomplete="off">
+        <input id="wiki-q" type="search" placeholder="Search the project wiki…" aria-label="Query" required>
+        <input id="wiki-collection" type="text" placeholder="collection (optional)" aria-label="Collection">
+        <label class="wiki-fast"><input id="wiki-fast" type="checkbox"> fast (no rerank)</label>
+        <button type="submit" class="control-btn" id="wiki-go">Search</button>
+      </form>
+      <p class="wiki-hint">QMD runs locally — 0 tokens, ~60s with rerank, ~5s in fast mode.</p>
+    </section>
+    <section id="wiki-results" class="wiki-results"></section>
+  </main>
+  <script src="/wiki.js"></script>
+</body>
+</html>

package/packages/hu-board/public/wiki.js

@@ -0,0 +1,53 @@
+// KJC-TSK-0508 — HU Board Wiki panel frontend. Calls POST /api/wiki/query
+// (server-side spawns `qmd query --format json`) and renders the hits.
+// A 503 with `installable:true` triggers an "Install QMD" CTA instead of
+// a generic error so the user can act on the missing binary.
+const TOKEN = new URLSearchParams(location.search).get("token") || localStorage.getItem("kj_board_token") || "";
+const HEADERS = { "Content-Type": "application/json", ...(TOKEN ? { Authorization: `Bearer ${TOKEN}` } : {}) };
+const ESC = (s) => String(s).replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[c]));
+
+function renderInstallCTA(root) {
+  root.innerHTML = `<div class="rag-card rag-card--error">
+    <h3>QMD not installed</h3>
+    <p>The semantic wiki engine is not available on this host. Install it once:</p>
+    <pre class="wiki-code">npm install -g @tobilu/qmd</pre>
+    <p class="rag-stat-sub">Then re-run <code>kj init</code> in this project to register the wiki collection.</p>
+  </div>`;
+}
+
+function renderHits(root, results) {
+  if (!Array.isArray(results) || results.length === 0) {
+    root.innerHTML = '<p class="rag-empty">no hits — try a broader query or run <code>qmd update</code>.</p>';
+    return;
+  }
+  root.innerHTML = results.map((r) => {
+    const src = r.source || r.path || r.file || "(unknown source)";
+    const snip = r.snippet || r.text || r.content || "";
+    const score = typeof r.score === "number" ? r.score.toFixed(3) : "";
+    return `<article class="wiki-hit">
+      <header class="wiki-hit__head"><span class="wiki-hit__src">${ESC(src)}</span>${score ? `<span class="wiki-hit__score">${ESC(score)}</span>` : ""}</header>
+      <pre class="wiki-hit__snip">${ESC(snip)}</pre>
+    </article>`;
+  }).join("");
+}
+
+async function runSearch(ev) {
+  ev?.preventDefault();
+  const root = document.getElementById("wiki-results");
+  const query = document.getElementById("wiki-q").value.trim();
+  if (!query) return;
+  const collection = document.getElementById("wiki-collection").value.trim() || undefined;
+  const fast = document.getElementById("wiki-fast").checked;
+  root.innerHTML = '<div class="loading"><div class="loading__spinner"></div><p>Searching the wiki…</p></div>';
+  try {
+    const res = await fetch("/api/wiki/query", { method: "POST", headers: HEADERS, body: JSON.stringify({ query, collection, fast }) });
+    const data = await res.json().catch(() => ({}));
+    if (res.status === 503 && data.installable) { renderInstallCTA(root); return; }
+    if (!res.ok) throw new Error(data.error || `HTTP ${res.status}`);
+    renderHits(root, data.results);
+  } catch (err) {
+    root.innerHTML = `<div class="rag-card rag-card--error"><strong>Error:</strong> ${ESC(err.message || String(err))}</div>`;
+  }
+}
+
+document.getElementById("wiki-form").addEventListener("submit", runSearch);

package/packages/hu-board/src/auth.js

@@ -0,0 +1,92 @@
+/**
+ * Bearer-token authentication middleware for HU Board.
+ *
+ * Threat model — KJC-TSK-0355:
+ *   The board is a localhost dev tool. The "shared dev machine" risk
+ *   only kicks in when the server binds beyond loopback (e.g.
+ *   `--bind 0.0.0.0` to access from another laptop on LAN). For pure
+ *   loopback traffic, the OS already enforces "only the local user
+ *   can connect", so a token would be UX friction with zero benefit
+ *   (the browser opens `http://localhost:4000` and would stop working
+ *   without manual `?token=...` injection on every link).
+ *
+ * Behaviour:
+ *   - When `HU_BOARD_TOKEN` is set AND the request is from a non-
+ *     loopback address → require the token in `Authorization: Bearer`
+ *     header, `?token=` query param, or `kj_board_token` cookie.
+ *   - When the request comes from loopback (127.0.0.1 / ::1 / ::ffff:127.0.0.1)
+ *     → skip auth. The browser running on the same machine just works.
+ *   - When `HU_BOARD_TOKEN` is unset → skip auth entirely. Tests and
+ *     legacy callers keep working.
+ */
+
+/** Loopback addresses we trust without auth, regardless of token state. */
+const LOOPBACK_ADDRESSES = new Set([
+  "127.0.0.1",
+  "::1",
+  "::ffff:127.0.0.1",
+]);
+
+/**
+ * Returns an Express middleware that enforces token auth for non-
+ * loopback requests when HU_BOARD_TOKEN is defined.
+ *
+ * @returns {import('express').RequestHandler}
+ */
+export function authMiddleware() {
+  return (req, res, next) => {
+    const expected = process.env.HU_BOARD_TOKEN;
+    if (!expected) return next();
+
+    if (isLoopback(req)) return next();
+
+    const token = extractToken(req);
+    if (token === expected) return next();
+
+    return res.status(401).json({
+      error: "Unauthorized",
+      message:
+        "HU Board is bound to a non-loopback interface. Pass the token from " +
+        "~/.karajan/hu-board/token via Authorization: Bearer <token>, " +
+        "?token=<token>, or the kj_board_token cookie.",
+    });
+  };
+}
+
+/**
+ * @param {import('express').Request} req
+ * @returns {boolean}
+ */
+function isLoopback(req) {
+  // Express populates req.ip from req.socket.remoteAddress unless
+  // `trust proxy` is set (we don't, by design — the board never sits
+  // behind a proxy in its supported deployment). req.ip is therefore
+  // the actual peer address.
+  const ip = req.ip || req.socket?.remoteAddress || "";
+  return LOOPBACK_ADDRESSES.has(ip);
+}
+
+/**
+ * @param {import('express').Request} req
+ * @returns {string|undefined}
+ */
+function extractToken(req) {
+  const authHeader = req.headers.authorization;
+  if (authHeader && authHeader.startsWith("Bearer ")) {
+    return authHeader.slice(7);
+  }
+  if (req.query && typeof req.query.token === "string") {
+    return req.query.token;
+  }
+  // Cookie parsing: we don't pull cookie-parser as a dep just for one
+  // header. Express stores the raw header in req.headers.cookie; the
+  // grammar is `name=value; name2=value2`. Good enough for one key.
+  const cookieHeader = req.headers.cookie;
+  if (cookieHeader) {
+    for (const part of cookieHeader.split(";")) {
+      const [name, ...rest] = part.trim().split("=");
+      if (name === "kj_board_token") return rest.join("=");
+    }
+  }
+  return undefined;
+}

package/packages/hu-board/src/boot-info.js

@@ -0,0 +1,16 @@
+/**
+ * Process-scoped boot info (KJC-TSK-0379).
+ *
+ * BOOT_TIME is captured at module load and exposed via /api/version so
+ * the client can detect server restarts and trigger a reload. Lives in
+ * its own module to avoid the server.js ↔ routes/api.js import cycle.
+ */
+
+import { createRequire } from 'node:module';
+
+export const BOOT_TIME = new Date().toISOString();
+
+const require = createRequire(import.meta.url);
+export const PKG_VERSION = (() => {
+  try { return require('../package.json').version; } catch { return 'unknown'; }
+})();

package/packages/hu-board/src/cleanup-zombies.js

@@ -0,0 +1,145 @@
+/**
+ * Cleanup zombi resources of the HU Board (KJC-TSK-0380 PR C).
+ *
+ * Detects and removes orphan / abandoned entries that survive across
+ * dogfooding sessions and would otherwise reappear on every fullScan:
+ *
+ *  1. Ephemeral projects (`tmp_*`, `test_*`, `demo_*`, `kj-test-*`,
+ *     `s_*`, `plan-*`) older than `staleProjectDays` (default 7).
+ *  2. Stale prompts (no `.answer.json` and file mtime older than
+ *     `stalePromptHours`, default 24).
+ *  3. Orphan session directories (`~/.karajan/sessions/<id>/`) older
+ *     than `staleProjectDays` with no matching DB row.
+ *
+ * Each removal goes through the same path the API endpoints use:
+ * tombstone + fs cleanup. So nothing resurrects on the next sync.
+ *
+ * Usage:
+ *   import { cleanupZombies } from './cleanup-zombies.js';
+ *   const report = cleanupZombies({ dryRun: false });
+ *
+ * Pure module; no HTTP. Safe to call with the server down.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  getDb,
+  getKjHome,
+  addTombstone,
+  isTombstoned,
+  deleteProject,
+  deleteSession,
+  initDb,
+  closeDb,
+} from './db.js';
+
+// Re-export the db lifecycle helpers so callers (e.g. `kj board cleanup`)
+// can do a single `await import('cleanup-zombies.js')` and stay within
+// the project's dynamic-import budget. The script otherwise needs both
+// initDb/closeDb (lifecycle) and cleanupZombies (logic).
+export { initDb, closeDb };
+
+const EPHEMERAL_PREFIXES = ['tmp_', 'test_', 'demo_', 'kj-test-', 's_', 'plan-'];
+
+function isEphemeralId(id) {
+  return EPHEMERAL_PREFIXES.some((p) => id.startsWith(p));
+}
+
+// KJC-BUG-0059 (v2.19.3): cleanup walks all known plan roots,
+// canonical first then legacy. Pre-fix hard-coded `~/.kj/plans/`
+// missed every plan post-v2.19.0 → zombies never garbage-collected.
+import { getHuBoardPlansDirs } from './db.js';
+function plansRoots() {
+  return getHuBoardPlansDirs();
+}
+
+function olderThanDays(isoStr, days) {
+  if (!isoStr) return true;
+  const t = Date.parse(isoStr);
+  if (Number.isNaN(t)) return true;
+  return (Date.now() - t) > days * 24 * 60 * 60 * 1000;
+}
+
+function olderThanHours(mtimeMs, hours) {
+  return (Date.now() - mtimeMs) > hours * 60 * 60 * 1000;
+}
+
+/**
+ * @param {object} opts
+ * @param {boolean} [opts.dryRun=false] - Compute the report without writing.
+ * @param {number}  [opts.staleProjectDays=7]
+ * @param {number}  [opts.stalePromptHours=24]
+ * @returns {{ projects: string[], prompts: string[], sessions: string[], dryRun: boolean }}
+ */
+export function cleanupZombies(opts = {}) {
+  const dryRun = !!opts.dryRun;
+  const staleProjectDays = opts.staleProjectDays ?? 7;
+  const stalePromptHours = opts.stalePromptHours ?? 24;
+
+  const report = { projects: [], prompts: [], sessions: [], dryRun };
+  const db = getDb();
+
+  // (1) Ephemeral projects -------------------------------------------------
+  const allProjects = db.prepare('SELECT id, last_activity FROM projects').all();
+  for (const proj of allProjects) {
+    if (!isEphemeralId(proj.id)) continue;
+    if (!olderThanDays(proj.last_activity, staleProjectDays)) continue;
+    report.projects.push(proj.id);
+    if (dryRun) continue;
+
+    const storyIds = db.prepare('SELECT id FROM stories WHERE project_id = ?').all(proj.id).map((r) => r.id);
+    const sessionIds = db.prepare('SELECT id FROM sessions WHERE project_id = ?').all(proj.id).map((r) => r.id);
+    const fsPaths = [
+      ...storyIds.map((sid) => path.join(getKjHome(), 'hu-stories', sid)),
+      ...sessionIds.map((sid) => path.join(getKjHome(), 'sessions', sid)),
+      ...plansRoots().map((root) => path.join(root, proj.id)),
+    ];
+    deleteProject(proj.id);
+    addTombstone('project', proj.id, { source: 'auto-cleanup', fsPaths });
+    for (const sid of storyIds) addTombstone('story', sid, { source: 'auto-cleanup' });
+    for (const sid of sessionIds) addTombstone('session', sid, { source: 'auto-cleanup' });
+    for (const p of fsPaths) { try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* */ } }
+  }
+
+  // (2) Stale prompts ------------------------------------------------------
+  const promptsDir = path.join(getKjHome(), 'prompts');
+  if (fs.existsSync(promptsDir)) {
+    for (const name of fs.readdirSync(promptsDir)) {
+      if (!name.endsWith('.json') || name.endsWith('.answer.json')) continue;
+      const promptId = name.replace(/\.json$/, '');
+      if (isTombstoned('prompt', promptId)) continue;
+      const fullPath = path.join(promptsDir, name);
+      const answerPath = path.join(promptsDir, `${promptId}.answer.json`);
+      if (fs.existsSync(answerPath)) continue; // already resolved
+      const stat = fs.statSync(fullPath);
+      if (!olderThanHours(stat.mtimeMs, stalePromptHours)) continue;
+      report.prompts.push(promptId);
+      if (dryRun) continue;
+      addTombstone('prompt', promptId, { source: 'auto-cleanup', fsPaths: [fullPath, answerPath] });
+      try { fs.unlinkSync(fullPath); } catch { /* */ }
+    }
+  }
+
+  // (3) Orphan session directories ----------------------------------------
+  const sessionsDir = path.join(getKjHome(), 'sessions');
+  if (fs.existsSync(sessionsDir)) {
+    for (const dir of fs.readdirSync(sessionsDir)) {
+      if (isTombstoned('session', dir)) continue;
+      const fullPath = path.join(sessionsDir, dir);
+      const stat = fs.statSync(fullPath);
+      if (!stat.isDirectory()) continue;
+      const inDb = db.prepare('SELECT id FROM sessions WHERE id = ?').get(dir);
+      if (inDb) continue; // active session, not orphan
+      const mtimeIso = new Date(stat.mtimeMs).toISOString();
+      if (!olderThanDays(mtimeIso, staleProjectDays)) continue;
+      report.sessions.push(dir);
+      if (dryRun) continue;
+      deleteSession(dir);
+      addTombstone('session', dir, { source: 'auto-cleanup', fsPaths: [fullPath] });
+      try { fs.rmSync(fullPath, { recursive: true, force: true }); } catch { /* */ }
+    }
+  }
+
+  return report;
+}