@smartmemory/compose 0.1.1-beta → 0.1.3-beta

package/lib/bug-checkpoint.js

@@ -0,0 +1,191 @@
+/**
+ * bug-checkpoint.js — COMP-FIX-HARD T2.
+ *
+ * Emits docs/bugs/<bug_code>/checkpoint.md when a bug-mode pipeline force-terminates,
+ * then triggers regeneration of the global docs/bugs/INDEX.md.
+ *
+ * The bug-index-gen.js module is imported dynamically to tolerate parallel-task
+ * development: if T3's file is not yet present, we still write the checkpoint and
+ * emit a warning instead of throwing. Tests inject a stub via
+ * __setRegenerateBugIndexForTest.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { execSync } from 'node:child_process';
+
+const DIFF_CAP = 5000;
+
+// Test seam: tests can install a fake regenerator. When null, the default
+// dynamic-import path is used.
+let regeneratorOverride = null;
+
+/**
+ * Test-only hook to override the regenerateBugIndex implementation.
+ * Pass `null` to restore default behavior.
+ * @param {((cwd: string) => void | Promise<void>) | null} fn
+ */
+export function __setRegenerateBugIndexForTest(fn) {
+  regeneratorOverride = fn;
+}
+
+/**
+ * Emit a checkpoint markdown file for a bug whose pipeline has force-terminated,
+ * then regenerate the bugs INDEX.
+ *
+ * @param {{ cwd: string, bug_code: string }} context - Build context (must include cwd and bug_code).
+ * @param {string} stepId - The pipeline step that exhausted retries.
+ * @param {{ violations?: any[], retries_exhausted?: number, [k: string]: any }} terminalResult
+ *        - The final step response that triggered termination.
+ * @returns {Promise<string>} Absolute path of the written checkpoint.md.
+ */
+export async function emitCheckpoint(context, stepId, terminalResult) {
+  const { cwd, bug_code } = context;
+  const bugDir = join(cwd, 'docs', 'bugs', bug_code);
+  mkdirSync(bugDir, { recursive: true });
+
+  const ts = new Date().toISOString();
+  const retriesExhausted =
+    (terminalResult && typeof terminalResult.retries_exhausted === 'number'
+      ? terminalResult.retries_exhausted
+      : null) ?? readActiveBuildRetries(cwd, stepId) ?? 0;
+
+  const diffBody = getCurrentDiff(cwd);
+
+  const violations =
+    terminalResult && Array.isArray(terminalResult.violations) ? terminalResult.violations : [];
+  const failureBody = formatLastFailure(violations[0]);
+
+  const ledgerPointer = existsSync(join(bugDir, 'hypotheses.jsonl'))
+    ? '[hypotheses.jsonl](./hypotheses.jsonl)'
+    : '(none yet)';
+
+  const md = [
+    `# Checkpoint: ${bug_code}`,
+    '',
+    `**Time:** ${ts}`,
+    `**Step:** ${stepId}`,
+    `**Retries exhausted:** ${retriesExhausted}`,
+    '',
+    '## Current Diff',
+    '',
+    '```diff',
+    diffBody,
+    '```',
+    '',
+    '## Last Failure',
+    '',
+    '```',
+    failureBody,
+    '```',
+    '',
+    '## Hypothesis Ledger',
+    '',
+    ledgerPointer,
+    '',
+    '## To Resume',
+    '',
+    '```bash',
+    `compose fix ${bug_code} --resume`,
+    '```',
+    '',
+    '## Next Steps',
+    '',
+    '- Inspect the diff above and decide whether to keep, amend, or revert it.',
+    '- Review the hypothesis ledger for previously rejected diagnoses.',
+    '- Run the resume command to re-enter the failed step with full context.',
+    '- If the bug is unsolvable in this session, mark it `PARKED` in the roadmap.',
+    '',
+  ].join('\n');
+
+  const checkpointPath = join(bugDir, 'checkpoint.md');
+  writeFileSync(checkpointPath, md, 'utf8');
+
+  await invokeRegenerateBugIndex(cwd);
+
+  return checkpointPath;
+}
+
+/**
+ * Capture `git diff --no-color HEAD`, capped at DIFF_CAP chars.
+ * Returns "(unable to get diff)" if git is unavailable or cwd is not a repo.
+ * Never throws.
+ */
+function getCurrentDiff(cwd) {
+  try {
+    const out = execSync('git diff --no-color HEAD', {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+      // 2MB cap: large enough that realistic multi-file diffs at force-terminate
+      // time fit (round-1 reduced from 50MB to avoid OOM; round-2 caught that
+      // 20KB / DIFF_CAP*4 was so small ENOBUFS fired on most real diffs and
+      // checkpoint lost the diff entirely). 2MB is the sweet spot: keeps OOM
+      // safety while preserving usable diffs for normal cases.
+      maxBuffer: 2 * 1024 * 1024,
+    });
+    if (!out || out.length === 0) return '(no changes)';
+    return out.length > DIFF_CAP ? out.slice(0, DIFF_CAP) : out;
+  } catch {
+    return '(unable to get diff)';
+  }
+}
+
+/**
+ * Best-effort lookup of retries-so-far from .compose/data/active-build.json.
+ * Returns null when unavailable.
+ */
+function readActiveBuildRetries(cwd, stepId) {
+  try {
+    const p = join(cwd, '.compose', 'data', 'active-build.json');
+    if (!existsSync(p)) return null;
+    const raw = readFileSync(p, 'utf8');
+    const obj = JSON.parse(raw);
+    const counters = obj?.retryCounters || obj?.retry_counters;
+    if (counters && typeof counters[stepId] === 'number') return counters[stepId];
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Format the head violation for the Last Failure block.
+ * - JSON-stringify objects (pretty), pass strings through.
+ */
+function formatLastFailure(v) {
+  if (v == null) return '(no violation captured)';
+  if (typeof v === 'string') return v;
+  try {
+    return JSON.stringify(v, null, 2);
+  } catch {
+    return String(v);
+  }
+}
+
+/**
+ * Resolve the regenerateBugIndex function and call it. Honors test override.
+ * Falls back gracefully (warning to stderr) if the sibling module isn't present yet.
+ */
+async function invokeRegenerateBugIndex(cwd) {
+  if (typeof regeneratorOverride === 'function') {
+    await regeneratorOverride(cwd);
+    return;
+  }
+  try {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const target = join(here, 'bug-index-gen.js');
+    if (!existsSync(target)) {
+      // Sibling module not built yet (parallel-task race); skip silently in that
+      // narrow window. INDEX will refresh next time a checkpoint emits.
+      return;
+    }
+    const mod = await import(`file://${target}`);
+    if (typeof mod.regenerateBugIndex === 'function') {
+      await mod.regenerateBugIndex(cwd);
+    }
+  } catch (err) {
+    process.stderr.write(`[bug-checkpoint] regenerateBugIndex failed: ${err?.message || err}\n`);
+  }
+}

package/lib/bug-escalation.js

@@ -0,0 +1,306 @@
+/**
+ * bug-escalation.js — COMP-FIX-HARD T10 Tier 1 + Tier 2 escalation.
+ *
+ * Tier 1: Codex second opinion (read-only). Costs ~30s, no writes.
+ *   - Constructs a bounded prompt (one bug, one ledger, one diff).
+ *   - Dispatches via stratum.runAgentText('codex', prompt, {cwd}).
+ *   - Parses output to canonical ReviewResult via review-normalize.
+ *   - Appends an `escalation_tier_1` entry to the bug's hypothesis ledger.
+ *
+ * Tier 2: Fresh agent in an isolated git worktree (patch-only, never commits).
+ *   - "Materially new" gate: only proceeds if Codex's hypothesis is not already
+ *     present in the ledger as a rejected entry.
+ *   - Creates a detached worktree under ~/.stratum/worktrees/comp-fix-hard/<bug>-<ts>/.
+ *   - Dispatches a fresh Claude agent with explicit "DO NOT commit" instructions
+ *     and a target patch artifact path docs/bugs/<bug>/escalation-patch-<N>.md.
+ *   - Cleanup runs in finally — worktree is removed on both success and error.
+ *
+ * Pattern references:
+ *   - lib/build.js:2670+ (parallel-dispatch worktree create/remove)
+ *   - lib/review-normalize.js (normalizeReviewResult)
+ *   - lib/stratum-mcp-client.js (runAgentText)
+ */
+
+import { existsSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { execSync } from 'node:child_process';
+
+import { normalizeReviewResult } from './review-normalize.js';
+import { appendHypothesisEntry, readHypotheses } from './bug-ledger.js';
+
+// ---------------------------------------------------------------------------
+// Tier 1 — Codex read-only second opinion
+// ---------------------------------------------------------------------------
+
+/**
+ * Format the hypothesis ledger as a "Previously attempted" block for the
+ * Codex prompt. Includes both rejected and accepted entries so Codex sees
+ * the full investigation history, not just dead ends.
+ */
+function formatHypothesisBlock(hypotheses) {
+  if (!Array.isArray(hypotheses) || hypotheses.length === 0) {
+    return '## Previously attempted hypotheses\n\n_(none — this is the first escalation.)_\n';
+  }
+  const lines = ['## Previously attempted hypotheses', ''];
+  for (const h of hypotheses) {
+    if (!h) continue;
+    lines.push(`- **Attempt ${h.attempt ?? '?'}** (${h.verdict ?? 'unknown'}): ${h.hypothesis ?? '(no hypothesis recorded)'}`);
+    if (Array.isArray(h.evidence_against) && h.evidence_against.length > 0) {
+      for (const ev of h.evidence_against) lines.push(`  - against: ${typeof ev === 'string' ? ev : JSON.stringify(ev)}`);
+    }
+    if (h.next_to_try) lines.push(`  - next_to_try: ${h.next_to_try}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+function buildCodexPrompt(bugDescription, reproTest, currentDiff, hypotheses) {
+  return [
+    '# Bug-fix second opinion (read-only)',
+    '',
+    'You are Codex acting as a second opinion on a stuck bug-fix loop. Do NOT modify any files. Output a structured review.',
+    '',
+    '## Bug description',
+    '',
+    bugDescription || '(no description provided)',
+    '',
+    '## Reproducer test',
+    '',
+    '```',
+    reproTest || '(no repro provided)',
+    '```',
+    '',
+    '## Current working diff',
+    '',
+    '```diff',
+    currentDiff || '(no diff yet)',
+    '```',
+    '',
+    formatHypothesisBlock(hypotheses),
+    '',
+    '## Output format',
+    '',
+    'Respond with a JSON object: { "summary": string, "findings": [{ "lens": "general", "file": string|null, "line": number|null, "severity": "must-fix"|"should-fix"|"nit", "finding": string, "confidence": 1-10, "rationale": string }] }.',
+    '',
+    'Focus on hypotheses NOT already attempted above. If you spot a materially new angle, flag it as must-fix with high confidence.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Tier 1 — dispatch Codex for a read-only second opinion on a stuck bug.
+ *
+ * @param {object} stratum         StratumMcpClient (must expose runAgentText)
+ * @param {object} context         { cwd, mode:'bug', bug_code }
+ * @param {string} bugDescription
+ * @param {string} reproTest
+ * @param {string} currentDiff
+ * @param {object[]} hypotheses    ledger entries (readHypotheses output)
+ * @returns {Promise<object>} canonical ReviewResult
+ */
+export async function tier1CodexReview(stratum, context, bugDescription, reproTest, currentDiff, hypotheses) {
+  const codexPrompt = buildCodexPrompt(bugDescription, reproTest, currentDiff, hypotheses ?? []);
+  const rawText = await stratum.runAgentText('codex', codexPrompt, { cwd: context.cwd });
+
+  const review = await normalizeReviewResult(rawText, {
+    agentType: 'codex',
+    lens: 'general',
+    confidenceGate: 7,
+  });
+
+  // Append to ledger as escalation_tier_1.
+  try {
+    const prior = readHypotheses(context.cwd, context.bug_code);
+    // Use max(prior.attempt) + 1 to keep attempt numbers monotonic — using
+    // length+1 caused collisions with diagnose-success entries written
+    // concurrently across retries.
+    const maxAttempt = prior.reduce((acc, e) => Math.max(acc, Number(e.attempt) || 0), 0);
+    const attempt = maxAttempt + 1;
+    appendHypothesisEntry(context.cwd, context.bug_code, {
+      attempt,
+      ts: new Date().toISOString(),
+      hypothesis: review.summary || (review.findings[0]?.finding ?? '(codex returned no summary)'),
+      verdict: 'escalation_tier_1',
+      agent: 'codex',
+      findings: review.findings,
+    });
+  } catch (err) {
+    // Best-effort: ledger I/O must not abort the escalation flow.
+    // eslint-disable-next-line no-console
+    console.warn(`[bug-escalation] tier1 ledger append failed: ${err?.message || err}`);
+  }
+
+  return review;
+}
+
+// ---------------------------------------------------------------------------
+// Tier 2 — Fresh agent in worktree (patch-only)
+// ---------------------------------------------------------------------------
+
+const WORKTREE_BASE = join(homedir(), '.stratum', 'worktrees', 'comp-fix-hard');
+
+/**
+ * Determine whether Codex's hypothesis is "materially new" — i.e., not already
+ * in the ledger with verdict 'rejected'. Comparison is normalized token-overlap
+ * (Jaccard); substring containment was too aggressive — short rejected entries
+ * like "race condition" suppressed any future Codex angle that mentioned them.
+ */
+function tokenize(s) {
+  return new Set(
+    String(s ?? '')
+      .toLowerCase()
+      .replace(/[^\p{L}\p{N}\s]/gu, ' ')
+      .split(/\s+/)
+      .filter(t => t.length >= 3)  // drop stopwords-like noise
+  );
+}
+
+function jaccard(a, b) {
+  if (a.size === 0 || b.size === 0) return 0;
+  let overlap = 0;
+  for (const t of a) if (b.has(t)) overlap++;
+  return overlap / (a.size + b.size - overlap);
+}
+
+const SAME_HYPOTHESIS_THRESHOLD = 0.7;
+
+function isMateriallyNew(codexReview, ledgerEntries) {
+  const codexHyp = codexReview?.summary ?? codexReview?.findings?.[0]?.finding ?? '';
+  const codexTokens = tokenize(codexHyp);
+  // Un-tokenizable summary (e.g. terse "OOM", numeric-only) → treat as novel.
+  // Returning false here would silently suppress Tier 2 for any short Codex
+  // hypothesis that didn't survive the length≥3 filter.
+  if (codexTokens.size === 0) return true;
+  for (const e of ledgerEntries ?? []) {
+    if (e?.verdict !== 'rejected') continue;
+    const priorTokens = tokenize(e.hypothesis);
+    if (priorTokens.size === 0) continue;
+    if (jaccard(codexTokens, priorTokens) >= SAME_HYPOTHESIS_THRESHOLD) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Pick the next escalation-patch-N.md filename, counting existing ones in
+ * docs/bugs/<bug-code>/.
+ */
+function nextPatchPath(cwd, bugCode) {
+  const bugDir = join(cwd, 'docs', 'bugs', bugCode);
+  let n = 1;
+  if (existsSync(bugDir)) {
+    const existing = readdirSync(bugDir).filter(f => /^escalation-patch-(\d+)\.md$/.test(f));
+    if (existing.length > 0) {
+      const max = existing.reduce((acc, name) => {
+        const m = name.match(/^escalation-patch-(\d+)\.md$/);
+        const num = m ? parseInt(m[1], 10) : 0;
+        return num > acc ? num : acc;
+      }, 0);
+      n = max + 1;
+    }
+  }
+  return join(bugDir, `escalation-patch-${n}.md`);
+}
+
+function buildFreshAgentPrompt(bugCode, codexReview, hypotheses, patchPath, checkpointPath) {
+  return [
+    '# Fresh-agent escalation (patch-only, NO COMMITS)',
+    '',
+    `You are a fresh agent dispatched to investigate bug **${bugCode}** with no prior context from the original session.`,
+    '',
+    '## Hard rules',
+    '',
+    '1. **DO NOT commit.** Do not run `git commit` or `git add` under any circumstances.',
+    '2. **DO NOT push.** Do not modify the remote.',
+    `3. Produce a single artifact at \`${patchPath}\` describing the proposed patch (diff + reasoning) and STOP.`,
+    '4. The original session will review your artifact and decide whether to apply it.',
+    '',
+    '## Codex second-opinion review',
+    '',
+    `Summary: ${codexReview?.summary ?? '(no summary)'}`,
+    '',
+    'Findings:',
+    ...((codexReview?.findings ?? []).map(f => `- [${f.severity}] ${f.file ?? '(no file)'}:${f.line ?? '?'} — ${f.finding}`)),
+    '',
+    formatHypothesisBlock(hypotheses ?? []),
+    '',
+    checkpointPath ? `## Checkpoint reference\n\nSee ${checkpointPath} for prior context.\n` : '',
+    '## Output',
+    '',
+    `Write to ${patchPath}:`,
+    '- A unified diff of your proposed change',
+    '- Reasoning: why this addresses the Codex finding without retreading rejected hypotheses',
+    '- Risk notes: blast radius and rollback steps',
+    '',
+    'Then STOP.',
+    '',
+  ].join('\n');
+}
+
+/**
+ * Tier 2 — dispatch a fresh agent in an isolated git worktree to draft a
+ * patch (no commits). Cleanup is guaranteed via finally.
+ *
+ * @param {object} stratum
+ * @param {object} context           { cwd, mode:'bug', bug_code }
+ * @param {object} codexReview       output of tier1CodexReview
+ * @param {object[]} hypotheses      ledger entries (readHypotheses output)
+ * @param {string|null} checkpointPath
+ * @returns {Promise<{skipped?: boolean, reason?: string, patch_path?: string, agent_reasoning?: string}>}
+ */
+export async function tier2FreshAgent(stratum, context, codexReview, hypotheses, checkpointPath) {
+  // Materially-new gate — load ledger fresh in case caller passed stale data.
+  let ledger = hypotheses;
+  if (!Array.isArray(ledger) || ledger.length === 0) {
+    try { ledger = readHypotheses(context.cwd, context.bug_code); } catch { ledger = []; }
+  }
+  if (!isMateriallyNew(codexReview, ledger)) {
+    return { skipped: true, reason: 'no new hypothesis (codex matches a previously rejected entry)' };
+  }
+
+  // Compute patch artifact path BEFORE creating the worktree, so the agent
+  // prompt references the same path that we report back to the caller.
+  const patchPath = nextPatchPath(context.cwd, context.bug_code);
+
+  // Create the detached worktree.
+  const ts = new Date().toISOString().replace(/[:.]/g, '-');
+  const wtPath = join(WORKTREE_BASE, `${context.bug_code}-${ts}`);
+  // mkdir -p the parent (homedir() always exists; .stratum/worktrees may not)
+  try {
+    execSync(`mkdir -p "${WORKTREE_BASE}"`, { encoding: 'utf-8', timeout: 5000 });
+  } catch { /* best-effort */ }
+
+  // git worktree add can partially succeed (creates dir, fails registration).
+  // Wrap so we rm -rf the lingering dir before rethrowing.
+  try {
+    execSync(`git worktree add "${wtPath}" --detach HEAD`, {
+      cwd: context.cwd, encoding: 'utf-8', timeout: 30_000, stdio: 'pipe',
+    });
+  } catch (err) {
+    try { execSync(`rm -rf "${wtPath}"`, { encoding: 'utf-8', timeout: 10_000 }); } catch { /* best-effort */ }
+    throw err;
+  }
+
+  try {
+    const prompt = buildFreshAgentPrompt(
+      context.bug_code,
+      codexReview,
+      ledger,
+      patchPath,
+      checkpointPath,
+    );
+    const agent_reasoning = await stratum.runAgentText('claude', prompt, { cwd: wtPath });
+    return { patch_path: patchPath, agent_reasoning: agent_reasoning ?? '' };
+  } finally {
+    try {
+      execSync(`git worktree remove "${wtPath}" --force`, {
+        cwd: context.cwd, encoding: 'utf-8', timeout: 30_000, stdio: 'pipe',
+      });
+    } catch {
+      // If `git worktree remove` fails (e.g. cwd no longer a git repo in tests),
+      // fall back to `rm -rf` so the worktree dir doesn't linger.
+      try { execSync(`rm -rf "${wtPath}"`, { encoding: 'utf-8', timeout: 10_000 }); } catch { /* give up */ }
+    }
+  }
+}

package/lib/bug-index-gen.js

@@ -0,0 +1,136 @@
+/**
+ * bug-index-gen.js — Generate docs/bugs/INDEX.md from per-bug checkpoint.md files.
+ *
+ * Per-bug `docs/bugs/<code>/checkpoint.md` files are the source of truth.
+ * INDEX.md is a rendered view, atomically written so concurrent invocations
+ * don't clobber each other.
+ *
+ * Mirrors the rendering style of `lib/roadmap-gen.js`.
+ */
+
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  statSync,
+  writeFileSync,
+  unlinkSync,
+} from 'node:fs';
+import { join } from 'node:path';
+
+const HEADER = '# Bugs Index\n\nGenerated by compose. Do not edit by hand.\n\n';
+const NO_ATTEMPT = '(no attempts yet)';
+
+/**
+ * Extract the `**Time:** <iso>` line from a checkpoint.md body.
+ *
+ * @param {string} body
+ * @returns {string | null}
+ */
+function extractCheckpointTime(body) {
+  const m = body.match(/^\*\*Time:\*\*\s*(.+)$/m);
+  return m ? m[1].trim() : null;
+}
+
+/**
+ * Collect metadata for a single bug folder.
+ *
+ * @param {string} bugsDir
+ * @param {string} code
+ * @returns {{ code: string, lastAttempt: string|null, openSince: string, status: 'OPEN'|'CLOSED', sortKey: number }}
+ */
+function readBugMeta(bugsDir, code) {
+  const dir = join(bugsDir, code);
+  const checkpointPath = join(dir, 'checkpoint.md');
+  const closedPath = join(dir, 'closed.md');
+
+  let lastAttempt = null;
+  let openSinceMs;
+
+  if (existsSync(checkpointPath)) {
+    const body = readFileSync(checkpointPath, 'utf-8');
+    lastAttempt = extractCheckpointTime(body);
+    try {
+      openSinceMs = statSync(checkpointPath).mtimeMs;
+    } catch {
+      openSinceMs = statSync(dir).mtimeMs;
+    }
+  } else {
+    openSinceMs = statSync(dir).mtimeMs;
+  }
+
+  const status = existsSync(closedPath) ? 'CLOSED' : 'OPEN';
+
+  // Sort key: parsed ISO time of last attempt; missing → 0 (sorts last in desc).
+  let sortKey = 0;
+  if (lastAttempt) {
+    const t = Date.parse(lastAttempt);
+    if (!Number.isNaN(t)) sortKey = t;
+  }
+
+  return {
+    code,
+    lastAttempt,
+    openSince: new Date(openSinceMs).toISOString(),
+    status,
+    sortKey,
+  };
+}
+
+/**
+ * Render the markdown table from collected bug metadata.
+ *
+ * @param {ReturnType<typeof readBugMeta>[]} entries
+ * @returns {string}
+ */
+function renderTable(entries) {
+  const lines = [
+    '| Bug | Last attempt | Open since | Status |',
+    '|-----|--------------|------------|--------|',
+  ];
+  for (const e of entries) {
+    const last = e.lastAttempt ?? NO_ATTEMPT;
+    const since = e.lastAttempt ? e.openSince : NO_ATTEMPT;
+    lines.push(`| ${e.code} | ${last} | ${since} | ${e.status} |`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+/**
+ * Regenerate `docs/bugs/INDEX.md` from per-bug checkpoint files.
+ *
+ * No-op when `docs/bugs/` doesn't exist. Writes atomically via tmp+rename
+ * so concurrent invocations don't clobber a half-written file.
+ *
+ * @param {string} cwd - Project root
+ * @returns {void}
+ */
+export function regenerateBugIndex(cwd) {
+  const bugsDir = join(cwd, 'docs', 'bugs');
+  if (!existsSync(bugsDir)) return;
+
+  const dirents = readdirSync(bugsDir, { withFileTypes: true });
+  const codes = dirents
+    .filter(d => d.isDirectory())
+    .map(d => d.name)
+    .filter(name => !name.startsWith('.'));
+
+  const entries = codes.map(code => readBugMeta(bugsDir, code));
+
+  // Sort by Last attempt desc; bugs with no attempts (sortKey 0) go last.
+  entries.sort((a, b) => b.sortKey - a.sortKey);
+
+  const content = HEADER + renderTable(entries);
+
+  const indexPath = join(bugsDir, 'INDEX.md');
+  const tmpPath = join(bugsDir, 'INDEX.md.tmp');
+
+  // Clear any stale tmp from a previously-crashed run before writing.
+  if (existsSync(tmpPath)) {
+    try { unlinkSync(tmpPath); } catch { /* ignore */ }
+  }
+
+  writeFileSync(tmpPath, content);
+  renameSync(tmpPath, indexPath);
+}