clawmatrix 0.2.7 → 0.2.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawmatrix",
-  "version": "0.2.7",
+  "version": "0.2.8",
   "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

@@ -8,7 +8,7 @@ import {
 import type { PeerManager } from "./peer-manager.ts";
 import type { ClawMatrixConfig } from "./config.ts";
 import type { GatewayInfo } from "./tool-proxy.ts";
-import { spawnProcess, readFileText } from "./compat.ts";
+import { spawnProcess, readFileText, readFileHead, readFileTail } from "./compat.ts";
 import { debug } from "./debug.ts";
 import { homedir } from "node:os";
 import { join } from "node:path";
@@ -57,6 +57,29 @@ const DEFAULT_SESSION_TTL = 1_800_000;
 const DEFAULT_MAX_SESSIONS = 5;
 const CLEANUP_INTERVAL = 120_000;
 const SESSION_INIT_TIMEOUT = 60_000; // 60s timeout for ACP agent initialization
+const REUSE_POOL_TTL = 60_000; // keep oneshot sessions alive for 60s for reuse
+const PREWARM_DELAY = 5_000; // delay before prewarming after a session is used
+const DAEMON_IDLE_TTL = 300_000; // kill daemon after 5 min idle
+
+// ── Agent Daemon: long-lived process per agent type ─────────────
+
+/**
+ * A long-lived ACP agent process that stays alive across multiple sessions.
+ * Instead of spawning a new process per session, we reuse the same initialized
+ * connection and call newSession() which takes milliseconds vs seconds for a cold spawn.
+ */
+interface AgentDaemon {
+  agent: string;
+  cwd: string;
+  conn: ClientSideConnection;
+  proc: { kill: () => void; exited: Promise<number> };
+  /** Per-session stream callbacks keyed by ACP session ID */
+  streamCallbacks: Map<string, ((delta: string, event?: string) => void) | null>;
+  lastActiveAt: number;
+  idleTimer: ReturnType<typeof setTimeout>;
+  /** Set to true when process has exited */
+  dead: boolean;
+}
 
 // ── Session state on receiver side ───────────────────────────────
 
@@ -124,6 +147,17 @@ export class AcpProxy {
   private cleanupTimer: ReturnType<typeof setInterval> | null = null;
   // Multi-device sync: track which nodes are watching each session
   private sessionWatchers = new Map<string, Set<string>>();
+  // Session reuse pool: oneshot sessions kept alive briefly for reuse
+  private reusePool = new Map<string, { session: AcpSession; timer: ReturnType<typeof setTimeout> }>();
+  // Prewarm pool: pre-initialized ACP connections ready for immediate use
+  private warmPool = new Map<string, AcpSession[]>();
+  // Track pending prewarm timers so they can be cancelled on dispose
+  private prewarmTimers = new Set<ReturnType<typeof setTimeout>>();
+  private disposed = false;
+  // Agent daemon pool: long-lived process per agent type, reused across sessions
+  private daemons = new Map<string, AgentDaemon>();
+  // In-flight daemon acquisition: prevents multiple concurrent spawns for same agent
+  private daemonStarting = new Map<string, Promise<AgentDaemon>>();
 
   constructor(config: ClawMatrixConfig, peerManager: PeerManager, openclawConfig?: Record<string, unknown>, gatewayInfo?: GatewayInfo) {
     this.config = config;
@@ -577,7 +611,7 @@ export class AcpProxy {
               });
             }
             if (mode === "oneshot" && task) {
-              this.destroySession(newSession);
+              this.returnToReusePool(newSession, cwd ?? process.cwd());
             }
           } else {
             // Re-create native session
@@ -637,7 +671,7 @@ export class AcpProxy {
             });
           }
           if (mode === "oneshot" && task) {
-            this.destroySession(session);
+            this.returnToReusePool(session, cwd ?? process.cwd());
           }
         } else {
           // Create new native OpenClaw session
@@ -871,6 +905,15 @@ export class AcpProxy {
       return;
     }
 
+    if (session.kind !== "acp") {
+      this.peerManager.sendTo(from, {
+        type: "acp_set_mode_res", id, from: this.config.nodeId, to: from,
+        timestamp: Date.now(),
+        payload: { success: false, error: "Mode switching not supported for native sessions" },
+      } satisfies AcpSetModeResponse);
+      return;
+    }
+
     try {
       await session.conn.setSessionMode({
         sessionId: session.acpSessionId,
@@ -910,8 +953,8 @@ export class AcpProxy {
       timestamp: Date.now(),
       payload: {
         success: true,
-        modes: session.availableModes,
-        currentModeId: session.currentModeId,
+        modes: session.kind === "acp" ? session.availableModes : undefined,
+        currentModeId: session.kind === "acp" ? session.currentModeId : undefined,
       },
     } satisfies AcpGetModesResponse);
   }
@@ -1022,17 +1065,17 @@ export class AcpProxy {
               const sessionsDir = join(agentsDir, agentId, "sessions");
               if (entry.sessionFile) {
                 const candidate = join(sessionsDir, entry.sessionFile);
-                try { await readFileText(candidate); return candidate; } catch { /* try default */ }
+                try { await access(candidate); return candidate; } catch { /* try default */ }
               }
               const candidate = join(sessionsDir, `${sessionId}.jsonl`);
-              try { await readFileText(candidate); return candidate; } catch { /* continue */ }
+              try { await access(candidate); return candidate; } catch { /* continue */ }
             }
           }
         } catch { /* store unreadable */ }
 
         // Fallback: try direct file path
         const candidate = join(agentsDir, agentId, "sessions", `${sessionId}.jsonl`);
-        try { await readFileText(candidate); return candidate; } catch { /* next agent */ }
+        try { await access(candidate); return candidate; } catch { /* next agent */ }
       }
     } catch { /* no agents directory */ }
 
@@ -1049,16 +1092,282 @@ export class AcpProxy {
     return null;
   }
 
+  // ── Internal: agent daemon pool ─────────────────────────────────
+
+  /**
+   * Get or create a long-lived daemon for the given agent.
+   * The daemon process stays alive and its initialized connection is reused
+   * for all subsequent newSession() calls — eliminating spawn+init overhead.
+   */
+  private async getOrCreateDaemon(agent: string, cwd: string): Promise<AgentDaemon> {
+    const key = `${agent}:${cwd}`;
+    // Return existing healthy daemon for this agent+cwd
+    const existing = this.daemons.get(key);
+    if (existing && !existing.dead) {
+      existing.lastActiveAt = Date.now();
+      this.resetDaemonIdleTimer(existing);
+      return existing;
+    }
+
+    // Prevent concurrent spawns for the same agent+cwd
+    const inflight = this.daemonStarting.get(key);
+    if (inflight) return inflight;
+
+    const promise = this.spawnDaemon(agent, cwd);
+    this.daemonStarting.set(key, promise);
+    try {
+      const daemon = await promise;
+      return daemon;
+    } finally {
+      this.daemonStarting.delete(key);
+    }
+  }
+
+  private async spawnDaemon(agent: string, cwd: string): Promise<AgentDaemon> {
+    const streamCallbacks = new Map<string, ((delta: string, event?: string) => void) | null>();
+
+    const { conn, proc } = await this.spawnAndInit(agent, cwd, "spawnDaemon", (params) => {
+      const acpSessionId = (params as unknown as { sessionId?: string }).sessionId;
+      if (!acpSessionId) {
+        debug("acp", `[${agent}:daemon] sessionUpdate missing sessionId, cannot route`);
+        return null;
+      }
+      return streamCallbacks.get(acpSessionId) ?? null;
+    });
+
+    debug("acp", `[${agent}] daemon initialized`);
+
+    const key = `${agent}:${cwd}`;
+    const daemon: AgentDaemon = {
+      agent,
+      cwd,
+      conn,
+      proc,
+      streamCallbacks,
+      lastActiveAt: Date.now(),
+      idleTimer: setTimeout(() => {}, 0), // placeholder, reset below
+      dead: false,
+    };
+
+    // Monitor process exit — clean up daemon and any sessions using its connection
+    const onDaemonExit = () => {
+      daemon.dead = true;
+      // Only remove from map if this daemon hasn't been replaced by a new one
+      if (this.daemons.get(key) === daemon) this.daemons.delete(key);
+      // Clean up sessions that were using this daemon's connection
+      for (const [sid, s] of this.sessions) {
+        if (s.kind === "acp" && s.conn === daemon.conn) {
+          this.sessions.delete(sid);
+          debug("acp", `daemon exited: cleaned up session ${sid} (agent=${daemon.agent})`);
+        }
+      }
+    };
+    proc.exited.then(onDaemonExit).catch(onDaemonExit);
+
+    this.resetDaemonIdleTimer(daemon);
+    this.daemons.set(key, daemon);
+    return daemon;
+  }
+
+  private resetDaemonIdleTimer(daemon: AgentDaemon) {
+    clearTimeout(daemon.idleTimer);
+    daemon.idleTimer = setTimeout(() => {
+      if (daemon.dead) return;
+      // Only kill if no active sessions are using this daemon
+      const hasActiveSessions = [...this.sessions.values()].some(
+        (s) => s.kind === "acp" && s.agent === daemon.agent && s.conn === daemon.conn,
+      );
+      if (!hasActiveSessions) {
+        debug("acp", `daemon idle timeout: killing ${daemon.agent} (cwd=${daemon.cwd})`);
+        daemon.dead = true;
+        this.daemons.delete(`${daemon.agent}:${daemon.cwd}`);
+        try { daemon.proc.kill(); } catch { /* best effort */ }
+      } else {
+        // Sessions still active, reschedule
+        this.resetDaemonIdleTimer(daemon);
+      }
+    }, DAEMON_IDLE_TTL);
+  }
+
+  /**
+   * Create a new ACP session using the daemon's long-lived connection.
+   * Falls back to spawnAndConnect if daemon is unavailable.
+   */
+  private async createSessionViaDaemon(
+    agent: string,
+    cwd: string,
+    from: string,
+  ): Promise<AcpSession> {
+    const daemon = await this.getOrCreateDaemon(agent, cwd);
+
+    const response = await daemon.conn.newSession({ cwd, mcpServers: [] });
+    debug("acp", `[${agent}] daemon session created: ${response.sessionId}`);
+
+    const availableModes: AcpModeInfo[] | undefined = response.modes?.availableModes?.map(
+      (m) => ({ id: m.id, name: m.name, description: m.description ?? undefined }),
+    );
+
+    const session: AcpSession = {
+      kind: "acp",
+      sessionId: crypto.randomUUID(),
+      agent,
+      acpSessionId: response.sessionId,
+      conn: daemon.conn,
+      proc: daemon.proc,
+      lastActiveAt: Date.now(),
+      from,
+      setStreamCallback: (cb) => {
+        daemon.streamCallbacks.set(response.sessionId, cb);
+      },
+      availableModes,
+      currentModeId: response.modes?.currentModeId,
+    };
+
+    return session;
+  }
+
+  // ── Internal: session reuse & prewarming ─────────────────────────
+
+  /** Try to grab a reusable session from the reuse pool (same agent, same cwd). */
+  private takeFromReusePool(agent: string, cwd: string): AcpSession | null {
+    const key = `${agent}:${cwd}`;
+    const entry = this.reusePool.get(key);
+    if (!entry) return null;
+    this.reusePool.delete(key);
+    clearTimeout(entry.timer);
+    debug("acp", `reuse pool hit: agent=${agent} cwd=${cwd} sessionId=${entry.session.sessionId}`);
+    return entry.session;
+  }
+
+  /** Find the daemon that owns this session's connection (if any). */
+  private findDaemonByConn(session: AcpSession): AgentDaemon | null {
+    // Fast path: check the exact agent+cwd key
+    for (const daemon of this.daemons.values()) {
+      if (daemon.conn === session.conn) return daemon;
+    }
+    return null;
+  }
+
+  /** Return a completed oneshot session to the reuse pool instead of destroying it. */
+  private returnToReusePool(session: AcpSession, cwd: string) {
+    // Daemon-backed sessions don't need reuse pool — the daemon stays alive
+    const daemon = this.findDaemonByConn(session);
+    if (daemon) {
+      daemon.streamCallbacks.delete(session.acpSessionId);
+      debug("acp", `daemon-backed oneshot done: agent=${session.agent} (daemon stays alive)`);
+      return;
+    }
+
+    const key = `${session.agent}:${cwd}`;
+    // Evict any existing entry for the same key
+    const existing = this.reusePool.get(key);
+    if (existing) {
+      clearTimeout(existing.timer);
+      this.destroySession(existing.session);
+    }
+    const timer = setTimeout(() => {
+      const entry = this.reusePool.get(key);
+      if (entry?.session.sessionId === session.sessionId) {
+        this.reusePool.delete(key);
+        this.destroySession(session);
+        debug("acp", `reuse pool expired: agent=${session.agent} cwd=${cwd}`);
+      }
+    }, REUSE_POOL_TTL);
+    this.reusePool.set(key, { session, timer });
+    debug("acp", `reuse pool stored: agent=${session.agent} cwd=${cwd} ttl=${REUSE_POOL_TTL / 1000}s`);
+  }
+
+  /** Try to grab a pre-warmed session from the warm pool (same agent + cwd). */
+  private takeFromWarmPool(agent: string, cwd: string): AcpSession | null {
+    const key = `${agent}:${cwd}`;
+    const pool = this.warmPool.get(key);
+    if (!pool || pool.length === 0) return null;
+    const session = pool.shift()!;
+    debug("acp", `warm pool hit: agent=${agent} cwd=${cwd} sessionId=${session.sessionId}`);
+    return session;
+  }
+
+  /** Schedule a prewarm for the given agent after a short delay. */
+  private schedulePrewarm(agent: string, cwd: string) {
+    const timer = setTimeout(async () => {
+      this.prewarmTimers.delete(timer);
+      if (this.disposed) return;
+      // Only prewarm if the warm pool is empty for this agent+cwd
+      const key = `${agent}:${cwd}`;
+      const pool = this.warmPool.get(key);
+      if (pool && pool.length > 0) return;
+      try {
+        debug("acp", `prewarming agent=${agent} cwd=${cwd}`);
+        const session = await this.spawnAndInitSession(agent, cwd, "prewarm");
+        if (this.disposed) { this.destroySession(session); return; }
+        if (!this.warmPool.has(key)) this.warmPool.set(key, []);
+        this.warmPool.get(key)!.push(session);
+        debug("acp", `warm pool ready: agent=${agent} sessionId=${session.sessionId}`);
+      } catch (err) {
+        debug("acp", `prewarm failed: agent=${agent} error=${errorMessage(err)}`);
+      }
+    }, PREWARM_DELAY);
+    this.prewarmTimers.add(timer);
+  }
+
   // ── Internal: ACP session management (receiver) ────────────────
 
   private async createSession(agent: string, cwd: string | undefined, from: string): Promise<AcpSession> {
-    const cmd = this.resolveCommand(agent);
     const effectiveCwd = cwd ?? process.cwd();
 
-    debug("acp", `createSession: spawning ${cmd.join(" ")} in ${effectiveCwd} (for ${from})`);
+    // 1. Try daemon pool first (long-lived process, instant newSession)
+    try {
+      return await this.createSessionViaDaemon(agent, effectiveCwd, from);
+    } catch (err) {
+      debug("acp", `daemon session failed for ${agent}: ${errorMessage(err)}, falling back`);
+    }
+
+    // 2. Check reuse pool (same agent + cwd, still alive)
+    const reused = this.takeFromReusePool(agent, effectiveCwd);
+    if (reused) {
+      reused.from = from;
+      reused.lastActiveAt = Date.now();
+      reused.sessionId = crypto.randomUUID();
+      this.monitorProcess(reused);
+      return reused;
+    }
+
+    // 3. Check warm pool (pre-initialized, same agent + cwd)
+    const warm = this.takeFromWarmPool(agent, effectiveCwd);
+    if (warm) {
+      warm.from = from;
+      warm.lastActiveAt = Date.now();
+      warm.sessionId = crypto.randomUUID();
+      this.monitorProcess(warm);
+      this.schedulePrewarm(agent, effectiveCwd);
+      return warm;
+    }
+
+    // 4. Cold start: spawn + initialize (last resort)
+    const session = await this.spawnAndInitSession(agent, effectiveCwd, from);
+    this.schedulePrewarm(agent, effectiveCwd);
+    return session;
+  }
+
+  /**
+   * Spawn an ACP agent process, set up NDJSON/stdio, and initialize the ACP connection.
+   * Returns the initialized connection and process handle.
+   * Shared by spawnDaemon (daemon pool) and spawnAndConnect (per-session).
+   *
+   * @param resolveStreamCb Called on each sessionUpdate to resolve the stream callback.
+   *   For daemons this routes by ACP session ID; for per-session it returns a closure variable.
+   */
+  private async spawnAndInit(
+    agent: string,
+    cwd: string,
+    label: string,
+    resolveStreamCb: (params: SessionNotification) => ((delta: string, event?: string) => void) | null | undefined,
+  ): Promise<{ conn: ClientSideConnection; proc: { kill: () => void; exited: Promise<number> } }> {
+    const cmd = this.resolveCommand(agent);
+    debug("acp", `${label}: spawning ${cmd.join(" ")} in ${cwd}`);
 
     const proc = spawnProcess(cmd, {
-      cwd: effectiveCwd,
+      cwd,
       stdout: "pipe",
       stderr: "pipe",
       stdin: "pipe",
@@ -1069,7 +1378,7 @@ export class AcpProxy {
       throw new Error(`Failed to spawn ACP agent "${agent}": no stdio streams`);
     }
 
-    // Capture stderr for diagnostics (agent errors, missing API keys, etc.)
+    // Capture stderr for diagnostics
     if (proc.stderr) {
       const reader = (proc.stderr as ReadableStream<Uint8Array>).getReader();
       const decoder = new TextDecoder();
@@ -1085,19 +1394,14 @@ export class AcpProxy {
       })();
     }
 
-    // Detect early process exit (e.g., npx not found, package install failure)
     let earlyExit = false;
     const earlyExitPromise = proc.exited.then((code) => {
       earlyExit = true;
       throw new Error(`ACP agent "${agent}" exited during init with code ${code}`);
     });
 
-    // Build ACP connection over NDJSON/stdio
     const stream = ndJsonStream(proc.stdin, proc.stdout);
 
-    // Accumulated text for streaming back — set per-prompt via closure
-    let streamCallback: ((delta: string, event?: string) => void) | null = null;
-
     const conn = new ClientSideConnection(
       (_agentRef) => ({
         requestPermission: async (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
@@ -1106,23 +1410,21 @@ export class AcpProxy {
         sessionUpdate: async (params: SessionNotification): Promise<void> => {
           const update = params.update as Record<string, unknown>;
           const updateType = update.sessionUpdate as string;
-
-          // Extract text delta from content chunks
+          const cb = resolveStreamCb(params);
           if (updateType === "agent_message_chunk" || updateType === "agent_thought_chunk") {
             const content = (update as { content?: { type?: string; text?: string } }).content;
             if (content?.type === "text" && content.text) {
-              streamCallback?.(content.text, updateType);
+              cb?.(content.text, updateType);
             }
           } else if (updateType === "tool_call") {
             const toolName = (update as { title?: string }).title
               || (update as { toolCallId?: string }).toolCallId
               || "unknown";
-            debug("acp", `tool_call update: title=${JSON.stringify((update as any).title)} toolCallId=${JSON.stringify((update as any).toolCallId)} keys=${Object.keys(update).join(",")}`);
-            streamCallback?.(`\n[tool_call: ${toolName}]\n`, updateType);
+            cb?.(`\n[tool_call: ${toolName}]\n`, updateType);
           } else if (updateType === "tool_call_update") {
             const status = (update as { status?: string }).status;
             if (status === "completed" || status === "error") {
-              streamCallback?.("", "tool_result");
+              cb?.("", "tool_result");
             }
           }
         },
@@ -1130,74 +1432,86 @@ export class AcpProxy {
       stream,
     );
 
-    // Initialize with timeout — prevents hanging if agent process is stuck
+    let initTimer: ReturnType<typeof setTimeout>;
     const initTimeout = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error(
+      initTimer = setTimeout(() => reject(new Error(
         `ACP agent "${agent}" initialization timed out after ${SESSION_INIT_TIMEOUT / 1000}s`,
       )), SESSION_INIT_TIMEOUT);
     });
 
-    const initAndSession = async () => {
-      // Initialize the ACP connection
-      debug("acp", `[${agent}] initializing ACP connection...`);
-      await conn.initialize({
-        protocolVersion: 1,
-        clientInfo: { name: "ClawMatrix", version: "0.1.0" },
-        clientCapabilities: {},
-      });
-      debug("acp", `[${agent}] ACP connection initialized, creating session...`);
-
-      // Create a new session
-      return conn.newSession({
-        cwd: effectiveCwd,
-        mcpServers: [],
-      });
-    };
-
-    let sessionResponse: Awaited<ReturnType<typeof conn.newSession>>;
     try {
-      sessionResponse = await Promise.race([
-        initAndSession(),
+      await Promise.race([
+        conn.initialize({
+          protocolVersion: 1,
+          clientInfo: { name: "ClawMatrix", version: "0.1.0" },
+          clientCapabilities: {},
+        }),
         initTimeout,
         earlyExitPromise as Promise<never>,
       ]);
     } catch (err) {
-      const msg = err instanceof Error ? err.message : (typeof err === "string" ? err : JSON.stringify(err));
-      debug("acp", `[${agent}] init failed: ${msg}`);
-      // Kill the process if init failed
       if (!earlyExit) proc.kill();
-      throw new Error(`ACP agent "${agent}" init failed: ${msg}`);
+      throw err;
+    } finally {
+      clearTimeout(initTimer!);
     }
-    debug("acp", `[${agent}] session created: ${sessionResponse.sessionId}`);
 
-    // Extract available modes from session response
-    const availableModes: AcpModeInfo[] | undefined = sessionResponse.modes?.availableModes?.map(
+    return { conn, proc };
+  }
+
+  /**
+   * Spawn an ACP agent, initialize, then call `sessionFactory` to create/resume the session.
+   * Used for per-session (non-daemon) spawns.
+   */
+  private async spawnAndConnect(
+    agent: string,
+    cwd: string,
+    from: string,
+    label: string,
+    sessionFactory: (conn: ClientSideConnection, cwd: string) => Promise<{ sessionId: string; modes?: { availableModes?: Array<{ id: string; name: string; description?: string }>; currentModeId?: string } }>,
+  ): Promise<AcpSession> {
+    let streamCallback: ((delta: string, event?: string) => void) | null = null;
+
+    const { conn, proc } = await this.spawnAndInit(agent, cwd, label, () => streamCallback);
+
+    let response: Awaited<ReturnType<typeof sessionFactory>>;
+    try {
+      response = await sessionFactory(conn, cwd);
+    } catch (err) {
+      proc.kill();
+      throw err;
+    }
+    debug("acp", `[${agent}] session ready: ${response.sessionId}`);
+
+    const availableModes: AcpModeInfo[] | undefined = response.modes?.availableModes?.map(
       (m) => ({ id: m.id, name: m.name, description: m.description ?? undefined }),
     );
-    const currentModeId = sessionResponse.modes?.currentModeId;
-
-    const sessionId = crypto.randomUUID();
 
     const session: AcpSession = {
       kind: "acp",
-      sessionId,
+      sessionId: crypto.randomUUID(),
       agent,
-      acpSessionId: sessionResponse.sessionId,
+      acpSessionId: response.sessionId,
       conn,
       proc,
       lastActiveAt: Date.now(),
       from,
       setStreamCallback: (cb) => { streamCallback = cb; },
       availableModes,
-      currentModeId,
+      currentModeId: response.modes?.currentModeId,
     };
 
-    // Monitor process exit — clean up dead sessions proactively
     this.monitorProcess(session);
-
     return session;
   }
 
+  /** Spawn a new ACP agent process, initialize ACP connection, and create a session. */
+  private spawnAndInitSession(agent: string, cwd: string, from: string): Promise<AcpSession> {
+    return this.spawnAndConnect(agent, cwd, from, "spawnAndInitSession", (conn, effectiveCwd) =>
+      conn.newSession({ cwd: effectiveCwd, mcpServers: [] }),
+    );
+  }
+
   /** Watch for unexpected process exit and clean up the session. */
   private monitorProcess(session: AcpSession) {
     session.proc.exited.then(() => {
@@ -1386,7 +1700,7 @@ export class AcpProxy {
 
     const reader = body.getReader();
     const decoder = new TextDecoder();
-    let full = "";
+    const chunks: string[] = [];
     let buffer = "";
 
     try {
@@ -1407,7 +1721,7 @@ export class AcpProxy {
             const parsed = JSON.parse(data);
             const delta = parsed.choices?.[0]?.delta?.content;
             if (delta) {
-              full += delta;
+              chunks.push(delta);
               const streamFrame: AcpStreamChunk = {
                 type: "acp_stream",
                 id: requestId,
@@ -1428,141 +1742,19 @@ export class AcpProxy {
       reader.releaseLock();
     }
 
-    return full;
+    return chunks.join("");
   }
 
   /** Create a session by resuming an existing ACP session ID. */
-  private async createSessionWithResume(
+  private createSessionWithResume(
     agent: string,
     acpSessionId: string,
     cwd: string,
     from: string,
   ): Promise<AcpSession> {
-    const cmd = this.resolveCommand(agent);
-    debug("acp", `createSessionWithResume: spawning ${cmd.join(" ")} in ${cwd} (resume ${acpSessionId.slice(0, 8)}...)`);
-
-    const proc = spawnProcess(cmd, {
-      cwd,
-      stdout: "pipe",
-      stderr: "pipe",
-      stdin: "pipe",
-    });
-
-    if (!proc.stdin || !proc.stdout) {
-      proc.kill();
-      throw new Error(`Failed to spawn ACP agent "${agent}": no stdio streams`);
-    }
-
-    // Capture stderr for diagnostics
-    if (proc.stderr) {
-      const reader = (proc.stderr as ReadableStream<Uint8Array>).getReader();
-      const decoder = new TextDecoder();
-      (async () => {
-        try {
-          while (true) {
-            const { done, value } = await reader.read();
-            if (done) break;
-            const text = decoder.decode(value, { stream: true }).trim();
-            if (text) debug("acp", `[${agent}:stderr] ${text}`);
-          }
-        } catch { /* stream closed */ }
-      })();
-    }
-
-    let earlyExit = false;
-    const earlyExitPromise = proc.exited.then((code) => {
-      earlyExit = true;
-      throw new Error(`ACP agent "${agent}" exited during resume init with code ${code}`);
-    });
-
-    const stream = ndJsonStream(proc.stdin, proc.stdout);
-    let streamCallback: ((delta: string, event?: string) => void) | null = null;
-
-    const conn = new ClientSideConnection(
-      (_agentRef) => ({
-        requestPermission: async (params: RequestPermissionRequest): Promise<RequestPermissionResponse> => {
-          return this.resolvePermission(params);
-        },
-        sessionUpdate: async (params: SessionNotification): Promise<void> => {
-          const update = params.update as Record<string, unknown>;
-          const updateType = update.sessionUpdate as string;
-          if (updateType === "agent_message_chunk" || updateType === "agent_thought_chunk") {
-            const content = (update as { content?: { type?: string; text?: string } }).content;
-            if (content?.type === "text" && content.text) {
-              streamCallback?.(content.text, updateType);
-            }
-          } else if (updateType === "tool_call") {
-            const toolName = (update as { title?: string }).title
-              || (update as { toolCallId?: string }).toolCallId
-              || "unknown";
-            debug("acp", `tool_call update: title=${JSON.stringify((update as any).title)} toolCallId=${JSON.stringify((update as any).toolCallId)} keys=${Object.keys(update).join(",")}`);
-            streamCallback?.(`\n[tool_call: ${toolName}]\n`, updateType);
-          } else if (updateType === "tool_call_update") {
-            const status = (update as { status?: string }).status;
-            if (status === "completed" || status === "error") {
-              streamCallback?.("", "tool_result");
-            }
-          }
-        },
-      }),
-      stream,
-    );
-
-    const initTimeout = new Promise<never>((_, reject) => {
-      setTimeout(() => reject(new Error(
-        `ACP agent "${agent}" resume initialization timed out after ${SESSION_INIT_TIMEOUT / 1000}s`,
-      )), SESSION_INIT_TIMEOUT);
-    });
-
-    const initAndResume = async () => {
-      await conn.initialize({
-        protocolVersion: 1,
-        clientInfo: { name: "ClawMatrix", version: "0.1.0" },
-        clientCapabilities: {},
-      });
-
-      // Resume the existing ACP session instead of creating a new one
-      return conn.unstable_resumeSession({
-        sessionId: acpSessionId,
-        cwd,
-      });
-    };
-
-    let resumeResponse: Awaited<ReturnType<typeof conn.unstable_resumeSession>>;
-    try {
-      resumeResponse = await Promise.race([
-        initAndResume(),
-        initTimeout,
-        earlyExitPromise as Promise<never>,
-      ]);
-    } catch (err) {
-      if (!earlyExit) proc.kill();
-      throw err;
-    }
-
-    const availableModes: AcpModeInfo[] | undefined = resumeResponse.modes?.availableModes?.map(
-      (m) => ({ id: m.id, name: m.name, description: m.description ?? undefined }),
+    return this.spawnAndConnect(agent, cwd, from, "createSessionWithResume", (conn) =>
+      conn.unstable_resumeSession({ sessionId: acpSessionId, cwd }),
     );
-    const currentModeId = resumeResponse.modes?.currentModeId;
-
-    const sessionId = crypto.randomUUID();
-
-    const session: AcpSession = {
-      kind: "acp",
-      sessionId,
-      agent,
-      acpSessionId,
-      conn,
-      proc,
-      lastActiveAt: Date.now(),
-      from,
-      setStreamCallback: (cb) => { streamCallback = cb; },
-      availableModes,
-      currentModeId,
-    };
-
-    this.monitorProcess(session);
-    return session;
   }
 
   /** Read all session stores from disk (OpenClaw + Claude Code). */
@@ -1571,7 +1763,16 @@ export class AcpProxy {
   }
 
   private destroySession(session: AnySession) {
+    invalidateSessionListCache();
     if (session.kind === "acp") {
+      // Clean up daemon stream callback
+      const daemon = this.findDaemonByConn(session);
+      if (daemon) {
+        daemon.streamCallbacks.delete(session.acpSessionId);
+        // Don't kill — process is shared by the daemon
+        return;
+      }
+      // Not a daemon-backed session — kill the process
       try {
         session.proc.kill();
       } catch {
@@ -1844,6 +2045,36 @@ export class AcpProxy {
     }
     this.sessions.clear();
     this.sessionWatchers.clear();
+
+    this.disposed = true;
+
+    // Cancel pending prewarm timers
+    for (const timer of this.prewarmTimers) clearTimeout(timer);
+    this.prewarmTimers.clear();
+
+    // Clean up reuse pool
+    for (const [, entry] of this.reusePool) {
+      clearTimeout(entry.timer);
+      this.destroySession(entry.session);
+    }
+    this.reusePool.clear();
+
+    // Clean up warm pool
+    for (const [, pool] of this.warmPool) {
+      for (const session of pool) {
+        this.destroySession(session);
+      }
+    }
+    this.warmPool.clear();
+
+    // Clean up daemons
+    for (const [, daemon] of this.daemons) {
+      clearTimeout(daemon.idleTimer);
+      daemon.dead = true;
+      try { daemon.proc.kill(); } catch { /* best effort */ }
+    }
+    this.daemons.clear();
+    this.daemonStarting.clear();
   }
 }
 
@@ -1855,9 +2086,7 @@ const TRANSCRIPT_MAX_LINES = 20;
 /** Read the first user message from a session transcript JSONL file. */
 async function readFirstUserMessageFromTranscript(transcriptPath: string): Promise<string | null> {
   try {
-    const content = await readFileText(transcriptPath);
-    // Only scan the head to avoid reading large transcripts
-    const head = content.slice(0, TRANSCRIPT_HEAD_BYTES);
+    const head = await readFileHead(transcriptPath, TRANSCRIPT_HEAD_BYTES);
     const lines = head.split("\n").slice(0, TRANSCRIPT_MAX_LINES);
     for (const line of lines) {
       if (!line.trim()) continue;
@@ -1883,8 +2112,56 @@ async function readFirstUserMessageFromTranscript(transcriptPath: string): Promi
   return null;
 }
 
+// ── Session list cache (stale-while-revalidate) ─────────────────────
+const SESSION_LIST_CACHE_TTL = 30_000; // 30 seconds fresh
+const SESSION_LIST_STALE_TTL = 120_000; // serve stale up to 2 min while refreshing
+let sessionListCache: { result: AcpSessionInfo[]; expiresAt: number; staleAt: number } | null = null;
+let sessionListRefreshing = false;
+
+/** Invalidate the session list cache so the next call re-reads from disk. */
+export function invalidateSessionListCache() {
+  sessionListCache = null;
+}
+
+/** Refresh session list in background (stale-while-revalidate). */
+async function refreshSessionListInBackground() {
+  if (sessionListRefreshing) return;
+  sessionListRefreshing = true;
+  try {
+    const result = await fetchSessionListFromDisk();
+    const now = Date.now();
+    sessionListCache = { result, expiresAt: now + SESSION_LIST_CACHE_TTL, staleAt: now + SESSION_LIST_STALE_TTL };
+  } catch {
+    // Background refresh failed — keep stale data
+  } finally {
+    sessionListRefreshing = false;
+  }
+}
+
 /** Read all ACP session stores from disk (OpenClaw + Claude Code). Can be used without an AcpProxy instance. */
 export async function readAllSessionStoresFromDisk(): Promise<AcpSessionInfo[]> {
+  const now = Date.now();
+  if (sessionListCache) {
+    if (now < sessionListCache.expiresAt) {
+      // Fresh cache — return immediately
+      return sessionListCache.result;
+    }
+    if (now < sessionListCache.staleAt) {
+      // Stale but within grace period — return stale data, refresh in background
+      refreshSessionListInBackground();
+      return sessionListCache.result;
+    }
+  }
+
+  // Cache miss or expired — fetch from disk and cache
+  const results = await fetchSessionListFromDisk();
+  const ts = Date.now();
+  sessionListCache = { result: results, expiresAt: ts + SESSION_LIST_CACHE_TTL, staleAt: ts + SESSION_LIST_STALE_TTL };
+  return results;
+}
+
+/** Fetch session list from disk (no caching). */
+async function fetchSessionListFromDisk(): Promise<AcpSessionInfo[]> {
   const results: AcpSessionInfo[] = [];
 
   // 1. OpenClaw agent session stores (ACP-backed + native OpenClaw sessions)
@@ -1898,20 +2175,22 @@ export async function readAllSessionStoresFromDisk(): Promise<AcpSessionInfo[]>
       try {
         const content = await readFileText(storePath);
         const entries: Record<string, { sessionId?: string; updatedAt?: number; displayName?: string; subject?: string; label?: string; acp?: { agent?: string } }> = JSON.parse(content);
-        for (const [key, entry] of Object.entries(entries)) {
-          if (!entry.sessionId) continue;
-          // Use the OpenClaw agent directory name, not the ACP backend agent.
-          // A cron/handoff session using Claude Code as backend is still an OpenClaw session.
-          // Pure Claude Code sessions are read separately from ~/.claude/history.jsonl.
-          const agent = agentId;
-          // Try to read the first user message from the transcript for description
-          const transcriptPath = join(sessionsDir, `${entry.sessionId}.jsonl`);
-          const firstMessage = await readFirstUserMessageFromTranscript(transcriptPath);
+        const agent = agentId;
+        // Read all transcripts in parallel instead of sequentially
+        const entryList = Object.entries(entries).filter(([, e]) => e.sessionId);
+        const transcriptResults = await Promise.all(
+          entryList.map(([, entry]) => {
+            const transcriptPath = join(sessionsDir, `${entry.sessionId!}.jsonl`);
+            return readFirstUserMessageFromTranscript(transcriptPath);
+          }),
+        );
+        for (let i = 0; i < entryList.length; i++) {
+          const [key, entry] = entryList[i]!;
           results.push({
-            sessionId: entry.sessionId,
+            sessionId: entry.sessionId!,
             cwd: key,
             title: entry.displayName ?? entry.subject ?? entry.label ?? undefined,
-            description: firstMessage ?? undefined,
+            description: transcriptResults[i] ?? undefined,
             updatedAt: entry.updatedAt ? new Date(entry.updatedAt).toISOString() : undefined,
             agent,
           });
@@ -1925,9 +2204,11 @@ export async function readAllSessionStoresFromDisk(): Promise<AcpSessionInfo[]>
   }
 
   // 2. Claude Code session history (~/.claude/history.jsonl)
+  // Only read the last 512KB — newer entries are appended at the end,
+  // so the tail contains the most recent sessions.
   try {
     const historyPath = join(homedir(), ".claude", "history.jsonl");
-    const content = await readFileText(historyPath);
+    const content = await readFileTail(historyPath, 512 * 1024);
     const sessions = new Map<string, { title: string; updatedAt: number; cwd: string }>();
 
     for (const line of content.split("\n")) {

package/src/compat.ts

@@ -5,7 +5,7 @@
  */
 
 import { spawn as cpSpawn } from "node:child_process";
-import { readFile, writeFile } from "node:fs/promises";
+import { open, readFile, stat, writeFile } from "node:fs/promises";
 import { createRequire } from "node:module";
 
 export interface SpawnResult {
@@ -167,6 +167,41 @@ export async function readFileText(path: string): Promise<string> {
   return readFile(path, "utf-8");
 }
 
+/** Read at most `bytes` bytes from the beginning of a file as text. */
+export async function readFileHead(path: string, bytes: number): Promise<string> {
+  const fh = await open(path, "r");
+  try {
+    const buf = Buffer.alloc(bytes);
+    const { bytesRead } = await fh.read(buf, 0, bytes, 0);
+    return buf.toString("utf-8", 0, bytesRead);
+  } finally {
+    await fh.close();
+  }
+}
+
+/** Read at most `bytes` bytes from the end of a file as text. */
+export async function readFileTail(path: string, bytes: number): Promise<string> {
+  const info = await stat(path);
+  const size = info.size;
+  if (size === 0) return "";
+  const readBytes = Math.min(bytes, size);
+  const offset = size - readBytes;
+  const fh = await open(path, "r");
+  try {
+    const buf = Buffer.alloc(readBytes);
+    const { bytesRead } = await fh.read(buf, 0, readBytes, offset);
+    const text = buf.toString("utf-8", 0, bytesRead);
+    // Drop the first (possibly partial) line if we didn't read from start
+    if (offset > 0) {
+      const nl = text.indexOf("\n");
+      return nl >= 0 ? text.slice(nl + 1) : text;
+    }
+    return text;
+  } finally {
+    await fh.close();
+  }
+}
+
 /** Write text to a file (replaces Bun.write()). */
 export async function writeFileText(path: string, content: string): Promise<void> {
   await writeFile(path, content, "utf-8");

package/src/handoff.ts

@@ -91,6 +91,7 @@ export class HandoffManager {
     for (const [id, entry] of this.active) {
       if (entry.status === "input_required" && entry.inputRequiredAt && now - entry.inputRequiredAt > INPUT_REQUIRED_TTL) {
         this.active.delete(id);
+        this.sessionWatchers.delete(entry.sessionId);
         // Notify the requester that the handoff timed out
         this.peerManager.sendTo(entry.from, {
           type: "handoff_res",
@@ -110,6 +111,7 @@ export class HandoffManager {
       // (e.g. cancel arrived during input_required when no process was running)
       if (entry.status === "canceled") {
         this.active.delete(id);
+        this.sessionWatchers.delete(entry.sessionId);
       }
     }
     // Clean stale inputRequiredTargets (requester side)
@@ -355,6 +357,7 @@ export class HandoffManager {
 
     if (activeEntry.status === "canceled") {
       this.active.delete(id);
+      this.sessionWatchers.delete(activeEntry.sessionId);
       return;
     }
 
@@ -401,11 +404,13 @@ export class HandoffManager {
 
       if (activeEntry.status === "canceled") {
         this.active.delete(id);
+        this.sessionWatchers.delete(activeEntry.sessionId);
         return;
       }
 
       activeEntry.status = "completed";
       this.active.delete(id);
+      this.sessionWatchers.delete(activeEntry.sessionId);
 
       // Broadcast task completed
       this.taskActivity.broadcast(id, "handoff", "completed", agent, activeEntry.startedAt);
@@ -429,10 +434,12 @@ export class HandoffManager {
     } catch (err) {
       if (activeEntry.status === "canceled") {
         this.active.delete(id);
+        this.sessionWatchers.delete(activeEntry.sessionId);
         return;
       }
       activeEntry.status = "failed";
       this.active.delete(id);
+      this.sessionWatchers.delete(activeEntry.sessionId);
 
       // Broadcast task failed
       this.taskActivity.broadcast(
@@ -468,7 +475,7 @@ export class HandoffManager {
 
     const reader = body.getReader();
     const decoder = new TextDecoder();
-    let full = "";
+    const chunks: string[] = [];
     let buffer = "";
 
     try {
@@ -489,7 +496,7 @@ export class HandoffManager {
             const parsed = JSON.parse(data);
             const delta = parsed.choices?.[0]?.delta?.content;
             if (delta) {
-              full += delta;
+              chunks.push(delta);
               const streamFrame: HandoffStreamChunk = {
                 type: "handoff_stream",
                 id: handoffId,
@@ -531,7 +538,7 @@ export class HandoffManager {
     this.peerManager.sendTo(to, doneFrame);
     if (sessionId) this.sendToOtherWatchers(sessionId, to, doneFrame);
 
-    return full;
+    return chunks.join("");
   }
 
   /** Handle incoming input_required from remote (requester side). */

package/src/peer-manager.ts

@@ -28,6 +28,26 @@ import type { KeyPair } from "./crypto.ts";
 const RECONNECT_BASE = 1_000;
 const RECONNECT_MAX = 60_000;
 
+/** Frame types that bypass dedup (streams share one id across chunks; responses share id with request). */
+const SKIP_DEDUP_TYPES = new Set([
+  // Streaming
+  "model_stream", "handoff_stream", "acp_stream",
+  // Response frames (share id with their request)
+  "model_res", "tool_res", "tool_batch_res",
+  "handoff_res", "handoff_status_res", "handoff_input_required",
+  // Handoff control (reuse original handoff_req id)
+  "handoff_input", "handoff_cancel", "handoff_status",
+  // Diagnostics & approval
+  "diagnostic_exec_res", "diagnostic_status_res", "peer_approval_res",
+  // ACP responses
+  "acp_res", "acp_close_res", "acp_list_res", "acp_resume_res",
+  "acp_cancel_res", "acp_set_mode_res", "acp_get_modes_res",
+  "chat_history_res",
+  // Terminal
+  "terminal_open_res", "terminal_data", "terminal_resize",
+  "terminal_close", "terminal_close_res",
+]);
+
 /** Classify WebSocket close code into a human-readable reason. */
 function classifyCloseReason(code: number, reason: string): string {
   if (reason) return reason;
@@ -364,6 +384,12 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       tryReconnect();
     });
     ws.addEventListener("close", (ev) => {
+      // Don't reconnect if this was a self-connection (peer URL points to ourselves).
+      // Without this guard, outbound detects self → closes → scheduleReconnect → loop.
+      if (ev.code === 4002 && ev.reason === "self-connection") {
+        debug("peer", `connectToPeer(${peer.nodeId}): self-connection, will not reconnect`);
+        return;
+      }
       if (!lastError) {
         lastError = classifyCloseReason(ev.code, ev.reason);
       }
@@ -397,19 +423,17 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
     // Peer's persistent public key for TOFU identity binding
     const peerPublicKey = conn.remoteIdentityKey ?? undefined;
 
-    // Prevent self-connection: if outbound connection authenticated as our own nodeId
-    // (e.g. peer URL accidentally points to self), close immediately.
-    if (conn.role === "outbound" && nodeId === this.config.nodeId) {
-      debug("peer", `Self-connection detected (outbound to ${nodeId}), closing`);
+    // Prevent self-connection: close immediately if the remote side authenticated
+    // with our own nodeId.  For outbound this means the peer URL accidentally
+    // points to self; for inbound it means a remote node is (mis)using our nodeId.
+    // Exception: loopback connections with the same nodeId are local clients
+    // (Mac desktop app / iOS simulator) and are allowed through.
+    const isLocalClient = conn.role === "inbound" && nodeId === this.config.nodeId && isLoopback(ip);
+    if (nodeId === this.config.nodeId && !isLocalClient) {
+      debug("peer", `Self-connection detected (${conn.role}, nodeId=${nodeId}, ip=${ip}), closing`);
       conn.close(4002, "self-connection");
       return;
     }
-
-    // Peer approval check (inbound only — outbound peers are explicitly configured)
-    // Skip approval for same-nodeId connections from localhost (local clients
-    // like Mac desktop app / iOS simulator). An attacker would need to already
-    // be on the same machine to exploit this, which is outside our threat model.
-    const isLocalClient = nodeId === this.config.nodeId && isLoopback(ip);
     debug("approval", `onPeerAuthenticated: nodeId=${nodeId} role=${conn.role} isLocalClient=${isLocalClient} ip=${ip}`);
     if (conn.role === "inbound" && !isLocalClient) {
       // IP-level approval rate limiting (suppress noise from leaked tokens)
@@ -589,32 +613,10 @@ export class PeerManager extends EventEmitter<PeerManagerEvents> {
       return;
     }
 
-    // Skip dedup for streaming and response frame types.
-    // Stream frames share one id across many chunks.
-    // Response frames (model_res, tool_res, handoff_res, etc.) share the same id
-    // as their request — without this exemption, a relay node that forwarded
-    // the request would mark the id as seen and then drop the returning response.
     // Skip dedup for streaming chunks (same id across many chunks) and response
     // frames (share id with their request — relay would otherwise drop the reply).
-    // handoff_input, handoff_cancel, and handoff_status reuse the original handoff_req id,
-    // so relay nodes that already forwarded the request would drop them as duplicates.
-    const skipDedup = frame.type === "model_stream" || frame.type === "handoff_stream"
-      || frame.type === "model_res" || frame.type === "tool_res"
-      || frame.type === "handoff_res" || frame.type === "handoff_status_res"
-      || frame.type === "handoff_input_required"
-      || frame.type === "handoff_input" || frame.type === "handoff_cancel"
-      || frame.type === "handoff_status"
-      || frame.type === "diagnostic_exec_res" || frame.type === "diagnostic_status_res"
-      || frame.type === "peer_approval_res"
-      || frame.type === "acp_stream" || frame.type === "acp_res"
-      || frame.type === "acp_close_res"
-      || frame.type === "acp_list_res" || frame.type === "acp_resume_res"
-      || frame.type === "acp_cancel_res"
-      || frame.type === "acp_set_mode_res" || frame.type === "acp_get_modes_res"
-      || frame.type === "terminal_open_res" || frame.type === "terminal_data"
-      || frame.type === "terminal_resize" || frame.type === "terminal_close"
-      || frame.type === "terminal_close_res";
-    if (frame.id && !skipDedup && this.router.isDuplicate(frame.id)) return;
+    // handoff_input/cancel/status reuse the original handoff_req id.
+    if (frame.id && !SKIP_DEDUP_TYPES.has(frame.type) && this.router.isDuplicate(frame.id)) return;
 
     // Handle peer approval responses locally (don't emit to cluster-service)
     if (frame.type === "peer_approval_res") {

package/src/router.ts

@@ -3,6 +3,7 @@ import type { Connection } from "./connection.ts";
 
 const DEFAULT_TTL = 3;
 const MAX_SEEN_FRAMES = 10_000;
+const MAX_FAILED_REQUESTS = 5_000;
 const ROTATE_INTERVAL = 60_000; // rotate dedup maps every 60s
 
 export interface RouteEntry {
@@ -305,6 +306,21 @@ export class Router {
    *  TTL defaults to 15 minutes — long enough for handoff timeouts. */
   markFailed(requestId: string, ttlMs = 900_000) {
     this.failedRequests.set(requestId, Date.now() + ttlMs);
+    // Evict entries when map grows too large: first expired, then FIFO
+    if (this.failedRequests.size > MAX_FAILED_REQUESTS) {
+      const now = Date.now();
+      // Pass 1: remove expired entries
+      for (const [id, expiresAt] of this.failedRequests) {
+        if (now > expiresAt) this.failedRequests.delete(id);
+      }
+      // Pass 2: if still over limit, remove oldest (insertion-order) entries
+      if (this.failedRequests.size > MAX_FAILED_REQUESTS) {
+        for (const [id] of this.failedRequests) {
+          if (this.failedRequests.size <= MAX_FAILED_REQUESTS) break;
+          this.failedRequests.delete(id);
+        }
+      }
+    }
   }
 
   isFailed(requestId: string): boolean {