clawmatrix 0.2.11 → 0.3.1

package/src/cluster-service.ts

@@ -102,6 +102,9 @@ export class ClusterRuntime {
   private logger: PluginLogger;
   private openclawConfig: OpenClawConfig;
   private exitHandler: (() => void) | null = null;
+  // Pre-built indexes for O(1) local agent lookup
+  private agentById = new Map<string, ClawMatrixConfig["agents"][number]>();
+  private agentsByTag = new Map<string, ClawMatrixConfig["agents"][number]>();
 
   constructor(config: ClawMatrixConfig, logger: PluginLogger, openclawConfig: OpenClawConfig, openclawVersion?: string) {
     this.config = config;
@@ -123,9 +126,14 @@ export class ClusterRuntime {
       nodeId: config.nodeId,
       peerManager: this.peerManager,
     });
+    // Build agent indexes
+    for (const a of config.agents) {
+      this.agentById.set(a.id, a);
+      for (const t of a.tags) this.agentsByTag.set(t, a);
+    }
   }
 
-  start() {
+  async start() {
     // Wire up frame dispatch
     this.peerManager.on("frame", (frame) => {
       this.dispatchFrame(frame);
@@ -207,14 +215,31 @@ export class ClusterRuntime {
       this.logger.error(`[clawmatrix] Health tracker failed to start: ${err}`);
     });
 
-    // Start subsystems
-    this.peerManager.start();
-    this.modelProxy.start();
-
     // Sentinel: detached subprocess for diagnostics when gateway dies.
     // Default on; starts when not explicitly disabled AND (has outbound peers OR gateway is a listener for port takeover)
-    if ((this.config.sentinel?.enabled ?? true) && (this.config.peers.length > 0 || this.config.listen)) {
+    const sentinelEnabled = (this.config.sentinel?.enabled ?? true) && (this.config.peers.length > 0 || this.config.listen);
+    if (sentinelEnabled) {
       this.sentinelManager = new SentinelManager(this.config);
+      // Kill old sentinel and wait for the listen port to be released
+      // before PeerManager tries to bind it.
+      await this.sentinelManager.ensurePortFree();
+    }
+
+    // Start subsystems (port is now guaranteed free)
+    this.peerManager.start();
+    this.modelProxy.start();
+
+    // Fetch tool catalog from the local gateway (non-blocking).
+    // The catalog (tool names, descriptions) is advertised to peers via peer_sync
+    // so remote LLM callers can discover available tools.
+    if (this.config.toolProxy?.enabled) {
+      this.fetchToolCatalog().catch((err) => {
+        this.logger.warn(`[clawmatrix] Tool catalog fetch failed (non-fatal): ${err}`);
+      });
+    }
+
+    // Spawn the new sentinel after PeerManager is listening
+    if (sentinelEnabled && this.sentinelManager) {
       this.sentinelManager.start();
       this.logger.info(`[clawmatrix] Sentinel started for node "${this.config.nodeId}"`);
     }
@@ -261,6 +286,61 @@ export class ClusterRuntime {
     this.modelProxy.updateDiscoveredModels(peers);
   }
 
+  /** Fetch tool catalog from the local OpenClaw gateway and advertise to peers. */
+  private async fetchToolCatalog() {
+    const { spawnProcess } = await import("./compat.ts");
+    const proc = spawnProcess(
+      ["openclaw", "gateway", "call", "tools.catalog", "--json", "--params", '{"includePlugins":true}'],
+      { stdout: "pipe", stderr: "pipe" },
+    );
+    const chunks: Uint8Array[] = [];
+    if (proc.stdout) {
+      const reader = proc.stdout.getReader();
+      while (true) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        chunks.push(value);
+      }
+    }
+    const code = await proc.exited;
+    if (code !== 0) return;
+
+    const stdout = Buffer.concat(chunks).toString("utf-8").trim();
+    if (!stdout) return;
+    // stdout may contain non-JSON log lines (e.g. "[plugins] ...") before the actual JSON.
+    // Extract the first JSON object from the output.
+    const jsonStart = stdout.indexOf("{");
+    if (jsonStart < 0) return;
+    const data = JSON.parse(stdout.slice(jsonStart)) as {
+      groups?: Array<{
+        tools: Array<{ id: string; label: string; description: string }>;
+      }>;
+    };
+    if (!data.groups) return;
+
+    const allowSet = new Set(this.config.toolProxy?.allow ?? []);
+    const isWildcard = allowSet.has("*") || allowSet.size === 0;
+    const denySet = new Set(this.config.toolProxy?.deny ?? []);
+    const catalog: import("./types.ts").ToolCatalogEntry[] = [];
+    for (const group of data.groups) {
+      for (const tool of group.tools) {
+        if (denySet.has(tool.id)) continue;
+        if (!isWildcard && !allowSet.has(tool.id)) continue;
+        // Skip clawmatrix's own cluster_ tools (they're the invoker, not the invokee)
+        if (tool.id.startsWith("cluster_")) continue;
+        catalog.push({
+          name: tool.id,
+          description: tool.description,
+        });
+      }
+    }
+
+    if (catalog.length > 0) {
+      this.peerManager.updateToolCatalog(catalog);
+      this.logger.info(`[clawmatrix] Tool catalog: ${catalog.length} tool(s) advertised to peers`);
+    }
+  }
+
   private resolveWorkspacePath(): string | null {
     // Read workspace from OpenClaw agent config (first agent or default agent)
     const agents = (this.openclawConfig as Record<string, unknown>).agents as
@@ -491,6 +571,29 @@ export class ClusterRuntime {
       case "acp_get_modes_res":
         this.acpProxy?.handleGetModesResponse(frame as AcpGetModesResponse);
         break;
+      case "acp_set_config":
+        if (this.acpProxy) {
+          this.acpProxy.handleSetConfigRequest(frame as import("./types.ts").AcpSetConfigRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP set config error: ${err}`);
+          });
+        }
+        break;
+      case "acp_set_config_res":
+        this.acpProxy?.handleSetConfigResponse(frame as import("./types.ts").AcpSetConfigResponse);
+        break;
+      case "acp_subscribe":
+        if (this.acpProxy) {
+          this.acpProxy.handleSubscribeRequest(frame as import("./types.ts").AcpSubscribeRequest).catch((err) => {
+            this.logger.error(`[clawmatrix] ACP subscribe error: ${err}`);
+          });
+        }
+        break;
+      case "acp_unsubscribe":
+        this.acpProxy?.handleUnsubscribeRequest(frame as import("./types.ts").AcpUnsubscribeRequest);
+        break;
+      case "acp_session_notify":
+        // Outbound notification — no server-side handling needed.
+        break;
       case "chat_history_req":
         if (this.acpProxy) {
           this.acpProxy.handleChatHistoryRequest(frame as ChatHistoryRequest).catch((err) => {
@@ -544,12 +647,9 @@ export class ClusterRuntime {
   private handleSendMessage(frame: SendMessage) {
     // Inject message into local agent session via openclaw CLI
     const { target, message } = frame.payload;
-    const agent = this.config.agents.find((a) => {
-      if (target.startsWith("tags:")) {
-        return a.tags.includes(target.slice(5));
-      }
-      return a.id === target;
-    });
+    const agent = target.startsWith("tags:")
+      ? this.agentsByTag.get(target.slice(5))
+      : this.agentById.get(target);
 
     if (!agent) {
       this.logger.warn(
@@ -587,9 +687,9 @@ export function createClusterService(
 ): OpenClawPluginService {
   return {
     id: "clawmatrix",
-    start(ctx: OpenClawPluginServiceContext) {
+    async start(ctx: OpenClawPluginServiceContext) {
       clusterRuntime = new ClusterRuntime(config, ctx.logger, openclawConfig, openclawVersion);
-      clusterRuntime.start();
+      await clusterRuntime.start();
       onStarted?.();
     },
     async stop() {

package/src/compat.ts

@@ -8,12 +8,6 @@ import { spawn as cpSpawn } from "node:child_process";
 import { open, readFile, stat, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 
-export interface SpawnResult {
-  exitCode: number;
-  stdout: string;
-  stderr: string;
-}
-
 /** Spawn a subprocess and collect stdout/stderr. */
 export function spawnProcess(
   cmd: string[],

package/src/config.ts

@@ -161,17 +161,20 @@ const RawClawMatrixConfigSchema = z.object({
   secret: z.string().min(16, "secret must be at least 16 characters"),
   listen: z.boolean().default(false),
   listenHost: z.string().default("0.0.0.0"),
-  listenPort: z.number().default(0),
+  listenPort: z.number().int().min(0).max(65535).default(0),
   peers: z.array(PeerConfigSchema).default([]),
   agents: z.array(AgentInfoSchema).default([]),
   models: z.array(ModelInfoSchema).default([]),
   proxyModels: z.array(ProxyModelGroupSchema).default([]),
   tags: z.array(z.string()).default([]),
-  proxyPort: z.number().default(0),
+  proxyPort: z.number().int().min(0).max(65535).default(0),
   toolProxy: ToolProxyConfigSchema.optional(),
-  handoffTimeout: z.number().default(600_000),
-  modelTimeout: z.number().default(120_000),
-  toolTimeout: z.number().default(30_000),
+  handoffTimeout: z.number().positive().default(600_000),
+  modelTimeout: z.number().positive().default(120_000),
+  toolTimeout: z.number().positive().default(30_000),
+  /** Grace period (ms) before broadcasting peer_leave after disconnect.
+   *  Allows brief reconnections (WiFi/cellular handoff) to be invisible to the mesh. */
+  disconnectGrace: z.number().nonnegative().default(30_000),
   sentinel: SentinelConfigSchema,
   web: WebConfigSchema,
   knowledge: KnowledgeConfigSchema,

package/src/connection.ts

@@ -485,70 +485,76 @@ export class Connection extends EventEmitter<ConnectionEvents> {
 
   private startHeartbeat() {
     this.lastReceivedAt = Date.now();
-    const scheduleNext = () => {
-      const interval = HEARTBEAT_BASE + Math.random() * HEARTBEAT_JITTER;
-      this.heartbeatTimer = setTimeout(() => {
-        if (this.closed) return;
-
-        // Watchdog: if no data received for a long time, the connection is dead
-        // regardless of what the heartbeat ping/pong state says.
-        const silenceMs = Date.now() - this.lastReceivedAt;
-        if (this.lastReceivedAt > 0 && silenceMs > Connection.RECEIVE_TIMEOUT) {
-          debug("heartbeat", `No data received for ${Math.round(silenceMs / 1000)}s from ${this.remoteNodeId ?? "unknown"}, closing`);
-          this.close(4002, "receive timeout");
-          return;
-        }
+    this.scheduleHeartbeatTick();
+  }
 
-        // Increment before checking: this ping is about to be sent and
-        // counts as outstanding until a pong arrives.
-        this.missedPongs++;
-        if (this.missedPongs >= HEARTBEAT_TIMEOUT_COUNT) {
-          debug("heartbeat", `${HEARTBEAT_TIMEOUT_COUNT} missed pongs from ${this.remoteNodeId ?? "unknown"}, closing`);
-          this.close(4002, "heartbeat timeout");
-          return;
-        }
+  private scheduleHeartbeatTick() {
+    const interval = HEARTBEAT_BASE + Math.random() * HEARTBEAT_JITTER;
+    this.heartbeatTimer = setTimeout(this.heartbeatTick, interval);
+  }
 
-        // Send ping — wrapped in try-catch to prevent breaking the heartbeat chain.
-        // If send fails, the connection is dead; close it.
-        try {
-          if (this.transport.readyState !== WebSocket.OPEN) {
-            debug("heartbeat", `Transport not open (state=${this.transport.readyState}) for ${this.remoteNodeId ?? "unknown"}, closing`);
-            this.close(4002, "transport closed");
-            return;
-          }
-          this.lastPingSentAt = Date.now();
-          this.send({
-            type: "ping",
-            from: this.nodeId,
-            timestamp: this.lastPingSentAt,
-          } as AnyClusterFrame);
-        } catch (err) {
-          debug("heartbeat", `Ping send failed for ${this.remoteNodeId ?? "unknown"}: ${err}`);
-          this.close(4002, "ping send failed");
-          return;
-        }
+  private heartbeatTick = () => {
+    if (this.closed) return;
 
-        scheduleNext();
-      }, interval);
-    };
-    scheduleNext();
-  }
+    // Watchdog: if no data received for a long time, the connection is dead
+    // regardless of what the heartbeat ping/pong state says.
+    const silenceMs = Date.now() - this.lastReceivedAt;
+    if (this.lastReceivedAt > 0 && silenceMs > Connection.RECEIVE_TIMEOUT) {
+      debug("heartbeat", `No data received for ${Math.round(silenceMs / 1000)}s from ${this.remoteNodeId ?? "unknown"}, closing`);
+      this.close(4002, "receive timeout");
+      return;
+    }
+
+    // Increment before checking: this ping is about to be sent and
+    // counts as outstanding until a pong arrives.
+    this.missedPongs++;
+    if (this.missedPongs >= HEARTBEAT_TIMEOUT_COUNT) {
+      debug("heartbeat", `${HEARTBEAT_TIMEOUT_COUNT} missed pongs from ${this.remoteNodeId ?? "unknown"}, closing`);
+      this.close(4002, "heartbeat timeout");
+      return;
+    }
+
+    // Send ping — wrapped in try-catch to prevent breaking the heartbeat chain.
+    // If send fails, the connection is dead; close it.
+    try {
+      if (this.transport.readyState !== WebSocket.OPEN) {
+        debug("heartbeat", `Transport not open (state=${this.transport.readyState}) for ${this.remoteNodeId ?? "unknown"}, closing`);
+        this.close(4002, "transport closed");
+        return;
+      }
+      this.lastPingSentAt = Date.now();
+      this.send({
+        type: "ping",
+        from: this.nodeId,
+        timestamp: this.lastPingSentAt,
+      } as AnyClusterFrame);
+    } catch (err) {
+      debug("heartbeat", `Ping send failed for ${this.remoteNodeId ?? "unknown"}: ${err}`);
+      this.close(4002, "ping send failed");
+      return;
+    }
+
+    this.scheduleHeartbeatTick();
+  };
 
   // ── Dummy traffic (breaks heartbeat timing pattern) ────────────
   private startDummyTraffic() {
     if (!this.sessionKey) return;
-    const scheduleNext = () => {
-      // Random interval 2-8 seconds — interleaves with heartbeat to obscure pattern
-      const interval = 2_000 + Math.random() * 6_000;
-      this.dummyTimer = setTimeout(() => {
-        if (this.closed || !this.sessionKey) return;
-        this.send({ type: "_d", from: "", timestamp: 0 } as unknown as AnyClusterFrame);
-        scheduleNext();
-      }, interval);
-    };
-    scheduleNext();
+    this.scheduleDummyTick();
   }
 
+  private scheduleDummyTick() {
+    // Random interval 2-8 seconds — interleaves with heartbeat to obscure pattern
+    const interval = 2_000 + Math.random() * 6_000;
+    this.dummyTimer = setTimeout(this.dummyTick, interval);
+  }
+
+  private dummyTick = () => {
+    if (this.closed || !this.sessionKey) return;
+    this.send({ type: "_d", from: "", timestamp: 0 } as unknown as AnyClusterFrame);
+    this.scheduleDummyTick();
+  };
+
   // ── Cleanup ────────────────────────────────────────────────────
   close(code = 1000, reason = "normal") {
     if (this.closed) return;

package/src/e2e/helpers.ts

@@ -23,11 +23,6 @@ export function allocPort(): number {
   return nextPort++;
 }
 
-/** Reset port counter (call in afterAll if tests run in a loop). */
-export function resetPorts(start = 19500): void {
-  nextPort = start;
-}
-
 // ── Logger ──────────────────────────────────────────────────────────
 
 /** Minimal no-op logger satisfying PluginLogger. */
@@ -110,6 +105,7 @@ function buildConfig(options: TestNodeOptions): ClawMatrixConfig {
     handoffTimeout: options.handoffTimeout ?? 600_000,
     modelTimeout: options.modelTimeout ?? 120_000,
     toolTimeout: options.toolTimeout ?? 30_000,
+    disconnectGrace: 0,
     peerApproval: {
       enabled: false,
       mode: "notify",

package/src/file-transfer.ts

@@ -1,5 +1,5 @@
 import { createHash } from "node:crypto";
-import { readFile, writeFile, stat, mkdir } from "node:fs/promises";
+import { readFile, writeFile, stat, mkdir, lstat, realpath } from "node:fs/promises";
 import path from "node:path";
 import { debug } from "./debug.ts";
 import type { PeerManager } from "./peer-manager.ts";
@@ -40,6 +40,7 @@ interface PendingTransfer {
   expectedChunks?: number;
   expectedChecksum?: string;
   receivedChunks?: number;
+  onProgress?: (progress: TransferProgress) => void;
 }
 
 interface ReceivingTransfer {
@@ -59,6 +60,20 @@ interface ReceivingTransfer {
   cachedData?: Buffer;
 }
 
+export interface TransferProgress {
+  sessionId: string;
+  direction: "push" | "pull";
+  sentChunks: number;
+  totalChunks: number;
+  bytesTransferred: number;
+  totalBytes: number;
+}
+
+export interface TransferOptions {
+  /** Called after each chunk is acknowledged. */
+  onProgress?: (progress: TransferProgress) => void;
+}
+
 export interface TransferResult {
   success: boolean;
   bytesTransferred: number;
@@ -87,10 +102,10 @@ export class FileTransferManager {
 
   // ── Public API ──────────────────────────────────────────────────
 
-  async pushFile(remoteNode: string, localPath: string, remotePath: string): Promise<TransferResult> {
+  async pushFile(remoteNode: string, localPath: string, remotePath: string, opts?: TransferOptions): Promise<TransferResult> {
     this.ensureEnabled();
     const resolvedPath = path.resolve(localPath);
-    this.validatePath(resolvedPath);
+    await this.validatePath(resolvedPath);
 
     const fileData = await readFile(resolvedPath);
     if (fileData.length > this.config.maxFileSize) {
@@ -117,6 +132,7 @@ export class FileTransferManager {
         chunkSize: this.config.chunkSize,
         totalChunks,
         sentChunks: 0,
+        onProgress: opts?.onProgress,
       });
 
       this.peerManager.sendTo(remoteNode, {
@@ -139,10 +155,10 @@ export class FileTransferManager {
     });
   }
 
-  async pullFile(remoteNode: string, remotePath: string, localPath: string): Promise<TransferResult> {
+  async pullFile(remoteNode: string, remotePath: string, localPath: string, opts?: TransferOptions): Promise<TransferResult> {
     this.ensureEnabled();
     const resolvedPath = path.resolve(localPath);
-    this.validatePath(resolvedPath);
+    await this.validatePath(resolvedPath);
 
     const sessionId = crypto.randomUUID();
 
@@ -160,6 +176,7 @@ export class FileTransferManager {
         timer,
         chunks: new Map(),
         receivedChunks: 0,
+        onProgress: opts?.onProgress,
       });
 
       this.peerManager.sendTo(remoteNode, {
@@ -196,7 +213,7 @@ export class FileTransferManager {
     if (direction === "push") {
       // Remote wants to push a file to us
       const resolvedTarget = path.resolve(targetPath);
-      if (!this.isPathAllowed(resolvedTarget)) {
+      if (!(await this.isPathAllowed(resolvedTarget))) {
         this.sendAck(frame.from, sessionId, frame.id, false, "Target path not allowed");
         return;
       }
@@ -226,7 +243,7 @@ export class FileTransferManager {
     } else {
       // Remote wants to pull a file from us
       const resolvedSource = path.resolve(filePath);
-      if (!this.isPathAllowed(resolvedSource)) {
+      if (!(await this.isPathAllowed(resolvedSource))) {
         this.sendAck(frame.from, sessionId, frame.id, false, "Source path not allowed");
         return;
       }
@@ -331,6 +348,16 @@ export class FileTransferManager {
         payload: { sessionId, chunkIndex, success: true },
       } as FileTransferChunkAck);
 
+      pending.onProgress?.({
+        sessionId,
+        direction: "pull",
+        sentChunks: pending.receivedChunks!,
+        totalChunks: pending.expectedChunks ?? 0,
+        // Use current chunk size as proxy — Math.min clamps the last (smaller) chunk correctly
+        bytesTransferred: Math.min(pending.receivedChunks! * buf.length, pending.expectedSize ?? 0),
+        totalBytes: pending.expectedSize ?? 0,
+      });
+
       // Check if all chunks received
       if (pending.receivedChunks === pending.expectedChunks) {
         this.finalizePull(sessionId).catch((err) => {
@@ -387,6 +414,14 @@ export class FileTransferManager {
         return;
       }
       pending.sentChunks = chunkIndex + 1;
+      pending.onProgress?.({
+        sessionId,
+        direction: "push",
+        sentChunks: pending.sentChunks!,
+        totalChunks: pending.totalChunks!,
+        bytesTransferred: Math.min(pending.sentChunks! * (pending.chunkSize ?? this.config.chunkSize), pending.fileData?.length ?? 0),
+        totalBytes: pending.fileData?.length ?? 0,
+      });
       if (pending.sentChunks! < pending.totalChunks!) {
         this.sendNextChunk(sessionId);
       }
@@ -442,13 +477,13 @@ export class FileTransferManager {
   }
 
   destroy(): void {
-    for (const [id, transfer] of this.pending) {
+    for (const [, transfer] of this.pending) {
       clearTimeout(transfer.timer);
       transfer.reject(new Error("FileTransferManager destroyed"));
     }
     this.pending.clear();
 
-    for (const [id, transfer] of this.receiving) {
+    for (const [, transfer] of this.receiving) {
       clearTimeout(transfer.timer);
     }
     this.receiving.clear();
@@ -462,20 +497,35 @@ export class FileTransferManager {
     }
   }
 
-  private validatePath(resolvedPath: string): void {
-    if (!this.isPathAllowed(resolvedPath)) {
+  private async validatePath(resolvedPath: string): Promise<void> {
+    if (!(await this.isPathAllowed(resolvedPath))) {
       throw new Error(`Path not allowed: ${resolvedPath}`);
     }
   }
 
-  private isPathAllowed(resolvedPath: string): boolean {
+  private async isPathAllowed(resolvedPath: string): Promise<boolean> {
     // TODO(security): allowedPaths 为空时默认允许所有路径，当前仅用于受信任网络。
     // 开放到非受信环境前需改为默认拒绝，或要求显式配置 allowedPaths。
     if (this.config.allowedPaths.length === 0) return true;
-    const normalized = path.resolve(resolvedPath);
+
+    // Resolve symlinks to prevent path traversal via symlink
+    let realResolved: string;
+    try {
+      realResolved = await realpath(resolvedPath);
+    } catch {
+      // File doesn't exist yet (for write targets) — check parent directory
+      const parentDir = path.dirname(resolvedPath);
+      try {
+        realResolved = path.join(await realpath(parentDir), path.basename(resolvedPath));
+      } catch {
+        // Parent doesn't exist either — use the resolved path as-is
+        realResolved = resolvedPath;
+      }
+    }
+
     return this.config.allowedPaths.some((allowed) => {
       const resolvedAllowed = path.resolve(allowed);
-      return normalized === resolvedAllowed || normalized.startsWith(resolvedAllowed + path.sep);
+      return realResolved === resolvedAllowed || realResolved.startsWith(resolvedAllowed + path.sep);
     });
   }
 

package/src/handoff.ts

@@ -54,16 +54,33 @@ export class HandoffManager {
   // Multi-device sync: track which nodes are watching each handoff session (by sessionId)
   private sessionWatchers = new Map<string, Set<string>>();
 
+  // Pre-built indexes for O(1) agent lookup
+  private agentById = new Map<string, ClawMatrixConfig["agents"][number]>();
+  private agentsByTag = new Map<string, ClawMatrixConfig["agents"][number]>();
+
   constructor(config: ClawMatrixConfig, peerManager: PeerManager, gatewayInfo: GatewayInfo) {
     this.config = config;
     this.peerManager = peerManager;
     this.gatewayInfo = gatewayInfo;
     this.taskActivity = new TaskActivityBroadcaster(config, peerManager);
 
+    // Build agent indexes
+    for (const a of config.agents) {
+      this.agentById.set(a.id, a);
+      for (const t of a.tags) this.agentsByTag.set(t, a);
+    }
+
     // Periodically clean up stale input_required entries
     this.staleCleanupTimer = setInterval(() => this.cleanupStale(), STALE_CLEANUP_INTERVAL);
   }
 
+  private findLocalAgent(target: string): ClawMatrixConfig["agents"][number] | undefined {
+    if (target.startsWith("tags:")) {
+      return this.agentsByTag.get(target.slice(5));
+    }
+    return this.agentById.get(target);
+  }
+
   // ── Multi-device sync helpers ──────────────────────────────────
 
   private addSessionWatcher(sessionId: string, nodeId: string) {
@@ -271,13 +288,7 @@ export class HandoffManager {
     const { id, from, payload } = frame;
 
     // Find matching local agent
-    const agent = this.config.agents.find((a) => {
-      if (payload.target.startsWith("tags:")) {
-        const tag = payload.target.slice(5);
-        return a.tags.includes(tag);
-      }
-      return a.id === payload.target;
-    });
+    const agent = this.findLocalAgent(payload.target);
 
     if (!agent) {
       this.peerManager.sendTo(from, {
@@ -477,6 +488,8 @@ export class HandoffManager {
     const decoder = new TextDecoder();
     const chunks: string[] = [];
     let buffer = "";
+    // Cache active entry lookup outside the hot loop — stable during the stream
+    const activeEntry = this.active.get(handoffId);
 
     try {
       while (true) {
@@ -510,7 +523,6 @@ export class HandoffManager {
 
               // Broadcast progress to mobile nodes (throttled, detail is just
               // a heartbeat — don't send token-level deltas as they're meaningless fragments)
-              const activeEntry = this.active.get(handoffId);
               if (activeEntry) {
                 this.taskActivity.broadcast(
                   handoffId, "handoff", "progress", activeEntry.agent, activeEntry.startedAt,
@@ -605,6 +617,7 @@ export class HandoffManager {
 
     // If canceled during input_required, no runAgentTurn is running to clean up
     if (wasInputRequired) {
+      this.sessionWatchers.delete(entry.sessionId);
       this.active.delete(frame.id);
     }