klypix-mcp 1.96.0 → 1.98.0

package/README.md

@@ -235,13 +235,23 @@ not a filing convention.
   session's brief. That is brief priority, not a retrieval-ranking boost.
 - **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` 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.
+- **Retrieval is local.** With the on-device model ("search by meaning"), `brain_ask` and
+  `search_all_brains` use BGE semantic ranking with lexical help for exact identifiers, paths, and
+  versions — still entirely on your machine. Without it, retrieval is keyword-only. 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.
+- **Search by meaning is installed for you (1.97).** `npx klypix-mcp install` run by a person in a
+  terminal installs it: about 150 MB to download once, about 110 MB on disk after the files Node
+  never loads are removed. Skip it with `--no-semantic` (or `KLYPIX_SEMANTIC=0`). Installs with no
+  terminal — CI, scripts, an AI agent running the install — get it only with `--semantic`. The
+  Claude plugin never downloads it. Measured on the frozen 102-question set: the right card in the
+  top 5 for 54 questions with it, 19 without.
+- **Preparing a brain never makes a question wait.** Each card is turned into a meaning vector once
+  (about 45 ms a card on a laptop CPU, one card at a time, ~305 MB peak), newest cards first, by a
+  low-priority background job that saves as it goes. A question on a brain that is not ready yet
+  answers right away from what is ready plus keywords, and says how far along the preparation is
+  ("Getting this brain ready for search by meaning: 900 of 3,670 cards so far, about 5 min left").
+  After that, only new or edited cards are prepared.
 
 ### Bounded semantic-memory runtime
 
@@ -518,12 +528,22 @@ Future hosts get baseline support merely by connecting the MCP server. A deeper
 
 ## Overlap warnings
 
-When two sessions declare overlapping expected files, `brain_sync` surfaces it: the peer, its
-declared task, and the exact paths in common. A one-time alert is queued to whichever session got
-there first, so a late arrival is not the only one who knows.
+`brain_sync` reports three kinds of overlap with other live sessions on the same brain:
 
-This warns. It does not prevent. Nothing blocks an edit, matching is exact-path, and both sides
-have to have declared their files for the overlap to be visible at all.
+- **Same file.** Both sessions declared, or were observed editing, the same path. You see the peer,
+  its task and the paths in common, and a one-time alert is queued to whichever session got there
+  first, so a late arrival is not the only one who knows.
+- **Would conflict at merge.** The two sessions are on different branches, and a test merge of the
+  two branch tips (`git merge-tree`, git 2.38 or newer) conflicts in named files, even though no
+  declared file overlaps. This sees committed work only: an uncommitted edit is invisible to git.
+  It also gets a one-time alert. Files the brain tooling regenerates on every branch (AGENTS.md,
+  rule files, `.mcp.json`, `brain.klypix`) are not counted.
+- **Same folder (advisory).** Both sessions work in one folder with no file in common yet. No alert
+  is sent. A folder that at least three sessions, and more than half of them, touch is treated as
+  noise and not reported.
+
+This warns. It does not prevent. Nothing blocks an edit. A session that never declared its files
+and was never observed editing is invisible to the file and folder checks.
 
 ## Handoffs and messages
 
@@ -747,6 +767,15 @@ lost 0 of 46. If the control ever loses nothing, the run reports **inconclusive*
 
 Latest results, with hardware and date: [BENCHMARKS.md](BENCHMARKS.md).
 
+**Does it change what agents do?** That needs real agents, so it lives in the repository rather than
+the package: [`bench/coordination/`](bench/coordination/README.md) runs Claude Code or Codex on four
+small repos where another session knows something the agent needs (a decision changed today, work
+overlapping on another branch, a note from a session that has ended, a root cause another vendor's
+session found). Each run is graded by a test written after the agent finishes, against no shared
+channel, a human copy-paste, `AGENTS.md` kept tidy or appended, and KLYPIX over MCP only. Every number
+is printed with its sample size and interval; tools it has not measured are listed as not measured.
+`--dry-run` costs nothing and proves the graders.
+
 ## Git and concurrency
 
 One file in your repo, committed with your code — versioned, branchable, portable. So two
@@ -1095,9 +1124,10 @@ Read this section before you build on any of it.
   loop prevention, stable message IDs and per-recipient-machine acknowledgement primitives), but no
   transport: carrying frames between machines is the desktop app's job. With `klypix-mcp` alone,
   coordination is machine-local.
-- **Overlap matching is exact-path, and both sides must declare.** A session that never declares
-  its expected files is invisible to overlap detection, and `src/auth/token.ts` does not match a
-  rename or a parent directory.
+- **File overlap is exact-path.** A session needs declared files or observed edits to be checked;
+  `src/auth/token.ts` does not match a rename. Folder overlap is advisory. The merge test sees
+  committed work only, needs git 2.38 or newer, and runs only for sessions on different local
+  branches of the same repository.
 - **Overlap warnings are advisory.** Nothing is blocked. One severity string in the payload reads
   `blocking`; the mechanism is not.
 - **Codex has no automatic capture**, with or without `--codex-hooks`. The Codex hook never writes

package/bin/klypix-install.mjs

@@ -12,6 +12,10 @@
 //   npx klypix-mcp install --codex-hooks  # optional prompt/file awareness; Codex asks for trust
 //   npx klypix-mcp install --allow-untagged  # acknowledge deploying an UNTAGGED source checkout
 //                                            # (dev deploy; also KLYPIX_MCP_ALLOW_UNTAGGED=1)
+//   npx klypix-mcp install --semantic     # also install search by meaning (~150 MB download, once)
+//   npx klypix-mcp install --no-semantic  # never (also KLYPIX_SEMANTIC=0)
+//   A person running install in a terminal gets search by meaning by default;
+//   scripted, CI and agent-run installs (no terminal) only with --semantic.
 //
 // Never-throws-silently: it's an explicit CLI, so it reports what it did and exits
 // non-zero on a real failure. Never wires a broken settings.json (refuse + restore).
@@ -35,6 +39,7 @@ import { brainInstallDecision, deploySourceDecision } from '../src/install-versi
 import { acquireInstallLockSync, releaseInstallLockSync } from '../src/install-lock.mjs';
 import { collectRepoState } from '../src/repo-state.mjs';
 import { runSetup, renderBrief } from '../src/setup.mjs';
+import { SEMANTIC_RUNTIME_MANIFEST, dirBytes, pruneSemanticRuntime, semanticInstallDecision } from '../src/semantic-install.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -60,6 +65,10 @@ const SETUP_JSON = process.argv.includes('--json');
 // this is source authority (knowingly deploy an untagged working tree).
 const ALLOW_UNTAGGED = process.argv.includes('--allow-untagged')
     || process.env.KLYPIX_MCP_ALLOW_UNTAGGED === '1';
+// Search by meaning (1.97.0). Measured 2026-10-11 on the real 102-question
+// set: the right card in the top 5 for 54 questions with it, 19 without.
+const SEMANTIC_FLAG = process.argv.includes('--semantic');
+const NO_SEMANTIC = process.argv.includes('--no-semantic') || process.env.KLYPIX_SEMANTIC === '0';
 
 const HOME = os.homedir();
 const CLAUDE_DIR = path.join(HOME, '.claude');
@@ -143,6 +152,52 @@ function wireCodex() {
     };
 }
 
+// ── Search by meaning: the optional on-device runtime (src/semantic-install.mjs) ──
+function installSemanticRuntimeIfWanted() {
+    const semanticDir = path.join(BRAIN_DIR, 'semantic');
+    const transformers = path.join(semanticDir, 'node_modules', '@huggingface', 'transformers');
+    const decision = semanticInstallDecision({
+        optOut: NO_SEMANTIC,
+        flag: SEMANTIC_FLAG,
+        runtimeOnly: RUNTIME_ONLY,
+        plugin: String(process.env.KLYPIX_PLUGIN ?? '').trim() === '1',
+        present: exists(transformers),
+        ci: Boolean(process.env.CI),
+        tty: Boolean(process.stdout.isTTY),
+    });
+    if (decision !== 'install') return { decision };
+    console.log('• Installing search by meaning (about 150 MB to download, once; skip with --no-semantic)…');
+    const started = Date.now();
+    try {
+        fs.mkdirSync(semanticDir, { recursive: true });
+        fs.writeFileSync(path.join(semanticDir, 'package.json'), `${JSON.stringify(SEMANTIC_RUNTIME_MANIFEST, null, 2)}\n`);
+        const npmArgs = ['install', '--prefix', semanticDir, '--omit=dev', '--no-audit', '--no-fund', '--loglevel=error'];
+        if (process.platform === 'win32') execFileSync('cmd.exe', ['/d', '/s', '/c', 'npm.cmd', ...npmArgs], { stdio: ['ignore', 'ignore', 'pipe'], timeout: 600_000, windowsHide: true });
+        else execFileSync('npm', npmArgs, { stdio: ['ignore', 'ignore', 'pipe'], timeout: 600_000 });
+        if (!exists(transformers)) throw new Error('npm finished but the runtime is missing');
+        let freed = 0;
+        try { freed = pruneSemanticRuntime(semanticDir); } catch { /* pruning is an optimisation */ }
+        return { decision, ok: true, seconds: Math.round((Date.now() - started) / 1000), sizeMb: Math.round(dirBytes(path.join(semanticDir, 'node_modules')) / 1048576), freedMb: Math.round(freed / 1048576) };
+    } catch (error) {
+        const why = String(error?.stderr || error?.message || error).split('\n').map(s => s.trim()).filter(Boolean).slice(-1)[0] || 'npm failed';
+        return { decision, ok: false, error: why.slice(0, 200) };
+    }
+}
+
+function reportSemantic(step) {
+    const turnOn = 'npx klypix-mcp install --semantic';
+    if (!step) return;
+    if (step.decision === 'install' && step.ok) {
+        console.log(`✓ search by meaning installed in ${step.seconds}s (${step.sizeMb} MB on disk). Your project brains are being prepared in the background, newest cards first: questions work right away and get better as it finishes.`);
+    } else if (step.decision === 'install') {
+        console.error(`⚠ search by meaning could not be installed (${step.error}). Keyword search still works. Try again with: ${turnOn}`);
+    } else if (step.decision === 'present') {
+        console.log('✓ search by meaning: on');
+    } else if (step.decision === 'skip-noninteractive' || step.decision === 'skip-ci') {
+        console.log(`• search by meaning is off. Turn it on with: ${turnOn}  (about 150 MB, once; agents then find the right card about 3x as often)`);
+    }
+}
+
 function reportCodex(result) {
     if (result.ok) {
         const mcp = result.mcp.action === 'skipped-no-project-brain'
@@ -594,6 +649,9 @@ try {
     const notWired = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse', 'PreToolUse'].filter(e => !wiredFor(e));
 
     releaseInstallLockSync(installLock);
+    // Search by meaning: installed AFTER the brain itself is committed, so a
+    // slow or failed download never touches a working keyword-only install.
+    const semanticStep = installSemanticRuntimeIfWanted();
     // 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
@@ -617,6 +675,7 @@ try {
     }
     if (!RUNTIME_ONLY) reportCodex(codex);
     console.log(`✓ installed klypix brain v${VERSION} → ${BRAIN_DIR}  (${n} scripts, ${deps} dep packages)`);
+    reportSemantic(semanticStep);
     if (RUNTIME_ONLY) console.log('✓ runtime-only update: host settings and project files were preserved');
     else if (!notWired.length) console.log('✓ wired 5 hooks: SessionStart · UserPromptSubmit (--prompt) · Stop (--capture) · PostToolUse (--live) · PreToolUse (--guard) → settings.json');
     else console.error(`⚠ readiness: ${notWired.length} hook(s) did NOT take (${notWired.join(', ')}) — the brain will read but not capture/sync. Re-run \`npx klypix-mcp install --force\` or check ${SETTINGS}.`);

package/bin/klypix-semantic-warm.mjs

@@ -1,7 +1,11 @@
 #!/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.
+// One detached, best-effort preparation of brains for search by meaning: after
+// an install or a compatible core update (every registered brain), or started
+// by a question on a brain that is not ready yet (--brain <file> --only: that
+// brain alone). It runs at below-normal priority, reports progress to the
+// status file while it works (brainPreparationStatus reads it), refreshes its
+// lock so a long run is never taken for a dead one, and never changes brain
+// content.
 import fs from 'fs';
 import os from 'os';
 import path from 'path';
@@ -9,6 +13,7 @@ import { parseKlypix } from '../src/klypix-format.mjs';
 import { readRegisteredProjectBrains } from '../src/mcp-auto-update.mjs';
 import {
   EMBEDDING_CACHE_KEY,
+  cachedVectorsForBrain,
   disposeSemanticModels,
   getEmbedderForUse,
   vectorsForBrain,
@@ -22,6 +27,7 @@ const brainDir = path.resolve(arg('brain-dir', path.join(os.homedir(), '.claude'
 const lockFile = path.join(brainDir, '.semantic-update-warm.lock');
 const statusFile = path.join(brainDir, '.semantic-update-warm.json');
 const explicitBrain = arg('brain');
+const onlyExplicit = process.argv.includes('--only');
 const startedAt = Date.now();
 let lock = null;
 
@@ -31,6 +37,9 @@ const atomicJson = (file, value) => {
   fs.renameSync(tmp, file);
 };
 
+// A background job: never compete with the person's own work for the CPU.
+try { os.setPriority(os.constants.priority.PRIORITY_BELOW_NORMAL); } catch { /* best-effort */ }
+
 try {
   fs.mkdirSync(brainDir, { recursive: true });
   try {
@@ -45,13 +54,17 @@ try {
   }
   fs.writeFileSync(lock, JSON.stringify({ pid: process.pid, startedAt, modelKey: EMBEDDING_CACHE_KEY }));
 
-  const registered = readRegisteredProjectBrains(brainDir).map(item => item.brainPath);
+  const registered = onlyExplicit && explicitBrain ? [] : 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() });
+    // Nothing to prepare yet, but fetch the model now (~33 MB, once) so the
+    // first question on a new brain does not pay for the download.
+    let model = 'unavailable';
+    try { model = (await getEmbedderForUse(() => {}, 5 * 60_000)) ? 'downloaded' : 'unavailable'; } catch { /* the first question fetches it */ }
+    atomicJson(statusFile, { protocol: 1, result: 'no-registered-brains', model, modelKey: EMBEDDING_CACHE_KEY, completedAt: new Date().toISOString() });
   } else {
     const pipe = await getEmbedderForUse(() => {}, 5 * 60_000);
     if (!pipe) {
@@ -61,7 +74,18 @@ try {
       for (const file of candidates) {
         try {
           const { struct } = await parseKlypix(fs.readFileSync(file));
-          const vectors = await vectorsForBrain(pipe, file, struct.cards);
+          const brainStarted = new Date().toISOString();
+          let lastReport = 0;
+          const report = ({ done, total }, force = false) => {
+            if (!force && Date.now() - lastReport < 3_000) return;
+            lastReport = Date.now();
+            try { atomicJson(statusFile, { protocol: 1, result: 'preparing', modelKey: EMBEDDING_CACHE_KEY, brain: file, done, total, startedAt: brainStarted, updatedAt: new Date().toISOString() }); } catch { /* advisory */ }
+            try { const now = new Date(); fs.utimesSync(lockFile, now, now); } catch { /* advisory */ }
+          };
+          let alreadyReady = 0;
+          try { alreadyReady = cachedVectorsForBrain(file, struct.cards).size; } catch { /* starts from zero */ }
+          report({ done: alreadyReady, total: struct.cards.filter(c => c.type !== 'container' && String(c.text || '').trim()).length }, true);
+          const vectors = await vectorsForBrain(pipe, file, struct.cards, { maxEmbed: Infinity, onProgress: report });
           warmed++;
           cards += vectors.size;
         } catch { failed++; }

package/bin/klypix-worker.mjs

@@ -508,7 +508,7 @@ server.registerTool('search_all_brains', {
 
 server.registerTool('brain_ask', {
   title: 'Ask the project brain a question (whole-brain, correction-aware answer)',
-  description: 'Answer a natural-language question from the WHOLE project brain — "what did we decide about X?", "where did the auth work land?", "why did we drop Y?". Ranks every card lexically, blended with on-device semantic similarity ONLY when the optional local model is installed (a fresh install is lexical; it degrades cleanly). INCLUDES superseded/archived history (flagged, so you can see how a decision changed), and attaches each stale card\'s live CORRECTION so the answer reflects the current truth, not an outdated card. Returns a synthesis-ready context (full cards + provenance + lifecycle) for you to turn into a direct, cited answer — it does not itself write prose. Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup). Optional as_of (YYYY-MM-DD) answers "what was true then". Cards are often worded differently from the question, so end the question with one more line, `Also: <8–14 words a card answering it would likely use: synonyms, feature, file or tool names>`; they widen the search while the question still leads (measured: right card in the top 5 for 60 of 102 test questions instead of 55; 24 instead of 19 when no local model is installed). Defaults to the project brain ("brain").',
+  description: 'Answer a natural-language question from the WHOLE project brain — "what did we decide about X?", "where did the auth work land?", "why did we drop Y?". Ranks every card by meaning with the on-device model (installed by `npx klypix-mcp install` run in a terminal, or with `--semantic`), with keywords for exact names; without the model it is keyword-only, and while a brain is still being prepared the answer says how far along it is. INCLUDES superseded/archived history (flagged, so you can see how a decision changed), and attaches each stale card\'s live CORRECTION so the answer reflects the current truth, not an outdated card. Returns a synthesis-ready context (full cards + provenance + lifecycle) for you to turn into a direct, cited answer — it does not itself write prose. Prefer this over search_canvases when the user asks a QUESTION (not a keyword lookup). Optional as_of (YYYY-MM-DD) answers "what was true then". Cards are often worded differently from the question, so end the question with one more line, `Also: <8–14 words a card answering it would likely use: synonyms, feature, file or tool names>`; they widen the search while the question still leads (measured: right card in the top 5 for 60 of 102 test questions instead of 55; 24 instead of 19 when no local model is installed). Defaults to the project brain ("brain").',
   inputSchema: {
     question: z.string().describe('The natural-language question to answer from the brain.'),
     canvas: z.string().optional().describe('Brain canvas filename/path. Defaults to the project brain ("brain").'),
@@ -1066,7 +1066,7 @@ server.registerTool('brain_reopen', {
 
 server.registerTool('brain_sync', {
   title: 'KLYPIX Context Gateway — synchronize task, peers, conflicts, and relevant memory',
-  description: 'APPROVAL-FREE task gateway over the authorized MCP connection. Call FIRST with a concise intent and expected files, again when scope changes, and with phase:"complete" before the final response. One bounded response returns compact task-relevant brain context, active TASK peers (idle connections hidden), one-time messages, structured exact-file conflicts, and late-arrival overlap alerts. A completion that supplies machine-checkable result manifests is fail-closed: invalid, conflicting, or incomparable evidence returns needs-reconciliation and retains task scope. Works on any MCP host — it needs only the authorized MCP connection, so native lifecycle hooks are optional. LIMITS: conflict matching is EXACT-PATH and both sessions must have declared their files, coordination/result reconciliation is machine-local and OS-user-local (a teammate on another machine is invisible), and file overlap remains ADVISORY.',
+  description: 'APPROVAL-FREE task gateway over the authorized MCP connection. Call FIRST with a concise intent and expected files, again when scope changes, and with phase:"complete" before the final response. One bounded response returns compact task-relevant brain context, active TASK peers (idle connections hidden), one-time messages, structured exact-file conflicts, and late-arrival overlap alerts. A completion that supplies machine-checkable result manifests is fail-closed: invalid, conflicting, or incomparable evidence returns needs-reconciliation and retains task scope. `results` is ONLY for such manifests, never a summary of the work: with nothing machine-checkable to claim, complete without it. Works on any MCP host — it needs only the authorized MCP connection, so native lifecycle hooks are optional. LIMITS: blocking overlap is EXACT-PATH over the declared files of each session plus the edits its host observed; sessions on different branches are also test-merged with git merge-tree (committed work only); a same-folder overlap is an advisory notice; coordination/result reconciliation is machine-local and OS-user-local (a teammate on another machine is invisible), and file overlap remains ADVISORY.',
   annotations: {
     destructiveHint: false,
     idempotentHint: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.96.0",
+  "version": "1.98.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -86,7 +86,7 @@
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
     "pretest": "node test/publish-workflow.mjs",
-    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/brain-ask-words.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.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/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/merge-readings.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/document-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
+    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/brain-ask-words.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.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/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-preparation.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/overlap-tiers.mjs && node test/coordination-bench.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/results-not-manifests.mjs && node test/merge-brains.mjs && node test/merge-readings.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/current-first.mjs && node test/status-shape.mjs && node test/status-hook.mjs && node test/read-canvas-saved-readings.mjs && node test/document-readings.mjs && node test/open-lease.mjs && node test/agent-card-style.mjs && node test/tool-schema-freeze.mjs && node test/app-lease-vectors.mjs && node test/app-tools-stdio.mjs && node test/card-contents-files.mjs && node test/codex-app-table.mjs && node test/plugin-mode.mjs && node test/app-bridge-vectors.mjs && node test/app-bridge-client.mjs && node test/app-tools-static.mjs && node test/app-tools-stdio-live.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs",

package/src/global-brain-hook.mjs

@@ -1462,6 +1462,22 @@ function peerFooter(sid) {
     const lines = ['', `## ⚠️ Other live session(s) in this project — ${peers.length} total, as of ${asOf}${hiddenIdle ? ` (+${hiddenIdle} inactive not shown)` : ''} — coordinate (the brain is shared, NOT live-merged)`];
     const releaseLine = releaseLeaseFooterLine(list, now);
     if (releaseLine) lines.push(releaseLine);
+    // Same branch, said ONCE (1.98.0). Two sessions can only share a branch
+    // name by sharing a checkout (git refuses one branch in two worktrees), so
+    // the risk is concrete: a broad `git add` sweeps the other session's edits
+    // into your commit. Per-peer, this line repeated on every row of a busy
+    // lane and stopped being read.
+    const sameBranchCount = myBranch ? peers.filter(p => p.branch === myBranch).length : 0;
+    if (sameBranchCount) lines.push(`- ⚠️ ${sameBranchCount} of these session(s) share your branch \`${myBranch}\` (one checkout): stage only your own files — never \`git add -u\` / \`-A\` — and coordinate before you commit.`);
+    // Same folder, no shared file yet (twin of mcp-presence findNearbyWork, no
+    // git): with 3+ scoped sessions, a folder most of them touch is noise.
+    const dirOf = (k) => { const at = k.lastIndexOf('/'); return at > 0 ? k.slice(0, at) : ''; };
+    const dirsOfScope = (s) => new Set(scopeOf(s).map(fileKey).map(dirOf).filter(Boolean));
+    const myDirs = dirsOfScope(me);
+    const scopedRows = [me, ...peers].filter(s => s && scopeOf(s).length);
+    const dirCount = new Map();
+    for (const s of scopedRows) for (const d of dirsOfScope(s)) dirCount.set(d, (dirCount.get(d) || 0) + 1);
+    const dirIsNoise = (d) => { const n = dirCount.get(d) || 0; return n >= 3 && n > scopedRows.length / 2; };
     for (const p of peers.slice(0, 4)) {
         const bits = [];
         if (p.branch) bits.push(`branch \`${p.branch}\``);
@@ -1496,10 +1512,12 @@ function peerFooter(sid) {
             warn = `  · ⚠️ both edited: ${marked.join(', ')} — expect a conflict, KEEP BOTH${legend}`;
         }
         // State the fact, never the git operation. This runs in a latency-sensitive
-        // hook and must not spawn git, so it cannot know whether the branch is merely
-        // behind or has DIVERGED — and on a diverged branch "pull/rebase" is advice
-        // the real state contradicts. Naming the collision is what this footer is for.
-        else if (p.branch && myBranch && p.branch === myBranch) warn = '  · ⚠️ same branch — your commits will interleave; coordinate before you commit';
+        // hook and must not spawn git. The same-branch fact is stated once above
+        // the list; per peer, only a shared folder is added (advisory).
+        else {
+            const near = [...dirsOfScope(p)].filter(d => myDirs.has(d) && !dirIsNoise(d)).sort().slice(0, 2);
+            if (near.length) warn = `  · 📁 same folder: ${near.map(d => `${d}/`).join(', ')} — no shared file yet`;
+        }
         // Unique over the full live list (not just shown peers) — the MSG router
         // resolves a prefix against every row, so uniqueness must match that set.
         lines.push(`- session ${shortestUniquePeerPrefix(list, p.id)} · ${bits.join(' · ')}${warn}`);

package/src/klypix-core.mjs

@@ -34,7 +34,7 @@ import {
   challengeBrain, challengeContextToMarkdown, buildRenderSpec, structToBrief,
   brainLensData, lensToMarkdown, deathDateOfCard,
   statusContextToMarkdown, findFulfillmentCandidates, findStaleOpenCards, releaseFulfilledOpens, openStatusSummary, perAreaTableToMarkdown,
-  splitQueryTokens, scoreCardsAgainstQuery, correctionOverlaysFor, currentGuidanceFor, currentGuidancePrefix,
+  splitQueryTokens, scoreCardsAgainstQuery, correctionOverlaysFor, supersededByNote, currentGuidanceFor, currentGuidancePrefix,
   isFastDecayCard, isUnresolvedOpenCard, isSkillCard, validateGuard, guardSidecarPathFor, ensureGuardSidecar, DECAY_STALE_MS, formatDecayAge,
   isPlanCard, planFulfillmentFor, PLAN_PAIR_SIM_BRAIN, isAgconfTwinId,
   readPendingShips, clearPendingShips, pendingShipCards, formatCaptureReceipts, parseVerifySuffix, amendmentFirst,
@@ -56,7 +56,7 @@ import {
   dot, embedTexts, getEmbedder, getEmbedderForUse, withRerankerForUse,
   rerankHits, semanticFallbackNotice, semanticMemorySnapshot,
   semanticRuntimeInstalled, shouldPrewarmSemantic, vectorsForBrain,
-  cachedVectorsForBrain,
+  cachedVectorsForBrain, startBrainPreparation, preparationNotice,
 } from './semantic-memory.mjs';
 
 // The MCP and A2A faces prewarm through this protocol-neutral module. Bounded
@@ -435,6 +435,9 @@ export async function opSearchCanvases({ vault, query }) {
       const isArchived = (c) => /^archive$/i.test(c.area || '');
       const n = struct.counts;
       const head = `## ${rel} — "${struct.title}" · ${n.live ?? n.cards} live cards${n.archived ? `, ${n.archived} archived` : ''}, ${n.connections} connections${saved ? ` · saved ${saved}` : ''}${nameMatch && !matched.length ? '  (name/title match)' : ''}`;
+      // A stale hit names its replacement (1.98.0) — never a bare "archived".
+      let successors = new Map();
+      try { successors = correctionOverlaysFor(struct, matched.slice(0, 8)); } catch { successors = new Map(); }
       const body = matched.slice(0, 8).map(c => {
         const pos = (c.pos && c.pos.x != null) ? ` @(${Math.round(c.pos.x)},${Math.round(c.pos.y)})` : '';
         const allTags = [...new Set([...(c.tags || []), ...itemTags(c)])];
@@ -449,7 +452,10 @@ export async function opSearchCanvases({ vault, query }) {
         const fromReading = reading && !hit(c.title) && !hit(c.text) && hit(reading.text)
           ? `\n    in KLYPIX's saved reading: ${escapeInstructionLines(reading.text.replace(/\s+/g, ' ').slice(0, 240))}`
           : '';
-        return `- [${c.type}] "${c.title || '(card)'}" (${c.id})${pos}${date ? ` · ${date}` : ''}${tags}${arch}\n    ${escapeInstructionLines(ownText)}${fromReading}`;
+        const replaced = successors.has(c.id)
+          ? `\n    ↪ ${supersededByNote(successors.get(c.id))} — read that card for the current state`
+          : '';
+        return `- [${c.type}] "${c.title || '(card)'}" (${c.id})${pos}${date ? ` · ${date}` : ''}${tags}${arch}\n    ${escapeInstructionLines(ownText)}${fromReading}${replaced}`;
       }).join('\n');
       hits.push(matched.length ? `${head}\n${body}` : head);
     }
@@ -503,7 +509,13 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
     let struct;
     try { ({ struct } = await parseKlypix(fs.readFileSync(b.path))); } catch { continue; }
     let vecs = null;
-    if (qv) { try { vecs = await vectorsForBrain(pipe, b.path, struct.cards); } catch { /* lexical for this brain */ } }
+    if (qv) { try { const r = await questionVectors(pipe, b.path, struct.cards); vecs = r.usable ? r.vecs : null; } catch { /* lexical for this brain */ } }
+    // Replacement per stale card (1.98.0), only when this brain HAS lifecycle
+    // edges; skipped under as_of (a correction is a present-day fact).
+    let successors = new Map();
+    if (asOfTs == null && (struct.connections || []).some(cn => cn.label === 'superseded by' || cn.label === 'closed by')) {
+      try { successors = correctionOverlaysFor(struct, struct.cards); } catch { successors = new Map(); }
+    }
     for (const c of struct.cards) {
       if (c.type === 'container') continue;
       const t = String(c.text || '').toLowerCase();
@@ -529,7 +541,7 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
         if (isArchived) score -= 1;
         if (isCur) score += sem != null ? 1.5 : 1; // current-project locality prior
       }
-      scored.push({ score, sem, cur: isCur, project: b.project || path.basename(path.dirname(b.path)), area: c.area, c });
+      scored.push({ score, sem, cur: isCur, project: b.project || path.basename(path.dirname(b.path)), area: c.area, c, successor: successors.get(c.id) || null });
     }
   }
   if (!scored.length) return { blocks: [text(`No matches for "${query}" across ${brains.length} registered brain(s).`)] };
@@ -537,7 +549,7 @@ export async function opSearchAllBrains({ vault, query, as_of, log = () => {} })
   const top = scored.slice(0, 20);
   const lines = top.map(h => {
     const when = h.c.createdAt ? new Date(h.c.createdAt).toISOString().slice(0, 10) : '';
-    return `- ${h.cur ? '★ ' : ''}[${h.project}${h.area ? ' › ' + h.area : ''}] ${when} ${String(h.c.text || '').replace(/\s+/g, ' ').slice(0, 240)}`;
+    return `- ${h.cur ? '★ ' : ''}[${h.project}${h.area ? ' › ' + h.area : ''}] ${when} ${String(h.c.text || '').replace(/\s+/g, ' ').slice(0, 240)}${h.successor ? `\n    ↪ ${supersededByNote(h.successor)}` : ''}`;
   });
   // Never say "warming — retry" to someone who simply has not installed the
   // runtime: for them that advice is wrong forever, and their results are the
@@ -765,6 +777,21 @@ export async function opBrainTaskContext({
   };
 }
 
+// Card meanings for a question, never waiting on a preparation (1.97.0): at
+// most a few seconds of embedding inline; whatever is still missing is handed
+// to the background preparation (startBrainPreparation) and the answer says
+// so (preparationNotice). Meaning ranking is used once at least
+// MEANING_READY_SHARE of the cards are ready — below that the keyword path
+// covers every card, which a mostly-unprepared meaning ranking would not.
+const MEANING_READY_SHARE = 0.5;
+async function questionVectors(pipe, file, cards) {
+  const stats = {};
+  const vecs = await vectorsForBrain(pipe, file, cards, { stats });
+  if (stats.pending > 0) startBrainPreparation(file);
+  const usable = Boolean(vecs && vecs.size) && (!stats.wanted || stats.ready / stats.wanted >= MEANING_READY_SHARE);
+  return { vecs, stats, usable };
+}
+
 export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log = () => {} }) {
   // A last line `Also: <words>` is the caller's guess at the card's wording; it
   // joins the meaning query only (splitAskWords in klypix-format.mjs).
@@ -781,13 +808,14 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
   // Semantic blend (best-effort, time-bounded): embed the question + the brain's
   // cards on-device, hand rankForQuestion a Map<cardId, cosine>. A missing/warming
   // model degrades cleanly to pure lexical.
-  let semantic = null, mode = 'lexical', cardVecs = null;
+  let semantic = null, mode = 'lexical', cardVecs = null, prep = null;
   try {
     const pipe = await getEmbedderForUse(log, 20_000);
     if (pipe) {
       const [qv] = await embedTexts(pipe, [words ? `${q}\n${words}` : q], { kind: 'query' });
-      const vecs = await vectorsForBrain(pipe, t.file, struct.cards);
-      if (qv && vecs && vecs.size) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); cardVecs = vecs; mode = `semantic+lexical (on-device)${words ? ' + your Also words' : ''}`; }
+      const { vecs, stats, usable } = await questionVectors(pipe, t.file, struct.cards);
+      prep = stats;
+      if (qv && usable) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); cardVecs = vecs; mode = `semantic+lexical (on-device)${words ? ' + your Also words' : ''}`; }
     }
   } catch { semantic = null; cardVecs = null; }
   // Parity with search_all_brains (8445e9c): never say "warming — retry" to a
@@ -801,6 +829,7 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
   if (!semantic) {
     fallbackNotice = semanticFallbackNotice(false);
     if (fallbackNotice) mode = fallbackNotice.startsWith('LEXICAL ONLY') ? 'lexical-only (no semantic runtime)' : 'lexical (semantic warming)';
+    if (prep?.pending > 0) mode = 'lexical (preparing search by meaning)';
     if (words) mode += ' + your Also words';
   }
   const kk = Math.max(1, Math.min(20, k || 10));
@@ -849,7 +878,11 @@ export async function opBrainAsk({ vault, canvas, question, as_of, k = 10, log =
       mode += ' + status-mode';
     } catch { statusMd = ''; }
   }
-  const noticeMd = fallbackNotice ? `> ${fallbackNotice}\n\n` : '';
+  // While the brain is still being prepared, that is the one thing to say: the
+  // runtime IS installed, so the "warming — retry" fallback line would only
+  // repeat it less precisely.
+  const prepNotice = preparationNotice(t.file, prep, { usedMeaning: Boolean(semantic) });
+  const noticeMd = prepNotice ? `> ${prepNotice}\n\n` : (fallbackNotice ? `> ${fallbackNotice}\n\n` : '');
   const evidenceCache = new Map();
   const evidenceForCard = (card) => formatCardEvidence(inspectCardEvidence(card, { projectRoot: path.dirname(t.file), cache: evidenceCache }));
   return { blocks: [text(stamp + noticeMd + statusMd + questionContextToMarkdown(q, result, { mode, as_of: timeTravel ? as_of : null, evidenceForCard }))] };
@@ -874,8 +907,8 @@ export async function opBrainChallenge({ vault, canvas, claim, k = 8, via, log =
     const pipe = await getEmbedderForUse(log, 20_000);
     if (pipe) {
       const [qv] = await embedTexts(pipe, [q], { kind: 'query' });
-      const vecs = await vectorsForBrain(pipe, t.file, struct.cards);
-      if (qv && vecs && vecs.size) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); mode = 'semantic+lexical (on-device)'; }
+      const { vecs, usable } = await questionVectors(pipe, t.file, struct.cards);
+      if (qv && usable) { semantic = new Map(); for (const [id, v] of vecs) semantic.set(id, dot(qv, v)); mode = 'semantic+lexical (on-device)'; }
     }
   } catch { semantic = null; }
   const result = challengeBrain(struct, q, { semantic, k: Math.max(1, Math.min(20, k || 8)) });
@@ -1163,7 +1196,11 @@ export async function opBrainReconcile({ vault, canvas, root, mode = 'all', ref
         if (mode === 'plans' && cold && installed) {
           try {
             const pipe = await getEmbedderForUse(log, 20_000);
-            if (pipe) vecs = await vectorsForBrain(pipe, file, struct.cards);
+            if (pipe) {
+              const stats = {};
+              vecs = await vectorsForBrain(pipe, file, struct.cards, { stats });
+              if (stats.pending > 0) startBrainPreparation(file);
+            }
           } catch (e) { embedErr = e; }
         }
         let pairSim = null, how;
@@ -1699,7 +1736,9 @@ export async function opBrainConnect({ vault, canvas, apply = false, max = 24, t
   try { pipe = await getEmbedderForUse(log, 20_000); } catch { /* saturated/unavailable → structural */ }
   if (pipe) {
     try {
-      const vecs = await vectorsForBrain(pipe, file, struct.cards);
+      const stats = {};
+      const vecs = await vectorsForBrain(pipe, file, struct.cards, { stats });
+      if (stats.pending > 0) startBrainPreparation(file);
       const items = live.filter(c => vecs.get(c.id));
       const sources = normalizedScope === 'orphans' ? items.filter(c => orphanIds.has(c.id)) : items;
       for (const a of sources) {