klypix-mcp 1.72.0 → 1.73.2

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 26 tools, and not the retrieval engine.
+It verifies 15 required coordination behaviours — not the 22 tools, and not the retrieval engine.
 
 ---
 
@@ -102,7 +102,7 @@ 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       lossless .klypix merge driver registered
-  verified  ✓ 26 tools reachable via .mcp.json (892ms)
+  verified  ✓ 22 tools reachable via .mcp.json (892ms)
 ```
 
 That last line is the point. MCP config fails **silently** — a wrong entry means the server never
@@ -542,10 +542,6 @@ The MCP verbs below are what agents call. These are what **you** call:
 | `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 |

package/bin/klypix-install.mjs

@@ -246,7 +246,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\/(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(/\.\.\/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)\.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)`);
 
@@ -380,7 +380,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', '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', 'remote-client.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', '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-worker.mjs

@@ -39,7 +39,6 @@ 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.
@@ -408,91 +407,6 @@ const toContent = (r) => {
   return result;
 };
 
-// Return raw MCP results here. The universal registerTool wrapper above owns
-// the single presence/message transition for every non-brain_sync call. A
-// helper-level decoration would offer and then acknowledge one note inside the
-// same Remote call, violating delivery-v3's later-action invariant.
-const remoteToolResult = (label, value) => ({
-  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 {
-    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,
-  };
-};
-const remoteProjectRoot = () => (mcpPresence.brainPath ? path.dirname(mcpPresence.brainPath) : null);
-
-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({ projectRoot: remoteProjectRoot() })); }
-  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: {},
-}, async () => {
-  try { return remoteToolResult('KLYPIX Remote sessions', await remoteSessions({ projectRoot: remoteProjectRoot() })); }
-  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({ projectRoot: remoteProjectRoot() })); }
-  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: true },
-  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 }, extra) => {
-  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,
-      })),
-    }, {
-      projectRoot: remoteProjectRoot(),
-      actionIdentity: extra.klypixRequestIdentity?.actionId,
-    });
-    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.',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "klypix-mcp",
-  "version": "1.72.0",
+  "version": "1.73.2",
   "description": "Shared project brain and MCP coordination server for multi-agent coding.",
   "type": "module",
   "license": "Apache-2.0",
@@ -79,12 +79,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",
     "pretest": "node test/publish-workflow.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/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.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-security.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/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/git-tools.mjs && node test/uninstall.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/request-identity.mjs && node test/session-identity-core.mjs && node test/agent-presence.mjs && node test/message-delivery-v3.mjs && node test/claude-message-delivery-v3.mjs && node test/result-reconcile.mjs && node test/evidence-publication-gate.mjs && node test/release-evidence-cli.mjs && node test/intent-guard.mjs && node test/git-capture-install.mjs && node test/brain-history.mjs && node test/brain-graveyard.mjs && node test/archived-visibility.mjs && node test/finding-routing.mjs && node test/finding-routing-hook.mjs && node test/presence-relay.mjs && node test/install-version.mjs && node test/install-rename-backoff.mjs && node test/project-binding-rebind.mjs && node test/context-gateway.mjs && node test/repo-state.mjs && node test/released-tag-guard.mjs && node test/conformance.mjs && node test/brain-doctor.mjs && node test/version-currency.mjs && node test/ship-capture.mjs && node test/lane-message.mjs && node test/brain-quality.mjs && node test/brain-connect-orphans.mjs && node test/orphan-gardener.mjs && node test/brief-and-recall.mjs && node test/layout-cluster.mjs && node test/brain-ask.mjs && node test/retrieval-fusion.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-security.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/undeclared-active.mjs && node test/presence-liveness.mjs && node test/observed-scope.mjs && node test/release-lease.mjs && node test/release-ancestry.mjs && node test/release-handshake.mjs && node test/completion-guard.mjs && node test/merge-brains.mjs && node test/concurrent-writes.mjs && node test/lock-interop.mjs && node test/capture-write-failure.mjs && node test/a2a-smoke.mjs && node test/one-command-setup.mjs && node test/cli-args.mjs && node test/format-guard.mjs && node test/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"

package/src/mcp-presence.mjs

@@ -598,6 +598,12 @@ const publicSession = (session, now) => {
 // Only real prompt/tool work stamps activityAt; heartbeats deliberately
 // preserve it, so a fresh stamp means work, not merely a live socket.
 const UNDECLARED_ACTIVE_MS = 10 * 60 * 1000;
+
+// How much of the ~2h release lease must remain before the HOLDER is warned.
+// 25 minutes is longer than a full desktop candidate build + verify, so a
+// holder who sees the warning still has time to finish or refresh rather than
+// losing the lease mid-release.
+const RELEASE_LEASE_WARN_MS = 25 * 60 * 1000;
 const isUndeclaredActive = (session, now) =>
   !isTaskSession(session)
   && Number(session?.activityAt || 0) > 0
@@ -1829,6 +1835,11 @@ export function createMcpPresence({
       : undefined;
     if (started && resolved === vault
       && (selectedBrainPath === undefined || selectedBrainPath === brainPath)) {
+      // Same reason as the sync() adoption above: a reconnect to the vault we
+      // are already on must still re-adopt the freshly validated binding, or a
+      // brain rewritten since the last bind leaves this connection guarded by a
+      // dead inode.
+      if (validatedSelection?.projectBinding) currentProjectBinding = validatedSelection.projectBinding;
       return touch({ event: 'McpReconnect', includePresence: true });
     }
     if (started) stop({
@@ -2299,6 +2310,19 @@ export function createMcpPresence({
       clientInfoPrepared: preparedClientInfo,
       branchPrepared: preparedBranch,
     };
+    // Adopt the preflight's binding on BOTH arms, not just the start() arm.
+    // A same-project re-sync takes touch(), which never reassigns — so the
+    // guard kept comparing a binding whose brain inode had already been retired
+    // by an atomic write (every managed brain write is writeFileSync+rename, so
+    // ANY write by anyone, including this session's own Stop hook, mints a new
+    // inode). The result was a permanent deadlock: brain_sync succeeded and
+    // reported the right project while every other verb was rejected, and the
+    // only refresh path was itself gated behind the failing check. This binding
+    // was already validated three times earlier in THIS call (preflightSync →
+    // consumeSyncPreflight → revalidateConsumedSyncPreflight), so adopting it is
+    // strictly more current than retaining the stale one and grants no new
+    // authority — the canonical-root and escape checks already ran on it.
+    if (projectBinding) currentProjectBinding = projectBinding;
     let report = started && requestedVault === vault && resultBrainPath === brainPath
       ? touch(details)
       : start(requestedVault, details, {
@@ -2454,6 +2478,10 @@ export function createMcpPresence({
     {
       const leaseStamp = now();
       let outcome = null;
+      // Set when the holder's own sync arrived with the lease already close to
+      // lapsing; reported after the refresh so the holder learns the habit that
+      // protects them, not merely that nothing broke this time.
+      let nearExpiryBeforeRefreshMs = null;
       if (releaseIntentChecked.provided && completing) {
         // The DECLARATION is ignored on completion, but a REAL completion must
         // still free a lease this session holds — a holder who kept attaching
@@ -2528,6 +2556,17 @@ export function createMcpPresence({
         const freed = freeReleaseLease({ brainPath, sessionId, home, now: leaseStamp });
         if (freed.status === 'released') outcome = freed;
       } else if (!completing) {
+        // Snapshot BEFORE the refresh. A holder's sync refreshes the lease, so
+        // by the time we report, expiry has already moved out and "expiring
+        // soon" is never true — yet the risk was real a millisecond earlier.
+        // The field failure was a holder who ran a 40-minute build with no
+        // sync in it and lost the lease silently; the useful moment to say so
+        // is the sync that arrives while the clock is still low.
+        const preRefresh = readReleaseLease({ brainPath, home, now: leaseStamp });
+        if (preRefresh && preRefresh.holderId === sessionId && preRefresh.expiresAt) {
+          const leftBefore = Math.max(0, preRefresh.expiresAt - leaseStamp);
+          if (leftBefore <= RELEASE_LEASE_WARN_MS) nearExpiryBeforeRefreshMs = leftBefore;
+        }
         const refreshed = refreshReleaseLease({ brainPath, sessionId, home, now: leaseStamp });
         // 'lease-lost' = THIS session held the lease but it lapsed (TTL passed
         // with no checkpoint). Surfacing it beats silent pruning: a holder who
@@ -2626,6 +2665,26 @@ export function createMcpPresence({
         releaseText = `KLYPIX release lease freed: completion released the exclusive release lease (v${outcome.lease?.version} from ${outcome.lease?.ref}).`;
       } else if (active) {
         releaseLease = { status: 'held', holder: holderBlock };
+        // The holder must never learn about expiry by noticing the footer
+        // vanished — which is exactly what happened in the field on
+        // 2026-08-16, mid-release-build. The 'lease-lost' message this design
+        // relies on is UNREACHABLE in any project that has peers: a non-holder's
+        // sync meets the expired lease first, prunes it (status 'stale-pruned',
+        // write:true, lease:null) and is told nothing, so the holder's next sync
+        // takes the no-lease fast path and never reaches the lease-lost branch.
+        // Warning while the lease still EXISTS is therefore the last moment the
+        // holder can still act on it, and it needs no cross-session state.
+      }
+      // Holder-facing expiry telemetry, attached to whichever branch produced
+      // the block. Always reporting expiresInMs is half the fix on its own: the
+      // holder can see the clock instead of inferring it from a footer.
+      if (releaseLease && holderBlock && holderBlock.sessionId === sessionId && holderBlock.expiresAt) {
+        releaseLease.expiresInMs = Math.max(0, holderBlock.expiresAt - leaseStamp);
+        if (nearExpiryBeforeRefreshMs !== null) {
+          releaseLease.expiringSoon = true;
+          releaseLease.nearExpiryBeforeRefreshMs = nearExpiryBeforeRefreshMs;
+          releaseText = `KLYPIX release lease expires in ~${Math.max(1, Math.round(nearExpiryBeforeRefreshMs / 60000))} min — refreshed by this sync. Only a brain_sync from THIS session refreshes it, so a long build with no sync in it will let the lease lapse, and a peer then prunes it without telling you.`;
+        }
       }
       // ── Would this release leave finished work behind? (1.72.0) ──────────
       // Coordination in this engine had always been about files two sessions