contextdevkit 1.8.0

package/templates/contextkit/runtime/hooks/concurrency-guard.mjs

@@ -0,0 +1,110 @@
+#!/usr/bin/env node
+/**
+ * PreToolUse concurrency guard (Level >= 3) — prevents one session from
+ * silently clobbering another's work on the same file.
+ *
+ * Claude Code's own `Edit` already refuses to edit a file changed since the
+ * agent last read it. This guard covers the remaining same-machine gaps:
+ *   - `Write` (full overwrite) — does NOT check freshness, so it can clobber.
+ *   - cross-session awareness — another live session (or an external tool)
+ *     modified this exact file recently.
+ *
+ * It WARNS (never blocks → no retry loops): prints a banner that becomes
+ * context, telling the agent to re-read and merge rather than overwrite.
+ * Cross-machine conflicts are caught at push time by the pre-push hook.
+ *
+ * Defensive: any error exits 0 silently.
+ */
+import { stat } from 'node:fs/promises';
+import { resolve } from 'node:path';
+import { getLevel } from '../config/load.mjs';
+import { listAllLedgers, readLedger, resolveSessionId, ROOT, toRepoRelative } from './ledger.mjs';
+
+const RECENT_MS = 12 * 60 * 60 * 1000; // ignore stale ledgers older than 12h
+
+async function readStdin() {
+  return new Promise((res) => {
+    let buf = '';
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (c) => (buf += c));
+    process.stdin.on('end', () => res(buf));
+    setTimeout(() => res(buf), 500).unref?.();
+  });
+}
+
+function extractFilePath(payload) {
+  const t = payload?.tool_name;
+  const input = payload?.tool_input ?? {};
+  if ((t === 'Edit' || t === 'Write' || t === 'MultiEdit') && typeof input.file_path === 'string') return input.file_path;
+  return null;
+}
+
+/** Most recent modification entry for `path` in a ledger (or null). */
+function lastMod(ledger, path) {
+  let best = null;
+  for (const m of ledger.modifications || []) {
+    if (m.path === path && (!best || m.at > best.at)) best = m;
+  }
+  return best;
+}
+
+async function main() {
+  if (getLevel(ROOT) < 3) return;
+  const raw = await readStdin();
+  if (!raw) return;
+  let payload;
+  try {
+    payload = JSON.parse(raw);
+  } catch {
+    return;
+  }
+
+  const filePath = extractFilePath(payload);
+  if (!filePath) return;
+  const target = toRepoRelative(filePath);
+  if (!target) return;
+
+  const myId = resolveSessionId(payload);
+  const tool = payload.tool_name;
+  const warnings = [];
+
+  // 1. Another active session touched this exact file recently.
+  const now = Date.now();
+  for (const { sessionId, ledger } of await listAllLedgers()) {
+    if (sessionId === myId) continue;
+    if (ledger.registered) continue; // their work is already saved/registered
+    const m = lastMod(ledger, target);
+    if (m && now - m.at < RECENT_MS) {
+      warnings.push(`another active session \`${sessionId.slice(0, 8)}\` modified it ${Math.round((now - m.at) / 60000)}m ago`);
+    }
+  }
+
+  // 2. The file changed on disk since THIS session last wrote it (external edit).
+  const mine = lastMod(await readLedger(myId), target);
+  if (mine && typeof mine.mtime === 'number') {
+    try {
+      const current = (await stat(resolve(ROOT, filePath))).mtimeMs;
+      if (current > mine.mtime + 1) warnings.push('it changed on disk since you last wrote it');
+    } catch {
+      /* gone — ignore */
+    }
+  }
+
+  if (warnings.length === 0) return;
+
+  const out = [
+    '<concurrency-warning>',
+    `⚠️  Concurrency on \`${target}\`: ${warnings.join('; ')}.`,
+    tool === 'Write'
+      ? '   You are about to OVERWRITE the whole file. Re-read it first, then preserve the other'
+      : '   Re-read it first, then make sure you only change your part —',
+    '   changes and add yours — do NOT clobber another session\'s work.',
+    '</concurrency-warning>',
+  ].join('\n');
+  process.stdout.write(out);
+}
+
+main().catch((err) => {
+  process.stderr.write(`[concurrency-guard] ${err?.message ?? err}\n`);
+  process.exit(0);
+});

package/templates/contextkit/runtime/hooks/ledger.mjs

@@ -0,0 +1,231 @@
+/**
+ * Shared helpers for the per-session ledger (L2).
+ *
+ * Each Claude Code session writes its OWN ledger at:
+ *   `.claude/.sessions/<sessionId>.json`
+ *
+ * Why per-session and not a single file?
+ *   - Multiple parallel chats on the same machine would otherwise stomp on
+ *     each other's state. Per-session files isolate naturally.
+ *   - For multi-machine parallelism, `git worktree` gives each chat its own
+ *     `.claude/.sessions/` directory anyway (it lives outside `.git`).
+ *
+ * Ledger schema:
+ *   {
+ *     sessionId: string,
+ *     startedAt: number,
+ *     modifications: Array<{ path, tool, at }>,
+ *     registered: boolean,
+ *     stopWarnedAt: number | null,
+ *     simulations: Array<{ objective, coveredPaths, predictionFile, at }>
+ *   }
+ *
+ * All functions are defensive: never throw; on error return safe defaults so
+ * a hook never breaks a Claude session. Zero third-party deps.
+ */
+import { mkdir, readdir, readFile, stat } from 'node:fs/promises';
+import { dirname, relative, resolve } from 'node:path';
+import { isImportant, isRegistrationFile, isTrackable } from './path-classification.mjs';
+import { writeFileAtomic } from './safe-io.mjs';
+import { LEDGER_DIR } from '../config/paths.mjs';
+
+export { isImportant, isRegistrationFile, isTrackable };
+
+export const ROOT = process.cwd();
+export const SESSIONS_DIR = resolve(ROOT, LEDGER_DIR);
+
+/**
+ * "Last touched" pointer — updated by every track-edits run. Lets slash
+ * commands (`/log-session`) discover the current session without a hook
+ * payload.
+ */
+export const LAST_TOUCHED_PATH = resolve(SESSIONS_DIR, '.last-touched');
+
+export function ledgerPathFor(sessionId) {
+  return resolve(SESSIONS_DIR, `${sanitizeSid(sessionId)}.json`);
+}
+
+/** Reads a ledger by sessionId. Returns a fresh ledger if missing/corrupt. */
+export async function readLedger(sessionId) {
+  try {
+    const raw = await readFile(ledgerPathFor(sessionId), 'utf-8');
+    return normalizeLedger(JSON.parse(raw), sessionId);
+  } catch {
+    return freshLedger(sessionId);
+  }
+}
+
+/** Persists a ledger and updates the last-touched pointer (both atomic). */
+export async function writeLedger(sessionId, ledger) {
+  try {
+    await mkdir(SESSIONS_DIR, { recursive: true });
+    await writeFileAtomic(ledgerPathFor(sessionId), JSON.stringify(ledger, null, 2));
+    await writeFileAtomic(LAST_TOUCHED_PATH, JSON.stringify({ sessionId, at: Date.now() }));
+  } catch (err) {
+    process.stderr.write(`[ledger] write failed: ${err?.message ?? err}\n`);
+  }
+}
+
+/**
+ * Most recently touched ledger across all session files. Used by slash
+ * commands that don't receive a hook payload.
+ *
+ * @returns {Promise<{ sessionId: string, ledger: any } | null>}
+ */
+export async function readMostRecentLedger() {
+  try {
+    const raw = await readFile(LAST_TOUCHED_PATH, 'utf-8');
+    const ptr = JSON.parse(raw);
+    if (typeof ptr?.sessionId !== 'string') return null;
+    return { sessionId: ptr.sessionId, ledger: await readLedger(ptr.sessionId) };
+  } catch {
+    try {
+      const files = await readdir(SESSIONS_DIR);
+      let best = null;
+      for (const f of files) {
+        if (!f.endsWith('.json') || f.startsWith('.')) continue;
+        const st = await stat(resolve(SESSIONS_DIR, f));
+        if (!best || st.mtimeMs > best.mtime) {
+          best = { sessionId: f.slice(0, -5), mtime: st.mtimeMs };
+        }
+      }
+      if (!best) return null;
+      return { sessionId: best.sessionId, ledger: await readLedger(best.sessionId) };
+    } catch {
+      return null;
+    }
+  }
+}
+
+/** Lists all ledgers in this worktree. Used by SessionStart drift detection. */
+export async function listAllLedgers() {
+  let files = [];
+  try {
+    files = await readdir(SESSIONS_DIR);
+  } catch {
+    return [];
+  }
+  const all = [];
+  for (const f of files) {
+    if (!f.endsWith('.json') || f.startsWith('.')) continue;
+    const sid = f.slice(0, -5);
+    all.push({ sessionId: sid, ledger: await readLedger(sid) });
+  }
+  return all;
+}
+
+export function freshLedger(sessionId) {
+  return {
+    sessionId,
+    startedAt: Date.now(),
+    modifications: [],
+    registered: false,
+    stopWarnedAt: null,
+    simulations: [],
+  };
+}
+
+/**
+ * Maps a session id to a filesystem-safe token: only `[A-Za-z0-9_-]`, capped at
+ * 64 chars. Exported so every path-constructing caller (ledger, claim/release,
+ * track-edits) sanitizes consistently — a session id is external input and must
+ * never be able to escape `.claude/.sessions` or `.claude/.workspace` (`../`).
+ */
+export function sanitizeSid(sid) {
+  return String(sid).replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 64);
+}
+
+function normalizeLedger(obj, sessionId) {
+  const base = freshLedger(sessionId);
+  if (!obj || typeof obj !== 'object') return base;
+  return {
+    sessionId: typeof obj.sessionId === 'string' ? obj.sessionId : sessionId,
+    startedAt: typeof obj.startedAt === 'number' ? obj.startedAt : base.startedAt,
+    modifications: Array.isArray(obj.modifications) ? obj.modifications : [],
+    registered: obj.registered === true,
+    stopWarnedAt: typeof obj.stopWarnedAt === 'number' ? obj.stopWarnedAt : null,
+    simulations: Array.isArray(obj.simulations) ? obj.simulations : [],
+  };
+}
+
+export function toRepoRelative(absOrRel) {
+  if (!absOrRel) return '';
+  try {
+    return relative(ROOT, resolve(ROOT, absOrRel)).replaceAll('\\', '/');
+  } catch {
+    return String(absOrRel);
+  }
+}
+
+export function pendingImportantPaths(ledger) {
+  const seen = new Set();
+  for (const mod of ledger.modifications) {
+    if (isRegistrationFile(mod.path)) continue;
+    if (!isImportant(mod.path)) continue;
+    seen.add(mod.path);
+  }
+  return [...seen];
+}
+
+export function wasRegisteredDuringSession(ledger) {
+  return ledger.modifications.some((m) => isRegistrationFile(m.path));
+}
+
+/**
+ * Appends a simulate-impact record (L5). `coveredPaths` MUST already be
+ * repo-relative + forward-slashed. Mutates the ledger in place and returns it.
+ *
+ * @param {ReturnType<typeof freshLedger>} ledger
+ * @param {{ objective: string, coveredPaths: string[], predictionFile?: string }} entry
+ */
+export function markSimulation(ledger, entry) {
+  if (!ledger || typeof ledger !== 'object') return ledger;
+  if (!entry || typeof entry.objective !== 'string') return ledger;
+  if (!Array.isArray(ledger.simulations)) ledger.simulations = [];
+  const covered = Array.isArray(entry.coveredPaths)
+    ? entry.coveredPaths.filter((p) => typeof p === 'string' && p.length > 0)
+    : [];
+  ledger.simulations.push({
+    objective: entry.objective,
+    coveredPaths: covered,
+    predictionFile: typeof entry.predictionFile === 'string' ? entry.predictionFile : null,
+    at: Date.now(),
+  });
+  return ledger;
+}
+
+/**
+ * True when at least one simulation entry covers `targetPath` (exact match or
+ * a directory-prefix claim ending in `/`).
+ *
+ * @param {ReturnType<typeof freshLedger>} ledger
+ * @param {string} targetPath — repo-relative, forward-slashed
+ */
+export function hasSimulationFor(ledger, targetPath) {
+  if (!ledger || !Array.isArray(ledger.simulations)) return false;
+  if (typeof targetPath !== 'string' || targetPath.length === 0) return false;
+  const normalized = toRepoRelative(targetPath);
+  for (const sim of ledger.simulations) {
+    if (!sim || !Array.isArray(sim.coveredPaths)) continue;
+    for (const covered of sim.coveredPaths) {
+      if (typeof covered !== 'string' || covered.length === 0) continue;
+      if (covered === normalized) return true;
+      if (covered.endsWith('/') && normalized.startsWith(covered)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Reads the sessionId from a hook stdin payload, falling back to env then a
+ * synthetic per-process id so the script never crashes.
+ *
+ * @param {any} payload
+ */
+export function resolveSessionId(payload) {
+  if (payload?.session_id && typeof payload.session_id === 'string') return payload.session_id;
+  if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
+  return `local_${process.pid}_${Date.now()}`;
+}
+
+export { dirname };

package/templates/contextkit/runtime/hooks/md-extract.mjs

@@ -0,0 +1,65 @@
+/**
+ * Markdown extraction primitives — pure, zero-dep, defensive. [ADR-0027]
+ *
+ * Generic helpers shared by the session and ADR digest cores (the second
+ * consumer that justified the split). No I/O, no path construction — callers
+ * pass already-split lines or raw values. Each helper degrades to '' / [] rather
+ * than throwing, so a malformed document never breaks a digest.
+ */
+
+/** Clips to `max` chars with a trailing ellipsis when over budget. */
+export const clip = (text, max) =>
+  String(text).length > max ? `${String(text).slice(0, max - 1).trimEnd()}…` : String(text);
+
+/** Strips markdown noise: `[label](url)` → `label`, drops `*_\`` markers, collapses ws. */
+export function stripMd(value) {
+  return String(value)
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, '$1')
+    .replace(/[`*_]/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/** Body lines under a `## …<keyword>…` heading, until the next `##`/`---`/EOF. */
+export function section(lines, keyword) {
+  const kw = keyword.toLowerCase();
+  const start = lines.findIndex((l) => /^##\s+/.test(l) && l.toLowerCase().includes(kw));
+  if (start === -1) return [];
+  const rest = lines.slice(start + 1);
+  const end = rest.findIndex((l) => /^##\s+/.test(l) || l.trim() === '---');
+  return rest.slice(0, end === -1 ? rest.length : end);
+}
+
+/** First prose paragraph of a section as one clean line (markdown stripped). */
+export function firstParagraph(sectionLines, max = 180) {
+  const buffer = [];
+  for (const raw of sectionLines) {
+    const line = raw.replace(/^>\s?/, '');
+    if (!line.trim()) {
+      if (buffer.length) break;
+      continue;
+    }
+    if (/^#{1,6}\s/.test(line)) break;
+    buffer.push(line.replace(/^[-*]\s+/, '').trim());
+    if (buffer.join(' ').length >= max) break;
+  }
+  return clip(stripMd(buffer.join(' ')), max);
+}
+
+/** Bullet items of a section (text after the marker, markdown stripped), each clipped. */
+export function bullets(sectionLines, max = 110) {
+  return sectionLines
+    .filter((l) => /^\s*[-*]\s+/.test(l))
+    .map((l) => clip(stripMd(l.replace(/^\s*[-*]\s+/, '')), max))
+    .filter(Boolean);
+}
+
+/** Reads a `- **Label**: value` metadata bullet (backticks stripped); '' if absent. */
+export function metaValue(lines, label) {
+  const re = new RegExp(`^[-*]\\s*\\*\\*${label}\\*\\*:\\s*(.+)$`, 'i');
+  for (const l of lines) {
+    const m = re.exec(l.trim());
+    if (m) return m[1].replace(/`/g, '').trim();
+  }
+  return '';
+}

package/templates/contextkit/runtime/hooks/path-classification.mjs

@@ -0,0 +1,62 @@
+/**
+ * Path classification for the L2 session ledger — CONFIG-DRIVEN.
+ *
+ * Three predicates power drift detection:
+ *   - `isTrackable(path)` — record this edit in the ledger at all?
+ *     Excludes build output, caches and the ledger's own runtime state.
+ *   - `isImportant(path)` — does an edit here trigger the Stop drift nudge?
+ *     Captures source, platform and top-level config.
+ *   - `isRegistrationFile(path)` — does an edit here count AS registering
+ *     the session (suppressing the nudge)?
+ *
+ * Prefix lists come from `contextkit/config.json` (`ledger.*`), falling back to
+ * the stack-agnostic defaults. This is the seam that makes the kit portable:
+ * a Python project sets `important: ["app/", "tests/"]`, a Go project sets
+ * `["cmd/", "internal/"]`, etc. — no code edits required.
+ *
+ * Zero third-party deps so it runs on a fresh project.
+ */
+import { loadConfigSync } from '../config/load.mjs';
+
+const config = loadConfigSync();
+const IMPORTANT_PREFIXES = config.ledger.important;
+const IRRELEVANT_PREFIXES = config.ledger.irrelevant;
+const REGISTRATION_PATHS = config.ledger.registration;
+
+function normalize(relPath) {
+  return relPath.replaceAll('\\', '/');
+}
+
+/**
+ * Returns true if the given repo-relative path should be persisted in the
+ * session ledger.
+ *
+ * @param {string} relPath
+ */
+export function isTrackable(relPath) {
+  if (!relPath) return false;
+  const norm = normalize(relPath);
+  return !IRRELEVANT_PREFIXES.some((p) => norm === p || norm.startsWith(p));
+}
+
+/**
+ * Returns true if a modification at the given path should count toward the
+ * Stop-hook drift nudge.
+ *
+ * @param {string} relPath
+ */
+export function isImportant(relPath) {
+  const norm = normalize(relPath);
+  return IMPORTANT_PREFIXES.some((p) => norm === p || norm.startsWith(p));
+}
+
+/**
+ * Returns true if a modification at the given path counts AS the session
+ * registration step (suppresses the nudge).
+ *
+ * @param {string} relPath
+ */
+export function isRegistrationFile(relPath) {
+  const norm = normalize(relPath);
+  return REGISTRATION_PATHS.includes(norm);
+}

package/templates/contextkit/runtime/hooks/safe-io.mjs

@@ -0,0 +1,84 @@
+/**
+ * Atomic file writes — shared, zero-dependency I/O helper.
+ *
+ * Strategy: write to a unique temp sibling, then `rename` it over the target.
+ * `rename(2)` is atomic on the same filesystem, so a concurrent reader always
+ * sees either the previous file or the complete new one — never a half-written,
+ * truncated, or interleaved file. This is the safe replacement for the bare
+ * `writeFile` calls in the ledger, workspace and pipeline writers, which could
+ * corrupt state when two sessions wrote the same artifact at once.
+ *
+ * Lives in `runtime/hooks/` alongside the other internal libs (ledger.mjs,
+ * path-classification.mjs) so both the runtime hooks and the tool scripts share
+ * one source. Sync variant for the scripts, async for the hot-path hooks.
+ */
+import { existsSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { rename, unlink, writeFile } from 'node:fs/promises';
+
+const BOM = /^/;
+
+/**
+ * Parse JSON defensively: strips a leading UTF-8 BOM (common from Windows
+ * editors / PowerShell) and returns `fallback` on any error instead of throwing.
+ */
+export function parseJsonSafe(text, fallback = null) {
+  if (typeof text !== 'string') return fallback;
+  try {
+    return JSON.parse(text.replace(BOM, ''));
+  } catch {
+    return fallback;
+  }
+}
+
+/**
+ * Read + parse a JSON file defensively (BOM-tolerant). A missing file or invalid
+ * JSON returns `fallback`. This is the single source for the BOM-strip+parse
+ * pattern previously copy-pasted across the tool scripts.
+ */
+export function readJsonSafe(path, fallback = null) {
+  if (!existsSync(path)) return fallback;
+  try {
+    return parseJsonSafe(readFileSync(path, 'utf-8'), fallback);
+  } catch {
+    return fallback;
+  }
+}
+
+/** Unique temp path next to the target (same dir → same filesystem → atomic rename). */
+function tmpName(path) {
+  return `${path}.tmp-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/**
+ * Atomically write `data` to `path` (synchronous — for the tool scripts).
+ * On failure the temp file is cleaned up and the original error re-thrown.
+ */
+export function writeFileAtomicSync(path, data, encoding = 'utf-8') {
+  const tmp = tmpName(path);
+  try {
+    writeFileSync(tmp, data, encoding);
+    renameSync(tmp, path);
+  } catch (err) {
+    try {
+      unlinkSync(tmp);
+    } catch {
+      /* temp may not exist */
+    }
+    throw err;
+  }
+}
+
+/**
+ * Atomically write `data` to `path` (async — for the runtime hooks).
+ * On failure the temp file is cleaned up and the original error re-thrown.
+ */
+export async function writeFileAtomic(path, data, encoding = 'utf-8') {
+  const tmp = tmpName(path);
+  try {
+    await writeFile(tmp, data, encoding);
+    await rename(tmp, path);
+  } catch (err) {
+    await unlink(tmp).catch(() => {});
+    throw err;
+  }
+}

package/templates/contextkit/runtime/hooks/session-digest-core.mjs

@@ -0,0 +1,85 @@
+/**
+ * Session-log digest core — pure, zero-dep structural extraction. [ADR-0027]
+ *
+ * Parses a ContextDevKit session log into a compact record so callers reason over a
+ * ~6-line digest instead of the 75–188 raw lines. SINGLE SOURCE (rule 4): used by
+ * BOTH the boot hook (`boot-context-readers.digestLatestSession`) and the
+ * `session-digest.mjs` / `context-pack.mjs` scripts.
+ *
+ * No I/O and no path construction here — callers pass the file text + name; this
+ * module only parses and renders. Every function is defensive: a malformed log
+ * yields `{ ok: false }` so the caller can fall back to the raw view (rule 8 —
+ * a digest miss is a visible fallback, never a silent drop).
+ */
+
+import { bullets, firstParagraph, metaValue, section } from './md-extract.mjs';
+
+/** `<YYYY-MM-DD>-<NN>-<slug>.md` — same shape the reindex/boot readers use. */
+export const SESSION_FILENAME_RE = /^(\d{4}-\d{2}-\d{2})-(\d{2,})-([a-z0-9._-]+)\.md$/;
+const ADR_RE = /ADR-(\d{4})/g;
+
+/** Drops a redundant `Session <N> —` prefix the title often repeats. */
+function cleanTitle(title, number) {
+  if (number == null) return title.trim();
+  return title.replace(new RegExp(`^session\\s*${number}\\s*[—:\\-]\\s*`, 'i'), '').trim();
+}
+
+/** Works / Pending / Mixed verdict from the `Final state` section (honest ''). */
+function deriveVerdict(finalLines) {
+  const text = finalLines.join('\n');
+  const works = /\bworks?\b/i.test(text) || text.includes('✅');
+  const pending = /\bpending\b|\bnot done\b|\bawait/i.test(text) || text.includes('⚠️');
+  if (works && pending) return 'Mixed';
+  if (works) return 'Works';
+  if (pending) return 'Pending';
+  return '';
+}
+
+/**
+ * Parses one session-log markdown string into a compact record.
+ * @param {string} text     the file contents
+ * @param {string} filename the `<date>-<NN>-<slug>.md` name (for fallbacks)
+ * @returns {{ok:boolean, number:?number, date:string, branch:string, title:string,
+ *   request:string, done:string, decisions:string[], adrs:string[], verdict:string, slug:string}}
+ */
+export function parseSessionLog(text, filename = '') {
+  const safe = String(text || '').replace(/^/, '');
+  const lines = safe.split('\n');
+  const fm = SESSION_FILENAME_RE.exec(filename) || [];
+  const number = Number.parseInt(metaValue(lines, 'Session number') || fm[2] || '', 10) || null;
+  const rawTitle = (lines.find((l) => l.startsWith('# ')) || '').slice(2).trim();
+  const title = cleanTitle(rawTitle, number);
+  const date = (metaValue(lines, 'Date') || fm[1] || '').trim();
+  const branch = metaValue(lines, 'Branch');
+  const request = firstParagraph(section(lines, 'request'));
+  const done = firstParagraph(section(lines, 'done'));
+  const decisions = bullets(section(lines, 'decision')).slice(0, 4);
+  const adrs = [...new Set(safe.match(ADR_RE) || [])].sort();
+  const verdict = deriveVerdict(section(lines, 'final'));
+  // `ok` means we extracted usable STRUCTURE (not just a number from the filename),
+  // so a structureless log degrades to the raw boot view rather than a bare header.
+  const ok = Boolean(title || request || done || decisions.length || verdict);
+  return { ok, number, date, branch, title, request, done, decisions, adrs, verdict, slug: fm[3] || '' };
+}
+
+/** Multi-line (~6) digest block for one session, or `null` if unparseable. */
+export function renderDigest(record) {
+  if (!record || !record.ok) return null;
+  const head = `**Session ${record.number ?? '??'}${record.title ? ` — ${record.title}` : ''}**` +
+    `${record.date ? `  (${record.date}${record.branch ? ` · \`${record.branch}\`` : ''})` : ''}`;
+  const out = [head];
+  if (record.request) out.push(`- Request: ${record.request}`);
+  if (record.done) out.push(`- Done: ${record.done}`);
+  if (record.decisions.length) out.push(`- Decisions: ${record.decisions.join('; ')}`);
+  if (record.adrs.length) out.push(`- ADRs: ${record.adrs.join(', ')}`);
+  out.push(`- Final: ${record.verdict || '—'}`);
+  return out.join('\n');
+}
+
+/** One-line index form for a list of sessions. */
+export function renderDigestLine(record) {
+  if (!record || !record.ok) return null;
+  const adrs = record.adrs.length ? ` [${record.adrs.join(', ')}]` : '';
+  const verdict = record.verdict ? ` _${record.verdict}_` : '';
+  return `- **${record.number ?? '??'}** ${record.date} — ${record.title || record.slug}${verdict}${adrs}`;
+}