klypix-mcp 1.104.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

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', '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.104.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/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/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

package/src/codex-brain-hook.mjs

@@ -91,29 +91,105 @@ function toolInput(input) {
   return candidate && typeof candidate === 'object' ? candidate : {};
 }
 
-function projectRelative(file, projectDir) {
+// A relative path resolves against `baseDir`, the session's working directory
+// (see touchedFiles). A path outside the project returns null, including one
+// on another drive, where path.relative returns an absolute path.
+function projectRelative(file, projectDir, baseDir = projectDir) {
   if (!file) return null;
-  const absolute = path.isAbsolute(file) ? path.normalize(file) : path.resolve(projectDir, file);
-  const relative = path.relative(projectDir, absolute).replace(/\\/g, '/');
+  const absolute = path.isAbsolute(file) ? path.normalize(file) : path.resolve(baseDir, file);
+  const fromProject = path.relative(projectDir, absolute);
+  if (path.isAbsolute(fromProject)) return null;
+  const relative = fromProject.replace(/\\/g, '/');
   if (!relative || relative === '.' || relative === '..' || relative.startsWith('../')) return null;
   return relative;
 }
 
-function touchedFiles(input, projectDir) {
+// File paths an apply_patch body names, read the way Codex's own parser reads
+// them (codex-rs/apply-patch/src/streaming_parser.rs, process_line):
+// - Outside an Update hunk (right after *** Begin Patch, among an Add File's
+//   '+' lines, after a Delete File) a header is matched on the line with
+//   leading and trailing whitespace trimmed, so an indented header there is
+//   still a header and Codex edits that file.
+// - Inside an Update hunk only trailing whitespace is trimmed, so a header
+//   must start at column 0 and an indented one is a context line. Hunk lines
+//   that start with '+', '-' or ' ' are never headers.
+// - The marker includes its one space ("*** Update File: ") and the path is
+//   the rest of the line with nothing more trimmed, as Codex's PathBuf::from
+//   takes it: "*** Update File:a.md" is no header, and a double space names
+//   " a.md". An empty path is no header (trimming removes the space).
+// - "*** Move to: " is read only on the line straight after an Update File
+//   header. A move touches the old path and the new one.
+const APPLY_PATCH_HEADERS = [
+  ['*** Add File: ', 'add'],
+  ['*** Delete File: ', 'delete'],
+  ['*** Update File: ', 'update'],
+];
+const APPLY_PATCH_MOVE = '*** Move to: ';
+
+function applyPatchHeader(line) {
+  for (const [marker, mode] of APPLY_PATCH_HEADERS) {
+    if (line.startsWith(marker) && line.length > marker.length) return { mode, path: line.slice(marker.length) };
+  }
+  return null;
+}
+
+function applyPatchPaths(patch) {
+  const paths = [];
+  let mode = 'started';
+  let moveAllowed = false;
+  for (const line of patch.trim().split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed === '*** Begin Patch') { mode = 'started'; moveAllowed = false; continue; }
+    if (trimmed === '*** End Patch') { mode = 'ended'; moveAllowed = false; continue; }
+    if (mode === 'ended') continue;
+    const candidate = mode === 'update' ? line.trimEnd() : trimmed;
+    const header = applyPatchHeader(candidate);
+    if (header) {
+      paths.push(header.path);
+      mode = header.mode;
+      moveAllowed = header.mode === 'update';
+      continue;
+    }
+    if (mode === 'update' && moveAllowed && candidate.startsWith(APPLY_PATCH_MOVE)
+      && candidate.length > APPLY_PATCH_MOVE.length) {
+      paths.push(candidate.slice(APPLY_PATCH_MOVE.length));
+    }
+    moveAllowed = false;
+  }
+  return paths;
+}
+
+// The apply_patch body. The official Codex hooks docs
+// (https://learn.chatgpt.com/docs/hooks) say: "Bash and apply_patch use
+// tool_input.command". Codex builds both PreToolUse and PostToolUse input as
+// { tool_name: "apply_patch", tool_input: { command: <the raw patch> } }.
+// Before 2026-10-16 only `patch`, `input` and `content` were read, so no real
+// Codex edit was attributed. `command` is read first; those three stay as
+// fallbacks, and a bare-string tool_input is taken as the patch itself.
+function applyPatchBody(input) {
+  const args = toolInput(input);
+  const raw = input.tool_input ?? input.toolInput ?? input.tool?.input;
+  const command = Array.isArray(args.command) ? args.command : [args.command];
+  return [...command, args.patch, args.input, args.content, raw]
+    .find((value) => typeof value === 'string' && value.includes('*** ')) || '';
+}
+
+// Project-relative paths this tool call names. `cwd` is the session's working
+// directory: Codex applies a patch's relative paths from there, and
+// findProjectBrain walks UP from it, so the brain's folder can be an ancestor.
+export function touchedFiles(input, projectDir,
+  cwd = typeof input?.cwd === 'string' && input.cwd ? path.resolve(input.cwd) : projectDir) {
   const name = toolName(input);
   const args = toolInput(input);
   const candidates = [];
   for (const key of ['path', 'file_path', 'filePath', 'target_file', 'targetFile']) {
     if (typeof args[key] === 'string') candidates.push(args[key]);
   }
-  const patch = [args.patch, args.input, args.content]
-    .find((value) => typeof value === 'string' && value.includes('*** '));
+  const patch = applyPatchBody(input);
   if (patch && /apply_patch|Edit|Write/i.test(name)) {
-    for (const match of patch.matchAll(/^\*\*\* (?:Add|Update|Delete) File:\s*(.+)$/gm)) {
-      candidates.push(match[1].trim());
-    }
+    candidates.push(...applyPatchPaths(patch));
   }
-  return [...new Set(candidates.map((file) => projectRelative(file, projectDir)).filter(Boolean))];
+  return [...new Set(candidates.map((file) => projectRelative(file, projectDir, cwd)).filter(Boolean))];
 }
 
 function ownBrainMessageText(input) {
@@ -262,7 +338,7 @@ function formatConflictWarning(conflicts, event, sessions = []) {
 // klypix-format predates guards degrades to silence, never a throw. This lane
 // only ever WARNS: block-severity guards are named as such so the model treats
 // them as a hard stop, but no mechanism here denies anything.
-async function guardWarnings(projectDir, brainPath, input) {
+async function guardWarnings(projectDir, brainPath, input, cwd) {
   try {
     if (typeof brainFormat.evaluateGuards !== 'function'
       || typeof brainFormat.ensureGuardSidecar !== 'function') return '';
@@ -273,7 +349,7 @@ async function guardWarnings(projectDir, brainPath, input) {
     const ensured = await brainFormat.ensureGuardSidecar(brainPath);
     const guards = Array.isArray(ensured.guards) ? ensured.guards : [];
     if (!guards.length) return '';
-    const files = touchedFiles(input, projectDir);
+    const files = touchedFiles(input, projectDir, cwd);
     const cmd = toolInput(input).command;
     const needWt = guards.some((g) => g?.when?.multiWorktree);
     const fired = brainFormat.evaluateGuards(guards, {
@@ -508,8 +584,16 @@ async function main() {
   // while marking them observed, and skips any path the session's DECLARED
   // scope (brain_sync) already covers.
   const observed = event === 'PreToolUse' || event === 'PostToolUse'
-    ? touchedFiles(input, projectDir)
+    ? touchedFiles(input, projectDir, cwd)
     : undefined;
+  // Whose is this? (1.104.0): remember the bytes Codex's edits left, so a Claude
+  // session's sweeping git command can name this session as the owner.
+  if (event === 'PostToolUse' && Array.isArray(observed) && observed.length) {
+    try {
+      const whose = await import(new URL('./whose.mjs', import.meta.url).href);
+      await whose.recordEdits({ brainPath, sid: sessionId, client: 'codex', cwd: projectDir, files: observed });
+    } catch { /* attribution is best-effort */ }
+  }
   const files = humanTurn ? [] : undefined;
   const workPatch = codexWorkPatch({ event, humanTurn, prompt, input }) || {};
   // Where it works (1.103.0): the directory a tool call ran in (Codex's exec
@@ -653,7 +737,7 @@ async function main() {
       // call — Codex hook output is `continue: true` by design — so a matching
       // guard renders as a warning; a block-severity guard says it should be
       // treated as a hard stop, without claiming a mechanism this lane lacks.
-      ...(event === 'PreToolUse' ? [await guardWarnings(projectDir, brainPath, input)] : []),
+      ...(event === 'PreToolUse' ? [await guardWarnings(projectDir, brainPath, input, cwd)] : []),
       stampReceivedMessages(messages, Date.now(), undefined, sessionId),
     ], event);
     return;

package/src/global-brain-hook.mjs

@@ -6262,8 +6262,62 @@ async function registerBrain() {
     } catch { /* registry is best-effort */ }
 }
 
+// "Whose is this?" (1.104.0): a risky git command that would sweep, discard or
+// stash ANOTHER session's uncommitted work gets deny / ask / context, and edits
+// are recorded so ownership is known. Runs before the brain-at-cwd check because
+// it finds the brain by walking up (an agent may have cd'd into a subfolder).
+// Cheap gates first: only edit tools (--live) or a command that mentions git
+// (--guard) pay the dynamic import. Never throws.
+const WHOSE_EDIT_TOOLS = new Set(['Edit', 'Write', 'MultiEdit', 'NotebookEdit', 'edit_file', 'write_file']);
+async function whoseStep(isGuard) {
+    try {
+        const input = readHookInput();
+        const tool = String(input.tool_name || '');
+        if (!isGuard) {
+            if (!WHOSE_EDIT_TOOLS.has(tool)) return null;
+            const w = await import(new URL('./whose.mjs', import.meta.url).href);
+            await w.recordFromClaudeHook(input);
+            return null;
+        }
+        if (tool !== 'Bash' && tool !== 'PowerShell') return null;
+        const cmd = input.tool_input && input.tool_input.command;
+        if (typeof cmd !== 'string' || !/\bgit|\bgh\b/i.test(cmd)) return null;
+        const w = await import(new URL('./whose.mjs', import.meta.url).href);
+        let r = await w.decide(input);
+        if (r && w.whoseMode() === 'shadow') r = w.shadowOf(r);
+        return r;
+    } catch { return null; }
+}
+function emitWhose(r) {
+    if (!r || !r.text) return;
+    const out = r.decision === 'deny' || r.decision === 'ask'
+        ? { hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: r.decision, permissionDecisionReason: r.text } }
+        : { hookSpecificOutput: { hookEventName: 'PreToolUse', additionalContext: r.text } };
+    try { fs.writeSync(1, JSON.stringify(out)); } catch { /* stdout gone */ }
+}
+
+// --end (SessionEnd, 1.105.0): the session is over — remove its live rows and
+// tombstone it through the engine's own endSession (the same call Codex's
+// SessionEnd makes), so peers stop reading a dead session as working. Walks up
+// for the brain like Whose does. Never throws.
+async function endStep() {
+    try {
+        const input = readHookInput();
+        const sid = String(input.session_id || '');
+        if (!sid) return;
+        const ap = await import(new URL('./agent-presence.mjs', import.meta.url).href);
+        const brainPath = ap.findProjectBrain(input.cwd || process.cwd());
+        if (brainPath) ap.endSession({ brainPath, id: sid });
+    } catch { /* never fail a session's exit */ }
+}
+
 async function main() {
-    if (!fs.existsSync(BRAIN)) return;                  // not a brain project → instant no-op
+    if (process.argv.includes('--end')) { await endStep(); return; }
+    const isLive = process.argv.includes('--live');
+    const isGuard = process.argv.includes('--guard');
+    const whose = (isLive || isGuard) ? await whoseStep(isGuard) : null;
+    if (whose && (whose.decision === 'deny' || whose.decision === 'ask')) { emitWhose(whose); return; }
+    if (!fs.existsSync(BRAIN)) { if (whose) emitWhose(whose); return; }   // not a brain project → instant no-op
     // --live (PostToolUse) is the cheapest mode: pure payload string-work + at most
     // one tiny locked append. It must NOT pay the lazy klypix-format import, so it
     // runs BEFORE everything else and returns. (Fires on Bash|PowerShell|Edit|Write.)
@@ -6271,7 +6325,15 @@ async function main() {
     // --guard (PreToolUse) is the second fast path: stat + sidecar read on the
     // common case; it lazy-imports the lib itself only when a compiled guard's
     // tool pattern could match this call. Runs before the unconditional import.
-    if (process.argv.includes('--guard')) { await guardCheck(); return; }
+    if (process.argv.includes('--guard')) {
+        // A brain guard card's own decision wins; Whose context rides only when it said nothing.
+        let wrote = false;
+        const orig = process.stdout.write.bind(process.stdout);
+        process.stdout.write = (...a) => { wrote = true; return orig(...a); };
+        try { await guardCheck(); } finally { process.stdout.write = orig; }
+        if (!wrote && whose) emitWhose(whose);
+        return;
+    }
     const lib = await import('./klypix-format.mjs');    // lazy: only when a brain exists
     // Per-prompt retrieval runs on EVERY prompt — skip the registry write and
     // go straight to the (mtime-cached) ranked lookup to keep it cheap.

package/src/mcp-presence.mjs

@@ -69,7 +69,7 @@ export const KLYPIX_MCP_INSTRUCTIONS = [
   'Use its active-task, message, and file-overlap report to coordinate concurrent work.',
   'A coordination note is not consumed merely because it was offered: after a later independent KLYPIX action acknowledges the offer, call brain_message_receipt with its exact message id and offer token only when you actually incorporated it into your work. If you do not, a further independent action auto-consumes the note without a receipt — which records activity, not uptake — so the sender is told it was auto-consumed rather than acted on. Sending an explicit receipt is what makes your uptake visible to them.',
   'Never make the human carry a message between agents: if you would otherwise ask the human to relay or paste something to another agent session on this project — live, idle, or recently closed — send it with brain_message addressed to that session id instead, and tell the human it was sent or queued; a closed session receives a directed note the moment it next starts. If the human wants a queued note handled sooner, offer brain_reopen: KLYPIX asks the human with a Reopen / Not now prompt and reopens that session only on yes. Hand the human the text only if brain_message refuses.',
-  'When you stop before the work is done — the human asks for a handoff, your context or usage limit is near, the day ends, you are blocked or switching tool — call brain_handoff {action:"write"} with the task, what is done, what is NEXT in order, the files and how to verify: it is a card in the brain the human can see, and the next session on this project (any agent) sees it at its first brain_sync and takes it with {action:"take"}; never ask the human to paste a summary into the next session. KLYPIX also records every session\'s last reply, files and commits automatically, so brain_sync may list "unfinished work" another session left: if the human asks you to continue it, take it with brain_handoff {action:"take", session} and finish with {action:"done"}; that list is history, not a lock — a stopped session holds no claim on its files. When a session stopped without writing a card, KLYPIX drafts one from that record at the next brain_sync (its card says "Drafted: by KLYPIX"): treat it as a lead, not a verified state — confirm with git before relying on it. A note that asks agents to keep off a file (whatever its wording: do not touch, hands off, WIP, someone else has it) can outlive its work: before obeying one, call brain_sync with that file in files — KLYPIX reports local sessions, branches and registered worktrees. Decide which kind of note it is: a temporary reservation for someone\'s in-flight change ends when that work ends; a permanent rule (generated file, policy, legal or human restriction) always holds. If a temporary reservation\'s work has ended and the task needs the file, change it there and tell the human (never delete the note yourself). Incomplete checks say UNKNOWN.',
+  'When you stop before the work is done — the human asks for a handoff, your context or usage limit is near, the day ends, you are blocked or switching tool — call brain_handoff {action:"write"} with the task, what is done, what is NEXT in order, the files and how to verify: it is a card in the brain the human can see, and the next session on this project (any agent) sees it at its first brain_sync and takes it with {action:"take"}; never ask the human to paste a summary into the next session. KLYPIX also records every session\'s last reply, files and commits automatically, so brain_sync may list "unfinished work" another session left: if the human asks you to continue it, take it with brain_handoff {action:"take", session} and finish with {action:"done"}; that list is history, not a lock — a stopped session holds no claim on its files. A LIVE session\'s uncommitted edits are its work in progress: never sweep, discard or stash them; 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. When a session stopped without writing a card, KLYPIX drafts one from that record at the next brain_sync (its card says "Drafted: by KLYPIX"): treat it as a lead, not a verified state — confirm with git before relying on it. A note that asks agents to keep off a file (whatever its wording: do not touch, hands off, WIP, someone else has it) can outlive its work: before obeying one, call brain_sync with that file in files — KLYPIX reports local sessions, branches and registered worktrees. Decide which kind of note it is: a temporary reservation for someone\'s in-flight change ends when that work ends; a permanent rule (generated file, policy, legal or human restriction) always holds. If a temporary reservation\'s work has ended and the task needs the file, change it there and tell the human (never delete the note yourself). Incomplete checks say UNKNOWN.',
   'Call brain_sync again when your file scope materially changes, and with phase "complete" before your final response.',
   'When a task publishes a quantified or otherwise machine-checkable claim, include its validated result manifest in the completion sync; conflicting or incomparable peer results retain the task scope until reconciled.',
   'A session preparing a RELEASE of the project should declare it by adding releaseIntent {version, ref} to brain_sync: the first declarer takes an exclusive lease every peer sees, and a second declarer gets a hard conflict naming the holder.',