clawmatrix 0.2.9 → 0.2.11

package/package.json

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

@@ -153,6 +153,8 @@ export class AcpProxy {
   private warmPool = new Map<string, AcpSession[]>();
   // Track pending prewarm timers so they can be cancelled on dispose
   private prewarmTimers = new Set<ReturnType<typeof setTimeout>>();
+  // Track pending retry timers for sendResponse so they can be cancelled on destroy
+  private retryTimers = 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>();
@@ -1246,6 +1248,7 @@ export class AcpProxy {
       },
       availableModes,
       currentModeId: response.modes?.currentModeId,
+
     };
 
     return session;
@@ -1524,6 +1527,7 @@ export class AcpProxy {
       setStreamCallback: (cb) => { streamCallback = cb; },
       availableModes,
       currentModeId: response.modes?.currentModeId,
+
     };
 
     this.monitorProcess(session);
@@ -1777,9 +1781,21 @@ export class AcpProxy {
     cwd: string,
     from: string,
   ): Promise<AcpSession> {
-    return this.spawnAndConnect(agent, cwd, from, "createSessionWithResume", (conn) =>
-      conn.unstable_resumeSession({ sessionId: acpSessionId, cwd }),
-    );
+    return this.spawnAndConnect(agent, cwd, from, "createSessionWithResume", async (conn, effectiveCwd) => {
+      // Try session/load first (supported by Codex, Claude Code, and most ACP agents).
+      // It restores conversation history and replays it via notifications.
+      try {
+        const loadResp = await conn.loadSession({ sessionId: acpSessionId, cwd: effectiveCwd, mcpServers: [] });
+        debug("acp", `loadSession succeeded for ${agent} (acpSessionId=${acpSessionId.slice(0, 8)}...)`);
+        return { sessionId: acpSessionId, modes: loadResp.modes };
+      } catch (loadErr) {
+        debug("acp", `loadSession failed for ${agent}: ${errorMessage(loadErr)}, trying session/resume`);
+      }
+
+      // Fallback to session/resume (unstable, supported by Claude Code).
+      // Resumes without replaying history — faster but less widely supported.
+      return conn.unstable_resumeSession({ sessionId: acpSessionId, cwd: effectiveCwd });
+    });
   }
 
   /** Read all session stores from disk (OpenClaw + Claude Code). */
@@ -2020,11 +2036,14 @@ export class AcpProxy {
       const retryDelays = [2_000, 5_000, 10_000];
       let attempt = 0;
       const retry = () => {
-        if (attempt >= retryDelays.length) {
-          console.error(`[clawmatrix:acp] Failed to deliver acp_res to ${to} after ${retryDelays.length} retries`);
+        if (this.disposed || attempt >= retryDelays.length) {
+          if (!this.disposed) {
+            console.error(`[clawmatrix:acp] Failed to deliver acp_res to ${to} after ${retryDelays.length} retries`);
+          }
           return;
         }
-        setTimeout(() => {
+        const timer = setTimeout(() => {
+          this.retryTimers.delete(timer);
           frame.timestamp = Date.now();
           if (this.peerManager.sendTo(to, frame)) {
             debug("acp", `acp_res to ${to} delivered on retry ${attempt + 1}`);
@@ -2033,6 +2052,7 @@ export class AcpProxy {
             retry();
           }
         }, retryDelays[attempt]);
+        this.retryTimers.add(timer);
       };
       retry();
     }
@@ -2073,6 +2093,10 @@ export class AcpProxy {
 
     this.disposed = true;
 
+    // Cancel pending retry timers
+    for (const timer of this.retryTimers) clearTimeout(timer);
+    this.retryTimers.clear();
+
     // Cancel pending prewarm timers
     for (const timer of this.prewarmTimers) clearTimeout(timer);
     this.prewarmTimers.clear();

package/src/cluster-service.ts

@@ -14,6 +14,7 @@ import { ModelProxy } from "./model-proxy.ts";
 import { ToolProxy, type GatewayInfo } from "./tool-proxy.ts";
 import { AcpProxy, readAllSessionStoresFromDisk } from "./acp-proxy.ts";
 import { TerminalManager } from "./terminal.ts";
+import { FileTransferManager } from "./file-transfer.ts";
 import { WebHandler } from "./web.ts";
 import { KnowledgeSync } from "./knowledge-sync.ts";
 import { HealthTracker } from "./health-tracker.ts";
@@ -30,6 +31,8 @@ import type {
   HandoffInput,
   KnowledgeSyncFrame,
   HealthSyncFrame,
+  AvailabilityRequest,
+  AvailabilityResponse,
   ModelRequest,
   ModelResponse,
   ModelStreamChunk,
@@ -63,6 +66,11 @@ import type {
   TerminalResize,
   TerminalCloseRequest,
   TerminalCloseResponse,
+  FileTransferInit,
+  FileTransferAck,
+  FileTransferChunk,
+  FileTransferChunkAck,
+  FileTransferComplete,
 } from "./types.ts";
 
 function resolveGatewayInfo(openclawConfig: OpenClawConfig): GatewayInfo {
@@ -86,6 +94,7 @@ export class ClusterRuntime {
   readonly toolProxy: ToolProxy;
   readonly acpProxy: AcpProxy | null;
   readonly terminalManager: TerminalManager;
+  readonly fileTransferManager: FileTransferManager | null;
   knowledgeSync: KnowledgeSync | null = null;
   healthTracker: HealthTracker;
   webHandler: WebHandler | null = null;
@@ -107,6 +116,9 @@ export class ClusterRuntime {
     const acpEnabled = config.acp?.enabled || (openclawConfig as Record<string, any>).acp?.enabled;
     this.acpProxy = acpEnabled ? new AcpProxy(config, this.peerManager, openclawConfig as Record<string, unknown>, gatewayInfo) : null;
     this.terminalManager = new TerminalManager(config, this.peerManager);
+    this.fileTransferManager = config.fileTransfer?.enabled
+      ? new FileTransferManager(config, this.peerManager)
+      : null;
     this.healthTracker = new HealthTracker({
       nodeId: config.nodeId,
       peerManager: this.peerManager,
@@ -238,6 +250,7 @@ export class ClusterRuntime {
     this.acpProxy?.destroy();
     this.terminalManager.destroy();
     this.modelProxy.stop();
+    this.fileTransferManager?.destroy();
     this.toolProxy.destroy();
     await this.peerManager.stop();
     this.logger.info(`[clawmatrix] Node "${this.config.nodeId}" stopped`);
@@ -338,6 +351,20 @@ export class ClusterRuntime {
       case "health_sync":
         this.healthTracker.handleSyncMessage(frame as HealthSyncFrame);
         break;
+      case "availability_req": {
+        const af = frame as AvailabilityRequest;
+        const range = af.payload.range ?? "24h";
+        const data = this.healthTracker.getAvailability(range);
+        this.peerManager.sendTo(af.from, {
+          type: "availability_res",
+          id: af.id,
+          from: this.config.nodeId,
+          to: af.from,
+          timestamp: Date.now(),
+          payload: { success: true, data },
+        } as AvailabilityResponse);
+        break;
+      }
       case "acp_req":
         if (this.acpProxy) {
           this.acpProxy.handleRequest(frame as AcpTaskRequest).catch((err) => {
@@ -494,6 +521,23 @@ export class ClusterRuntime {
           frame as TerminalOpenRequest | TerminalOpenResponse | TerminalData | TerminalResize | TerminalCloseRequest | TerminalCloseResponse,
         );
         break;
+      case "file_transfer_init":
+        this.fileTransferManager?.handleInit(frame as FileTransferInit).catch((err) => {
+          this.logger.error(`[clawmatrix] File transfer init error: ${err}`);
+        });
+        break;
+      case "file_transfer_ack":
+        this.fileTransferManager?.handleAck(frame as FileTransferAck);
+        break;
+      case "file_transfer_chunk":
+        this.fileTransferManager?.handleChunk(frame as FileTransferChunk);
+        break;
+      case "file_transfer_chunk_ack":
+        this.fileTransferManager?.handleChunkAck(frame as FileTransferChunkAck);
+        break;
+      case "file_transfer_complete":
+        this.fileTransferManager?.handleComplete(frame as FileTransferComplete);
+        break;
     }
   }
 

package/src/config.ts

@@ -134,6 +134,14 @@ const TerminalConfigSchema = z.object({
   allowFrom: z.array(z.string()).default([]),
 }).optional();
 
+const FileTransferConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  chunkSize: z.number().default(262_144),       // 256KB
+  maxFileSize: z.number().default(104_857_600),  // 100MB
+  timeout: z.number().default(300_000),          // 5min per-chunk
+  allowedPaths: z.array(z.string()).default([]), // empty = no restriction
+}).optional();
+
 const AcpConfigSchema = z.object({
   enabled: z.boolean().default(false),
   /** ACP agents available on this node. Advertised to peers via capabilities. */
@@ -169,6 +177,7 @@ const RawClawMatrixConfigSchema = z.object({
   knowledge: KnowledgeConfigSchema,
   terminal: TerminalConfigSchema,
   acp: AcpConfigSchema,
+  fileTransfer: FileTransferConfigSchema,
   peerApproval: z.union([
     z.boolean(),           // true = required mode, false = disabled
     PeerApprovalConfigSchema,

package/src/file-transfer.ts

@@ -0,0 +1,671 @@
+import { createHash } from "node:crypto";
+import { readFile, writeFile, stat, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { debug } from "./debug.ts";
+import type { PeerManager } from "./peer-manager.ts";
+import type { ClawMatrixConfig } from "./config.ts";
+import type {
+  FileTransferInit,
+  FileTransferAck,
+  FileTransferChunk,
+  FileTransferChunkAck,
+  FileTransferComplete,
+} from "./types.ts";
+
+interface FileTransferConfig {
+  enabled: boolean;
+  chunkSize: number;
+  maxFileSize: number;
+  timeout: number;
+  allowedPaths: string[];
+}
+
+interface PendingTransfer {
+  sessionId: string;
+  direction: "push" | "pull";
+  filePath: string;
+  targetPath: string;
+  remoteNode: string;
+  resolve: (result: TransferResult) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+  // Push state
+  fileData?: Buffer;
+  chunkSize?: number;
+  totalChunks?: number;
+  sentChunks?: number;
+  // Pull state
+  chunks?: Map<number, Buffer>;
+  expectedSize?: number;
+  expectedChunks?: number;
+  expectedChecksum?: string;
+  receivedChunks?: number;
+}
+
+interface ReceivingTransfer {
+  sessionId: string;
+  direction: "push" | "pull";
+  filePath: string;
+  targetPath: string;
+  fromNode: string;
+  fileSize: number;
+  totalChunks: number;
+  chunkSize: number;
+  checksum: string;
+  chunks: Map<number, Buffer>;
+  receivedChunks: number;
+  timer: ReturnType<typeof setTimeout>;
+  /** Cached file data for pull-mode serving to avoid re-reading per chunk */
+  cachedData?: Buffer;
+}
+
+export interface TransferResult {
+  success: boolean;
+  bytesTransferred: number;
+  error?: string;
+}
+
+export class FileTransferManager {
+  private config: FileTransferConfig;
+  private nodeId: string;
+  private peerManager: PeerManager;
+  private pending = new Map<string, PendingTransfer>();
+  private receiving = new Map<string, ReceivingTransfer>();
+
+  constructor(config: ClawMatrixConfig, peerManager: PeerManager) {
+    this.nodeId = config.nodeId;
+    this.peerManager = peerManager;
+    const ft = config.fileTransfer;
+    this.config = {
+      enabled: ft?.enabled ?? false,
+      chunkSize: ft?.chunkSize ?? 262_144,
+      maxFileSize: ft?.maxFileSize ?? 104_857_600,
+      timeout: ft?.timeout ?? 300_000,
+      allowedPaths: ft?.allowedPaths ?? [],
+    };
+  }
+
+  // ── Public API ──────────────────────────────────────────────────
+
+  async pushFile(remoteNode: string, localPath: string, remotePath: string): Promise<TransferResult> {
+    this.ensureEnabled();
+    const resolvedPath = path.resolve(localPath);
+    this.validatePath(resolvedPath);
+
+    const fileData = await readFile(resolvedPath);
+    if (fileData.length > this.config.maxFileSize) {
+      throw new Error(`File too large: ${fileData.length} bytes (max ${this.config.maxFileSize})`);
+    }
+
+    const checksum = createHash("sha256").update(fileData).digest("hex");
+    const totalChunks = Math.ceil(fileData.length / this.config.chunkSize) || 1;
+    const sessionId = crypto.randomUUID();
+
+    return new Promise<TransferResult>((resolve, reject) => {
+      const timer = this.createTimer(sessionId, "pending");
+
+      this.pending.set(sessionId, {
+        sessionId,
+        direction: "push",
+        filePath: resolvedPath,
+        targetPath: remotePath,
+        remoteNode,
+        resolve,
+        reject,
+        timer,
+        fileData,
+        chunkSize: this.config.chunkSize,
+        totalChunks,
+        sentChunks: 0,
+      });
+
+      this.peerManager.sendTo(remoteNode, {
+        type: "file_transfer_init",
+        id: sessionId,
+        from: this.nodeId,
+        to: remoteNode,
+        timestamp: Date.now(),
+        payload: {
+          sessionId,
+          direction: "push",
+          filePath: resolvedPath,
+          targetPath: remotePath,
+          fileSize: fileData.length,
+          totalChunks,
+          chunkSize: this.config.chunkSize,
+          checksum,
+        },
+      } as FileTransferInit);
+    });
+  }
+
+  async pullFile(remoteNode: string, remotePath: string, localPath: string): Promise<TransferResult> {
+    this.ensureEnabled();
+    const resolvedPath = path.resolve(localPath);
+    this.validatePath(resolvedPath);
+
+    const sessionId = crypto.randomUUID();
+
+    return new Promise<TransferResult>((resolve, reject) => {
+      const timer = this.createTimer(sessionId, "pending");
+
+      this.pending.set(sessionId, {
+        sessionId,
+        direction: "pull",
+        filePath: remotePath,
+        targetPath: resolvedPath,
+        remoteNode,
+        resolve,
+        reject,
+        timer,
+        chunks: new Map(),
+        receivedChunks: 0,
+      });
+
+      this.peerManager.sendTo(remoteNode, {
+        type: "file_transfer_init",
+        id: sessionId,
+        from: this.nodeId,
+        to: remoteNode,
+        timestamp: Date.now(),
+        payload: {
+          sessionId,
+          direction: "pull",
+          filePath: remotePath,
+          targetPath: resolvedPath,
+          fileSize: 0,
+          totalChunks: 0,
+          chunkSize: this.config.chunkSize,
+          checksum: "",
+        },
+      } as FileTransferInit);
+    });
+  }
+
+  // ── Frame handlers (called by cluster-service dispatch) ─────────
+
+  async handleInit(frame: FileTransferInit): Promise<void> {
+    const { sessionId, direction, filePath, targetPath, fileSize, totalChunks, chunkSize, checksum } = frame.payload;
+
+    // Validate enabled
+    if (!this.config.enabled) {
+      this.sendAck(frame.from, sessionId, frame.id, false, "File transfer not enabled on this node");
+      return;
+    }
+
+    if (direction === "push") {
+      // Remote wants to push a file to us
+      const resolvedTarget = path.resolve(targetPath);
+      if (!this.isPathAllowed(resolvedTarget)) {
+        this.sendAck(frame.from, sessionId, frame.id, false, "Target path not allowed");
+        return;
+      }
+      if (fileSize > this.config.maxFileSize) {
+        this.sendAck(frame.from, sessionId, frame.id, false, `File too large: ${fileSize} bytes (max ${this.config.maxFileSize})`);
+        return;
+      }
+
+      // Accept and prepare to receive chunks
+      const timer = this.createTimer(sessionId, "receiving");
+      this.receiving.set(sessionId, {
+        sessionId,
+        direction: "push",
+        filePath,
+        targetPath: resolvedTarget,
+        fromNode: frame.from,
+        fileSize,
+        totalChunks,
+        chunkSize,
+        checksum,
+        chunks: new Map(),
+        receivedChunks: 0,
+        timer,
+      });
+
+      this.sendAck(frame.from, sessionId, frame.id, true);
+    } else {
+      // Remote wants to pull a file from us
+      const resolvedSource = path.resolve(filePath);
+      if (!this.isPathAllowed(resolvedSource)) {
+        this.sendAck(frame.from, sessionId, frame.id, false, "Source path not allowed");
+        return;
+      }
+
+      let fileData: Buffer;
+      try {
+        fileData = await readFile(resolvedSource);
+      } catch (err) {
+        this.sendAck(frame.from, sessionId, frame.id, false, `Cannot read file: ${err instanceof Error ? err.message : String(err)}`);
+        return;
+      }
+
+      if (fileData.length > this.config.maxFileSize) {
+        this.sendAck(frame.from, sessionId, frame.id, false, `File too large: ${fileData.length} bytes`);
+        return;
+      }
+
+      const fileChecksum = createHash("sha256").update(fileData).digest("hex");
+      const fileTotalChunks = Math.ceil(fileData.length / this.config.chunkSize) || 1;
+
+      // Send ack with file metadata
+      this.peerManager.sendTo(frame.from, {
+        type: "file_transfer_ack",
+        id: frame.id,
+        from: this.nodeId,
+        to: frame.from,
+        timestamp: Date.now(),
+        payload: {
+          sessionId,
+          accepted: true,
+          fileSize: fileData.length,
+          totalChunks: fileTotalChunks,
+          checksum: fileChecksum,
+        },
+      } as FileTransferAck);
+
+      // Store as a "receiving" entry for tracking (we are the sender in pull mode)
+      const timer = this.createTimer(sessionId, "receiving");
+      this.receiving.set(sessionId, {
+        sessionId,
+        direction: "pull",
+        filePath: resolvedSource,
+        targetPath,
+        fromNode: frame.from,
+        fileSize: fileData.length,
+        totalChunks: fileTotalChunks,
+        chunkSize: this.config.chunkSize,
+        checksum: fileChecksum,
+        chunks: new Map(),
+        receivedChunks: 0,
+        timer,
+        cachedData: fileData,
+      });
+
+      // Start sending chunks (stop-and-wait: send first, wait for ack)
+      this.sendChunkFromReceiving(sessionId, 0, fileData);
+    }
+  }
+
+  handleAck(frame: FileTransferAck): void {
+    const { sessionId, accepted, error, fileSize, totalChunks, checksum } = frame.payload;
+    const transfer = this.pending.get(sessionId);
+    if (!transfer) return;
+
+    this.resetTimer(sessionId, "pending");
+
+    if (!accepted) {
+      this.completePending(sessionId, { success: false, bytesTransferred: 0, error: error || "Transfer rejected" });
+      return;
+    }
+
+    if (transfer.direction === "push") {
+      // Start sending chunks
+      this.sendNextChunk(sessionId);
+    } else {
+      // Pull mode: store expected metadata
+      transfer.expectedSize = fileSize;
+      transfer.expectedChunks = totalChunks;
+      transfer.expectedChecksum = checksum;
+      // Wait for chunks from remote
+    }
+  }
+
+  handleChunk(frame: FileTransferChunk): void {
+    const { sessionId, chunkIndex, data } = frame.payload;
+
+    // Check if this is a pull we initiated (we're receiving)
+    const pending = this.pending.get(sessionId);
+    if (pending && pending.direction === "pull") {
+      this.resetTimer(sessionId, "pending");
+      const buf = Buffer.from(data, "base64");
+      pending.chunks!.set(chunkIndex, buf);
+      pending.receivedChunks = (pending.receivedChunks ?? 0) + 1;
+
+      // Send chunk ack
+      this.peerManager.sendTo(pending.remoteNode, {
+        type: "file_transfer_chunk_ack",
+        id: frame.id,
+        from: this.nodeId,
+        to: pending.remoteNode,
+        timestamp: Date.now(),
+        payload: { sessionId, chunkIndex, success: true },
+      } as FileTransferChunkAck);
+
+      // Check if all chunks received
+      if (pending.receivedChunks === pending.expectedChunks) {
+        this.finalizePull(sessionId).catch((err) => {
+          this.completePending(sessionId, {
+            success: false,
+            bytesTransferred: 0,
+            error: err instanceof Error ? err.message : String(err),
+          });
+        });
+      }
+      return;
+    }
+
+    // Otherwise, this is a push from remote (we're receiving)
+    const receiving = this.receiving.get(sessionId);
+    if (!receiving || receiving.direction !== "push") return;
+
+    this.resetTimer(sessionId, "receiving");
+    const buf = Buffer.from(data, "base64");
+    receiving.chunks.set(chunkIndex, buf);
+    receiving.receivedChunks++;
+
+    // Send chunk ack
+    this.peerManager.sendTo(receiving.fromNode, {
+      type: "file_transfer_chunk_ack",
+      id: frame.id,
+      from: this.nodeId,
+      to: receiving.fromNode,
+      timestamp: Date.now(),
+      payload: { sessionId, chunkIndex, success: true },
+    } as FileTransferChunkAck);
+
+    // Check if all chunks received
+    if (receiving.receivedChunks === receiving.totalChunks) {
+      this.finalizePushReceive(sessionId).catch((err) => {
+        debug("file-transfer", `finalizePushReceive error: ${err}`);
+      });
+    }
+  }
+
+  handleChunkAck(frame: FileTransferChunkAck): void {
+    const { sessionId, chunkIndex, success, error } = frame.payload;
+
+    // Push mode: we sent a chunk, got ack, send next
+    const pending = this.pending.get(sessionId);
+    if (pending && pending.direction === "push") {
+      this.resetTimer(sessionId, "pending");
+      if (!success) {
+        this.completePending(sessionId, {
+          success: false,
+          bytesTransferred: chunkIndex * (pending.chunkSize ?? this.config.chunkSize),
+          error: error || `Chunk ${chunkIndex} rejected`,
+        });
+        return;
+      }
+      pending.sentChunks = chunkIndex + 1;
+      if (pending.sentChunks! < pending.totalChunks!) {
+        this.sendNextChunk(sessionId);
+      }
+      // If all sent, wait for file_transfer_complete from receiver
+      return;
+    }
+
+    // Pull mode (we are serving): got chunk ack, send next
+    const receiving = this.receiving.get(sessionId);
+    if (receiving && receiving.direction === "pull") {
+      this.resetTimer(sessionId, "receiving");
+      if (!success) {
+        this.cleanupReceiving(sessionId);
+        return;
+      }
+      const nextIndex = chunkIndex + 1;
+      if (nextIndex < receiving.totalChunks) {
+        if (receiving.cachedData) {
+          this.sendChunkFromReceiving(sessionId, nextIndex, receiving.cachedData);
+        } else {
+          // Fallback: read file if cached data is missing
+          readFile(receiving.filePath).then((data) => {
+            receiving.cachedData = data;
+            this.sendChunkFromReceiving(sessionId, nextIndex, data);
+          }).catch(() => {
+            this.cleanupReceiving(sessionId);
+          });
+        }
+      }
+      // If all chunks sent, wait for file_transfer_complete from puller
+    }
+  }
+
+  handleComplete(frame: FileTransferComplete): void {
+    const { sessionId, success, error, bytesTransferred } = frame.payload;
+
+    // Pending transfer completed
+    const pending = this.pending.get(sessionId);
+    if (pending) {
+      this.completePending(sessionId, {
+        success,
+        bytesTransferred: bytesTransferred ?? 0,
+        error: error || undefined,
+      });
+      return;
+    }
+
+    // Receiving transfer completed (pull mode serving — remote confirms)
+    const receiving = this.receiving.get(sessionId);
+    if (receiving) {
+      this.cleanupReceiving(sessionId);
+    }
+  }
+
+  destroy(): void {
+    for (const [id, transfer] of this.pending) {
+      clearTimeout(transfer.timer);
+      transfer.reject(new Error("FileTransferManager destroyed"));
+    }
+    this.pending.clear();
+
+    for (const [id, transfer] of this.receiving) {
+      clearTimeout(transfer.timer);
+    }
+    this.receiving.clear();
+  }
+
+  // ── Internal helpers ────────────────────────────────────────────
+
+  private ensureEnabled(): void {
+    if (!this.config.enabled) {
+      throw new Error("File transfer is not enabled");
+    }
+  }
+
+  private validatePath(resolvedPath: string): void {
+    if (!this.isPathAllowed(resolvedPath)) {
+      throw new Error(`Path not allowed: ${resolvedPath}`);
+    }
+  }
+
+  private isPathAllowed(resolvedPath: string): boolean {
+    // TODO(security): allowedPaths 为空时默认允许所有路径，当前仅用于受信任网络。
+    // 开放到非受信环境前需改为默认拒绝，或要求显式配置 allowedPaths。
+    if (this.config.allowedPaths.length === 0) return true;
+    const normalized = path.resolve(resolvedPath);
+    return this.config.allowedPaths.some((allowed) => {
+      const resolvedAllowed = path.resolve(allowed);
+      return normalized === resolvedAllowed || normalized.startsWith(resolvedAllowed + path.sep);
+    });
+  }
+
+  private sendAck(to: string, sessionId: string, frameId: string, accepted: boolean, error?: string): void {
+    this.peerManager.sendTo(to, {
+      type: "file_transfer_ack",
+      id: frameId,
+      from: this.nodeId,
+      to,
+      timestamp: Date.now(),
+      payload: { sessionId, accepted, error },
+    } as FileTransferAck);
+  }
+
+  private sendNextChunk(sessionId: string): void {
+    const transfer = this.pending.get(sessionId);
+    if (!transfer || !transfer.fileData) return;
+
+    const chunkIndex = transfer.sentChunks!;
+    const start = chunkIndex * transfer.chunkSize!;
+    const end = Math.min(start + transfer.chunkSize!, transfer.fileData.length);
+    const chunk = transfer.fileData.subarray(start, end);
+
+    this.peerManager.sendTo(transfer.remoteNode, {
+      type: "file_transfer_chunk",
+      id: transfer.sessionId,
+      from: this.nodeId,
+      to: transfer.remoteNode,
+      timestamp: Date.now(),
+      payload: {
+        sessionId,
+        chunkIndex,
+        data: chunk.toString("base64"),
+      },
+    } as FileTransferChunk);
+  }
+
+  private sendChunkFromReceiving(sessionId: string, chunkIndex: number, fileData: Buffer): void {
+    const receiving = this.receiving.get(sessionId);
+    if (!receiving) return;
+
+    const start = chunkIndex * receiving.chunkSize;
+    const end = Math.min(start + receiving.chunkSize, fileData.length);
+    const chunk = fileData.subarray(start, end);
+
+    this.peerManager.sendTo(receiving.fromNode, {
+      type: "file_transfer_chunk",
+      id: sessionId,
+      from: this.nodeId,
+      to: receiving.fromNode,
+      timestamp: Date.now(),
+      payload: {
+        sessionId,
+        chunkIndex,
+        data: chunk.toString("base64"),
+      },
+    } as FileTransferChunk);
+  }
+
+  private async finalizePushReceive(sessionId: string): Promise<void> {
+    const receiving = this.receiving.get(sessionId);
+    if (!receiving) return;
+
+    // Reassemble file
+    const buffers: Buffer[] = [];
+    for (let i = 0; i < receiving.totalChunks; i++) {
+      const chunk = receiving.chunks.get(i);
+      if (!chunk) {
+        this.sendComplete(receiving.fromNode, sessionId, false, "Missing chunk " + i);
+        this.cleanupReceiving(sessionId);
+        return;
+      }
+      buffers.push(chunk);
+    }
+
+    const assembled = Buffer.concat(buffers);
+
+    // Verify checksum
+    const actualChecksum = createHash("sha256").update(assembled).digest("hex");
+    if (actualChecksum !== receiving.checksum) {
+      this.sendComplete(receiving.fromNode, sessionId, false, `Checksum mismatch: expected ${receiving.checksum}, got ${actualChecksum}`);
+      this.cleanupReceiving(sessionId);
+      return;
+    }
+
+    // Write file
+    try {
+      await mkdir(path.dirname(receiving.targetPath), { recursive: true });
+      await writeFile(receiving.targetPath, assembled);
+    } catch (err) {
+      this.sendComplete(receiving.fromNode, sessionId, false, `Write error: ${err instanceof Error ? err.message : String(err)}`);
+      this.cleanupReceiving(sessionId);
+      return;
+    }
+
+    this.sendComplete(receiving.fromNode, sessionId, true, undefined, assembled.length);
+    this.cleanupReceiving(sessionId);
+  }
+
+  private async finalizePull(sessionId: string): Promise<void> {
+    const transfer = this.pending.get(sessionId);
+    if (!transfer) return;
+
+    // Reassemble file
+    const buffers: Buffer[] = [];
+    for (let i = 0; i < transfer.expectedChunks!; i++) {
+      const chunk = transfer.chunks!.get(i);
+      if (!chunk) {
+        throw new Error(`Missing chunk ${i}`);
+      }
+      buffers.push(chunk);
+    }
+
+    const assembled = Buffer.concat(buffers);
+
+    // Verify checksum
+    const actualChecksum = createHash("sha256").update(assembled).digest("hex");
+    if (actualChecksum !== transfer.expectedChecksum) {
+      // Notify remote of failure
+      this.sendComplete(transfer.remoteNode, sessionId, false, `Checksum mismatch: expected ${transfer.expectedChecksum}, got ${actualChecksum}`);
+      this.completePending(sessionId, {
+        success: false,
+        bytesTransferred: 0,
+        error: `Checksum mismatch`,
+      });
+      return;
+    }
+
+    // Write file
+    await mkdir(path.dirname(transfer.targetPath), { recursive: true });
+    await writeFile(transfer.targetPath, assembled);
+
+    // Notify remote of success
+    this.sendComplete(transfer.remoteNode, sessionId, true, undefined, assembled.length);
+    this.completePending(sessionId, { success: true, bytesTransferred: assembled.length });
+  }
+
+  private sendComplete(to: string, sessionId: string, success: boolean, error?: string, bytesTransferred?: number): void {
+    this.peerManager.sendTo(to, {
+      type: "file_transfer_complete",
+      id: sessionId,
+      from: this.nodeId,
+      to,
+      timestamp: Date.now(),
+      payload: { sessionId, success, error, bytesTransferred },
+    } as FileTransferComplete);
+  }
+
+  private completePending(sessionId: string, result: TransferResult): void {
+    const transfer = this.pending.get(sessionId);
+    if (!transfer) return;
+    clearTimeout(transfer.timer);
+    this.pending.delete(sessionId);
+    transfer.resolve(result);
+  }
+
+  private cleanupReceiving(sessionId: string): void {
+    const receiving = this.receiving.get(sessionId);
+    if (!receiving) return;
+    clearTimeout(receiving.timer);
+    this.receiving.delete(sessionId);
+  }
+
+  private createTimer(sessionId: string, mapType: "pending" | "receiving"): ReturnType<typeof setTimeout> {
+    return setTimeout(() => {
+      if (mapType === "pending") {
+        const transfer = this.pending.get(sessionId);
+        if (transfer) {
+          this.pending.delete(sessionId);
+          transfer.reject(new Error("File transfer timeout"));
+        }
+      } else {
+        this.receiving.delete(sessionId);
+      }
+    }, this.config.timeout);
+  }
+
+  private resetTimer(sessionId: string, mapType: "pending" | "receiving"): void {
+    if (mapType === "pending") {
+      const transfer = this.pending.get(sessionId);
+      if (transfer) {
+        clearTimeout(transfer.timer);
+        transfer.timer = this.createTimer(sessionId, "pending");
+      }
+    } else {
+      const receiving = this.receiving.get(sessionId);
+      if (receiving) {
+        clearTimeout(receiving.timer);
+        receiving.timer = this.createTimer(sessionId, "receiving");
+      }
+    }
+  }
+}

package/src/health-tracker.ts

@@ -132,12 +132,17 @@ export class HealthTracker {
   // ── Event recording ─────────────────────────────────────────
 
   recordEvent(event: HealthEvent) {
+    // Strip undefined values — Automerge rejects them
+    const clean: Record<string, unknown> = {};
+    for (const [k, v] of Object.entries(event)) {
+      if (v !== undefined) clean[k] = v;
+    }
     this.doc = Automerge.change(this.doc, (d) => {
       if (!d.nodes[this.nodeId]) {
         d.nodes[this.nodeId] = { events: [], lastUpdated: 0 };
       }
       const entry = d.nodes[this.nodeId]!;
-      entry.events.push({ ...event });
+      entry.events.push(clean as HealthEvent);
       entry.lastUpdated = Date.now();
     });
     this.scheduleSave();

package/src/index.ts

@@ -16,6 +16,7 @@ import { createClusterDiagnosticTool } from "./tools/cluster-diagnostic.ts";
 import { createClusterAcpTool } from "./tools/cluster-acp.ts";
 import { createClusterTerminalTool } from "./tools/cluster-terminal.ts";
 import { createClusterToolInvokeTool } from "./tools/cluster-tool.ts";
+import { createClusterTransferTool } from "./tools/cluster-transfer.ts";
 import { registerClusterCli } from "./cli.ts";
 import { spawnProcess } from "./compat.ts";
 
@@ -302,6 +303,7 @@ const plugin = {
     api.registerTool(createClusterAcpTool(), { optional: true });
     api.registerTool(createClusterTerminalTool(), { optional: true });
     api.registerTool(createClusterToolInvokeTool(), { optional: true });
+    api.registerTool(createClusterTransferTool(), { optional: true });
 
     // Wire up peer approval with OpenClaw channel API
     if (config.peerApproval.enabled) {
@@ -330,20 +332,23 @@ const plugin = {
 
             const proc = spawnProcess(
               ["openclaw", "gateway", "call", "send", "--json", "--params", JSON.stringify(sendParams)],
-              { stdout: "pipe", stderr: "pipe" },
+              { stdout: "ignore", stderr: "pipe" },
             );
-            const code = await proc.exited;
-            if (code !== 0) {
-              const stderrChunks: Uint8Array[] = [];
+            // Collect stderr concurrently with waiting for exit to avoid pipe deadlock
+            const stderrPromise = (async () => {
+              const chunks: Uint8Array[] = [];
               if (proc.stderr) {
                 const reader = proc.stderr.getReader();
                 while (true) {
                   const { done, value } = await reader.read();
                   if (done) break;
-                  stderrChunks.push(value);
+                  chunks.push(value);
                 }
               }
-              const errMsg = Buffer.concat(stderrChunks).toString("utf-8").trim();
+              return Buffer.concat(chunks).toString("utf-8").trim();
+            })();
+            const [code, errMsg] = await Promise.all([proc.exited, stderrPromise]);
+            if (code !== 0) {
               throw new Error(`gateway send failed (exit ${code}): ${errMsg}`);
             }
           });

package/src/knowledge-sync.ts

@@ -128,6 +128,8 @@ export class KnowledgeSync {
   // ── FS / Watcher ───────────────────────────────────────────────
   private watcher: FSWatcher | null = null;
   private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private localChangesRunning = false;
+  private localChangesQueued = false;
   /** Paths recently written by exportFileToFs — suppress watcher re-trigger. Stores {content, timestamp}. */
   private writtenByExport = new Map<string, { content: string; ts: number }>();
   /** Deferred git commit timer — batches multiple remote syncs into one commit. */
@@ -474,6 +476,27 @@ export class KnowledgeSync {
   }
 
   private async handleLocalChanges() {
+    // Mutex: if already running, mark queued and return — the running
+    // invocation will re-run when it finishes to pick up new changes.
+    if (this.localChangesRunning) {
+      this.localChangesQueued = true;
+      return;
+    }
+    this.localChangesRunning = true;
+    try {
+      await this.handleLocalChangesInner();
+    } finally {
+      this.localChangesRunning = false;
+      if (this.localChangesQueued) {
+        this.localChangesQueued = false;
+        this.handleLocalChanges().catch((err) => {
+          debug(TAG, `queued local change handling error: ${err}`);
+        });
+      }
+    }
+  }
+
+  private async handleLocalChangesInner() {
     // Only process files in pendingChanges (incremental)
     const changesToProcess = new Set(this.pendingChanges);
     this.pendingChanges.clear();
@@ -802,7 +825,13 @@ export class KnowledgeSync {
     if (this.isIgnored(relPath)) return;
 
     const content = doc.content ?? "";
-    const absPath = path.join(this.opts.workspacePath, relPath);
+    const absPath = path.resolve(this.opts.workspacePath, relPath);
+
+    // Prevent path traversal (e.g. relPath = "../../etc/passwd")
+    if (!absPath.startsWith(this.opts.workspacePath + path.sep) && absPath !== this.opts.workspacePath) {
+      debug(TAG, `blocked path traversal attempt: ${relPath}`);
+      return;
+    }
 
     let currentContent: string | null = null;
     try {

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. */

package/src/sentinel-manager.ts

@@ -8,7 +8,7 @@
 
 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 { homedir, tmpdir } from "node:os";
 import type { ClawMatrixConfig } from "./config.ts";
 
@@ -42,6 +42,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 +86,7 @@ export class SentinelManager {
     }, 1000);
   }
 
-  stop() {
+  async stop() {
     // IPC is disconnected shortly after start, so use PID file for shutdown
     if (existsSync(this.pidFile)) {
       try {
@@ -92,13 +95,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/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/tools/cluster-diagnostic.ts

@@ -88,6 +88,8 @@ export function createClusterDiagnosticTool(): AnyAgentTool {
           };
         }
 
+        // TODO(security): exec 允许任何已认证 peer 在远程 sentinel 执行任意命令，无 allowlist 或 capability check。
+        // 当前仅用于受信任网络。开放前需添加命令白名单或 per-peer 授权。
         if (action === "exec") {
           if (!command) {
             return {

package/src/tools/cluster-transfer.ts

@@ -0,0 +1,91 @@
+import type { AnyAgentTool } from "openclaw/plugin-sdk";
+import { getClusterRuntime } from "../cluster-service.ts";
+
+export function createClusterTransferTool(): AnyAgentTool {
+  return {
+    name: "cluster_transfer",
+    label: "Cluster File Transfer",
+    description:
+      "Transfer a file between the local node and a remote cluster node. " +
+      "Supports large files (up to 100MB) with chunked transfer and SHA-256 integrity check. " +
+      "Specify source_node to pull from remote, or target_node to push to remote.",
+    parameters: {
+      type: "object",
+      properties: {
+        source_node: {
+          type: "string",
+          description: "Source nodeId (omit for local). Exactly one of source_node or target_node must be provided.",
+        },
+        source_path: {
+          type: "string",
+          description: "File path on the source node",
+        },
+        target_node: {
+          type: "string",
+          description: "Target nodeId (omit for local). Exactly one of source_node or target_node must be provided.",
+        },
+        target_path: {
+          type: "string",
+          description: "File path on the target node",
+        },
+      },
+      required: ["source_path", "target_path"],
+    },
+    async execute(_toolCallId, params) {
+      const { source_node, source_path, target_node, target_path } = params as {
+        source_node?: string;
+        source_path: string;
+        target_node?: string;
+        target_path: string;
+      };
+
+      // Validate: exactly one of source_node or target_node must be provided
+      if (source_node && target_node) {
+        return {
+          content: [{ type: "text" as const, text: "Error: Provide either source_node or target_node, not both." }],
+          details: { error: true },
+        };
+      }
+      if (!source_node && !target_node) {
+        return {
+          content: [{ type: "text" as const, text: "Error: Provide either source_node (to pull) or target_node (to push)." }],
+          details: { error: true },
+        };
+      }
+
+      try {
+        const runtime = getClusterRuntime();
+        const ftm = runtime.fileTransferManager;
+        if (!ftm) {
+          return {
+            content: [{ type: "text" as const, text: "Error: File transfer is not enabled on this node." }],
+            details: { error: true },
+          };
+        }
+
+        let result;
+        if (source_node) {
+          // Pull: remote → local
+          result = await ftm.pullFile(source_node, source_path, target_path);
+        } else {
+          // Push: local → remote
+          result = await ftm.pushFile(target_node!, source_path, target_path);
+        }
+
+        const text = result.success
+          ? `Transfer complete: ${result.bytesTransferred} bytes transferred.`
+          : `Transfer failed: ${result.error}`;
+
+        return {
+          content: [{ type: "text" as const, text }],
+          details: result,
+        };
+      } catch (err) {
+        return {
+          content: [{ type: "text" as const, text: `Transfer error: ${err instanceof Error ? err.message : String(err)}` }],
+          details: { error: true },
+        };
+      }
+    },
+  };
+}

package/src/types.ts

@@ -317,6 +317,68 @@ export interface ToolBatchResponse extends ClusterFrame {
   };
 }
 
+// ── File transfer ─────────────────────────────────────────────────
+export interface FileTransferInit extends ClusterFrame {
+  type: "file_transfer_init";
+  id: string;
+  payload: {
+    sessionId: string;
+    direction: "push" | "pull";
+    filePath: string;
+    targetPath: string;
+    fileSize: number;
+    totalChunks: number;
+    chunkSize: number;
+    checksum: string; // SHA-256 hex
+  };
+}
+
+export interface FileTransferAck extends ClusterFrame {
+  type: "file_transfer_ack";
+  id: string;
+  payload: {
+    sessionId: string;
+    accepted: boolean;
+    error?: string;
+    // Pull mode: responder includes file metadata
+    fileSize?: number;
+    totalChunks?: number;
+    checksum?: string;
+  };
+}
+
+export interface FileTransferChunk extends ClusterFrame {
+  type: "file_transfer_chunk";
+  id: string;
+  payload: {
+    sessionId: string;
+    chunkIndex: number;
+    data: string; // base64-encoded
+  };
+}
+
+export interface FileTransferChunkAck extends ClusterFrame {
+  type: "file_transfer_chunk_ack";
+  id: string;
+  payload: {
+    sessionId: string;
+    chunkIndex: number;
+    success: boolean;
+    error?: string;
+  };
+}
+
+export interface FileTransferComplete extends ClusterFrame {
+  type: "file_transfer_complete";
+  id: string;
+  payload: {
+    sessionId: string;
+    success: boolean;
+    error?: string;
+    bytesTransferred?: number;
+  };
+}
+
 // ── Device info ───────────────────────────────────────────────────
 export interface DeviceInfo {
   os: string; // e.g. "Darwin 24.6.0", "Linux 6.1.0"
@@ -419,6 +481,24 @@ export interface HealthSyncFrame extends ClusterFrame {
   };
 }
 
+export interface AvailabilityRequest extends ClusterFrame {
+  type: "availability_req";
+  id: string;
+  payload: {
+    range: "24h" | "7d" | "90d";
+  };
+}
+
+export interface AvailabilityResponse extends ClusterFrame {
+  type: "availability_res";
+  id: string;
+  payload: {
+    success: boolean;
+    data?: unknown;
+    error?: string;
+  };
+}
+
 // ── Diagnostic (sentinel) ────────────────────────────────────────
 export interface DiagnosticExec extends ClusterFrame {
   type: "diagnostic_exec";
@@ -840,4 +920,11 @@ export type AnyClusterFrame =
   | TerminalResize
   | TerminalCloseRequest
   | TerminalCloseResponse
-  | HealthSyncFrame;
+  | HealthSyncFrame
+  | AvailabilityRequest
+  | AvailabilityResponse
+  | FileTransferInit
+  | FileTransferAck
+  | FileTransferChunk
+  | FileTransferChunkAck
+  | FileTransferComplete;