karajan-code 4.70.4 → 5.0.1

package/packages/hu-board/src/command-runner.js

@@ -1,9 +1,7 @@
 /**
  * Generic Karajan-CLI launcher used by the board's "Commands" panel.
- * Wraps the same spawn-detached-with-log pattern that `runPlan`
- * already uses (see plan-mutations.js), but covers the broader set
- * of commands the user wants to trigger from the UI: plan,
- * architect, clean, etc.
+ * Spawns a whitelisted `kj` command detached, with its output in a
+ * log the board can tail. Today the whitelist holds `clean`.
  *
  * Security: the command name is matched against an explicit
  * whitelist. Free-form arg arrays are NOT allowed — each command
@@ -16,8 +14,8 @@
  * planId, in routes/api.js).
  */
 
-import { mkdirSync, openSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { existsSync, mkdirSync, openSync, readdirSync } from "node:fs";
+import { join, dirname, isAbsolute } from "node:path";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { randomUUID } from "node:crypto";
@@ -36,7 +34,7 @@ import { getHuBoardRunsDir } from "./db.js";
 
 /**
  * Whitelist + argv builders. Each entry maps a logical command name
- * (`plan`, `architect`, `clean`) to a function that turns the
+ * (e.g. `clean`) to a function that turns the
  * board-side input into a CLI argv. Adding a new command means: add
  * an entry here and an entry in the board UI's `COMMANDS` table.
  *
@@ -47,25 +45,9 @@ import { getHuBoardRunsDir } from "./db.js";
  * Each builder returns `{ args, projectDir? }`. `projectDir` is the
  * cwd the spawn should use (defaults to the board's cwd).
  */
+// KJC-TSK-1323: `plan` (generate) and `architect` left with 5.0, which retired them;
+// a request for either now gets the 400 of any command outside the whitelist.
 const COMMAND_BUILDERS = {
-  plan: (input) => {
-    const args = ["plan"];
-    if (input.taskFile) args.push("--task-file", String(input.taskFile));
-    if (input.context) args.push("--context", String(input.context));
-    if (input.quick) args.push("--quick");
-    if (input.noTestsSynth) args.push("--no-tests-synth");
-    if (input.noPlanReview) args.push("--no-plan-review");
-    // Positional task goes last when no --task-file was given.
-    if (!input.taskFile && input.task) args.push(String(input.task));
-    return { args, projectDir: input.projectDir };
-  },
-  architect: (input) => {
-    const args = ["architect"];
-    if (input.taskFile) args.push("--task-file", String(input.taskFile));
-    if (input.context) args.push("--context", String(input.context));
-    if (!input.taskFile && input.task) args.push(String(input.task));
-    return { args, projectDir: input.projectDir };
-  },
   clean: (input) => {
     const args = ["clean", "--yes"];      // never prompt; UI confirms ahead
     if (input.nuke) args.push("--nuke");
@@ -101,6 +83,11 @@ export function runKjCommand({ command, input = {} } = {}) {
     return { ok: false, error: `Bad input for "${command}": ${err.message}` };
   }
 
+  return spawnKj(command, built);
+}
+
+/** Spawn `kj <args>` detached, its output in a run log the board can tail. */
+function spawnKj(command, built) {
   const dir = getHuBoardRunsDir();
   mkdirSync(dir, { recursive: true });
   const commandId = `cmd-${command}-${Date.now()}-${randomUUID().slice(0, 8)}`;
@@ -127,6 +114,30 @@ export function runKjCommand({ command, input = {} } = {}) {
   return { ok: true, commandId, pid: child.pid ?? 0, logPath };
 }
 
+const CARD_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+/**
+ * KJC-TSK-1324: the ▶ of a card. `kj hu start <id> --code` checks the card, opens its lane
+ * and has the panel coder write it there; review and commit stay with the person. Only a card
+ * id and an absolute git checkout get through, never a free-form argument.
+ */
+export function startCardInLane({ id, projectDir } = {}) {
+  if (!CARD_ID.test(String(id ?? ""))) return { ok: false, error: `not a card id: ${id}` };
+  if (!isAbsolute(String(projectDir ?? "")) || !existsSync(join(projectDir, ".git"))) {
+    return { ok: false, error: `not a git checkout: ${projectDir}` };
+  }
+  const lane = laneOfCard({ id, projectDir });
+  if (lane) return { ok: false, lane, error: `${id} already has a lane: ${lane}` };
+  return spawnKj("hu-start", { args: ["hu", "start", id, "--code"], projectDir });
+}
+
+/** The lane a card already has (kj names it <id>-<slug>), or null. */
+export function laneOfCard({ id, projectDir }) {
+  const lanes = join(projectDir, ".kj", "worktrees");
+  const found = existsSync(lanes) ? readdirSync(lanes).find((name) => name.startsWith(`${id}-`)) : null;
+  return found ? join(lanes, found) : null;
+}
+
 /** Test helper: list of command names exposed. */
 export function listSupportedCommands() {
   return Object.keys(COMMAND_BUILDERS);

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

@@ -0,0 +1,282 @@
+// KJC-TSK-0542: the board's SQLite connection, its schema and migrations. Other modules reach the
+// handle through getDb(); db.js re-exports these functions, so callers keep importing from there.
+// KJC-TSK-0617 (SQL-C): the handle is karajan-core's better-sqlite3-compatible adapter over
+// node:sqlite, built into Node: no native addon to compile.
+import { openDatabase } from 'karajan-core/db';
+import { join } from 'node:path';
+import { mkdirSync, renameSync } from 'node:fs';
+
+import { getKjHome } from './db-paths.js';
+
+/** @type {ReturnType<typeof openDatabase> | null} */
+let db = null;
+
+// Bump when the schema gains a column / index / table that older
+// Karajan versions cannot understand. A DB written by a newer Karajan
+// refuses to open here so it does not get silently downgraded.
+const SCHEMA_VERSION = 1;
+
+/**
+ * Tries to open the SQLite database; if it is corrupt, moves it aside
+ * and opens a fresh one. `fullScan` afterwards rebuilds the cache from
+ * the JSON files on disk — the DB is a cache, never the source of
+ * truth. Without this the board crashed at startup with a raw
+ * `SqliteError: database disk image is malformed` whenever the WAL
+ * checkpoint died in the wrong place.
+ *
+ * @param {string} dbPath
+ * @returns {ReturnType<typeof openDatabase>}
+ */
+function openDbResilient(dbPath) {
+  let handle = null;
+  try {
+    handle = openDatabase(dbPath);
+    // SQLite reads the file header on the first statement, which is what
+    // surfaces "file is not a database". Probe `schema_version` (a built-in
+    // SQLite pragma) to force it.
+    handle.pragma("schema_version", { simple: true });
+    return handle;
+  } catch (err) {
+    const code = err?.code || "";
+    const msg = err?.message || "";
+    if (code === "SQLITE_CORRUPT" || code === "SQLITE_NOTADB" || /malformed|not a database/i.test(msg)) {
+      try { handle?.close(); } catch { /* already unusable */ }
+      const aside = `${dbPath}.corrupt-${Date.now()}`;
+      try { renameSync(dbPath, aside); } catch { /* may already be gone */ }
+      // eslint-disable-next-line no-console
+      console.warn(`[hu-board] DB at ${dbPath} was corrupt; moved aside to ${aside}. Rebuilding from disk via fullScan.`);
+      return openDatabase(dbPath);
+    }
+    throw err;
+  }
+}
+
+/**
+ * Initializes the SQLite database and creates tables if they don't exist.
+ * @returns {ReturnType<typeof openDatabase>}
+ */
+export function initDb() {
+  const kjHome = getKjHome();
+  mkdirSync(kjHome, { recursive: true });
+
+  const dbPath = join(kjHome, 'hu-board.db');
+  db = openDbResilient(dbPath);
+
+  db.pragma('journal_mode = WAL');
+  db.pragma('foreign_keys = ON');
+  // Wait up to 5s for a competing writer (e.g. concurrent fullScan +
+  // mutation) before giving up. Without this any contention surfaced
+  // as SQLITE_BUSY and crashed the request mid-flight.
+  db.pragma('busy_timeout = 5000');
+
+  // Schema-version guard. If the DB was written by a newer Karajan with
+  // a different schema, refuse to open instead of silently mis-binding
+  // named parameters against a renamed column.
+  const onDisk = db.pragma('user_version', { simple: true });
+  if (onDisk > SCHEMA_VERSION) {
+    throw new Error(
+      `[hu-board] DB schema is from a newer Karajan (user_version=${onDisk}, this build expects ${SCHEMA_VERSION}). `
+      + `Upgrade karajan-code or remove ${dbPath} (it will be rebuilt from disk).`
+    );
+  }
+  if (onDisk < SCHEMA_VERSION) {
+    db.pragma(`user_version = ${SCHEMA_VERSION}`);
+  }
+
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS projects (
+      id TEXT PRIMARY KEY,
+      name TEXT,
+      first_seen TEXT,
+      last_activity TEXT,
+      total_stories INTEGER DEFAULT 0
+    );
+
+    CREATE TABLE IF NOT EXISTS stories (
+      id TEXT PRIMARY KEY,
+      project_id TEXT,
+      session_id TEXT,
+      status TEXT DEFAULT 'pending',
+      title TEXT,
+      original_text TEXT,
+      certified_as TEXT,
+      certified_want TEXT,
+      certified_so_that TEXT,
+      quality_total INTEGER,
+      quality_d1 INTEGER,
+      quality_d2 INTEGER,
+      quality_d3 INTEGER,
+      quality_d4 INTEGER,
+      quality_d5 INTEGER,
+      quality_d6 INTEGER,
+      antipatterns TEXT,
+      ac_format TEXT,
+      acceptance_criteria TEXT,
+      created_at TEXT,
+      updated_at TEXT,
+      certified_at TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS sessions (
+      id TEXT PRIMARY KEY,
+      project_id TEXT,
+      task TEXT,
+      status TEXT,
+      created_at TEXT,
+      updated_at TEXT,
+      iterations INTEGER DEFAULT 0,
+      duration_ms INTEGER,
+      approved INTEGER DEFAULT 0,
+      commits TEXT,
+      stages_completed TEXT,
+      checkpoints TEXT,
+      llm_calls TEXT,
+      config_snapshot TEXT,
+      budget TEXT
+    );
+
+    CREATE TABLE IF NOT EXISTS context_requests (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      story_id TEXT,
+      fields_needed TEXT,
+      question TEXT,
+      answer TEXT,
+      requested_at TEXT,
+      answered_at TEXT
+    );
+
+    -- KJC-TSK-0380 — Tombstones: "deleted, do not resurrect".
+    -- The board's data is reconstructed from the filesystem on every
+    -- fullScan(), so a plain DELETE from the table is silently undone
+    -- the next time chokidar fires. The tombstone table holds the ids
+    -- the user explicitly killed; sync* functions check it before any
+    -- upsert and skip + clean fs paths.
+    CREATE TABLE IF NOT EXISTS tombstones (
+      resource_type TEXT NOT NULL,
+      resource_id   TEXT NOT NULL,
+      deleted_at    TEXT NOT NULL,
+      source        TEXT NOT NULL,
+      fs_paths      TEXT,
+      PRIMARY KEY (resource_type, resource_id)
+    );
+
+    CREATE INDEX IF NOT EXISTS idx_stories_project ON stories(project_id);
+    CREATE INDEX IF NOT EXISTS idx_stories_status ON stories(status);
+    CREATE INDEX IF NOT EXISTS idx_sessions_project ON sessions(project_id);
+    CREATE INDEX IF NOT EXISTS idx_context_story ON context_requests(story_id);
+    CREATE INDEX IF NOT EXISTS idx_tombstones_deleted_at ON tombstones(deleted_at);
+  `);
+
+  // --- Migrations ---
+  // Each ALTER is idempotent on restart — we swallow the duplicate-column
+  // error so adding one over time doesn't force a board DB nuke.
+  //
+  // plan_id:       lets the mutation endpoints locate the source-of-truth plan
+  //                JSON at ~/.karajan/plans/<slug>/<planId>.json without a scan.
+  // ac_count:      number of acceptance criteria, surfaced on the card.
+  // test_count:    number of acceptance_tests, surfaced on the card.
+  // blocked_by:    denormalised JSON array of HU ids this story waits on,
+  //                so the card can render `⏳ waits for: lao-001` inline.
+  try { db.exec('ALTER TABLE stories ADD COLUMN plan_id TEXT'); } catch { /* already migrated */ }
+  try { db.exec('ALTER TABLE stories ADD COLUMN ac_count INTEGER'); } catch { /* already migrated */ }
+  try { db.exec('ALTER TABLE stories ADD COLUMN test_count INTEGER'); } catch { /* already migrated */ }
+  try { db.exec('ALTER TABLE stories ADD COLUMN blocked_by TEXT'); } catch { /* already migrated */ }
+  // acceptance_tests is the raw JSON of `hu.acceptance_tests` — the
+  // plan stores each test as either a plain string or an object with
+  // { name, description, given/when/then, ... }. The modal renders
+  // the list; the card just shows the count (test_count above).
+  try { db.exec('ALTER TABLE stories ADD COLUMN acceptance_tests TEXT'); } catch { /* already migrated */ }
+  // plan_order is the index of the HU in `plan.hus[]` as the planner
+  // emitted it. The planner's output is already topological (it calls
+  // addHu with `blocked_by: [prevId]`), so sorting the board by this
+  // column puts roots first and dependents last — matching what
+  // `kj run --plan` will actually execute.
+  try { db.exec('ALTER TABLE stories ADD COLUMN plan_order INTEGER'); } catch { /* already migrated */ }
+  // spec_section (v2.7.5 PR C): the SPEC.md heading this HU
+  // implements (e.g. "5.3" or "§5 Initial Scope"). Surfaces in the
+  // card + modal so the user can trace HU → spec coverage.
+  try { db.exec('ALTER TABLE stories ADD COLUMN spec_section TEXT'); } catch { /* already migrated */ }
+  // outcome (PR3): JSON blob with what actually happened during
+  // execution — iterations, duration, commits, branch, blockers,
+  // human summary. Stamped by hu-sub-pipeline at the end of each
+  // HU and ingested by syncPlanFile so the board can show the 📄
+  // indicator and detail modal without parsing the plan JSON
+  // again. Stored as TEXT (JSON.stringify'd) for simplicity —
+  // parsed on read by the UI.
+  try { db.exec('ALTER TABLE stories ADD COLUMN outcome TEXT'); } catch { /* already migrated */ }
+  // KJC-TSK-0394: result (pass | fail | partial | null) ortogonal al status.
+  // Diferente del campo `outcome` arriba (que es blob JSON con metadata del
+  // run). result es el enum de "último resultado" para mostrar como badge.
+  try { db.exec('ALTER TABLE stories ADD COLUMN result TEXT'); } catch { /* already migrated */ }
+  // KJC-TSK-0406: coder_model y reviewer_model independientes por HU.
+  // Asignados por el triage según complexity (KJC-TSK-0405) y override-able
+  // desde el modal del board. coder_provider y reviewer_provider permiten
+  // cross-provider review (claude↔codex) sin tocar el config global.
+  try { db.exec('ALTER TABLE stories ADD COLUMN coder_model TEXT'); } catch { /* already migrated */ }
+  try { db.exec('ALTER TABLE stories ADD COLUMN reviewer_model TEXT'); } catch { /* already migrated */ }
+  try { db.exec('ALTER TABLE stories ADD COLUMN coder_provider TEXT'); } catch { /* already migrated */ }
+  try { db.exec('ALTER TABLE stories ADD COLUMN reviewer_provider TEXT'); } catch { /* already migrated */ }
+  // KJC-PRP-0002 PR6: free-form handle of the human (or dev_XXX AI) who
+  // owns this HU on a team-shared board. NULL = unassigned. Only surfaced
+  // in the UI when the parent project is `is_shared = 1`, but stored
+  // 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 */ }
+  // KJC-TSK-0525 (Φ0-G): persisted cached/input tokens per HU so the
+  // board can render the "🎯 N% cached" badge without re-parsing the
+  // session summary. NULL = unmeasured (older runs, cold runs without
+  // cache support). INTEGER because providers report token counts as
+  // ints. Ratio is computed at read time as cached_tokens / tokens_in.
+  try { db.exec('ALTER TABLE stories ADD COLUMN cached_tokens INTEGER'); } catch { /* already migrated */ }
+  try { db.exec('ALTER TABLE stories ADD COLUMN tokens_in INTEGER'); } 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
+  // controls the ephemeral-cleanup heuristic. NULL = follow heuristic
+  // (id under tmp_/test_/demo_/kj-test- → ephemeral after 24h);
+  // 1 = always treat as ephemeral; 0 = NEVER auto-clean (user override).
+  // The UI surfaces this as a toggle on each project card.
+  try { db.exec('ALTER TABLE projects ADD COLUMN is_test INTEGER'); } catch { /* already migrated */ }
+
+  // is_shared (KJC-PRP-0002 PR3): 1 when at least one plan of the project came
+  // from `<projectDir>/.karajan-shared/plans/`. Surfaced as a 🔗 badge on the
+  // board so the user can tell at a glance which projects are team-tracked.
+  try { db.exec('ALTER TABLE projects ADD COLUMN is_shared INTEGER'); } catch { /* already migrated */ }
+
+  return db;
+}
+
+/**
+ * Returns the current database instance.
+ * @returns {ReturnType<typeof openDatabase>}
+ */
+export function getDb() {
+  if (!db) throw new Error('Database not initialized. Call initDb() first.');
+  return db;
+}
+
+/**
+ * Lazily initialise the DB if it isn't open yet (KJC-BUG-0090). The cost
+ * writers run from `kj run`/`kj autorun` paths that may never start the board
+ * (which is what normally calls initDb), so cost writes failed with
+ * "Database not initialized". This makes those writers self-sufficient.
+ */
+export function ensureDb() {
+  if (!db) initDb();
+  return db;
+}
+
+/**
+ * Closes the database connection.
+ */
+export function closeDb() {
+  if (db) {
+    db.close();
+    db = null;
+  }
+}

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

@@ -0,0 +1,113 @@
+// KJC-TSK-0542: where the board keeps its files (karajan home, plans, run logs).
+// Re-exported by db.js, so callers keep importing from there.
+import { join, dirname } from 'node:path';
+import { rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+
+// Per-process tmp dir for VITEST runs that forget to set KJ_HOME.
+// Without this, a test that touches initDb() / upsertProject() drops
+// rows into the developer's real `~/.karajan/hu-board.db` and the
+// running board UI shows phantom projects (observed: "sess-1",
+// "default", "Karajan Code" with 49 test fixture plans). Memoise so
+// every consumer in the same process agrees on the path. The
+// trailing `.karajan` segment keeps semantic parity with non-VITEST
+// defaults so any caller assuming the path ends in `.karajan` still
+// works.
+let _vitestKjHome = null;
+function vitestTmpKjHome() {
+  if (_vitestKjHome) return _vitestKjHome;
+  _vitestKjHome = join(
+    tmpdir(),
+    `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;
+}
+
+/**
+ * Returns the KJ home directory, respecting KJ_HOME env var.
+ * Under VITEST without KJ_HOME, returns a per-process tmp dir to
+ * prevent accidental writes into the developer's real `~/.karajan/`.
+ * @returns {string}
+ */
+export function getKjHome() {
+  // KJC-TSK-0420: same precedence chain as src/utils/paths.js::resolveHome():
+  // KARAJAN_HOME (canonical) > KJ_HOME (legacy) > VITEST tmp > ~/.karajan.
+  // Kept inline rather than cross-workspace imported so the hu-board package
+  // does not gain a new src/ dep; the precedence behaviour is the same.
+  if (process.env.KARAJAN_HOME) return process.env.KARAJAN_HOME;
+  if (process.env.KJ_HOME) return process.env.KJ_HOME;
+  if (process.env.VITEST) return vitestTmpKjHome();
+  return join(process.env.HOME || '/root', '.karajan');
+}
+
+/**
+ * Canonical path to the HU Board's run-logs directory
+ * (`<karajan-home>/hu-board-runs/`). Centralised here so the four
+ * board callers (plan-mutations, command-runner, api.js GET routes
+ * for plan + commandId logs) and the garbage-collector all agree on
+ * the same string — KJC-TSK-0421.
+ *
+ * @returns {string}
+ */
+export function getHuBoardRunsDir() {
+  return join(getKjHome(), 'hu-board-runs');
+}
+
+/**
+ * Canonical path to the plans directory the board scans
+ * (`<karajan-home>/plans/`). Respects `KJ_PLANS_DIR` as an absolute
+ * override, mirroring sync.js. KJC-BUG-0059 (v2.19.3): preflight
+ * endpoint used a hard-coded `~/.kj/plans/` legacy fallback that
+ * survived the v2.19.0 consolidation, causing the board to report
+ * "directorio del proyecto: no detectado" even when the plan on disk
+ * had a valid `projectDir`.
+ *
+ * @returns {string}
+ */
+export function getHuBoardPlansDir() {
+  return process.env.KJ_PLANS_DIR || join(getKjHome(), 'plans');
+}
+
+/**
+ * Legacy `~/.kj/plans/` directory — only returned when KJ_PLANS_DIR
+ * is unset (it would be the same path anyway when overridden).
+ * Callers iterate canonical + legacy so users who have not yet run
+ * the v2.19.0 auto-migrator still see their plans. KJC-BUG-0059.
+ *
+ * @returns {string|null}
+ */
+export function getHuBoardLegacyPlansDir() {
+  if (process.env.KJ_PLANS_DIR) return null;
+  return join(process.env.HOME || '/root', '.kj', 'plans');
+}
+
+/**
+ * Ordered list of every plans root the board should scan: canonical
+ * first (`~/.karajan/plans/`), legacy second when applicable
+ * (`~/.kj/plans/`). Honours `KJ_PLANS_DIR` as a single override,
+ * matching `sync.js`'s fullScan / startWatcher precedence so the
+ * preflight, plans-outcome, delete-project and delete-plan endpoints
+ * see the same set of files the watcher sees. KJC-BUG-0059.
+ *
+ * @returns {string[]}
+ */
+export function getHuBoardPlansDirs() {
+  const dirs = [getHuBoardPlansDir()];
+  const legacy = getHuBoardLegacyPlansDir();
+  if (legacy) dirs.push(legacy);
+  return dirs;
+}

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

@@ -0,0 +1,188 @@
+// KJC-TSK-0542: the read side of the board DB (projects, stories, sessions, cost, dashboard),
+// re-exported by db.js.
+import { getDb } from './db-connection.js';
+
+/**
+ * Returns all projects with aggregated stats.
+ * @returns {Array<object>}
+ */
+export function getProjects() {
+  return getDb().prepare(`
+    SELECT p.*,
+      (SELECT COUNT(*) FROM stories s WHERE s.project_id = p.id) AS story_count,
+      (SELECT COUNT(*) FROM stories s WHERE s.project_id = p.id AND s.status = 'certified') AS certified_count,
+      (SELECT COUNT(*) FROM stories s WHERE s.project_id = p.id AND s.status = 'pending') AS pending_count,
+      (SELECT COUNT(*) FROM sessions ss WHERE ss.project_id = p.id) AS session_count
+    FROM projects p
+    ORDER BY p.last_activity DESC
+  `).all();
+}
+
+/**
+ * Returns stories for a specific project.
+ * @param {string} projectId
+ * @returns {Array<object>}
+ */
+/**
+ * Fetch all stories of a project ordered by plan_order ASC (roots first,
+ * dependents last — matches what `kj run --plan` will actually execute)
+ * and falling back to updated_at DESC for legacy rows that never had
+ * plan_order stamped.
+ */
+export function getStoriesByProject(projectId) {
+  return getDb().prepare(`
+    SELECT * FROM stories WHERE project_id = ?
+    ORDER BY plan_order IS NULL, plan_order ASC, updated_at DESC
+  `).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;
+
+  // Φ0-G: cached_tokens / tokens_in are nullable independently of
+  // cost_usd, so we read all three columns but keep cost as the
+  // primary filter (a row with only cache telemetry but no $ should
+  // not appear in the per-plan totals — cost rules the byPlan list).
+  const rows = getDb()
+    .prepare(
+      `SELECT plan_id, cost_usd, cached_tokens, tokens_in 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;
+  let totalCached = 0;
+  let totalTokensIn = 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 cached = Number(r.cached_tokens);
+    const tin = Number(r.tokens_in);
+    if (Number.isFinite(cached) && cached >= 0) totalCached += cached;
+    if (Number.isFinite(tin) && tin >= 0) totalTokensIn += tin;
+    const cur = byPlanMap.get(planId) || { planId, totalUsd: 0, huCount: 0, cachedTokens: 0, tokensIn: 0 };
+    cur.totalUsd += cost;
+    cur.huCount += 1;
+    if (Number.isFinite(cached) && cached >= 0) cur.cachedTokens += cached;
+    if (Number.isFinite(tin) && tin >= 0) cur.tokensIn += tin;
+    byPlanMap.set(planId, cur);
+  }
+
+  const ratio = (cached, tin) => tin > 0 ? Math.round((cached / tin) * 1000) / 10 : null;
+  const byPlan = Array.from(byPlanMap.values())
+    .map((p) => ({
+      planId: p.planId,
+      totalUsd: round4(p.totalUsd),
+      huCount: p.huCount,
+      cachedTokens: p.cachedTokens,
+      tokensIn: p.tokensIn,
+      cachedRatioPct: ratio(p.cachedTokens, p.tokensIn),
+    }))
+    .sort((a, b) => b.totalUsd - a.totalUsd);
+
+  return {
+    totalUsd: round4(totalUsd),
+    byPlan,
+    cachedTokens: totalCached,
+    tokensIn: totalTokensIn,
+    cachedRatioPct: ratio(totalCached, totalTokensIn),
+    unknownModelTokens: { tokensIn: 0, tokensOut: 0, models: [] },
+    currency: 'USD',
+  };
+}
+
+/**
+ * Returns full story detail including context requests.
+ * @param {string} storyId
+ * @returns {object | null}
+ */
+export function getStoryDetail(storyId) {
+  const story = getDb().prepare('SELECT * FROM stories WHERE id = ?').get(storyId);
+  if (!story) return null;
+
+  const contextRequests = getDb().prepare(
+    'SELECT * FROM context_requests WHERE story_id = ? ORDER BY requested_at DESC'
+  ).all(storyId);
+
+  return { ...story, context_requests: contextRequests };
+}
+
+/**
+ * Returns sessions for a specific project.
+ *
+ * The `project_name` column is joined in so the UI can show a human
+ * label like `tmp_kj-test-4 · trivial(doc) · 08:35` instead of just
+ * the cryptic `s_2026-05-07T...` id.
+ *
+ * @param {string} projectId
+ * @returns {Array<object>}
+ */
+export function getSessionsByProject(projectId) {
+  return getDb().prepare(`
+    SELECT s.id, s.project_id, s.task, s.status, s.created_at, s.updated_at,
+           s.iterations, s.duration_ms, s.approved, s.stages_completed,
+           p.name AS project_name
+    FROM sessions s
+    LEFT JOIN projects p ON p.id = s.project_id
+    WHERE s.project_id = ?
+    ORDER BY s.created_at DESC
+  `).all(projectId);
+}
+
+/**
+ * Returns full session detail (with the joined project_name).
+ * @param {string} sessionId
+ * @returns {object | null}
+ */
+export function getSessionDetail(sessionId) {
+  return getDb().prepare(`
+    SELECT s.*, p.name AS project_name
+    FROM sessions s
+    LEFT JOIN projects p ON p.id = s.project_id
+    WHERE s.id = ?
+  `).get(sessionId);
+}
+
+/**
+ * Returns global dashboard statistics.
+ * @returns {object}
+ */
+export function getDashboardStats() {
+  const db = getDb();
+  const totalStories = db.prepare('SELECT COUNT(*) AS count FROM stories').get().count;
+  const certifiedStories = db.prepare("SELECT COUNT(*) AS count FROM stories WHERE status = 'certified'").get().count;
+  const pendingStories = db.prepare("SELECT COUNT(*) AS count FROM stories WHERE status = 'pending'").get().count;
+  const doneStories = db.prepare("SELECT COUNT(*) AS count FROM stories WHERE status = 'done'").get().count;
+  const needsContextStories = db.prepare("SELECT COUNT(*) AS count FROM stories WHERE status = 'needs_context'").get().count;
+  const avgQuality = db.prepare('SELECT AVG(quality_total) AS avg FROM stories WHERE quality_total IS NOT NULL').get().avg;
+  const totalSessions = db.prepare('SELECT COUNT(*) AS count FROM sessions').get().count;
+  const approvedSessions = db.prepare('SELECT COUNT(*) AS count FROM sessions WHERE approved = 1').get().count;
+  const totalProjects = db.prepare('SELECT COUNT(*) AS count FROM projects').get().count;
+
+  return {
+    total_stories: totalStories,
+    certified_stories: certifiedStories,
+    pending_stories: pendingStories,
+    done_stories: doneStories,
+    needs_context_stories: needsContextStories,
+    avg_quality: avgQuality ? Math.round(avgQuality * 10) / 10 : null,
+    total_sessions: totalSessions,
+    approved_sessions: approvedSessions,
+    total_projects: totalProjects,
+  };
+}