klypix-mcp 1.90.0 → 1.91.0

package/README.md

@@ -119,7 +119,7 @@ npx klypix-mcp conformance
 
 It runs in a temporary fixture and touches nothing else. It checks tool discovery, task memory,
 truthful peer reporting, overlap surfacing, proactive logging, and in-band delivery of a peer note.
-It verifies 15 required coordination behaviours — not the 22 tools, and not the retrieval engine.
+It verifies 15 required coordination behaviours — not the 23 tools, and not the retrieval engine.
 
 ---
 
@@ -142,7 +142,7 @@ git repo, and then **proves the result** before it exits:
   editors   Claude Code · Cursor · Codex · Gemini CLI · Antigravity · VS Code
   wired     9 file(s) · 9 updated   (skipped 5 for tools you don't have)
   git       .klypix merge driver registered
-  verified  ✓ 22 tools reachable via .mcp.json (892ms)
+  verified  ✓ 23 tools reachable via .mcp.json (892ms)
 ```
 
 That last line is the point. MCP config fails **silently** — a wrong entry means the server never
@@ -451,8 +451,9 @@ KLYPIX has identified before that is **not on the lane now** (closed, or quiet)
 directed note the moment it next acts — a directed note is kept 7 days, and the sender is told it
 is *queued*, not delivered. That is what stops the human from being the courier between two
 agents: the standing rule every host receives is that a message it would otherwise ask the person
-to relay or paste is sent this way instead. Nothing here starts or wakes a session — the note
-waits until a person opens it. A supported
+to relay or paste is sent this way instead. Nothing here starts or wakes a session on its own — the
+note waits until a person opens it, and the person decides when that is (see *Reopen on your OK*
+below). A supported
 KLYPIX action offers the note in model-visible context; the next independent supported action
 replays it and records an acknowledgement. That acknowledgement proves only that a later action followed the
 offer — never that a person read it or that an agent acted on it. The note keeps replaying until the
@@ -463,6 +464,30 @@ instead of silently looking delivered. The send-time audience is fixed, unresolv
 fail closed, the core lane is machine-local, a note to every session expires after 24 hours and a
 directed note after 7 days, and notes are never written into the brain.
 
+### Reopen on your OK
+
+A note to a session that has closed would otherwise wait until someone happens to open that
+session again. When the person wants it handled sooner, the sending agent calls `brain_reopen`, and
+**KLYPIX asks the person** — an in-chat *Reopen / Not now* prompt in apps that support MCP
+elicitation (Claude Code, Codex), otherwise a small native dialog. Only on *Reopen* does KLYPIX
+open that Claude Code or Codex session in a **new, visible terminal**, in the folder it worked in,
+with the host's own resume command (`claude --resume <id>`, `codex resume <id>`); the session
+receives the waiting note at its first action and the sender sees the receipt as usual.
+
+- The person decides, never a model: the answer comes from the app's prompt or KLYPIX's own
+  dialog, which no agent can click. With neither available, nothing opens and the person is given
+  the command to run.
+- Only a session with a note **addressed to it** is reopened — KLYPIX reopens a conversation so a
+  note can reach it; it does not start, route or supervise agents.
+- The first prompt the reopened session gets is fixed text that tells it to collect the note; the
+  note itself arrives through the labelled message channel as information from another session,
+  never typed in as if the person had said it. The sender's session identity never leaks into it.
+- *Not now* is remembered: the same session is not offered again for a while, and a double click
+  cannot open two windows.
+- From a terminal: `npx klypix-mcp sessions` lists this project's closed sessions and the notes
+  waiting for them; `npx klypix-mcp sessions reopen <id>` reopens one (`--quiet` lets it wait for
+  you instead of starting on the note).
+
 Durable handoffs go in the brain itself — decisions, findings, open questions and skills captured
 as cards, each stamped with the agent that wrote it.
 
@@ -637,7 +662,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 
 ---
 
-## The 22 verbs
+## The 23 verbs
 
 | Tool | What it does |
 |---|---|
@@ -651,6 +676,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `brain_doctor` | Self-diagnosis: version, core/enhanced host adapters, active sessions, tool count, projection drift |
 | `brain_message` | Session-to-session coordination notes — to a live session, or queued for one that is not running until it next starts — with a fixed send-time audience and per-recipient pending / offer / acknowledgement / consumption / failure receipts (a directed note is kept 7 days, a broadcast 24h; never written into the brain) |
 | `brain_message_receipt` | Explicitly record model-side consumption using the exact message id and per-recipient offer token; acknowledgement alone never consumes a note |
+| `brain_reopen` | Reopen a closed Claude Code or Codex session so a note waiting for it gets there now — only after the person answers *Reopen* in an in-chat prompt or KLYPIX's own dialog; opens a new, visible terminal in that session's folder with the host's resume command |
 | `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing, and optional result-manifest reconciliation |
 | `brain_connect` | Find and draw related-but-unlinked cards |
 | `project_map_context` | Read-only, bounded code-graph evidence beside correction-aware brain context, with exact-path review proposals; external artifacts (e.g. Graphify) are supported but never installed or run locally |

package/bin/klypix-install.mjs

@@ -212,6 +212,33 @@ function renameSyncWithBackoff(from, to) {
     }
 }
 
+// The live install as its own `.mcp-runtime.json` describes it, every listed
+// file read and hashed now: { raw, entries: [[name, bytes]] }; { absent: true }
+// with no manifest (an install from before the supervisor); { error } when a
+// listed file is missing or differs — a half-applied install, two versions'
+// files side by side. Only the flat layout (bare file names) is accepted.
+function readVerifiedLiveRuntime(dir) {
+    const manifestPath = path.join(dir, '.mcp-runtime.json');
+    let raw;
+    try { raw = fs.readFileSync(manifestPath, 'utf8'); }
+    catch (e) { return e?.code === 'ENOENT' ? { absent: true } : { error: `manifest unreadable (${e?.code || e?.message})` }; }
+    let manifest;
+    try { manifest = JSON.parse(raw); } catch { return { error: 'manifest is not valid JSON' }; }
+    const files = manifest && typeof manifest.files === 'object' && !Array.isArray(manifest.files) ? manifest.files : null;
+    if (manifest?.protocol !== 1 || !files || !Object.prototype.hasOwnProperty.call(files, String(manifest.worker || ''))) {
+        return { error: 'manifest does not hash its worker' };
+    }
+    const entries = [];
+    for (const [name, expected] of Object.entries(files)) {
+        if (path.basename(name) !== name) return { error: `unexpected path ${name}` };
+        let bytes;
+        try { bytes = fs.readFileSync(path.join(dir, name)); } catch { return { error: `${name} is missing` }; }
+        if (crypto.createHash('sha256').update(bytes).digest('hex') !== expected) return { error: `${name} differs from its hash` };
+        entries.push([name, bytes]);
+    }
+    return { raw, entries };
+}
+
 function migrateProjectMcpConfig() {
     try {
         const file = path.join(process.cwd(), '.mcp.json');
@@ -416,10 +443,37 @@ try {
         const s = path.join(BIN, src); if (exists(s)) staged.push({ dst, content: flatten(fs.readFileSync(s, 'utf8')) });
     }
     for (const st of staged) fs.writeFileSync(path.join(BRAIN_DIR, st.dst + '.klypix-new'), st.content);
+    // .prev is what a supervisor boots while an install is half-applied (a
+    // fresh connection, a wake, a crash recovery), so it must be ONE version,
+    // whole (K1-PREV-UNVERIFIED, 2026-10-03 review). It used to be refreshed from
+    // whatever the live directory held: a retry after an install that stopped
+    // mid-rename (the updater's own, 15 min later) copied the MIXED set over the
+    // last complete snapshot. Now the live files are snapshotted only when they
+    // verify against their own manifest — the very bytes that were hashed are
+    // written — and that manifest is copied in LAST: it is what the supervisor
+    // verifies before it boots .prev (prevSnapshotAt). A live directory that
+    // fails its manifest leaves the last complete snapshot where it is.
     try {
-        const prevDir = path.join(BRAIN_DIR, '.prev'); fs.mkdirSync(prevDir, { recursive: true });
-        for (const st of staged) { const live = path.join(BRAIN_DIR, st.dst); if (exists(live)) fs.copyFileSync(live, path.join(prevDir, st.dst)); }
-    } catch { /* .prev rollback snapshot is best-effort */ }
+        const prevDir = path.join(BRAIN_DIR, '.prev');
+        const prevManifest = path.join(prevDir, '.mcp-runtime.json');
+        const live = readVerifiedLiveRuntime(BRAIN_DIR);
+        if (live.entries) {
+            fs.mkdirSync(prevDir, { recursive: true });
+            fs.rmSync(prevManifest, { force: true });   // nothing vouches for .prev while it changes
+            for (const [name, bytes] of live.entries) fs.writeFileSync(path.join(prevDir, name), bytes);
+            fs.writeFileSync(prevManifest + '.klypix-new', live.raw);
+            renameSyncWithBackoff(prevManifest + '.klypix-new', prevManifest);
+        } else if (live.absent) {
+            // No manifest to verify against (an install from before the
+            // supervisor): a plain copy for a manual rollback, which no
+            // supervisor boots — nothing vouches for it.
+            fs.mkdirSync(prevDir, { recursive: true });
+            fs.rmSync(prevManifest, { force: true });
+            for (const st of staged) { const file = path.join(BRAIN_DIR, st.dst); if (exists(file)) fs.copyFileSync(file, path.join(prevDir, st.dst)); }
+        } else {
+            console.log(`• .prev kept: the live core files do not match their manifest (${live.error}) — the last complete snapshot stays the rollback copy`);
+        }
+    } catch { /* .prev rollback snapshot is best-effort; an unfinished one has no manifest */ }
     const renameOrder = staged.slice().sort((a, b) => (a.dst === 'global-brain-hook.mjs' ? 1 : 0) - (b.dst === 'global-brain-hook.mjs' ? 1 : 0));
     let n = 0;
     for (const st of renameOrder) { renameSyncWithBackoff(path.join(BRAIN_DIR, st.dst + '.klypix-new'), path.join(BRAIN_DIR, st.dst)); n++; }

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']);
+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 USAGE = [
   `klypix-mcp ${PKG_VERSION} — shared project brain + MCP coordination server.`,
@@ -29,6 +29,8 @@ const USAGE = [
   '          [--no-project] [--json]     brain, config for the editors you actually have, merge driver, verified',
   '  link [dir] [--check]                project this project\'s 14 managed agent config files (--check audits, writes nothing, exits 1 on drift)',
   '  doctor [--npm] [--all] [--json]     read-only self-check; exits 1 on drift',
+  '  sessions [--json]                   closed agent sessions of this project and the notes waiting for them',
+  '  sessions reopen <id> [--quiet]      reopen one (Claude Code / Codex) in a new terminal so its waiting notes reach it',
   '  runtime [--json] [--watch seconds]  passive MCP process/RAM attribution; never terminates a process',
   '  conformance [--json]                launch two real MCP clients against this build',
   '  bench [--quick] [--json] [--out F]  reproducible benchmark: concurrent-write safety, latency, soak, crash',

package/bin/klypix-sessions.mjs

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+// klypix-sessions — `npx klypix-mcp sessions`. The human side of "reopen on your
+// OK": the recent agent sessions of THIS project that are not running, which of
+// them have notes waiting, and a one-word way to bring one back so its notes
+// reach it.
+//
+//   npx klypix-mcp sessions                       # list (this project)
+//   npx klypix-mcp sessions --json                # the same, machine-readable
+//   npx klypix-mcp sessions reopen <id>           # reopen it in a new terminal; it starts on the note
+//   npx klypix-mcp sessions reopen <id> --quiet   # reopen it, but let it wait for you
+//   npx klypix-mcp sessions ... --project <dir> | --dry-run
+//
+// Typing `reopen` IS the human's yes, so there is no second prompt here. Only a
+// Claude Code or Codex session that has a note waiting can be reopened — KLYPIX
+// reopens a conversation so a note can reach it; it does not start agents.
+import fs from 'fs';
+import path from 'path';
+import {
+  buildReopenLaunch,
+  findProjectBrain,
+  launchReopen,
+  listKnownSessions,
+  recordSessionReopen,
+  reopenCandidate,
+  REOPEN_NUDGE,
+} from '../src/agent-presence.mjs';
+
+const isDir = (p) => { try { return fs.statSync(p).isDirectory(); } catch { return false; } };
+const raw = process.argv.slice(2);
+const argv = (raw[0] === 'sessions' && !isDir(path.resolve(raw[0]))) ? raw.slice(1) : raw;
+const has = (flag) => argv.includes(flag);
+const val = (flag) => { const i = argv.indexOf(flag); return i >= 0 ? argv[i + 1] : undefined; };
+const projectDir = path.resolve(val('--project') || process.cwd());
+const brainPath = findProjectBrain(projectDir);
+const word = (client) => {
+  const key = String(client || '').toLowerCase();
+  if (key === 'claude-code' || key === 'claude') return 'Claude Code';
+  if (key === 'codex') return 'Codex';
+  return key ? key.replace(/(^|[-_ ])([a-z])/g, (_m, p, c) => `${p}${c.toUpperCase()}`) : 'Unknown';
+};
+
+if (!brainPath) {
+  console.error(`No project brain (brain.klypix) at or above ${projectDir} — run this in the project folder, or pass --project <dir>.`);
+  process.exit(1);
+}
+
+if (argv[0] === 'reopen') {
+  const target = argv[1] && !argv[1].startsWith('--') ? argv[1] : '';
+  if (!target) {
+    console.error('Usage: npx klypix-mcp sessions reopen <session id or 8+ character prefix> [--quiet] [--dry-run]');
+    process.exit(2);
+  }
+  const candidate = reopenCandidate({ brainPath, target, humanInitiated: true });
+  if (!candidate.ok) {
+    const who = candidate.entry ? `${word(candidate.entry.client)} ${String(candidate.entry.id).slice(0, 8)}` : `"${target}"`;
+    const why = {
+      'unknown-session': `no session KLYPIX remembers in this project matches ${who}`,
+      'ambiguous-session': `${who} matches more than one session — use more characters of its id`,
+      live: `${who} is running${candidate.statusLabel ? ` (${candidate.statusLabel})` : ''}; it gets its notes at its next action`,
+      'unsupported-client': `${who} cannot be reopened by KLYPIX (only Claude Code and Codex have a verified resume-by-id)`,
+      'unsafe-id': `${who} has an id that cannot be passed to a terminal safely`,
+      'no-waiting-note': `no note is waiting for ${who} — KLYPIX reopens a session only so a note can reach it`,
+      'just-reopened': `${who} was reopened moments ago — look for its terminal window`,
+    }[candidate.reason] || `${who} cannot be reopened (${candidate.reason})`;
+    console.error(`Not reopened: ${why}.`);
+    process.exit(1);
+  }
+  const plan = buildReopenLaunch({ hostKey: candidate.hostKey, sessionId: candidate.entry.id, cwd: candidate.cwd, prompt: has('--quiet') ? '' : REOPEN_NUDGE });
+  const launch = launchReopen(plan, { env: has('--dry-run') ? { ...process.env, KLYPIX_REOPEN_LAUNCH: 'dry-run' } : process.env });
+  const label = `${candidate.hostLabel} ${candidate.entry.id.slice(0, 8)}`;
+  if (launch.dryRun) {
+    console.log(`Dry run: would reopen ${label} via ${plan.method} in ${candidate.cwd} with ${candidate.command}${has('--quiet') ? '' : ' (and let it act on the note)'}.`);
+    process.exit(0);
+  }
+  if (!launch.launched) {
+    recordSessionReopen({ brainPath, sessionId: candidate.entry.id, outcome: 'manual', via: 'cli', method: plan.method || null });
+    console.error(`Could not open a terminal here (${plan.reason || launch.reason || 'unknown'}). Run it yourself:\n  cd ${JSON.stringify(candidate.cwd)}\n  ${candidate.command}`);
+    process.exit(1);
+  }
+  recordSessionReopen({ brainPath, sessionId: candidate.entry.id, outcome: 'reopened', via: 'cli', method: plan.method });
+  const notes = candidate.waitingNotes.length;
+  console.log(`🔓 Reopened ${label} in a new terminal (${candidate.cwd}) with ${candidate.command}${has('--quiet') ? ' — it waits for you' : ' — it starts on the note'}. ${notes === 1 ? 'Its waiting note is' : `Its ${notes} waiting notes are`} delivered at its first action.`);
+  process.exit(0);
+}
+
+const now = Date.now();
+const rows = listKnownSessions({ brainPath, now }).filter((row) => !row.live);
+if (has('--json')) {
+  console.log(JSON.stringify({ project: path.dirname(brainPath), brain: brainPath, sessions: rows.map((row) => ({
+    id: row.id, client: row.client, intent: row.intent, status: row.status, lastSeen: row.lastSeen,
+    endedAt: row.endedAt || null, waitingNotes: row.waitingDirectedNotes, waitingBroadcasts: row.waitingNotes - row.waitingDirectedNotes,
+    cwd: row.cwd || null, reopenable: Boolean(row.resumeCommand) && row.waitingDirectedNotes > 0, resumeCommand: row.resumeCommand || null,
+  })) }, null, 2));
+  process.exit(0);
+}
+if (!rows.length) {
+  console.log('No recent sessions of this project are closed. (Live sessions: npx klypix-mcp doctor.)');
+  process.exit(0);
+}
+const waiting = rows.filter((row) => row.waitingDirectedNotes > 0);
+console.log(`Recent sessions of ${path.basename(path.dirname(brainPath))} that are not running (${rows.length}${waiting.length ? `, ${waiting.length} with notes waiting` : ''}):`);
+for (const row of rows.slice(0, 20)) {
+  const n = row.waitingDirectedNotes;
+  const note = n ? ` · 📬 ${n} note${n === 1 ? '' : 's'} waiting` : '';
+  console.log(`  ${row.id.slice(0, 8)}  ${word(row.client).padEnd(11)} ${String(row.status).padEnd(18)}${note}${row.intent ? `  “${row.intent.slice(0, 70)}”` : ''}`);
+}
+const first = waiting.find((row) => row.resumeCommand);
+if (first) console.log(`\nReopen one so its notes reach it:  npx klypix-mcp sessions reopen ${first.id.slice(0, 8)}${waiting.length > 1 ? '   (any id above with notes waiting)' : ''}`);
+process.exit(0);

package/bin/klypix-worker.mjs

@@ -33,7 +33,18 @@ import {
 import { compareProjectGraphResults, projectGraphContextMarkdown, queryProjectGraph, suggestProjectGraphBrainLinks, scanNativeProjectMap, checkBrainDrift, brainDriftMarkdown } from '../src/project-graph.mjs';
 import { auditProject, compactAgentsBrief, linkProject, mcpServerEntry } from '../src/agent-rules.mjs';
 import { createMcpPresence, KLYPIX_MCP_INSTRUCTIONS, normalizeMcpClient } from '../src/mcp-presence.mjs';
-import { consumeMessageReceipt, findProjectBrain, listActiveSessions } from '../src/agent-presence.mjs';
+import {
+  buildReopenLaunch,
+  consumeMessageReceipt,
+  findProjectBrain,
+  launchReopen,
+  listActiveSessions,
+  nativeReopenDialog,
+  recordSessionReopen,
+  reopenCandidate,
+  reopenQuestion,
+  REOPEN_NUDGE,
+} from '../src/agent-presence.mjs';
 import { collectRepoState, commitsInRange, makeContainmentProbe } from '../src/repo-state.mjs';
 import {
   reconcileRegisteredProjects,
@@ -114,6 +125,11 @@ await runVerb('link', './klypix-link.mjs');
 // projection in sync? One verdict, one reconcile block. Exits 1 on drift (CI gate).
 await runVerb('doctor', './klypix-doctor.mjs');
 
+// `npx klypix-mcp sessions` — this project's closed agent sessions and the notes
+// waiting for them; `sessions reopen <id>` reopens one in a new terminal so its
+// notes reach it (typing the verb is the human's yes). Runs before server setup.
+await runVerb('sessions', './klypix-sessions.mjs');
+
 // `npx klypix-mcp conformance` — launch two real, isolated MCP clients against
 // this exact installed server and verify task memory, truthful peers, blocking
 // overlap detection, proactive logging, and guaranteed next-action delivery.
@@ -751,7 +767,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. 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. 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.'),
@@ -827,6 +843,143 @@ server.registerTool('brain_message_receipt', {
   };
 });
 
+// ── brain_reopen (1.91.0): reopen a closed session so a waiting note reaches it
+// The agent proposes; the HUMAN decides. Consent is collected by KLYPIX itself,
+// never by the model: an in-chat prompt when the client supports MCP
+// elicitation, otherwise a native "Reopen / Not now" dialog raised by this
+// process, otherwise nothing opens and the human is given the command. The
+// session opens in a new, visible terminal with its host's own resume command.
+const REOPEN_ELICIT_TIMEOUT_MS = 110_000;
+const REOPEN_CHOICE_ACT = 'Reopen it and let it act on the note';
+const REOPEN_CHOICE_QUIET = 'Reopen it — I will prompt it myself';
+const REOPEN_CHOICE_WAIT = 'Not now — let the note wait';
+
+async function askHumanToReopen({ question, start, extra }) {
+  let caps = {};
+  try { caps = server.server.getClientCapabilities?.() || {}; } catch { /* older SDK */ }
+  if (caps.elicitation) {
+    const choices = start === false ? [REOPEN_CHOICE_QUIET, REOPEN_CHOICE_WAIT] : [REOPEN_CHOICE_ACT, REOPEN_CHOICE_QUIET, REOPEN_CHOICE_WAIT];
+    try {
+      const answer = await server.server.elicitInput({
+        mode: 'form',
+        message: question,
+        requestedSchema: {
+          type: 'object',
+          properties: { choice: { type: 'string', title: 'Reopen this session now?', enum: choices, default: choices[0] } },
+          required: ['choice'],
+        },
+      }, { timeout: REOPEN_ELICIT_TIMEOUT_MS, ...(extra?.requestId !== undefined ? { relatedRequestId: extra.requestId } : {}) });
+      if (answer?.action === 'accept') {
+        const choice = String(answer.content?.choice || choices[0]);
+        if (choice === REOPEN_CHOICE_WAIT) return { via: 'in-chat', answer: 'wait' };
+        return { via: 'in-chat', answer: 'reopen', start: choice === REOPEN_CHOICE_ACT };
+      }
+      if (answer?.action === 'decline') return { via: 'in-chat', answer: 'wait' };
+      return { via: 'in-chat', answer: 'no-answer' };
+    } catch (error) {
+      // An unanswered in-chat prompt is an answer ("not now, not here"): never
+      // follow it with a second prompt in another window.
+      if (/time(d)? ?out/i.test(String(error?.message || ''))) return { via: 'in-chat', answer: 'no-answer' };
+      log(`brain_reopen: in-chat prompt unavailable (${String(error?.message || error).slice(0, 120)}); using the native dialog`);
+    }
+  }
+  const native = await nativeReopenDialog({
+    message: `${question}\n\nYes = reopen it${start === false ? '' : ' and let it act on the note'}. No = not now.`,
+    timeoutS: 50,
+  });
+  if (native === 'reopen') return { via: 'dialog', answer: 'reopen', start: start !== false };
+  if (native === 'wait') return { via: 'dialog', answer: 'wait' };
+  if (native === 'timeout') return { via: 'dialog', answer: 'no-answer' };
+  return { via: null, answer: 'unavailable' };
+}
+
+const reopenClientWord = (client) => {
+  const key = String(client || '').toLowerCase();
+  if (key === 'claude-code' || key === 'claude') return 'Claude Code';
+  if (key === 'codex') return 'Codex';
+  return key ? key.replace(/(^|[-_ ])([a-z])/g, (_m, p, c) => `${p}${c.toUpperCase()}`) : 'Another';
+};
+
+server.registerTool('brain_reopen', {
+  title: 'Reopen a closed agent session so a waiting note reaches it — only after the human says yes',
+  description: 'A note to a session that has CLOSED waits up to 7 days and is delivered only when that session is next used. When the human wants it handled sooner, call this: KLYPIX asks the HUMAN (an in-chat Reopen / Not now prompt where the app supports it, otherwise a native dialog) and, only on yes, reopens that Claude Code or Codex session in a new, visible terminal in its own folder with the host\'s resume command; the reopened session receives the waiting note(s) at its first action. Nothing opens without the human\'s answer, nothing runs headless, and only a session with a note waiting can be reopened. Do not call it again for the same session after the human chose "Not now" unless they bring it up. Machine-local.',
+  annotations: {
+    destructiveHint: false,
+    idempotentHint: false,
+    openWorldHint: true,
+  },
+  inputSchema: {
+    session: z.string().min(1).max(160).describe('The session to reopen: its id, or a unique prefix of at least 8 characters, as shown in the queued-note reply, brain_sync peers, or brain_doctor. It must be a Claude Code or Codex session that is not running and has a note waiting.'),
+    start: z.boolean().optional().describe('true (default): the reopened session starts on the note right away. false: it opens and waits for the human to prompt it.'),
+    project: z.string().optional().describe('Absolute project root containing brain.klypix. Defaults to this connection\'s project.'),
+  },
+}, async ({ session, start, project }, extra) => {
+  const brainPath = project ? findProjectBrain(path.resolve(project)) : (mcpPresence.brainPath || findProjectBrain(mcpPresence.vault));
+  const identity = extra?.klypixRequestIdentity || {};
+  const me = String(identity.sessionId || mcpPresence.id || '');
+  const senderLabel = `${reopenClientWord(identity.clientInfo?.client)} session ${me.slice(0, 8)}`.trim();
+  const now = Date.now();
+  const candidate = reopenCandidate({ brainPath, target: session, now, selfIds: [me, mcpPresence.id].filter(Boolean), explicit: true });
+  const reply = (status, text, structured = {}) => ({
+    content: [{ type: 'text', text }],
+    structuredContent: { schemaVersion: 1, status, session: candidate?.entry?.id || String(session || ''), ...structured },
+    ...(status === 'failed' ? { isError: true } : {}),
+  });
+  if (!candidate.ok) {
+    const e = candidate.entry || {};
+    const who = e.id ? `${reopenClientWord(e.client)} ${String(e.id).slice(0, 8)}` : `"${String(session).slice(0, 40)}"`;
+    const ago = (at) => `${Math.max(1, Math.round((now - Number(at || now)) / 60_000))} minute(s) ago`;
+    const why = {
+      'no-brain': 'there is no project brain for this connection — call brain_sync with the project root first.',
+      'unknown-session': `no session KLYPIX remembers matches ${who}. Use the id from the queued-note reply, brain_sync peers, or brain_doctor.`,
+      'ambiguous-session': `${who} matches more than one session — use more characters of its id.`,
+      self: `${who} is this session.`,
+      live: `${who} is running${candidate.statusLabel ? ` (${candidate.statusLabel})` : ''} — it gets the note at its next action, so there is nothing to reopen.`,
+      'unsupported-client': `${who} cannot be reopened by KLYPIX — only Claude Code and Codex have a verified resume-by-id. The note stays queued until that session is next used.`,
+      'unsafe-id': `${who} has an id that cannot be passed to a terminal safely, so KLYPIX will not reopen it.`,
+      'no-waiting-note': `no note is waiting for ${who}. KLYPIX reopens a session only so a note can reach it — send it with brain_message first.`,
+      'just-reopened': `KLYPIX opened ${who} ${ago(candidate.reopenedAt)} — the terminal window should already be up.`,
+      'recently-declined': `the human chose "Not now" for ${who} ${ago(candidate.declinedAt)}. Ask them in chat before offering it again.`,
+    }[candidate.reason] || `KLYPIX could not reopen ${who} (${candidate.reason}).`;
+    return reply('refused', `Not reopened: ${why}`, { reason: candidate.reason });
+  }
+  const wantStart = start !== false;
+  const question = reopenQuestion(candidate, { senderLabel, start: wantStart, now });
+  const consent = await askHumanToReopen({ question, start: wantStart, extra });
+  const label = `${candidate.hostLabel} ${candidate.entry.id.slice(0, 8)}`;
+  const kept = candidate.expiresAt ? `kept ${Math.max(1, Math.round((candidate.expiresAt - Date.now()) / 86_400_000))} more day(s)` : 'kept up to 7 days';
+  const manualLine = `${candidate.cwdSource === 'session' ? 'In' : 'From the project folder'} ${candidate.cwd}, run: ${candidate.command}`;
+  if (consent.answer === 'unavailable') {
+    recordSessionReopen({ brainPath, sessionId: candidate.entry.id, outcome: 'manual', by: me });
+    return reply('manual', `Not reopened: KLYPIX cannot show the human a Reopen button in this app or on this machine, so nothing was opened. Give them this to run themselves if they want it now — ${manualLine}. Otherwise the note stays queued (${kept}).`, { cwd: candidate.cwd, command: candidate.command });
+  }
+  if (consent.answer === 'wait') {
+    recordSessionReopen({ brainPath, sessionId: candidate.entry.id, outcome: 'declined', via: consent.via, by: me });
+    return reply('declined', `Not reopened — the human chose "Not now". The note stays queued (${kept}) and is delivered when ${label} is next used. Do not offer this again unless the human brings it up.`, { via: consent.via });
+  }
+  if (consent.answer !== 'reopen') {
+    recordSessionReopen({ brainPath, sessionId: candidate.entry.id, outcome: 'no-answer', via: consent.via, by: me });
+    return reply('no-answer', `Not reopened — the human did not answer the prompt, so nothing was opened. The note stays queued (${kept}). If they want it now: ${manualLine}.`, { via: consent.via, cwd: candidate.cwd, command: candidate.command });
+  }
+  const plan = buildReopenLaunch({ hostKey: candidate.hostKey, sessionId: candidate.entry.id, cwd: candidate.cwd, prompt: consent.start ? REOPEN_NUDGE : '' });
+  const launch = launchReopen(plan);
+  if (launch.dryRun) {
+    recordSessionReopen({ brainPath, sessionId: candidate.entry.id, outcome: 'dry-run', via: consent.via, method: plan.method, by: me });
+    const would = plan.method === 'manual' ? 'would be handed to the human as a command (no terminal can be opened here)' : `would open via ${plan.method}`;
+    return reply('dry-run', `Dry run (KLYPIX_REOPEN_LAUNCH=dry-run): the human said yes, and ${label} ${would} in ${candidate.cwd} with ${candidate.command}. Nothing was started.`, { via: consent.via, method: plan.method, cwd: candidate.cwd, command: candidate.command, launch });
+  }
+  if (!launch.launched) {
+    recordSessionReopen({ brainPath, sessionId: candidate.entry.id, outcome: plan.method === 'manual' ? 'manual' : 'failed', via: consent.via, method: plan.method || null, by: me });
+    const reason = plan.method === 'manual'
+      ? (plan.reason === 'no-display' ? 'there is no display to open a terminal on' : 'no terminal app was found')
+      : String(launch.reason || plan.reason || 'the terminal did not start');
+    return reply(plan.method === 'manual' ? 'manual' : 'failed', `The human said yes, but KLYPIX could not open a terminal here (${reason}). Give them this to run — ${manualLine}. The note stays queued until then.`, { via: consent.via, cwd: candidate.cwd, command: candidate.command, reason });
+  }
+  recordSessionReopen({ brainPath, sessionId: candidate.entry.id, outcome: 'reopened', via: consent.via, method: plan.method, by: me });
+  const notes = candidate.waitingNotes.length;
+  return reply('reopened', `🔓 Reopened ${label} — the human said yes${consent.via === 'dialog' ? ' in the KLYPIX dialog' : ''}. It opened in a new ${plan.method === 'windows-terminal' ? 'Windows Terminal window' : plan.method === 'macos-terminal' ? 'Terminal window' : 'terminal window'} in ${candidate.cwd} with ${candidate.command}${consent.start ? ', and starts on the note right away' : ', waiting for the human to prompt it'}. ${notes === 1 ? 'The waiting note is' : `The ${notes} waiting notes are`} delivered at its first action; your next prompt shows the receipt. If the window shows an error (for example the command is not found), the note stays queued — ${manualLine}.`, { via: consent.via, method: plan.method, cwd: candidate.cwd, command: candidate.command, start: Boolean(consent.start), notes });
+});
+
 server.registerTool('brain_sync', {
   title: 'KLYPIX Context Gateway — synchronize task, peers, conflicts, and relevant memory',
   description: 'APPROVAL-FREE task gateway over the authorized MCP connection. Call FIRST with a concise intent and expected files, again when scope changes, and with phase:"complete" before the final response. One bounded response returns compact task-relevant brain context, active TASK peers (idle connections hidden), one-time messages, structured exact-file conflicts, and late-arrival overlap alerts. A completion that supplies machine-checkable result manifests is fail-closed: invalid, conflicting, or incomparable evidence returns needs-reconciliation and retains task scope. Works on any MCP host — it needs only the authorized MCP connection, so native lifecycle hooks are optional. LIMITS: conflict matching is EXACT-PATH and both sessions must have declared their files, coordination/result reconciliation is machine-local and OS-user-local (a teammate on another machine is invisible), and file overlap remains ADVISORY.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.90.0",
+  "version": "1.91.0",
   "mcpName": "io.github.dahshanlabs/klypix-mcp",
   "description": "Active state management for multi-agent coding: a shared, versioned project brain over MCP.",
   "type": "module",
@@ -84,7 +84,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/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/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs",
+    "test": "node test/publish-verdict.mjs && node test/npx-owned-names.mjs && node test/project-graph.mjs && node test/project-map-cli.mjs && node test/mcp-auto-update.mjs && node test/mcp-supervisor.mjs && node test/runtime-inspector.mjs && node test/codex-hooks.mjs && node test/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/session-mailbox.mjs && node test/session-reopen.mjs && node test/lane-write-retry.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/capture-gap.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/guard-cards.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.mjs && node test/eval-retrieval.mjs && node test/field-report-2026-07-04.mjs && node test/autoprop.mjs && node test/overlay-recency-2026-07-12.mjs && node test/brain-challenge.mjs && node test/brain-lens.mjs && node test/brain-kind.mjs && node test/rule-drafts.mjs && node test/claim-engine.mjs && node test/partial-notes.mjs && node test/lifecycle-prefix.mjs && node test/close-link-safety.mjs && node test/resolve-ledger.mjs && node test/plan-fulfillment.mjs && node test/arrange-receipts.mjs && node test/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-security.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/semantic-hash-parity.mjs && node test/enrichment.mjs && node test/provenance.mjs && node test/confirm-trail.mjs && node test/hook-fallback.mjs && node test/eval-hook-lane.mjs && node test/hook-unified-lane.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/marker-suffix-grammar.mjs && node test/evidence-anchors.mjs && node test/brain-evidence.mjs && node test/presence-visibility.mjs && node test/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-reconcile.mjs && node test/release-ancestry.mjs && node test/release-claim-join.mjs && node test/release-claims.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/revival-map.mjs && node test/merge-scale.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/canvas-groups.mjs && node test/git-tools.mjs && node test/link-compat.mjs && node test/uninstall.mjs && node test/current-guidance.mjs && node test/status-shape.mjs && node test/status-hook.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs",