karajan-code 2.18.1 → 2.19.1

package/packages/hu-board/src/ephemeral-cleaner.js

@@ -0,0 +1,198 @@
+/**
+ * Ephemeral project cleaner for the HU Board (board-polish #3,
+ * KJC-TSK-0371 — dogfooding 2026-05-07).
+ *
+ * Why this exists
+ * ===============
+ *
+ * Every `kj run` against a throwaway directory (`/tmp/kj-test-1`,
+ * `/tmp/demo-foo`, ad-hoc scratch projects under `tmp_*`) produces
+ * a board project that hangs around forever, even after the user
+ * has long since rm-rf'd the source tree. After 12 days of
+ * dogfooding the board ended up with 30+ "kj-test-N" projects
+ * the user couldn't tell apart from real ones — exactly the
+ * "noise on the demo" risk the user flagged on 2026-05-07.
+ *
+ * Heuristic (per the user's spec on the same session, "solución
+ * c — heurística + flag visible"):
+ *
+ *   1. Project is ephemeral when:
+ *        a) `is_test = 1` (user explicitly marked it test), OR
+ *        b) project id matches /^(tmp_|test_|demo_|kj-test-)/i
+ *           AND `is_test IS NULL` (no override).
+ *   2. AND last_activity is older than `ttlHours` (default 24h).
+ *
+ *   3. Override: when `is_test = 0` (user clicked "keep it"), the
+ *      project is NEVER deleted, even if the heuristic would match.
+ *
+ * What "cleanup" means: DELETE the project row + cascade-delete its
+ * stories and sessions, ADD a project tombstone, and rm-rf the
+ * on-disk dirs (`hu-stories/<sid>/`, `sessions/<sid>/`,
+ * `~/.kj/plans/<projectId>/`). Without the tombstone + fs cleanup,
+ * the very next chokidar `add` event or `fullScan` would re-import
+ * those files as a brand-new project (KJC-BUG-0055).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { homedir } from "node:os";
+import { addTombstone, getKjHome } from "./db.js";
+
+const DEFAULT_TTL_HOURS = 24;
+const EPHEMERAL_ID_PATTERNS = [
+  /^tmp_/i,
+  /^test_/i,
+  /^demo_/i,
+  /^kj-test-/i,
+  /^auto-tmp_/i,    // also covers auto-batch projects derived from /tmp/
+  /^auto-test_/i,
+  /^auto-demo_/i,
+  // KJC-TSK-0377: stray session/plan-prefixed projects accumulate during
+  // dogfooding when a kj run is invoked without a proper projectDir.
+  // The HU Board's sync_*File handlers create a placeholder project row
+  // with `id = session_id` or `id = plan_id`, which after 24h of
+  // inactivity is the same kind of zombi the other patterns target.
+  /^s_/i,
+  /^plan-/i,
+];
+
+/**
+ * Decide whether a single project row qualifies as an ephemeral
+ * candidate ready for deletion at `now`. Pure function — no I/O.
+ *
+ * The matrix:
+ *   is_test = 1         → ephemeral (user marked it)
+ *   is_test = 0         → not ephemeral, EVER (user override wins)
+ *   is_test = NULL/und. → fall back to id-pattern heuristic
+ *   too recent          → not ephemeral (still in use)
+ *
+ * @param {{ id: string, last_activity?: string|null, first_seen?: string|null,
+ *           is_test?: number|null }} project
+ * @param {{ now: number, ttlHours: number }} ctx
+ * @returns {{ ephemeral: boolean, reason?: string }}
+ */
+export function classifyEphemeral(project, ctx) {
+  if (!project || !project.id) return { ephemeral: false };
+  // Explicit user override always wins. is_test=0 means "keep it".
+  if (project.is_test === 0) return { ephemeral: false };
+
+  const idMatch = EPHEMERAL_ID_PATTERNS.some((re) => re.test(project.id));
+  const explicitTest = project.is_test === 1;
+  if (!idMatch && !explicitTest) return { ephemeral: false };
+
+  const refIso = project.last_activity || project.first_seen;
+  if (!refIso) return { ephemeral: false };
+  const refTs = new Date(refIso).getTime();
+  if (Number.isNaN(refTs)) return { ephemeral: false };
+  const ageHours = (ctx.now - refTs) / 3_600_000;
+  if (ageHours <= 0) return { ephemeral: false };
+  if (ageHours < ctx.ttlHours) return { ephemeral: false };
+
+  const why = explicitTest ? "is_test=1" : "id heuristic";
+  return {
+    ephemeral: true,
+    reason: `${why}, ${ageHours.toFixed(1)}h inactive (>= ${ctx.ttlHours}h)`,
+  };
+}
+
+/**
+ * Filter a list of project rows down to the ephemeral ones. Pure.
+ *
+ * @param {Array<object>} projects
+ * @param {{ now?: number, ttlHours?: number }} [opts]
+ * @returns {Array<{ project: object, reason: string }>}
+ */
+export function findEphemeralProjects(projects, opts = {}) {
+  const ctx = {
+    now: opts.now ?? Date.now(),
+    ttlHours: opts.ttlHours ?? DEFAULT_TTL_HOURS,
+  };
+  const out = [];
+  for (const project of projects || []) {
+    const verdict = classifyEphemeral(project, ctx);
+    if (verdict.ephemeral) out.push({ project, reason: verdict.reason });
+  }
+  return out;
+}
+
+/**
+ * Cascade-delete every ephemeral project at `now`. Side-effecting.
+ * Returns the list of cleaned projects so the server can log them.
+ *
+ * Idempotent: cleanup deletes the rows outright, so running twice
+ * has no effect on the second pass.
+ *
+ * @param {object} deps
+ * @param {object} deps.db        better-sqlite3 Database handle
+ * @param {object} [deps.opts]    threshold overrides
+ * @param {Function} [deps.now]   () => number, for tests
+ * @returns {Array<{ id: string, reason: string, stories_deleted: number, sessions_deleted: number }>}
+ */
+export function cleanupEphemeralProjects({
+  db,
+  opts = {},
+  now = () => Date.now(),
+  // Deps are injectable so the legacy in-memory tests (which never
+  // call `initDb()`) can pass no-op stubs and still verify the
+  // cascade-delete logic. Production callers omit them and get the
+  // real persistence + fs side-effects.
+  tombstone = (type, id, o) => {
+    try { addTombstone(type, id, o); } catch { /* DB not initialised (test) */ }
+  },
+  kjHome = () => {
+    try { return getKjHome(); } catch { return null; }
+  },
+} = {}) {
+  if (!db) return [];
+  const allProjects = db
+    .prepare("SELECT id, last_activity, first_seen, is_test FROM projects")
+    .all();
+  const candidates = findEphemeralProjects(allProjects, { ...opts, now: now() });
+  if (candidates.length === 0) return [];
+
+  const countStories = db.prepare("SELECT COUNT(*) AS n FROM stories WHERE project_id = ?");
+  const countSessions = db.prepare("SELECT COUNT(*) AS n FROM sessions WHERE project_id = ?");
+  const delStories = db.prepare("DELETE FROM stories WHERE project_id = ?");
+  const delSessions = db.prepare("DELETE FROM sessions WHERE project_id = ?");
+  const delProject = db.prepare("DELETE FROM projects WHERE id = ?");
+
+  const selStories = db.prepare("SELECT id FROM stories WHERE project_id = ?");
+  const selSessions = db.prepare("SELECT id FROM sessions WHERE project_id = ?");
+  const plansRoot = process.env.KJ_PLANS_DIR
+    || path.join(homedir(), ".kj", "plans");
+  const home = kjHome();
+  const cleaned = [];
+  for (const { project, reason } of candidates) {
+    const storyIds = selStories.all(project.id).map((r) => r.id);
+    const sessionIds = selSessions.all(project.id).map((r) => r.id);
+    const fsPaths = home
+      ? [
+          ...storyIds.map((sid) => path.join(home, "hu-stories", sid)),
+          ...sessionIds.map((sid) => path.join(home, "sessions", sid)),
+          path.join(plansRoot, project.id),
+        ]
+      : [];
+    db.transaction(() => {
+      delStories.run(project.id);
+      delSessions.run(project.id);
+      delProject.run(project.id);
+    })();
+    // Tombstone the lot + best-effort rm-rf. If the fs op fails (perm
+    // error, file in use) we still keep the tombstone — that alone is
+    // enough to stop sync.js from re-importing on the next chokidar
+    // event, and `fullScan` will retry the rm-rf at next boot.
+    tombstone("project", project.id, { source: "ephemeral-cleaner", fsPaths });
+    for (const sid of storyIds) tombstone("story", sid, { source: "ephemeral-cleaner" });
+    for (const sid of sessionIds) tombstone("session", sid, { source: "ephemeral-cleaner" });
+    for (const p of fsPaths) {
+      try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* best effort */ }
+    }
+    cleaned.push({
+      id: project.id,
+      reason,
+      stories_deleted: storyIds.length,
+      sessions_deleted: sessionIds.length,
+    });
+  }
+  return cleaned;
+}

package/packages/hu-board/src/event-bus.js

@@ -0,0 +1,58 @@
+/**
+ * Tiny pub/sub used to push sync-related events to connected SSE
+ * clients. The chokidar watcher calls `publish(event)` whenever a plan
+ * / session / batch file changes; the SSE endpoint subscribes each
+ * connected response and writes the JSON-encoded event as a message.
+ *
+ * No external dependency on purpose — `events.EventEmitter` would work
+ * but would make testing the endpoint awkward (we need deterministic
+ * subscribe/publish semantics for the integration tests in
+ * sse.test.js). The contract is:
+ *
+ *   subscribe(fn)   → returns an unsubscribe function
+ *   publish(event)  → calls every current subscriber once
+ *   subscriberCount → how many listeners are live (tests only)
+ *
+ * Events are plain JSON objects. Callers pick the shape:
+ *
+ *   { type: 'plan',    planId, projectId }   — a plan JSON was synced
+ *   { type: 'session', sessionId, projectId }— a session JSON was synced
+ *   { type: 'story',   storyId, projectId }  — a single HU row mutated
+ *
+ * The board's client treats these as hints: the usual response is to
+ * re-fetch the affected project's stories and patch the kanban in
+ * place, so no full page reload is ever required.
+ */
+
+const subscribers = new Set();
+
+/**
+ * @param {(event: object) => void} fn
+ * @returns {() => void} unsubscribe
+ */
+export function subscribe(fn) {
+  subscribers.add(fn);
+  return () => { subscribers.delete(fn); };
+}
+
+/**
+ * @param {object} event
+ */
+export function publish(event) {
+  for (const fn of subscribers) {
+    try { fn(event); } catch (err) {
+      // A broken subscriber must not take the bus down. Log and move on.
+      console.error('[event-bus] subscriber threw:', err.message);
+    }
+  }
+}
+
+/** @returns {number} */
+export function subscriberCount() {
+  return subscribers.size;
+}
+
+/** Test helper — drops every subscriber. */
+export function _resetForTests() {
+  subscribers.clear();
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Pure formatters used by the board UI to turn database rows into
+ * human-friendly labels. No DOM, no node APIs — easy to unit-test.
+ */
+
+const TIME_RE_FALLBACK = "—";
+const MAX_TASK_CHARS = 60;
+const MAX_PROJECT_CHARS = 40;
+
+/**
+ * Format an ISO 8601 timestamp as `HH:MM` (24h, local time of the
+ * server). Falls back to `—` when the input is missing or unparseable
+ * so the UI never renders `Invalid Date` or `null`.
+ *
+ * @param {string|null|undefined} iso
+ * @returns {string}
+ */
+export function formatHHMM(iso) {
+  if (!iso) return TIME_RE_FALLBACK;
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return TIME_RE_FALLBACK;
+  const hh = String(d.getHours()).padStart(2, "0");
+  const mm = String(d.getMinutes()).padStart(2, "0");
+  return `${hh}:${mm}`;
+}
+
+/**
+ * Truncate a task description to a max of N chars, collapsing internal
+ * whitespace, suffixed with "…" when truncated. Returns "" when the
+ * input is empty so the caller can decide whether to render the slot.
+ *
+ * @param {string|null|undefined} text
+ * @param {number} [max=MAX_TASK_CHARS]
+ * @returns {string}
+ */
+export function shortTask(text, max = MAX_TASK_CHARS) {
+  if (!text) return "";
+  const collapsed = String(text).replace(/\s+/g, " ").trim();
+  if (collapsed.length <= max) return collapsed;
+  return collapsed.slice(0, max - 1).trimEnd() + "…";
+}
+
+/**
+ * Build the label tuple used by `renderSessionCard` and
+ * `showSessionDetail`. The board used to print the session.id verbatim
+ * (e.g. `s_2026-05-07T08-35-58-010Z`) which is technically correct but
+ * impossible to scan at a glance — the user explicitly flagged this
+ * during pre-talk testing on 2026-05-07.
+ *
+ * Returned shape:
+ *   - `title`: bold-line title for the card (project + time).
+ *     Always non-empty; falls back to the session id when no project
+ *     is known so the card is never blank.
+ *   - `subtitle`: short task summary (≤ 60 chars). Empty when the
+ *     session has no task field — caller hides the slot.
+ *   - `idChip`: the cryptic session id, kept available for the user
+ *     who needs it for `kj resume <id>` and as a tooltip on the title.
+ *
+ * @param {{ id: string, project_name?: string|null, task?: string|null,
+ *           created_at?: string|null }} session
+ * @returns {{ title: string, subtitle: string, idChip: string }}
+ */
+export function formatSessionLabel(session) {
+  if (!session || !session.id) {
+    return { title: "(no session)", subtitle: "", idChip: "" };
+  }
+  const projectName = (session.project_name || "").trim();
+  const time = formatHHMM(session.created_at);
+  const projectPart = projectName
+    ? projectName.length > MAX_PROJECT_CHARS
+      ? projectName.slice(0, MAX_PROJECT_CHARS - 1) + "…"
+      : projectName
+    : session.id;  // fall back so a card without a joined project never
+                   // ends up blank — the cryptic id is better than empty
+  const title = time !== TIME_RE_FALLBACK
+    ? `${projectPart} · ${time}`
+    : projectPart;
+  return {
+    title,
+    subtitle: shortTask(session.task, MAX_TASK_CHARS),
+    idChip: session.id,
+  };
+}

package/packages/hu-board/src/hu-zombie-reaper.js

@@ -0,0 +1,103 @@
+/**
+ * HU-level zombie reaper (KJC-TSK-0394 step 3).
+ *
+ * Counterpart to zombie-reaper.js (que opera sobre sesiones). Detecta
+ * HUs que el orquestador dejó stuck en `coding`/`reviewing` —síntoma
+ * de crash mid-iteration— y las resetea a `pending`.
+ *
+ * Threshold separado de las sesiones: una sesión legítima puede
+ * tardar horas (loop largo), una HU individual rara vez >30 min. Por
+ * eso este reaper trabaja en minutos, no en horas.
+ *
+ * Semántica del reap: status → `pending` (NO `failed`: el orquestador
+ * perdió contacto, no podemos afirmar el outcome). El campo `result`
+ * NO se toca — se conserva como historial. La persistencia pasa por
+ * plan-mutations::setHuStatus (escribe el plan JSON + resync DB). Si
+ * el JSON write falla cae al fallback DB-only.
+ */
+
+const DEFAULT_RUNNING_MINUTES = 30;
+// `coding` + `reviewing` son los nombres legacy; `running` es el
+// canónico tras step 5. Aceptamos los tres durante la transición.
+const RUNNING_STATUSES = new Set(["coding", "reviewing", "running"]);
+
+/**
+ * Pure. Decide si un HU row es zombi a `now`.
+ */
+export function classifyHuZombie(hu, ctx) {
+  if (!hu || !hu.status) return { zombie: false };
+  const status = String(hu.status).toLowerCase();
+  if (!RUNNING_STATUSES.has(status)) return { zombie: false };
+  const refIso = hu.updated_at;
+  if (!refIso) return { zombie: false };
+  const refTs = new Date(refIso).getTime();
+  if (Number.isNaN(refTs)) return { zombie: false };
+  const ageMinutes = (ctx.now - refTs) / 60_000;
+  if (ageMinutes < ctx.runningMinutes) return { zombie: false };
+  return {
+    zombie: true,
+    reason: `${status} ${ageMinutes.toFixed(0)}min inactive (>= ${ctx.runningMinutes}min)`,
+  };
+}
+
+/** Pure. Filtra solo los zombis. */
+export function findZombieHus(hus, opts = {}) {
+  const ctx = {
+    now: opts.now ?? Date.now(),
+    runningMinutes: opts.runningMinutes ?? DEFAULT_RUNNING_MINUTES,
+  };
+  const out = [];
+  for (const hu of hus || []) {
+    const verdict = classifyHuZombie(hu, ctx);
+    if (verdict.zombie) out.push({ hu, reason: verdict.reason });
+  }
+  return out;
+}
+
+/**
+ * Resetea a `pending` cada HU zombi en la DB Y en el fichero del
+ * plan. `setHuStatus` se inyecta para que los tests no necesiten un
+ * plan-file real. Devuelve la lista de reapeados para el log.
+ */
+export function reapZombieHus({ db, setHuStatus, setHuFailResult, opts = {}, now = () => Date.now() }) {
+  if (!db || typeof setHuStatus !== "function") return [];
+  const rows = db.prepare(
+    "SELECT id, project_id, plan_id, status, updated_at FROM stories WHERE status IN ('coding', 'reviewing', 'running')",
+  ).all();
+  const zombies = findZombieHus(rows, { ...opts, now: now() });
+  if (zombies.length === 0) return [];
+  const reaped = [];
+  for (const { hu, reason } of zombies) {
+    // El id compuesto del board es `${projectId}::${huId}`; setHuStatus
+    // quiere el huId local.
+    const localHuId = hu.id.includes("::") ? hu.id.split("::").slice(1).join("::") : hu.id;
+    let planPersisted = false;
+    if (hu.plan_id) {
+      try {
+        const result = setHuStatus({ planId: hu.plan_id, huId: localHuId, status: "pending", projectId: hu.project_id });
+        planPersisted = !!(result && result.ok);
+      } catch { /* swallow — never block startup */ }
+      // KJC-TSK-0404: además de resetear status=pending, marcar la HU con
+      // result=fail + blocker. El siguiente `kj run` ve el blocker y se
+      // lo inyecta al coder como "## PREVIOUS ATTEMPT FAILED" para que
+      // no repita el mismo error. No-op si la fn no se inyectó.
+      if (planPersisted && typeof setHuFailResult === "function") {
+        try {
+          setHuFailResult({
+            planId: hu.plan_id, huId: localHuId, projectId: hu.project_id,
+            blocker: `timeout: ${reason}`,
+          });
+        } catch { /* swallow — el status reset ya está hecho */ }
+      }
+    }
+    // Fallback DB-only para legacy rows (plan_id null) o si el write al
+    // plan falló. setHuStatus ya resincroniza en el caso happy.
+    if (!planPersisted) {
+      try {
+        db.prepare("UPDATE stories SET status = 'pending', updated_at = ? WHERE id = ?").run(new Date(now()).toISOString(), hu.id);
+      } catch { /* swallow */ }
+    }
+    reaped.push({ id: hu.id, status_before: hu.status, reason, plan_persisted: planPersisted });
+  }
+  return reaped;
+}

package/packages/hu-board/src/journal-parser.js

@@ -0,0 +1,180 @@
+/**
+ * Journal parser — reads `.reviews/<sessionId>/` artefacts produced by Karajan's
+ * session journal writers (decisions.md, iterations.md, summary.md, tree.txt)
+ * and exposes them as structured JSON for the /pipeline dashboard.
+ *
+ * Scope: zero new runtime dependencies. Uses only node:fs + node:path.
+ * Poll-friendly: every call re-reads from disk so the UI can refresh by
+ * hitting the API endpoint on an interval (1-2 s). No WebSocket, no SSE —
+ * keeps the surface minimal (TSK-0325).
+ *
+ * Input layout (as written by src/session/journal/*):
+ *
+ *   <projectDir>/.reviews/<sessionId>/
+ *     ├─ decisions.md     — Brain / Solomon / standby / checkpoint decisions
+ *     ├─ iterations.md    — per-iteration coder/reviewer/sonar/solomon detail
+ *     ├─ summary.md       — executive view: stages, budget, links
+ *     └─ tree.txt         — directory-grouped file status
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Resolve the directory where session journals live. Honours KJ_PROJECT_DIR
+ * for the common "hu-board runs in a different process from the pipeline"
+ * case; otherwise falls back to the current working directory.
+ */
+function getProjectDir() {
+  return process.env.KJ_PROJECT_DIR || process.cwd();
+}
+
+/**
+ * Resolve the `.reviews/` directory under the active project dir.
+ */
+function getReviewsDir() {
+  return path.join(getProjectDir(), ".reviews");
+}
+
+/**
+ * List available sessions. Each entry points at a `.reviews/<sessionId>/`
+ * directory that has been produced by Karajan's journal writers.
+ *
+ * @returns {Array<{id: string, journalPath: string, mtimeMs: number}>}
+ */
+export function listSessions() {
+  const reviewsDir = getReviewsDir();
+  if (!fs.existsSync(reviewsDir)) return [];
+  const entries = fs.readdirSync(reviewsDir, { withFileTypes: true });
+  const sessions = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const dir = path.join(reviewsDir, entry.name);
+    let mtimeMs = 0;
+    try {
+      mtimeMs = fs.statSync(dir).mtimeMs;
+    } catch { /* stat failed — skip this entry */ }
+    sessions.push({ id: entry.name, journalPath: dir, mtimeMs });
+  }
+  // Most recent first — what the UI wants by default.
+  sessions.sort((a, b) => b.mtimeMs - a.mtimeMs);
+  return sessions;
+}
+
+/**
+ * Split a markdown doc into `## Heading` blocks. Keeps the heading name
+ * and the body under it.
+ * @param {string} md
+ * @returns {Array<{heading: string, body: string}>}
+ */
+export function splitByHeading(md, level = 2) {
+  if (!md) return [];
+  const prefix = "#".repeat(level) + " ";
+  const lines = md.split(/\r?\n/);
+  const blocks = [];
+  let current = null;
+  for (const line of lines) {
+    if (line.startsWith(prefix) && !line.startsWith(prefix + "# ")) {
+      if (current) blocks.push(current);
+      current = { heading: line.slice(prefix.length).trim(), body: "" };
+    } else if (current) {
+      current.body += (current.body ? "\n" : "") + line;
+    }
+  }
+  if (current) blocks.push(current);
+  return blocks;
+}
+
+/**
+ * Parse iterations.md into a list of iteration objects. The journal writer
+ * (src/session/journal/iteration-logger.js) produces `## Iteration N`
+ * sections, each with `### Stage` sub-blocks (Coder, Reviewer, Sonar, …).
+ *
+ * @param {string} md
+ * @returns {Array<{number: number, title: string, duration?: string, stages: Array<{name: string, body: string}>}>}
+ */
+export function parseIterations(md) {
+  return splitByHeading(md, 2).map((block) => {
+    const match = block.heading.match(/Iteration\s+(\d+)/i);
+    const number = match ? Number(match[1]) : 0;
+    const durationMatch = block.body.match(/\*\*Duration\*\*:\s*([^\n]+)/i);
+    const duration = durationMatch ? durationMatch[1].trim() : null;
+    const stages = splitByHeading(block.body, 3).map((s) => ({
+      name: s.heading,
+      body: s.body.trim(),
+    }));
+    return { number, title: block.heading, duration, stages };
+  });
+}
+
+/**
+ * Parse decisions.md into structured records. The writer uses
+ * `## <timestamp> — <decisionType>` headings; fall back to a flat list
+ * when the format drifts.
+ *
+ * @param {string} md
+ * @returns {Array<{heading: string, body: string}>}
+ */
+export function parseDecisions(md) {
+  return splitByHeading(md, 2).map((b) => ({
+    heading: b.heading,
+    body: b.body.trim(),
+  }));
+}
+
+/**
+ * Parse summary.md into { preamble, sections }. The preamble is anything
+ * before the first `## Heading`.
+ *
+ * @param {string} md
+ * @returns {{preamble: string, sections: Array<{heading: string, body: string}>}}
+ */
+export function parseSummary(md) {
+  const sections = splitByHeading(md, 2);
+  const firstHeadingIdx = md.indexOf("## ");
+  const preamble = firstHeadingIdx === -1 ? md.trim() : md.slice(0, firstHeadingIdx).trim();
+  return { preamble, sections };
+}
+
+/**
+ * Read a file defensively — returns null when missing, the content when
+ * present. Lets `readJournal` return a consistent shape even when the
+ * pipeline wrote some artefacts but not others.
+ */
+function readIfExists(file) {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read + parse the four journal artefacts for a given session. Always
+ * returns an object with the same keys so the client has predictable
+ * defaults.
+ *
+ * @param {string} sessionId
+ */
+export function readJournal(sessionId) {
+  const dir = path.join(getReviewsDir(), sessionId);
+  const iterationsRaw = readIfExists(path.join(dir, "iterations.md"));
+  const decisionsRaw = readIfExists(path.join(dir, "decisions.md"));
+  const summaryRaw = readIfExists(path.join(dir, "summary.md"));
+  const treeRaw = readIfExists(path.join(dir, "tree.txt"));
+  return {
+    id: sessionId,
+    journalPath: dir,
+    exists: fs.existsSync(dir),
+    iterations: iterationsRaw ? parseIterations(iterationsRaw) : [],
+    decisions: decisionsRaw ? parseDecisions(decisionsRaw) : [],
+    summary: summaryRaw ? parseSummary(summaryRaw) : { preamble: "", sections: [] },
+    tree: treeRaw || "",
+    raw: {
+      iterations: iterationsRaw,
+      decisions: decisionsRaw,
+      summary: summaryRaw,
+      tree: treeRaw,
+    },
+  };
+}