clawmatrix 0.6.1 → 0.6.3

package/cli/skills/clawmatrix/SKILL.md

@@ -3,58 +3,102 @@ name: clawmatrix
 description: Use the clawmatrix CLI to interact with remote devices (phones, computers, servers) in a mesh cluster — run tools, check location, get battery status, read/write files, execute commands, and more on any connected node.
 ---
 
-Use the `clawmatrix` CLI to interact with the ClawMatrix mesh cluster. Remote nodes can be phones (iPhone/Android), computers, or servers.
+Use the `clawmatrix` CLI to interact with the ClawMatrix mesh cluster. Remote nodes can be phones (iPhone/Android), computers, or servers. You can invoke any tool available on remote nodes — including getting device location, battery status, running shell commands, reading/writing files, and more.
 
-Run `clawmatrix --help` or `clawmatrix <command> --help` for detailed usage.
+All commands output LLM-friendly text (no ANSI colors) when stdout is not a TTY.
 
-## Capabilities
+## Quick Start
 
-**Cluster & Discovery**
-- View cluster topology, peer status, node config, and uptime/availability
-- Check reachability of specific nodes with latency
-- Approve/deny/revoke peer connections
+1. Run `clawmatrix status` to see connected nodes and their capabilities
+2. Run `clawmatrix tools <nodeId>` to see what tools a node offers
+3. Run `clawmatrix call <nodeId> <tool> '<params>'` to invoke a tool
 
-**Remote Tool Execution**
-- Discover tools across all nodes (filter by keyword, describe params)
-- Invoke single tools or batch multiple in one round-trip
-- Tools include device-specific capabilities: location, battery, camera, clipboard, contacts, calendar, health data, HomeKit, etc.
+## Cluster Status
 
-**Models**
-- List all LLM models available across the cluster, filterable by node
+```bash
+clawmatrix status          # Cluster topology: peers, agents, models, tags
+clawmatrix status --json   # Structured JSON output
+clawmatrix check <nodeId>  # Quick reachability check with latency
+```
 
-**Agent Delegation**
-- `handoff` — delegate tasks to remote agents with streaming output and failover
-- `send` — fire-and-forget messages to remote nodes
-- `acp` — manage persistent coding agent sessions (Claude Code, Codex, Gemini) with prompt/resume/cancel/close
+Always start with `clawmatrix status` to understand the current topology before performing other operations.
 
-**Events & Automations**
-- Query, consume, and ingest events from external sources (iOS Shortcuts, webhooks, etc.)
-- Manage automation rules: list, create/save, manually trigger, replay historical executions
+## Remote Tools
 
-**Infrastructure**
-- `diagnostic` — sentinel-based diagnostics (works even when gateway is down)
-- `terminal` — interactive PTY sessions on remote nodes
-- `transfer` — push/pull files up to 100MB between nodes with integrity verification
-- `notify` — push Dynamic Island / Live Activity notifications to iOS devices
+```bash
+clawmatrix tools                        # List all remote tools (compact)
+clawmatrix tools <nodeId>               # Tools on a specific node
+clawmatrix tools --describe <tool>      # Full usage and parameter schema
+clawmatrix tools --filter <keyword>     # Search by name or description
+```
 
-**Knowledge Sync (CRDT)**
-- List synced workspace files, view change history, line-by-line blame, read file content
-- All knowledge is CRDT-based and mesh-synced across nodes
+Use `--describe` to understand a tool's parameters before calling it.
 
-**Kanban Board**
-- Distributed task board: create, list, get, update, claim, move, annotate, delete cards
-- Filter by stage/priority/label/node; stages flow from `backlog` → `done` → `archived`
+## Invoke Tools
 
-**Config Management**
-- View runtime config summary
-- Read/write config files under `~/.openclaw/` (for remote node configuration)
+```bash
+clawmatrix call <nodeId> <tool> '<json-params>'    # Single tool invocation
+clawmatrix call <nodeId> <tool> '<json-params>' -t 30000  # With timeout (ms)
+```
 
-## Important Notes
+```bash
+clawmatrix batch <nodeId> '[{"tool":"t1","params":{}},{"tool":"t2","params":{}}]'
+clawmatrix batch <nodeId> --no-stop-on-error '[...]'  # Continue on failure
+```
 
-- **Always start with `clawmatrix status`** to understand the cluster topology before other operations
-- **Use `clawmatrix tools --describe <tool>`** to check a tool's parameter schema before calling it
-- **Use `clawmatrix notify` proactively during long tasks** (builds, tests, large refactors) so the user can track progress on their phone without watching the terminal
-- Output is **LLM-optimized**: no ANSI colors and compact format when stdout is not a TTY; add `--json` for structured output
-- Target nodes by exact `nodeId` or by tag expression `tags:<tag>`
-- Most commands support `--json` for structured output
-- `batch` and `automations save` support stdin for piping data
+Batch supports stdin: `echo '<json>' | clawmatrix batch <nodeId>`
+
+## Models
+
+```bash
+clawmatrix models                   # All cluster models
+clawmatrix models --node <nodeId>   # Filter by node
+```
+
+## Events
+
+```bash
+clawmatrix events                       # Unconsumed events
+clawmatrix events --type <type>         # Filter by type
+clawmatrix events --source <nodeId>     # Filter by source node
+clawmatrix events --consume <id1,id2>   # Mark events as consumed
+clawmatrix events --all                 # Include consumed events
+```
+
+## Peer Approval
+
+```bash
+clawmatrix approve <approvalId>         # Approve a pending peer
+clawmatrix deny <approvalId>            # Deny a pending peer
+clawmatrix approval list                # List pending/approved/denied peers
+clawmatrix approval revoke <nodeId>     # Revoke an approved peer
+```
+
+## Notifications (Dynamic Island / Live Activity)
+
+Push progress notifications to the user's iPhone via `clawmatrix notify`. This triggers the Dynamic Island and lock screen Live Activity.
+
+**Use this proactively when running long tasks** (iOS builds, large refactors, test suites, batch operations) so the user can track progress without watching the terminal.
+
+```bash
+# Start a notification
+clawmatrix notify "iOS 构建" --detail "正在编译..."
+# Returns: {"taskId":"<id>", "action":"start", "targets":1}
+
+# Update progress
+clawmatrix notify "iOS 构建" --action update --task-id <id> --detail "链接中..." --progress 80
+
+# End (success)
+clawmatrix notify "iOS 构建" --action end --task-id <id>
+```
+
+Options: `--detail <text>`, `--progress <0-100>`, `--action start|update|end`, `--task-id <id>`, `--tool <name>`
+
+## Workflow
+
+1. Run `clawmatrix status` to see the cluster topology
+2. Use `clawmatrix tools --filter <keyword>` to find relevant tools
+3. Use `clawmatrix tools --describe <tool>` to check parameters
+4. Use `clawmatrix call` or `clawmatrix batch` to invoke tools
+5. If a call fails, run `clawmatrix check <nodeId>` to verify connectivity
+6. For long-running tasks, use `clawmatrix notify` to push progress to the user's phone

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.6.1",
+  "version": "0.6.3",
   "description": "Decentralized mesh cluster plugin for OpenClaw — inter-gateway communication, model proxy, task handoff, and tool proxy.",
   "type": "module",
   "license": "MIT",

package/src/acp-proxy.ts

@@ -2626,6 +2626,42 @@ export class AcpProxy {
     return null;
   }
 
+  /** Reject a specific pending request by frame id (e.g. from relay_fail). */
+  rejectPending(frameId: string, reason: string) {
+    const entry = this.pending.get(frameId);
+    if (entry) {
+      clearTimeout(entry.timer);
+      this.pending.delete(frameId);
+      entry.reject(new Error(reason));
+    }
+  }
+
+  /**
+   * Fail-fast all pending requests targeting a disconnected node (or nodes
+   * that were reachable only via that node as relay).
+   * Called by ClusterRuntime on peerDisconnected.
+   */
+  onPeerDisconnected(nodeId: string) {
+    for (const [id, entry] of this.pending) {
+      const target = entry.targetNodeId;
+      if (!target) continue;
+      // Direct match: request was targeting the disconnected node
+      if (target === nodeId) {
+        clearTimeout(entry.timer);
+        this.pending.delete(id);
+        entry.reject(new Error(`Node "${target}" disconnected while request was pending`));
+        continue;
+      }
+      // Relay match: request was targeting a node reachable via the disconnected relay
+      const route = this.peerManager.router.getRoute(target);
+      if (!route || (!route.connection?.isOpen && !route.reachableVia)) {
+        clearTimeout(entry.timer);
+        this.pending.delete(id);
+        entry.reject(new Error(`Node "${target}" became unreachable (relay "${nodeId}" disconnected)`));
+      }
+    }
+  }
+
   private sendRequest(
     targetNodeId: string,
     agent: string,

package/src/cluster-service.ts

@@ -175,6 +175,9 @@ export class ClusterRuntime {
       this.refreshDiscoveredModels();
       this.healthTracker.recordPeerOffline(nodeId);
       this.healthTracker.removePeerSync(nodeId);
+      // Fail-fast any pending requests targeting this node or relayed through it
+      this.acpProxy?.onPeerDisconnected(nodeId);
+      this.handoffManager?.onPeerDisconnected(nodeId);
     });
 
     this.peerManager.on("peerCapabilitiesChanged", () => {
@@ -275,7 +278,12 @@ export class ClusterRuntime {
     // Auto-detect ACP agents if ACP is enabled but no agents are explicitly configured
     // Check both ClawMatrix and OpenClaw configs (consistent with acpProxy creation above)
     if (this.acpProxy && (!this.config.acp?.agents || this.config.acp.agents.length === 0)) {
-      AcpProxy.detectAvailableAgents(this.config.acp?.commands).then((detected) => {
+      const openclawAcp = (this.openclawConfig as Record<string, any>).acp;
+      const detectionCommands = {
+        ...(openclawAcp?.commands && typeof openclawAcp.commands === "object" ? openclawAcp.commands : {}),
+        ...(this.config.acp?.commands ?? {}),
+      };
+      AcpProxy.detectAvailableAgents(Object.keys(detectionCommands).length > 0 ? detectionCommands : undefined).then((detected) => {
         if (detected.length > 0) {
           this.logger.info(`[clawmatrix] Auto-detected ACP agents: ${detected.map((a) => a.id).join(", ")}`);
           this.peerManager.updateAcpAgents(detected);
@@ -891,6 +899,22 @@ export class ClusterRuntime {
           this.apiHandler.pushKanbanEvent(kf.payload);
         }
         break;
+      case "relay_fail": {
+        // A relay node could not forward our frame to its target.
+        // Clean up the stale relay route and reject pending requests.
+        const target = (frame.payload as any)?.target ?? "unknown";
+        debug("dispatch", `relay_fail id=${frame.id} target=${target} from=${frame.from}`);
+        // Remove the stale relay route so we don't keep sending frames into a dead path
+        if (typeof target === "string" && target !== "unknown") {
+          this.peerManager.router.removeRelayRoute(target);
+        }
+        if (frame.id) {
+          this.acpProxy?.rejectPending(frame.id, `Relay "${frame.from}" cannot reach "${target}"`);
+          this.handoffManager?.rejectPending(frame.id, `Relay "${frame.from}" cannot reach "${target}"`);
+          this.toolProxy.rejectPending(frame.id, `Relay "${frame.from}" cannot reach "${target}"`);
+        }
+        break;
+      }
     }
   }
 

package/src/connection.ts

@@ -147,7 +147,17 @@ export class Connection extends EventEmitter<ConnectionEvents> {
 
   /** Bind standard WebSocket event listeners. Call this for outbound connections. */
   bindWebSocket(ws: WebSocket) {
-    ws.addEventListener("message", (ev) => this.onRawMessage(ev.data));
+    // Node.js 22+ built-in WebSocket defaults binaryType to "blob", which
+    // onRawMessage cannot handle (Blob is async-only).  Set "arraybuffer"
+    // so binary frames arrive as ArrayBuffer, then normalize to Buffer below.
+    if ("binaryType" in ws) {
+      (ws as any).binaryType = "arraybuffer";
+    }
+    ws.addEventListener("message", (ev) => {
+      // Normalize ArrayBuffer → Buffer for consistent handling across runtimes
+      const data = ev.data instanceof ArrayBuffer ? Buffer.from(ev.data) : ev.data;
+      this.onRawMessage(data);
+    });
     ws.addEventListener("close", (ev) => {
       this.close(ev.code, ev.reason);
     });
@@ -208,11 +218,19 @@ export class Connection extends EventEmitter<ConnectionEvents> {
 
   /** Send raw data. Buffers sent as binary frames; strings as-is; objects JSON-encoded. */
   private sendRaw(data: unknown) {
-    if (this.transport.readyState === WebSocket.OPEN) {
-      if (Buffer.isBuffer(data)) {
-        this.transport.send(data);
-      } else {
-        this.transport.send(typeof data === "string" ? data : JSON.stringify(data));
+    try {
+      if (this.transport.readyState === WebSocket.OPEN) {
+        if (Buffer.isBuffer(data)) {
+          this.transport.send(data);
+        } else {
+          this.transport.send(typeof data === "string" ? data : JSON.stringify(data));
+        }
+      }
+    } catch (err) {
+      debug("send", `sendRaw failed for ${this.remoteNodeId ?? "unknown"}: ${err}`);
+      // Transport is broken — schedule close on next tick to avoid re-entrancy
+      if (!this.closed) {
+        queueMicrotask(() => this.close(4002, "send failed"));
       }
     }
   }
@@ -269,25 +287,6 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   private async onRawMessage(data: unknown) {
     this.lastReceivedAt = Date.now();
 
-    // Debug: log data type for unauthenticated connections to diagnose auth issues
-    if (!this.authenticated && this.role === "outbound") {
-      const dtype = Buffer.isBuffer(data) ? `Buffer(${(data as Buffer).length})` :
-        data instanceof ArrayBuffer ? `ArrayBuffer(${data.byteLength})` :
-        typeof data === "string" ? `string(${data.length})` :
-        `${data?.constructor?.name ?? typeof data}`;
-      debug("auth", `onRawMessage[outbound] dataType=${dtype}`);
-    }
-
-    // Normalize non-Buffer binary types to Buffer.
-    // Node.js 24+'s built-in WebSocket (undici) delivers binary frames as Blob
-    // (binaryType "blob") or ArrayBuffer (binaryType "arraybuffer").
-    // The ws package delivers Buffer (binaryType "nodebuffer").
-    if (data instanceof ArrayBuffer) {
-      data = Buffer.from(data);
-    } else if (typeof Blob !== "undefined" && data instanceof Blob) {
-      data = Buffer.from(await data.arrayBuffer());
-    }
-
     let frame: AnyClusterFrame | undefined;
 
     // Binary frame (Buffer) — decrypt directly without base64
@@ -403,7 +402,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
     }
 
     if (frame.type === "ping") {
-      this.send({ type: "pong", from: this.nodeId, timestamp: Date.now() } as AnyClusterFrame);
+      this.sendDirect({ type: "pong", from: this.nodeId, timestamp: Date.now() } as AnyClusterFrame);
       return;
     }
     if (frame.type === "pong") {
@@ -579,7 +578,6 @@ export class Connection extends EventEmitter<ConnectionEvents> {
       }
 
       // auth_ok (decrypted from binary envelope, or plaintext legacy)
-      debug("auth", `Outbound received frame type=${frame.type} (authenticated=${this.authenticated})`);
       if (frame.type === "auth_ok") {
         const ok = frame as AuthOk;
         this.remoteNodeId = ok.payload.nodeId;
@@ -718,7 +716,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
         return;
       }
       this.lastPingSentAt = Date.now();
-      this.send({
+      this.sendDirect({
         type: "ping",
         from: this.nodeId,
         timestamp: this.lastPingSentAt,
@@ -755,7 +753,7 @@ export class Connection extends EventEmitter<ConnectionEvents> {
   close(code = 1000, reason = "normal") {
     if (this.closed) return;
     // Flush any pending batch before closing
-    this.flushBatch();
+    try { this.flushBatch(); } catch { /* transport may already be dead */ }
     this.closed = true;
     this.clearAuthTimer();
     if (this.heartbeatTimer) {

package/src/handoff.ts

@@ -744,6 +744,38 @@ export class HandoffManager {
     return false;
   }
 
+  /** Reject a specific pending request by frame id (e.g. from relay_fail). */
+  rejectPending(frameId: string, reason: string) {
+    const entry = this.pending.get(frameId);
+    if (entry) {
+      clearTimeout(entry.timer);
+      this.pending.delete(frameId);
+      entry.reject(new Error(reason));
+    }
+  }
+
+  /**
+   * Fail-fast pending handoff requests targeting a disconnected node
+   * (or nodes reachable only via that relay). Called on peerDisconnected.
+   */
+  onPeerDisconnected(nodeId: string) {
+    for (const [id, entry] of this.pending) {
+      if (entry.targetNodeId === nodeId) {
+        clearTimeout(entry.timer);
+        this.pending.delete(id);
+        entry.reject(new Error(`Node "${entry.targetNodeId}" disconnected while handoff was pending`));
+        continue;
+      }
+      // Check if the target was reachable via this relay
+      const route = this.peerManager.router.getRoute(entry.targetNodeId);
+      if (!route || (!route.connection?.isOpen && !route.reachableVia)) {
+        clearTimeout(entry.timer);
+        this.pending.delete(id);
+        entry.reject(new Error(`Node "${entry.targetNodeId}" became unreachable (relay "${nodeId}" disconnected)`));
+      }
+    }
+  }
+
   destroy() {
     if (this.staleCleanupTimer) {
       clearInterval(this.staleCleanupTimer);

package/src/index.ts

@@ -1537,291 +1537,6 @@ const plugin = {
       },
     );
 
-    // ── Availability gateway method ──────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.availability",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          const { range } = (params ?? {}) as { range?: string };
-          const validRanges = ["24h", "7d", "90d"];
-          const r = validRanges.includes(range ?? "") ? (range as "24h" | "7d" | "90d") : "24h";
-          const result = runtime.healthTracker.getAvailability(r);
-          respond(true, result);
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    // ── Automation gateway methods ──────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.rules",
-      ({ respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(true, { rules: [] });
-            return;
-          }
-          respond(true, { rules: runtime.automationManager.getRules() });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.save",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(false, { error: "Automations not available" });
-            return;
-          }
-          const { rules } = (params ?? {}) as { rules?: unknown[] };
-          if (!Array.isArray(rules)) {
-            respond(false, { error: "Missing required param: rules (array)" });
-            return;
-          }
-          await runtime.automationManager.saveRules(rules as Parameters<typeof runtime.automationManager.saveRules>[0]);
-          respond(true, { ok: true, count: rules.length });
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.history",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(true, { executions: [] });
-            return;
-          }
-          const { limit } = (params ?? {}) as { limit?: number };
-          respond(true, { executions: runtime.automationManager.getExecutions(limit ?? 50) });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.run",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(false, { error: "Automations not available" });
-            return;
-          }
-          const { ruleId, event } = (params ?? {}) as { ruleId?: string; event?: Record<string, unknown> };
-          if (!ruleId) {
-            respond(false, { error: "Missing required param: ruleId" });
-            return;
-          }
-          const evt = event ? {
-            id: nanoid(),
-            source: String(event.source || "cli"),
-            type: String(event.type || "manual"),
-            data: (event.data ?? {}) as Record<string, unknown>,
-            ts: typeof event.ts === "number" ? event.ts : Date.now(),
-            consumed: false,
-          } as import("./types.ts").IngestedEvent : undefined;
-          const execution = await runtime.automationManager.runRuleById(ruleId, evt);
-          respond(true, { ok: true, execution });
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.automations.replay",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.automationManager) {
-            respond(false, { error: "Automations not available" });
-            return;
-          }
-          const { executionId } = (params ?? {}) as { executionId?: string };
-          if (!executionId) {
-            respond(false, { error: "Missing required param: executionId" });
-            return;
-          }
-          const execution = await runtime.automationManager.replayExecution(executionId);
-          respond(true, { ok: true, execution });
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    // ── Events ingest gateway method ──────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.events.ingest",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.apiHandler) {
-            respond(false, { error: "API handler not available (listen mode required)" });
-            return;
-          }
-          const { events } = (params ?? {}) as { events?: unknown[] };
-          if (!Array.isArray(events) || events.length === 0) {
-            respond(false, { error: "Missing required param: events (non-empty array)" });
-            return;
-          }
-          const result = runtime.apiHandler.ingestEvents(events as Array<Record<string, unknown>>);
-          respond(true, { ok: true, ...result });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    // ── Board update gateway method ──────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.board.update",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.kanbanManager) {
-            respond(false, { error: "Kanban not enabled" });
-            return;
-          }
-          const { cardId, ...updates } = (params ?? {}) as {
-            cardId?: string; title?: string; description?: string;
-            priority?: string; targetNode?: string; targetAgent?: string;
-            cwd?: string; labels?: string[];
-          };
-          if (!cardId) {
-            respond(false, { error: "Missing required param: cardId" });
-            return;
-          }
-          const card = runtime.kanbanManager.updateCard(cardId, updates as Parameters<typeof runtime.kanbanManager.updateCard>[1]);
-          if (!card) {
-            respond(false, { error: `Card not found: ${cardId}` });
-            return;
-          }
-          respond(true, card);
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    // ── Config gateway method ──────────────────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.config.get",
-      ({ respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          const c = runtime.config;
-          respond(true, {
-            nodeId: c.nodeId,
-            listen: c.listen,
-            tags: c.tags,
-            agents: c.agents.map((a) => ({ id: a.id, model: a.model })),
-            models: c.models.map((m) => ({ id: m.id, provider: m.provider })),
-            e2ee: c.e2ee,
-            toolProxy: c.toolProxy ? { enabled: c.toolProxy.enabled, allow: c.toolProxy.allow, deny: c.toolProxy.deny } : undefined,
-            terminal: c.terminal,
-            acp: c.acp ? { enabled: c.acp.enabled } : undefined,
-            knowledge: c.knowledge ? { enabled: c.knowledge.enabled } : undefined,
-            proxyModels: c.proxyModels?.length ?? 0,
-            peers: c.peers?.length ?? 0,
-          });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
-    // ── Config file read/write gateway methods ──────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.config.read",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.apiHandler) {
-            respond(false, { error: "API handler not available" });
-            return;
-          }
-          const { path: configPath } = (params ?? {}) as { path?: string };
-          if (!configPath) {
-            respond(false, { error: "Missing required param: path" });
-            return;
-          }
-          const result = await runtime.apiHandler.readConfigFile(configPath);
-          respond(result.success, result);
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    api.registerGatewayMethod(
-      "clawmatrix.config.write",
-      async ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.apiHandler) {
-            respond(false, { error: "API handler not available" });
-            return;
-          }
-          const { path: configPath, content } = (params ?? {}) as { path?: string; content?: string };
-          if (!configPath || typeof content !== "string") {
-            respond(false, { error: "Missing required params: path, content" });
-            return;
-          }
-          const result = await runtime.apiHandler.writeConfigFile(configPath, content);
-          respond(result.success, result);
-        } catch (err) {
-          respond(false, { error: String(err) });
-        }
-      },
-    );
-
-    // ── Knowledge content gateway method ──────────────────────────────
-
-    api.registerGatewayMethod(
-      "clawmatrix.kb.content",
-      ({ params, respond }: GatewayRequestHandlerOptions) => {
-        try {
-          const runtime = getClusterRuntime();
-          if (!runtime.knowledgeSync) {
-            respond(false, { error: "Knowledge sync not enabled" });
-            return;
-          }
-          const { path } = (params ?? {}) as { path?: string };
-          if (!path) {
-            respond(false, { error: "Missing required param: path" });
-            return;
-          }
-          const content = runtime.knowledgeSync.getFileContent(path);
-          if (content === null) {
-            respond(false, { error: "File not found or content not yet synced" });
-            return;
-          }
-          respond(true, { path, content });
-        } catch {
-          respond(false, { error: "ClawMatrix service not running" });
-        }
-      },
-    );
-
     // Log model selection on each LLM call (fire-and-forget)
     api.on("llm_input", (event) => {
       api.logger.debug(`[clawmatrix] llm_input: provider=${event.provider} model=${event.model}`);

package/src/knowledge-sync.ts

@@ -191,6 +191,11 @@ export class KnowledgeSync {
 
   // ── Public API ─────────────────────────────────────────────────
 
+  /** The resolved workspace directory that knowledge files are synced under. */
+  get workspacePath(): string {
+    return this.opts.workspacePath;
+  }
+
   async start() {
     debug(TAG, `starting knowledge sync: workspace=${this.opts.workspacePath}`);
 
@@ -536,7 +541,7 @@ export class KnowledgeSync {
   }
 
   /** List all synced files with metadata. */
-  listSyncedFiles(): Array<{ path: string; version: number; updatedAt: number; deleted: boolean }> {
+  listSyncedFiles(): Array<{ path: string; version: number; updatedAt: number; deleted: boolean; synced: boolean }> {
     const files = this.registry.files;
     if (!files) return [];
     return Object.entries(files).map(([path, meta]) => ({
@@ -544,6 +549,7 @@ export class KnowledgeSync {
       version: meta.version,
       updatedAt: meta.updatedAt,
       deleted: meta.deleted,
+      synced: this.fileDocs.has(path) && this.fileDocs.get(path)!.content !== undefined,
     })).filter(f => !f.deleted);
   }
 

package/src/peer-manager.ts

@@ -50,6 +50,8 @@ const SKIP_DEDUP_EXPLICIT = new Set([
   // File transfer
   "file_transfer_chunk", "file_transfer_chunk_ack",
   "file_transfer_ack", "file_transfer_complete",
+  // Relay failure notification (shares id with the original request)
+  "relay_fail",
 ]);
 
 function skipDedup(type: string): boolean {
@@ -151,6 +153,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         acpAgents = config.acp.agents;
       } else if (Array.isArray(ocAcp?.allowedAgents) && ocAcp.allowedAgents.length > 0) {
         acpAgents = ocAcp.allowedAgents.map((id: string) => ({ id, description: "" }));
+      } else if (ocAcp?.commands && typeof ocAcp.commands === "object") {
+        acpAgents = Object.keys(ocAcp.commands).map((id) => ({ id, description: "" }));
       }
     }
     this.localCapabilities = {
@@ -231,6 +235,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     }
     // Start route probing for peers with multiple URLs
     this.startRouteProbing();
+    // Start periodic sweep of stale relay routes
+    this.router.startRelaySweep();
   }
 
   async stop() {
@@ -719,9 +725,15 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         debug("peer", `connectToChannel(${nodeId}): self-connection, will not reconnect`);
         return;
       }
-      // Don't reconnect warm-up pruned channels
-      if (ev.reason === "warm-up pruned") {
-        debug("peer", `connectToChannel(${nodeId}): warm-up pruned, will not reconnect`);
+      // Don't reconnect deliberate closures that shouldn't trigger reconnection
+      const skipReasons = ["warm-up pruned", "route switch", "replaced by new connection"];
+      if (skipReasons.includes(ev.reason)) {
+        debug("peer", `connectToChannel(${nodeId}): ${ev.reason}, will not reconnect`);
+        return;
+      }
+      // Don't reconnect when peer approval was denied — retrying is futile
+      if (ev.code === 4005) {
+        debug("peer", `connectToChannel(${nodeId}): approval denied, will not reconnect`);
         return;
       }
       // Record close code for adaptive backoff
@@ -1245,6 +1257,22 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         // No remote alternative — fall through to local handling
         // (model-proxy will handle locally or send error back)
       } else {
+        // Relay failed — clean up the stale route so we don't keep trying it,
+        // and notify the sender so it can fail-fast.
+        if (frame.to) {
+          this.router.removeRelayRoute(frame.to);
+        }
+        if (frame.from && frame.id) {
+          debug("peer", `relay failed for ${frame.type} id=${frame.id} to=${frame.to}, sending relay_fail to ${frame.from}`);
+          this.sendTo(frame.from, {
+            type: "relay_fail",
+            id: frame.id,
+            from: this.config.nodeId,
+            to: frame.from,
+            timestamp: Date.now(),
+            payload: { target: frame.to, reason: "unreachable" },
+          } as AnyClusterFrame);
+        }
         return;
       }
     }
@@ -1329,21 +1357,18 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         if (peer.nodeId === this.config.nodeId) continue;
         if (peer.nodeId === from.remoteNodeId) {
           const prev = this.router.getRoute(peer.nodeId);
-          const hadAgents = prev?.agents.length ?? 0;
-          const hadDirectPeers = prev?.directPeers.length ?? 0;
-          const hadDeviceInfo = prev?.deviceInfo?.hostname;
-          const hadAcpAgents = prev?.acpAgents?.length ?? 0;
-          const hadToolProxyEnabled = prev?.toolProxy?.enabled;
-          const hadToolProxyCatalogLen = prev?.toolProxy?.catalog?.length ?? 0;
-          const hadToolProxyAllowLen = prev?.toolProxy?.allow?.length ?? 0;
+          const prevSnapshot = prev ? JSON.stringify({
+            a: prev.agents.length, m: prev.models.length,
+            dp: prev.directPeers?.length, tp: prev.toolProxy,
+            di: prev.deviceInfo, aa: prev.acpAgents?.length,
+          }) : "";
           this.router.updatePeerCapabilities(peer.nodeId, peer);
-          if (peer.agents.length !== hadAgents || peer.models.length !== (prev?.models.length ?? 0)
-              || (peer.directPeers?.length ?? 0) !== hadDirectPeers
-              || peer.toolProxy?.enabled !== hadToolProxyEnabled
-              || (peer.toolProxy?.catalog?.length ?? 0) !== hadToolProxyCatalogLen
-              || (peer.toolProxy?.allow?.length ?? 0) !== hadToolProxyAllowLen
-              || peer.deviceInfo?.hostname !== hadDeviceInfo
-              || (peer.acpAgents?.length ?? 0) !== hadAcpAgents) {
+          const newSnapshot = JSON.stringify({
+            a: peer.agents.length, m: peer.models.length,
+            dp: peer.directPeers?.length, tp: peer.toolProxy,
+            di: peer.deviceInfo, aa: peer.acpAgents?.length,
+          });
+          if (newSnapshot !== prevSnapshot) {
             changed = true;
           }
         } else {
@@ -1351,7 +1376,14 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
           // using them as relay would create a routing loop.
           if (peer.reachableVia === this.config.nodeId) continue;
           const existing = this.router.getRoute(peer.nodeId);
-          if (!existing) changed = true;
+          if (!existing) {
+            changed = true;
+          } else {
+            // Detect changes in existing relay peer (e.g. version update after restart)
+            const prevSnap = JSON.stringify({ a: existing.agents.length, m: existing.models.length, di: existing.deviceInfo, aa: existing.acpAgents?.length });
+            const newSnap = JSON.stringify({ a: peer.agents.length, m: peer.models.length, di: peer.deviceInfo, aa: peer.acpAgents?.length });
+            if (newSnap !== prevSnap) changed = true;
+          }
           this.router.addRelayPeer(peer, from.remoteNodeId!);
         }
       }

package/src/router.ts

@@ -8,6 +8,9 @@ const MAX_SEEN_FRAMES = 10_000;
 const MAX_FAILED_REQUESTS = 5_000;
 const SEEN_FRAME_TTL = 120_000;      // 2 minutes (was ~60-120s with double-map rotation)
 const FAILED_REQUEST_TTL = 900_000;   // 15 minutes
+/** Relay routes older than this without a peer_sync refresh are considered stale. */
+const RELAY_ROUTE_MAX_AGE = 300_000;  // 5 minutes
+const RELAY_ROUTE_SWEEP_INTERVAL = 60_000; // sweep every 60s
 
 export interface RouteEntry {
   nodeId: string;
@@ -127,8 +130,51 @@ export class Router {
     }
   }
 
+  private relaySweepTimer: ReturnType<typeof setInterval> | null = null;
+
+  /** Start periodic sweep of stale relay routes. */
+  startRelaySweep() {
+    if (this.relaySweepTimer) return;
+    this.relaySweepTimer = setInterval(() => this.removeStaleRelayRoutes(), RELAY_ROUTE_SWEEP_INTERVAL);
+  }
+
+  /** Remove relay routes whose lastSeen is older than RELAY_ROUTE_MAX_AGE. */
+  removeStaleRelayRoutes(): string[] {
+    const now = Date.now();
+    const removed: string[] = [];
+    for (const [id, entry] of this.routes) {
+      if (entry.reachableVia && !entry.connection && (now - entry.lastSeen) > RELAY_ROUTE_MAX_AGE) {
+        debug("router", `removing stale relay route: ${id} (via ${entry.reachableVia}, age=${Math.round((now - entry.lastSeen) / 1000)}s)`);
+        this.unindexEntry(entry);
+        this.routes.delete(id);
+        this.syncVersion++;
+        this.removedPeers.set(id, this.syncVersion);
+        this.peerVersions.delete(id);
+        removed.push(id);
+      }
+    }
+    return removed;
+  }
+
+  /** Remove a specific relay route (e.g. on relay_fail). No-op for direct connections. */
+  removeRelayRoute(nodeId: string): boolean {
+    const entry = this.routes.get(nodeId);
+    if (!entry || entry.connection) return false; // only remove relay routes
+    debug("router", `removing relay route on failure: ${nodeId} (via ${entry.reachableVia})`);
+    this.unindexEntry(entry);
+    this.routes.delete(nodeId);
+    this.syncVersion++;
+    this.removedPeers.set(nodeId, this.syncVersion);
+    this.peerVersions.delete(nodeId);
+    return true;
+  }
+
   /** Stop periodic cleanup. Call on shutdown. */
   destroy() {
+    if (this.relaySweepTimer) {
+      clearInterval(this.relaySweepTimer);
+      this.relaySweepTimer = null;
+    }
     this.seenFrames.clear();
     this.failedRequests.clear();
     this.channels.clear();

package/src/sentinel.ts

@@ -177,7 +177,7 @@ function buildCapabilities(): NodeCapabilities {
 }
 
 function connectToPeer(peer: { nodeId: string; url: string }) {
-  const ws = new WsWebSocket(peer.url, ["graphql-transport-ws"]);
+  const ws = new WebSocket(peer.url, ["graphql-transport-ws"]);
   const e2eeOpts: ConnectionE2eeOptions = {
     e2ee: config.e2ee,
     compression: config.compression,

package/src/tool-proxy.ts

@@ -130,6 +130,23 @@ export class ToolProxy {
   }
 
   // ── Incoming response ──────────────────────────────────────────
+  /** Reject a specific pending request by frame id (e.g. from relay_fail). */
+  rejectPending(frameId: string, reason: string) {
+    const pending = this.pending.get(frameId);
+    if (pending) {
+      clearTimeout(pending.timer);
+      this.pending.delete(frameId);
+      pending.reject(new Error(reason));
+      return;
+    }
+    const batch = this.pendingBatch.get(frameId);
+    if (batch) {
+      clearTimeout(batch.timer);
+      this.pendingBatch.delete(frameId);
+      batch.reject(new Error(reason));
+    }
+  }
+
   handleResponse(frame: ToolProxyResponse) {
     if (this.peerManager.router.isFailed(frame.id)) return;
     const pending = this.pending.get(frame.id);