klypix-mcp 1.51.1 → 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),

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

@@ -278,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',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.51.1",
+  "version": "1.52.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,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": [
@@ -70,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 }
         : {}),

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}`);

package/src/brain-semantic.mjs

@@ -2,8 +2,8 @@
 //
 // WHY a separate module: the hook's per-prompt recall is LEXICAL (keyword) — fast
 // and bulletproof. Semantic (embedding) recall would understand paraphrase, but the
-// hook is a ONE-SHOT process (no daemon allowed), so loading the 23MB MiniLM model
-// costs ~550ms EVERY prompt — unacceptable on the common path. The measured-and-
+// hook is a ONE-SHOT process (no daemon allowed), so loading an embedding model
+// on EVERY prompt is unacceptable on the common path. The measured-and-
 // verified design is therefore: run semantic ONLY when lexical found nothing (the
 // paraphrase / keyword-miss case, where you'd otherwise get zero recall), pay the
 // cost just there, timeout-bounded, and read-only.
@@ -22,6 +22,13 @@ import crypto from 'crypto';
 const PB_DIR = path.join(os.homedir(), '.claude', 'project-brain');
 const EMB_DIR = path.join(PB_DIR, 'embeddings');
 const sha1 = (s) => crypto.createHash('sha1').update(s).digest('hex');
+// Keep these values byte-identical to semantic-memory.mjs. The one-shot hook is
+// intentionally standalone, so it does not import the long-lived runtime merely
+// to read configuration.
+export const HOOK_EMBEDDING_MODEL_ID = 'Xenova/bge-small-en-v1.5';
+export const HOOK_EMBEDDING_QUERY_PREFIX = 'Represent this sentence for searching relevant passages: ';
+export const HOOK_EMBEDDING_POOLING = 'cls';
+export const HOOK_EMBEDDING_CACHE_KEY = `${HOOK_EMBEDDING_MODEL_ID}|q8|${HOOK_EMBEDDING_POOLING}|query-instruction-v1`;
 
 // Memoized within THIS process only (a one-shot hook run) — across prompts it
 // reloads cold, which is exactly why we only pay it on a lexical miss.
@@ -41,36 +48,48 @@ function getEmbedder() {
             if (!t) throw last;
         }
         t.env.cacheDir = path.join(PB_DIR, 'hf-cache');
-        return await t.pipeline('feature-extraction', 'Xenova/all-MiniLM-L6-v2', { dtype: 'q8' });
+        return await t.pipeline('feature-extraction', HOOK_EMBEDDING_MODEL_ID, { dtype: 'q8' });
     })().catch(() => null);   // not installed / load fail → null → lexical fallback
     return _embedder;
 }
 
-async function embedTexts(pipe, texts) {
-    const out = await pipe(texts, { pooling: 'mean', normalize: true });
-    const [n, d] = out.dims;
-    const vecs = [];
-    for (let i = 0; i < n; i++) vecs.push(Array.from(out.data.slice(i * d, (i + 1) * d)));
-    return vecs;
+async function embedQueries(pipe, texts) {
+    let out = null;
+    try {
+        const instructed = texts.map(text => `${HOOK_EMBEDDING_QUERY_PREFIX}${text}`);
+        out = await pipe(instructed, { pooling: HOOK_EMBEDDING_POOLING, normalize: true });
+        const [n, d] = out.dims;
+        const vecs = [];
+        for (let i = 0; i < n; i++) vecs.push(Array.from(out.data.slice(i * d, (i + 1) * d)));
+        return vecs;
+    } finally {
+        try { out?.dispose?.(); } catch { /* one-shot process exit remains the fallback */ }
+    }
 }
 // Vectors are unit-normalized, so dot == cosine.
 export const dot = (a, b) => { let s = 0; const n = Math.min(a.length, b.length); for (let i = 0; i < n; i++) s += a[i] * b[i]; return s; };
 
 // READ-ONLY card-vector cache — NEVER embeds or writes (embedding all cards in the
 // per-prompt process is the multi-second stall we forbid). Reuses the SAME warm
-// cache the MCP host fills, keyed sha1(path, slashes-only). The MCP keys WITHOUT
-// lowercasing the drive letter, so a brain can have an `e:`-keyed and an `E:`-keyed
-// cache file — try the drive-case variants so we hit whichever exists.
+// cache the MCP host fills. Current workers canonicalize absolute Windows paths
+// to a lowercase drive letter; legacy caches used raw drive casing, so probe both
+// identities while accepting only the exact current modelKey.
 function readCachedVecs(brainPath, cards) {
     const slashed = String(brainPath).replace(/\\/g, '/');
+    const resolved = path.resolve(String(brainPath)).replace(/\\/g, '/');
     const variants = [...new Set([
+        resolved.replace(/^([a-zA-Z]):/, (_m, d) => d.toLowerCase() + ':'),
+        resolved,
         slashed,
         slashed.replace(/^([a-zA-Z]):/, (_m, d) => d.toLowerCase() + ':'),
         slashed.replace(/^([a-zA-Z]):/, (_m, d) => d.toUpperCase() + ':'),
     ])];
     let cache = null;
     for (const v of variants) {
-        try { const c = JSON.parse(fs.readFileSync(path.join(EMB_DIR, sha1(v) + '.json'), 'utf8')); if (c && c.cards) { cache = c; break; } } catch { /* try next variant */ }
+        try {
+            const c = JSON.parse(fs.readFileSync(path.join(EMB_DIR, sha1(v) + '.json'), 'utf8'));
+            if (c?.modelKey === HOOK_EMBEDDING_CACHE_KEY && c.cards) { cache = c; break; }
+        } catch { /* try next variant */ }
     }
     const map = new Map();
     if (cache && cache.cards) for (const c of cards) { const e = cache.cards[c.id]; if (e && e.v) map.set(c.id, e.v); }
@@ -98,7 +117,7 @@ export async function semanticVecs(brainPath, struct, query, { timeoutMs = 1200
         if (!vecsMap.size) return null;
         const pipe = await Promise.race([getEmbedder(), new Promise(r => setTimeout(() => r(null), timeoutMs))]);
         if (!pipe) return null;
-        const [qv] = await embedTexts(pipe, [q]);
+        const [qv] = await embedQueries(pipe, [q]);
         if (!qv) return null;
         return { qv, vecsMap, dot };
     } catch { return null; }

package/src/global-brain-hook.mjs

@@ -390,6 +390,10 @@ function touchSession(sid, patch = {}) {
             const wantsIntent = patch.intent !== undefined && !declaredFresh;
             const nextIntent = wantsIntent ? patch.intent : (prev.intent ?? '');
             const intentChanged = wantsIntent && nextIntent !== (prev.intent ?? '');
+            const recordsActivity = patch.intent !== undefined
+                || patch.addFiles !== undefined
+                || patch.files !== undefined
+                || patch.ships !== undefined;
             list.push({
                 ...prev,   // unknown/foreign keys (an MCP writer's, a future field) survive this touch
                 id: sid, pid: process.pid, project: path.basename(CWD),
@@ -421,6 +425,9 @@ function touchSession(sid, patch = {}) {
                 // list silently dropped unknown patch keys, which made the
                 // dedup dead code (review-caught).
                 statusDigestHash: patch.statusDigestHash !== undefined ? patch.statusDigestHash : (prev.statusDigestHash ?? null),
+                ...(recordsActivity
+                    ? { activityAt: now, activityKind: patch.intent !== undefined ? 'UserPromptSubmit' : 'ObservedWork' }
+                    : (prev.activityAt ? { activityAt: prev.activityAt, activityKind: prev.activityKind || null } : {})),
                 channels: Object.keys(channelSeen), channelSeen,
                 startedAt: prev.startedAt || now, lastSeen: now,
             });