klypix-mcp 1.75.0 → 1.77.0

package/README.md

@@ -1,12 +1,14 @@
 # Every project gets a brain.
 
-**A portable project workspace with a shared brain.**
+**Active state management for multi-agent coding — a local-first active context engine with a shared brain.**
 *One project. One shared understanding.*
 
-**One shared project brain for multi-agent coding.** `klypix-mcp` gives supported coding agents
-and humans one versioned `brain.klypix` in your repo, containing current decisions, corrections,
-evidence anchors, open questions, active work, and handoffs. Agents read it and write to it over
-MCP. You read it and correct it in the [KLYPIX app](https://klypix.com).
+**One actively managed project brain for multi-agent coding.** `klypix-mcp` keeps one versioned
+`brain.klypix` in your repo: the project's active state — current decisions, corrections, evidence
+anchors, open questions, active work, and handoffs. Corrections supersede stale decisions,
+`brain_challenge` tests proposed decisions against standing rules and reversed approaches, and
+sessions declare their scope and get warned about same-machine file overlap. Agents read it and
+write to it over MCP. You read it and correct it in the [KLYPIX app](https://klypix.com).
 
 > **One project. Many agents. One current understanding.**
 

package/bin/klypix-install.mjs

@@ -246,7 +246,15 @@ 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\/(bench|brain-doctor|agent-presence|agent-rules|finding-routing|mcp-presence|mcp-supervisor|mcp-auto-update|presence-relay|semantic-memory|runtime-inspector|project-graph|git-capture-install)\.mjs/g, './$1.mjs')
+    // capture-gap: the worker imports it from BOTH brain_note (the per-session
+    // capture receipt) and brain_sync (the uncaptured-work check). Both are
+    // wrapped in try/catch by design, so an unflattened path here would not
+    // crash — it would make the agent-neutral half silently never fire in the
+    // deployed runtime. test/cli-args.mjs "G: no unresolved ../src/*.mjs" is the
+    // only thing standing between that and the field; it caught exactly this.
+    // (remote-client deliberately absent: the Remote feature was removed in
+    // 1.73.x, and this cherry-pick must not resurrect it — recorded rule.)
+    .replace(/\.\.\/src\/(bench|brain-doctor|agent-presence|agent-rules|capture-gap|enrichment|finding-routing|mcp-presence|mcp-supervisor|mcp-auto-update|presence-relay|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)`);
 
@@ -291,12 +299,15 @@ try {
     // (`git tag --points-at HEAD` semantics inside collectRepoState): the
     // release tag names the exact evidence commit, so any non-HEAD comparison
     // would certify code the tag never covered.
-    const checkout = exists(path.join(PKG_ROOT, '.git')) ? collectRepoState(PKG_ROOT) : null;
-    const sourceDecision = deploySourceDecision({ checkout, allowUntagged: ALLOW_UNTAGGED });
+    const gitPresent = exists(path.join(PKG_ROOT, '.git'));
+    const checkout = gitPresent ? collectRepoState(PKG_ROOT) : null;
+    const sourceDecision = deploySourceDecision({ checkout, allowUntagged: ALLOW_UNTAGGED, gitPresent });
     const checkoutLabel = `v${VERSION}, branch ${checkout?.branch || '(detached)'}, head ${checkout?.headShort || '?'}`;
     if (sourceDecision.action === 'refuse') {
         releaseInstallLockSync(installLock);
-        console.error(`✗ refusing to deploy an UNRELEASED source checkout machine-globally: ${checkoutLabel} — no release tag v${VERSION} at HEAD; no files were changed.`);
+        console.error(sourceDecision.source === 'unverifiable-git-state'
+            ? `✗ refusing to deploy from a git checkout whose state could NOT be verified: ${checkoutLabel} — the git probes failed (busy machine?); no files were changed. Retry, or acknowledge a dev deploy explicitly.`
+            : `✗ refusing to deploy an UNRELEASED source checkout machine-globally: ${checkoutLabel} — no release tag v${VERSION} at HEAD; no files were changed.`);
         console.error('  Released installs come from the registry: npx -y klypix-mcp@latest install');
         console.error('  To deliberately deploy this working tree (a dev deploy), acknowledge it: re-run with --allow-untagged or KLYPIX_MCP_ALLOW_UNTAGGED=1.');
         console.error('  An acknowledged dev deploy is stamped dev-owned, so brain_doctor shows it and auto-update will not silently replace it.');
@@ -380,7 +391,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', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.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', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.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 [
@@ -402,8 +413,19 @@ try {
     let n = 0;
     for (const st of renameOrder) { renameSyncWithBackoff(path.join(BRAIN_DIR, st.dst + '.klypix-new'), path.join(BRAIN_DIR, st.dst)); n++; }
 
-    // 3) mark the dir an ESM package
-    fs.writeFileSync(path.join(BRAIN_DIR, 'package.json'), JSON.stringify({ name: 'klypix-project-brain', private: true, type: 'module' }, null, 2));
+    // 3) mark the dir an ESM package — WITH the brain-core version in it. The
+    // version was only ever discoverable from .brain-version.json or by regexing
+    // the baked PKG_VERSION out of klypix-mcp-server.mjs; an agent asked "what
+    // version is this brain?", read package.json (the one place everybody looks),
+    // got `version: undefined`, and reported the install unidentifiable
+    // (2026-08-16 field report). This is provenance, never the gate: the
+    // never-downgrade decision still reads .brain-version.json / .mcp-runtime.json.
+    fs.writeFileSync(path.join(BRAIN_DIR, 'package.json'), JSON.stringify({
+        name: 'klypix-project-brain',
+        ...(VERSION ? { version: VERSION } : {}),
+        private: true,
+        type: 'module',
+    }, null, 2));
 
     // 5) wire the 4 hooks into settings.json (refuse on invalid JSON; back up;
     // atomic). A background runtime-only update refreshes the scripts while

package/bin/klypix-worker.mjs

@@ -686,7 +686,19 @@ server.registerTool('brain_note', {
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
   },
 }, async ({ text, marker, area, closes, canvas }, extra) => {
-  return toContent(await opBrainNote({ vault: mcpPresence.vault, canvas: boundBrainCanvas(canvas), text, area, marker: marker || '', closes, via: extra.klypixClientName }));
+  // Both 1.77 and 1.78 ride this call: the enrichment question (the asker's
+  // vocabulary for retrieval) AND the per-session capture receipt below.
+  const result = await opBrainNote({ vault: mcpPresence.vault, canvas: boundBrainCanvas(canvas), text, area, marker: marker || '', closes, via: extra.klypixClientName, enrichmentQuestion: mcpPresence.declaredIntent });
+  // Per-session capture receipt — this is what stops the uncaptured-work nudge
+  // from firing at a session that DID record its reasoning, just through MCP
+  // rather than a 🧠 marker. The Stop hook and this server share one session-id
+  // space (the same presence lane), so the receipt written here is the one the
+  // hook reads. Best-effort: a receipt failure must never fail the note.
+  try {
+    const { recordSessionCapture } = await import('../src/capture-gap.mjs');
+    recordSessionCapture(extra?.klypixRequestIdentity?.sessionId || mcpPresence.id);
+  } catch { /* receipt is best-effort */ }
+  return toContent(result);
 });
 
 server.registerTool('brain_message', {
@@ -796,6 +808,7 @@ server.registerTool('brain_sync', {
       shas: z.array(z.string().max(40)).max(20).optional().describe('Commit shas that MUST ride the next release. Stake after committing work a user was promised — the claim OUTLIVES this session (14d), and every future releaseIntent must contain these commits or acknowledge them by name.'),
       note: z.string().max(160).optional().describe('One line of why — shown verbatim in any refusal that names this claim ("founder was told the Arrow tool ships in the next build").'),
       withdraw: z.union([z.array(z.string().max(40)).max(20), z.boolean()]).optional().describe('Shas to withdraw from this session\'s claim; [] or true withdraws the whole claim. Only the staking session (or its logical continuation) can withdraw.'),
+      publish: z.boolean().optional().describe('Also write the claim as .klypix/claims/<owner>.json in the project (or delete that file when withdrawing). Commit it and the promise TRAVELS WITH THE REPO: every clone\'s release gate reads it, it is reviewable in PRs, and its history is auditable — team-wide claims over plain git, zero infrastructure.'),
     }).optional().describe('Stake a durable claim that specific commits ride the NEXT release — the promise "you\'ll see it in the next build" made machine-readable. Unlike presence rows (which age out ~10min after a session ends), a claim persists until fulfilled (the release ref contains the shas — auto-retired with a courtesy note), withdrawn, or expired (14d). A release that would drop claimed shas is REFUSED until they are acknowledged BY NAME, and acknowledging them away notifies the owner. Use exactly one of shas (stake/extend) or withdraw.'),
   },
 }, async ({ project, intent, files, phase, include_context, results, releaseIntent, releaseClaim }, extra) => {
@@ -876,6 +889,77 @@ server.registerTool('brain_sync', {
       }
     } catch { /* observation is best-effort — never fail a sync */ }
   }
+  // ── Uncaptured-work check, host-neutral half ────────────────────────────────
+  // The Stop hook can REFUSE a stop; every other host has no lifecycle hook at
+  // all, so brain_sync is the only place the same question can be asked. Stamp
+  // the git HEAD at "start", and at "complete" compare it against HEAD: commits
+  // that landed during this task with nothing recorded about WHY is the same gap
+  // the hook catches, and it produces the same drafted card. Advisory only — it
+  // never changes status/mutation, so completion semantics are untouched.
+  let captureGapText = '';
+  {
+    const projectDir = report.structured?.project || mcpPresence.vault;
+    const sid = String(extra?.klypixRequestIdentity?.sessionId || mcpPresence.id || '');
+    // `require` does not exist in ESM — the child_process binding has to be
+    // imported, and gitOut must stay synchronous for the ancestry/count chain.
+    let execFileSync = null;
+    try { ({ execFileSync } = await import('child_process')); } catch { /* no child_process → no check */ }
+    const gitOut = (args) => {
+      if (!execFileSync) return '';
+      try {
+        return String(execFileSync('git', args, { cwd: projectDir, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], timeout: 4000 })).trim();
+      } catch { return ''; }
+    };
+    // `git merge-base --is-ancestor` answers with its EXIT CODE and prints
+    // nothing, so it must be read as ok/not-ok — an output check would treat
+    // "not an ancestor" and "success" as the same empty string.
+    const gitOk = (args) => {
+      if (!execFileSync) return false;
+      try {
+        execFileSync('git', args, { cwd: projectDir, stdio: 'ignore', timeout: 4000 });
+        return true;
+      } catch { return false; }
+    };
+    try {
+      const gap = await import('../src/capture-gap.mjs');
+      if (phase === 'start' && projectDir && sid) {
+        const head = gitOut(['rev-parse', 'HEAD']);
+        if (head) gap.recordTaskBaseline(sid, { head, project: projectDir });
+      } else if (phase === 'complete' && projectDir && sid) {
+        const baseline = gap.readTaskBaseline(sid);
+        if (baseline?.head) {
+          // An ancestry check first: a rebase/reset makes the range meaningless,
+          // and reporting a rewritten history as "commits you didn't record" is
+          // exactly the cry-wolf that gets a nudge switched off.
+          const reachable = gitOk(['merge-base', '--is-ancestor', baseline.head, 'HEAD']);
+          const count = reachable ? Number(gitOut(['rev-list', '--count', '--no-merges', `${baseline.head}..HEAD`]) || 0) : 0;
+          if (count > 0) {
+            const subjects = gitOut(['log', '--no-merges', '--format=%s', `${baseline.head}..HEAD`])
+              .split('\n').map((s) => s.trim()).filter(Boolean).slice(0, 5);
+            // Bodies decide whether ANY rationale was recorded — the same rule
+            // the hook uses, so the two halves never disagree about one session.
+            const withRationale = gitOut(['log', '--no-merges', '--format=%x1e%b', `${baseline.head}..HEAD`])
+              .split('\x1e').map((b) => b.replace(/\s+/g, ' ').trim()).filter((b) => b.length >= 12).length;
+            const decision = gap.captureGapDecision({
+              commitTotal: count,
+              commitCards: withRationale,
+              sessionCaptured: gap.sessionHasCaptured(sid),
+            });
+            if (decision) {
+              const changed = gitOut(['diff', '--name-only', `${baseline.head}..HEAD`]).split('\n').filter(Boolean).slice(0, 20);
+              const draft = gap.draftCaptureMarker({
+                commits: subjects.map((subject) => ({ subject })),
+                filesTouched: changed,
+              });
+              captureGapText = gap.captureGapReason({ ...decision, draft, mode: 'advise' });
+              gap.recordCaptureGapNudge(sid);
+            }
+          }
+        }
+        gap.clearTaskBaseline(sid);
+      }
+    } catch { /* the check never fails a sync */ }
+  }
   let taskContext = null;
   if (phase !== 'complete' && include_context !== false && (intent || files?.length)) {
     taskContext = await opBrainTaskContext({
@@ -926,7 +1010,7 @@ server.registerTool('brain_sync', {
   return {
     content: [{
       type: 'text',
-      text: [report.text, harnessText, shipNotice, contextText, timingText].filter(Boolean).join('\n\n'),
+      text: [report.text, harnessText, shipNotice, captureGapText, contextText, timingText].filter(Boolean).join('\n\n'),
     }],
     structuredContent,
     ...(report.isError ? { isError: true } : {}),

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "klypix-mcp",
-  "version": "1.75.0",
-  "description": "Shared project brain and MCP coordination server for multi-agent coding.",
+  "version": "1.77.0",
+  "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
   "license": "Apache-2.0",
   "keywords": [
@@ -83,7 +83,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.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/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.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/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.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-security.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/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.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/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.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-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/enrichment.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.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/capture-gap.mjs

@@ -0,0 +1,258 @@
+// Uncaptured-work detection — ONE implementation, every host.
+//
+// Capture is opt-in: something has to CHOOSE to emit a 🧠 marker or call
+// brain_note. That fails hardest exactly where it matters most — a long, loaded
+// session is both the least likely to remember and the most likely to have
+// produced something worth keeping. The 2026-08-16 field report is the canonical
+// instance: a multi-session workstream took a file format to a REGISTERED IANA
+// media type (spec written, 8 schema-drift bugs fixed, PR merged, registration
+// landed) and the brain recorded NONE of it — the agent had been writing to its
+// own private per-project memory dir the whole time, which no peer can read.
+//
+// This module holds the parts that must behave identically whether the caller is
+// the Claude Code Stop hook (which can REFUSE the stop) or an MCP host calling
+// brain_sync(phase:"complete") (which can only advise). Both ask the same
+// question of the same facts and hand back the same drafted card.
+//
+// Three deliberate properties, each learned the hard way:
+//
+//   • A DRAFT, NOT AN ASSIGNMENT. Asking a drained session to "record the
+//     decision" buys a one-line receipt ("merged PR #406") — the event, never
+//     the reasoning, which is the half that was actually lost. So the draft
+//     pre-fills every mechanical fact from the artifacts themselves (ship, commit
+//     subjects, files, area) and leaves exactly ONE slot: why it matters. The
+//     agent supplies the only sentence it alone knows, or discards the card.
+//
+//   • PER-SESSION PROVENANCE, NOT FILE MTIME. The first cut stayed silent when
+//     brain.klypix changed during the session — which, on a shared brain with
+//     ten live sessions, means a PEER's card silences the session that shipped
+//     and recorded nothing. That is backwards: it goes quiet exactly in the
+//     multi-agent case. Silence now requires THIS session id to have captured.
+//
+//   • NARROW ON PURPOSE. A nudge that cries wolf gets ignored, then disabled.
+//     It needs a real artifact and a total absence of recorded rationale — a
+//     good commit body IS capture and buys silence.
+
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+
+// Shared sidecar: which sessions have been nudged (once each) and which have
+// captured something (so a later turn in the same session stays quiet). Lives
+// beside the other brain-home state; the Claude Code session id and the MCP
+// presence session id are the SAME id space (the hook and the server share one
+// lane), so a brain_note through MCP correctly silences the Stop hook.
+export function captureGapStatePath(home = os.homedir()) {
+    return path.join(home, '.claude', 'project-brain', '.capture-gap.json');
+}
+
+export function readCaptureGapState(file = captureGapStatePath()) {
+    try {
+        const j = JSON.parse(fs.readFileSync(file, 'utf8'));
+        return {
+            nudged: Array.isArray(j?.nudged) ? j.nudged.map(String) : [],
+            captured: (j && typeof j.captured === 'object' && !Array.isArray(j.captured)) ? j.captured : {},
+            baselines: (j && typeof j.baselines === 'object' && !Array.isArray(j.baselines)) ? j.baselines : {},
+        };
+    } catch { return { nudged: [], captured: {}, baselines: {} }; }
+}
+
+// Best-effort, never throws. A torn write only loses the memo — `stop_hook_active`
+// remains the primary loop guard and a re-nudge is bounded to one extra turn.
+function writeCaptureGapState(state, file) {
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        fs.writeFileSync(file, JSON.stringify(state));
+    } catch { /* best-effort */ }
+}
+
+export function recordCaptureGapNudge(sessionId, file = captureGapStatePath()) {
+    const sid = String(sessionId || ''); if (!sid) return;
+    const state = readCaptureGapState(file);
+    state.nudged = [...state.nudged.filter(s => s !== sid), sid].slice(-300);
+    writeCaptureGapState(state, file);
+}
+
+// Called by EVERY capture path that knows its session: the Stop hook after an
+// authored capture, and the brain_note MCP verb. This is what makes the silence
+// rule per-session instead of per-file.
+export function recordSessionCapture(sessionId, file = captureGapStatePath(), now = Date.now()) {
+    const sid = String(sessionId || ''); if (!sid) return;
+    const state = readCaptureGapState(file);
+    state.captured[sid] = now;
+    // Bound the map: keep the 300 most recent sessions.
+    const entries = Object.entries(state.captured).sort((a, b) => Number(b[1]) - Number(a[1])).slice(0, 300);
+    state.captured = Object.fromEntries(entries);
+    writeCaptureGapState(state, file);
+}
+
+export function sessionHasCaptured(sessionId, file = captureGapStatePath()) {
+    const sid = String(sessionId || ''); if (!sid) return false;
+    return Boolean(readCaptureGapState(file).captured[sid]);
+}
+
+// ── Task baseline, for hosts with no lifecycle hook ──────────────────────────
+// The Stop hook gets its commit window from the hook's own per-project baseline.
+// An MCP host has no such thing, so brain_sync stamps the git HEAD at phase
+// "start" and reads it back at phase "complete" — the same "what landed during
+// this task" question, answered from the only two calls every host makes. Kept
+// in the same sidecar so there is one file to reason about.
+export function recordTaskBaseline(sessionId, { head = '', project = '' } = {}, file = captureGapStatePath(), now = Date.now()) {
+    const sid = String(sessionId || ''); if (!sid || !head) return;
+    const state = readCaptureGapState(file);
+    state.baselines = (state.baselines && typeof state.baselines === 'object' && !Array.isArray(state.baselines)) ? state.baselines : {};
+    state.baselines[sid] = { head: String(head), project: String(project || ''), at: now };
+    const entries = Object.entries(state.baselines).sort((a, b) => Number(b[1]?.at || 0) - Number(a[1]?.at || 0)).slice(0, 300);
+    state.baselines = Object.fromEntries(entries);
+    writeCaptureGapState(state, file);
+}
+
+export function readTaskBaseline(sessionId, file = captureGapStatePath()) {
+    const sid = String(sessionId || ''); if (!sid) return null;
+    const b = readCaptureGapState(file).baselines?.[sid];
+    return (b && b.head) ? b : null;
+}
+
+export function clearTaskBaseline(sessionId, file = captureGapStatePath()) {
+    const sid = String(sessionId || ''); if (!sid) return;
+    const state = readCaptureGapState(file);
+    if (state.baselines?.[sid]) { delete state.baselines[sid]; writeCaptureGapState(state, file); }
+}
+
+// ── The decision ─────────────────────────────────────────────────────────────
+// Returns null to stay silent, or the observed evidence. Pure: every input is
+// supplied by the caller, so the Stop hook (transcript + git) and brain_sync
+// (git + presence) can answer the same question from what each can see.
+export function captureGapDecision({
+    authored = 0, commitTotal = 0, commitCards = 0, shipped = [], pushed = false,
+    filesTouched = 0, sessionCaptured = false, stopHookActive = false,
+    alreadyNudged = false, env = process.env,
+} = {}) {
+    if (String(env.KLYPIX_BRAIN_NUDGE || '').toLowerCase() === 'off') return null;
+    if (stopHookActive || alreadyNudged) return null;
+    if (authored > 0 || commitCards > 0) return null;      // rationale exists somewhere
+    if (sessionCaptured) return null;                      // THIS session already fed the brain
+    const significant = shipped.length > 0 || commitTotal >= 2
+        || (pushed && commitTotal >= 1) || filesTouched >= 6;
+    if (!significant) return null;
+    const undocumented = Math.max(0, commitTotal - commitCards);
+    const evidence = [];
+    if (shipped.length) evidence.push(shipped.slice(0, 3).join(' · '));
+    if (commitTotal) evidence.push(`${commitTotal} new commit${commitTotal === 1 ? '' : 's'}${undocumented === commitTotal ? ' (no rationale body on any of them)' : ''}`);
+    else if (pushed) evidence.push('pushed to a remote');
+    if (filesTouched) evidence.push(`${filesTouched} file${filesTouched === 1 ? '' : 's'} edited`);
+    return evidence.length ? { evidence } : null;
+}
+
+// ── The draft ────────────────────────────────────────────────────────────────
+const slug = (s) => String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+const CC_SCOPE = /^(?:feat|fix|perf|refactor|chore|docs|test|build|ci)(?:\(([^)]+)\))?!?:\s*(.+)$/i;
+
+// The area a drafted card should land in, inferred from what the session
+// actually touched: a conventional-commit scope first (the author's own label),
+// then the dominant source directory, then a neutral fallback. Never invents a
+// topic — an area guessed from prose is worse than "Ship".
+export function inferArea({ commits = [], filesTouched = [] } = {}) {
+    for (const c of commits) {
+        const m = CC_SCOPE.exec(String(c?.subject || ''));
+        if (m && m[1] && m[1].trim()) return m[1].trim();
+    }
+    const counts = new Map();
+    for (const p of filesTouched) {
+        const parts = String(p).replace(/\\/g, '/').split('/').filter(Boolean);
+        // Skip a leading src/lib/app wrapper — "src" is never a useful area.
+        const seg = parts.length >= 2
+            ? (/^(src|lib|app|packages|apps)$/i.test(parts[0]) ? parts[1] : parts[0])
+            : '';
+        if (seg && !/\./.test(seg)) counts.set(seg, (counts.get(seg) || 0) + 1);
+    }
+    let best = '', n = 0;
+    for (const [k, v] of counts) if (v > n) { best = k; n = v; }
+    return best || 'Ship';
+}
+
+const shortFileList = (files, max = 3) => {
+    const uniq = [...new Set(files.map(f => String(f).replace(/\\/g, '/').split('/').pop()).filter(Boolean))];
+    if (!uniq.length) return '';
+    const head = uniq.slice(0, max).join(', ');
+    return uniq.length > max ? `${head} (+${uniq.length - max} more)` : head;
+};
+
+// Build the ready-to-emit marker. Everything mechanical is filled in from the
+// artifacts; the ONE thing left blank is the sentence only the session can
+// supply. That asymmetry is the whole design — a fully pre-written card would
+// just be approved, and we would be back to capturing the event without the why.
+export const WHY_SLOT = '<one sentence: the decision, obligation, or discovery a future session needs — if there is none, say so and discard this>';
+// A draft pasted back with the slot STILL IN IT is a placeholder wearing a
+// card's clothes: it would sit in the brain reading, to every future session, as
+// though the reasoning had been recorded. That is strictly worse than no card,
+// so the marker guard refuses it and says why. The sentinel deliberately matches
+// the head of WHY_SLOT above — test/capture-gap.mjs asserts the two agree, so
+// they cannot drift apart in silence.
+export const UNFILLED_DRAFT_RE = /WHY THIS MATTERS:\s*<\s*one sentence/i;
+export const looksLikeUnfilledDraft = (text) => UNFILLED_DRAFT_RE.test(String(text || ''));
+export function draftCaptureMarker({ shipped = [], commits = [], filesTouched = [], area = '' } = {}) {
+    const resolvedArea = area || inferArea({ commits, filesTouched });
+    const facts = [];
+    if (shipped.length) facts.push(shipped.slice(0, 2).join(' · '));
+    const subjects = commits
+        .map(c => { const m = CC_SCOPE.exec(String(c?.subject || '')); return (m ? m[2] : String(c?.subject || '')).trim(); })
+        .filter(Boolean).slice(0, 3);
+    if (subjects.length) facts.push(subjects.map(s => `"${s}"`).join('; '));
+    const files = shortFileList(filesTouched);
+    if (files) facts.push(files);
+    // A ship with no subjects and no files still deserves a draft — the marker
+    // shape matters more than the richness of the pre-fill.
+    const head = facts.length ? facts.join(' — ') : 'work completed this session';
+    const marker = shipped.length ? '!' : '';           // a ship is a milestone; everything else a decision
+    return {
+        area: resolvedArea,
+        marker,
+        text: `${head}. WHY THIS MATTERS: ${WHY_SLOT}`,
+        line: `🧠 BRAIN [${resolvedArea}]${marker ? ' ' + marker : ''}: ${head}. WHY THIS MATTERS: ${WHY_SLOT}`,
+        tags: [`#${slug(resolvedArea)}`].filter(Boolean),
+    };
+}
+
+// ── The message ──────────────────────────────────────────────────────────────
+// `mode` picks the register: 'refuse' is the Stop hook, which has just declined
+// to end the turn; 'advise' is brain_sync(complete) on a host with no lifecycle
+// hook, where this is the only channel available and nothing is being blocked.
+export function captureGapReason({ evidence = [], draft = null, mode = 'refuse' } = {}) {
+    const lead = mode === 'refuse'
+        ? '[brain] 🧠 UNCAPTURED WORK — this session produced durable artifacts and recorded NOTHING in the project brain.'
+        : '🧠 UNCAPTURED WORK — this task produced durable artifacts and recorded nothing in the project brain.';
+    const out = [
+        lead,
+        `  Observed: ${evidence.join(' · ')}.`,
+        '  Nothing recorded the reasoning: no 🧠 marker, no ✓/~, no rationale-bearing commit body, and this',
+        '  session has not written the brain through any channel.',
+    ];
+    if (draft) {
+        out.push(
+            '',
+            '  A card is DRAFTED from what this session actually did. The facts are filled in; supply the one',
+            '  sentence only you know, then emit it verbatim (or correct it first):',
+            '',
+            `    ${draft.line}`,
+            '',
+            mode === 'refuse'
+                ? '  Emitting that line in your reply is all it takes — the Stop hook harvests it. Or call brain_note.'
+                : '  Pass it to brain_note (text + area), or emit it as a marker if your host harvests them.',
+        );
+    } else {
+        out.push(
+            '  Record it now — one line in your reply:',
+            '    🧠 BRAIN [Area]: <the decision and why>      (`!` milestone · `?` open question · `+` reusable rule)',
+            '  — or call the brain_note MCP verb.',
+        );
+    }
+    out.push(
+        mode === 'refuse'
+            ? '  If there is genuinely nothing durable to keep, say so in one sentence and stop; this will not ask again this session.'
+            : '  If there is genuinely nothing durable to keep, ignore this; it will not be raised again for this session.',
+        '  NOTE: your own memory directory (~/.claude/projects/<project>/memory/) is NOT the project brain. Writing',
+        '  there is private to this host — no other session, agent, or human can read it. Only brain.klypix is shared.',
+    );
+    return out.join('\n') + '\n';
+}