clawmatrix 0.2.9 → 0.3.1

package/src/peer-manager.ts

@@ -46,6 +46,9 @@ const SKIP_DEDUP_TYPES = new Set([
   // Terminal
   "terminal_open_res", "terminal_data", "terminal_resize",
   "terminal_close", "terminal_close_res",
+  // File transfer
+  "file_transfer_chunk", "file_transfer_chunk_ack",
+  "file_transfer_ack", "file_transfer_complete",
 ]);
 
 /** Classify WebSocket close code into a human-readable reason. */
@@ -90,6 +93,8 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   private wss: WebSocketServer | null = null;
   private reconnectTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private reconnectAttempts = new Map<string, number>();
+  /** Deferred disconnect timers — grace period before broadcasting peer_leave. */
+  private disconnectGraceTimers = new Map<string, ReturnType<typeof setTimeout>>();
   private stopped = false;
   /** Map from ws WebSocket to Connection for inbound connections. */
   private inboundConnections = new Map<WsWebSocket, Connection>();
@@ -162,6 +167,17 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     }
   }
 
+  /** Update the local tool proxy catalog and re-broadcast to all peers. */
+  updateToolCatalog(catalog: import("./types.ts").ToolCatalogEntry[]) {
+    if (this.localCapabilities.toolProxy) {
+      this.localCapabilities.toolProxy = { ...this.localCapabilities.toolProxy, catalog };
+    }
+    this.router.updateLocalToolCatalog(catalog);
+    for (const conn of this.router.getDirectConnections()) {
+      this.sendPeerSync(conn);
+    }
+  }
+
   // ── Lifecycle ──────────────────────────────────────────────────
   async start() {
     await this.approvalManager.load();
@@ -187,6 +203,12 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       clearTimeout(timer);
     }
     this.reconnectTimers.clear();
+    // Flush all disconnect grace timers (execute leave immediately on shutdown)
+    for (const [nodeId, timer] of this.disconnectGraceTimers) {
+      clearTimeout(timer);
+      this.executePeerLeave(nodeId);
+    }
+    this.disconnectGraceTimers.clear();
 
     this.router.broadcast({
       type: "peer_leave",
@@ -458,9 +480,6 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         if (this.pendingApprovalConns.has(nodeId)) {
           debug("approval", `reusing pending approval for ${nodeId}, updating conn ref`);
           this.pendingApprovalConns.set(nodeId, { conn, caps });
-          if (this.config.peerApproval?.mode === "required") {
-            conn.on("close", () => this.onPeerDisconnected(conn));
-          }
           return;
         }
 
@@ -492,10 +511,12 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
             );
           }
         });
-        // In required mode, don't complete the join yet
+        // In required mode, don't complete the join yet.
+        // No close handler needed here: the peer was never added to the router,
+        // so onPeerDisconnected would broadcast a spurious peer_leave.
+        // If the conn drops before approval resolves, the .then() handler sees
+        // activeConn.isOpen === false and skips all actions.
         if (this.config.peerApproval?.mode === "required") {
-          // Wire up close handler to clean up if connection drops while pending
-          conn.on("close", () => this.onPeerDisconnected(conn));
           return;
         }
         // In notify mode, requestApproval resolves immediately, but
@@ -512,6 +533,9 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
   private completePeerJoin(conn: Connection, caps: NodeCapabilities) {
     const nodeId = conn.remoteNodeId!;
 
+    // Cancel disconnect grace timer if the peer is reconnecting
+    const wasInGrace = this.cancelDisconnectGrace(nodeId);
+
     // If there's an existing connection for this nodeId (e.g. peer reconnected
     // while old TCP hadn't closed yet), close it AFTER overwriting the route so
     // the stale-close guard in onPeerDisconnected correctly skips cleanup.
@@ -582,15 +606,58 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       return;
     }
 
+    // Grace period: defer peer_leave broadcast to allow quick reconnection
+    // (e.g. iOS WiFi ↔ cellular handoff, brief audio interruption).
+    // If the peer reconnects within the grace window, completePeerJoin
+    // will cancel this timer via cancelDisconnectGrace.
+    const graceMs = this.config.disconnectGrace ?? 30_000;
+    if (graceMs <= 0) {
+      this.executePeerLeave(nodeId, conn);
+      return;
+    }
+    debug("peer", `onPeerDisconnected(${nodeId}): starting ${graceMs / 1000}s grace period`);
+
+    // Clear any existing grace timer for this node (shouldn't happen, but be safe)
+    this.cancelDisconnectGrace(nodeId);
+
+    this.disconnectGraceTimers.set(nodeId, setTimeout(() => {
+      this.disconnectGraceTimers.delete(nodeId);
+      this.executePeerLeave(nodeId, conn);
+    }, graceMs));
+  }
+
+  /** Cancel a pending disconnect grace timer (called when peer reconnects quickly). */
+  private cancelDisconnectGrace(nodeId: string): boolean {
+    const timer = this.disconnectGraceTimers.get(nodeId);
+    if (timer) {
+      clearTimeout(timer);
+      this.disconnectGraceTimers.delete(nodeId);
+      debug("peer", `cancelDisconnectGrace(${nodeId}): peer reconnected within grace period`);
+      return true;
+    }
+    return false;
+  }
+
+  /** Execute the actual peer leave (after grace period expires or immediate for shutdown). */
+  private executePeerLeave(nodeId: string, conn?: Connection) {
+    // Double-check the route hasn't been replaced by a new connection during grace
+    if (conn) {
+      const currentRoute = this.router.getRoute(nodeId);
+      if (currentRoute?.connection && currentRoute.connection !== conn) {
+        debug("peer", `executePeerLeave(${nodeId}): route replaced during grace — skipping`);
+        return;
+      }
+    }
+
     audit("peer_leave", { nodeId });
     this.router.removePeer(nodeId);
 
     // Remove satellite contexts that were only reachable via this peer
-    this.satelliteContexts = this.satelliteContexts.filter(s => {
-      // Keep satellites that are not associated with the disconnected peer
-      // (satellite nodeIds typically differ from mesh peer nodeIds)
-      return s.nodeId !== nodeId;
-    });
+    for (let i = this.satelliteContexts.length - 1; i >= 0; i--) {
+      if (this.satelliteContexts[i].nodeId === nodeId) {
+        this.satelliteContexts.splice(i, 1);
+      }
+    }
 
     this.router.broadcast({
       type: "peer_leave",
@@ -745,13 +812,17 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
         const prev = this.router.getRoute(peer.nodeId);
         const hadAgents = prev?.agents.length ?? 0;
         const hadDirectPeers = prev?.directPeers.length ?? 0;
-        const hadToolProxy = JSON.stringify(prev?.toolProxy);
         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;
         this.router.updatePeerCapabilities(peer.nodeId, peer);
         if (peer.agents.length !== hadAgents || peer.models.length !== (prev?.models.length ?? 0)
             || (peer.directPeers?.length ?? 0) !== hadDirectPeers
-            || JSON.stringify(peer.toolProxy) !== hadToolProxy
+            || 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) {
           changed = true;

package/src/rate-limiter.ts

@@ -33,19 +33,20 @@ export class RateLimiter {
 
     let timestamps = this.attempts.get(ip);
     if (timestamps) {
-      // Remove expired entries
-      timestamps = timestamps.filter((t) => t > cutoff);
+      // In-place pruning: find first non-expired index and splice
+      let firstValid = 0;
+      while (firstValid < timestamps.length && timestamps[firstValid] <= cutoff) firstValid++;
+      if (firstValid > 0) timestamps.splice(0, firstValid);
     } else {
       timestamps = [];
+      this.attempts.set(ip, timestamps);
     }
 
     if (timestamps.length >= this.config.maxAttempts) {
-      this.attempts.set(ip, timestamps);
       return false;
     }
 
     timestamps.push(now);
-    this.attempts.set(ip, timestamps);
     return true;
   }
 
@@ -61,19 +62,24 @@ export class RateLimiter {
   /** Get remaining attempts for an IP. */
   remaining(ip: string): number {
     const cutoff = Date.now() - this.config.windowMs;
-    const timestamps = this.attempts.get(ip) ?? [];
-    const active = timestamps.filter((t) => t > cutoff).length;
+    const timestamps = this.attempts.get(ip);
+    if (!timestamps) return this.config.maxAttempts;
+    let active = 0;
+    for (let i = timestamps.length - 1; i >= 0; i--) {
+      if (timestamps[i] > cutoff) active++; else break;
+    }
     return Math.max(0, this.config.maxAttempts - active);
   }
 
   private gc() {
     const cutoff = Date.now() - this.config.windowMs;
     for (const [ip, timestamps] of this.attempts) {
-      const active = timestamps.filter((t) => t > cutoff);
-      if (active.length === 0) {
+      let firstValid = 0;
+      while (firstValid < timestamps.length && timestamps[firstValid] <= cutoff) firstValid++;
+      if (firstValid === timestamps.length) {
         this.attempts.delete(ip);
-      } else {
-        this.attempts.set(ip, active);
+      } else if (firstValid > 0) {
+        timestamps.splice(0, firstValid);
       }
     }
   }

package/src/router.ts

@@ -38,6 +38,14 @@ export class Router {
   /** Failed request IDs with expiry timestamps. Separate from dedup to support longer TTLs. */
   private failedRequests = new Map<string, number>(); // requestId → expiresAt
 
+  // ── Indexes for O(1) lookups in hot paths ──────────────────────
+  /** agentId → Set of nodeIds that host this agent. */
+  private agentIndex = new Map<string, Set<string>>();
+  /** tag → Set of nodeIds (both node-level and agent-level tags). */
+  private tagIndex = new Map<string, Set<string>>();
+  /** modelId → Set of nodeIds that provide this model. */
+  private modelIndex = new Map<string, Set<string>>();
+
   constructor(
     nodeId: string,
     localCapabilities?: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo; acpAgents?: AcpAgentInfo[] },
@@ -53,11 +61,64 @@ export class Router {
     this.rotateTimer = setInterval(() => this.rotateSeenFrames(), ROTATE_INTERVAL);
   }
 
+  /** Rebuild all indexes from scratch. Called after any route table mutation. */
+  private rebuildIndexes() {
+    this.agentIndex.clear();
+    this.tagIndex.clear();
+    this.modelIndex.clear();
+    for (const entry of this.routes.values()) {
+      this.indexEntry(entry);
+    }
+  }
+
+  /** Add a single entry to all indexes. */
+  private indexEntry(entry: RouteEntry) {
+    const nid = entry.nodeId;
+    for (const a of entry.agents) {
+      let set = this.agentIndex.get(a.id);
+      if (!set) { set = new Set(); this.agentIndex.set(a.id, set); }
+      set.add(nid);
+      for (const t of a.tags ?? []) {
+        let ts = this.tagIndex.get(t);
+        if (!ts) { ts = new Set(); this.tagIndex.set(t, ts); }
+        ts.add(nid);
+      }
+    }
+    for (const t of entry.tags ?? []) {
+      let set = this.tagIndex.get(t);
+      if (!set) { set = new Set(); this.tagIndex.set(t, set); }
+      set.add(nid);
+    }
+    for (const m of entry.models ?? []) {
+      let set = this.modelIndex.get(m.id);
+      if (!set) { set = new Set(); this.modelIndex.set(m.id, set); }
+      set.add(nid);
+    }
+  }
+
+  /** Remove a single entry from all indexes. */
+  private unindexEntry(entry: RouteEntry) {
+    const nid = entry.nodeId;
+    for (const a of entry.agents ?? []) {
+      this.agentIndex.get(a.id)?.delete(nid);
+      for (const t of a.tags ?? []) this.tagIndex.get(t)?.delete(nid);
+    }
+    for (const t of entry.tags ?? []) this.tagIndex.get(t)?.delete(nid);
+    for (const m of entry.models ?? []) this.modelIndex.get(m.id)?.delete(nid);
+  }
+
   /** Update locally advertised ACP agents (used after auto-detection). */
   updateLocalAcpAgents(agents: AcpAgentInfo[]) {
     this.localAcpAgents = agents;
   }
 
+  /** Update the local tool proxy catalog (descriptions + schemas for remote callers). */
+  updateLocalToolCatalog(catalog: ToolProxyInfo["catalog"]) {
+    if (this.localToolProxy) {
+      this.localToolProxy = { ...this.localToolProxy, catalog };
+    }
+  }
+
   /** Stop periodic cleanup. Call on shutdown. */
   destroy() {
     if (this.rotateTimer) {
@@ -75,8 +136,10 @@ export class Router {
     connection: Connection,
     capabilities: { agents: AgentInfo[]; models: ModelInfo[]; tags: string[]; deviceInfo?: DeviceInfo; toolProxy?: ToolProxyInfo; acpAgents?: AcpAgentInfo[] },
   ) {
+    const old = this.routes.get(nodeId);
+    if (old) this.unindexEntry(old);
     this.connections.set(nodeId, connection);
-    this.routes.set(nodeId, {
+    const entry: RouteEntry = {
       nodeId,
       agents: capabilities.agents,
       models: capabilities.models,
@@ -89,7 +152,9 @@ export class Router {
       deviceInfo: capabilities.deviceInfo,
       toolProxy: capabilities.toolProxy,
       acpAgents: capabilities.acpAgents,
-    });
+    };
+    this.routes.set(nodeId, entry);
+    this.indexEntry(entry);
   }
 
   addRelayPeer(peer: PeerInfo, viaNodeId: string) {
@@ -106,7 +171,8 @@ export class Router {
     // Don't overwrite a better relay route with a worse one (allow equal for capability updates)
     if (existing?.reachableVia && existing.latencyMs < estimatedLatency) return;
 
-    this.routes.set(peer.nodeId, {
+    if (existing) this.unindexEntry(existing);
+    const entry: RouteEntry = {
       nodeId: peer.nodeId,
       agents: peer.agents,
       models: peer.models,
@@ -119,15 +185,22 @@ export class Router {
       deviceInfo: peer.deviceInfo,
       toolProxy: peer.toolProxy,
       acpAgents: peer.acpAgents,
-    });
+    };
+    this.routes.set(peer.nodeId, entry);
+    this.indexEntry(entry);
   }
 
   removePeer(nodeId: string) {
     this.connections.delete(nodeId);
-    this.routes.delete(nodeId);
+    const removed = this.routes.get(nodeId);
+    if (removed) {
+      this.unindexEntry(removed);
+      this.routes.delete(nodeId);
+    }
     // Also remove routes that relied on this node as relay
     for (const [id, entry] of this.routes) {
       if (entry.reachableVia === nodeId) {
+        this.unindexEntry(entry);
         this.routes.delete(id);
       }
     }
@@ -139,6 +212,7 @@ export class Router {
   ) {
     const entry = this.routes.get(nodeId);
     if (entry) {
+      this.unindexEntry(entry);
       entry.agents = capabilities.agents;
       entry.models = capabilities.models;
       entry.tags = capabilities.tags;
@@ -151,6 +225,7 @@ export class Router {
       entry.toolProxy = capabilities.toolProxy;
       entry.acpAgents = capabilities.acpAgents;
       entry.lastSeen = Date.now();
+      this.indexEntry(entry);
     }
   }
 
@@ -169,20 +244,20 @@ export class Router {
   /** Resolve target agent to a specific nodeId. Supports agent ID or "tags:<tag>". */
   resolveAgent(target: string): RouteEntry | undefined {
     const isTagQuery = target.startsWith("tags:");
-    const tag = isTagQuery ? target.slice(5) : null;
+
+    let nodeIds: Set<string> | undefined;
+    if (isTagQuery) {
+      nodeIds = this.tagIndex.get(target.slice(5));
+    } else {
+      nodeIds = this.agentIndex.get(target);
+    }
 
     let candidates: RouteEntry[] = [];
-    for (const entry of this.routes.values()) {
-      // Skip self — never resolve to our own node
-      if (entry.nodeId === this.nodeId) continue;
-      if (isTagQuery) {
-        if (entry.agents.some((a) => a.tags.includes(tag!)) || entry.tags.includes(tag!)) {
-          candidates.push(entry);
-        }
-      } else {
-        if (entry.agents.some((a) => a.id === target)) {
-          candidates.push(entry);
-        }
+    if (nodeIds) {
+      for (const nid of nodeIds) {
+        if (nid === this.nodeId) continue;
+        const entry = this.routes.get(nid);
+        if (entry) candidates.push(entry);
       }
     }
 
@@ -193,6 +268,7 @@ export class Router {
     }
 
     if (candidates.length === 0) return undefined;
+    if (candidates.length === 1) return candidates[0];
 
     // Sort: direct connections first, then by latency
     candidates.sort((a, b) => {
@@ -210,15 +286,16 @@ export class Router {
   resolveNode(target: string): RouteEntry | undefined {
     if (target.startsWith("tags:")) {
       const tag = target.slice(5);
+      const nodeIds = this.tagIndex.get(tag);
+      if (!nodeIds) return undefined;
       const candidates: RouteEntry[] = [];
-      for (const entry of this.routes.values()) {
-        // Skip self — never resolve to our own node
-        if (entry.nodeId === this.nodeId) continue;
-        if (entry.tags.includes(tag)) {
-          candidates.push(entry);
-        }
+      for (const nid of nodeIds) {
+        if (nid === this.nodeId) continue;
+        const entry = this.routes.get(nid);
+        if (entry) candidates.push(entry);
       }
       if (candidates.length === 0) return undefined;
+      if (candidates.length === 1) return candidates[0];
       // Sort: direct connections first, then by latency
       candidates.sort((a, b) => {
         const aDirect = a.connection ? 0 : 1;
@@ -236,10 +313,13 @@ export class Router {
   /** Find reachable nodes that provide a specific model, sorted by latency.
    *  Excludes nodes in the `exclude` set. */
   findNodesForModel(modelId: string, exclude?: Set<string>): RouteEntry[] {
+    const nodeIds = this.modelIndex.get(modelId);
+    if (!nodeIds) return [];
     const candidates: RouteEntry[] = [];
-    for (const entry of this.routes.values()) {
-      if (exclude?.has(entry.nodeId)) continue;
-      if (!entry.models.some((m) => m.id === modelId)) continue;
+    for (const nid of nodeIds) {
+      if (exclude?.has(nid)) continue;
+      const entry = this.routes.get(nid);
+      if (!entry) continue;
       // Check reachability
       if (entry.connection?.isOpen) {
         candidates.push(entry);
@@ -248,13 +328,15 @@ export class Router {
         if (relay?.isOpen) candidates.push(entry);
       }
     }
-    // Sort: direct first, then by latency
-    candidates.sort((a, b) => {
-      const aDirect = a.connection ? 0 : 1;
-      const bDirect = b.connection ? 0 : 1;
-      if (aDirect !== bDirect) return aDirect - bDirect;
-      return a.latencyMs - b.latencyMs;
-    });
+    if (candidates.length > 1) {
+      // Sort: direct first, then by latency
+      candidates.sort((a, b) => {
+        const aDirect = a.connection ? 0 : 1;
+        const bDirect = b.connection ? 0 : 1;
+        if (aDirect !== bDirect) return aDirect - bDirect;
+        return a.latencyMs - b.latencyMs;
+      });
+    }
     return candidates;
   }
 

package/src/sentinel-manager.ts

@@ -8,7 +8,8 @@
 
 import { fork, type ChildProcess } from "node:child_process";
 import { join, dirname } from "node:path";
-import { existsSync, readFileSync, mkdirSync, openSync } from "node:fs";
+import { existsSync, readFileSync, mkdirSync, openSync, closeSync } from "node:fs";
+import { createConnection } from "node:net";
 import { homedir, tmpdir } from "node:os";
 import type { ClawMatrixConfig } from "./config.ts";
 
@@ -42,6 +43,9 @@ export class SentinelManager {
       execArgv: this.resolveExecArgv(),
     });
 
+    // Close the log fd in the parent — the child has its own copy
+    closeSync(logFd);
+
     // Send config to sentinel via IPC (includes gateway PID for health checks)
     // If sentinel has no explicit listenPort but the gateway is a listener,
     // inherit the gateway's port for automatic takeover when gateway dies.
@@ -83,7 +87,57 @@ export class SentinelManager {
     }, 1000);
   }
 
-  stop() {
+  /**
+   * Kill the old sentinel and wait for the listen port to become free.
+   * Must be called BEFORE PeerManager.startListening() to avoid EADDRINUSE.
+   */
+  async ensurePortFree() {
+    // Kill old sentinel process if alive
+    if (existsSync(this.pidFile)) {
+      try {
+        const pid = parseInt(readFileSync(this.pidFile, "utf-8").trim(), 10);
+        if (pid) {
+          try {
+            process.kill(pid, "SIGTERM");
+            // Wait for the process to exit (up to 5s)
+            for (let i = 0; i < 100; i++) {
+              try {
+                process.kill(pid, 0);
+                await new Promise((r) => setTimeout(r, 50));
+              } catch {
+                break; // exited
+              }
+            }
+          } catch {
+            // Already gone
+          }
+        }
+      } catch {
+        // Malformed PID file
+      }
+    }
+
+    // Probe the port until it's free (up to 5s)
+    const port = this.config.sentinel?.listenPort
+      ?? (this.config.listen ? this.config.listenPort : 0);
+    if (!port) return;
+
+    const host = this.config.sentinel?.listenHost ?? this.config.listenHost ?? "0.0.0.0";
+    for (let i = 0; i < 50; i++) {
+      const inUse = await new Promise<boolean>((resolve) => {
+        const sock = createConnection({ port, host }, () => {
+          sock.destroy();
+          resolve(true);
+        });
+        sock.on("error", () => resolve(false));
+        sock.setTimeout(200, () => { sock.destroy(); resolve(false); });
+      });
+      if (!inUse) return;
+      await new Promise((r) => setTimeout(r, 100));
+    }
+  }
+
+  async stop() {
     // IPC is disconnected shortly after start, so use PID file for shutdown
     if (existsSync(this.pidFile)) {
       try {
@@ -92,13 +146,11 @@ export class SentinelManager {
           process.kill(pid, "SIGTERM");
           // Wait briefly for the process to exit so the next start()
           // doesn't race with a still-dying sentinel
-          const deadline = Date.now() + 3_000;
-          while (Date.now() < deadline) {
+          for (let i = 0; i < 60; i++) {
             try {
               process.kill(pid, 0);
-              // Still alive — brief spin
-              const waitUntil = Date.now() + 50;
-              while (Date.now() < waitUntil) { /* spin */ }
+              // Still alive — async wait
+              await new Promise((r) => setTimeout(r, 50));
             } catch {
               break; // exited
             }

package/src/sentinel.ts

@@ -78,6 +78,11 @@ let httpServer: Server | null = null;
 let wss: WebSocketServer | null = null;
 const inboundConnections = new Map<WsWebSocket, Connection>();
 let listening = false;
+/** Timestamp when sentinel voluntarily released the port. During the cooldown
+ *  period (30s), sentinel will not re-listen even if gateway appears to be gone,
+ *  giving the new gateway time to bind the port. */
+let voluntaryReleaseAt = 0;
+const PORT_RELEASE_COOLDOWN = 30_000;
 
 // ── Rate limiting for diagnostic_exec ────────────────────────────
 const EXEC_RATE_WINDOW = 60_000; // 1 minute
@@ -464,6 +469,9 @@ function stopListening() {
   httpServer?.close();
   httpServer = null;
   listening = false;
+  // Mark voluntary release — sentinel will not re-listen during cooldown
+  // to give the gateway time to bind the port.
+  voluntaryReleaseAt = Date.now();
   log("Port released — gateway is back");
 }
 
@@ -612,12 +620,14 @@ function startGatewayHealthCheck() {
         log(`Gateway process (pid ${gatewayPid}) gone — entering standalone mode`);
         // Connect to peers now that gateway is down
         connectAllPeers();
-        // Take over the gateway's listen port
+        // Take over the gateway's listen port — but respect cooldown after
+        // voluntary release so we don't compete with a restarting gateway.
         if (config.listenPort) {
-          // Small delay to let the OS release the port from the dead process
+          const cooldownRemaining = PORT_RELEASE_COOLDOWN - (Date.now() - voluntaryReleaseAt);
+          const delay = Math.max(2_000, cooldownRemaining);
           setTimeout(() => {
             if (!gatewayAlive && !isReplaced()) startListening();
-          }, 2_000);
+          }, delay);
         }
       }
     }

package/src/terminal.ts

@@ -109,7 +109,8 @@ export class TerminalManager {
       return;
     }
 
-    // Check allowFrom
+    // TODO(security): allowFrom 为空时默认允许所有已认证 peer 打开终端会话。
+    // 当前仅用于受信任网络。开放前需改为默认拒绝或要求显式配置。
     if (termConfig?.allowFrom && termConfig.allowFrom.length > 0) {
       if (!termConfig.allowFrom.includes(frame.from)) {
         this.peerManager.sendTo(frame.from, {

package/src/tool-proxy.ts

@@ -45,6 +45,10 @@ export class ToolProxy {
   private logger: PluginLogger;
   private satelliteHandler: SatelliteToolHandler | null = null;
   private readonly toolTimeout: number;
+  // Pre-built Sets for O(1) allow/deny checks
+  private readonly allowSet: Set<string>;
+  private readonly denySet: Set<string>;
+  private readonly allowAll: boolean;
 
   constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo, logger: PluginLogger) {
     this.config = config;
@@ -52,6 +56,10 @@ export class ToolProxy {
     this.gatewayInfo = gatewayInfo;
     this.logger = logger;
     this.toolTimeout = config.toolTimeout ?? DEFAULT_TOOL_TIMEOUT;
+    const tp = config.toolProxy;
+    this.denySet = new Set(tp?.deny ?? []);
+    this.allowSet = new Set(tp?.allow ?? []);
+    this.allowAll = this.allowSet.size === 0 || this.allowSet.has("*");
   }
 
   /** Set the satellite tool handler (called by ClusterRuntime after WebHandler is created). */
@@ -338,10 +346,10 @@ export class ToolProxy {
   }
 
   // ── Security ───────────────────────────────────────────────────
-  private isToolAllowed(tool: string, tpConfig: ToolProxyConfig): boolean {
-    if (tpConfig.deny.includes(tool)) return false;
-    if (tpConfig.allow.length === 0 || tpConfig.allow.includes("*")) return true;
-    return tpConfig.allow.includes(tool);
+  private isToolAllowed(tool: string, _tpConfig: ToolProxyConfig): boolean {
+    if (this.denySet.has(tool)) return false;
+    if (this.allowAll) return true;
+    return this.allowSet.has(tool);
   }
 
   destroy() {