klypix-mcp 1.103.0 → 1.105.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
@@ -515,6 +530,33 @@ so fresh relevant findings are not crowded out by older area vocabulary.
 Briefs are **not** injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity —
 there are no lifecycle hooks on those hosts.
 
+### The live projection — the file the agent obeys
+
+The coordination bench showed that an agent trusts the instruction file it was launched with
+over anything a tool or hook tells it, and that each host reads a different surface. So the
+brain's state is projected into those files, in two halves:
+
+- **Committed, from the brain:** the compact brief block in `AGENTS.md` (standing rules,
+  corrections, open handoff cards), refreshed by the Claude Code Stop hook only when its content
+  changed, so diffs stay quiet.
+- **Machine-local, from the lane (klypix-mcp 1.104.0):** which sessions are live on this PC and
+  which files they hold, the work a stopped session left, and the evidence beside every
+  "keep off this file" note — written at session start and at every Stop by the Claude Code and
+  Codex hooks into `CLAUDE.local.md` at the project root (Claude Code loads it beside
+  `CLAUDE.md`; KLYPIX keeps it out of git through `.git/info/exclude`, never a committed file)
+  and into one section per project of the Codex global instructions file
+  (`~/.codex/AGENTS.override.md` when you have one, else `~/.codex/AGENTS.md`). A project-level
+  `AGENTS.override.md` is never written: Codex loads one file per directory, so it would hide
+  your `AGENTS.md`.
+
+The block is a snapshot and says so: bounded to about 2.4KB, rewritten only when its content
+changed (the time stamp alone never causes a write), with the keep-off evidence kept first when
+the budget bites, and "nothing live" written in words so an older snapshot never stands. It
+holds the same strings the hooks print, so the file and the session context cannot disagree.
+Sections for projects not touched in a day are pruned from the Codex file, at most eight are
+kept, and `uninstall unlink` strips the block (deleting `CLAUDE.local.md` only when nothing else
+is in it). `brain_sync` remains the live source; the block tells the agent to call it.
+
 ## Capture and corrections
 
 `brain_note` accepts structured supporting references and inert verification text:
@@ -1350,7 +1392,10 @@ It strips only KLYPIX's own entries — every other hook and setting in
 `~/.claude/settings.json` stays — backs up each file it edits, and **never deletes a `.klypix`**.
 Removal requires `--yes`. Without it, the command prints the plan and changes nothing;
 there is no interactive confirmation prompt. Run the project-local form in each project you
-want to unlink. A preview exits non-zero while managed files remain.
+want to unlink. A preview exits non-zero while managed files remain. The project-local form also
+strips the live-projection block from `CLAUDE.local.md` (the file goes only when nothing else is
+in it) and this project's section from the Codex global file; the machine-global form strips
+every live section there.
 
 Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or without this package.
 

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.103.0",
+  "version": "1.105.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/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/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-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