klypix-mcp 1.60.0 → 1.62.0

package/README.md

@@ -79,7 +79,7 @@ npx klypix-mcp conformance
 
 It runs in a temporary fixture and touches nothing else. It checks tool discovery, task memory,
 truthful peer reporting, overlap surfacing, proactive logging, and in-band delivery of a peer note.
-It verifies 12 required coordination behaviours — not the 19 tools, and not the retrieval engine.
+It verifies 12 required coordination behaviours — not the 21 tools, and not the retrieval engine.
 
 ---
 
@@ -431,13 +431,14 @@ 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 |
 
 ---
 
-## The 19 verbs
+## The 21 verbs
 
 | Tool | What it does |
 |---|---|
@@ -452,7 +453,9 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `brain_message` | Session-to-session coordination notes (24h TTL, never written into the brain) |
 | `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing |
 | `brain_connect` | Find and draw related-but-unlinked cards |
-| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context, with exact-path review proposals; Graphify artifacts are supported but never installed or run locally |
+| `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context, with exact-path review proposals; external artifacts (e.g. Graphify) are supported but never installed or run locally |
+| `project_map_scan` | KLYPIX's own zero-install scanner: gitignore-aware file inventory + file-level import edges (relative, tsconfig-alias, and monorepo-workspace imports resolved) written to `klypix-map/graph.json` — which then serves `project_map_context` automatically |
+| `project_map_drift` | Read-only drift report: brain cards whose referenced files are gone or moved (with rename candidates), plus a headline when the checkout itself is behind its origin default branch |
 | `canvas_view` | Returns the board as a structured render spec plus a text summary, and declares an MCP Apps (SEP-1865) UI resource |
 | `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |
 | `search_canvases` | Search across canvases by name and content |

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-project-map.mjs

@@ -2,7 +2,7 @@
 import fs from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
-import { discoverProjectGraph } from '../src/project-graph.mjs';
+import { discoverProjectGraph, scanNativeProjectMap, checkBrainDrift, brainDriftMarkdown } from '../src/project-graph.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const template = path.resolve(here, '..', 'examples', 'github', 'klypix-project-map.yml');
@@ -22,8 +22,11 @@ function usage() {
     'KLYPIX Project Map',
     '',
     '  klypix-project-map status [project]',
+    '  klypix-project-map scan [project]      native no-install map: file inventory + import edges -> klypix-map/graph.json',
+    '  klypix-project-map drift [project]     check brain cards\' file references against the repo\'s real files (read-only)',
     '  klypix-project-map setup-github [project] [--force]',
     '',
+    'scan writes only its own artifact (klypix-map/graph.json) inside the project; drift writes nothing.',
     'setup-github installs a read-only, pinned GitHub Actions workflow. It never installs or runs a provider on your computer.',
   ].join('\n'));
 }
@@ -42,6 +45,19 @@ try {
     console.log(`GitHub workflow: ${fs.existsSync(workflow) ? 'installed' : 'not installed'}`);
     process.exit(0);
   }
+  if (command === 'scan') {
+    const result = scanNativeProjectMap({ project: root });
+    console.log(`Project: ${result.projectRoot}`);
+    console.log(`Artifact: ${result.artifactRelative} (${result.viaGit ? 'gitignore-aware' : 'walk fallback'}${result.truncated ? ', TRUNCATED at file cap' : ''})`);
+    console.log(`Files: ${result.counts.files.toLocaleString()} | parsed code files: ${result.counts.parsedCodeFiles.toLocaleString()} | import edges: ${result.counts.importEdges.toLocaleString()}`);
+    console.log(`Workspace packages: ${result.counts.workspacePackages} | external packages: ${result.counts.externalPackages} | minified skipped: ${result.counts.skippedMinified}`);
+    process.exit(0);
+  }
+  if (command === 'drift') {
+    const result = await checkBrainDrift({ project: root });
+    console.log(brainDriftMarkdown(result));
+    process.exit(result.status === 'ready' ? 0 : 1);
+  }
   if (command !== 'setup-github') {
     usage();
     process.exit(1);

package/bin/klypix-worker.mjs

@@ -30,7 +30,7 @@ import {
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
   opBrainTaskContext,
 } from '../src/klypix-core.mjs';
-import { compareProjectGraphResults, projectGraphContextMarkdown, queryProjectGraph, suggestProjectGraphBrainLinks } from '../src/project-graph.mjs';
+import { compareProjectGraphResults, projectGraphContextMarkdown, queryProjectGraph, suggestProjectGraphBrainLinks, scanNativeProjectMap, checkBrainDrift, brainDriftMarkdown } from '../src/project-graph.mjs';
 import { auditProject, compactAgentsBrief, linkProject, mcpServerEntry } from '../src/agent-rules.mjs';
 import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS } from '../src/mcp-presence.mjs';
 import {
@@ -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');
 
@@ -348,6 +353,39 @@ server.registerTool('project_map_context', {
   });
 });
 
+server.registerTool('project_map_scan', {
+  title: 'Scan the project natively - no-install file inventory + import map',
+  description: 'KLYPIX\'s own zero-install scanner: walks the repo (gitignore-aware, junk dirs like browser profiles and build output excluded), extracts FILE-LEVEL import edges for the JS/TS family (relative, tsconfig-alias, and monorepo-workspace imports resolved), and writes klypix-map/graph.json inside the project — the only thing it ever writes. The artifact then serves project_map_context automatically when no Graphify artifact exists. It deliberately does not build a per-symbol AST graph; deeper external artifacts remain importable through the same door.',
+  annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema: {
+    project: z.string().optional().describe('Absolute project root. Defaults to this MCP connection\'s configured project/vault.'),
+  },
+}, async ({ project }) => {
+  const root = typeof project === 'string' && project.trim() ? path.resolve(project.trim()) : path.resolve(mcpPresence.vault);
+  const result = scanNativeProjectMap({ project: root });
+  return toContent({
+    blocks: [{ kind: 'text', text: `Native project map written to \`${result.artifactRelative}\` (${result.viaGit ? 'gitignore-aware' : 'walk fallback'}${result.truncated ? '; TRUNCATED at the file cap' : ''}).\nFiles: ${result.counts.files.toLocaleString()}; parsed code files: ${result.counts.parsedCodeFiles.toLocaleString()}; import edges: ${result.counts.importEdges.toLocaleString()}; workspace packages: ${result.counts.workspacePackages}; minified skipped: ${result.counts.skippedMinified}.` }],
+    structured: result,
+  });
+});
+
+server.registerTool('project_map_drift', {
+  title: 'Check brain cards against the repo\'s real files (drift report)',
+  description: 'Read-only drift check: every brain card that references THIS project\'s files is verified against the working tree. Reports cards whose referenced files are gone or moved (with rename candidates by unique basename), and headlines when the checkout itself is behind its origin default branch — in that state a "missing" file may simply not be in this checkout. Slash-joined name enumerations and other-project paths are recognized and skipped, not reported as drift. Nothing is written; fix cards with a CORRECTION marker or by editing them in KLYPIX.',
+  annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema: {
+    project: z.string().optional().describe('Absolute project root. Defaults to this MCP connection\'s configured project/vault.'),
+    brain: z.string().optional().describe('Optional brain filename/path inside the project. Defaults to brain.klypix / brain.any.'),
+  },
+}, async ({ project, brain }) => {
+  const root = typeof project === 'string' && project.trim() ? path.resolve(project.trim()) : path.resolve(mcpPresence.vault);
+  const result = await checkBrainDrift({ project: root, brain });
+  return toContent({
+    blocks: [{ kind: 'text', text: brainDriftMarkdown(result) }],
+    structured: result,
+  });
+});
+
 server.registerTool('brain_challenge', {
   title: 'Challenge a decision against the brain (argue back with receipts)',
   description: 'BEFORE committing to a significant decision, ask the brain to ARGUE BACK: prior decisions that deterministically contradict the claim (correction-cue / opposite-polarity evidence — never mere topical similarity), 🛠 standing rules that dispute it, approaches tried before and REVERSED (with the correction/successor as the receipt), and open questions it collides with. Candidates, not verdicts — silence means "no deterministic contradiction signal", not verified consistency. Cards captured by a DIFFERENT agent are flagged so you coordinate instead of overriding. Dismiss a confirmed-false pair (after capturing the claim) with brain_connect pairs + relationship:"not_contradiction". Defaults to the project brain ("brain").',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.60.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' };