klypix-mcp 1.90.1 → 1.92.0

package/README.md

@@ -119,12 +119,16 @@ 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 25 tools, and not the retrieval engine.
 
 ---
 
 ## Quick start
 
+**You need Node.js 20 or newer** (`node -v` to check). Every way of connecting runs the server with
+`node` — `npx`, the installed bundle, and the entry KLYPIX's Settings buttons write — and none of them
+checks for Node first.
+
 Run this **inside your project**:
 
 ```bash
@@ -142,7 +146,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  ✓ 25 tools reachable via .mcp.json (892ms)
 ```
 
 That last line is the point. MCP config fails **silently** — a wrong entry means the server never
@@ -315,15 +319,17 @@ behaviour is unverified.
 | **Gemini CLI / Antigravity** | MCP config + always-on rules file | `link` | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
 | **Windsurf** | Rules file only | `link` | Reaches the tools through Windsurf's own global MCP config | Model must call `brain_note` | Via its own MCP config |
 | **Aider** | Rules file only (no MCP) | `link` | CLI path: `npx -y -p klypix-mcp klypix-read` | CLI path: `npx -y -p klypix-mcp klypix-append` | — |
-| **Claude Desktop** | One-time manual config edit | you | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
+| **Claude Desktop** | One-time config: KLYPIX's Settings button, or a manual edit | KLYPIX app or you | Model must call `brain_sync` | Model must call `brain_note` | For the MCP connection |
 
 `install` and `link` are different things and are not interchangeable: `install` sets up the
 machine engine and hooks, then wires supported hosts detected for this project (see *Quick start*).
 `link` is the explicit per-project repair/projection path for all 14 managed files, regardless of
 which hosts are installed.
 
-**Claude Desktop** — add this to `claude_desktop_config.json` by hand; nothing writes that file
-for you:
+**Claude Desktop** — in the KLYPIX desktop app, Settings → Project → **Connect Claude Desktop**
+writes this entry for you; or add it to `claude_desktop_config.json` by hand. Either way it needs
+Node.js on the PC, and Claude Desktop must be quit completely (tray icon → Quit) and reopened before
+it lists the tools:
 
 ```json
 {
@@ -451,8 +457,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 +470,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.
 
@@ -503,6 +534,27 @@ The app is a separate, proprietary Windows product. The format, this server and
 Apache-2.0 and work with no app installed. The app's interface is available in English and Arabic
 (some newer panels are still English-only).
 
+### KLYPIX canvases and your AI tool
+
+Beyond project brains, the same connection reads and writes the KLYPIX canvases (spaces) saved on
+your PC. **Your AI tool reads what KLYPIX has already read:**
+
+- `read_canvas` prints every card with its id; `read_card_contents` returns what is inside a card
+  from what KLYPIX saved — the transcript on a video card, the text card **Read contents** made for a
+  reel or web page, an OCR card for a photo, a folder's file list. For a reel or a video, choose Read
+  contents in KLYPIX first (select the card, press Enter), let the canvas save, then ask your AI tool.
+  This version does not start new readings itself.
+- What a person set up in KLYPIX is respected: cards inside a box **locked from AI tools** are left
+  out of every read; frozen cards are marked read-only; collapsed boxes, comments and tags are shown.
+- `klypix_status` tells your AI tool what KLYPIX can do on this PC right now, and which step the person
+  has to take.
+- **A canvas that is open in KLYPIX is not written.** KLYPIX builds that write the open-canvas lease
+  (`%APPDATA%\klypix\agent-bridge\endpoint.json`, no secret in it) make `add_to_canvas` refuse
+  that canvas and say why; project brains are the exception, because KLYPIX merges them. With an older
+  KLYPIX, `add_to_canvas` writes and its reply tells the person to close the canvas's tab and open it
+  again.
+- Text that comes back from cards, pages, reels and files is fenced as data, never instructions.
+
 ## Measure it yourself
 
 Claims about a shared brain — "nothing is lost", "it stays fast" — are unfalsifiable until a
@@ -637,7 +689,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 
 ---
 
-## The 22 verbs
+## The 25 verbs
 
 | Tool | What it does |
 |---|---|
@@ -651,20 +703,23 @@ 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 |
 | `project_map_scan` | KLYPIX's own zero-install scanner: gitignore-aware file inventory + file-level import edges (relative, tsconfig-alias, and monorepo-workspace imports resolved) written to `klypix-map/graph.json` — which then serves `project_map_context` automatically |
 | `project_map_drift` | Read-only drift report: brain cards whose referenced files are gone or moved (with rename candidates), plus a headline when the checkout itself is behind its origin default branch |
 | `canvas_view` | Returns the board as a structured render spec plus a text summary, and declares an MCP Apps (SEP-1865) UI resource |
-| `read_canvas` | A canvas as markdown (cards, connection graph, `[[links]]`, `#tags`) |
-| `search_canvases` | Search across canvases by name and content |
+| `read_canvas` | A canvas as markdown: every card with its id, the connection graph, `[[links]]`, `#tags` and tag pills, status, comments, reactions, frozen and collapsed boxes, and the readings KLYPIX already saved on link, video and photo cards; photo cards' images attached, each labelled with its card. Cards inside a box a person locked from AI tools are left out, and counted. Titles as KLYPIX shows them work as names |
+| `read_card_contents` | What is inside up to 5 cards — a reel, YouTube video, web page, video or audio file, photo, document or folder — from what KLYPIX has already read: transcripts it saved on the card, its Read contents and OCR result cards, folder listings. Fenced as data, marked full or partial, with where it was made (this PC or cloud AI). A card KLYPIX has not read yet comes back with the one step the person takes in KLYPIX; this version starts no new readings |
+| `klypix_status` | What KLYPIX can do on this PC right now: whether the app is running and which canvases it has open (from the lease file the app writes), where canvases are read from, and what each feature still needs from the person |
+| `search_canvases` | Search across canvases by name, content, tags and tag pills, and the readings KLYPIX saved on cards; returns card ids and dates. Never searches inside a box a person locked from AI tools |
 | `search_all_brains` | Cross-project memory search across every registered brain on this machine |
 | `create_canvas` | New `.klypix` from cards + connections |
-| `add_to_canvas` | Append cards/connections (positions preserved) |
+| `add_to_canvas` | Append cards/connections (positions preserved), bordered and readable on KLYPIX's dark and Paper themes; a card's `group` puts it in that titled box. Refuses a canvas open in KLYPIX (`OPEN_IN_APP`), a box locked from AI tools (`SCOPE_LOCKED`) or a frozen box (`FROZEN`), and writes nothing; project brains are the exception to the first. Returns the new card ids |
 | `list_canvases` | List every `.klypix` in the vault |
 
-Exactly 22, machine-verifiable with `npx klypix-mcp doctor`.
+Exactly 25 as of klypix-mcp 1.92.0, machine-verifiable with `npx klypix-mcp doctor`.
 
 > **`canvas_view`:** no MCP Apps host has been observed rendering the UI resource yet — there is no
 > screenshot and no host-level test. Hosts without the extension get clean text, which is the path

package/bin/klypix-append.mjs

@@ -11,15 +11,22 @@
 //   echo '<addition>' | node scripts/append-klypix.mjs <file.klypix>
 //
 // addition:
-//   { "cards": [{ "text": "...", "heading"?, "color"? }],
+//   { "cards": [{ "text": "...", "heading"?, "color"?, "group"?, "border"? }],
 //     "connections": [{ "from": <idx|title>, "to": <idx|title>, "relationship"? }] }
 //   from/to may reference a NEW card (by index in this addition, or its title)
 //   or an EXISTING card already on the canvas (by its title). New cards land in
 //   a column just to the right of the current content, stacked on top.
+//
+// Like add_to_canvas it honours the KLYPIX lease (src/app-lease.mjs): a canvas
+// that is open in KLYPIX is refused and left byte-identical (project brains are
+// the exception — KLYPIX merges them), and on Windows with no lease file it
+// writes and prints the step that keeps the cards if the canvas IS open.
 
 import fs from 'fs';
-import { appendToKlypix, atomicWrite } from '../src/klypix-format.mjs';
+import path from 'path';
+import { appendToKlypix, atomicWrite, readManifestCheap } from '../src/klypix-format.mjs';
 import { brainCaptureLockPath, withAdvisoryWriteLock } from '../src/brain-write-lock.mjs';
+import { canvasWriteLockPath, leaseVerdict, tellUser, LEASE_SINCE_APP_VERSION } from '../src/app-lease.mjs';
 
 const args = process.argv.slice(2);
 const file = args.find(a => !a.startsWith('--'));
@@ -33,22 +40,46 @@ try {
     addition = JSON.parse(raw);
 } catch (e) { console.error('Addition is not valid JSON:', e.message); process.exit(2); }
 
-// Read-modify-write under the SAME cross-process lock as the MCP engine, hooks,
-// and desktop app; racing them unlocked is silent last-writer-wins loss.
-const wrote = await withAdvisoryWriteLock(brainCaptureLockPath(file), async (locked) => {
-    if (!locked) return false;
+// A project brain: by file name, or by the manifest's explicit kind (a renamed brain).
+const manifest = readManifestCheap(file);
+const isBrain = /^brain\.(klypix|any)$/i.test(path.basename(file)) || manifest?.kind === 'brain';
+const title = (manifest && typeof manifest.title === 'string' && manifest.title.trim()) || path.basename(file).replace(/\.(klypix|any)$/i, '');
+
+// Read-modify-write under the SAME cross-process lock as the MCP engine:
+// brains share the hooks' and desktop app's folder lock; an ordinary canvas
+// locks in the profile, so no `.claude` folder appears beside it. Racing them
+// unlocked is silent last-writer-wins loss. The callback only RETURNS — exiting
+// inside it would skip the lock's release.
+const outcome = await withAdvisoryWriteLock(isBrain ? brainCaptureLockPath(file) : canvasWriteLockPath(file), async (locked) => {
+    if (!locked) return { status: 'busy' };
+    const verdict = isBrain ? { action: 'write' } : leaseVerdict(file);
+    if (verdict.action === 'refuse') return { status: 'open' };
     let buf;
     try {
         buf = await appendToKlypix(fs.readFileSync(file), addition);
-    } catch (e) { console.error(e.message); process.exit(1); }
-    await atomicWrite(file, buf);
-    return true;
+    } catch (e) { return { status: 'failed', message: e.message, code: e.code }; }
+    await atomicWrite(file, buf, { isBrain, restorePoint: !isBrain, reason: 'klypix-append' });
+    return { status: 'written', warn: verdict.action === 'warn' };
 }, { tries: 100, waitMs: 60 });
-if (!wrote) {
+
+if (outcome.status === 'busy') {
     console.error('append-klypix refused (file unchanged): the write lock is held by another writer — retry in a moment.');
     process.exit(1);
 }
+if (outcome.status === 'open') {
+    console.error(`append-klypix refused (file unchanged): '${title}' is open in KLYPIX right now (code OPEN_IN_APP).`);
+    console.error(`Tell the user: ${tellUser('OPEN_IN_APP', { canvas: title })}`);
+    process.exit(1);
+}
+if (outcome.status === 'failed') {
+    console.error(outcome.message);
+    if (outcome.code === 'SCOPE_LOCKED' || outcome.code === 'FROZEN') console.error(`Tell the user: ${tellUser(outcome.code)}`);
+    process.exit(1);
+}
 const cardCount = Array.isArray(addition.cards) ? addition.cards.length : 0;
 const connCount = Array.isArray(addition.connections) ? addition.connections.length : 0;
 console.log(`Appended ${cardCount} card(s), ${connCount} connection(s) to ${file}.`);
-console.log(`Reopen it in the KLYPIX app, or verify: node scripts/read-klypix.mjs "${file}"`);
+console.log(isBrain
+    ? `It appears in the brain if it is open in KLYPIX (inside OneDrive or Dropbox, when you next open it). Verify: node scripts/read-klypix.mjs "${file}"`
+    : `They appear when the canvas is next opened in KLYPIX. Verify: node scripts/read-klypix.mjs "${file}"`);
+if (outcome.warn) console.log(`Tell the user: ${tellUser('MAY_BE_OPEN', { canvas: title, version: LEASE_SINCE_APP_VERSION })}`);

package/bin/klypix-install.mjs

@@ -118,8 +118,10 @@ function wireCodex() {
     // Pre-1.35 installed a global `--vault "."` entry. A global Codex process
     // resolves that dot from the app install directory, not the user's project,
     // so it can silently bind the wrong brain and override the correct project
-    // table. Remove only KLYPIX-owned global tables; preserve every other server.
-    const globalMcp = disconnectCodexMcpServer({ configPath: CODEX_CONFIG });
+    // table. Remove only KLYPIX-owned global tables whose --vault is RELATIVE;
+    // preserve every other server — including the absolute-vault table KLYPIX's
+    // own Settings → Codex button writes (removing it greyed that button).
+    const globalMcp = disconnectCodexMcpServer({ configPath: CODEX_CONFIG, onlyRelativeVault: true });
     const instructions = mergeCodexGlobalInstructions(HOME);
     const hookScript = path.join(BRAIN_DIR, 'codex-brain-hook.mjs');
     const presence = CODEX_HOOKS && exists(hookScript)
@@ -285,7 +287,10 @@ const flatten = (code) => code
     // commitsInRange / makeContainmentProbe from it. It was already STAGED in
     // the flat bundle (mcp-presence needs it) but never flattened, because
     // nothing in bin/ had imported it directly before.
-    .replace(/\.\.\/src\/(bench|brain-doctor|agent-presence|agent-rules|capture-gap|enrichment|finding-routing|mcp-presence|mcp-supervisor|mcp-auto-update|presence-relay|repo-state|semantic-memory|runtime-inspector|project-graph|git-capture-install)\.mjs/g, './$1.mjs')
+    // app-lease / app-tools (P0 agent parity): the worker lazily imports the
+    // app tools (klypix_status, read_card_contents); klypix-core and the app
+    // tools import the lease reader.
+    .replace(/\.\.\/src\/(bench|brain-doctor|agent-presence|agent-rules|capture-gap|enrichment|finding-routing|mcp-presence|mcp-supervisor|mcp-auto-update|presence-relay|repo-state|semantic-memory|runtime-inspector|project-graph|git-capture-install|app-lease|app-tools)\.mjs/g, './$1.mjs')
     .replace(/klypix-worker\.mjs/g, 'klypix-mcp-worker.mjs')
     .replace(/const PKG_VERSION = \(\(\) => \{[\s\S]*?\}\)\(\);/, `const PKG_VERSION = '${VERSION}'; // baked at install (flat layout has no package.json)`);
 
@@ -429,7 +434,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', 'klypix-core.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', '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-tools.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', '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 [

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-read.mjs

@@ -15,7 +15,7 @@
 
 import fs from 'fs';
 import path from 'path';
-import { parseKlypix, structToMarkdown } from '../src/klypix-format.mjs';
+import { parseKlypix, structToMarkdown, scopeLockedView } from '../src/klypix-format.mjs';
 
 const args = process.argv.slice(2);
 const file = args.find(a => !a.startsWith('--'));
@@ -31,20 +31,29 @@ try {
     console.error(e.message);
     process.exit(1);
 }
-const { struct, zip, assetPaths } = parsed;
+const { zip, assetPaths } = parsed;
+// This is the read path agents without MCP use (Aider), so it shows them what
+// read_canvas shows: cards inside a box a person locked from AI tools in KLYPIX
+// are left out (and counted), and each card's id, saved reading and state ride
+// along.
+const view = scopeLockedView(parsed);
+const struct = view.struct;
 // Fall back to the filename for the title when the file didn't store one.
 if (!struct.title || struct.title === 'Untitled') {
     struct.title = path.basename(file).replace(/\.(klypix|any)$/i, '');
 }
 
-// Optionally extract binary assets so the agent can open images with vision.
+// Optionally extract binary assets so the agent can open images with vision —
+// never an asset only a hidden (scope-locked) card uses.
 if (assetsDir && assetPaths.length) {
     fs.mkdirSync(assetsDir, { recursive: true });
+    const visibleAssets = new Set(struct.assets);
     for (const p of assetPaths) {
+        if (!visibleAssets.has(path.basename(p))) continue;
         const bytes = await zip.file(p).async('nodebuffer');
         fs.writeFileSync(path.join(assetsDir, path.basename(p)), bytes);
     }
 }
 
 if (asJson) { console.log(JSON.stringify(struct, null, 2)); process.exit(0); }
-console.log(structToMarkdown(struct, { assetsDir }));
+console.log(structToMarkdown(struct, { assetsDir, parsed, lockedBoxes: view.boxes }));

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);