klypix-mcp 1.51.0 → 1.52.0

package/README.md

@@ -162,18 +162,21 @@ not a filing convention.
 - **You can ask what the project believed then.** `brain_ask` with `as_of: 2026-03-01` reweights
   ranking by card lifecycle dates, so corrections made later do not leak backwards.
 - **Retrieval is local.** Lexical by default. If the optional on-device model is installed,
-  `brain_ask` and `search_all_brains` blend semantic similarity with lexical scoring and rerank
-  with a cross-encoder — still entirely on your machine. Without it, retrieval degrades cleanly to
-  lexical. `npx klypix-mcp install` deliberately does not install that model, so a fresh install
-  is lexical.
+  `brain_ask` and `search_all_brains` use BGE semantic ranking with lexical help for exact
+  identifiers, paths, and versions — still entirely on your machine. The previous cross-encoder
+  is available for experiments with `KLYPIX_RERANK=1`, but is off by default because it reduced
+  precision and added latency on the frozen human-paraphrase evaluation. Without the embedding
+  model, retrieval degrades cleanly to lexical. `npx klypix-mcp install` deliberately does not
+  install that model, so a fresh install is lexical.
 
 ### Bounded semantic-memory runtime
 
 Long-lived MCP and A2A workers use the bounded semantic-memory runtime by default. Models load only
 when semantic work is requested, native inference is serialized per process, embedding work is
-split into small batches, cross-encoder candidates are scored in bounded batches before one global
-sort, and temporary tensors are released after use. These controls change the resource lifecycle
-only; brain cards, ranking rules, project coordination, and the on-disk brain format are unchanged.
+split into small batches, and temporary tensors are released after use. Loaded models retire after
+an idle interval and transparently reload on the next semantic request, so warm queries stay fast
+without permanently pinning native model memory. These controls change the resource lifecycle only;
+brain cards, project coordination, and the on-disk brain format are unchanged.
 
 The previous runtime remains available as an emergency rollback. Set
 `KLYPIX_SEMANTIC_MEMORY_MODE=legacy` in the MCP server environment and reconnect or restart the
@@ -184,6 +187,12 @@ Run the deterministic lifecycle tests with `npm run test:memory`. For an opt-in
 against a disposable or backed-up brain, set `KLYPIX_MEMORY_SOAK_BRAIN` to its path and run
 `npm run test:memory:soak`.
 
+For process-level attribution, run `npx klypix-mcp runtime` (or add `--json`; `--watch 30` samples
+every 30 seconds). It reports KLYPIX workers, supervisors, and legacy launcher overhead separately,
+excludes the owning IDE/chat application's RAM, redacts command-line secrets, and never opens a
+brain or terminates a process. Multiple processes under one host are reported as parallel sessions,
+not called duplicates without an authoritative logical-session receipt.
+
 ---
 
 ## Supported hosts and their integration level
@@ -365,6 +374,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `npx klypix-mcp install` | Install the engine + Claude Code hooks on this machine (see Quick start) |
 | `npx klypix-mcp link` | Wire this project for Cursor, Cline, Windsurf, Copilot, Gemini CLI, Aider (`--check` audits) |
 | `npx klypix-mcp doctor` | One verdict: version, hosts, live sessions, tool count, drift. Exits non-zero — usable as a CI gate |
+| `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 diff [ref]` | Card-level brain diff against a git ref, as markdown |
@@ -488,6 +498,12 @@ settings and project files. The check is detached and fail-open, developer-owned
 protected, concurrent sessions collapse behind one lock, and `KLYPIX_AUTO_UPDATE=0` opts out
 entirely.
 
+When the optional semantic runtime is already enabled, an update also schedules one detached,
+single-writer cache migration across registered brains. That removes the multi-minute first-query
+re-index after a model/cache upgrade; cache writes are model-keyed and atomic across concurrent
+agent sessions. Lexical-only installs download nothing. Set `KLYPIX_SEMANTIC_WARM_ON_UPDATE=0` to
+keep lazy first-use indexing instead.
+
 ## Security and permissions
 
 - **Apache-2.0, source public** at [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
@@ -495,7 +511,8 @@ entirely.
   deterministic and local; the only LLM anywhere is *your* agent. The one exception in this package
   is the supervisor's once-per-24h npm version check described above — turn it off with
   `KLYPIX_AUTO_UPDATE=0`.
-- **The optional semantic model runs on device.** No cloud inference on any retrieval path.
+- **The optional semantic model runs on device.** Enabling it (or upgrading its model) can fetch
+  model weights from Hugging Face; retrieval inference and brain data stay local.
 - **Coordination state is local files.** The brain is a file in your repo; the presence lane is a
   file under your home directory. Nothing is uploaded.
 - **`install` writes to your home directory:** `~/.claude/project-brain` (engine + runtime),
@@ -579,6 +596,7 @@ Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or wi
 ## Contributing
 
 Issues and pull requests: [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
+Questions or feedback: [hello@klypix.com](mailto:hello@klypix.com).
 
 The repository carries 38 test files, 34 of them in the `npm test` chain, covering the presence
 lane and its cross-machine relay, the Context Gateway, supervisor hot-swap, auto-update, retrieval

package/bin/klypix-a2a.mjs

@@ -146,8 +146,8 @@ function agentCard(publicUrl) {
     }] : []),
     {
       id: 'brain_connect',
-      name: 'Densify the brain graph (connect related cards)',
-      description: 'Find genuinely related but unlinked cards and propose (or, with apply, draw) connections — semantic when the on-device model is present, else shared tags + [[mentions]]. Additive; never deletes.',
+      name: 'Repair orphaned brain cards (connect related cards)',
+      description: 'Propose related links for orphaned decision/milestone cards by default, with a before→projected receipt; apply draws only additive, removable connections and never archives or rewrites cards. Pass scope:"all" for deliberate whole-graph densification.',
       tags: ['brain', 'graph', 'connect', 'memory'],
       examples: ['Connect the related cards in my project brain'],
       inputModes: ['text/plain', 'application/json'],
@@ -256,8 +256,11 @@ async function runSkill(skill, args, text, via) {
       const target = confinedCanvas(args.canvas);
       if (!target.ok) return refusedCanvas(args.canvas);
       const max = Math.max(1, Math.min(200, Math.floor(finiteNumber(args.max, 24))));
-      const threshold = Math.max(0.3, Math.min(1, finiteNumber(args.threshold, 0.45)));
-      return await opBrainConnect({ vault: VAULT, canvas: target.canvas, apply: args.apply === true, max, threshold, log });
+      const threshold = args.threshold == null
+        ? null
+        : Math.max(0.3, Math.min(1, finiteNumber(args.threshold, 0.55)));
+      const scope = args.scope === 'all' ? 'all' : 'orphans';
+      return await opBrainConnect({ vault: VAULT, canvas: target.canvas, apply: args.apply === true, max, threshold, scope, log });
     }
     case 'make_board':
     {

package/bin/klypix-install.mjs

@@ -17,6 +17,7 @@ import fs from 'fs';
 import os from 'os';
 import path from 'path';
 import crypto from 'crypto';
+import { spawn } from 'child_process';
 import { fileURLToPath } from 'url';
 import {
     connectCodexMcpServer,
@@ -225,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)\.mjs/g, './$1.mjs')
+    .replace(/\.\.\/src\/(brain-doctor|agent-rules|mcp-presence|mcp-supervisor|mcp-auto-update|semantic-memory|runtime-inspector)\.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)`);
 
@@ -292,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', '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', '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', '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 [
@@ -300,6 +301,8 @@ try {
         ['klypix-worker.mjs', 'klypix-mcp-worker.mjs'],
         ['klypix-a2a.mjs', 'klypix-a2a-server.mjs'],
         ['klypix-conformance.mjs', 'klypix-conformance.mjs'],
+        ['klypix-runtime.mjs', 'klypix-runtime.mjs'],
+        ['klypix-semantic-warm.mjs', 'klypix-semantic-warm.mjs'],
     ]) {
         const s = path.join(BIN, src); if (exists(s)) staged.push({ dst, content: flatten(fs.readFileSync(s, 'utf8')) });
     }
@@ -381,6 +384,27 @@ try {
     const notWired = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse'].filter(e => !wiredFor(e));
 
     if (gotLock) releaseLock();
+    // Users who already enabled the optional local semantic runtime should not
+    // pay a multi-minute first question after a model/cache contract upgrade.
+    // Migrate registered brains once in a detached process after the atomic
+    // runtime commit. Fresh lexical-only installs download nothing.
+    let semanticWarm = 'not-enabled';
+    const semanticRuntime = path.join(BRAIN_DIR, 'semantic', 'node_modules', '@huggingface', 'transformers');
+    if (process.env.KLYPIX_SEMANTIC_WARM_ON_UPDATE !== '0' && exists(semanticRuntime)) {
+        try {
+            const warmArgs = [path.join(BRAIN_DIR, 'klypix-semantic-warm.mjs'), '--brain-dir', BRAIN_DIR];
+            const currentBrain = ['brain.klypix', 'brain.any'].map(name => path.join(process.cwd(), name)).find(exists);
+            if (currentBrain) warmArgs.push('--brain', currentBrain);
+            const warm = spawn(process.execPath, warmArgs, {
+                detached: true,
+                stdio: 'ignore',
+                windowsHide: true,
+                env: { ...process.env, KLYPIX_SEMANTIC_WARM_ON_UPDATE: '1' },
+            });
+            warm.unref();
+            semanticWarm = 'scheduled';
+        } catch { semanticWarm = 'deferred'; }
+    }
     if (!RUNTIME_ONLY) reportCodex(codex);
     console.log(`✓ installed klypix brain v${VERSION} → ${BRAIN_DIR}  (${n} scripts, ${deps} dep packages)`);
     if (RUNTIME_ONLY) console.log('✓ runtime-only update: host settings and project files were preserved');

package/bin/klypix-mcp.mjs

@@ -19,7 +19,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-const DIRECT = new Set(['install', 'link', 'doctor', 'conformance', 'garden-code', 'init', 'git-driver', 'diff', 'pr-brief', 'uninstall']);
+const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'diff', 'pr-brief', 'uninstall']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -28,6 +28,7 @@ const USAGE = [
   '  install [--force] [--codex-hooks]   install/update this machine\'s brain engine + Claude Code hooks',
   '  link [dir] [--check]                project this project\'s 14 managed agent config files (--check audits, writes nothing, exits 1 on drift)',
   '  doctor [--npm] [--all] [--json]     read-only self-check; exits 1 on drift',
+  '  runtime [--json] [--watch seconds]  passive MCP process/RAM attribution; never terminates a process',
   '  conformance [--json]                launch two real MCP clients against this build',
   '  init                                seed a starter ./brain.klypix + print an MCP config',
   '  garden-code [brain]                 print the human approval code for brain_garden',
@@ -54,7 +55,10 @@ if (verb && !verb.startsWith('-') && !DIRECT.has(verb)) {
   process.exit(2);
 }
 
-if (DIRECT.has(verb)) {
+if (verb === 'runtime') {
+  process.argv.splice(2, 1);
+  await import('./klypix-runtime.mjs');
+} else if (DIRECT.has(verb)) {
   await import('./klypix-worker.mjs');
 } else {
   const { runMcpSupervisor } = await import('../src/mcp-supervisor.mjs');

package/bin/klypix-runtime.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+import os from 'os';
+import path from 'path';
+import { formatRuntimeReport, inspectKlypixRuntime } from '../src/runtime-inspector.mjs';
+
+const args = process.argv.slice(2);
+const valueAfter = (flag) => {
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : null;
+};
+const json = args.includes('--json');
+const brainDir = valueAfter('--brain-dir') || path.join(os.homedir(), '.claude', 'project-brain');
+const watchSeconds = Math.max(0, Number(valueAfter('--watch') || 0));
+
+const sample = () => {
+  try {
+    const report = inspectKlypixRuntime({ brainDir });
+    process.stdout.write((json ? JSON.stringify(report) : formatRuntimeReport(report)) + '\n');
+  } catch (error) {
+    const message = error?.message || String(error);
+    if (json) process.stdout.write(JSON.stringify({ schemaVersion: 1, passive: true, mutated: false, error: message }) + '\n');
+    else process.stderr.write(`KLYPIX runtime inspection failed: ${message}\n`);
+    process.exitCode = 1;
+  }
+};
+
+sample();
+if (watchSeconds > 0) {
+  const timer = setInterval(sample, Math.max(5, watchSeconds) * 1_000);
+  process.once('SIGINT', () => { clearInterval(timer); process.exit(); });
+  process.once('SIGTERM', () => { clearInterval(timer); process.exit(); });
+}
+

package/bin/klypix-semantic-warm.mjs

@@ -0,0 +1,93 @@
+#!/usr/bin/env node
+// One detached, best-effort cache migration after a compatible core update.
+// It runs only when the optional semantic runtime already exists, processes
+// registered brains sequentially, and never changes brain content.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { parseKlypix } from '../src/klypix-format.mjs';
+import { readRegisteredProjectBrains } from '../src/mcp-auto-update.mjs';
+import {
+  EMBEDDING_CACHE_KEY,
+  disposeSemanticModels,
+  getEmbedderForUse,
+  vectorsForBrain,
+} from '../src/semantic-memory.mjs';
+
+const arg = (name, fallback = null) => {
+  const index = process.argv.indexOf(`--${name}`);
+  return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+};
+const brainDir = path.resolve(arg('brain-dir', path.join(os.homedir(), '.claude', 'project-brain')));
+const lockFile = path.join(brainDir, '.semantic-update-warm.lock');
+const statusFile = path.join(brainDir, '.semantic-update-warm.json');
+const explicitBrain = arg('brain');
+const startedAt = Date.now();
+let lock = null;
+
+const atomicJson = (file, value) => {
+  const tmp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(tmp, `${JSON.stringify(value, null, 2)}\n`);
+  fs.renameSync(tmp, file);
+};
+
+try {
+  fs.mkdirSync(brainDir, { recursive: true });
+  try {
+    lock = fs.openSync(lockFile, 'wx');
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+    let stale = false;
+    try { stale = Date.now() - fs.statSync(lockFile).mtimeMs > 30 * 60_000; } catch { stale = true; }
+    if (!stale) process.exit(0);
+    try { fs.unlinkSync(lockFile); } catch { process.exit(0); }
+    lock = fs.openSync(lockFile, 'wx');
+  }
+  fs.writeFileSync(lock, JSON.stringify({ pid: process.pid, startedAt, modelKey: EMBEDDING_CACHE_KEY }));
+
+  const registered = readRegisteredProjectBrains(brainDir).map(item => item.brainPath);
+  const candidates = [...new Set([explicitBrain ? path.resolve(explicitBrain) : null, ...registered].filter(Boolean))]
+    .filter(file => {
+      try { return fs.statSync(file).isFile(); } catch { return false; }
+    });
+  if (!candidates.length) {
+    atomicJson(statusFile, { protocol: 1, result: 'no-registered-brains', modelKey: EMBEDDING_CACHE_KEY, completedAt: new Date().toISOString() });
+  } else {
+    const pipe = await getEmbedderForUse(() => {}, 5 * 60_000);
+    if (!pipe) {
+      atomicJson(statusFile, { protocol: 1, result: 'semantic-unavailable', modelKey: EMBEDDING_CACHE_KEY, completedAt: new Date().toISOString() });
+    } else {
+      let warmed = 0, failed = 0, cards = 0;
+      for (const file of candidates) {
+        try {
+          const { struct } = await parseKlypix(fs.readFileSync(file));
+          const vectors = await vectorsForBrain(pipe, file, struct.cards);
+          warmed++;
+          cards += vectors.size;
+        } catch { failed++; }
+      }
+      atomicJson(statusFile, {
+        protocol: 1,
+        result: failed ? (warmed ? 'partial' : 'failed') : 'ready',
+        modelKey: EMBEDDING_CACHE_KEY,
+        brains: candidates.length,
+        warmed,
+        failed,
+        cards,
+        durationMs: Date.now() - startedAt,
+        completedAt: new Date().toISOString(),
+      });
+    }
+  }
+} catch {
+  // Background migration is fail-open: a later brain_ask can still warm lazily.
+} finally {
+  try { await disposeSemanticModels(); } catch { /* */ }
+  try { if (lock != null) fs.closeSync(lock); } catch { /* */ }
+  try { fs.unlinkSync(lockFile); } catch { /* */ }
+}
+
+// onnxruntime can retain background handles after model disposal on Windows.
+// This is a detached one-shot migration, so terminate deterministically after
+// every cache/status write and cleanup has completed.
+process.exit(0);

package/bin/klypix-worker.mjs

@@ -30,9 +30,13 @@ import {
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
   opBrainTaskContext,
 } from '../src/klypix-core.mjs';
-import { mcpServerEntry } from '../src/agent-rules.mjs';
+import { auditProject, compactAgentsBrief, linkProject, mcpServerEntry } from '../src/agent-rules.mjs';
 import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS } from '../src/mcp-presence.mjs';
-import { spawnAutoUpdateHelper } from '../src/mcp-auto-update.mjs';
+import {
+  reconcileRegisteredProjects,
+  registerProjectBrain,
+  spawnAutoUpdateHelper,
+} from '../src/mcp-auto-update.mjs';
 // Namespace import (already in-process via the klypix-core chain, so zero added
 // load cost) so a bundle whose klypix-format predates classifyDecay degrades
 // gracefully — a named import of a missing export would kill the whole server.
@@ -41,6 +45,10 @@ import * as brainFormat from '../src/klypix-format.mjs';
 // Real package version for the MCP handshake (was hardcoded '1.0.0', which
 // misled every client/version diagnosis — it could never reflect the true release).
 const PKG_VERSION = (() => { try { return createRequire(import.meta.url)('../package.json').version; } catch { return '0.0.0'; } })();
+const RUNTIME_BRAIN_DIR = path.dirname(
+  process.env.KLYPIX_MCP_RUNTIME_MANIFEST
+  || path.join(os.homedir(), '.claude', 'project-brain', '.mcp-runtime.json'),
+);
 
 // IMPORTANT: stdout is the JSON-RPC channel. Never console.log — only stderr.
 const log = (...a) => console.error('[klypix-mcp]', ...a);
@@ -216,7 +224,7 @@ server.registerTool('search_canvases', {
 
 server.registerTool('search_all_brains', {
   title: 'Search every project brain on this machine',
-  description: 'Cross-project memory search: looks through every brain.klypix this machine has REGISTERED, not just the current vault. Ranking is lexical, blended with on-device semantic similarity ONLY when the optional local model is installed (a fresh `npx klypix-mcp install` is lexical) — it degrades cleanly, never errors. Use when the answer may live in ANOTHER project\'s decisions. Optional as_of (YYYY-MM-DD) answers "what was true then" — superseded cards count as live if they were current at that date. LIMIT: the cross-project registry is written by the Claude Code lifecycle hook and by nothing else, so on a Codex-only or Cursor-only machine this returns an empty result — that is a missing registry, not "no match".',
+  description: 'Cross-project memory search: looks through every brain.klypix this machine has REGISTERED, not just the current vault. Ranking is lexical, blended with on-device semantic similarity ONLY when the optional local model is installed (a fresh `npx klypix-mcp install` is lexical) — it degrades cleanly, never errors. Use when the answer may live in ANOTHER project\'s decisions. Optional as_of (YYYY-MM-DD) answers "what was true then" — superseded cards count as live if they were current at that date. The registry is populated by Claude lifecycle and by brain_sync on any MCP host; a project that has never started through either path is absent from cross-project search.',
   inputSchema: {
     query: z.string().describe('What to find across all project brains.'),
     as_of: z.string().optional().describe('Optional YYYY-MM-DD: rank what was TRUE at that date (time-travel query).'),
@@ -270,16 +278,17 @@ server.registerTool('brain_lens', {
 
 server.registerTool('brain_connect', {
   title: 'Connect related-but-unlinked brain cards (densify the graph)',
-  description: 'Finds genuinely related cards that AREN\'T linked yet and proposes connections — semantic similarity when the on-device model is installed, else shared tags + [[mentions]]. Dry-run by default (review the suggestions); pass apply:true to draw them (ADDITIVE — never deletes; the human can remove any arrow). Use after brain_insights flags many orphans, to turn a flat list into a real knowledge graph. To DISMISS a brain_reconcile false-positive contradiction, pass pairs:[{fromId,toId}] (the ids are in the reconcile output) with relationship:"not_contradiction" — a persisted dismissal that stops that pair ever resurfacing as a candidate.',
+  description: 'Repairs orphaned decision/milestone cards first (scope:"orphans", the default) by proposing genuinely related unlinked pairs — semantic similarity at a conservative 0.55 threshold when the on-device model is installed, else shared tags + [[mentions]]. The dry run includes a before→projected orphan receipt; apply:true draws only additive, removable arrows and reports the measured after count. It NEVER archives or rewrites cards. Use scope:"all" for deliberate whole-graph densification. To DISMISS a brain_reconcile false-positive contradiction, pass pairs:[{fromId,toId}] with relationship:"not_contradiction".',
   inputSchema: {
     canvas: z.string().optional().describe('Canvas filename/path. Defaults to the project brain ("brain").'),
     apply: z.boolean().optional().describe('false (default) = suggest only; true = draw the connections.'),
     max: z.number().optional().describe('Max connections to propose/draw (default 24).'),
-    threshold: z.number().optional().describe('Min semantic similarity 0–1 to link (default 0.45). Higher = fewer, tighter links.'),
+    threshold: z.number().optional().describe('Min semantic similarity 0–1. Default 0.55 for orphan repair; 0.45 for scope:"all". Higher = fewer, tighter links.'),
+    scope: z.enum(['orphans', 'all']).optional().describe('"orphans" (default) repairs isolated decision/milestone cards; "all" proposes across every live card.'),
     pairs: z.array(z.object({ fromId: z.string(), toId: z.string() })).optional().describe('Explicit card-id pairs to connect (bypasses auto-proposal). Use to dismiss a reconcile false-positive: pass the two card ids with relationship:"not_contradiction".'),
     relationship: z.string().optional().describe('Relationship for explicit `pairs` (e.g. "not_contradiction" to permanently dismiss a contradiction candidate, or "relates_to", "depends_on", "supports").'),
   },
-}, async ({ canvas, apply, max, threshold, pairs, relationship }) => toContent(await opBrainConnect({ vault: mcpPresence.vault, canvas, apply, max, threshold, pairs, relationship, log })));
+}, async ({ canvas, apply, max, threshold, scope, pairs, relationship }) => toContent(await opBrainConnect({ vault: mcpPresence.vault, canvas, apply, max, threshold, scope, pairs, relationship, log })));
 
 server.registerTool('brain_reconcile', {
   title: 'Reconcile the brain — contradictions between cards + unrecorded migrations',
@@ -378,6 +387,24 @@ server.registerTool('brain_sync', {
 }, async ({ project, intent, files, phase, include_context }) => {
   const totalStartedAt = Date.now();
   const report = mcpPresence.sync({ project, intent, files, phase });
+  // Zero-manual harness convergence: brain_sync is the one project-aware
+  // gateway every MCP host can call. Register MCP-only projects here (Claude's
+  // lifecycle hook is no longer the sole registry writer), then reconcile only
+  // KLYPIX-managed instructions/config entries before task work begins.
+  let harness = null;
+  let registration = null;
+  if (phase === 'start' && report.structured?.brain) {
+    registration = registerProjectBrain({
+      brainPath: report.structured.brain,
+      brainDir: RUNTIME_BRAIN_DIR,
+    });
+    harness = await reconcileRegisteredProjects({
+      brainDir: RUNTIME_BRAIN_DIR,
+      version: PKG_VERSION,
+      brainPaths: [report.structured.brain],
+      rules: { auditProject, compactAgentsBrief, linkProject },
+    });
+  }
   // Class-C ship observation, host-neutral: brain_sync is the ONE surface every
   // MCP host calls at task start, so an MCP-only project (no Claude/Codex hook)
   // still notices a release nobody narrated. Queued here, drained at the next
@@ -429,13 +456,20 @@ server.registerTool('brain_sync', {
       context: taskContext?.context?.durationMs || 0,
       total: totalMs,
     },
+    ...(registration ? { registration } : {}),
+    ...(harness ? { harness } : {}),
   };
+  const harnessText = harness?.failed
+    ? `KLYPIX harness self-heal needs attention: ${harness.failed} project(s) remain partially aligned; brain_doctor has the exact files.`
+    : harness?.updated
+      ? `KLYPIX harness self-healed automatically: ${harness.updated} project(s) refreshed; no manual link command is required.`
+      : '';
   const timingText = `Context Gateway total: ${totalMs}ms`
     + (taskContext?.context ? ` (memory ${taskContext.context.durationMs}ms)` : '') + '.';
   return {
     content: [{
       type: 'text',
-      text: [report.text, shipNotice, contextText, timingText].filter(Boolean).join('\n\n'),
+      text: [report.text, harnessText, shipNotice, contextText, timingText].filter(Boolean).join('\n\n'),
     }],
     structuredContent,
   };
@@ -608,12 +642,8 @@ server.server.oninitialized = () => {
   // older stable supervisor acquire the updater immediately after hot-swapping
   // to a compatible new worker; no extra host reconnect is needed for the
   // scheduler itself. Stamp + lock make the duplicate trigger effectively free.
-  const autoUpdateDir = path.dirname(
-    process.env.KLYPIX_MCP_RUNTIME_MANIFEST
-    || path.join(os.homedir(), '.claude', 'project-brain', '.mcp-runtime.json'),
-  );
   const checkForCoreUpdate = () => spawnAutoUpdateHelper({
-    brainDir: autoUpdateDir,
+    brainDir: RUNTIME_BRAIN_DIR,
     currentVersion: PKG_VERSION,
   });
   autoUpdateStarter = setTimeout(checkForCoreUpdate, 2000);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.51.0",
+  "version": "1.52.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -28,11 +28,16 @@
     "type": "git",
     "url": "https://github.com/dahshanlabs/klypix-mcp"
   },
+  "bugs": {
+    "url": "https://github.com/dahshanlabs/klypix-mcp/issues",
+    "email": "hello@klypix.com"
+  },
   "bin": {
     "klypix-mcp": "bin/klypix-mcp.mjs",
     "klypix-conformance": "bin/klypix-conformance.mjs",
     "klypix-link": "bin/klypix-link.mjs",
     "klypix-doctor": "bin/klypix-doctor.mjs",
+    "klypix-runtime": "bin/klypix-runtime.mjs",
     "klypix-a2a": "bin/klypix-a2a.mjs",
     "klypix-read": "bin/klypix-read.mjs",
     "klypix-write": "bin/klypix-write.mjs",
@@ -49,6 +54,8 @@
     "./mcp-presence": "./src/mcp-presence.mjs",
     "./presence-relay": "./src/presence-relay.mjs",
     "./supervisor": "./src/mcp-supervisor.mjs",
+    "./runtime-inspector": "./src/runtime-inspector.mjs",
+    "./runtime": "./src/runtime-inspector.mjs",
     "./auto-update": "./src/mcp-auto-update.mjs"
   },
   "files": [
@@ -66,9 +73,10 @@
     "node": ">=18"
   },
   "scripts": {
-    "test": "node test/mcp-auto-update.mjs && node test/mcp-supervisor.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/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/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/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/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/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"
+    "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
+    "runtime": "node bin/klypix-runtime.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.4",

package/src/agent-presence.mjs

@@ -225,6 +225,12 @@ export function upsertSession({
       ? String(intent || '').replace(/\s+/g, ' ').trim().slice(0, 160)
       : (previous.intent || '');
     const intentChanged = intent !== 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.
+    const activityEvent = /^(?:McpToolUse|McpTaskStart|McpTaskCheckpoint|UserPromptSubmit|PreToolUse|PostToolUse)$/i.test(String(event || ''))
+      ? String(event)
+      : null;
     const next = {
       ...previous,
       id: String(id),
@@ -240,6 +246,9 @@ export function upsertSession({
         : (previous.intentAt ? { intentAt: previous.intentAt, intentSource: previous.intentSource || null } : {})),
       files: mergedFiles,
       event: event ?? previous.event ?? null,
+      ...(activityEvent
+        ? { activityAt: now, activityKind: activityEvent }
+        : (previous.activityAt ? { activityAt: previous.activityAt, activityKind: previous.activityKind || null } : {})),
       ...(Object.keys(channelSeen).length
         ? { channels: Object.keys(channelSeen), channelSeen }
         : {}),