karajan-code 3.0.0 → 3.2.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/config-yaml.js

@@ -349,11 +349,19 @@ function getDeep(obj, path) {
   return cur;
 }
 
+// KJC-BUG-0076: never walk into Object.prototype via crafted YAML keys
+// (`__proto__.x`, `constructor.prototype.y`, `prototype.z`). Silent skip
+// over a poisoned segment — the rest of the path is untouched.
+const UNSAFE_KEY_RE = /^(?:__proto__|constructor|prototype)$/;
+
 function setDeep(obj, path, value) {
+  if (typeof path !== 'string') return;
   const parts = path.split('.');
   const last = parts.pop();
+  if (UNSAFE_KEY_RE.test(last)) return;
   let cur = obj;
   for (const p of parts) {
+    if (UNSAFE_KEY_RE.test(p)) return;
     if (cur[p] == null || typeof cur[p] !== 'object') cur[p] = {};
     cur = cur[p];
   }
@@ -361,10 +369,13 @@ function setDeep(obj, path, value) {
 }
 
 function deleteDeep(obj, path) {
+  if (typeof path !== 'string') return;
   const parts = path.split('.');
   const last = parts.pop();
+  if (UNSAFE_KEY_RE.test(last)) return;
   let cur = obj;
   for (const p of parts) {
+    if (UNSAFE_KEY_RE.test(p)) return;
     if (cur == null || typeof cur !== 'object') return;
     cur = cur[p];
   }
@@ -516,3 +527,6 @@ export function writeConfigPatch(patch, { scope = 'global' } = {}) {
   renameSync(tmpFile, p);
   return { path: p, scope, written: true, applied, errors: [] };
 }
+
+// Exposed for prototype-pollution regression tests (KJC-BUG-0076).
+export const __pollutionInternals = { setDeep, deleteDeep };

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

@@ -1,6 +1,6 @@
 import Database from 'better-sqlite3';
-import { join } from 'node:path';
-import { mkdirSync, renameSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { mkdirSync, renameSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 
 /** @type {import('better-sqlite3').Database | null} */
@@ -23,6 +23,19 @@ function vitestTmpKjHome() {
     `karajan-vitest-${process.pid}-${Math.random().toString(36).slice(2, 10)}`,
     '.karajan'
   );
+  // KJC-BUG-0075: clean up on clean exit so /tmp doesn't accumulate one
+  // dir per fork × run. We rm the *parent* (the `karajan-vitest-<pid>-<rand>`
+  // wrapper), not the `.karajan` segment, so the whole tmp tree goes.
+  // Only fires on graceful exit; SIGKILL leaks are caught by the
+  // global-setup mtime purge at the start of the next run.
+  const parent = dirname(_vitestKjHome);
+  process.on('exit', () => {
+    try {
+      rmSync(parent, { recursive: true, force: true });
+    } catch {
+      // best-effort: never crash a test process on cleanup failure
+    }
+  });
   return _vitestKjHome;
 }
 
@@ -310,6 +323,11 @@ export function initDb() {
   // unconditionally so solo devs who later promote a plan don't lose
   // values they typed pre-share.
   try { db.exec('ALTER TABLE stories ADD COLUMN assignee TEXT'); } catch { /* already migrated */ }
+  // KJC-TSK-0514 (Cost C): persisted USD cost of running this HU. NULL
+  // until the orchestrator (Cost D) calls setStoryCost on HU close. UI
+  // renders "—" while NULL. Stored as REAL so the SQL aggregations in
+  // Cost E (/api/projects/:id/cost) can SUM directly without parsing.
+  try { db.exec('ALTER TABLE stories ADD COLUMN cost_usd REAL'); } catch { /* already migrated */ }
   try { db.exec('CREATE INDEX IF NOT EXISTS idx_stories_plan ON stories(plan_id)'); } catch { /* ignore */ }
 
   // is_test (KJC-TSK-0371 — board polish #3): per-project flag that
@@ -486,6 +504,32 @@ export function updateStoryStatus(storyId, status) {
   return res.changes > 0;
 }
 
+/**
+ * Persist the USD cost of a HU. Called by the orchestrator (Cost D) once
+ * the HU finishes — the value comes from `aggregateRunCost(events).totalUsd`
+ * (Cost B). `null` clears the cell so the UI renders "—" again. Other
+ * numeric inputs are coerced via `Number`; non-finite values reject with
+ * an explicit throw so callers don't silently NULL-out real cost rows.
+ *
+ * @param {string} storyId
+ * @param {number|null} costUsd
+ * @returns {boolean} true when the row existed and was updated
+ */
+export function setStoryCost(storyId, costUsd) {
+  let value = null;
+  if (costUsd !== null && costUsd !== undefined) {
+    const n = Number(costUsd);
+    if (!Number.isFinite(n)) {
+      throw new Error(`setStoryCost: costUsd must be a finite number or null (got ${costUsd})`);
+    }
+    value = n;
+  }
+  const res = getDb()
+    .prepare('UPDATE stories SET cost_usd = ?, updated_at = ? WHERE id = ?')
+    .run(value, new Date().toISOString(), storyId);
+  return res.changes > 0;
+}
+
 /**
  * List every distinct `plan_id` stamped on the stories of a given project.
  * Used by "mark plan ready" so the board can act on each plan of a project
@@ -585,6 +629,53 @@ export function getStoriesByProject(projectId) {
   `).all(projectId);
 }
 
+/**
+ * Aggregate $ cost for a project (KJC-TSK-0516, Cost E).
+ * Sums stories.cost_usd, groups by plan_id ('unassigned' for NULL).
+ * Returns null if project does not exist; otherwise an object with
+ * totalUsd=0 and byPlan=[] when no stories carry cost_usd yet.
+ * @param {string} projectId
+ * @returns {{ totalUsd:number, byPlan:Array<{planId:string,totalUsd:number,huCount:number}>, unknownModelTokens:object, currency:string } | null}
+ */
+export function getProjectCost(projectId) {
+  const project = getDb()
+    .prepare('SELECT id FROM projects WHERE id = ?')
+    .get(projectId);
+  if (!project) return null;
+
+  const rows = getDb()
+    .prepare(
+      `SELECT plan_id, cost_usd FROM stories
+       WHERE project_id = ? AND cost_usd IS NOT NULL`
+    )
+    .all(projectId);
+
+  const round4 = (n) => Math.round(n * 10000) / 10000;
+  const byPlanMap = new Map();
+  let totalUsd = 0;
+  for (const r of rows) {
+    const planId = r.plan_id || 'unassigned';
+    const cost = Number(r.cost_usd);
+    if (!Number.isFinite(cost)) continue;
+    totalUsd += cost;
+    const cur = byPlanMap.get(planId) || { planId, totalUsd: 0, huCount: 0 };
+    cur.totalUsd += cost;
+    cur.huCount += 1;
+    byPlanMap.set(planId, cur);
+  }
+
+  const byPlan = Array.from(byPlanMap.values())
+    .map((p) => ({ planId: p.planId, totalUsd: round4(p.totalUsd), huCount: p.huCount }))
+    .sort((a, b) => b.totalUsd - a.totalUsd);
+
+  return {
+    totalUsd: round4(totalUsd),
+    byPlan,
+    unknownModelTokens: { tokensIn: 0, tokensOut: 0, models: [] },
+    currency: 'USD',
+  };
+}
+
 /**
  * Returns full story detail including context requests.
  * @param {string} storyId

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

@@ -60,6 +60,85 @@ export function shortTask(text, max = MAX_TASK_CHARS) {
  *           created_at?: string|null }} session
  * @returns {{ title: string, subtitle: string, idChip: string }}
  */
+/**
+ * Format a per-HU cost (USD) for the card badge. Cost F (KJC-TSK-0517).
+ *
+ * Two outputs in one call so the UI can render both at once:
+ *   - `label`: 2-decimal "$X.XX" shown on the card (compact).
+ *   - `tooltip`: 4-decimal "Estimated cost: $X.XXXX" shown on hover
+ *     (matches the precision aggregated by Cost B/C/D, see
+ *     `packages/core/src/cost/index.js`).
+ *
+ * Returns `null` for null/undefined/non-finite inputs so the caller
+ * skips the badge entirely (rendering "$0.00" for an unknown cost
+ * would be misleading — there is a real difference between "we know it
+ * was free" and "we haven't measured it yet").
+ *
+ * @param {number|null|undefined} costUsd
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatCost(costUsd) {
+  if (costUsd === null || costUsd === undefined) return null;
+  const n = Number(costUsd);
+  if (!Number.isFinite(n)) return null;
+  return {
+    label: `$${n.toFixed(2)}`,
+    tooltip: `Estimated cost: $${n.toFixed(4)}`,
+  };
+}
+
+/**
+ * Format the aggregated project-level cost chip rendered in the board
+ * header. Cost G (KJC-TSK-0518). Consumes the shape returned by
+ * `GET /api/projects/:id/cost` (Cost E):
+ *   { totalUsd, byPlan: [{planId, totalUsd, huCount}, …],
+ *     unknownModelTokens: { tokensIn, tokensOut, models }, currency }
+ *
+ * Returns `{ label, tooltip }` where:
+ *   - `label` is the compact "Total: $X.XX" shown in the header.
+ *   - `tooltip` is a multi-line string with full precision, the
+ *     per-plan breakdown, and a note when some tokens used a model we
+ *     don't price (they aren't included in the total — surfacing the
+ *     skip is more honest than silently swallowing it).
+ *
+ * Returns `null` when there is nothing to show (no input, or no
+ * measured cost yet and no plans). The chip is then hidden — same
+ * reasoning as `formatCost`: "$0.00" with no data is misleading.
+ *
+ * @param {{totalUsd:number, byPlan?:Array, unknownModelTokens?:object}|null|undefined} cost
+ * @returns {{ label: string, tooltip: string } | null}
+ */
+export function formatProjectCostSummary(cost) {
+  if (!cost || typeof cost !== "object") return null;
+  const total = Number(cost.totalUsd);
+  if (!Number.isFinite(total)) return null;
+  const byPlan = Array.isArray(cost.byPlan) ? cost.byPlan : [];
+  if (total === 0 && byPlan.length === 0) return null;
+
+  const lines = [`Total: $${total.toFixed(4)}`];
+  if (byPlan.length > 0) {
+    lines.push("By plan:");
+    for (const p of byPlan) {
+      const planTotal = Number(p?.totalUsd);
+      if (!Number.isFinite(planTotal)) continue;
+      const huCount = Number.isFinite(p?.huCount) ? p.huCount : 0;
+      const planLabel = p?.planId || "unassigned";
+      lines.push(`  ${planLabel}: $${planTotal.toFixed(2)} (${huCount} HU${huCount === 1 ? "" : "s"})`);
+    }
+  }
+  const unk = cost.unknownModelTokens;
+  if (unk && Number.isFinite(unk.tokensIn) && Number.isFinite(unk.tokensOut)) {
+    const unkTotal = unk.tokensIn + unk.tokensOut;
+    if (unkTotal > 0) {
+      lines.push(`(${unkTotal} tokens with unknown pricing not included)`);
+    }
+  }
+  return {
+    label: `Total: $${total.toFixed(2)}`,
+    tooltip: lines.join("\n"),
+  };
+}
+
 export function formatSessionLabel(session) {
   if (!session || !session.id) {
     return { title: "(no session)", subtitle: "", idChip: "" };

package/packages/hu-board/src/plan-mutations.js

@@ -17,13 +17,13 @@
 import { readFileSync, existsSync, readdirSync, mkdirSync, openSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { writeJsonAtomicSync } from '../../../src/utils/atomic-write.js';
+import { writeJsonAtomicSync } from '@karajan/core/atomic-write';
 import { spawn } from 'node:child_process';
 import { trackRun, untrack } from './run-tracker.js';
 import { getHuBoardRunsDir } from './db.js';
 import { fileURLToPath } from 'node:url';
-import { updateHuStatus, certifyAllHus, updateHu } from '../../../src/plan/plan-hu-ops.js';
-import { validateBlockedByChange } from '../../../src/plan/plan-validation.js';
+import { updateHuStatus, certifyAllHus, updateHu } from '@karajan/core/plan-hu-ops';
+import { validateBlockedByChange } from '@karajan/core/plan-validation';
 import { syncPlanFile } from './sync.js';
 import { getDb } from './db.js';
 
@@ -230,7 +230,7 @@ export async function revertHuFromSnapshot({ planId, huId, projectId }) {
   const projectDir = plan.projectDir;
   if (!projectDir) return { ok: false, error: 'plan sin projectDir' };
 
-  const { restoreHuSnapshot } = await import('../../../src/git/hu-snapshot.js');
+  const { restoreHuSnapshot } = await import('@karajan/core/hu-snapshot');
   const restore = await restoreHuSnapshot({ projectDir, huId });
   if (!restore.ok) return { ok: false, error: `restore falló: ${restore.error}` };