klypix-mcp 1.51.1 → 1.53.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 18 tools, and not the retrieval engine.
+It verifies 12 required coordination behaviours — not the 19 tools, and not the retrieval engine.
 
 ---
 
@@ -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 |
@@ -373,7 +383,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 
 ---
 
-## The 18 verbs
+## The 19 verbs
 
 | Tool | What it does |
 |---|---|
@@ -388,6 +398,7 @@ 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; Graphify artifacts are supported but never installed or run |
 | `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 |
@@ -396,7 +407,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `add_to_canvas` | Append cards/connections (positions preserved) |
 | `list_canvases` | List every `.klypix` in the vault |
 
-Exactly 18, machine-verifiable with `npx klypix-mcp doctor`.
+Exactly 19, machine-verifiable with `npx klypix-mcp doctor`.
 
 > **`canvas_view`:** no MCP Apps host has been observed rendering the UI resource yet — there is no
 > screenshot and no host-level test. Hosts without the extension get clean text, which is the path
@@ -488,6 +499,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 +512,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),
@@ -581,7 +599,7 @@ Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or wi
 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
+The repository carries 49 test files, 45 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
 quality, decay, challenge, lenses, the format guard, the git tools (including a real `git merge`
 through the merge driver), uninstall, and conformance. Run them with `npm test` from a clone — they

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|project-graph)\.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', 'project-graph.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,6 +30,7 @@ import {
   opBrainInsights, opBrainConnect, opBrainReconcile, opBrainGarden, opCreateCanvas, opAddToCanvas, opBrainNote, opBrainMessage, opBrainAsk, opBrainChallenge, opCanvasView, opBrainLens,
   opBrainTaskContext,
 } from '../src/klypix-core.mjs';
+import { projectGraphContextMarkdown, queryProjectGraph } 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 {
@@ -201,6 +202,7 @@ const toContent = (r) => {
     ? { type: 'image', data: b.data, mimeType: b.mime }
     : { type: 'text', text: b.text });
   const result = r.isError ? { content, isError: true } : { content };
+  if (r.structured && typeof r.structured === 'object') result.structuredContent = r.structured;
   return mcpPresence.decorateToolResult(result);
 };
 
@@ -242,6 +244,67 @@ server.registerTool('brain_ask', {
   },
 }, async ({ question, canvas, as_of, k }) => toContent(await opBrainAsk({ vault: mcpPresence.vault, canvas, question, as_of, k, log })));
 
+server.registerTool('project_map_context', {
+  title: 'Project Map context - current code structure plus brain decisions',
+  description: 'Read-only combined context for a coding question. It queries a provider-neutral, bounded view of the generated project graph (Graphify graphify-out/graph.json is supported first) and places that CURRENT CODE evidence beside fast, correction-aware KLYPIX brain cards (decisions and rationale). KLYPIX never installs or runs Graphify and never copies graph nodes into brain.klypix. Missing graph artifacts degrade cleanly to brain-only context. Source-file anchors are accepted only when they stay inside the declared project root. Set deep_history:true only when superseded history is genuinely needed; the default never loads the local embedding model.',
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+  inputSchema: {
+    question: z.string().min(1).describe('Question or code concept to ground in both current structure and project memory.'),
+    project: z.string().optional().describe('Absolute project root. Defaults to this MCP connection\'s configured project/vault.'),
+    graph_path: z.string().optional().describe('Optional project-relative graph JSON path. Defaults to graphify-out/graph.json and may not escape the project root.'),
+    depth: z.number().optional().describe('Relationship hops around the best code matches (0-3, default 1).'),
+    max_nodes: z.number().optional().describe('Maximum code nodes returned (default 60, capped 200).'),
+    k: z.number().optional().describe('Maximum brain cards returned (default 8; fast mode caps 8, deep history caps 20).'),
+    deep_history: z.boolean().optional().describe('false (default) uses the sub-second lexical-fast correction-aware path; true opts into whole-brain semantic/history retrieval, which may cold-load the local model.'),
+  },
+}, async ({ question, project, graph_path, depth, max_nodes, k, deep_history }) => {
+  let graphResult;
+  let graphMarkdown;
+  try {
+    graphResult = queryProjectGraph({
+      project: project || mcpPresence.vault,
+      graphPath: graph_path,
+      query: question,
+      depth,
+      maxNodes: max_nodes,
+    });
+    graphMarkdown = projectGraphContextMarkdown(graphResult);
+  } catch (error) {
+    graphResult = { schemaVersion: 1, status: 'invalid', error: error?.message || String(error) };
+    graphMarkdown = `# Project Map\n\nThe generated graph could not be read safely: ${graphResult.error}`;
+  }
+  const graphFiles = Array.isArray(graphResult?.nodes)
+    ? [...new Set(graphResult.nodes.map(node => node.sourceFile).filter(Boolean))].slice(0, 20)
+    : [];
+  const brainResult = deep_history
+    ? await opBrainAsk({
+      vault: mcpPresence.vault,
+      question,
+      k: Math.max(1, Math.min(20, Number(k) || 8)),
+      log,
+    })
+    : await opBrainTaskContext({
+      vault: mcpPresence.vault,
+      intent: question,
+      files: graphFiles,
+      k: Math.max(1, Math.min(8, Number(k) || 8)),
+      budgetChars: 4_500,
+    });
+  const brainMarkdown = brainResult.blocks
+    .filter(block => block.kind === 'text')
+    .map(block => block.text)
+    .join('\n\n');
+  return toContent({
+    blocks: [{ kind: 'text', text: `${graphMarkdown}\n\n---\n\n# Project Brain - ${deep_history ? 'decisions and history' : 'current decisions and corrections'}\n\n${brainMarkdown}` }],
+    isError: brainResult.isError,
+    structured: { projectGraph: graphResult, brainContext: brainResult.context || null, deepHistory: deep_history === true },
+  });
+});
+
 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").',
@@ -278,16 +341,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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.51.1",
+  "version": "1.53.0",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -37,6 +37,7 @@
     "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",
@@ -53,6 +54,9 @@
     "./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",
+    "./project-graph": "./src/project-graph.mjs",
     "./auto-update": "./src/mcp-auto-update.mjs"
   },
   "files": [
@@ -70,18 +74,20 @@
     "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:project-graph": "node test/project-graph.mjs",
+    "test": "node test/project-graph.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/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",
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "fractional-indexing": "^3.2.0",
     "jszip": "^3.10.1",
     "zod": "^4.3.6"
   },
-  "optionalDependencies": {
+  "devDependencies": {
     "@huggingface/transformers": "^4.2.0"
   }
 }

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 }
         : {}),

package/src/brain-doctor.mjs

@@ -263,6 +263,13 @@ function inspectPeers(brainDir, brainPath, now, selfId = null) {
       hostPid: s.hostPid || null,
       // Sync-rich vs sync-silent: has this session declared any task scope?
       synced: Boolean(String(s.intent || '').trim() || (Array.isArray(s.files) && s.files.length)),
+      // Transport liveness is not task activity. Only real prompt/tool work
+      // stamps activityAt; heartbeats deliberately preserve rather than refresh it.
+      activityAt: Number(s.activityAt || 0) || null,
+      activityKind: s.activityKind || null,
+      activeUnscoped: !Boolean(String(s.intent || '').trim() || (Array.isArray(s.files) && s.files.length))
+        && Number(s.activityAt || 0) > 0
+        && now - Number(s.activityAt) < SESSION_FRESH_MS,
       lastSeenMin: Math.round((now - liveness.lastSeen) / 60000),
     }));
   // Twin rows = channel merge NOT occurring: >1 live row sharing one hostPid is
@@ -278,7 +285,13 @@ function inspectPeers(brainDir, brainPath, now, selfId = null) {
       now,
     })
     : { sent: 0, receipts: [] };
-  return { file, live, count: live.length, rawRecent, syncedCount: live.filter(p => p.synced).length, twinGroups, receipts };
+  const syncedCount = live.filter(p => p.synced).length;
+  const activeUnscopedCount = live.filter(p => p.activeUnscoped).length;
+  return {
+    file, live, count: live.length, rawRecent, syncedCount, activeUnscopedCount,
+    idleUnscopedCount: Math.max(0, live.length - syncedCount - activeUnscopedCount),
+    twinGroups, receipts,
+  };
 }
 
 // ── DECAY-GUARD layer (fast-decay status protection, 2026-07-28) ─────────────
@@ -408,9 +421,9 @@ export function inspect(opts = {}) {
   // coordination. That is a readiness gap, not file/runtime drift: say PARTIAL
   // instead of the misleading all-clear that prompted the field audit.
   const readinessWarnings = [];
-  const silentSessions = Math.max(0, peers.count - peers.syncedCount);
-  if (peers.count > 1 && silentSessions > 0) {
-    readinessWarnings.push(`${silentSessions} of ${peers.count} active sessions have not declared task scope`);
+  const activeSilentSessions = peers.activeUnscopedCount || 0;
+  if (peers.count > 1 && activeSilentSessions > 0) {
+    readinessWarnings.push(`${activeSilentSessions} active session${activeSilentSessions === 1 ? '' : 's'} used KLYPIX without declared task scope (${peers.count} live connections total)`);
   }
   if (Number(autoUpdate.harness?.failed || 0) > 0) {
     readinessWarnings.push(`${autoUpdate.harness.failed} automatic harness repair(s) remain partial`);
@@ -570,10 +583,17 @@ export function render(r, opts = {}) {
   if (!r.sessions.count) L.push(`${ok} ${c.bold}SESSIONS${c.rst}  0 active sessions ${c.dim}(saved/recent chats are history, not active)${c.rst}`);
   else {
     const hiddenIdle = Math.max(0, (r.sessions.rawRecent || r.sessions.count) - r.sessions.count);
-    L.push(`${r.sessions.count > 1 ? warn : ok} ${c.bold}SESSIONS${c.rst}  ${r.sessions.count} active session${r.sessions.count === 1 ? '' : 's'} · ${r.sessions.syncedCount ?? r.sessions.count} with declared task scope ${c.dim}(all hosts; channel-aware liveness${hiddenIdle ? `; +${hiddenIdle} row(s) with only a dead mcp channel excluded` : ''})${c.rst}`);
+    const activeSilent = r.sessions.activeUnscopedCount || 0;
+    const idleConnections = r.sessions.idleUnscopedCount || 0;
+    L.push(`${activeSilent ? warn : ok} ${c.bold}SESSIONS${c.rst}  ${r.sessions.count} live connection${r.sessions.count === 1 ? '' : 's'} · ${r.sessions.syncedCount ?? r.sessions.count} with declared task scope${activeSilent ? ` · ${activeSilent} active without scope` : ''}${idleConnections ? ` · ${idleConnections} idle/unscoped (not graded)` : ''} ${c.dim}(all hosts; channel-aware liveness${hiddenIdle ? `; +${hiddenIdle} row(s) with only a dead mcp channel excluded` : ''})${c.rst}`);
     for (const p of r.sessions.live) {
       const intentAge = p.intentAgeMin !== null && p.intentAgeMin - p.lastSeenMin > 3 ? ` (set ${p.intentAgeMin}m ago)` : '';
-      L.push(`        · ${p.client}:${p.id}${p.branch ? ' @' + p.branch : ''}${p.channels.length ? ` [${p.channels.join('+')}]` : ''}${p.intent ? ` “${p.intent.slice(0, 50)}”${intentAge}` : ''}${p.synced ? '' : ` ${c.yel}· sync-silent (no brain_sync intent/scope)${c.rst}`} ${c.dim}(${p.lastSeenMin}m ago)${c.rst}`);
+      const scopeState = p.synced
+        ? ''
+        : (p.activeUnscoped
+          ? ` ${c.yel}· active sync-silent (used KLYPIX without brain_sync scope)${c.rst}`
+          : ` ${c.dim}· idle connection (no task activity to grade)${c.rst}`);
+      L.push(`        · ${p.client}:${p.id}${p.branch ? ' @' + p.branch : ''}${p.channels.length ? ` [${p.channels.join('+')}]` : ''}${p.intent ? ` “${p.intent.slice(0, 50)}”${intentAge}` : ''}${scopeState} ${c.dim}(${p.lastSeenMin}m ago)${c.rst}`);
     }
     for (const g of (r.sessions.twinGroups || [])) {
       L.push(`        ${c.yel}⚠ twin rows — channel merge NOT occurring: host pid ${g.hostPid} appears as ${g.ids.join(' + ')} (one logical session counted ${g.ids.length}×)${c.rst}`);