klypix-mcp 1.104.0 → 1.106.0

package/README.md

@@ -10,10 +10,17 @@ over MCP by a process on your machine. In the standalone setup, brain data stays
 your agent's provider can still receive what the agent reads. Integration depth differs by host — see
 [Supported hosts](#supported-hosts-and-their-integration-level).
 
-The **Apache-2.0 engine works without the KLYPIX desktop app or a KLYPIX account**. The optional
+Klypix is a **portable project workspace with a shared brain**. This repository provides its
+local MCP server for shared project memory in coding tools. The **Apache-2.0 engine works without the KLYPIX
+desktop app or a KLYPIX account**. The optional
 [Windows workspace](https://klypix.com/developers) lets people inspect the same project brain
 beside their files. App-based sharing has its own cloud path; see [Security and permissions](#security-and-permissions).
 
+For the **Projects & Ideas** path — saved project materials in ChatGPT or Claude chat — follow
+[Save project materials and use them with your assistant](https://klypix.com/guides/connect-klypix-to-chatgpt-and-claude).
+That uses Klypix's separate hosted connection for the spaces you authorize. Installing this local
+MCP server does not set up that connection.
+
 [Install](#quick-start) · [Try your first decision](#your-first-decision-and-correction) ·
 [Supported hosts](#supported-hosts-and-their-integration-level) ·
 [Privacy](#security-and-permissions) · [Limits](#current-limitations) · [Uninstall](#uninstall)
@@ -38,6 +45,11 @@ It creates `brain.klypix` if the project has none, wires the editors it finds on
 registers the `.klypix` merge driver if this is a git repo, and exits only after a real MCP
 handshake has counted the tools that answered.
 
+Next, reconnect your coding host and [try your first decision and correction](#your-first-decision-and-correction).
+A successful trial means a fresh session finds your recorded decision and its reason, then finds
+the corrected decision as current. Check the returned source cards; a successful install alone
+does not prove that your host has loaded the tools or that a particular decision was retrieved.
+
 [![Claude Code](https://img.shields.io/badge/Claude_Code-5_lifecycle_hooks-475569?style=flat-square)](#supported-hosts-and-their-integration-level)
 [![Codex](https://img.shields.io/badge/Codex-native_MCP_%2B_presence-475569?style=flat-square)](#supported-hosts-and-their-integration-level)
 [![Cursor](https://img.shields.io/badge/Cursor-MCP_config_%2B_rules-475569?style=flat-square)](#supported-hosts-and-their-integration-level)
@@ -158,6 +170,9 @@ so running it from `src/` is fine), gives the project a brain if it doesn't have
 agent tools you actually have installed, registers the card-level `.klypix` merge driver if it's a
 git repo, and then **proves the result** before it exits:
 
+Illustrative output; detected editors, file counts, tool counts and timings vary with the machine
+and installed version:
+
 ```text
   project   E:\work\api  (git repository root)
   brain     created brain.klypix — a starter brain, ready for its first decision

package/bin/klypix-install.mjs

@@ -495,7 +495,7 @@ try {
     // a newer klypix-format cannot. merge-brains and the driver ship here so
     // brain-history's restore merge, the KLYPIX core and the git driver all
     // find one engine in this directory.
-    for (const f of ['global-brain-hook.mjs', 'klypix-format.mjs', 'brain-graveyard.mjs', 'merge-brains.mjs', 'klypix-merge-driver.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'provenance.mjs', 'brain-note.mjs', 'brain-evidence.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'app-lease.mjs', 'klypix-core.mjs', 'app-bridge-protocol.mjs', 'app-bridge-client.mjs', 'app-tools.mjs', 'card-files.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'session-handoff.mjs', 'live-projection.mjs', 'canvas-view-app.html']) {
+    for (const f of ['global-brain-hook.mjs', 'klypix-format.mjs', 'brain-graveyard.mjs', 'merge-brains.mjs', 'klypix-merge-driver.mjs', 'capture-gap.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'enrichment.mjs', 'provenance.mjs', 'brain-note.mjs', 'brain-evidence.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'app-lease.mjs', 'klypix-core.mjs', 'app-bridge-protocol.mjs', 'app-bridge-client.mjs', 'app-tools.mjs', 'card-files.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'editor-detect.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'repo-state.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'network-bridge.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'bench.mjs', 'codex-brain-hook.mjs', 'codex-hooks.mjs', 'session-handoff.mjs', 'live-projection.mjs', 'whose.mjs', 'whose-classify.mjs', 'whose-ledger.mjs', 'whose-rescue.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 [
@@ -568,11 +568,16 @@ try {
         ['SessionStart', { matcher: 'startup|resume|clear', hooks: [{ type: 'command', command: brainCmd('') }] }],
         ['UserPromptSubmit', { hooks: [{ type: 'command', command: brainCmd('--prompt'), timeout: 10 }] }],
         ['Stop', { hooks: [{ type: 'command', command: brainCmd('--capture') }] }],
-        ['PostToolUse', { matcher: 'Bash|PowerShell|Edit|Write', hooks: [{ type: 'command', command: brainCmd('--live'), timeout: 10 }] }],
+        ['PostToolUse', { matcher: 'Bash|PowerShell|Edit|Write|MultiEdit|NotebookEdit', hooks: [{ type: 'command', command: brainCmd('--live'), timeout: 10 }] }],
         // Guard cards (2026-08-24): pre-action lane. Fast path — reads only the
         // compiled guard sidecar; 'warn' injects context, 'block' denies with
         // the card's message. Absent guards = stat + one tiny read, then no-op.
         ['PreToolUse', { matcher: 'Bash|PowerShell|Edit|Write', hooks: [{ type: 'command', command: brainCmd('--guard'), timeout: 10 }] }],
+        // Session end (1.105.0): a closed or cut-off Claude Code session leaves
+        // the lane at once. Before this, only the 10-minute TTL removed it, so the
+        // next session read a dead peer as "live" and refused to continue its
+        // work (round-4 continuity bench, 2026-10-20). Codex already had this.
+        ['SessionEnd', { hooks: [{ type: 'command', command: brainCmd('--end'), timeout: 10 }] }],
     ];
     const stripOurs = (arr) => (Array.isArray(arr) ? arr : [])
         .map(g => (g && Array.isArray(g.hooks)) ? { ...g, hooks: g.hooks.filter(h => !(typeof h?.command === 'string' && h.command.includes(HOOK_MARK))) } : g)
@@ -679,7 +684,7 @@ try {
     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 if (!notWired.length) console.log('✓ wired 6 hooks: SessionEnd (--end) · 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}.`);
     console.log(`✓ MCP supervisor runs from the local bundle (node ${fwd(path.join(BRAIN_DIR, 'klypix-mcp-server.mjs'))}) — compatible core updates activate without restarting the host.`);
     if (migrated) console.log(`✓ migrated ${migrated.file} klypix-canvas server: ${migrated.from} → ${migrated.to} (backup: .mcp.json.klypix-bak). Reconnect (/mcp) or restart to pick it up.`);

package/bin/klypix-mcp.mjs

@@ -19,7 +19,7 @@ const PKG_VERSION = (() => {
   }
 })();
 
-const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'git-hook', 'brain-history', 'brain-deleted', 'orphans', 'diff', 'pr-brief', 'uninstall', 'bench', 'sessions']);
+const DIRECT = new Set(['install', 'link', 'doctor', 'runtime', 'conformance', 'garden-code', 'init', 'git-driver', 'git-hook', 'brain-history', 'brain-deleted', 'orphans', 'diff', 'pr-brief', 'uninstall', 'bench', 'sessions', 'rescue']);
 
 const USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -41,6 +41,8 @@ const USAGE = [
   '  git-hook [install|remove|status]    wire the agent-neutral commit-capture hook (any agent/branch/worktree → brain cards)',
   '  brain-history [list|restore <id>]   restore points for this brain — undo an accidental delete, edit, or overwrite',
   '  brain-deleted [list|restore|purge]  recycle bin for this brain — cards you deleted, kept recoverable',
+  '  rescue [list|show <id>|restore <id> [paths…]|prune]',
+  '                                      copies of uncommitted files KLYPIX saved before a git command could discard them',
   '  orphans [brain] [--apply|--areas]   orphan gardener backfill: report unconnected cards, link the confident subset (dry-run default)',
   '  diff [ref] [--brain <path>]         readable brain diff vs a git ref (default HEAD) — markdown to stdout',
   '  pr-brief [baseRef] [--brain <path>] brain decisions touching the files changed since baseRef — PR-comment markdown',

package/bin/klypix-rescue.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+// `klypix-mcp rescue [list|show <n|id>|restore <n|id> [paths…]|prune]`
+// The human surface for the rescue copies KLYPIX takes before a git command
+// could discard uncommitted files (src/whose-rescue.mjs). A copy nobody can
+// find is a copy nobody trusts, so `list` is the default, `show` says exactly
+// what a copy holds and what it left out, and `restore` says what it changed
+// and how to undo it — a restore first saves the files it is about to replace.
+//
+// A restore writes the working tree only. It never stages, commits, switches a
+// branch or touches the git index.
+//
+// ARGV: process.argv.slice(2) — the standalone shape. The dispatcher
+// (bin/klypix-worker.mjs runVerb) removes its own `rescue` token first.
+import path from 'path';
+import {
+  listRescuesResult, showRescue, restoreRescue, pruneRescues,
+  rescueRestoreCommand, RESCUE_KEEP, RESCUE_MAX_AGE_MS,
+} from '../src/whose-rescue.mjs';
+
+const USAGE = [
+  'klypix-mcp rescue — copies of uncommitted files KLYPIX saved before a git command could discard them.',
+  '',
+  'Usage:',
+  '  npx klypix-mcp rescue [list] [--all]               newest first (--all: every worktree of this repository)',
+  '  npx klypix-mcp rescue show <n|id>                  what one copy holds, and what it left out',
+  '  npx klypix-mcp rescue restore <n|id> [paths…]      write its files back (all, or the paths/folders named)',
+  '  npx klypix-mcp rescue prune [--days 14] [--keep 50] [--dry-run]',
+  '',
+  'Flags: --repo <dir> (default: the current folder), --json, --other-worktree (restore a copy taken in another worktree here).',
+  '<n> is the number `list` shows; an id may be shortened while it stays unique.',
+  'A restore first saves the files it replaces as a new copy, so it can be undone the same way.',
+  'It writes the working tree only: nothing is staged, committed or switched.',
+].join('\n');
+
+const raw = process.argv.slice(2);
+if (raw.includes('--help') || raw.includes('-h')) { console.log(USAGE); process.exit(0); }
+
+const VALUE_FLAGS = new Set(['--repo', '--days', '--keep']);
+const BOOL_FLAGS = new Set(['--json', '--all', '--dry-run', '--other-worktree']);
+const flags = {};
+const positional = [];
+for (let i = 0; i < raw.length; i++) {
+  const a = raw[i];
+  if (a === '--') { positional.push(...raw.slice(i + 1)); break; }
+  if (VALUE_FLAGS.has(a)) {
+    if (i + 1 >= raw.length) { console.error(`klypix-mcp rescue: ${a} needs a value.\n\n${USAGE}`); process.exit(2); }
+    flags[a] = raw[++i];
+  } else if (BOOL_FLAGS.has(a)) flags[a] = true;
+  else if (a.startsWith('-') && a.length > 1) { console.error(`klypix-mcp rescue: unknown flag ${a}\n\n${USAGE}`); process.exit(2); }
+  else positional.push(a);
+}
+const ACTIONS = ['list', 'show', 'restore', 'prune'];
+const action = ACTIONS.includes(positional[0]) ? positional.shift() : 'list';
+if (action === 'list' && positional.length) {
+  console.error(`klypix-mcp rescue: unknown command "${positional[0]}".\n\n${USAGE}`);
+  process.exit(2);
+}
+const repoRoot = path.resolve(flags['--repo'] || process.cwd());
+const json = Boolean(flags['--json']);
+const out = (value) => console.log(JSON.stringify(value, null, 2));
+
+const ago = (ts) => {
+  const m = Math.max(0, Math.round((Date.now() - ts) / 60000));
+  if (m < 1) return 'just now';
+  if (m < 60) return `${m}m ago`;
+  const h = Math.round(m / 60);
+  return h < 48 ? `${h}h ago` : `${Math.round(h / 24)}d ago`;
+};
+const utc = (ts) => new Date(ts).toISOString().replace('T', ' ').replace(/\.\d+Z$/, ' UTC');
+const plural = (n, word, many = `${word}s`) => `${n} ${n === 1 ? word : many}`;
+const SHOW = 12;
+const listLines = (items, fmt) => {
+  for (const x of items.slice(0, SHOW)) console.log(`  ${fmt(x)}`);
+  if (items.length > SHOW) console.log(`  …and ${items.length - SHOW} more`);
+};
+const summary = (e) => {
+  const absent = e.deleted.length ? ` (${e.deleted.length} absent)` : '';
+  const left = e.skipped.length ? `, ${e.skipped.length} not included` : '';
+  return `${plural(e.paths.length, 'file')}${absent}${left}`;
+};
+
+if (action === 'list') {
+  const res = listRescuesResult({ repoRoot, allWorktrees: Boolean(flags['--all']) });
+  if (!res.ok) { console.error(`klypix-mcp rescue: ${res.error}`); process.exit(1); }
+  if (json) { out(res.rescues); process.exit(0); }
+  if (!res.rescues.length) {
+    console.log(`No rescue copies in ${res.top}${flags['--all'] ? '' : ' (this worktree)'}.`);
+    if (res.elsewhere) console.log(`${plural(res.elsewhere, 'copy', 'copies')} taken in other worktrees of this repository: add --all.`);
+    console.log('KLYPIX takes one before a git command could discard uncommitted files.');
+    process.exit(0);
+  }
+  console.log(`Rescue copies in ${res.top}, newest first:`);
+  // Numbers count this worktree's copies only — the same numbering `show <n>`
+  // and `restore <n>` use — so a copy from another worktree gets none.
+  let n = 0;
+  for (const e of res.rescues) {
+    const num = e.here ? String(++n) : '-';
+    const where = e.here ? '' : `  [${e.worktree}]`;
+    console.log(`  ${num.padStart(3)}  ${e.id}  ${ago(e.at).padEnd(9)} ${e.reason} · ${summary(e)}${where}`);
+  }
+  if (!flags['--all'] && res.elsewhere) console.log(`  (+${plural(res.elsewhere, 'copy', 'copies')} from other worktrees: add --all)`);
+  console.log('');
+  console.log('Show one:    npx klypix-mcp rescue show <n|id>');
+  console.log('Restore one: npx klypix-mcp rescue restore <n|id> [paths…]');
+  console.log('A restore saves the current files first, so it can be undone the same way.');
+  process.exit(0);
+}
+
+if (action === 'show') {
+  if (!positional[0]) { console.error(`Usage: npx klypix-mcp rescue show <n|id>\n\n${USAGE}`); process.exit(2); }
+  const res = showRescue({ repoRoot, id: positional[0] });
+  if (json) { out(res); process.exit(res.ok ? 0 : 1); }
+  if (!res.ok) { console.error(`klypix-mcp rescue: ${res.error}`); process.exit(1); }
+  console.log(`Rescue ${res.id} — ${res.reason}`);
+  console.log(`  taken     ${ago(res.at)} (${utc(res.at)})${res.sid ? ` by session ${res.sid}` : ''}`);
+  console.log(`  on        ${res.branch || 'a detached HEAD'}${res.head ? ` @ ${res.head.slice(0, 10)}` : ' (no commit yet)'}${res.worktree ? `, in ${res.worktree}` : ''}${res.here ? '' : '  — ANOTHER worktree'}`);
+  console.log(`  git       ${res.ref} (commit ${res.commit.slice(0, 10)})`);
+  console.log(`\n${plural(res.files.length, 'file')}; ${res.stat.added} line(s) added and ${res.stat.removed} removed against that HEAD:`);
+  const width = Math.min(48, Math.max(...res.files.map((f) => f.path.length), 4));
+  listLines(res.files, (f) => {
+    const lines = f.binary ? 'binary' : f.change === 'deleted' || f.change === 'absent' ? '' : `+${f.added} -${f.removed}`;
+    return `${f.change.padEnd(12)} ${f.path.padEnd(width)} ${lines}`.trimEnd();
+  });
+  if (res.skipped.length) {
+    console.log('\nNot included:');
+    listLines(res.skipped, (s) => `${s.path} (${s.why})`);
+  }
+  console.log(`\nRestore:     ${rescueRestoreCommand(res.id)} [paths…]`);
+  console.log(`Or with git: ${res.head ? `git diff ${res.commit.slice(0, 10)}^ ${res.commit.slice(0, 10)}` : `git show ${res.commit.slice(0, 10)}`}`);
+  process.exit(0);
+}
+
+if (action === 'restore') {
+  if (!positional[0]) {
+    console.error('Usage: npx klypix-mcp rescue restore <n|id> [paths…]');
+    console.error('Run `npx klypix-mcp rescue list` to see the copies.');
+    process.exit(2);
+  }
+  const [id, ...paths] = positional;
+  const res = restoreRescue({
+    repoRoot, id, paths: paths.length ? paths : null, sid: 'cli', cwd: process.cwd(),
+    allowOtherWorktree: Boolean(flags['--other-worktree']),
+  });
+  if (json) { out(res); process.exit(res.ok && !res.skipped?.length ? 0 : 1); }
+  if (!res.ok) {
+    console.error(`Restore failed: ${res.error}`);
+    if (res.skipped?.length) listLines(res.skipped, (s) => `${s.path} — ${s.why}`);
+    process.exit(1);
+  }
+  const written = res.restored.filter((p) => !res.deleted.includes(p));
+  if (res.restored.length) {
+    console.log(`Restored ${plural(res.restored.length, 'path')} from rescue ${res.from}:`);
+    listLines(written, (p) => p);
+    if (res.deleted.length) listLines(res.deleted, (p) => `removed ${p} (it did not exist when the copy was taken)`);
+  } else console.log(`Nothing needed writing from rescue ${res.from}.`);
+  if (res.unchanged.length) {
+    console.log('Already as in the copy:');
+    listLines(res.unchanged, (p) => p);
+  }
+  if (res.skipped.length) {
+    console.log('Left as it is:');
+    listLines(res.skipped, (s) => `${s.path} — ${s.why}`);
+  }
+  if (res.backupId) {
+    console.log(`\nWhat was there before is saved as ${res.backupId}. Undo this restore: ${rescueRestoreCommand(res.backupId)}`);
+  }
+  console.log('Only the working tree changed: nothing was staged or committed. `git status` shows the result.');
+  process.exit(res.skipped.length ? 1 : 0);
+}
+
+// prune
+const days = flags['--days'] != null ? Number(flags['--days']) : RESCUE_MAX_AGE_MS / 86400000;
+const keep = flags['--keep'] != null ? Number(flags['--keep']) : RESCUE_KEEP;
+if (!Number.isFinite(days) || days < 0 || !Number.isInteger(keep) || keep < 0) {
+  console.error(`klypix-mcp rescue prune: --days takes a number of days and --keep a whole number.\n\n${USAGE}`);
+  process.exit(2);
+}
+const res = pruneRescues({ repoRoot, keep, maxAgeMs: days * 86400000, dryRun: Boolean(flags['--dry-run']) });
+if (json) { out(res); process.exit(res.ok ? 0 : 1); }
+if (!res.ok) { console.error(`klypix-mcp rescue: ${res.error}`); process.exit(1); }
+const rule = `older than ${days} day(s), keeping the newest ${keep} of each worktree`;
+if (flags['--dry-run']) {
+  const would = res.wouldDelete || [];
+  console.log(would.length ? `Would prune ${plural(would.length, 'copy', 'copies')} ${rule}:` : `Nothing to prune (${rule}).`);
+  listLines(would, (x) => x);
+  console.log('DRY RUN — nothing was deleted.');
+} else {
+  console.log(res.deleted.length ? `Pruned ${plural(res.deleted.length, 'copy', 'copies')} ${rule}; ${res.kept} remain.` : `Nothing to prune (${rule}); ${res.kept} kept.`);
+}
+process.exit(0);

package/bin/klypix-worker.mjs

@@ -190,6 +190,11 @@ await runVerb('pr-brief', './klypix-pr-brief.mjs');
 // CLI's own --help) said no uninstall existed at all.
 await runVerb('uninstall', './klypix-uninstall.mjs');
 
+// `npx klypix-mcp rescue` — list, show and restore the rescue copies KLYPIX
+// takes before a git command could discard uncommitted files (whose-rescue.mjs).
+// A restore writes the working tree only, after saving what it replaces.
+await runVerb('rescue', './klypix-rescue.mjs');
+
 // `npx klypix-mcp garden-code` — the HUMAN half of the garden approval gate.
 // brain_garden's apply requires an 8-char code derived from the exact dormant
 // candidate set + day; the agent is deliberately never shown it. The human runs
@@ -854,7 +859,7 @@ server.registerTool('brain_note', {
 
 server.registerTool('brain_message', {
   title: 'Message another agent session on this project — live, idle, or recently closed (one-time note, not a brain card)',
-  description: 'Leave a DELIBERATE, targeted note for another agent session working on this project ("merged the hook refactor — rebase before you commit", "don\'t touch canvasStore, mid-refactor"). Address it to a session id from the brain_sync peer list or brain_doctor. A LIVE session gets it on its next lifecycle event or KLYPIX tool call, even if it is idle right now. A session KLYPIX has identified before that is NOT on the lane now (closed, or quiet) still receives a directed note the moment it next acts — the note is kept for up to 7 days — so if you would otherwise ask the human to relay or paste something to another agent session, send it here instead and tell them it was sent or queued. If the human wants a queued note handled sooner, brain_reopen asks them whether to reopen that session now. Broadcasts ("all") reach only sessions live right now. Any MCP client can send and receive through the shared machine-local presence lane. Delivery contract: a supported action offers the note into model-visible context, a later independent action acknowledges it, and it retires either by an explicit brain_message_receipt ("acted on it") or by auto-consumption on a further independent action; your receipt line names which, and neither is proof a human read it. Expiry or capacity loss leaves a failed per-recipient receipt instead of silently disappearing. OS-user-local and machine-local. Ephemeral and NOT persisted to the brain — for a durable decision use brain_note instead.',
+  description: 'Leave a DELIBERATE, targeted note for another agent session working on this project ("merged the hook refactor — rebase before you commit", "don\'t touch canvasStore, mid-refactor"). Address it to a session id from the brain_sync peer list or brain_doctor. A LIVE session gets it on its next lifecycle event or KLYPIX tool call, even if it is idle right now. A session KLYPIX has identified before that is NOT on the lane now (closed, or quiet) still receives a directed note the moment it next acts — the note is kept for up to 7 days — so if you would otherwise ask the human to relay or paste something to another agent session, send it here instead and tell them it was sent or queued. If the human wants a queued note handled sooner, brain_reopen asks them whether to reopen that session now. Broadcasts ("all") reach only sessions live right now. Any MCP client can send and receive through the shared machine-local presence lane. Delivery contract: a supported action offers the note into model-visible context, a later independent action acknowledges it, and it retires either by an explicit brain_message_receipt ("acted on it") or by auto-consumption on a further independent action; your receipt line names which, and neither is proof a human read it. Expiry or capacity loss leaves a failed per-recipient receipt instead of silently disappearing. OS-user-local and machine-local; with KLYPIX network installed on both computers, a session on another computer in the same project is reached too (its id starts with net:, and there is no read receipt across computers). Ephemeral and NOT persisted to the brain — for a durable decision use brain_note instead.',
   inputSchema: {
     text: z.string().describe('The note to deliver (kept to 400 chars).'),
     to: z.string().optional().describe('Target — a session id (or unique prefix of at least 8 characters) from the peer list, or an exact unique branch; omit or "all" for every session live right now. A directed id may name a session that is not running: the note then waits and is delivered when that session next starts.'),
@@ -873,6 +878,7 @@ server.registerTool('brain_message', {
     to,
     via: extra.klypixClientName,
     from: extra.klypixRequestIdentity.sessionId,
+    networkSend: mcpPresence.networkSend,
   }));
 });
 
@@ -1124,7 +1130,7 @@ server.registerTool('brain_handoff', {
 
 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. `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.',
+  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 computer appears only when KLYPIX network is installed on both computers (presence, intent, files and brain_message, no result reconciliation), and file overlap remains ADVISORY.',
   annotations: {
     destructiveHint: false,
     idempotentHint: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.104.0",
+  "version": "1.106.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Shared project memory for Claude Code, Codex and Cursor: decisions and corrections through MCP.",
   "type": "module",
@@ -91,7 +91,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/session-handoff.mjs && node test/lock-notes.mjs && node test/live-projection.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/marker-after-colon.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": "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/session-handoff.mjs && node test/lock-notes.mjs && node test/whose-classify.mjs && node test/whose-ledger.mjs && node test/whose-rescue.mjs && node test/whose-hook.mjs && node test/live-projection.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/network-bridge.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/marker-after-colon.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",
@@ -101,7 +101,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.7.5",
-    "@modelcontextprotocol/sdk": "^1.31.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "fractional-indexing": "^3.2.0",
     "jpeg-js": "^0.4.4",
     "jszip": "^3.10.1",

package/src/agent-presence.mjs

@@ -114,7 +114,7 @@ export function isProcessAlive(pid) {
 }
 
 export function isDeadHostRow(session, now = Date.now(), probe = isProcessAlive) {
-  if (!session || session.via === 'cloud') return false;
+  if (!session || (session.via === 'cloud' || session.via === 'network')) return false;
   if (String(session.hostPidSource || '') !== 'env') return false;
   if (!session.machine || String(session.machine) !== String(MACHINE_ID)) return false;
   if (now - Number(session.lastSeen || 0) < DEAD_HOST_GRACE_MS) return false;
@@ -635,7 +635,7 @@ const pruneDirectory = (rows, now) => (Array.isArray(rows) ? rows : [])
 function rememberSession(directory, row, now, { ended = false } = {}) {
   const rows = pruneDirectory(directory, now);
   const id = recipientKey(row?.logicalSessionId || '');
-  if (!id || row?.via === 'cloud') return rows;
+  if (!id || (row?.via === 'cloud' || row?.via === 'network')) return rows;
   const index = rows.findIndex((entry) => entry.id === id);
   const prev = index >= 0 ? rows[index] : null;
   const scope = [...new Set([...normalizeFiles(row.files), ...normalizeFiles(row.observedFiles)])].slice(-8);
@@ -1297,6 +1297,9 @@ export function upsertSession({
 // machine renders once, as local. Rows land with via:'cloud' + channelSeen.cloud
 // so existing TTL pruning governs their lifetime (P3) and buildPresenceFrame
 // refuses to re-broadcast them (loop prevention).
+// Where a remote row came from. Only these are ever written by upsertRemoteSessions.
+export const REMOTE_VIAS = new Set(['cloud', 'network']);
+
 export function upsertRemoteSessions({ brainPath, rows, machineId = MACHINE_ID, home, now = Date.now() }) {
   if (!brainPath || !Array.isArray(rows) || !rows.length) return withWriteVerdict([], false, 'nothing-to-write');
   const laneFile = laneFileFor(brainPath, home);
@@ -1309,10 +1312,12 @@ export function upsertRemoteSessions({ brainPath, rows, machineId = MACHINE_ID,
     const data = laneRead.data;
     const sessions = pruneSessions(data.sessions, now);
     for (const row of rows) {
-      if (!row?.id || !row.machine || row.via !== 'cloud') continue;
+      // 'cloud' rows ride the Supabase presence channel; 'network' rows come from
+      // the KLYPIX network engine (network-bridge.mjs). Both are remote, never local.
+      if (!row?.id || !row.machine || !REMOTE_VIAS.has(row.via)) continue;
       if (String(row.machine) === String(machineId)) continue;   // never a remote row for this machine
       const existingIdx = sessions.findIndex((session) => session.id === row.id);
-      if (existingIdx >= 0 && sessions[existingIdx].via !== 'cloud') continue;   // local row wins
+      if (existingIdx >= 0 && !REMOTE_VIAS.has(sessions[existingIdx].via)) continue;   // local row wins
       const previous = existingIdx >= 0 ? sessions[existingIdx] : {};
       // REPLACE semantics, like `files` below: the frame is a full snapshot of
       // the sender's row, so an empty/absent observed lane must CLEAR the
@@ -1338,11 +1343,12 @@ export function upsertRemoteSessions({ brainPath, rows, machineId = MACHINE_ID,
         ...(remoteObserved.length ? { observedFiles: remoteObserved } : {}),
         machine: String(row.machine),
         host: row.host ?? previous.host ?? null,
-        via: 'cloud',
-        channels: ['cloud'],
-        transport: { cloud: { status: 'relay-best-effort', at: now } },
+        via: row.via,
+        channels: [row.via],
+        ...(row.via === 'network' && row.address ? { networkAddress: String(row.address).slice(0, 200) } : {}),
+        transport: { [row.via]: { status: 'relay-best-effort', at: now } },
         deliveryReachability: 'relay-best-effort',
-        channelSeen: { cloud: now },   // receiver clock (P4) — frame time never decides freshness
+        channelSeen: { [row.via]: now },   // receiver clock (P4) — frame time never decides freshness
         startedAt: previous.startedAt || now,
         lastSeen: now,
       };
@@ -1399,7 +1405,7 @@ export function purgeRemotePresence({ brainPath, home, now = Date.now() }) {
     };
     const data = laneRead.data;
     const maintainedSessions = pruneSessions(data.sessions, now);
-    const sessions = maintainedSessions.filter((session) => session.via !== 'cloud');
+    const sessions = maintainedSessions.filter((session) => !REMOTE_VIAS.has(session.via));
     const maintainedMessages = maintainMessages(data.messages, now);
     const messages = maintainedMessages.filter((message) =>
       !String(message?.dedupeKey || '').startsWith(REMOTE_MESSAGE_DEDUPE_PREFIX));
@@ -2032,7 +2038,7 @@ export function rotateEndedSessionIdentity({
 
     const existing = sessions.find((session) => recipientKey(session.id) === toKey
       || normalizeAliases(session.aliases).includes(toKey)) || null;
-    if (existing?.via === 'cloud') {
+    if ((existing?.via === 'cloud' || existing?.via === 'network')) {
       return { ok: false, changed: false, reason: 'destination-remote-only' };
     }
     const channelSeen = freshChannelSeen(existing?.channelSeen, now);
@@ -2141,7 +2147,7 @@ export function switchMcpSessionIdentity({
     // A stale alias on A must not turn this fresh switch back into an A→B
     // rekey. Only an independently stored B row may contribute B's own state.
     const existing = destinationCandidate === from ? null : destinationCandidate;
-    if (existing?.via === 'cloud') {
+    if ((existing?.via === 'cloud' || existing?.via === 'network')) {
       return { ok: false, changed: false, reason: 'destination-remote-only' };
     }
 
@@ -2809,7 +2815,11 @@ export function postPresenceMessage({
     // Receipt truth must survive peers ending before the sender checks doctor.
     // Snapshot only recipient session ids (already lane metadata) at SEND time;
     // old messages without this additive field retain reconstruction fallback.
-    const resolution = resolveMessageTarget({ to: target }, sessions);
+    // A session on another computer reached over the KLYPIX network is never a
+    // local-lane recipient: nothing on this PC would ever collect the note, so
+    // it would only age into a failed receipt. brain_message routes those
+    // through the engine (klypix-core.mjs opBrainMessage).
+    const resolution = resolveMessageTarget({ to: target }, sessions.filter((row) => row?.via !== 'network'));
     const candidateIds = resolution.ids
       .filter((id) => id && id !== senderId)
       .map((id) => String(id).slice(0, 160));
@@ -3629,7 +3639,7 @@ export function mergePresenceRows(sessions) {
     || (Array.isArray(row.channels) && row.channels.includes('lifecycle')));
   const isFoldableOrphan = (group) => group.length === 1
     && group.every((row) => !recipientKey(row.logicalSessionId)
-      && row.via !== 'cloud'
+      && (row.via !== 'cloud' && row.via !== 'network')
       && Number(row.hostPid) > 0
       && row.machine
       && Array.isArray(row.channels) && row.channels.length

package/src/agent-rules.mjs

@@ -515,7 +515,9 @@ commits and the checkouts it worked in (with their uncommitted files) automatica
 \`brain_sync\` may list **unfinished work** another session left without a card: if the human asks
 you to continue it, take it with \`brain_handoff\` {action:"take", session:"<id>"} first, and look
 first in the checkout the record names — it may be a side folder, not the project. That list is history, not a lock — a stopped session holds no claim on its
-files. Never ask the human to paste a summary into the next session.
+files. A LIVE session's uncommitted edits are its work in progress: never sweep, discard or stash them
+(\`git add -A\`, \`commit -a\`, \`reset --hard\`, \`stash\`); commit only your own files. A stopped session's leftovers
+are yours to finish and commit when you are continuing its work; never discard them without the human. Never ask the human to paste a summary into the next session.
 
 **A note that asks agents to keep off a file**, whatever its wording (here, in AGENTS.md / CLAUDE.md or any
 notes file) can outlive the work it protected. Before you obey one, or before you edit the file