klypix-mcp 1.61.0 → 1.63.0

package/README.md

@@ -431,6 +431,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `npx klypix-mcp runtime` | Passive per-connection process/RAM attribution (`--json`, optional `--watch seconds`); never kills or deduplicates |
 | `npx klypix-mcp conformance` | Launch two real MCP clients against this build and verify coordination behaviour |
 | `npx klypix-mcp git-driver` | Register the lossless `.klypix` merge driver for a repo (`status` to check) |
+| `npx klypix-mcp git-hook` | Wire the agent-neutral commit-capture hook: rationale-bearing `feat`/`fix`/`perf` commits from any agent, branch, or worktree card into the brain at commit time (`install`/`remove`/`status`; sessions auto-install it where the hook slots are free) |
 | `npx klypix-mcp diff [ref]` | Card-level brain diff against a git ref, as markdown |
 | `npx klypix-mcp pr-brief [ref]` | Brain cards referencing the files changed since a ref, as markdown |
 | `npx klypix-mcp garden-code` | Print the human approval code `brain_garden` requires |

package/bin/klypix-brain-history.mjs

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+// `klypix-mcp brain-history [list|restore <id>|prune] [--brain <path>]`
+// The human surface for brain restore points. Protection nobody can see is
+// protection nobody trusts, so `list` is the default and it says plainly what
+// each point would give back.
+import fs from 'fs';
+import path from 'path';
+import { listBrainHistory, pruneBrainHistory, restoreBrainSnapshot, historyDirFor } from '../src/brain-history.mjs';
+
+const argv = process.argv.slice(2).filter((a) => a !== 'brain-history');
+const action = ['list', 'restore', 'prune'].includes(argv[0]) ? argv.shift() : 'list';
+const brainIdx = argv.indexOf('--brain');
+const brainPath = path.resolve(brainIdx >= 0 && argv[brainIdx + 1] ? argv.splice(brainIdx, 2)[1] : 'brain.klypix');
+const positional = argv.filter((a) => !a.startsWith('-'));
+
+const ago = (ts) => {
+  const m = Math.max(0, Math.round((Date.now() - ts) / 60000));
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h}h ago` : `${Math.round(h / 24)}d ago`;
+};
+const kb = (b) => `${(b / 1024).toFixed(0)} KB`;
+
+// Card counts make a restore point meaningful ("this one still has the 14 cards
+// you deleted"). Parsing ≤20 small zips is fine for a human-invoked command;
+// a parse failure degrades to size only rather than failing the listing.
+async function cardCount(file) {
+  try {
+    const { parseKlypix } = await import('../src/klypix-format.mjs');
+    const { struct } = await parseKlypix(fs.readFileSync(file));
+    return struct?.cards?.length ?? null;
+  } catch { return null; }
+}
+
+if (action === 'list') {
+  const entries = listBrainHistory(brainPath);
+  if (!entries.length) {
+    console.log(`No restore points for ${brainPath}.`);
+    console.log(`They are written automatically before each brain write, to ${historyDirFor(brainPath)}.`);
+    process.exit(0);
+  }
+  const liveExists = fs.existsSync(brainPath);
+  const liveCards = liveExists ? await cardCount(brainPath) : null;
+  console.log(`Restore points for ${brainPath}${liveExists ? '' : '  (the brain itself is MISSING — restore will recreate it)'}`);
+  if (liveCards != null) console.log(`current: ${liveCards} cards, ${kb(fs.statSync(brainPath).size)}\n`);
+  for (const e of entries) {
+    const cards = await cardCount(e.file);
+    const delta = cards != null && liveCards != null ? cards - liveCards : null;
+    const deltaText = delta == null ? '' : delta > 0 ? `  (+${delta} cards vs now)` : delta < 0 ? `  (${delta} cards vs now)` : '  (same card count)';
+    console.log(`  ${e.id}   ${ago(e.ts).padEnd(9)} ${String(cards ?? '?').padStart(5)} cards  ${kb(e.bytes).padStart(8)}${e.reason ? `  [${e.reason}]` : ''}${deltaText}`);
+  }
+  console.log(`\nRestore: npx klypix-mcp brain-history restore <id> --brain "${brainPath}"`);
+  console.log('Restoring snapshots the current file first, so it is itself undoable.');
+  process.exit(0);
+}
+
+if (action === 'prune') {
+  const removed = pruneBrainHistory(brainPath);
+  console.log(`Pruned ${removed} restore point(s) beyond the retention window (newest 20 + one per day for 14 days).`);
+  process.exit(0);
+}
+
+// restore
+const id = positional[0];
+if (!id) {
+  console.error('Usage: npx klypix-mcp brain-history restore <id> [--brain <path>]');
+  console.error('Run `npx klypix-mcp brain-history list` to see the ids.');
+  process.exit(2);
+}
+const { parseKlypix } = await import('../src/klypix-format.mjs');
+const res = await restoreBrainSnapshot(brainPath, id, { parse: parseKlypix });
+if (!res.ok) { console.error(`Restore failed: ${res.error}`); process.exit(1); }
+console.log(`Restored ${brainPath} from ${res.restoredFrom} (${kb(res.bytes)}).`);
+if (res.safetyId) console.log(`The state you just replaced was saved as ${res.safetyId} — undo with: npx klypix-mcp brain-history restore ${res.safetyId}`);
+console.log('If the app has this brain OPEN, close and reopen the tab: its in-memory copy is now older than disk and a save would merge it back.');

package/bin/klypix-git-hook.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+// `klypix-mcp git-hook [install|remove|status] [repo]` — wire the agent-neutral
+// commit-capture hook (brain-git-hook.mjs) into a repo, so rationale-bearing
+// feat/fix/perf commits from ANY agent/branch/worktree card into ./brain.klypix
+// at commit time. Standalone use: node bin/klypix-git-hook.mjs <args>
+import path from 'path';
+import { gitCaptureHookStatus, installGitCaptureHook, removeGitCaptureHook } from '../src/git-capture-install.mjs';
+
+const args = process.argv.slice(2).filter((a) => a !== 'git-hook');
+const action = ['install', 'remove', 'status'].includes(args[0]) ? args[0] : 'status';
+const repo = path.resolve(process.cwd(), args.find((a, i) => i > 0 || !['install', 'remove', 'status'].includes(a)) || '.');
+
+const describe = (s) => `state: ${s.state}${s.hooksDir ? `\nhooks dir: ${s.hooksDir}` : ''}${s.hooks && Object.keys(s.hooks).length
+  ? '\n' + Object.entries(s.hooks).map(([n, st]) => `  ${n}: ${st}`).join('\n') : ''}`;
+
+if (action === 'status') {
+  const s = gitCaptureHookStatus(repo);
+  console.log(describe(s));
+  if (s.state === 'custom-hookspath') console.log('core.hooksPath is set — add the managed block to that hooks dir yourself, or unset it and re-run.');
+  if (s.state === 'foreign') console.log('A non-sh hook occupies the slot — not touched. Chain it manually or convert it to sh.');
+  process.exit(s.state === 'installed' ? 0 : 1);
+} else if (action === 'install') {
+  const r = installGitCaptureHook(repo);
+  if (!r.ok) { console.error(`Not installed: ${r.reason}.`); process.exit(1); }
+  console.log(r.changed.length ? `Installed/updated: ${r.changed.join(', ')} in ${r.hooksDir}` : 'Already current — nothing to change.');
+  if (r.skipped.length) console.log(`Skipped (non-sh foreign hook, not touched): ${r.skipped.join(', ')}`);
+  process.exit(0);
+} else {
+  const r = removeGitCaptureHook(repo);
+  if (!r.ok) { console.error(`Nothing removed: ${r.reason}.`); process.exit(1); }
+  console.log(r.changed.length ? `Removed the managed block from: ${r.changed.join(', ')}` : 'No managed block found — nothing to remove.');
+  process.exit(0);
+}

package/bin/klypix-install.mjs

@@ -226,7 +226,7 @@ const flatten = (code) => code
     .replace(/\.\.\/src\/klypix-(core|format)\.mjs/g, './klypix-$1.mjs')
     // brain-doctor + agent-rules (the server's lazy `import('../src/brain-doctor.mjs')`
     // for the brain_doctor tool) → flat sibling refs in the runtime layout.
-    .replace(/\.\.\/src\/(brain-doctor|agent-rules|mcp-presence|mcp-supervisor|mcp-auto-update|semantic-memory|runtime-inspector|project-graph)\.mjs/g, './$1.mjs')
+    .replace(/\.\.\/src\/(brain-doctor|agent-rules|mcp-presence|mcp-supervisor|mcp-auto-update|semantic-memory|runtime-inspector|project-graph|git-capture-install)\.mjs/g, './$1.mjs')
     .replace(/klypix-worker\.mjs/g, 'klypix-mcp-worker.mjs')
     .replace(/const PKG_VERSION = \(\(\) => \{[\s\S]*?\}\)\(\);/, `const PKG_VERSION = '${VERSION}'; // baked at install (flat layout has no package.json)`);
 
@@ -293,7 +293,7 @@ try {
     // canvas-view-app.html is the canvas_view MCP App UI — staged raw (an HTML
     // file must never get a JS-comment banner) beside the flat server, which
     // resolves it via its ./canvas-view-app.html candidate path.
-    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'finding-routing.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'finding-routing.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'canvas-view-app.html']) {
         const s = path.join(SRC, f); if (exists(s)) staged.push({ dst: f, content: fs.readFileSync(s, 'utf8') });
     }
     for (const [src, dst] of [

package/bin/klypix-mcp.mjs

@@ -19,7 +19,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'diff', 'pr-brief', 'uninstall', 'bench']);
+const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'git-hook', 'brain-history', 'diff', 'pr-brief', 'uninstall', 'bench']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -35,6 +35,8 @@ const USAGE = [
   '  garden-code [brain]                 print the human approval code for brain_garden',
   '  uninstall [--check|--yes|unlink]    remove this install from the machine (--check inventories first; never deletes a .klypix)',
   '  git-driver [install|status] [repo]  register the lossless .klypix merge driver for a repo (zero-command teams)',
+  '  git-hook [install|remove|status]    wire the agent-neutral commit-capture hook (any agent/branch/worktree → brain cards)',
+  '  brain-history [list|restore <id>]   restore points for this brain — undo an accidental delete, edit, or overwrite',
   '  diff [ref] [--brain <path>]         readable brain diff vs a git ref (default HEAD) — markdown to stdout',
   '  pr-brief [baseRef] [--brain <path>] brain decisions touching the files changed since baseRef — PR-comment markdown',
   '',

package/bin/klypix-worker.mjs

@@ -116,6 +116,15 @@ await runVerb('conformance', './klypix-conformance.mjs');
 // git ref, and print the brain cards touching a PR's changed files. One module,
 // three verbs (it reads argv[2] itself).
 await runVerb('git-driver', './klypix-git-driver.mjs');
+// `npx klypix-mcp git-hook` — wire the agent-neutral commit-capture hook
+// (brain-git-hook.mjs) into a repo's post-commit/post-merge, so feat/fix/perf
+// commits with rationale bodies card into the brain from ANY agent, branch, or
+// worktree at commit time (the Stop hook alone is blind to other worktrees).
+await runVerb('git-hook', './klypix-git-hook.mjs');
+// `npx klypix-mcp brain-history` — list/restore the automatic restore points
+// written before every brain write. The recovery path for an accidental card
+// deletion, a destructive edit, a stale overwrite, or a deleted brain file.
+await runVerb('brain-history', './klypix-brain-history.mjs');
 await runVerb('diff', './klypix-diff.mjs');
 await runVerb('pr-brief', './klypix-pr-brief.mjs');
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.61.0",
+  "version": "1.63.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -79,7 +79,7 @@
     "test:project-graph": "node test/project-graph.mjs",
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
-    "test": "node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/agent-presence.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"

package/src/agent-presence.mjs

@@ -119,13 +119,88 @@ export function neutralizeMarkers(text) {
   return String(text || '').replace(/🧠(\s*)(BRAIN|MSG)/gi, '🧠·$2');
 }
 
+// ── Machine-turn intent guard ───────────────────────────────────────────────
+// UserPromptSubmit does not only carry human-typed text: harnesses inject task
+// notifications, system reminders and slash-command wrappers as "user" prompts.
+// One of those stored verbatim became a session's declared intent
+// ("<task-notification> <task-id>…" — 2026-08-07 AgentLit field incident), so
+// every peer surface showed tool-plumbing instead of what the session was doing.
+// deriveIntentFromPrompt() extracts the human intent from a raw prompt, or
+// returns null when the whole turn is machine-generated — callers must then KEEP
+// the previous intent (and may still stamp activity), never store the junk and
+// never clear a good intent because a background task happened to complete.
+const MACHINE_TAGS = 'task-notification|system-reminder|system-warning|local-command-caveat'
+  + '|command-name|command-message|command-args|command-contents|local-command-stdout|local-command-stderr'
+  + '|ide_selection|ide_opened_file|ide_diagnostics|persisted-output|tool-use-error'
+  + '|session-start-hook|user-prompt-submit-hook|post-tool-use-hook|hook-[a-z0-9-]+';
+const MACHINE_BLOCK_RE = new RegExp(
+  '^(?:<(' + MACHINE_TAGS + ')\\b[^>]*>[\\s\\S]*?(?:</\\1>|$)|\\[SYSTEM NOTIFICATION[^\\]]*\\])\\s*', 'i');
+// Tag-shaped start AFTER stripping known blocks: an unrecognized harness tag is
+// far more likely than a human opening a prompt with raw XML, and the cost of
+// failing closed is only "previous intent kept" — never data loss.
+const TAG_SHAPED_RE = /^<[a-z][\w.:-]*(?:\s|\/?>)/i;
+
+export function deriveIntentFromPrompt(raw) {
+  let text = String(raw || '').replace(/\s+/g, ' ').trim();
+  if (!text) return null;
+  // A "[SYSTEM NOTIFICATION …]"-led turn is machine end to end — the prose
+  // after the bracket header is harness narration, never the user's intent.
+  if (/^\[SYSTEM NOTIFICATION/i.test(text)) return null;
+  for (let hops = 0; hops < 12; hops++) {
+    const m = MACHINE_BLOCK_RE.exec(text);
+    if (!m) break;
+    text = text.slice(m[0].length).trim();
+  }
+  if (!text || TAG_SHAPED_RE.test(text)) return null;
+  return text;
+}
+
+// True when a non-empty prompt/intent value is machine-generated end to end.
+// Empty strings are NOT machine turns — brain_sync phase "complete" clears
+// intent with '' deliberately, and that semantic must keep working.
+export function looksMachineTurn(text) {
+  const t = String(text || '').trim();
+  return Boolean(t) && deriveIntentFromPrompt(t) === null;
+}
+
 // tmp+rename so lock-free readers (readLane, messageFooter, peers' status
 // lines) can never parse a torn lane as an authoritative "0 peers / no
 // messages", and a crash mid-write can never destroy undelivered messages.
+// On Windows, renaming over a destination a reader/AV momentarily holds open
+// throws EPERM — one immediate retry wins that race, and on final failure the
+// tmp is REMOVED before rethrowing (the field found dozens of orphaned
+// `.tmp-<pid>-<rand>` files littering the sessions dir, 2026-08-07).
 function writeLaneFileAtomic(laneFile, payload) {
   const tmp = `${laneFile}.tmp-${process.pid}-${Math.random().toString(36).slice(2, 8)}`;
   fs.writeFileSync(tmp, payload);
-  fs.renameSync(tmp, laneFile);
+  try {
+    fs.renameSync(tmp, laneFile);
+  } catch (err) {
+    try { fs.renameSync(tmp, laneFile); }
+    catch { try { fs.unlinkSync(tmp); } catch { /* best-effort */ } throw err; }
+  }
+  sweepStaleTmpFiles(path.dirname(laneFile));
+}
+
+// Opportunistic janitor for tmp orphans left by crashes or the pre-fix rename
+// path. Throttled to once per process per 10 minutes; only files matching our
+// own tmp naming and older than 15 minutes are touched, so an in-flight write
+// (millisecond lifetime) can never be swept.
+let lastTmpSweep = 0;
+export function sweepStaleTmpFiles(dir, { now = Date.now(), maxAgeMs = 15 * 60 * 1000, force = false } = {}) {
+  if (!force && now - lastTmpSweep < 10 * 60 * 1000) return 0;
+  lastTmpSweep = now;
+  let swept = 0;
+  try {
+    for (const name of fs.readdirSync(dir)) {
+      if (!/\.tmp-\d+(?:-[a-z0-9]+)?$|\.\d+\.tmp$/.test(name)) continue;
+      const full = path.join(dir, name);
+      try {
+        if (now - fs.statSync(full).mtimeMs > maxAgeMs) { fs.unlinkSync(full); swept++; }
+      } catch { /* raced or locked — next sweep */ }
+    }
+  } catch { /* dir unreadable — best-effort */ }
+  return swept;
 }
 
 function freshChannelSeen(channelSeen, now) {
@@ -242,10 +317,14 @@ export function upsertSession({
     // that never touch intent, so without intentAt a 100-minute-old intent renders
     // under "active just now" (2026-07-29 audit). Stamped only when the intent
     // VALUE actually changes; additive — old rows/readers are unaffected.
-    const nextIntent = intent !== undefined
-      ? String(intent || '').replace(/\s+/g, ' ').trim().slice(0, 160)
+    // Defense-in-depth: a machine-generated value (harness notification, raw
+    // XML tag) is treated as "no update" — the derivation layer in the hooks
+    // is the primary guard, this catches any writer that skipped it.
+    const effectiveIntent = intent !== undefined && looksMachineTurn(intent) ? undefined : intent;
+    const nextIntent = effectiveIntent !== undefined
+      ? String(effectiveIntent || '').replace(/\s+/g, ' ').trim().slice(0, 160)
       : (previous.intent || '');
-    const intentChanged = intent !== undefined && nextIntent !== (previous.intent || '');
+    const intentChanged = effectiveIntent !== undefined && nextIntent !== (previous.intent || '');
     // A connection heartbeat proves transport liveness, not that a task is in
     // progress. Stamp only events that carry real user/tool work so doctor can
     // distinguish an idle connected host from an active sync-silent session.
@@ -330,7 +409,9 @@ export function upsertRemoteSessions({ brainPath, rows, machineId = MACHINE_ID,
         client: String(row.client || previous.client || 'unknown'),
         surface: row.surface ?? previous.surface ?? null,
         branch: row.branch ?? previous.branch ?? null,
-        intent: String(row.intent || '').slice(0, 160),
+        // Same machine-turn guard as the local writer: a peer machine running a
+        // pre-guard build can relay junk intent — never mirror it verbatim.
+        intent: looksMachineTurn(row.intent) ? String(previous.intent || '') : String(row.intent || '').slice(0, 160),
         files: normalizeFiles(row.files),
         machine: String(row.machine),
         host: row.host ?? previous.host ?? null,

package/src/brain-doctor.mjs

@@ -39,6 +39,10 @@ import { renderReceiptSummary, summarizeReceipts } from './finding-routing.mjs';
 // inspect() synchronous for its existing callers.
 let fmtLib = null;
 try { fmtLib = await import('./klypix-format.mjs'); } catch { fmtLib = null; }
+let gitCaptureLib = null;
+try { gitCaptureLib = await import('./git-capture-install.mjs'); } catch { gitCaptureLib = null; }
+let historyLib = null;
+try { historyLib = await import('./brain-history.mjs'); } catch { historyLib = null; }
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -372,6 +376,24 @@ export function inspect(opts = {}) {
     mcpInstructions: true,
     globalInstructions: codexGlobalInstructionsInstalled(home),
   };
+  // Commit-capture git hook (2026-08-07): informational, never a drift layer —
+  // SessionStart auto-installs it where safe; doctor reports the cases it can't
+  // (foreign hook in the slot, core.hooksPath set, brain nested below the repo
+  // top). Guarded dynamic import: on a half-updated bundle that lacks the
+  // module, doctor must keep working, not crash at load (review-caught).
+  let gitCapture = { state: 'n/a', hooks: {} };
+  if (hasBrain && gitCaptureLib && typeof gitCaptureLib.gitCaptureHookStatus === 'function') {
+    try { gitCapture = gitCaptureLib.gitCaptureHookStatus(projectDir, { home }); } catch { gitCapture = { state: 'error', hooks: {} }; }
+  }
+  // Restore points (2026-08-07). Informational: their absence on a brand-new
+  // brain is normal, and a missing history must never read as machine drift.
+  let history = { available: false, count: 0, newestAt: null };
+  if (hasBrain && historyLib && typeof historyLib.listBrainHistory === 'function') {
+    try {
+      const points = historyLib.listBrainHistory(brainPath, { home });
+      history = { available: true, count: points.length, newestAt: points[0]?.ts || null };
+    } catch { history = { available: true, count: 0, newestAt: null }; }
+  }
   const tools = inspectTools(brainDir, PKG_ROOT);
   const env = opts.env || process.env;
   // MCP passes the adopted live id explicitly. The CLI can inherit a host id,
@@ -418,6 +440,9 @@ export function inspect(opts = {}) {
       : (!codexHooks.installed
         ? 'optional'
         : (codexHooks.executionStatus === 'observed' ? 'ok' : 'warning')),
+    // Informational only — a repo the auto-installer can't wire (foreign hook,
+    // custom hooksPath) must never flip the machine verdict to DRIFTED.
+    gitCapture: gitCapture.state === 'installed' ? 'ok' : (gitCapture.state === 'n/a' ? 'n/a' : 'optional'),
     harness: hasBrain ? (harness.ok ? 'ok' : 'drift') : 'n/a',
     // DECAY-GUARD drifts when the protection is provably missing: the loaded
     // engine lacks classifyDecay, its renderer left the synthetic stale claim
@@ -456,9 +481,14 @@ export function inspect(opts = {}) {
     if (layers.decayGuard === 'drift') actions.push('npx klypix-mcp install   # decay-aware status guard missing/stale — stale build/deploy claims can render as CURRENT state');
     for (const s of supervisors.impaired || []) actions.push(`/mcp reconnect   # supervisor pid ${s.pid} is ${s.status} with no live worker — its tool calls hang until reconnected`);
     if (peers.twinGroups && peers.twinGroups.length) actions.push(`/mcp reconnect   # ${peers.twinGroups.length} session(s) split across twin lane rows (channel merge not occurring) — reconnect adopts the merged id`);
+    if (hasBrain && (gitCapture.state === 'foreign' || Object.values(gitCapture.hooks || {}).some(s => s === 'foreign' || s === 'foreign-sh'))) {
+      actions.push('npx klypix-mcp git-hook install   # a pre-existing git hook occupies post-commit/post-merge — this chains the commit-capture block after it (auto-install never edits a foreign hook)');
+    } else if (hasBrain && gitCapture.state === 'custom-hookspath') {
+      actions.push('git config core.hooksPath is set   # commit-capture hook not auto-installable — add the managed block to that hooks dir or unset the config, then `npx klypix-mcp git-hook install`');
+    }
   }
 
-  return { verdict, layers, drifted, readinessWarnings, version, running, supervisors, autoUpdate, hooks, codexSmart, codexHooks, tools, peers, sessions: peers, receipts: peers.receipts, receiptSessionId, harness, npm, decayGuard, project: { dir: projectDir, brainPath, hasBrain }, brainDir, actions };
+  return { verdict, layers, drifted, readinessWarnings, version, running, supervisors, autoUpdate, hooks, codexSmart, codexHooks, gitCapture, history, tools, peers, sessions: peers, receipts: peers.receipts, receiptSessionId, harness, npm, decayGuard, project: { dir: projectDir, brainPath, hasBrain }, brainDir, actions };
 }
 
 // One-line drift summary (empty when clean) — for a footer / status line.
@@ -580,6 +610,24 @@ export function render(r, opts = {}) {
   } else {
     L.push(`${chmark} ${c.bold}CODEX${c.rst}    automatic MCP presence + ${smart} · native auto-context + pre-edit guard active ${c.dim}(last observed ${r.codexHooks.lastExecutedAt})${c.rst}`);
   }
+  // Commit-capture git hook — per-repo, informational (auto-installed at
+  // session start where safe; foreign hooks are never edited automatically).
+  if (r.gitCapture && r.gitCapture.state !== 'n/a') {
+    const gc = r.gitCapture;
+    const gmark = gc.state === 'installed' ? ok : warn;
+    const detail = gc.state === 'installed' ? 'post-commit/post-merge wired — any agent/branch/worktree cards its rationale-bearing commits'
+      : gc.state === 'custom-hookspath' ? `${c.yel}core.hooksPath set — not auto-installable (see actions)${c.rst}`
+        : gc.state === 'foreign' ? `${c.yel}foreign hook in the slot — run \`npx klypix-mcp git-hook install\` to chain it deliberately${c.rst}`
+          : gc.state === 'no-git' ? `${c.dim}not a git repo${c.rst}`
+            : `${c.dim}${gc.state} — installs automatically at the next session start${c.rst}`;
+    L.push(`${gmark} ${c.bold}GIT-CAP${c.rst}  ${detail}`);
+  }
+  // Restore points — say the count and the age, because "you can undo an
+  // accidental delete" is only believable if the machine can show the receipts.
+  if (r.history?.available) {
+    const age = r.history.newestAt ? `${Math.max(0, Math.round((Date.now() - r.history.newestAt) / 60000))}m ago` : 'none yet';
+    L.push(`${ok} ${c.bold}HISTORY${c.rst}  ${r.history.count} restore point(s) · newest ${age} ${c.dim}(npx klypix-mcp brain-history list)${c.rst}`);
+  }
 
   // TOOLS
   L.push(`${ok} ${c.bold}TOOLS${c.rst}    ${r.tools.count} MCP verb(s)${r.tools.hash ? ` ${c.dim}[#${r.tools.hash}, ${r.tools.source}]${c.rst}` : ''}${r.tools.count ? `: ${c.dim}${r.tools.names.join(', ')}${c.rst}` : ''}`);

package/src/brain-git-hook.mjs

@@ -60,7 +60,15 @@ function parseLog(raw) {
         return { hash: (p[0] || '').trim(), subject: (p[1] || '').trim(), body: (p[2] || '').trim() };
     }).filter(c => c.hash && c.subject);
 }
-const readPrev = () => { try { return fs.readFileSync(STATE, 'utf8').trim() || null; } catch { return null; } };
+// The baseline is repo-writable and gets interpolated into git commands — accept
+// ONLY a bare sha, or a malicious checkout gains shell execution at commit time
+// (review-caught 2026-08-07). An invalid file re-baselines like a missing one.
+const readPrev = () => {
+    try {
+        const s = fs.readFileSync(STATE, 'utf8').trim();
+        return /^[0-9a-f]{4,64}$/i.test(s) ? s : null;
+    } catch { return null; }
+};
 const writePrev = (s) => { try { fs.mkdirSync(path.dirname(STATE), { recursive: true }); fs.writeFileSync(STATE, String(s || '')); } catch { /* best-effort */ } };
 
 async function main() {