klypix-mcp 1.66.1 → 1.67.0

package/README.md

@@ -79,7 +79,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 21 tools, and not the retrieval engine.
+It verifies 15 required coordination behaviours — not the 26 tools, and not the retrieval engine.
 
 ---
 
@@ -333,10 +333,13 @@ have to have declared their files for the overlap to be visible at all.
 `brain_message` leaves one-time coordination notes for other sessions. 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. Pending and offered notes survive
-reconnects. Expiry or bounded-capacity eviction records a failed per-recipient receipt instead of
-silently looking delivered. The core lane is machine-local, notes expire after 24 hours, and they
-are never written into the brain.
+offer — never that a person read it or that an agent acted on it. The note keeps replaying until the
+receiving model calls `brain_message_receipt` with the exact message id and per-recipient offer
+token; only that token-bound action records `consumed`. Pending, offered, and acknowledged notes
+survive reconnects. Expiry or bounded-capacity eviction records a failed per-recipient receipt
+instead of silently looking delivered. The send-time audience is fixed, unresolved targeted sends
+fail closed, the core lane is machine-local, notes expire after 24 hours, and they are never written
+into the brain.
 
 Durable handoffs go in the brain itself — decisions, findings, open questions and skills captured
 as cards, each stamped with the agent that wrote it.
@@ -345,14 +348,18 @@ as cards, each stamped with the agent that wrote it.
 
 When a task publishes a quantified or otherwise machine-checkable claim, it can attach one or more
 versioned result manifests to `brain_sync { phase: "complete" }`. Each manifest binds the claim to a
-report hash, producer/run provenance, the exact input and configuration fingerprints, and named
-metrics with counts and tolerances. Matching peer evidence is recorded as corroboration; conflicting
-or incomparable evidence returns `needs-reconciliation` and keeps the task scope active.
+report hash, producer/run provenance, the exact declared task scope, material artifact hashes,
+evaluation outputs, public metric wording, input/configuration fingerprints, and named metrics with
+counts and tolerances. Matching peer evidence is recorded as corroboration; conflicting or
+incomparable evidence returns `needs-reconciliation` and keeps the task scope active.
 
 The gate fails closed. Once a task submits result evidence, it cannot bypass an invalid or
 conflicting result by retrying completion without the manifest, and that obligation survives worker
 restart, hibernation, and transparent hot-swap. A fresh `phase: "start"` is the explicit boundary for
 a new task. The strict schema and reusable validator are exported as `klypix-mcp/result-reconcile`.
+Schema-v2 receipts can be converted into commit-bound publication evidence and independently checked
+with `klypix-mcp/release-evidence`; legacy schema-v1 results remain usable for coordination but cannot
+authorize publication.
 
 ## Human control in Klypix
 
@@ -488,7 +495,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 
 ---
 
-## The 21 verbs
+## The 26 verbs
 
 | Tool | What it does |
 |---|---|
@@ -500,12 +507,17 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `brain_lens` | Machine-readable freshness, provenance, activity, timeline, orrery and unresolved views |
 | `brain_garden` | Maintenance pass — proposes first, and cannot apply without an approval code the human generates |
 | `brain_doctor` | Self-diagnosis: version, core/enhanced host adapters, active sessions, tool count, projection drift |
-| `brain_message` | Session-to-session coordination notes with per-recipient offer / later-action acknowledgement / failure receipts (24h TTL, never written into the brain) |
+| `brain_message` | Session-to-session coordination notes with a fixed send-time audience and per-recipient pending / offer / acknowledgement / consumption / failure receipts (24h TTL, 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_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 |
+| `remote_status` | Inspect the local KLYPIX tray relay and its verified Remote capabilities |
+| `remote_sessions` | List coding-agent sessions with exact provider, host-binding and capability receipts |
+| `remote_actions` | List pending questions, approvals, failures, conflicts and reviews reported by supported providers |
+| `remote_command` | Control one exact verified coding-agent session using a fresh capability receipt; unsupported operations fail closed |
 | `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 |
@@ -514,7 +526,7 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `add_to_canvas` | Append cards/connections (positions preserved) |
 | `list_canvases` | List every `.klypix` in the vault |
 
-Exactly 21, machine-verifiable with `npx klypix-mcp doctor`.
+Exactly 26, 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
@@ -714,7 +726,8 @@ Your `brain.klypix` is yours — it is a plain ZIP and stays readable with or wi
 Issues and pull requests: [github.com/dahshanlabs/klypix-mcp](https://github.com/dahshanlabs/klypix-mcp).
 Questions or feedback: [hello@klypix.com](mailto:hello@klypix.com).
 
-The repository carries 59 test files, 54 of them in the `npm test` chain, covering the presence
+The repository carries 68 test files: 62 listed directly in `scripts.test`, plus the
+`pretest` workflow gate. Together they cover the presence
 lane and its cross-machine relay, the Context Gateway, supervisor hot-swap, auto-update, retrieval
 quality, decay, challenge, lenses, the format guard, the git tools (including a real `git merge`
 through the merge driver), uninstall, and conformance. Run them with `npm test` from a clone — they

package/bin/klypix-conformance.mjs

@@ -214,19 +214,21 @@ try {
         text: 'verified note',
         ts: now - 1_000,
         candidateIds: ['finding-owner'],
-        deliveryVersion: 2,
+        deliveryVersion: 3,
         deliveries: [{
           recipientId: 'finding-owner',
-          state: 'acknowledged',
+          state: 'consumed',
           attempts: 1,
+          offerToken: 'conformance-offer-token-000000',
           offeredAt: now - 900,
           acknowledgedAt: now - 500,
+          consumedAt: now - 250,
         }],
         seen: ['finding-owner'],
       }],
       sessions: lane, selfId: 'finding-sender', now,
     });
-    checks.findingReceiptRendered = /model-context delivery acknowledged by all 1 target peer\(s\) on a later action \(not human-read\)/.test(renderReceiptSummary(receipt));
+    checks.findingReceiptRendered = /explicitly consumed by all 1 target peer\(s\) after model-context delivery \(not human-read\)/.test(renderReceiptSummary(receipt));
   }
 
   // ── Cross-PC presence: simulated two-machine scenario ─────────────────────
@@ -277,6 +279,23 @@ try {
     });
     checks.crossMachineConsentGate = framesSent === 0 && gated.reason === 'no-consent';
 
+    // Give A a current B recipient before the message is created. Delivery v3
+    // snapshots concrete sessions at send time; a message created while A is
+    // still unaware of B is correctly rejected as a zero-audience broadcast.
+    const bToA = [];
+    relayOutbound({
+      sessions: listActiveSessions({ brainPath: brainB, home: homeB, now }),
+      consent: GRANT, machineId: 'xpc-mach-b', hostLabel: 'MACHINE-B', root: repoB, now,
+      send: (frame) => bToA.push(frame),
+    });
+    const rowsOnA = bToA
+      .map((frame) => relayInbound(frame, { consent: GRANT, machineId: 'xpc-mach-a', now: now + 250 }))
+      .filter((inbound) => inbound?.type === 'presence')
+      .map((inbound) => inbound.row);
+    if (rowsOnA.length) {
+      upsertRemoteSessions({ brainPath: brainA, rows: rowsOnA, machineId: 'xpc-mach-a', home: homeA, now: now + 250 });
+    }
+
     // Live channel: A's session and message reach B exactly once.
     const wire = [];
     relayOutbound({
@@ -358,7 +377,7 @@ const result = {
   metrics,
   contract: {
     proactive: 'best-effort MCP logging notification',
-    inBand: 'a retained machine-local note is offered on a supported model-context KLYPIX action, then acknowledged only by a later independent action; expiry/overflow are failed receipts',
+    inBand: 'a retained machine-local note is offered on a supported model-context KLYPIX action, acknowledged only by a later independent action, and retired only by explicit token-bound consumption; expiry/overflow are failed receipts',
     crossMachine: 'relay primitives require caller-confirmed durable insertion and a per-recipient-machine acknowledgement; app bridge wiring is a separate conformance boundary',
   },
 };
@@ -372,6 +391,6 @@ if (jsonMode) {
   }
   if (checks.error) console.log(`  error: ${checks.error}`);
   console.log(`  memory/coordination: ${metrics.firstClientMs ?? '?'}ms / ${metrics.secondClientMs ?? '?'}ms`);
-  console.log('  proactive notifications are best-effort; retained notes use offer → later-action acknowledgement, with explicit failure receipts.');
+  console.log('  proactive notifications are best-effort; retained notes use offer → later-action acknowledgement → explicit token-bound consumption, with explicit failure receipts.');
 }
 process.exit(ok ? 0 : 1);

package/bin/klypix-install.mjs

@@ -29,6 +29,8 @@ import {
     codexPresenceHookStatus,
     mergeCodexPresenceHooks,
 } from '../src/codex-hooks.mjs';
+import { brainInstallDecision } from '../src/install-version.mjs';
+import { acquireInstallLockSync, releaseInstallLockSync } from '../src/install-lock.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, '..');
@@ -147,45 +149,10 @@ function reportCodex(result) {
     console.error('  Claude Code installation is intact. Fix the Codex warning, then re-run this command.');
 }
 
-// ── Never-downgrade gate ─────────────────────────────────────────────────────
-// The brain version is a UNIFIED namespace = the klypix-mcp version, stamped by BOTH
-// the npm install (here) and the desktop bundle, so the two channels compare cleanly.
-// A dev deploy ({dev:true}) is authoritative; a strictly-newer install is not
-// downgraded. --force overrides both.
-const cmpSemver = (a, b) => { const pa = String(a || '').split('.').map(n => parseInt(n, 10) || 0), pb = String(b || '').split('.').map(n => parseInt(n, 10) || 0); for (let i = 0; i < 3; i++) { if ((pa[i] || 0) !== (pb[i] || 0)) return (pa[i] || 0) - (pb[i] || 0); } return 0; };
-const cur = (() => { try { return JSON.parse(fs.readFileSync(path.join(BRAIN_DIR, '.brain-version.json'), 'utf8')); } catch { return null; } })();
-if (!FORCE && cur) {
-    if (cur.dev === true) {
-        console.log(`• A dev deploy owns ${BRAIN_DIR} (dev:true) — leaving it untouched. Re-run with --force to override.`);
-        if (!RUNTIME_ONLY) reportCodex(wireCodex());
-        process.exit(0);
-    }
-    if (cur.brainVersion && cmpSemver(cur.brainVersion, VERSION) > 0) {
-        console.log(`• Installed brain v${cur.brainVersion} is newer than this package v${VERSION} — not downgrading. Re-run with --force to override.`);
-        if (!RUNTIME_ONLY) reportCodex(wireCodex());
-        process.exit(0);
-    }
-}
-
 // ── Install lock (auto-propagation, part D — concurrency) ─────────────────────
-// Two sessions can self-update at the same moment; serialize so their writes never
-// tear. O_EXCL create wins; a lock older than 60s (a sub-second install should never
-// take that) is stolen so a crashed installer can't wedge every future update.
-const LOCK = path.join(BRAIN_DIR, '.install.lock');
-const sleepSync = (ms) => { try { Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms); } catch { /* */ } };
-function acquireLock() {
-    try { fs.mkdirSync(BRAIN_DIR, { recursive: true }); } catch { /* */ }
-    for (let i = 0; i < 120; i++) {
-        try { const fd = fs.openSync(LOCK, 'wx'); fs.writeSync(fd, String(process.pid)); fs.closeSync(fd); return true; }
-        catch (e) {
-            if (e && e.code !== 'EEXIST') return false;
-            try { if (Date.now() - fs.statSync(LOCK).mtimeMs > 60000) { fs.unlinkSync(LOCK); continue; } } catch { /* raced on the stale file — retry */ }
-            sleepSync(50);
-        }
-    }
-    return false;
-}
-const releaseLock = () => { try { fs.unlinkSync(LOCK); } catch { /* */ } };
+// npm and desktop use this exact token-owned lock. The version decision is made
+// only AFTER acquisition, so an older queued installer re-reads and preserves a
+// newer runtime that committed while it waited.
 
 // Migrate THIS project's .mcp.json klypix-canvas entry off `npx` onto the local
 // bundle now that it's installed — the desync fix for EXISTING configs (the self-
@@ -230,12 +197,33 @@ const flatten = (code) => code
     .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)`);
 
-const gotLock = acquireLock();
-if (!gotLock) {
-    console.error(`✗ another KLYPIX install still owns ${LOCK}; no files were changed`);
+const installLock = acquireInstallLockSync(BRAIN_DIR);
+if (!installLock) {
+    console.error(`✗ another KLYPIX install still owns ${path.join(BRAIN_DIR, '.install.lock')}; no files were changed`);
     process.exit(1);
 }
 try {
+    // Never-downgrade gate: Brain Core semver is the unified payload identity.
+    // Read both receipts under the shared lock and conservatively keep the
+    // highest valid committed/recorded version. appVersion is provenance only.
+    const stamp = (() => { try { return JSON.parse(fs.readFileSync(path.join(BRAIN_DIR, '.brain-version.json'), 'utf8')); } catch { return null; } })();
+    const runtimeReceipt = (() => { try { return JSON.parse(fs.readFileSync(path.join(BRAIN_DIR, '.mcp-runtime.json'), 'utf8')); } catch { return null; } })();
+    const decision = brainInstallDecision({ candidateVersion: VERSION, stamp, runtime: runtimeReceipt, force: FORCE });
+    if (decision.action === 'refuse') {
+        releaseInstallLockSync(installLock);
+        console.error(`✗ package Brain Core version ${JSON.stringify(VERSION)} is invalid; refusing to install unidentified runtime files`);
+        process.exit(1);
+    }
+    if (decision.action === 'preserve') {
+        releaseInstallLockSync(installLock);
+        if (decision.reason === 'dev-owned') {
+            console.log(`• A dev deploy owns ${BRAIN_DIR} (dev:true) — leaving it untouched. Re-run with --force to override.`);
+        } else {
+            console.log(`• Installed brain v${decision.installedVersion} is newer than this package v${VERSION} — not downgrading. Re-run with --force to override.`);
+        }
+        if (!RUNTIME_ONLY) reportCodex(wireCodex());
+        process.exit(0);
+    }
     fs.mkdirSync(BRAIN_DIR, { recursive: true });
     // 1) runtime dependency CLOSURE (jszip+fractional-indexing for the hook/engine,
     //    @modelcontextprotocol/sdk+zod for the local MCP server). Resolve each via
@@ -280,7 +268,7 @@ try {
         if (!exists(path.join(destMods, name))) { copyDir(dir, path.join(destMods, name)); deps++; }
         try { const pj = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8')); for (const d of Object.keys(pj?.dependencies || {})) queue.push({ name: d, fromDir: dir }); } catch { /* no readable package.json */ }
     }
-    if (missing.length) { if (gotLock) releaseLock(); console.error(`✗ could not resolve required dep(s): ${missing.join(', ')} — aborting (the brain hook needs them).`); process.exit(1); }
+    if (missing.length) { releaseInstallLockSync(installLock); console.error(`✗ could not resolve required dep(s): ${missing.join(', ')} — aborting (the brain hook needs them).`); process.exit(1); }
 
     // 2) STAGE the scripts (engine + hook + flattened servers), write each to
     //    `<name>.klypix-new`, back up the current copy to .prev/, then atomically
@@ -337,7 +325,7 @@ try {
         rawSettings = fs.readFileSync(SETTINGS, 'utf8');
         if (rawSettings.trim()) {
             try { settings = JSON.parse(rawSettings); }
-            catch (e) { if (gotLock) releaseLock(); console.error(`✗ ${SETTINGS} is invalid JSON (${e.message}). Fix it and re-run — refusing to overwrite a broken config.`); process.exit(1); }
+            catch (e) { releaseInstallLockSync(installLock); console.error(`✗ ${SETTINGS} is invalid JSON (${e.message}). Fix it and re-run — refusing to overwrite a broken config.`); process.exit(1); }
         }
     }
     if (!RUNTIME_ONLY) {
@@ -351,12 +339,11 @@ try {
         fs.renameSync(tmp, SETTINGS);
     }
 
-    // 6) stamp the install (unified brain version → never-downgrade across channels)
+    // 6) Commit the runtime pointer and version receipt atomically while the
+    // shared cross-channel lock is still held. The runtime receipt goes first;
+    // a crash between receipts remains recoverable because the next installer
+    // compares both and keeps the highest valid Brain Core version.
     const installedAt = new Date().toISOString();
-    fs.writeFileSync(path.join(BRAIN_DIR, '.brain-version.json'), JSON.stringify({ brainVersion: VERSION, via: 'npm', dirty: false, installedAt }, null, 2));
-    // Commit the runtime pointer LAST. A running supervisor watches only this
-    // atomic file, validates every staged hash, and keeps the old worker if the
-    // candidate is incomplete or incompatible.
     const runtime = {
         protocol: 1,
         version: VERSION,
@@ -368,6 +355,9 @@ try {
     const runtimePath = path.join(BRAIN_DIR, '.mcp-runtime.json');
     fs.writeFileSync(runtimePath + '.klypix-new', JSON.stringify(runtime, null, 2) + '\n', 'utf8');
     fs.renameSync(runtimePath + '.klypix-new', runtimePath);
+    const versionPath = path.join(BRAIN_DIR, '.brain-version.json');
+    fs.writeFileSync(versionPath + '.klypix-new', JSON.stringify({ brainVersion: VERSION, via: 'npm', dirty: false, installedAt }, null, 2), 'utf8');
+    fs.renameSync(versionPath + '.klypix-new', versionPath);
 
     // 7) migrate THIS project's .mcp.json off npx onto the now-installed local bundle
     //    (heals an existing stale config so the next MCP server spawn runs current).
@@ -383,7 +373,7 @@ try {
     const wiredFor = (evt) => Array.isArray(verify?.hooks?.[evt]) && verify.hooks[evt].some(g => Array.isArray(g?.hooks) && g.hooks.some(h => typeof h?.command === 'string' && h.command.includes(HOOK_MARK)));
     const notWired = ['SessionStart', 'UserPromptSubmit', 'Stop', 'PostToolUse'].filter(e => !wiredFor(e));
 
-    if (gotLock) releaseLock();
+    releaseInstallLockSync(installLock);
     // Users who already enabled the optional local semantic runtime should not
     // pay a multi-minute first question after a model/cache contract upgrade.
     // Migrate registered brains once in a detached process after the atomic
@@ -419,7 +409,7 @@ try {
     console.log('  Compatible brain-core updates hot-swap behind the same MCP connection. Only the one-time legacy→supervisor migration, a supervisor change, or an intentionally breaking tool/protocol change needs reconnect.');
     console.log('  Verify anytime: `npx klypix-mcp doctor`; prove two-client behavior with `npx klypix-mcp conformance`.');
 } catch (e) {
-    if (gotLock) releaseLock();
+    releaseInstallLockSync(installLock);
     console.error(`✗ install failed: ${e?.message || e}`);
     process.exit(1);
 }