klypix-mcp 1.61.0 → 1.62.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-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', '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', 'diff', 'pr-brief', 'uninstall', 'bench']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -35,6 +35,7 @@ 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)',
   '  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,11 @@ 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');
 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.62.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/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,8 @@ 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; }
 
 const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 
@@ -372,6 +374,15 @@ 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: {} }; }
+  }
   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 +429,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 +470,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, 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 +599,18 @@ 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}`);
+  }
 
   // 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() {

package/src/codex-brain-hook.mjs

@@ -5,6 +5,7 @@ import { execFileSync } from 'child_process';
 import fs from 'fs';
 import path from 'path';
 import {
+  deriveIntentFromPrompt,
   findProjectBrain,
   formatPresenceMessage,
   formatReceivedMessages,
@@ -239,10 +240,18 @@ async function main() {
   }
 
   const projectDir = path.dirname(brainPath);
-  const prompt = input.prompt || input.user_prompt || input.userPrompt;
+  const rawPrompt = input.prompt || input.user_prompt || input.userPrompt;
+  // Machine-turn guard: a harness-injected "user" prompt (task notification,
+  // system reminder) must not become the session's declared intent — derive the
+  // human text, and on a machine turn keep the previous intent (undefined).
+  const prompt = rawPrompt === undefined ? undefined : (deriveIntentFromPrompt(rawPrompt) ?? undefined);
+  // A HUMAN prompt is a task boundary: reset the declared file scope. A machine
+  // turn is mid-task plumbing — it must keep the files exactly as it keeps the
+  // intent (review-caught: the guard preserved intent but wiped files[]).
+  const humanTurn = event === 'UserPromptSubmit' && prompt !== undefined;
   const files = event === 'PreToolUse' || event === 'PostToolUse'
     ? touchedFiles(input, projectDir)
-    : (event === 'UserPromptSubmit' ? [] : undefined);
+    : (humanTurn ? [] : undefined);
   const sessions = upsertSession({
     brainPath,
     id: sessionId,
@@ -253,7 +262,7 @@ async function main() {
     branch: gitBranch(cwd),
     intent: prompt === undefined ? undefined : prompt,
     files,
-    replaceFiles: event === 'UserPromptSubmit',
+    replaceFiles: humanTurn,
     event,
     channel: 'lifecycle',
     cwd,
@@ -275,6 +284,15 @@ async function main() {
     });
   }
   if (event === 'SessionStart') {
+    // Commit-capture completeness (2026-08-07): wire the agent-neutral git
+    // post-commit/post-merge hook when the slots are absent or already ours —
+    // never a foreign hook. Dynamic + guarded so a stale bundle no-ops.
+    const gitHookNotice = await (async () => {
+      try {
+        const ghl = await import(new URL('./git-capture-install.mjs', import.meta.url).href);
+        return typeof ghl.ensureGitCaptureHook === 'function' ? (ghl.ensureGitCaptureHook(projectDir).notice || '') : '';
+      } catch { return ''; }
+    })();
     emitSystemMessage([
       formatPresenceMessage(sessions, sessionId, { includeSolo: true }),
       // Class-C ship observation — the engine's, not a Claude-hook-local copy.
@@ -282,6 +300,7 @@ async function main() {
       // is exactly where the incident class bites hardest (2026-07-29 review).
       // The queue drains at the next brain write from any host.
       observeShipDrift(projectDir),
+      gitHookNotice.trim(),
       stampReceivedMessages(messages),
     ]);
     return;

package/src/codex-hooks.mjs

@@ -6,6 +6,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
+import { sweepStaleTmpFiles } from './agent-presence.mjs';
 
 export const CODEX_PRESENCE_EVENTS = [
   'SessionStart',
@@ -88,7 +89,8 @@ function writeHooks(file, raw, data) {
     const temp = file + '.klypix-tmp';
     fs.writeFileSync(temp, JSON.stringify(data, null, 2) + '\n', 'utf8');
     JSON.parse(fs.readFileSync(temp, 'utf8'));
-    fs.renameSync(temp, file);
+    try { fs.renameSync(temp, file); }
+    catch (err) { try { fs.unlinkSync(temp); } catch { /* */ } throw err; }
     return { ok: true, backup };
   } catch (error) {
     return { ok: false, error: `Couldn't write ${file}: ${error?.message || error}` };
@@ -166,7 +168,16 @@ export function recordCodexHookExecution({
     fs.mkdirSync(path.dirname(status.receiptPath), { recursive: true });
     const temp = status.receiptPath + `.${process.pid}.tmp`;
     fs.writeFileSync(temp, JSON.stringify(receipt, null, 2), 'utf8');
-    fs.renameSync(temp, status.receiptPath);
+    // Windows rename-over-open-destination throws EPERM (concurrent hook
+    // processes race on this receipt constantly): retry once, and never leave
+    // the tmp behind — the field found ~35 orphans from this exact line
+    // (2026-08-07). A losing racer's receipt is disposable; the winner's stands.
+    try { fs.renameSync(temp, status.receiptPath); }
+    catch {
+      try { fs.renameSync(temp, status.receiptPath); }
+      catch { try { fs.unlinkSync(temp); } catch { /* */ } return { ok: false, reason: 'rename-raced' }; }
+    }
+    sweepStaleTmpFiles(path.dirname(status.receiptPath));
     return { ok: true, path: status.receiptPath };
   } catch {
     return { ok: false, reason: 'write-failed' };

package/src/git-capture-install.mjs

@@ -0,0 +1,215 @@
+// git-capture-install — wire the agent-neutral commit-capture hook
+// (brain-git-hook.mjs) into a repo's git hooks, so rationale-bearing
+// feat/fix/perf commits card into ./brain.klypix from ANY agent (Cursor, Cline,
+// Codex, a human terminal), on ANY branch, in ANY worktree — at commit time.
+//
+// Why this exists (2026-08-07 field diagnosis): brain-git-hook.mjs shipped for
+// months but was installed NOWHERE — the desktop's installer path had zero UI
+// call sites and no CLI verb existed. The only live commit capture was the
+// Claude Code Stop hook, which walks `prev..HEAD` in the session's checkout —
+// commits authored on another worktree's branch were invisible to it (the
+// AgentLit `94b0b6b` incident). A post-commit hook fires in whatever worktree
+// the commit happens in, closing worktree, branch, AND foreign-agent blindness
+// with the SAME high-signal gates (feat|fix|perf + rationale body ≥ 12 chars)
+// — this is NOT blind auto-capture.
+//
+// Contract: never touch a hook we don't own. Our lines live between marker
+// comments; a foreign non-sh hook is reported, not modified. Removal is exact:
+// only the managed block goes.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { execFileSync } from 'child_process';
+import { fileURLToPath } from 'url';
+
+const HOOK_NAMES = ['post-commit', 'post-merge'];
+const MARK_START = '# >>> klypix-brain capture >>>';
+const MARK_END = '# <<< klypix-brain capture <<<';
+
+const gitOut = (repoDir, args) => {
+  try {
+    return execFileSync('git', args, {
+      cwd: repoDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 4000,
+    }).trim();
+  } catch { return null; }
+};
+
+// Prefer the machine-global deployed engine (stable across repo moves and the
+// path every other brain component already runs from); fall back to the sibling
+// copy for repo-checkout use. An EPHEMERAL npx cache is never an acceptable
+// target: the path is baked into a hook that must keep working for years, and
+// npm evicts the cache — the hook would silently stop capturing (review-caught).
+const EPHEMERAL_RE = /[\\/](_npx|_cacache|npm-cache[\\/]_)/i;
+export function resolveHookScript(home = os.homedir()) {
+  const deployed = path.join(home, '.claude', 'project-brain', 'brain-git-hook.mjs');
+  if (fs.existsSync(deployed)) return deployed;
+  const sibling = path.join(path.dirname(fileURLToPath(import.meta.url)), 'brain-git-hook.mjs');
+  if (fs.existsSync(sibling) && !EPHEMERAL_RE.test(sibling)) return sibling;
+  return null;   // nothing durable to point at — callers report 'no-engine'
+}
+
+// Single-quote for sh: immune to $, backticks and double quotes in the path
+// (review-caught: a metacharacter path was an sh-injection into an every-commit
+// hook). Embedded single quotes use the standard '\'' dance.
+const shq = (s) => `'${String(s).replace(/\\/g, '/').replace(/'/g, `'\\''`)}'`;
+
+function managedBlock(hookScript) {
+  const script = shq(hookScript);
+  return [
+    `${MARK_START} (managed by klypix-mcp — remove: npx klypix-mcp git-hook remove)`,
+    // [ -f ]: an uninstalled/evicted engine bundle degrades to a silent no-op
+    // instead of per-commit stderr noise (review-caught). command -v: a GUI git
+    // client without node on PATH must not fail the commit. No cwd argument:
+    // git runs hooks from the top of the CURRENT working tree and node's own
+    // process.cwd() is a proper native path in every sh flavor — passing
+    // "$(pwd)" handed node an MSYS/POSIX path under some git-for-windows setups.
+    `[ -f ${script} ] && command -v node >/dev/null 2>&1 && node ${script} || true`,
+    MARK_END,
+  ].join('\n');
+}
+
+// `git-hook remove` writes this marker so SessionStart auto-install respects
+// the human's decision instead of silently re-wiring next session
+// (review-caught: remove didn't stick). Explicit install clears it.
+const OPTOUT_REL = path.join('.claude', 'git-capture-optout');
+export function gitCaptureOptedOut(repoDir) {
+  return fs.existsSync(path.join(repoDir, OPTOUT_REL));
+}
+
+function hookFileState(file, hookScript) {
+  let raw = null;
+  try { raw = fs.readFileSync(file, 'utf8'); } catch { return { state: 'absent', raw: null }; }
+  if (raw.includes(MARK_START)) {
+    const current = raw.includes(managedBlock(hookScript));
+    return { state: current ? 'ours' : 'ours-stale', raw };
+  }
+  const firstLine = raw.split('\n', 1)[0] || '';
+  const shCompatible = !firstLine.startsWith('#!') || /\b(sh|bash|dash|zsh)\b/.test(firstLine);
+  return { state: shCompatible ? 'foreign-sh' : 'foreign', raw };
+}
+
+const canonDir = (p) => {
+  try { return fs.realpathSync.native ? fs.realpathSync.native(p) : fs.realpathSync(p); }
+  catch { return path.resolve(p); }
+};
+
+export function gitCaptureHookStatus(repoDir, { home = os.homedir() } = {}) {
+  const commonDir = gitOut(repoDir, ['rev-parse', '--git-common-dir']);
+  if (!commonDir) return { state: 'no-git', hooks: {} };
+  if (gitOut(repoDir, ['config', 'core.hooksPath'])) return { state: 'custom-hookspath', hooks: {} };
+  // Containment: the hook runs from the worktree TOP and looks for
+  // ./brain.klypix there. A brain nested deeper in a larger repo can never be
+  // captured by this hook — installing would mutate the enclosing repo's hooks
+  // for nothing and report a false green (review-caught).
+  const top = gitOut(repoDir, ['rev-parse', '--show-toplevel']);
+  if (top && canonDir(top) !== canonDir(repoDir)) return { state: 'nested-brain', hooks: {}, worktreeTop: top };
+  const hooksDir = path.resolve(repoDir, commonDir, 'hooks');
+  const hookScript = resolveHookScript(home);
+  // No durable engine path to bake into a hook (running straight from an npx
+  // cache with no installed bundle) — say so rather than wiring a hook that
+  // dies at the next cache eviction.
+  if (!hookScript) return { state: 'no-engine', hooksDir, hookScript: null, hooks: {} };
+  const hooks = {};
+  for (const name of HOOK_NAMES) hooks[name] = hookFileState(path.join(hooksDir, name), hookScript).state;
+  const states = Object.values(hooks);
+  const state = states.every((s) => s === 'ours') ? 'installed'
+    : states.some((s) => s === 'foreign') ? 'foreign'
+      : states.every((s) => s === 'absent') ? 'absent'
+        : 'partial';
+  return { state, hooksDir, hookScript, hooks };
+}
+
+// Install or refresh the managed block. Foreign sh-compatible hooks get the
+// block APPENDED (their lines run first, ours never exits non-zero); foreign
+// non-sh hooks are skipped and reported. Idempotent.
+export function installGitCaptureHook(repoDir, { home = os.homedir() } = {}) {
+  const status = gitCaptureHookStatus(repoDir, { home });
+  if (['no-git', 'custom-hookspath', 'nested-brain', 'no-engine'].includes(status.state)) {
+    return { ok: false, reason: status.state, changed: [], skipped: [] };
+  }
+  // Explicit install = the human opting back in — clear any remove-marker.
+  try { fs.unlinkSync(path.join(repoDir, OPTOUT_REL)); } catch { /* none */ }
+  const block = managedBlock(status.hookScript);
+  const changed = [], skipped = [];
+  fs.mkdirSync(status.hooksDir, { recursive: true });
+  for (const name of HOOK_NAMES) {
+    const file = path.join(status.hooksDir, name);
+    const { state, raw } = hookFileState(file, status.hookScript);
+    let next = null;
+    if (state === 'absent') next = `#!/bin/sh\n${block}\n`;
+    else if (state === 'ours-stale') {
+      next = raw.replace(new RegExp(`${MARK_START}[\\s\\S]*?${MARK_END}`), block);
+      if (!next.includes(block)) next = null;   // markers mangled — refuse to guess
+    } else if (state === 'foreign-sh') next = raw.replace(/\n*$/, '\n') + block + '\n';
+    else if (state === 'foreign') { skipped.push(name); continue; }
+    if (next === null) { if (state !== 'ours') skipped.push(name); continue; }
+    // LF endings are load-bearing: git's sh rejects CRLF shebangs.
+    fs.writeFileSync(file, next.replace(/\r\n/g, '\n'), 'utf8');
+    try { fs.chmodSync(file, 0o755); } catch { /* Windows — irrelevant */ }
+    changed.push(name);
+  }
+  return { ok: true, changed, skipped, hooksDir: status.hooksDir };
+}
+
+export function removeGitCaptureHook(repoDir, { home = os.homedir() } = {}) {
+  const status = gitCaptureHookStatus(repoDir, { home });
+  if (!status.hooksDir) return { ok: false, reason: status.state, changed: [] };
+  // Make the removal STICK: SessionStart auto-install honors this marker, so a
+  // human's `git-hook remove` is a durable decision, not a one-session pause.
+  try {
+    fs.mkdirSync(path.join(repoDir, '.claude'), { recursive: true });
+    fs.writeFileSync(path.join(repoDir, OPTOUT_REL),
+      'The commit-capture git hook was removed on purpose (npx klypix-mcp git-hook remove).\n'
+      + 'Sessions will NOT auto-reinstall it while this file exists. Opt back in: npx klypix-mcp git-hook install\n');
+  } catch { /* marker is best-effort; removal below still happens */ }
+  const changed = [];
+  for (const name of HOOK_NAMES) {
+    const file = path.join(status.hooksDir, name);
+    let raw = null;
+    try { raw = fs.readFileSync(file, 'utf8'); } catch { continue; }
+    if (!raw.includes(MARK_START)) continue;
+    const stripped = raw.replace(new RegExp(`\\n?${MARK_START}[\\s\\S]*?${MARK_END}\\n?`), '\n');
+    const residue = stripped.replace(/^#!\/bin\/sh\n?/, '').trim();
+    if (residue) fs.writeFileSync(file, stripped, 'utf8');
+    else fs.unlinkSync(file);   // nothing but our scaffold — leave no husk
+    changed.push(name);
+  }
+  return { ok: true, changed };
+}
+
+// Session-start convenience: install when safe (fresh repo or our own stale
+// block), refresh silently, and NEVER touch a foreign hook — that case is left
+// for doctor to surface. Returns a one-line notice only on a real transition.
+//
+// Consent posture: this writes an executable file into the repo's .git/hooks
+// without a prompt, so it is deliberately bounded — only files we fully own,
+// only a repo whose top holds this brain, a one-line announcement on the first
+// install, a removal that STICKS (.claude/git-capture-optout), and a machine
+// kill switch (KLYPIX_GIT_CAPTURE=0) for anyone who wants none of it.
+export function ensureGitCaptureHook(repoDir, { home = os.homedir(), env = process.env } = {}) {
+  if (/^(0|false|off|no)$/i.test(String(env?.KLYPIX_GIT_CAPTURE || ''))) {
+    return { changed: false, state: 'disabled', notice: '' };
+  }
+  if (gitCaptureOptedOut(repoDir)) return { changed: false, state: 'opted-out', notice: '' };
+  const status = gitCaptureHookStatus(repoDir, { home });
+  if (['installed', 'no-git', 'custom-hookspath', 'nested-brain', 'no-engine'].includes(status.state)) {
+    return { changed: false, state: status.state, notice: '' };
+  }
+  // Auto-install writes only files we fully own: every target must be absent or
+  // carry our markers. ANY foreign hook (even sh-compatible) defers to the
+  // explicit CLI — silently editing someone's custom hook is not a session
+  // side-effect. `npx klypix-mcp git-hook install` chains those deliberately.
+  if (Object.values(status.hooks).some((s) => s === 'foreign' || s === 'foreign-sh')) {
+    return { changed: false, state: status.state, notice: '' };
+  }
+  const firstInstall = Object.values(status.hooks).every((s) => s === 'absent');
+  const res = installGitCaptureHook(repoDir, { home });
+  if (!res.ok || !res.changed.length) return { changed: false, state: status.state, notice: '' };
+  return {
+    changed: true,
+    state: 'installed',
+    notice: firstInstall
+      ? '\n🔧 Installed the git commit-capture hook (post-commit/post-merge) — rationale-bearing feat/fix/perf commits from ANY agent, branch, or worktree now card into the brain. Remove: `npx klypix-mcp git-hook remove`.'
+      : '',
+  };
+}

package/src/global-brain-hook.mjs

@@ -308,7 +308,37 @@ const laneCanon = (p) => { try { return fs.realpathSync.native(p); } catch { ret
 const SESSIONS_FILE = path.join(SESSIONS_DIR, `${sha(normBrainPath(laneCanon(BRAIN)))}.json`); // one lane-file per PROJECT (shared by its concurrent sessions)
 const SESSIONS_LOCK = SESSIONS_FILE + '.lock';
 // tmp+rename: lock-free readers must never parse a torn lane as an empty one.
-function writeLaneAtomic(payload) { const tmp = SESSIONS_FILE + '.tmp-' + process.pid; fs.writeFileSync(tmp, payload); fs.renameSync(tmp, SESSIONS_FILE); }
+// Windows rename-over-open-destination throws EPERM (AV / a concurrent reader):
+// one immediate retry wins the race; on final failure the tmp is removed before
+// rethrowing so failures can't litter the sessions dir (field: dozens of
+// orphaned tmp files, 2026-08-07). A throttled janitor sweeps pre-fix orphans.
+function writeLaneAtomic(payload) {
+    const tmp = SESSIONS_FILE + '.tmp-' + process.pid + '-' + Math.random().toString(36).slice(2, 8);
+    fs.writeFileSync(tmp, payload);
+    try { fs.renameSync(tmp, SESSIONS_FILE); }
+    catch (err) {
+        try { fs.renameSync(tmp, SESSIONS_FILE); }
+        catch { try { fs.unlinkSync(tmp); } catch { /* best-effort */ } throw err; }
+    }
+    sweepStaleTmp(SESSIONS_DIR);
+}
+// PARITY: same throttle/age/pattern contract as agent-presence.mjs
+// sweepStaleTmpFiles() — duplicated because this hook stays free of sibling
+// static imports by design (a broken sibling must never kill the brief).
+let lastTmpSweep = 0;
+function sweepStaleTmp(dir) {
+    const now = Date.now();
+    if (now - lastTmpSweep < 10 * 60 * 1000) return;
+    lastTmpSweep = now;
+    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 > 15 * 60 * 1000) fs.unlinkSync(full); }
+            catch { /* raced or locked — next sweep */ }
+        }
+    } catch { /* dir unreadable — best-effort */ }
+}
 // Pending-captures queue: when the BRAIN lock cannot be acquired, the batch is
 // queued here durably instead of written from a stale base (a best-effort write
 // could erase a peer's or the desktop app's just-merged cards — the exact lost
@@ -387,6 +417,38 @@ const pruneSessions = (list, now) => {
 // SCHEMA PARITY: this writer and agent-presence.mjs upsertSession() write the
 // SAME row shape (client/surface/cwd/hostPid/channelSeen/intentAt/intentSource) —
 // `...prev` first so either writer's fields survive the other's touch (T8 class).
+
+// ── Machine-turn intent guard (BEHAVIOR PARITY with agent-presence.mjs
+// deriveIntentFromPrompt — duplicated because this hook stays free of sibling
+// static imports; test/intent-guard.mjs asserts both stay identical) ─────────
+// UserPromptSubmit is not only human-typed text: harnesses inject task
+// notifications, system reminders and slash-command wrappers as "user" prompts,
+// and one stored verbatim became a session's declared intent
+// ("<task-notification> <task-id>…" — 2026-08-07 AgentLit field incident).
+// null ⇒ the turn is machine-generated: KEEP the previous intent (still stamp
+// activity), never store the junk, never clear a good intent.
+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');
+const TAG_SHAPED_RE = /^<[a-z][\w.:-]*(?:\s|\/?>)/i;
+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;
+}
+
 function touchSession(sid, patch = {}) {
     if (!sid) return;
     try {
@@ -414,10 +476,15 @@ function touchSession(sid, patch = {}) {
             const wantsIntent = patch.intent !== undefined && !declaredFresh;
             const nextIntent = wantsIntent ? patch.intent : (prev.intent ?? '');
             const intentChanged = wantsIntent && nextIntent !== (prev.intent ?? '');
+            // `activity: true` records a work-shaped turn WITHOUT an intent
+            // update — a machine-generated prompt (task notification landing in
+            // a working session) proves the session is active, but its text
+            // must never become the declared intent.
             const recordsActivity = patch.intent !== undefined
                 || patch.addFiles !== undefined
                 || patch.files !== undefined
-                || patch.ships !== undefined;
+                || patch.ships !== undefined
+                || patch.activity === true;
             list.push({
                 ...prev,   // unknown/foreign keys (an MCP writer's, a future field) survive this touch
                 id: sid, pid: process.pid, project: path.basename(CWD),
@@ -477,7 +544,8 @@ function touchSession(sid, patch = {}) {
                     kept[String(HOST_PID)] = { sessionId: sid, ts: now };
                     const tmp = HOSTMAP_FILE + '.' + process.pid + '.tmp';
                     fs.writeFileSync(tmp, JSON.stringify(kept));
-                    fs.renameSync(tmp, HOSTMAP_FILE);
+                    try { fs.renameSync(tmp, HOSTMAP_FILE); }
+                    catch (err) { try { fs.unlinkSync(tmp); } catch { /* */ } throw err; }
                 } catch { /* best-effort */ }
             }
         } finally { if (got) releaseLock(SESSIONS_LOCK); }
@@ -839,7 +907,15 @@ function fileTagsFor(p) {
 // re-baselines if history was rewritten (rebase/reset) so a non-ancestor range
 // can never dump the whole history.
 const COMMIT_STATE = path.resolve(CWD, '.claude', 'brain-last-commit');
-const readLastCommit = () => { try { return fs.readFileSync(COMMIT_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 (review-caught
+// 2026-08-07). An invalid file re-baselines exactly like a missing one.
+const readLastCommit = () => {
+    try {
+        const s = fs.readFileSync(COMMIT_STATE, 'utf8').trim();
+        return /^[0-9a-f]{4,64}$/i.test(s) ? s : null;
+    } catch { return null; }
+};
 const writeLastCommit = (s) => { try { fs.mkdirSync(path.dirname(COMMIT_STATE), { recursive: true }); fs.writeFileSync(COMMIT_STATE, String(s || '')); } catch { /* best-effort */ } };
 const git = (args) => execSync(`git ${args}`, { cwd: CWD, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 4000 }).trim();
 
@@ -1846,8 +1922,46 @@ async function capture(lib) {
             for (const u of (Array.isArray(b.updates) ? b.updates : [])) updates.push(u);
         }
         if (!cards.length && !resolutions.length && !updates.length) return null;
-        const res = await lib.captureIntoBrain(fs.readFileSync(BRAIN), {
-            cards: cards.map(c => ({ text: c.text, color: '#e8e8ed', borderColor: c.borderColor, area: c.area, createdVia: c.createdVia || 'claude-code', ...(c.closes ? { closes: c.closes } : {}), ...(c.evidence ? { evidence: c.evidence } : {}), ...(c.verify ? { verify: c.verify } : {}) })),
+        const brainBuf = fs.readFileSync(BRAIN);
+        // Dual-channel commit dedup (2026-08-07): the auto-installed git
+        // post-commit hook cards commits AT COMMIT TIME with a #commit-<7> tag,
+        // deduping against the brain before it writes. This side must honor the
+        // same contract — without it every rationale-bearing commit in a hooked
+        // repo carded twice (feat → duplicate 🏁 cards; fix/perf → the git
+        // hook's minutes-old card got supersede-archived by its own clone).
+        // Scoped to createdVia==='commit' — cards from THIS channel only. A
+        // human marker that merely cites "#commit-abc1234" must never be
+        // swallowed by the auto-card that shares its hash (self-review catch:
+        // filtering on the tag alone is a silent-loss bug, and silent loss is
+        // the one thing the brain may never do).
+        const isCommitCard = (c) => c && c.createdVia === 'commit' && /#commit-[0-9a-f]{7}/i.test(String(c.text || ''));
+        let landedCards = cards;
+        try {
+            if (cards.some(isCommitCard)) {
+                const { struct: cur } = await lib.parseKlypix(brainBuf);
+                const already = new Set();
+                for (const c of (cur.cards || []))
+                    for (const m of String(c.text || '').matchAll(/#commit-([0-9a-f]{7})/gi)) already.add(m[1].toLowerCase());
+                landedCards = cards.filter(c => {
+                    if (!isCommitCard(c)) return true;
+                    const m = /#commit-([0-9a-f]{7})/i.exec(String(c.text || ''));
+                    return !already.has(m[1].toLowerCase());
+                });
+            }
+        } catch { /* parse failed → land unfiltered; the supersede pass copes */ }
+        if (!landedCards.length && !resolutions.length && !updates.length) {
+            // Everything gathered was already in the brain (the git hook carded
+            // it first). Advance every baseline exactly like a successful write —
+            // the commits ARE durable — so the same range never re-scans.
+            writeState(merged);
+            writeLastCommit(newLastCommit);
+            if (drainedPendingIds.size) updatePendingCaptures((current) => current.filter(b => b && !drainedPendingIds.has(b.id)));
+            if (drainedShips && typeof lib.clearPendingShips === 'function') lib.clearPendingShips(CWD);
+            advanceShipBaseline(lib);
+            return null;
+        }
+        const res = await lib.captureIntoBrain(brainBuf, {
+            cards: landedCards.map(c => ({ text: c.text, color: '#e8e8ed', borderColor: c.borderColor, area: c.area, createdVia: c.createdVia || 'claude-code', ...(c.closes ? { closes: c.closes } : {}), ...(c.evidence ? { evidence: c.evidence } : {}), ...(c.verify ? { verify: c.verify } : {}) })),
             resolutions,
             updates,
         });
@@ -1995,6 +2109,11 @@ async function promptRetrieve(lib) {
     const input = readHookInput();
     const sid = input.session_id;
     const prompt = input.prompt || input.user_prompt || input.userPrompt || '';
+    // Machine-turn guard: a harness-injected "user" prompt (task notification,
+    // system reminder, slash-command wrapper) carries NO human intent — it must
+    // neither become the lane's intent nor drive retrieval (it used to do both:
+    // junk intent for peers, garbage tokens against the brain). null ⇒ machine.
+    const humanText = deriveIntentFromPrompt(prompt);
     // Status-vocab quarantine (2026-07-23): "what is remaining?" must not
     // lexically retrieve the stale cards that SAY "remaining:" — status words
     // describe the question's shape, not its subject, and are anti-correlated
@@ -2004,10 +2123,10 @@ async function promptRetrieve(lib) {
     // #file- tag hits re-serve the exact corpse the quarantine removed
     // (adversarial review traced the side door). The brief's computed "Area
     // status" section carries the current-state answer instead.
-    let ptoks = lib.queryTokens(prompt);
+    let ptoks = lib.queryTokens(humanText || '');
     let statusShaped = false, statusStrong = false;
     if (typeof lib.splitQueryTokens === 'function') {
-        const sp = lib.splitQueryTokens(prompt);
+        const sp = lib.splitQueryTokens(humanText || '');
         ptoks = sp.content;
         statusShaped = sp.statusShaped;
         // strong = the prompt IS a status question (phrase shape / nothing but
@@ -2028,8 +2147,15 @@ async function promptRetrieve(lib) {
     // OWN edits (set at Stop). Here we just refresh INTENT + branch + the heartbeat.
     const changedPaths = gitChangedPaths();
     const branch = gitBranch();
-    touchSession(sid, { intent: String(prompt).replace(/\s+/g, ' ').trim().slice(0, 80), branch });
-    const fileToks = (ptoks.length < 2 && !statusShaped) ? changedPaths.flatMap(fileQueryTokens) : [];
+    // Human turn → latest prompt becomes the intent (80 chars). Machine turn →
+    // keep the previous intent, but still stamp activity: a notification landing
+    // here proves the session is mid-work, not idle.
+    touchSession(sid, humanText !== null
+        ? { intent: humanText.slice(0, 80), branch }
+        : { activity: true, branch });
+    // The git-diff fallback exists for TERSE HUMAN prompts ("go on") — a machine
+    // turn must not fall through to it and retrieve against the whole diff.
+    const fileToks = (ptoks.length < 2 && !statusShaped && humanText !== null) ? changedPaths.flatMap(fileQueryTokens) : [];
     const tokens = [...new Set(ptoks.concat(fileToks))];
     // Other live sessions in THIS repo — surfaced even when the prompt retrieves
     // nothing (a peer's presence/ship is itself the signal). Empty string when solo.
@@ -2043,7 +2169,7 @@ async function promptRetrieve(lib) {
         // only on a do/build request, only completed-work cards, only high confidence.
         // Matched on the PROMPT's stated intent (ptoks), not the git-diff fallback. A
         // false nudge erodes trust, so it's strict; the loose recall list still shows.
-        if (looksLikeWorkRequest(prompt) && typeof lib.detectRepeatWork === 'function') {
+        if (looksLikeWorkRequest(humanText || '') && typeof lib.detectRepeatWork === 'function') {
             try { repeats = lib.detectRepeatWork(struct, ptoks, { topK: 2 }); } catch { /* best-effort */ }
         }
     }
@@ -2061,7 +2187,10 @@ async function promptRetrieve(lib) {
         try {
             const semlib = await import(new URL('./brain-semantic.mjs', import.meta.url).href);
             if (typeof semlib.semanticVecs === 'function') {
-                const sem = await semlib.semanticVecs(BRAIN, struct, prompt, { timeoutMs: 1500 });
+                // Embed the DERIVED human text, never the raw prompt — a mixed
+                // turn's stripped machine block must not re-contaminate the
+                // semantic query (parity with the lexical path above).
+                const sem = await semlib.semanticVecs(BRAIN, struct, humanText || '', { timeoutMs: 1500 });
                 if (!sem) semMode = 'sem-unavailable';
                 else {
                     const fresh = Date.now() - 30 * 86_400_000;
@@ -2593,6 +2722,17 @@ async function read(lib) {
     // watching (tag/version drift vs the per-project sidecar) and queue them
     // for the Stop capture. The line rides BOTH emit tiers.
     const shipObsLine = observeOutOfSessionShips(lib);
+    // Commit-capture completeness (2026-08-07): the Stop hook's commit walk is
+    // blind to commits authored in OTHER worktrees/branches and to non-hooked
+    // agents. Ensure the agent-neutral git post-commit/post-merge hook is wired
+    // — writes only files we fully own (absent or marker-fenced ours), never a
+    // foreign hook. Dynamic + guarded so a stale bundle degrades to a no-op.
+    const gitHookNotice = await (async () => {
+        try {
+            const ghl = await import(new URL('./git-capture-install.mjs', import.meta.url).href);
+            return typeof ghl.ensureGitCaptureHook === 'function' ? (ghl.ensureGitCaptureHook(CWD).notice || '') : '';
+        } catch { return ''; }
+    })();
     const { struct } = await lib.parseKlypix(fs.readFileSync(BRAIN));
     const { freshness, drifted } = computeFreshness(struct);
     // The FULL brief: tiered brief + every self-heal/health footer. Messages are
@@ -2603,7 +2743,7 @@ async function read(lib) {
         + ruleDraftsFooter(input.session_id, struct, { markShown: false })
         + receiptLine + selfCheckFooter() + doctorFooter() + versionCurrencyFooter() + legendFooter() + memoryFooter();
     const emitFull = () => {
-        process.stdout.write(full + presenceLine + shipObsLine + messageFooter(input.session_id || '', input.transcript_path, lib));
+        process.stdout.write(full + presenceLine + shipObsLine + gitHookNotice + messageFooter(input.session_id || '', input.transcript_path, lib));
         appendJsonl(HEALTH, { ts: nowIso(), project: path.basename(CWD), mode: 'read', ok: true, briefBytes: Buffer.byteLength(full), cards: struct?.counts?.cards ?? null }, 500);
     };
     // --full = everything to stdout (manual runs); also the fallback when the
@@ -2644,7 +2784,7 @@ async function read(lib) {
     // go right after the ultra brief, at the top of the visible window, never
     // after a stack of footers that could push them past a preview cut.
     const messages = messageFooter(input.session_id || '', input.transcript_path, lib);
-    const out = ultra + messages + presenceLine + shipObsLine + healLine + draftLine
+    const out = ultra + messages + presenceLine + shipObsLine + gitHookNotice + healLine + draftLine
         + receiptLine
         + inflightFooter(input.session_id, struct)
         + selfCheckFooter() + doctorFooter() + versionCurrencyFooter();

package/src/mcp-presence.mjs

@@ -516,7 +516,14 @@ export function createMcpPresence({
       includePresence: true,
       includeSolo: true,
       deliverMessages: true,
-      intent: completing ? '' : intent,
+      // Intent semantics by phase (2026-08-07 — a checkpoint sync carrying an
+      // empty intent used to DECLARE that emptiness, masking the session as
+      // sync-silent for every peer): 'complete' clears deliberately; 'start' is
+      // a task boundary, so a missing intent clears the OLD task's intent
+      // rather than inheriting it; 'checkpoint' with a missing/empty intent
+      // keeps the previous declaration — it is a progress ping, not a recant.
+      intent: completing ? ''
+        : (compact(intent) ? intent : (nextPhase === 'start' ? '' : undefined)),
       files: completing ? [] : files,
       replaceFiles: completing || nextPhase === 'start',
     };