hypomnema 1.0.1 → 1.2.0

package/hooks/hypo-personal-check.mjs

@@ -3,111 +3,106 @@
  * hypo-personal-check.mjs — PreCompact hook
  *
  * Hard gate before /compact. Blocks if:
- *   - last substantial wiki op is not a session close
+ *   - the session-close memory files were not updated this session (fix #17:
+ *     session-state.md, project hot.md, root hot.md, session-log, log.md)
  *   - wiki git repo has uncommitted/unpushed changes
  *   - hot.md has forbidden structure
  *   - lint blockers exist
  *
- * Bypass options (checked in order, short-circuits before heavy checks):
- *   1. wiki-context-critical.json exists (context ≥ 90% — hard limit imminent)
- *   2. HYPO_SKIP_GATE=1 env var
- *   3. HYPO_SKIP_GATE=1 in a recent *user-role* transcript message
+ * Bypass options (checked in order, per ADR 0022 / spec §7.5):
+ *   1. HYPO_SKIP_GATE=1 env var
+ *   2. HYPO_SKIP_GATE=1 in a recent *user-role* transcript message
  *      (assistant/tool output is excluded to prevent self-triggering from block reason text)
+ *
+ * NOTE: capacity bypass (wiki-context-critical.json ≥90%) was REMOVED by fix #26
+ * (ADR 0022 amendment 2026-05-13). Spec §7.5: even at full context, minimal
+ * session-close is mandatory — auto-bypass on capacity caused silent state loss.
  */
 
 import { spawnSync } from 'child_process';
 import { join } from 'path';
-import { readFileSync, existsSync, unlinkSync } from 'fs';
+import { existsSync, unlinkSync } from 'fs';
 import { homedir } from 'os';
 import {
   HYPO_DIR,
   PKG_ROOT,
-  lastSubstantialOpIsSession,
   hypoIsClean,
   hotMdIsClean,
+  sessionCloseFileStatus,
   readChecklist,
   isGateSkipped,
+  isClosePattern,
+  extractUserMessages,
 } from './hypo-shared.mjs';
 
-const CRITICAL_FILE = join(homedir(), '.claude', 'state', 'wiki-context-critical.json');
-const WARNING_FILE  = join(homedir(), '.claude', 'state', 'wiki-context-warning.json');
-
-/** Parse JSONL transcript and return concatenated text of user-role messages only.
- *
- * Claude Code transcript format: each line is `{ type: "user", message: { role: "user", content: ... } }`.
- * Older shape (`{ role, content }` at top level) is also accepted for forward compatibility.
- */
-function extractUserMessages(transcriptPath) {
-  try {
-    const lines = readFileSync(transcriptPath, 'utf-8').split('\n');
-    const tail = lines.slice(-30); // last 30 lines is enough
-    return tail.map(line => {
-      try {
-        const obj = JSON.parse(line);
-        const msg = obj.message ?? obj;
-        const role = msg.role ?? obj.role ?? obj.type;
-        if (role !== 'user') return '';
-        const content = msg.content ?? obj.content;
-        return typeof content === 'string' ? content : JSON.stringify(content);
-      } catch { return ''; }
-    }).join('\n');
-  } catch { return ''; }
-}
+const WARNING_FILE = join(homedir(), '.claude', 'state', 'wiki-context-warning.json');
 
 let raw = '';
 process.stdin.setEncoding('utf-8');
-process.stdin.on('data', chunk => raw += chunk);
+process.stdin.on('data', (chunk) => (raw += chunk));
 process.stdin.on('end', () => {
   let transcriptPath = null;
   try {
     const input = JSON.parse(raw || '{}');
     transcriptPath = input.transcript_path ?? null;
-  } catch { /* fail-open */ }
-
-  // ── Bypass 1: context critical (≥90%) — short-circuit BEFORE all checks ──
-  if (existsSync(CRITICAL_FILE)) {
-    try { unlinkSync(CRITICAL_FILE); } catch {}
-    console.log(JSON.stringify({
-      continue: true,
-      systemMessage: '[WIKI CHECK] gate auto-bypassed (context ≥90% critical). Session close pending next session.',
-    }));
-    return;
+  } catch {
+    /* fail-open */
   }
 
+  // ── Capacity bypass (≥90%) REMOVED — fix #26, ADR 0022 amendment 2026-05-13.
+  //    Even at full context, minimal session-close is mandatory (spec §7.5).
+  //    Bypass paths are now only: HYPO_SKIP_GATE env / HYPO_SKIP_GATE in transcript.
+
   // ── Block 1.5: context warning (≥70%) — request session-compact before compact ──
   if (existsSync(WARNING_FILE)) {
-    try { unlinkSync(WARNING_FILE); } catch {}
-    console.log(JSON.stringify({
-      decision: 'block',
-      reason: [
-        `[WIKI CHECK — BLOCKING] Context ≥70%: run /session-compact before compacting.`,
-        `STOP. Do NOT compact yet.`,
-        `1. If Skill tool is available: call it with skill="session-compact" immediately.`,
-        `2. If Skill tool is unavailable: perform the full session-close checklist from hypo-guide.md.`,
-        `After session close completes, compact will proceed normally.`,
-        ``,
-        `To skip: set HYPO_SKIP_GATE=1`,
-      ].join('\n'),
-    }));
+    try {
+      unlinkSync(WARNING_FILE);
+    } catch {}
+    console.log(
+      JSON.stringify({
+        decision: 'block',
+        reason: [
+          `[WIKI CHECK — BLOCKING] Context ≥70%: run /session-compact before compacting.`,
+          `STOP. Do NOT compact yet.`,
+          `1. If Skill tool is available: call it with skill="session-compact" immediately.`,
+          `2. If Skill tool is unavailable: perform the full session-close checklist from hypo-guide.md.`,
+          `After session close completes, compact will proceed normally.`,
+          ``,
+          `To skip: set HYPO_SKIP_GATE=1`,
+        ].join('\n'),
+      }),
+    );
     return;
   }
 
-  // ── Bypass 2: env var ──
-  if (!isGateSkipped() && transcriptPath && existsSync(transcriptPath)) {
-    // Only scan user-role messages to avoid matching the block reason text
-    // which itself contains "Bypass with HYPO_SKIP_GATE=1"
+  // ── Transcript scan (Bypass 2 + #20 close-intent detection) ──
+  let hasCloseIntent = false;
+  if (transcriptPath && existsSync(transcriptPath)) {
     const userText = extractUserMessages(transcriptPath);
-    if (/HYPO_SKIP_GATE=1/.test(userText)) {
+    // Bypass 2: user-role "HYPO_SKIP_GATE=1" (scan before gate so bypass takes effect)
+    if (!isGateSkipped() && /HYPO_SKIP_GATE=1/.test(userText)) {
       process.env.HYPO_SKIP_GATE = '1';
     }
+    // #20: natural-language close-intent detection (informational — enriches block message)
+    hasCloseIntent = isClosePattern(userText);
   }
 
   // ── Heavy checks ──
   const today = new Date().toISOString().slice(0, 10);
 
-  const hasSession = lastSubstantialOpIsSession();
-  const gitStatus  = hypoIsClean();
-  const hotStatus  = hotMdIsClean();
+  const gitStatus = hypoIsClean();
+  const hotStatus = hotMdIsClean();
+  // fix #17: strict session-close (steps 1~6 of the 11-step crystallize
+  // checklist). closeFiles gates the 5 mandatory files (steps 1-4 + log.md);
+  // open-questions.md (step 5) is conditional ("변경 시") and intentionally
+  // ungated — see hypo-shared.mjs sessionCloseFileStatus and spec §5.2.7.
+  const closeFiles = sessionCloseFileStatus(HYPO_DIR);
+  const closeFilesReason = closeFiles.ok
+    ? ''
+    : `memory files not updated this session: ${[
+        ...closeFiles.missing.map((f) => `${f} (missing)`),
+        ...closeFiles.stale.map((f) => `${f} (stale)`),
+      ].join(', ')}`;
 
   const lintPath = PKG_ROOT ? join(PKG_ROOT, 'scripts', 'lint.mjs') : null;
   let lintBlockers = [];
@@ -124,14 +119,97 @@ process.stdin.on('end', () => {
       });
       const parsed = JSON.parse(r.stdout || '{}');
       lintBlockers = parsed.errors || [];
-      lintW8 = (parsed.warns || []).filter(w => w.id === 'W8');
-    } catch { /* fail-open */ }
+      lintW8 = (parsed.warns || []).filter((w) => w.id === 'W8');
+    } catch (err) {
+      /* fail-open */
+      process.stderr.write(`[hypo-personal-check] error: ${err?.message ?? String(err)}\n`);
+    }
   }
 
-  const lintOk          = lintBlockers.length === 0;
+  const lintOk = lintBlockers.length === 0;
   const designHistoryOk = lintW8.length === 0;
 
-  if (hasSession && gitStatus.clean && hotStatus.clean && lintOk && designHistoryOk) {
+  // ── fix #37 Phase C: feedback projection drift (ADR 0031) ──
+  // Single blocking gate invariant (spec §7.5): integrate into THIS hook, never
+  // add a separate PreCompact hook. `feedback-sync --check --strict` reports
+  // projection drift (wiki feedback SoT vs MEMORY / CLAUDE.md learned-behaviors
+  // projection). `--no-input` keeps this non-TTY hook from ever blocking on a
+  // prompt, and the engine's skip-MEMORY warning is *soft* (never escalated by
+  // --strict) so a fresh / external user whose ~/.claude/projects/<id> dir does
+  // not exist yet is never gated (contract §5 step 4). Fail-open on any spawn
+  // error, exactly like the lint check above.
+  const feedbackPath = PKG_ROOT ? join(PKG_ROOT, 'scripts', 'feedback-sync.mjs') : null;
+  let feedbackOk = true;
+  let feedbackReason = '';
+  let feedbackSkipped = false;
+  if (!feedbackPath || !existsSync(feedbackPath)) {
+    feedbackSkipped = true;
+  } else {
+    try {
+      const r = spawnSync(
+        process.execPath,
+        [
+          feedbackPath,
+          '--check',
+          '--strict',
+          '--no-input',
+          '--json',
+          `--hypo-dir=${HYPO_DIR}`,
+          `--claude-home=${join(homedir(), '.claude')}`,
+        ],
+        { encoding: 'utf-8', timeout: 30000 },
+      );
+      if (r.error || r.status === null) {
+        feedbackSkipped = true; // spawn failure → fail-open (never block on tooling)
+      } else if (r.status !== 0) {
+        // exit≠0 alone is ambiguous. A *missing* target file (e.g. a system
+        // whose ~/.claude/CLAUDE.md was never created) reports buildError +
+        // exit 1, which is benign — there is nothing to gate. Decide from the
+        // JSON report's per-target state instead of the raw exit code: block
+        // ONLY when some target has a genuine, actionable issue (drift,
+        // conflict, over-cap, or a malformed managed region). buildError is
+        // never actionable here, so any mix that lacks a real issue fails open
+        // — including memory:clean + claude:buildError (codex review: the prior
+        // `every(buildError)` predicate wrongly blocked that case). Mirrors
+        // doctor's buildError→warn (non-fatal) handling.
+        let report = null;
+        try {
+          report = JSON.parse(r.stdout || '');
+        } catch {
+          /* unparseable → fail-open below */
+        }
+        const targets = report ? Object.values(report.targets || {}) : [];
+        const conflicted = targets.some(
+          (t) =>
+            t.intruder || t.unpaired || t.outOfContainer || (t.conflicts && t.conflicts.length),
+        );
+        const overCap = targets.some((t) => t.overCap);
+        const drifted = targets.some((t) => t.dirty);
+        if (!report || !(conflicted || overCap || drifted)) {
+          feedbackSkipped = true; // missing target / pure warning / unparseable → fail-open
+        } else {
+          feedbackOk = false;
+          feedbackReason = conflicted
+            ? 'feedback projection conflict (manual edit) — run `hypomnema feedback-sync --import-target-change --from=<memory|claude>`'
+            : overCap
+              ? 'feedback projection over cap — demote/archive feedback pages'
+              : 'feedback projection drift — run `hypomnema feedback-sync --write`';
+        }
+      }
+    } catch (err) {
+      feedbackSkipped = true;
+      process.stderr.write(`[hypo-personal-check] error: ${err?.message ?? String(err)}\n`);
+    }
+  }
+
+  if (
+    gitStatus.clean &&
+    hotStatus.clean &&
+    lintOk &&
+    designHistoryOk &&
+    closeFiles.ok &&
+    feedbackOk
+  ) {
     console.log(JSON.stringify({ continue: true, suppressOutput: true }));
     return;
   }
@@ -139,57 +217,74 @@ process.stdin.on('end', () => {
   // ── Bypass 3: HYPO_SKIP_GATE ──
   if (isGateSkipped()) {
     const skipped = [
-      !hasSession      ? 'session log missing'                      : '',
-      !gitStatus.clean ? gitStatus.reason                           : '',
-      !hotStatus.clean ? hotStatus.reason                           : '',
+      !gitStatus.clean ? gitStatus.reason : '',
+      !hotStatus.clean ? hotStatus.reason : '',
+      !closeFiles.ok ? closeFilesReason : '',
       !designHistoryOk ? `design-history stale (${lintW8.length})` : '',
-      lintSkipped      ? 'lint skipped (hypo-pkg.json missing)'     : '',
-    ].filter(Boolean).join(', ');
-    console.log(JSON.stringify({
-      continue: true,
-      systemMessage: `[WIKI CHECK] gate bypassed via HYPO_SKIP_GATE=1 (incomplete: ${skipped}).`,
-    }));
+      !feedbackOk ? feedbackReason : '',
+      lintSkipped ? 'lint skipped (hypo-pkg.json missing)' : '',
+      feedbackSkipped ? 'feedback-sync skipped (hypo-pkg.json missing)' : '',
+    ]
+      .filter(Boolean)
+      .join(', ');
+    console.log(
+      JSON.stringify({
+        continue: true,
+        systemMessage: `[WIKI CHECK] gate bypassed via HYPO_SKIP_GATE=1 (incomplete: ${skipped}).`,
+      }),
+    );
     return;
   }
 
   // ── Block ──
   const reasons = [
-    !hasSession      ? 'session log entry missing'                                                   : '',
-    !gitStatus.clean ? gitStatus.reason                                                              : '',
-    !hotStatus.clean ? hotStatus.reason                                                              : '',
-    !lintOk          ? `lint blockers: ${lintBlockers.map(b => b.id).join(', ')}`                   : '',
-    !designHistoryOk ? `design-history stale: ${lintW8.map(w => w.file.split('/')[1]).join(', ')}` : '',
-    lintSkipped      ? 'lint skipped (run `hypomnema init` to enable lint gate)'                    : '',
+    !gitStatus.clean ? gitStatus.reason : '',
+    !hotStatus.clean ? hotStatus.reason : '',
+    !closeFiles.ok ? closeFilesReason : '',
+    !lintOk ? `lint blockers: ${lintBlockers.map((b) => b.id).join(', ')}` : '',
+    !designHistoryOk
+      ? `design-history stale: ${lintW8.map((w) => w.file.split('/')[1]).join(', ')}`
+      : '',
+    !feedbackOk ? feedbackReason : '',
+    lintSkipped ? 'lint skipped (run `hypomnema init` to enable lint gate)' : '',
   ].filter(Boolean);
 
-  const checklist     = readChecklist(today);
-  const checklistText = checklist ?? [
-    `  [ ] 0. Read SCHEMA.md + hypo-guide.md (required before wiki work)`,
-    `  [ ] 1. PRD       — create projects/<name>/prd.md if missing`,
-    `  [ ] 2. ADR       — decide yes/no on 5 types; if all N, note "no ADR — reason: <why>"`,
-    `  [ ] 3. Ingest    — if new external knowledge, save to sources/ and ingest`,
-    `  [ ] 4. Pages     — extract new concepts/patterns to pages/`,
-    `  [ ] 5. Synthesis — if 3+ cross-page analysis results, save to pages/syntheses/`,
-    `  [ ] 6. session-log — append to projects/<name>/session-log/YYYY-MM.md`,
-    `  [ ] 7. index.md  — update Projects section if needed`,
-    `  [ ] 8. log.md    — append ## [${today}] session | <project-name>`,
-    `  [ ] 9. hot.md    — update projects/<name>/hot.md (no exceptions)`,
-    `  [ ] 10. root hot.md — update ~/hypomnema/hot.md active project table`,
-    `  [ ] 11. updated: field — verify today's date on all touched .md files`,
-    `  [ ] 12. git commit & push`,
-  ].join('\n');
-
-  console.log(JSON.stringify({
-    decision: 'block',
-    reason: [
-      `[WIKI CHECK — BLOCKING] Session close incomplete. (${reasons.join(', ')})`,
-      `Run the checklist below in order, then retry /compact:`,
-      ``,
-      checklistText,
-      ``,
-      `Trivial session? Bypass with HYPO_SKIP_GATE=1`,
-    ].join('\n'),
-    continue: false,
-    stopReason: `Session close incomplete: ${reasons.join(', ')}`,
-  }));
+  const checklist = readChecklist(today);
+  const checklistText =
+    checklist ??
+    [
+      `  [ ] 0. Read SCHEMA.md + hypo-guide.md (required before wiki work)`,
+      `  [ ] 1. PRD       — create projects/<name>/prd.md if missing`,
+      `  [ ] 2. ADR       — decide yes/no on 5 types; if all N, note "no ADR — reason: <why>"`,
+      `  [ ] 3. Ingest    — if new external knowledge, save to sources/ and ingest`,
+      `  [ ] 4. Pages     — extract new concepts/patterns to pages/`,
+      `  [ ] 5. Synthesis — if 3+ cross-page analysis results, save to pages/syntheses/`,
+      `  [ ] 6. session-log — append to projects/<name>/session-log/YYYY-MM.md`,
+      `  [ ] 7. index.md  — update Projects section if needed`,
+      `  [ ] 8. log.md    — append ## [${today}] session | <project-name>`,
+      `  [ ] 9. hot.md    — update projects/<name>/hot.md (no exceptions)`,
+      `  [ ] 10. root hot.md — update ~/hypomnema/hot.md active project table`,
+      `  [ ] 11. updated: field — verify today's date on all touched .md files`,
+      `  [ ] 12. git commit & push`,
+    ].join('\n');
+
+  const closeIntentNote = hasCloseIntent
+    ? `[Close intent detected in recent messages — completing session close first.]\n`
+    : '';
+
+  console.log(
+    JSON.stringify({
+      decision: 'block',
+      reason: [
+        `${closeIntentNote}[WIKI CHECK — BLOCKING] Session close incomplete. (${reasons.join(', ')})`,
+        `Run the checklist below in order, then retry /compact:`,
+        ``,
+        checklistText,
+        ``,
+        `Trivial session? Bypass with HYPO_SKIP_GATE=1`,
+      ].join('\n'),
+      continue: false,
+      stopReason: `Session close incomplete: ${reasons.join(', ')}`,
+    }),
+  );
 });

package/hooks/hypo-pre-commit.mjs

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/**
+ * hypo-pre-commit.mjs — wiki git pre-commit hook worker (§6.8 fix #24)
+ *
+ * Blocks staged files that match .hypoignore patterns.
+ * Installed by `hypo init` to <wiki>/.git/hooks/pre-commit.
+ * The shell wrapper in that file calls: node <pkgRoot>/hooks/hypo-pre-commit.mjs
+ */
+
+import { spawnSync } from 'child_process';
+import { join } from 'path';
+import { loadHypoIgnore, isIgnored } from '../scripts/lib/hypo-ignore.mjs';
+
+// Detect wiki root = git top-level of the wiki repo
+const gitRoot = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf-8' });
+if (gitRoot.status !== 0) process.exit(0);
+
+const hypoDir = gitRoot.stdout.replace(/\r?\n$/, '');
+
+// Get staged files (NUL-separated for safe handling of special chars)
+const staged = spawnSync('git', ['diff', '--cached', '--name-only', '-z'], {
+  encoding: 'utf-8',
+  cwd: hypoDir,
+});
+if (staged.status !== 0 || !staged.stdout) process.exit(0);
+
+const files = staged.stdout
+  .split('\0')
+  .filter(Boolean)
+  .map((f) => join(hypoDir, f));
+const patterns = loadHypoIgnore(hypoDir);
+
+if (patterns.length === 0) process.exit(0);
+
+const blocked = files.filter((f) => isIgnored(f, hypoDir, patterns));
+if (blocked.length === 0) process.exit(0);
+
+const rel = blocked.map((f) => f.slice(hypoDir.length + 1));
+process.stderr.write(
+  `[hypo] Commit blocked — staged files match .hypoignore patterns:\n` +
+    rel.map((f) => `  ${f}`).join('\n') +
+    '\n' +
+    `\nUnstage with: git restore --staged <file>\n` +
+    `Override (at your own risk): git commit --no-verify\n`,
+);
+process.exit(1);

package/hooks/hypo-session-end.mjs

@@ -0,0 +1,58 @@
+#!/usr/bin/env node
+/**
+ * hypo-session-end.mjs — SessionEnd hook (fix #25 PR-A2, ADR 0022 Layer 2)
+ *
+ * `/clear` cannot be blocked: it never fires UserPromptSubmit (Stage 0 PoC,
+ * 2026-05-14). The only intervention point is the SessionEnd(reason='clear')
+ * → SessionStart(source='clear') pair. This hook captures the dying session's
+ * identity into `.cache/clear-marker.json` so hypo-session-start can issue a
+ * recovery nudge on the next session.
+ *
+ * Scope: writing the marker on reason='clear' only. Other reasons
+ * ('prompt_input_exit', 'logout', etc.) are deliberate user exits and need no
+ * recovery — touching them would pollute the unrelated next session.
+ *
+ * Silent: never blocks, never emits user-visible output. Failures are stderr
+ * debug lines only.
+ */
+
+import { HYPO_DIR, writeClearMarker } from './hypo-shared.mjs';
+import { existsSync } from 'fs';
+
+function emitContinue() {
+  console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+}
+
+let raw = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => (raw += chunk));
+process.stdin.on('end', () => {
+  try {
+    let payload = {};
+    try {
+      payload = JSON.parse(raw) || {};
+    } catch {}
+
+    const reason = payload.reason || '';
+    if (reason !== 'clear') {
+      emitContinue();
+      return;
+    }
+
+    // Wiki absent → nothing to recover into; skip silently.
+    if (!existsSync(HYPO_DIR)) {
+      emitContinue();
+      return;
+    }
+
+    writeClearMarker(HYPO_DIR, {
+      prev_session_id: payload.session_id || payload.sessionId || null,
+      prev_transcript_path: payload.transcript_path || payload.transcriptPath || null,
+      prev_cwd: payload.cwd || null,
+    });
+  } catch (err) {
+    // Best-effort: a marker failure must not break /clear itself.
+    process.stderr.write(`[hypo-session-end] error: ${err?.message ?? String(err)}\n`);
+  }
+  emitContinue();
+});

package/hooks/hypo-session-record.mjs

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+/**
+ * hypo-session-record.mjs — Stop hook
+ *
+ * Appends an entry to ~/hypomnema/.cache/sessions/index.jsonl for each
+ * completed session. The index.jsonl is the **primary** source for
+ * scripts/session-audit.mjs (which falls back to ~/.claude/projects/<encoded>/
+ * if the index is empty or missing — see ADR 0019).
+ *
+ * Silent: never blocks, never emits user-visible output.
+ */
+
+import { existsSync, mkdirSync, appendFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { HYPO_DIR } from './hypo-shared.mjs';
+
+const INDEX_PATH = join(HYPO_DIR, '.cache', 'sessions', 'index.jsonl');
+
+function emitContinue() {
+  console.log(JSON.stringify({ continue: true, suppressOutput: true }));
+}
+
+let raw = '';
+process.stdin.setEncoding('utf-8');
+process.stdin.on('data', (chunk) => (raw += chunk));
+process.stdin.on('end', () => {
+  try {
+    let payload = {};
+    try {
+      payload = JSON.parse(raw) || {};
+    } catch {}
+
+    const transcriptPath = payload.transcript_path || payload.transcriptPath || null;
+    const sessionId = payload.session_id || payload.sessionId || null;
+    if (!transcriptPath || !sessionId) {
+      // Older Claude Code (no transcript_path) — fallback path in
+      // scripts/session-audit.mjs handles this case.
+      emitContinue();
+      return;
+    }
+
+    if (!existsSync(HYPO_DIR)) {
+      emitContinue();
+      return;
+    }
+    mkdirSync(dirname(INDEX_PATH), { recursive: true });
+
+    const entry = {
+      session_id: sessionId,
+      transcript_path: transcriptPath,
+      recorded_at: new Date().toISOString(),
+      cwd: payload.cwd || process.cwd(),
+    };
+    appendFileSync(INDEX_PATH, JSON.stringify(entry) + '\n');
+  } catch (err) {
+    // Audit is best-effort observability — never let it block session close.
+    process.stderr.write(`[hypo-session-record] error: ${err?.message ?? String(err)}\n`);
+  }
+  emitContinue();
+});