klypix-mcp 1.65.0 → 1.66.1

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 12 required coordination behaviours — not the 21 tools, and not the retrieval engine.
+It verifies 15 required coordination behaviours — not the 21 tools, and not the retrieval engine.
 
 ---
 
@@ -150,7 +150,9 @@ not a filing convention.
 
 - **Decisions have a lifecycle.** A new decision that contradicts an old one supersedes it. The
   stale card is archived with an arrow and a date, never deleted, and later answers surface the
-  correction rather than the corpse.
+  correction rather than the corpse. If a later decision returns to an earlier superseded stance,
+  high-confidence lineage leaves a dated `re-adopts` stamp on the new card plus an earlier→current
+  edge; the original A→B→C history remains intact.
 - **Corrections are explicit, not guessed.** Supersession fires on an UPPERCASE correction cue or
   an explicit edge. `brain_reconcile` only *proposes* stale-vs-correction pairs for a human to
   confirm.
@@ -274,7 +276,9 @@ the full brief written to disk for when broad history or status work needs it.
 
 Every other host gets a bounded ~2.8KB task capsule from one `brain_sync` call, plus a compact
 always-loaded `AGENTS.md` block that tells the agent to make that call at task start, when scope
-changes, and on completion. The gateway capsule is lexical-fast by design.
+changes, and on completion. The gateway capsule is lexical-fast by design. A newly captured open
+gap can claim a labeled `RECENT OPEN` slot only after clearing the normal lexical-relevance floor,
+so fresh relevant findings are not crowded out by older area vocabulary.
 
 Briefs are **not** injected automatically on Cursor, Cline, Copilot, Gemini CLI or Antigravity —
 there are no lifecycle hooks on those hosts.
@@ -285,9 +289,12 @@ On Claude Code, decisions are captured automatically at turn end from inline `
 markers in the transcript, deduped, under a capture lock.
 
 On every other host, capture is explicit: `brain_note` runs the same capture engine as the hooks —
-dedup, supersession, `✓` resolve, `~` update in place, `+` skill, `closes:` — and stamps which
-agent wrote the card. (If you install the git commit hook from the KLYPIX app, commit messages also
-capture automatically, for any agent. That hook has no CLI installer.)
+dedup, supersession, round-trip re-adoption receipts, `✓` resolve, `~` update in place, `+` skill,
+`closes:` — and stamps which agent wrote the card. A `✓` question preference ranks only candidates
+that already clear raw lexical overlap and two subject-identity anchors; generic lifecycle wording
+cannot turn weak overlap into a closure.
+(If you install the git commit hook from the KLYPIX app, commit messages also capture automatically,
+for any agent. That hook has no CLI installer.)
 
 `brain_challenge` is the other direction: propose a decision and the brain answers with receipts —
 prior decisions that deterministically contradict it, standing rules that dispute it, and
@@ -323,14 +330,30 @@ have to have declared their files for the overlap to be visible at all.
 
 ## Handoffs and messages
 
-`brain_message` leaves one-time coordination notes for other sessions. They arrive on the peer's
-next KLYPIX action, expire after 24 hours, and are never written into the brain. Delivery is
-best-effort-proactive through MCP logging (which some hosts hide) and in-band on the peer's next
-action. A peer that stays offline past the TTL misses the note.
+`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.
 
 Durable handoffs go in the brain itself — decisions, findings, open questions and skills captured
 as cards, each stamped with the agent that wrote it.
 
+## Evidence-gated completion
+
+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.
+
+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`.
+
 ## Human control in Klypix
 
 > **Not a second brain. A shared one.**
@@ -471,14 +494,14 @@ The MCP verbs below are what agents call. These are what **you** call:
 |---|---|
 | `brain_ask` | Whole-brain question answering — correction-aware, `as_of` time travel |
 | `brain_challenge` | The brain argues back: contradictions with receipts, tried-and-reversed chains, standing rules, other-agent provenance flags |
-| `brain_note` | Capture with the full lifecycle — supersede / ✓ resolve / ~ update / 🛠 skill / `closes:` |
+| `brain_note` | Capture with the full lifecycle — supersede / re-adopt / ✓ resolve / ~ update / 🛠 skill / `closes:` |
 | `brain_reconcile` | Proposes stale-vs-correction pairs and unrecorded migrations for a human to confirm |
 | `brain_insights` | Hubs, orphaned decisions, stale questions, area sizes |
 | `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 (24h TTL, never written into the brain) |
-| `brain_sync` | Context Gateway: task capsule, active-task peers, exact-file overlap, one-time alerts, timing |
+| `brain_message` | Session-to-session coordination notes with per-recipient offer / later-action acknowledgement / failure receipts (24h TTL, never written into the brain) |
+| `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 |
@@ -491,7 +514,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 19, machine-verifiable with `npx klypix-mcp doctor`.
+Exactly 21, 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
@@ -570,7 +593,8 @@ replaceable worker runs the brain core. A staged update is hash-verified, initia
 checked for backward-compatible tool schemas, and handed the current `brain_sync` task scope before
 the supervisor switches between requests. Added tools use the standard
 `notifications/tools/list_changed` signal. A failed or breaking candidate is rejected while the old
-worker keeps serving.
+worker keeps serving. A blocked result claim is kept in a durable per-project/session marker, so a
+worker replacement cannot turn a failed evidence check into a result-less completion.
 
 Compatible engine updates therefore activate behind the same live connection — no reconnect, no
 host restart. Three cases still require a deliberate reconnect or manual install: the one-time
@@ -601,7 +625,11 @@ keep lazy first-use indexing instead.
 - **Coordination state is local files.** The brain is a file in your repo; the presence lane is a
   file under your home directory. Nothing is uploaded — with one explicit, default-OFF exception:
   the cross-PC presence relay, which (only after per-brain consent in the KLYPIX desktop app)
-  shares metadata-only presence frames over that brain's cloud channel. No consent, no frames.
+  shares whitelisted presence fields and the text of one-time coordination notes over that
+  brain's cloud channel. KLYPIX does not automatically attach file/card contents, diffs, or screen
+  data, but a note relays whatever its sender typed (and automatic overlap alerts name the declared
+  file paths involved). The scope is versioned: an older metadata-only grant does not authorize note
+  text and must be granted again. No current consent, no frames.
 - **`install` writes to your home directory:** `~/.claude/project-brain` (engine + runtime),
   `~/.claude/settings.json` (four hooks — written even if Claude Code is not installed),
   `~/.codex/AGENTS.md` (guidance block), and with `--codex-hooks`, `~/.codex/hooks.json`. It also
@@ -617,9 +645,10 @@ Read this section before you build on any of it.
 - **Coordination is machine-local and OS-user-local.** The presence lane is a file in your home
   directory. Two developers on two machines do not see each other's sessions, peers, overlaps or
   messages. This package ships the cross-machine presence *core* (`./presence-relay` — versioned
-  metadata-only frames, a symmetric default-off consent gate, loop prevention and message dedup),
-  but no transport: carrying frames between machines is the desktop app's job. With `klypix-mcp`
-  alone, coordination is machine-local.
+  whitelisted presence metadata plus coordination-note text, a symmetric default-off consent gate,
+  loop prevention, stable message IDs and per-recipient-machine acknowledgement primitives), but no
+  transport: carrying frames between machines is the desktop app's job. With `klypix-mcp` alone,
+  coordination is machine-local.
 - **Overlap matching is exact-path, and both sides must declare.** A session that never declares
   its expected files is invisible to overlap detection, and `src/auth/token.ts` does not match a
   rename or a parent directory.
@@ -685,7 +714,7 @@ 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 49 test files, 45 of them in the `npm test` chain, covering the presence
+The repository carries 59 test files, 54 of them in the `npm test` chain, covering 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-brain-deleted.mjs

@@ -37,8 +37,13 @@ if (action === 'list') {
   console.log(`${entries.length} deleted card(s) in ${path.basename(brainPath)} — newest first\n`);
   for (const e of entries) {
     const full = ids.includes(e.id) ? await readGraveyardCard(buf, e.id) : null;
-    console.log(`  ${e.id}   ${ago(e.deletedAt).padEnd(9)} ${e.area ? `[${e.area}] ` : ''}${e.preview || '(no text)'}`);
+    const label = e.summary?.label || e.preview || `(${e.summary?.type || 'unknown'} item)`;
+    const audit = e.deletion?.confidence === 'legacy'
+      ? 'legacy source unverified'
+      : `${e.deletion?.initiator || 'unknown'} via ${e.deletion?.cause || 'unclassified'}`;
+    console.log(`  ${e.id}   ${ago(e.deletedAt).padEnd(9)} ${e.area ? `[${e.area}] ` : ''}${label}   <${audit}>`);
     if (full?.content) console.log(`\n${String(full.content).split('\n').map((l) => `      ${l}`).join('\n')}\n`);
+    else if (full) console.log(`\n      ${JSON.stringify(e.summary || { type: full.type || 'unknown' })}\n`);
   }
   console.log(`\nFull text:  npx klypix-mcp brain-deleted list <id> --brain "${brainPath}"`);
   console.log(`Restore:    npx klypix-mcp brain-deleted restore <id>`);

package/bin/klypix-conformance.mjs

@@ -106,22 +106,32 @@ try {
   const tools = await a.client.listTools();
   checks.brainSyncDiscoverable = tools.tools?.some((tool) => tool.name === 'brain_sync') === true;
 
-  const aStart = await a.client.callTool({
-    name: 'brain_sync',
-    arguments: {
-      phase: 'start',
-      intent: 'Validate automatic Codex Context Gateway coordination',
-      files: ['src/conformance-overlap.ts'],
-    },
-  });
-  const bStart = await b.client.callTool({
-    name: 'brain_sync',
-    arguments: {
-      phase: 'start',
-      intent: 'Validate proactive overlap delivery from a second session',
-      files: ['src/conformance-overlap.ts'],
-    },
-  });
+  const syncStart = async (client, intent, expectedTasks) => {
+    let response;
+    for (let attempt = 1; attempt <= 3; attempt++) {
+      response = await client.callTool({
+        name: 'brain_sync',
+        arguments: {
+          phase: 'start',
+          intent,
+          files: ['src/conformance-overlap.ts'],
+        },
+      });
+      const structured = response.structuredContent || {};
+      if (Number.isFinite(structured.timingMs?.total)
+        && structured.counts?.activeTasks === expectedTasks) return { response, attempt };
+      await wait(75);
+    }
+    return { response, attempt: 3 };
+  };
+  // The lane is deliberately lock-protected and the two real clients heartbeat
+  // concurrently. A bounded retry proves convergence without turning one
+  // transient lock collision into a false product failure.
+  const aStarted = await syncStart(a.client, 'Validate automatic Codex Context Gateway coordination', 1);
+  const bStarted = await syncStart(b.client, 'Validate proactive overlap delivery from a second session', 2);
+  const aStart = aStarted.response;
+  const bStart = bStarted.response;
+  metrics.startAttempts = { first: aStarted.attempt, second: bStarted.attempt };
   const aStructured = aStart.structuredContent || {};
   const bStructured = bStart.structuredContent || {};
   checks.taskMemory = Array.isArray(aStructured.context?.hits) && aStructured.context.hits.length > 0;
@@ -144,16 +154,25 @@ try {
   metrics.firstClientLogCount = a.logs.length;
   if (!checks.proactiveLogging && a.logs.length) metrics.firstClientLogs = a.logs.slice(-4);
 
-  const aCheckpoint = await a.client.callTool({
-    name: 'brain_sync',
-    arguments: {
-      phase: 'checkpoint',
-      intent: 'Validate automatic Codex Context Gateway coordination',
-      files: ['src/conformance-overlap.ts'],
-    },
-  });
-  const checkpointStructured = aCheckpoint.structuredContent || {};
-  checks.guaranteedInBandDelivery = checkpointStructured.messages?.some((message) =>
+  let checkpointStructured = {};
+  let inBandAttempts = 0;
+  for (let attempt = 1; attempt <= 3; attempt++) {
+    inBandAttempts = attempt;
+    const aCheckpoint = await a.client.callTool({
+      name: 'brain_sync',
+      arguments: {
+        phase: 'checkpoint',
+        intent: 'Validate automatic Codex Context Gateway coordination',
+        files: ['src/conformance-overlap.ts'],
+      },
+    });
+    checkpointStructured = aCheckpoint.structuredContent || {};
+    if (checkpointStructured.messages?.some((message) =>
+      String(message.text).includes('Automatic KLYPIX overlap alert'))) break;
+    await wait(75);
+  }
+  metrics.inBandAttempts = inBandAttempts;
+  checks.durableInBandOffer = checkpointStructured.messages?.some((message) =>
     String(message.text).includes('Automatic KLYPIX overlap alert')) === true;
 
   await Promise.all([
@@ -188,10 +207,26 @@ try {
       && /no live session declared docs\/unowned\.md/.test(nobody.reason);
 
     const receipt = summarizeReceipts({
-      messages: [{ id: 'finding-note', from: 'finding-sender', to: 'all', text: 'verified note', ts: now - 1_000, candidateIds: ['finding-owner'], seen: ['finding-owner'] }],
+      messages: [{
+        id: 'finding-note',
+        from: 'finding-sender',
+        to: 'all',
+        text: 'verified note',
+        ts: now - 1_000,
+        candidateIds: ['finding-owner'],
+        deliveryVersion: 2,
+        deliveries: [{
+          recipientId: 'finding-owner',
+          state: 'acknowledged',
+          attempts: 1,
+          offeredAt: now - 900,
+          acknowledgedAt: now - 500,
+        }],
+        seen: ['finding-owner'],
+      }],
       sessions: lane, selfId: 'finding-sender', now,
     });
-    checks.findingReceiptRendered = /shown to all 1 peer\(s\) that were live/.test(renderReceiptSummary(receipt));
+    checks.findingReceiptRendered = /model-context delivery acknowledged by all 1 target peer\(s\) on a later action \(not human-read\)/.test(renderReceiptSummary(receipt));
   }
 
   // ── Cross-PC presence: simulated two-machine scenario ─────────────────────
@@ -305,7 +340,7 @@ const required = [
   'exactBlockingOverlap',
   'alertQueued',
   'proactiveLogging',
-  'guaranteedInBandDelivery',
+  'durableInBandOffer',
   'findingRouteOwnerReason',
   'findingRouteNobodyReason',
   'findingReceiptRendered',
@@ -323,7 +358,8 @@ const result = {
   metrics,
   contract: {
     proactive: 'best-effort MCP logging notification',
-    guaranteed: 'same alert on the next KLYPIX action',
+    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',
+    crossMachine: 'relay primitives require caller-confirmed durable insertion and a per-recipient-machine acknowledgement; app bridge wiring is a separate conformance boundary',
   },
 };
 
@@ -336,6 +372,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; next-action delivery is guaranteed.');
+  console.log('  proactive notifications are best-effort; retained notes use offer → later-action acknowledgement, with explicit failure receipts.');
 }
 process.exit(ok ? 0 : 1);

package/bin/klypix-git-tools.mjs

@@ -12,7 +12,7 @@
 //   • ONE merge engine — the driver rides src/merge-brains.mjs verbatim.
 //   • The registered driver path is the INSTALLED runtime
 //     (~/.claude/project-brain) — stable across npx cache evictions; this
-//     module self-provisions the three engine files + their two deps there
+//     module self-provisions the four engine files + their two deps there
 //     when missing, without running the full hook installer.
 //   • A truncated list must NEVER render as complete: every capped section
 //     emits its "…and N more" through an unguarded push.
@@ -85,11 +85,11 @@ async function loadEngine() {
 
 // ── git-driver ──────────────────────────────────────────────────────────────
 
-const ENGINE_FILES = ['klypix-merge-driver.mjs', 'merge-brains.mjs', 'klypix-format.mjs'];
+const ENGINE_FILES = ['klypix-merge-driver.mjs', 'merge-brains.mjs', 'klypix-format.mjs', 'brain-graveyard.mjs'];
 const ENGINE_DEPS = ['jszip', 'fractional-indexing'];
 
-// Make sure the INSTALLED runtime can actually run the driver: the three
-// engine files plus their two (dependency-free) deps. This is deliberately a
+// Make sure the INSTALLED runtime can actually run the driver: the four
+// engine files plus their two runtime deps. This is deliberately a
 // light provision — it never touches hooks or servers; the full installer
 // remains `npx klypix-mcp install`.
 function ensureDriverRuntime() {

package/bin/klypix-install.mjs

@@ -226,7 +226,7 @@ const flatten = (code) => code
     .replace(/\.\.\/src\/klypix-(core|format)\.mjs/g, './klypix-$1.mjs')
     // brain-doctor + agent-rules (the server's lazy `import('../src/brain-doctor.mjs')`
     // for the brain_doctor tool) → flat sibling refs in the runtime layout.
-    .replace(/\.\.\/src\/(brain-doctor|agent-rules|mcp-presence|mcp-supervisor|mcp-auto-update|semantic-memory|runtime-inspector|project-graph|git-capture-install)\.mjs/g, './$1.mjs')
+    .replace(/\.\.\/src\/(bench|brain-doctor|agent-presence|agent-rules|finding-routing|mcp-presence|mcp-supervisor|mcp-auto-update|presence-relay|semantic-memory|runtime-inspector|project-graph|git-capture-install|remote-client)\.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)`);
 
@@ -293,7 +293,7 @@ try {
     // canvas-view-app.html is the canvas_view MCP App UI — staged raw (an HTML
     // file must never get a JS-comment banner) beside the flat server, which
     // resolves it via its ./canvas-view-app.html candidate path.
-    for (const f of ['global-brain-hook.mjs', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'finding-routing.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', 'brain-semantic.mjs', 'semantic-memory.mjs', 'brain-note.mjs', 'brain-git-hook.mjs', 'git-capture-install.mjs', 'brain-history.mjs', 'brain-graveyard.mjs', 'klypix-format.mjs', 'klypix-core.mjs', 'brain-write-lock.mjs', 'agent-rules.mjs', 'brain-doctor.mjs', 'agent-presence.mjs', 'mcp-presence.mjs', 'result-reconcile.mjs', 'finding-routing.mjs', 'presence-relay.mjs', 'mcp-supervisor.mjs', 'mcp-auto-update.mjs', 'runtime-inspector.mjs', 'project-graph.mjs', 'remote-client.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-worker.mjs

@@ -38,6 +38,7 @@ import {
   registerProjectBrain,
   spawnAutoUpdateHelper,
 } from '../src/mcp-auto-update.mjs';
+import { remoteActions, remoteCommand, remoteSessions, remoteStatus } from '../src/remote-client.mjs';
 // Namespace import (already in-process via the klypix-core chain, so zero added
 // load cost) so a bundle whose klypix-format predates classifyDecay degrades
 // gracefully — a named import of a missing export would kill the whole server.
@@ -224,6 +225,85 @@ const toContent = (r) => {
   return mcpPresence.decorateToolResult(result);
 };
 
+const remoteToolResult = (label, value) => mcpPresence.decorateToolResult({
+  content: [{ type: 'text', text: `${label}\n\n${JSON.stringify(value, null, 2)}` }],
+  structuredContent: { result: value },
+});
+const remoteToolError = (error) => {
+  const message = typeof error?.message === 'string' && /^KLYPIX_[A-Z0-9_]+$/.test(error.message)
+    ? error.message : 'KLYPIX_REMOTE_REQUEST_REJECTED';
+  return mcpPresence.decorateToolResult({
+    content: [{ type: 'text', text: `${message}. The KLYPIX desktop window may be closed, but its tray relay must be running and Remote control must be enabled.` }],
+    isError: true,
+  });
+};
+
+server.registerTool('remote_status', {
+  title: 'Inspect the local KLYPIX Remote relay',
+  description: 'Reports whether the KLYPIX tray relay, discovery, provider hooks, verified controls, phone pairing, and encrypted network relay are active. The desktop WINDOW may be closed; KLYPIX must still be running in the tray and the PC must be awake.',
+  annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema: {},
+}, async () => {
+  try { return remoteToolResult('KLYPIX Remote status', await remoteStatus()); }
+  catch (error) { return remoteToolError(error); }
+});
+
+server.registerTool('remote_sessions', {
+  title: 'List coding-agent sessions by KLYPIX project',
+  description: 'Lists local coding-agent sessions with their project/path binding, current state, active host binding, and exact capability receipts. Treat each receipt as the truth for that specific provider + version + live session; never infer a missing action. The KLYPIX tray relay must be running.',
+  annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema: {
+    project_id: z.string().max(2048).optional().describe('Optional exact KLYPIX project id from a prior session result.'),
+  },
+}, async ({ project_id }) => {
+  try { return remoteToolResult('KLYPIX Remote sessions', await remoteSessions({ projectId: project_id })); }
+  catch (error) { return remoteToolError(error); }
+});
+
+server.registerTool('remote_actions', {
+  title: 'List pending coding-agent decisions',
+  description: 'Lists pending questions, permission requests, confirmations, failures, conflicts, and reviews reported by supported provider hooks. Approval/rejection still requires the exact session capability receipt and request digest. The KLYPIX tray relay must be running.',
+  annotations: { destructiveHint: false, idempotentHint: true, openWorldHint: false },
+  inputSchema: {},
+}, async () => {
+  try { return remoteToolResult('KLYPIX Remote actions', await remoteActions()); }
+  catch (error) { return remoteToolError(error); }
+});
+
+server.registerTool('remote_command', {
+  title: 'Control one verified coding-agent session',
+  description: 'Sends one command to the exact machine/provider/session and host binding named by a fresh remote_sessions capability receipt. Supports opening the exact provider session, messages, images/files, interrupt, approve/reject, close/archive/resume only when that exact receipt says the operation is available. File paths are local to this PC. The KLYPIX tray relay must be running and verified controls enabled.',
+  annotations: { destructiveHint: true, idempotentHint: false, openWorldHint: false },
+  inputSchema: {
+    machine_id: z.string().min(1).max(256),
+    provider: z.enum(['antigravity-agent', 'claude-code', 'codex', 'cursor-agent', 'gemini-cli', 'grok-build', 'kimi-code', 'opencode', 'pi', 'qoder', 'mistral-vibe', 'unknown']),
+    external_session_id: z.string().min(1).max(512),
+    operation: z.enum(['send-text', 'send-message', 'attach-image', 'attach-file', 'interrupt', 'approve', 'reject', 'close', 'archive', 'resume', 'open-provider']),
+    capability_receipt_id: z.string().min(1).max(256).describe('Fresh receipt id for this exact operation from remote_sessions.'),
+    binding_id: z.string().min(1).max(256).describe('Fresh host binding id named by the receipt.'),
+    request_digest: z.string().regex(/^[0-9a-f]{64}$/).optional().describe('Required for approve/reject; copy it from the pending remote action.'),
+    text: z.string().min(1).max(20000).optional(),
+    replace_draft: z.boolean().optional(),
+    attachments: z.array(z.object({
+      path: z.string().min(1).max(2048).describe('Absolute local file path on this PC.'),
+      kind: z.enum(['image', 'video', 'audio', 'document', 'file']),
+      mime_type: z.string().min(1).max(128).optional(),
+    })).max(25).optional(),
+  },
+}, async ({ machine_id, provider, external_session_id, operation, capability_receipt_id, binding_id, request_digest, text, replace_draft, attachments }) => {
+  try {
+    const receipt = await remoteCommand({
+      machineId: machine_id, provider, externalSessionId: external_session_id, operation,
+      capabilityReceiptId: capability_receipt_id, bindingId: binding_id,
+      requestDigest: request_digest, text, replaceDraft: replace_draft,
+      attachments: attachments?.map((attachment) => ({
+        path: attachment.path, kind: attachment.kind, mimeType: attachment.mime_type,
+      })),
+    });
+    return remoteToolResult('KLYPIX Remote command receipt', receipt);
+  } catch (error) { return remoteToolError(error); }
+});
+
 server.registerTool('list_canvases', {
   title: 'List KLYPIX canvases',
   description: 'List all .klypix / .any canvas files in the vault, with card and connection counts.',
@@ -413,8 +493,9 @@ server.registerTool('brain_insights', {
   inputSchema: {
     canvas: z.string().optional().describe('Canvas filename/path. Defaults to the project brain ("brain").'),
     staleDays: z.number().optional().describe('Open questions older than this many days count as stale (default 21).'),
+    view: z.enum(['full', 'areas', 'status']).optional().describe('"areas" = a cheap category map (what sections exist + live counts) to orient BEFORE retrieving. "status" = where each active area stands (newest milestone + open count). "full" (default) = hubs, orphans, stale questions and areas.'),
   },
-}, async ({ canvas, staleDays }) => toContent(await opBrainInsights({ vault: mcpPresence.vault, canvas, staleDays })));
+}, async ({ canvas, staleDays, view }) => toContent(await opBrainInsights({ vault: mcpPresence.vault, canvas, staleDays, view })));
 
 server.registerTool('brain_lens', {
   title: 'Brain lens — machine-readable views of a brain (freshness · provenance · activity · timeline · orrery · unresolved)',
@@ -425,8 +506,9 @@ server.registerTool('brain_lens', {
     root: z.string().optional().describe('Orrery center: a card title prefix or id. Default: the most-connected hub card.'),
     staleDays: z.number().optional().describe('Open questions older than this count as stale (default 21).'),
     limit: z.number().optional().describe('Cap for recent-activity entries (default 30).'),
+    structured: z.boolean().optional().describe('Also return the full machine-readable lens object (large — tens of KB). Default false: the markdown answers the question, and the object was previously attached to every call whether or not anything read it.'),
   },
-}, async ({ canvas, view, root, staleDays, limit }) => toContent(await opBrainLens({ vault: mcpPresence.vault, canvas, view, root, staleDays, limit })));
+}, async ({ canvas, view, root, staleDays, limit, structured }) => toContent(await opBrainLens({ vault: mcpPresence.vault, canvas, view, root, staleDays, limit, structured })));
 
 server.registerTool('brain_connect', {
   title: 'Connect related-but-unlinked brain cards (densify the graph)',
@@ -509,7 +591,7 @@ server.registerTool('brain_note', {
 
 server.registerTool('brain_message', {
   title: 'Message the other live agent sessions on this project (one-time note, not a brain card)',
-  description: 'Leave a DELIBERATE, targeted note for the OTHER active agent sessions working on this project right now ("merged the hook refactor — rebase before you commit", "don\'t touch canvasStore, mid-refactor"). Any MCP client can send and receive through the shared presence lane. Hookless MCP peers receive each note once on their next KLYPIX tool call (and may also see a host logging notification); lifecycle hooks provide more proactive delivery. Delivery is BEST-EFFORT, not guaranteed: the lane is machine-local and OS-user-local (a teammate on another machine never sees it) and a peer that takes no KLYPIX action within the 24h TTL misses the note entirely — so never tell the user a note was received. Ephemeral (expires in 24h) and NOT persisted to the brain — for a durable decision use brain_note instead.',
+  description: 'Leave a DELIBERATE, targeted note for the OTHER active agent sessions working on this project right now ("merged the hook refactor — rebase before you commit", "don\'t touch canvasStore, mid-refactor"). Any MCP client can send and receive through the shared machine-local presence lane. A supported lifecycle event or KLYPIX tool result offers the note into model-visible context; a later independent supported action acknowledges that offer. Pending/offered notes replay after reconnect, while expiry or capacity loss leaves a failed per-recipient receipt instead of silently disappearing. Acknowledged means a later action followed the offer — it is NOT proof a human read it. Delivery remains OS-user-local, machine-local, bounded by a 24h TTL, and unavailable to a peer that never takes a supported action. 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 hint — a peer session id-prefix or branch name; omit or "all" for every live session.'),
@@ -518,12 +600,23 @@ server.registerTool('brain_message', {
 }, async ({ text, to, canvas }) => {
   let via; try { via = server.server.getClientVersion()?.name; } catch { /* optional */ }
   mcpPresence.noteSent(text);
-  return toContent(await opBrainMessage({ vault: mcpPresence.vault, canvas, text, to, via }));
+  return toContent(await opBrainMessage({
+    vault: mcpPresence.vault,
+    // Bind the default message lane to the brain this worker actually joined.
+    // The worker process can be launched from an IDE/install directory that has
+    // a different ancestor brain; falling back to process.cwd() would split the
+    // sender presence and its message across two unrelated project lanes.
+    canvas: canvas || mcpPresence.brainPath,
+    text,
+    to,
+    via,
+    from: mcpPresence.refreshIdentity(),
+  }));
 });
 
 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. 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 is machine-local and OS-user-local (a teammate on another machine is invisible), and overlap is ADVISORY — nothing is blocked.',
+  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.',
   annotations: {
     destructiveHint: false,
     idempotentHint: true,
@@ -534,11 +627,24 @@ server.registerTool('brain_sync', {
     intent: z.string().max(160).optional().describe('One sentence describing the current task. Supply for start/checkpoint; completion clears it.'),
     files: z.array(z.string()).max(20).optional().describe('Project-relative files you expect to touch or have touched. Exact overlaps with peers are flagged.'),
     phase: z.enum(['start', 'checkpoint', 'complete']).optional().describe('start replaces prior task scope; checkpoint merges changed scope; complete clears task intent/files. Default: checkpoint.'),
-    include_context: z.boolean().optional().describe('Include fast task-relevant brain cards in the same response. Defaults true; ignored for phase complete.'),
+    include_context: z.boolean().optional().describe('Include fast task-relevant brain cards and offer queued coordination notes in the same response. Defaults true; false also defers note delivery so internal supervisor probes cannot consume model-visible messages.'),
+    // Deliberately permissive at the MCP/Zod boundary. The authoritative,
+    // versioned fail-closed validator lives in result-reconcile.mjs and must see
+    // malformed/unknown nested fields so it can persist the evidence-required
+    // marker before rejecting them. A strict transport schema rejected first,
+    // allowing a later result-less completion to bypass that state entirely.
+    results: z.unknown().optional().describe('On phase complete, 1-8 result manifests for stable claim keys. The in-handler versioned validator rejects malformed, empty, unknown-field, or incomparable evidence and retains task scope.'),
   },
-}, async ({ project, intent, files, phase, include_context }) => {
+}, async ({ project, intent, files, phase, include_context, results }) => {
   const totalStartedAt = Date.now();
-  const report = mcpPresence.sync({ project, intent, files, phase });
+  const report = mcpPresence.sync({
+    project,
+    intent,
+    files,
+    phase,
+    results,
+    deliverMessages: include_context !== false,
+  });
   // Zero-manual harness convergence: brain_sync is the one project-aware
   // gateway every MCP host can call. Register MCP-only projects here (Claude's
   // lifecycle hook is no longer the sole registry writer), then reconcile only
@@ -624,6 +730,7 @@ server.registerTool('brain_sync', {
       text: [report.text, harnessText, shipNotice, contextText, timingText].filter(Boolean).join('\n\n'),
     }],
     structuredContent,
+    ...(report.isError ? { isError: true } : {}),
   };
 });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.65.0",
+  "version": "1.66.1",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -53,6 +53,7 @@
     "./core": "./src/klypix-core.mjs",
     "./presence": "./src/agent-presence.mjs",
     "./mcp-presence": "./src/mcp-presence.mjs",
+    "./result-reconcile": "./src/result-reconcile.mjs",
     "./presence-relay": "./src/presence-relay.mjs",
     "./supervisor": "./src/mcp-supervisor.mjs",
     "./runtime-inspector": "./src/runtime-inspector.mjs",
@@ -76,10 +77,11 @@
     "node": ">=18"
   },
   "scripts": {
+    "test:remote": "node test/remote-client.mjs",
     "test:project-graph": "node test/project-graph.mjs",
     "bench": "node bin/klypix-mcp.mjs bench",
     "test:bench": "node test/bench.mjs",
-    "test": "node test/publish-verdict.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/agent-presence.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/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.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/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
+    "test": "node test/publish-verdict.mjs && node test/remote-client.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/agent-presence.mjs && node test/result-reconcile.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/context-gateway.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.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/skill-staleness.mjs && node test/canvas-view.mjs && node test/status-completeness.mjs && node test/semantic-gate.mjs && node test/memory-runtime.mjs && node test/semantic-cache.mjs && node test/decay-status.mjs && node test/decay-hook.mjs && node test/evidence-anchors.mjs && node test/presence-visibility.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/a2a-smoke.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.mjs",
     "test:memory": "node test/memory-runtime.mjs",
     "test:memory:soak": "node --expose-gc test/memory-soak.mjs",
     "runtime": "node bin/klypix-runtime.mjs"