@perkos/perkos-a2a 0.12.30 → 0.12.32

package/dist/index.js

@@ -1297,8 +1297,8 @@ var require_node = __commonJS({
           break;
         case "PIPE":
         case "TCP":
-          var net = __require("net");
-          stream2 = new net.Socket({
+          var net2 = __require("net");
+          stream2 = new net2.Socket({
             fd: fd2,
             readable: false,
             writable: true
@@ -4944,10 +4944,10 @@ var require_raw_body = __commonJS({
       if (done) {
         return readStream(stream, encoding, length, limit, wrap(done));
       }
-      return new Promise(function executor(resolve3, reject) {
+      return new Promise(function executor(resolve4, reject) {
         readStream(stream, encoding, length, limit, function onRead(err, buf) {
           if (err) return reject(err);
-          resolve3(buf);
+          resolve4(buf);
         });
       });
     }
@@ -18429,11 +18429,11 @@ var require_view = __commonJS({
     var debug = require_src()("express:view");
     var path = __require("path");
     var fs = __require("fs");
-    var dirname2 = path.dirname;
+    var dirname3 = path.dirname;
     var basename = path.basename;
     var extname = path.extname;
-    var join3 = path.join;
-    var resolve3 = path.resolve;
+    var join4 = path.join;
+    var resolve4 = path.resolve;
     module.exports = View;
     function View(name, options) {
       var opts = options || {};
@@ -18467,8 +18467,8 @@ var require_view = __commonJS({
       debug('lookup "%s"', name);
       for (var i = 0; i < roots.length && !path2; i++) {
         var root = roots[i];
-        var loc = resolve3(root, name);
-        var dir = dirname2(loc);
+        var loc = resolve4(root, name);
+        var dir = dirname3(loc);
         var file = basename(loc);
         path2 = this.resolve(dir, file);
       }
@@ -18478,14 +18478,14 @@ var require_view = __commonJS({
       debug('render "%s"', this.path);
       this.engine(this.path, options, callback);
     };
-    View.prototype.resolve = function resolve4(dir, file) {
+    View.prototype.resolve = function resolve5(dir, file) {
       var ext = this.ext;
-      var path2 = join3(dir, file);
+      var path2 = join4(dir, file);
       var stat = tryStat(path2);
       if (stat && stat.isFile()) {
         return path2;
       }
-      path2 = join3(dir, basename(file, ext), "index" + ext);
+      path2 = join4(dir, basename(file, ext), "index" + ext);
       stat = tryStat(path2);
       if (stat && stat.isFile()) {
         return path2;
@@ -19118,9 +19118,9 @@ var require_send = __commonJS({
     var Stream = __require("stream");
     var util = __require("util");
     var extname = path.extname;
-    var join3 = path.join;
+    var join4 = path.join;
     var normalize = path.normalize;
-    var resolve3 = path.resolve;
+    var resolve4 = path.resolve;
     var sep = path.sep;
     var BYTES_RANGE_REGEXP = /^ *bytes=/;
     var MAX_MAXAGE = 60 * 60 * 24 * 365 * 1e3;
@@ -19157,7 +19157,7 @@ var require_send = __commonJS({
       this._maxage = opts.maxAge || opts.maxage;
       this._maxage = typeof this._maxage === "string" ? ms(this._maxage) : Number(this._maxage);
       this._maxage = !isNaN(this._maxage) ? Math.min(Math.max(0, this._maxage), MAX_MAXAGE) : 0;
-      this._root = opts.root ? resolve3(opts.root) : null;
+      this._root = opts.root ? resolve4(opts.root) : null;
       if (!this._root && opts.from) {
         this.from(opts.from);
       }
@@ -19181,7 +19181,7 @@ var require_send = __commonJS({
       return this;
     }, "send.index: pass index as option");
     SendStream.prototype.root = function root(path2) {
-      this._root = resolve3(String(path2));
+      this._root = resolve4(String(path2));
       debug("root %s", this._root);
       return this;
     };
@@ -19337,7 +19337,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = path2.split(sep);
-        path2 = normalize(join3(root, path2));
+        path2 = normalize(join4(root, path2));
       } else {
         if (UP_PATH_REGEXP.test(path2)) {
           debug('malicious path "%s"', path2);
@@ -19345,7 +19345,7 @@ var require_send = __commonJS({
           return res;
         }
         parts = normalize(path2).split(sep);
-        path2 = resolve3(path2);
+        path2 = resolve4(path2);
       }
       if (containsDotFile(parts)) {
         var access = this._dotfiles;
@@ -19472,7 +19472,7 @@ var require_send = __commonJS({
           if (err) return self.onStatError(err);
           return self.error(404);
         }
-        var p = join3(path2, self._index[i]);
+        var p = join4(path2, self._index[i]);
         debug('stat "%s"', p);
         fs.stat(p, function(err2, stat) {
           if (err2) return next(err2);
@@ -20625,7 +20625,7 @@ var require_application = __commonJS({
     var deprecate = require_depd()("express");
     var flatten = require_array_flatten();
     var merge = require_utils_merge();
-    var resolve3 = __require("path").resolve;
+    var resolve4 = __require("path").resolve;
     var setPrototypeOf = require_setprototypeof();
     var hasOwnProperty = Object.prototype.hasOwnProperty;
     var slice = Array.prototype.slice;
@@ -20664,7 +20664,7 @@ var require_application = __commonJS({
       this.mountpath = "/";
       this.locals.settings = this.settings;
       this.set("view", View);
-      this.set("views", resolve3("views"));
+      this.set("views", resolve4("views"));
       this.set("jsonp callback name", "callback");
       if (env === "production") {
         this.enable("view cache");
@@ -21909,7 +21909,7 @@ var require_response = __commonJS({
     var send = require_send();
     var extname = path.extname;
     var mime = send.mime;
-    var resolve3 = path.resolve;
+    var resolve4 = path.resolve;
     var vary = require_vary();
     var res = Object.create(http.ServerResponse.prototype);
     module.exports = res;
@@ -22168,7 +22168,7 @@ var require_response = __commonJS({
       }
       opts = Object.create(opts);
       opts.headers = headers;
-      var fullPath = !opts.root ? resolve3(path2) : path2;
+      var fullPath = !opts.root ? resolve4(path2) : path2;
       return this.sendFile(fullPath, opts, done);
     };
     res.contentType = res.type = function contentType(type) {
@@ -22434,7 +22434,7 @@ var require_serve_static = __commonJS({
     var encodeUrl = require_encodeurl();
     var escapeHtml = require_escape_html();
     var parseUrl = require_parseurl();
-    var resolve3 = __require("path").resolve;
+    var resolve4 = __require("path").resolve;
     var send = require_send();
     var url = __require("url");
     module.exports = serveStatic;
@@ -22454,7 +22454,7 @@ var require_serve_static = __commonJS({
         throw new TypeError("option setHeaders must be function");
       }
       opts.maxage = opts.maxage || opts.maxAge || 0;
-      opts.root = resolve3(root);
+      opts.root = resolve4(root);
       var onDirectory = redirect ? createRedirectDirectoryListener() : createNotFoundDirectoryListener();
       return function serveStatic2(req, res, next) {
         if (req.method !== "GET" && req.method !== "HEAD") {
@@ -24815,9 +24815,9 @@ var require_websocket = __commonJS({
     var EventEmitter = __require("events");
     var https = __require("https");
     var http = __require("http");
-    var net = __require("net");
+    var net2 = __require("net");
     var tls = __require("tls");
-    var { randomBytes, createHash: createHash2 } = __require("crypto");
+    var { randomBytes, createHash: createHash3 } = __require("crypto");
     var { Duplex, Readable } = __require("stream");
     var { URL: URL2 } = __require("url");
     var PerMessageDeflate2 = require_permessage_deflate();
@@ -25477,7 +25477,7 @@ var require_websocket = __commonJS({
           abortHandshake(websocket, socket, "Invalid Upgrade header");
           return;
         }
-        const digest = createHash2("sha1").update(key + GUID).digest("base64");
+        const digest = createHash3("sha1").update(key + GUID).digest("base64");
         if (res.headers["sec-websocket-accept"] !== digest) {
           abortHandshake(websocket, socket, "Invalid Sec-WebSocket-Accept header");
           return;
@@ -25549,12 +25549,12 @@ var require_websocket = __commonJS({
     }
     function netConnect(options) {
       options.path = options.socketPath;
-      return net.connect(options);
+      return net2.connect(options);
     }
     function tlsConnect(options) {
       options.path = void 0;
       if (!options.servername && options.servername !== "") {
-        options.servername = net.isIP(options.host) ? "" : options.host;
+        options.servername = net2.isIP(options.host) ? "" : options.host;
       }
       return tls.connect(options);
     }
@@ -25844,7 +25844,7 @@ var require_websocket_server = __commonJS({
     var EventEmitter = __require("events");
     var http = __require("http");
     var { Duplex } = __require("stream");
-    var { createHash: createHash2 } = __require("crypto");
+    var { createHash: createHash3 } = __require("crypto");
     var extension2 = require_extension();
     var PerMessageDeflate2 = require_permessage_deflate();
     var subprotocol2 = require_subprotocol();
@@ -26145,7 +26145,7 @@ var require_websocket_server = __commonJS({
           );
         }
         if (this._state > RUNNING) return abortHandshake(socket, 503);
-        const digest = createHash2("sha1").update(key + GUID).digest("base64");
+        const digest = createHash3("sha1").update(key + GUID).digest("base64");
         const headers = [
           "HTTP/1.1 101 Switching Protocols",
           "Upgrade: websocket",
@@ -26263,6 +26263,7 @@ var RelayClient = class {
   heartbeatTimer = null;
   connected = false;
   stopped = false;
+  generation = 0;
   pendingCallbacks = /* @__PURE__ */ new Map();
   /** Responses that arrived with nobody waiting, claimable by a retry. */
   orphanResponses = /* @__PURE__ */ new Map();
@@ -26274,17 +26275,46 @@ var RelayClient = class {
     return this.connected;
   }
   start() {
+    if (!this.stopped && this.ws) return;
     this.stopped = false;
-    this.connect();
+    const generation = ++this.generation;
+    this.connect(generation);
   }
   stop() {
-    this.stopped = true;
-    this.clearTimers();
-    if (this.ws) {
-      this.ws.close(1e3, "Client shutting down");
-      this.ws = null;
+    const socket = this.beginStop();
+    try {
+      socket?.close(1e3, "Client shutting down");
+    } catch {
     }
-    this.connected = false;
+  }
+  /** Stop reconnect activity and wait a bounded time for the socket to close. */
+  async stopAndWait(timeoutMs = 5e3) {
+    const socket = this.beginStop();
+    if (!socket || socket.readyState === wrapper_default.CLOSED) return { closeTimedOut: false };
+    return new Promise((resolve4) => {
+      let settled = false;
+      const finish = (closeTimedOut) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve4({ closeTimedOut });
+      };
+      const timer = setTimeout(() => {
+        finish(true);
+        try {
+          socket.terminate();
+        } catch {
+        }
+      }, timeoutMs);
+      timer.unref?.();
+      socket.once("close", () => finish(false));
+      socket.once("error", () => finish(false));
+      try {
+        socket.close(1e3, "Client shutting down");
+      } catch {
+        finish(false);
+      }
+    });
   }
   /**
    * Send a task to another agent via the relay.
@@ -26333,8 +26363,8 @@ var RelayClient = class {
     };
     this.send(response);
   }
-  connect() {
-    if (this.stopped) return;
+  connect(generation) {
+    if (!this.isCurrent(generation)) return;
     const url = this.options.relay.url;
     this.logger.info(`[perkos-a2a] Connecting to relay: ${url}`);
     try {
@@ -26342,17 +26372,23 @@ var RelayClient = class {
     } catch (err) {
       const msg = err instanceof Error ? err.message : String(err);
       this.logger.error(`[perkos-a2a] Failed to create WebSocket: ${msg}`);
-      this.scheduleReconnect();
+      this.scheduleReconnect(generation);
       return;
     }
-    this.ws.on("open", () => {
+    const socket = this.ws;
+    socket.on("open", () => {
+      if (!this.isCurrent(generation, socket)) {
+        socket.close(1e3, "Stale relay generation");
+        return;
+      }
       this.connected = true;
       this.reconnectMs = MIN_RECONNECT_MS;
       this.logger.info("[perkos-a2a] Connected to relay hub");
       this.register();
       this.startHeartbeat();
     });
-    this.ws.on("message", (data) => {
+    socket.on("message", (data) => {
+      if (!this.isCurrent(generation, socket)) return;
       let msg;
       try {
         msg = JSON.parse(data.toString());
@@ -26362,15 +26398,17 @@ var RelayClient = class {
       }
       this.handleMessage(msg);
     });
-    this.ws.on("close", (code, reason) => {
+    socket.on("close", (code, reason) => {
+      if (!this.isCurrent(generation, socket)) return;
       this.connected = false;
       this.clearTimers();
       if (!this.stopped) {
         this.logger.info(`[perkos-a2a] Relay connection closed (${code}: ${reason || "no reason"}). Reconnecting...`);
-        this.scheduleReconnect();
+        this.scheduleReconnect(generation);
       }
     });
-    this.ws.on("error", (err) => {
+    socket.on("error", (err) => {
+      if (!this.isCurrent(generation, socket)) return;
       this.logger.error(`[perkos-a2a] Relay WebSocket error: ${err.message}`);
     });
   }
@@ -26450,7 +26488,7 @@ var RelayClient = class {
     }
   }
   async sendAndWait(msg, expectedType, timeoutMs) {
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve4, reject) => {
       const timer = setTimeout(() => {
         this.pendingCallbacks.delete(msg.id);
         reject(new Error(`Relay request timed out after ${timeoutMs}ms`));
@@ -26462,8 +26500,12 @@ var RelayClient = class {
           if (response.type === "error") {
             reject(new Error(`Relay error: ${response.payload.message}`));
           } else {
-            resolve3(response);
+            resolve4(response);
           }
+        },
+        cancel: (error) => {
+          clearTimeout(timer);
+          reject(error);
         }
       });
       this.send(msg);
@@ -26481,10 +26523,10 @@ var RelayClient = class {
       this.send(msg);
     }, HEARTBEAT_INTERVAL_MS);
   }
-  scheduleReconnect() {
-    if (this.stopped) return;
+  scheduleReconnect(generation) {
+    if (!this.isCurrent(generation)) return;
     this.reconnectTimer = setTimeout(() => {
-      this.connect();
+      if (this.isCurrent(generation)) this.connect(generation);
     }, this.reconnectMs);
     this.reconnectMs = Math.min(this.reconnectMs * 2, MAX_RECONNECT_MS);
   }
@@ -26498,6 +26540,23 @@ var RelayClient = class {
       this.reconnectTimer = null;
     }
   }
+  isCurrent(generation, socket) {
+    return !this.stopped && generation === this.generation && (!socket || socket === this.ws);
+  }
+  beginStop() {
+    if (this.stopped && !this.ws) return null;
+    this.stopped = true;
+    this.generation += 1;
+    this.clearTimers();
+    const error = new Error("CLIENT_STOPPED");
+    for (const pending of this.pendingCallbacks.values()) pending.cancel(error);
+    this.pendingCallbacks.clear();
+    this.orphanResponses.clear();
+    const socket = this.ws;
+    this.ws = null;
+    this.connected = false;
+    return socket;
+  }
 };
 
 // src/relay.ts
@@ -26533,17 +26592,33 @@ var RelayHub = class {
     });
     this.heartbeatTimer = setInterval(() => this.checkHeartbeats(), this.config.heartbeatIntervalMs);
   }
-  stop() {
+  async stop(timeoutMs = 5e3) {
     if (this.heartbeatTimer) {
       clearInterval(this.heartbeatTimer);
       this.heartbeatTimer = null;
     }
     if (this.wss) {
+      const wss = this.wss;
+      this.wss = null;
       for (const agent of this.agents.values()) {
         agent.ws.close(1001, "Relay shutting down");
       }
-      this.wss.close();
-      this.wss = null;
+      await new Promise((resolve4) => {
+        let settled = false;
+        const done = () => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          resolve4();
+        };
+        const timer = setTimeout(() => {
+          for (const client of wss.clients) client.terminate();
+          done();
+        }, timeoutMs);
+        timer.unref?.();
+        wss.close(() => done());
+      });
+      this.agents.clear();
       this.logger.info("[perkos-a2a] Relay hub stopped");
     }
   }
@@ -26933,11 +27008,18 @@ var A2AServer = class {
   logger;
   clientOnly = false;
   relayClient = null;
+  externalRelayTransport = false;
   relayHub = null;
   messageInjector = null;
   taskResultHandler = null;
   taskFailureHandler = null;
   lastRuntimeDelivery = null;
+  httpServer = null;
+  lifecycleState = "new";
+  generation = 0;
+  startPromise = null;
+  stopPromise = null;
+  operations = /* @__PURE__ */ new Set();
   constructor(config, logger) {
     this.config = config;
     this.logger = logger || { info: console.log, error: console.error };
@@ -26966,6 +27048,14 @@ var A2AServer = class {
   setTaskFailureHandler(handler) {
     this.taskFailureHandler = handler;
   }
+  /** Use a process-external owner for relay transport (OpenClaw supervisor). */
+  setRelayTransport(transport) {
+    if (this.lifecycleState !== "new" && this.lifecycleState !== "stopped") {
+      throw new Error("relay transport must be configured before start");
+    }
+    this.relayClient = transport;
+    this.externalRelayTransport = true;
+  }
   getTasks() {
     return this.tasks.values();
   }
@@ -26981,6 +27071,9 @@ var A2AServer = class {
   isRelayConnected() {
     return this.relayClient?.isConnected() || false;
   }
+  getAgentCard() {
+    return structuredClone(this.agentCard);
+  }
   authMiddleware() {
     return (req, res, next) => {
       if (!this.config.auth?.requireApiKey) {
@@ -27068,6 +27161,9 @@ var A2AServer = class {
     });
   }
   async handleSendMessage(params, rpcId) {
+    if (this.lifecycleState === "stopping" || this.lifecycleState === "stopped") {
+      return this.error(rpcId, 503, "SERVER_RELOADING");
+    }
     const message = params.message;
     const taskId = randomUUID4();
     const contextId = message?.contextId || randomUUID4();
@@ -27088,10 +27184,11 @@ var A2AServer = class {
     this.logger.info(
       `[perkos-a2a] Task ${taskId} received from ${task.metadata?.fromAgent}`
     );
-    void this.processTask(task);
+    const generation = this.generation;
+    this.trackOperation(this.processTask(task, generation));
     return this.success(rpcId, task);
   }
-  async processTask(task) {
+  async processTask(task, generation) {
     task.status = { state: "working", timestamp: (/* @__PURE__ */ new Date()).toISOString() };
     this.tasks.set(task.id, structuredClone(task));
     const textParts = task.messages.flatMap((m) => m.parts || []).filter((p) => p.kind === "text").map((p) => p.text).join("\n");
@@ -27135,9 +27232,11 @@ var A2AServer = class {
           timestamp: (/* @__PURE__ */ new Date()).toISOString()
         };
       }
+      if (!this.isGenerationActive(generation)) return;
       this.tasks.set(task.id, structuredClone(task));
       this.logger.info(`[perkos-a2a] Task ${task.id} completed`);
     } catch (err) {
+      if (!this.isGenerationActive(generation)) return;
       const msg = err instanceof Error ? err.message : String(err);
       if (this.taskFailureHandler) {
         await this.taskFailureHandler(task, msg);
@@ -27237,7 +27336,7 @@ var A2AServer = class {
   async waitForRemoteTaskTerminal(targetUrl, headers, taskId, timeoutMs = 45e3, pollMs = 1e3) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-      await new Promise((resolve3) => setTimeout(resolve3, pollMs));
+      await new Promise((resolve4) => setTimeout(resolve4, pollMs));
       const response = await fetch(`${targetUrl}/a2a/jsonrpc`, {
         method: "POST",
         headers,
@@ -27261,7 +27360,7 @@ var A2AServer = class {
       if (task && isTerminalTaskState(task.status?.state)) {
         return this.success(randomUUID4(), structuredClone(task));
       }
-      await new Promise((resolve3) => setTimeout(resolve3, pollMs));
+      await new Promise((resolve4) => setTimeout(resolve4, pollMs));
     }
     return null;
   }
@@ -27324,10 +27423,17 @@ var A2AServer = class {
   }
   /** Handle an inbound task received via the relay */
   handleRelayTask(msg) {
+    if (this.lifecycleState !== "running") {
+      this.relayClient?.sendTaskResponse(
+        msg,
+        this.error(String(msg.payload?.id ?? msg.id), 503, "SERVER_RELOADING")
+      );
+      return;
+    }
     const payload = msg.payload;
     const params = payload.params || payload;
     const rpcId = payload.id || msg.id;
-    this.handleSendMessage(params, rpcId).then(async (response) => {
+    const operation = this.handleSendMessage(params, rpcId).then(async (response) => {
       const task = response.result;
       const acceptQueued = task?.messages?.[0]?.metadata?.acceptQueued === true;
       if (task?.id && !isTerminalTaskState(task.status?.state)) {
@@ -27358,10 +27464,32 @@ var A2AServer = class {
       this.logger.error(`[perkos-a2a] Failed to process relay task: ${errMsg2}`);
       this.relayClient?.sendTaskResponse(msg, this.error(rpcId, -32603, errMsg2));
     });
+    this.trackOperation(operation);
   }
-  startRelayClient() {
+  /** Process a relay task delivered by the OpenClaw supervisor over IPC. */
+  async handleTransportTask(msg) {
+    if (this.lifecycleState !== "running") {
+      return this.error(String(msg.payload?.id ?? msg.id), 503, "SERVER_RELOADING");
+    }
+    const payload = msg.payload;
+    const params = payload.params || payload;
+    const rpcId = String(payload.id || msg.id);
+    const response = await this.handleSendMessage(params, rpcId);
+    const task = response.result;
+    if (task?.id && !isTerminalTaskState(task.status?.state)) {
+      const terminal = await this.waitForLocalTaskTerminal(task.id);
+      if (terminal) return terminal;
+    }
+    return response;
+  }
+  async startRelayClient() {
     const relay = this.config.relay;
     if (!relay?.enabled || !relay?.url) return;
+    if (this.externalRelayTransport && this.relayClient) {
+      await this.relayClient.start();
+      this.logger.info(`[perkos-a2a] Relay transport delegated to supervisor for ${relay.url}`);
+      return;
+    }
     this.relayClient = new RelayClient({
       agentName: this.config.agentName,
       relay,
@@ -27389,15 +27517,32 @@ var A2AServer = class {
     this.relayHub.start();
   }
   async start() {
+    if (this.lifecycleState === "running") return;
+    if (this.lifecycleState === "starting" && this.startPromise) return this.startPromise;
+    if (this.lifecycleState === "stopping" && this.stopPromise) await this.stopPromise;
+    const generation = ++this.generation;
+    this.lifecycleState = "starting";
+    const startPromise = this.startGeneration(generation);
+    this.startPromise = startPromise;
+    try {
+      await startPromise;
+      if (this.isGenerationActive(generation, "starting")) this.lifecycleState = "running";
+    } finally {
+      if (this.startPromise === startPromise) this.startPromise = null;
+    }
+  }
+  async startGeneration(generation) {
     const mode = this.config.mode || "auto";
     if (mode === "relay") {
+      if (!this.isGenerationActive(generation, "starting")) return;
       this.clientOnly = true;
       this.startRelayHub();
       return;
     }
     if (mode === "client-only") {
+      if (!this.isGenerationActive(generation, "starting")) return;
       this.clientOnly = true;
-      this.startRelayClient();
+      await this.startRelayClient();
       if (!this.config.relay?.enabled) {
         this.logger.info(
           "[perkos-a2a] Running in client-only mode. Configure relay for NAT traversal or set up Tailscale/tunnel."
@@ -27406,19 +27551,21 @@ var A2AServer = class {
       return;
     }
     if (mode === "full") {
-      this.tryListen(this.config.port);
-      this.startRelayClient();
+      await this.tryListen(this.config.port, 1, generation);
+      if (!this.isGenerationActive(generation, "starting")) return;
+      await this.startRelayClient();
       return;
     }
     try {
-      const net = await detectNetworking();
-      if (net.isBehindNat && !net.hasTailscale) {
+      const net2 = await detectNetworking();
+      if (!this.isGenerationActive(generation, "starting")) return;
+      if (net2.isBehindNat && !net2.hasTailscale) {
         if (this.config.relay?.enabled) {
           this.logger.info(
             "[perkos-a2a] Behind NAT, using relay for bidirectional communication"
           );
           this.clientOnly = true;
-          this.startRelayClient();
+          await this.startRelayClient();
         } else {
           this.logger.info(
             "[perkos-a2a] Running in client-only mode (behind NAT). Configure relay or Tailscale for bidirectional A2A."
@@ -27427,44 +27574,136 @@ var A2AServer = class {
         }
         return;
       }
-      if (net.isBehindNat && net.hasTailscale && net.tailscaleIp) {
+      if (net2.isBehindNat && net2.hasTailscale && net2.tailscaleIp) {
         this.logger.info(
-          `[perkos-a2a] Behind NAT but Tailscale detected (${net.tailscaleIp}). Starting server.`
+          `[perkos-a2a] Behind NAT but Tailscale detected (${net2.tailscaleIp}). Starting server.`
         );
       }
     } catch {
     }
-    this.tryListen(this.config.port);
-    this.startRelayClient();
+    await this.tryListen(this.config.port, 1, generation);
+    if (!this.isGenerationActive(generation, "starting")) return;
+    await this.startRelayClient();
+  }
+  stop(options = {}) {
+    if (this.lifecycleState === "stopping" && this.stopPromise) return this.stopPromise;
+    if (this.lifecycleState === "stopped" || this.lifecycleState === "new") {
+      this.lifecycleState = "stopped";
+      this.generation += 1;
+      return Promise.resolve();
+    }
+    this.lifecycleState = "stopping";
+    this.generation += 1;
+    const priorStart = this.startPromise;
+    let stopPromise;
+    stopPromise = (async () => {
+      try {
+        const timeoutMs = options.timeoutMs ?? 5e3;
+        const drainMs = Math.min(options.drainMs ?? 3e3, timeoutMs);
+        await this.teardownResources(timeoutMs);
+        await priorStart?.catch(() => void 0);
+        await this.teardownResources(timeoutMs);
+        await this.drainOperations(drainMs);
+        for (const task of this.tasks.values()) {
+          if (!isTerminalTaskState(task.status.state)) {
+            task.status = {
+              state: "failed",
+              timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+              message: { role: "agent", parts: [{ kind: "text", text: "interrupted_by_reload" }] }
+            };
+          }
+        }
+        this.lifecycleState = "stopped";
+        this.logger.info(`[perkos-a2a] A2A server stopped${options.reason ? ` (${options.reason})` : ""}`);
+      } finally {
+        if (this.stopPromise === stopPromise) this.stopPromise = null;
+      }
+    })();
+    this.stopPromise = stopPromise;
+    return stopPromise;
   }
-  tryListen(port, attempt = 1) {
+  tryListen(port, attempt, generation) {
     const maxAttempts = 3;
-    try {
+    return new Promise((resolveStart) => {
+      if (!this.isGenerationActive(generation, "starting")) {
+        resolveStart();
+        return;
+      }
       const bindHost = this.config.bindHost || "0.0.0.0";
       const srv = this.app.listen(port, bindHost, () => {
+        if (!this.isGenerationActive(generation, "starting")) {
+          srv.close(() => resolveStart());
+          return;
+        }
+        this.httpServer = srv;
         this.logger.info(
           `[perkos-a2a] ${this.config.agentName} server on ${bindHost}:${port}`
         );
         this.agentCard.url = `${(this.config.publicUrl || `http://localhost:${port}`).replace(/\/+$/, "")}/a2a/jsonrpc`;
+        resolveStart();
       });
       srv.on("error", (err) => {
         if (err.code === "EADDRINUSE" && attempt < maxAttempts) {
           const nextPort = port + 1;
           this.logger.info(`[perkos-a2a] Port ${port} in use, trying ${nextPort}`);
-          this.tryListen(nextPort, attempt + 1);
+          void this.tryListen(nextPort, attempt + 1, generation).then(resolveStart);
         } else if (err.code === "EADDRINUSE") {
           this.logger.info(
             `[perkos-a2a] Ports ${this.config.port}-${port} all in use. Falling back to client-only mode.`
           );
           this.clientOnly = true;
+          resolveStart();
         } else {
           this.logger.error(`[perkos-a2a] Server error: ${err.message}`);
+          resolveStart();
         }
       });
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      this.logger.error(`[perkos-a2a] Failed to start server: ${msg}`);
-    }
+    });
+  }
+  isGenerationActive(generation, expectedState) {
+    return generation === this.generation && (expectedState ? this.lifecycleState === expectedState : this.lifecycleState !== "stopping" && this.lifecycleState !== "stopped");
+  }
+  trackOperation(operation) {
+    this.operations.add(operation);
+    void operation.finally(() => this.operations.delete(operation)).catch(() => void 0);
+  }
+  async drainOperations(timeoutMs) {
+    if (this.operations.size === 0 || timeoutMs <= 0) return;
+    await Promise.race([
+      Promise.allSettled([...this.operations]),
+      new Promise((resolveDrain) => {
+        const timer = setTimeout(resolveDrain, timeoutMs);
+        timer.unref?.();
+      })
+    ]);
+  }
+  async teardownResources(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    const remaining = () => Math.max(1, deadline - Date.now());
+    const relayClient = this.relayClient;
+    if (!this.externalRelayTransport) this.relayClient = null;
+    await relayClient?.stopAndWait(remaining());
+    const relayHub = this.relayHub;
+    this.relayHub = null;
+    await relayHub?.stop(remaining());
+    const httpServer = this.httpServer;
+    this.httpServer = null;
+    if (!httpServer) return;
+    await new Promise((resolveClose) => {
+      let settled = false;
+      const done = () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolveClose();
+      };
+      const timer = setTimeout(() => {
+        httpServer.closeAllConnections?.();
+        done();
+      }, remaining());
+      timer.unref?.();
+      httpServer.close(() => done());
+    });
   }
   getExpressApp() {
     return this.app;
@@ -27472,10 +27711,10 @@ var A2AServer = class {
 };
 
 // src/index.ts
-import { randomUUID as randomUUID6 } from "crypto";
-import { readFileSync as readFileSync3 } from "node:fs";
-import { dirname, resolve as resolve2 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { randomUUID as randomUUID7 } from "crypto";
+import { readFileSync as readFileSync4 } from "node:fs";
+import { dirname as dirname2, resolve as resolve3 } from "node:path";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/agentic-actions.ts
 var FALLBACK_AGENT_ALIASES = [
@@ -27890,9 +28129,6 @@ ${replyResultText2}` : void 0,
   return true;
 }
 
-// src/chat-client.ts
-import { randomUUID as randomUUID5 } from "node:crypto";
-
 // src/chat-store.ts
 import { createHash } from "node:crypto";
 import { createReadStream } from "node:fs";
@@ -28020,7 +28256,7 @@ var ChatStore = class {
     let firstMessageAt = null;
     let lastMessageAt = null;
     let leftover = "";
-    return new Promise((resolve3, reject) => {
+    return new Promise((resolve4, reject) => {
       stream.on("data", (chunk) => {
         const text = typeof chunk === "string" ? chunk : chunk.toString("utf8");
         hash.update(text);
@@ -28060,7 +28296,7 @@ var ChatStore = class {
           hash.update(metaRaw);
         } catch {
         }
-        resolve3({
+        resolve4({
           transcriptHash: hash.digest("hex"),
           hashAlgo: "sha256",
           messageCount,
@@ -28095,7 +28331,398 @@ function isNotFound(err) {
   return !!err && typeof err === "object" && err.code === "ENOENT";
 }
 
+// src/openclaw-supervisor-client.ts
+import { randomUUID as randomUUID5 } from "node:crypto";
+import { spawn } from "node:child_process";
+import { homedir as homedir3 } from "node:os";
+import net from "node:net";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/supervisor-protocol.ts
+import { createHash as createHash2 } from "node:crypto";
+import { chmodSync, mkdirSync, readFileSync as readFileSync2, renameSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join as join2 } from "node:path";
+var SUPERVISOR_PROTOCOL_VERSION = 1;
+var SUPERVISOR_RENEW_MS = 5e3;
+function supervisorOwnerHash(lifecycleKey) {
+  return createHash2("sha256").update(lifecycleKey).digest("hex");
+}
+function supervisorDir(stateDir) {
+  return join2(stateDir, "perkos-a2a", "supervisors");
+}
+function supervisorSocketPath(stateDir, ownerHash) {
+  const preferred = join2(supervisorDir(stateDir), `${ownerHash.slice(0, 32)}.sock`);
+  if (Buffer.byteLength(preferred) <= 96) return preferred;
+  const uid = typeof process.getuid === "function" ? process.getuid() : "user";
+  return join2(tmpdir(), `perkos-a2a-${uid}`, `${ownerHash.slice(0, 32)}.sock`);
+}
+function currentBootId() {
+  try {
+    return readFileSync2("/proc/sys/kernel/random/boot_id", "utf8").trim();
+  } catch {
+    return `process-boot-${Math.floor(Date.now() - process.uptime() * 1e3)}`;
+  }
+}
+function processStartIdentity(pid = process.pid) {
+  try {
+    const stat = readFileSync2(`/proc/${pid}/stat`, "utf8");
+    const afterName = stat.slice(stat.lastIndexOf(")") + 2).trim().split(/\s+/u);
+    return `linux-start-ticks:${afterName[19] ?? "unknown"}`;
+  } catch {
+    if (pid === process.pid) return `epoch-ms:${Math.floor(Date.now() - process.uptime() * 1e3)}`;
+    return "unknown";
+  }
+}
+function encodeSupervisorMessage(message) {
+  return `${JSON.stringify(message)}
+`;
+}
+
+// src/openclaw-supervisor-client.ts
+var OpenClawSupervisorClient = class {
+  stateDir;
+  ownerHash;
+  socketPath;
+  config;
+  logger;
+  handlers;
+  lease;
+  socket = null;
+  startPromise = null;
+  stopPromise = null;
+  renewTimer = null;
+  pending = /* @__PURE__ */ new Map();
+  health = null;
+  stopped = true;
+  constructor(input) {
+    this.stateDir = resolve(input.stateDir ?? process.env.OPENCLAW_STATE_DIR ?? `${homedir3()}/.openclaw`);
+    this.ownerHash = input.ownerHash;
+    this.socketPath = supervisorSocketPath(this.stateDir, this.ownerHash);
+    this.config = input.config;
+    this.logger = input.logger;
+    this.handlers = input.handlers;
+    this.lease = {
+      ownerKey: input.ownerHash,
+      instanceId: input.instanceId,
+      generation: input.generation,
+      parentPid: process.pid,
+      parentStartTime: processStartIdentity(),
+      bootId: currentBootId(),
+      lastRenewedAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+  }
+  isConnected() {
+    return this.health?.relayConnected === true && this.health?.relayRegistered === true;
+  }
+  isChatConnected() {
+    return this.health?.chatConnected === true;
+  }
+  currentHealth() {
+    return this.health;
+  }
+  start() {
+    if (!this.stopped && this.socket && !this.socket.destroyed) return Promise.resolve();
+    if (this.startPromise) return this.startPromise;
+    this.stopped = false;
+    const starting = (async () => {
+      await this.connectOrSpawn();
+      await this.requestWithMessage({
+        protocolVersion: 1,
+        type: "claim",
+        requestId: randomUUID5(),
+        lease: this.freshLease(),
+        config: this.config
+      }, 15e3);
+      this.renewTimer = setInterval(() => this.renew(), SUPERVISOR_RENEW_MS);
+      this.renewTimer.unref?.();
+      this.logger.info(`[perkos-a2a] Supervisor owner ready generation=${this.lease.generation} instanceId=${this.lease.instanceId}`);
+    })().finally(() => {
+      if (this.startPromise === starting) this.startPromise = null;
+    });
+    this.startPromise = starting;
+    return starting;
+  }
+  stop() {
+    if (this.stopPromise) return this.stopPromise;
+    if (this.stopped && !this.socket) return Promise.resolve();
+    this.stopped = true;
+    if (this.renewTimer) clearInterval(this.renewTimer);
+    this.renewTimer = null;
+    const stopping = (async () => {
+      if (this.socket && !this.socket.destroyed) {
+        const requestId = randomUUID5();
+        try {
+          await this.requestWithMessage({
+            protocolVersion: 1,
+            type: "release",
+            requestId,
+            lease: this.freshLease()
+          }, 8e3);
+        } catch (error) {
+          const message = error instanceof Error ? error.message : String(error);
+          if (!message.includes("NOT_OWNER") && !message.includes("SUPERVISOR_DISCONNECTED")) throw error;
+        }
+      }
+      this.closeSocket(new Error("CLIENT_STOPPED"));
+      this.logger.info(`[perkos-a2a] A2A server stopped generation=${this.lease.generation} instanceId=${this.lease.instanceId}`);
+    })().finally(() => {
+      if (this.stopPromise === stopping) this.stopPromise = null;
+    });
+    this.stopPromise = stopping;
+    return stopping;
+  }
+  async stopAndWait() {
+    await this.stop();
+    return { closeTimedOut: false };
+  }
+  async sendTask(targetAgent, payload, taskId) {
+    return await this.request("sendTask", { target: targetAgent, payload, ...taskId ? { taskId } : {} }, 7e4);
+  }
+  async discover() {
+    return await this.request("discover", {}, 15e3);
+  }
+  sendTaskResponse(original, result) {
+    this.write({ protocolVersion: 1, type: "relayTaskResult", lease: this.freshLease(), eventId: randomUUID5(), original, result });
+  }
+  async sendChatReply(payload) {
+    return await this.request("chatReply", payload, 15e3);
+  }
+  async request(method, payload, timeoutMs) {
+    const requestId = randomUUID5();
+    return this.requestWithMessage({ protocolVersion: 1, type: "request", requestId, lease: this.freshLease(), method, payload }, timeoutMs);
+  }
+  async requestWithMessage(message, timeoutMs) {
+    return new Promise((resolveRequest, rejectRequest) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(message.requestId);
+        rejectRequest(new Error(`SUPERVISOR_REQUEST_TIMEOUT:${message.type}`));
+      }, timeoutMs);
+      timer.unref?.();
+      this.pending.set(message.requestId, { resolve: resolveRequest, reject: rejectRequest, timer });
+      try {
+        this.write(message);
+      } catch (error) {
+        clearTimeout(timer);
+        this.pending.delete(message.requestId);
+        rejectRequest(error instanceof Error ? error : new Error(String(error)));
+      }
+    });
+  }
+  freshLease() {
+    this.lease.lastRenewedAt = (/* @__PURE__ */ new Date()).toISOString();
+    return { ...this.lease };
+  }
+  renew() {
+    if (this.stopped || !this.socket || this.socket.destroyed) return;
+    this.write({ protocolVersion: 1, type: "renew", lease: this.freshLease() });
+  }
+  async connectOrSpawn() {
+    try {
+      await this.connectSocket(1e3);
+      return;
+    } catch {
+    }
+    const cliPath = fileURLToPath(new URL("./openclaw-supervisor-cli.js", import.meta.url));
+    const child = spawn(process.execPath, [cliPath, "--state-dir", this.stateDir, "--owner-key", this.ownerHash], {
+      detached: true,
+      stdio: "ignore",
+      env: { ...process.env }
+    });
+    child.unref();
+    const deadline = Date.now() + 1e4;
+    let lastError;
+    while (Date.now() < deadline) {
+      await new Promise((resolveWait) => setTimeout(resolveWait, 100));
+      try {
+        await this.connectSocket(1e3);
+        return;
+      } catch (error) {
+        lastError = error;
+      }
+    }
+    throw new Error(`OWNERSHIP_PRIMITIVE_UNAVAILABLE:${lastError instanceof Error ? lastError.message : String(lastError)}`);
+  }
+  connectSocket(timeoutMs) {
+    this.closeSocket(new Error("SUPERVISOR_RECONNECT"));
+    return new Promise((resolveConnect, rejectConnect) => {
+      const socket = net.createConnection(this.socketPath);
+      socket.setEncoding("utf8");
+      let buffered = "";
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) return;
+        settled = true;
+        socket.destroy();
+        rejectConnect(new Error("supervisor socket connect timeout"));
+      }, timeoutMs);
+      timer.unref?.();
+      socket.once("connect", () => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        this.socket = socket;
+        resolveConnect();
+      });
+      socket.once("error", (error) => {
+        if (!settled) {
+          settled = true;
+          clearTimeout(timer);
+          rejectConnect(error);
+        }
+      });
+      socket.on("data", (chunk) => {
+        buffered += chunk;
+        for (; ; ) {
+          const newline = buffered.indexOf("\n");
+          if (newline < 0) break;
+          const line = buffered.slice(0, newline);
+          buffered = buffered.slice(newline + 1);
+          if (line.trim()) void this.handleEvent(JSON.parse(line));
+        }
+      });
+      socket.on("close", () => {
+        if (this.socket === socket) this.closeSocket(new Error("SUPERVISOR_DISCONNECTED"));
+      });
+    });
+  }
+  async handleEvent(event) {
+    if (event.protocolVersion !== SUPERVISOR_PROTOCOL_VERSION) return;
+    if (event.type === "response") {
+      const pending = this.pending.get(event.requestId);
+      if (!pending) return;
+      this.pending.delete(event.requestId);
+      clearTimeout(pending.timer);
+      if (event.ok) pending.resolve(event.result);
+      else pending.reject(new Error(`${event.error?.code || "SUPERVISOR_ERROR"}:${event.error?.message || "request failed"}`));
+      return;
+    }
+    if (event.type === "health") {
+      this.health = event.health;
+      return;
+    }
+    if (event.type === "log") {
+      (event.level === "error" ? this.logger.error : this.logger.info)(event.message);
+      return;
+    }
+    if (event.type === "relayTask") {
+      try {
+        const result = await this.handlers.onRelayTask(event.message);
+        this.write({ protocolVersion: 1, type: "relayTaskResult", lease: this.freshLease(), eventId: event.eventId, original: event.message, result });
+      } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        this.write({
+          protocolVersion: 1,
+          type: "relayTaskResult",
+          lease: this.freshLease(),
+          eventId: event.eventId,
+          original: event.message,
+          result: { jsonrpc: "2.0", id: event.message.id, error: { code: -32603, message } }
+        });
+      }
+      return;
+    }
+    if (event.type === "chatDeliver") await this.handlers.onChatDeliver(event.frame);
+    if (event.type === "channelJoin") await this.handlers.onChannelJoin(event.frame);
+  }
+  write(message) {
+    if (!this.socket || this.socket.destroyed) throw new Error("SUPERVISOR_DISCONNECTED");
+    this.socket.write(encodeSupervisorMessage(message));
+  }
+  closeSocket(error) {
+    if (this.renewTimer) clearInterval(this.renewTimer);
+    this.renewTimer = null;
+    const socket = this.socket;
+    this.socket = null;
+    if (socket && !socket.destroyed) socket.destroy();
+    for (const pending of this.pending.values()) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+};
+
+// src/runtime-evidence.ts
+import { createHmac } from "node:crypto";
+import {
+  chmodSync as chmodSync2,
+  mkdirSync as mkdirSync2,
+  readFileSync as readFileSync3,
+  renameSync as renameSync2,
+  writeFileSync as writeFileSync2
+} from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { join as join3, resolve as resolve2 } from "node:path";
+var RUNTIME_EVIDENCE_SCHEMA_VERSION = 1;
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(
+    Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, canonicalize(child)])
+  );
+}
+function canonicalConfigJson(config) {
+  return JSON.stringify({ schemaVersion: RUNTIME_EVIDENCE_SCHEMA_VERSION, config: canonicalize(config) });
+}
+function configFingerprint(config, hmacKeyHex) {
+  if (!/^[a-f0-9]{64}$/u.test(hmacKeyHex)) throw new Error("runtime evidence HMAC key is invalid");
+  return createHmac("sha256", Buffer.from(hmacKeyHex, "hex")).update(canonicalConfigJson(config)).digest("hex");
+}
+function runtimeEvidenceDir(stateDir) {
+  return resolve2(stateDir ?? process.env.OPENCLAW_STATE_DIR ?? join3(homedir4(), ".openclaw"), "perkos-a2a");
+}
+function runtimeAttemptPath(stateDir) {
+  return join3(runtimeEvidenceDir(stateDir), "active-attempt.json");
+}
+function runtimeStatusPath(stateDir) {
+  return join3(runtimeEvidenceDir(stateDir), "runtime-status.json");
+}
+function configAgentId(config) {
+  if (config.platform?.agentId) return config.platform.agentId;
+  const match = config.platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u);
+  return match?.[1] ?? "unknown";
+}
+function recordRuntimeLoadEvidence(input) {
+  const evidenceDir = runtimeEvidenceDir(input.stateDir);
+  let attempt;
+  try {
+    attempt = JSON.parse(readFileSync3(runtimeAttemptPath(input.stateDir), "utf8"));
+  } catch {
+    input.logger.info(`[perkos-a2a] config loaded version=${input.version} agentId=${configAgentId(input.config)} attemptId=none`);
+    return null;
+  }
+  const agentId = configAgentId(input.config);
+  if (attempt.schemaVersion !== RUNTIME_EVIDENCE_SCHEMA_VERSION || attempt.targetVersion !== input.version || attempt.expectedAgentId !== agentId) {
+    input.logger.warn?.("[perkos-a2a] runtime evidence attempt does not match the loaded plugin identity");
+    return null;
+  }
+  const status = {
+    schemaVersion: RUNTIME_EVIDENCE_SCHEMA_VERSION,
+    loadedAt: (input.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
+    version: input.version,
+    agentId,
+    fingerprint: configFingerprint(input.config, attempt.hmacKeyHex),
+    attemptId: attempt.attemptId,
+    pid: process.pid,
+    pluginRoot: resolve2(input.pluginRoot)
+  };
+  mkdirSync2(evidenceDir, { recursive: true, mode: 448 });
+  const target = runtimeStatusPath(input.stateDir);
+  const temporary = `${target}.${process.pid}.tmp`;
+  writeFileSync2(temporary, `${JSON.stringify(status, null, 2)}
+`, { mode: 384 });
+  renameSync2(temporary, target);
+  chmodSync2(target, 384);
+  input.logger.info(
+    `[perkos-a2a] config loaded version=${status.version} agentId=${status.agentId} attemptId=${status.attemptId} fingerprint=${status.fingerprint}`
+  );
+  return status;
+}
+
 // src/chat-client.ts
+import { randomUUID as randomUUID6 } from "node:crypto";
 var DEFAULT_URL = "wss://chat.perkos.xyz/chat";
 var DEFAULT_HISTORY_LIMIT = 50;
 var DEFAULT_MIN_RECONNECT = 1e3;
@@ -28118,6 +28745,7 @@ var ChatClient = class {
   connected = false;
   authed = false;
   stopped = false;
+  generation = 0;
   constructor(opts) {
     this.agentName = opts.agentName;
     const cfg = opts.config;
@@ -28153,20 +28781,43 @@ var ChatClient = class {
       return;
     }
     this.stopped = false;
-    this.connect();
+    const generation = ++this.generation;
+    this.connect(generation);
   }
   stop() {
-    this.stopped = true;
-    this.clearTimers();
-    if (this.ws) {
+    const socket = this.beginStop();
+    try {
+      socket?.close(1e3, "client shutting down");
+    } catch {
+    }
+  }
+  async stopAndWait(timeoutMs = 5e3) {
+    const socket = this.beginStop();
+    if (!socket || socket.readyState === wrapper_default.CLOSED) return { closeTimedOut: false };
+    return new Promise((resolve4) => {
+      let settled = false;
+      const finish = (closeTimedOut) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve4({ closeTimedOut });
+      };
+      const timer = setTimeout(() => {
+        try {
+          socket.terminate();
+        } catch {
+        }
+        finish(true);
+      }, timeoutMs);
+      timer.unref?.();
+      socket.once("close", () => finish(false));
+      socket.once("error", () => finish(false));
       try {
-        this.ws.close(1e3, "client shutting down");
+        socket.close(1e3, "client shutting down");
       } catch {
+        finish(false);
       }
-      this.ws = null;
-    }
-    this.connected = false;
-    this.authed = false;
+    });
   }
   /**
    * Send a reply from this agent into a conversation. Appends to the local
@@ -28176,7 +28827,7 @@ var ChatClient = class {
    * required (the simple agent loop should just regenerate from history).
    */
   async sendReply(opts) {
-    const id = randomUUID5();
+    const id = randomUUID6();
     const msg = {
       id,
       from: `agent:${this.agentName}`,
@@ -28199,27 +28850,32 @@ var ChatClient = class {
   // -------------------------------------------------------------------------
   // WebSocket lifecycle
   // -------------------------------------------------------------------------
-  connect() {
-    if (this.stopped) return;
+  connect(generation) {
+    if (!this.isCurrent(generation)) return;
     const url = this.config.url;
     this.logger.info(`[perkos-chat] connecting to ${url}`);
     try {
       this.ws = new wrapper_default(url);
     } catch (err) {
       this.logger.error(`[perkos-chat] failed to construct WS: ${errMsg(err)}`);
-      this.scheduleReconnect();
+      this.scheduleReconnect(generation);
       return;
     }
+    const socket = this.ws;
     let authTimer = setTimeout(() => {
-      if (!this.authed) {
+      if (this.isCurrent(generation, socket) && !this.authed) {
         this.logger.error("[perkos-chat] auth timeout");
         try {
-          this.ws?.close(4002, "auth timeout");
+          socket.close(4002, "auth timeout");
         } catch {
         }
       }
     }, AUTH_TIMEOUT_MS);
     this.ws.on("open", () => {
+      if (!this.isCurrent(generation, socket)) {
+        socket.close(1e3, "stale chat generation");
+        return;
+      }
       this.connected = true;
       this.reconnectMs = this.config.minReconnectMs;
       this.sendFrame({
@@ -28230,6 +28886,7 @@ var ChatClient = class {
       });
     });
     this.ws.on("message", (data) => {
+      if (!this.isCurrent(generation, socket)) return;
       let frame;
       try {
         frame = JSON.parse(data.toString("utf8"));
@@ -28244,19 +28901,21 @@ var ChatClient = class {
       void this.handleFrame(frame);
     });
     this.ws.on("close", (code, reason) => {
-      this.connected = false;
-      this.authed = false;
-      this.clearTimers();
       if (authTimer) {
         clearTimeout(authTimer);
         authTimer = null;
       }
+      if (!this.isCurrent(generation, socket)) return;
+      this.connected = false;
+      this.authed = false;
+      this.clearTimers();
       if (!this.stopped) {
         this.logger.info(`[perkos-chat] disconnected (${code}: ${reason?.toString() || "no reason"}); reconnecting`);
-        this.scheduleReconnect();
+        this.scheduleReconnect(generation);
       }
     });
     this.ws.on("error", (err) => {
+      if (!this.isCurrent(generation, socket)) return;
       this.logger.error(`[perkos-chat] WS error: ${errMsg(err)}`);
     });
   }
@@ -28445,10 +29104,12 @@ var ChatClient = class {
       }
     }, this.config.heartbeatIntervalMs);
   }
-  scheduleReconnect() {
-    if (this.stopped) return;
+  scheduleReconnect(generation) {
+    if (!this.isCurrent(generation)) return;
     const delay = this.reconnectMs;
-    this.reconnectTimer = setTimeout(() => this.connect(), delay);
+    this.reconnectTimer = setTimeout(() => {
+      if (this.isCurrent(generation)) this.connect(generation);
+    }, delay);
     this.reconnectMs = Math.min(delay * 2, this.config.maxReconnectMs);
   }
   clearTimers() {
@@ -28461,151 +29122,25 @@ var ChatClient = class {
       this.reconnectTimer = null;
     }
   }
+  isCurrent(generation, socket) {
+    return !this.stopped && generation === this.generation && (!socket || socket === this.ws);
+  }
+  beginStop() {
+    if (this.stopped && !this.ws) return null;
+    this.stopped = true;
+    this.generation += 1;
+    this.clearTimers();
+    const socket = this.ws;
+    this.ws = null;
+    this.connected = false;
+    this.authed = false;
+    return socket;
+  }
 };
 function errMsg(err) {
   return err instanceof Error ? err.message : String(err);
 }
 
-// src/platform-heartbeat.ts
-var DEFAULT_INTERVAL_MS = 6e4;
-var MIN_INTERVAL_MS = 1e4;
-function startPlatformHeartbeat(opts) {
-  const env = opts.env ?? process.env;
-  const fetcher = opts.fetcher ?? fetch;
-  const url = opts.url?.trim() || env.PERKOS_HEARTBEAT_URL?.trim();
-  const relayKey = opts.relayKey?.trim() || env.A2A_RELAY_API_KEY?.trim();
-  if (!url || !relayKey) return { stop: () => void 0 };
-  const configuredInterval = Number(
-    opts.intervalMs ?? env.PERKOS_HEARTBEAT_INTERVAL_MS ?? DEFAULT_INTERVAL_MS
-  );
-  const intervalMs = Number.isFinite(configuredInterval) ? Math.max(MIN_INTERVAL_MS, configuredInterval) : DEFAULT_INTERVAL_MS;
-  const a2aRuntime = env.A2A_RUNTIME?.trim() || "hermes-api";
-  const runtimeKind = opts.runtimeKind ?? (a2aRuntime === "openclaw" ? "openclaw" : a2aRuntime === "custom" ? "custom" : "hermes");
-  let stopped = false;
-  let firstSuccess = true;
-  const report = async () => {
-    if (stopped) return;
-    try {
-      const res = await fetcher(url, {
-        method: "POST",
-        headers: {
-          "content-type": "application/json",
-          authorization: `Bearer ${relayKey}`,
-          "x-relay-key": relayKey
-        },
-        body: JSON.stringify({
-          runtimeKind,
-          version: opts.version?.trim() || env.PERKOS_A2A_VERSION?.trim() || "0.12.26",
-          ts: Date.now()
-        })
-      });
-      if (res.ok) {
-        if (firstSuccess) {
-          opts.logger.info(
-            `[perkos-heartbeat] reported online to ${url} (status=${res.status}, every=${intervalMs}ms)`
-          );
-          firstSuccess = false;
-        }
-      } else {
-        opts.logger.warn(
-          `[perkos-heartbeat] ${res.status} from ${url} (continuing)`
-        );
-      }
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      opts.logger.warn(
-        `[perkos-heartbeat] POST failed to ${url}: ${msg} (continuing)`
-      );
-    }
-  };
-  void report();
-  const timer = setInterval(() => void report(), intervalMs);
-  timer.unref?.();
-  return {
-    stop: () => {
-      stopped = true;
-      clearInterval(timer);
-    }
-  };
-}
-
-// src/runtime-evidence.ts
-import { createHmac } from "node:crypto";
-import {
-  chmodSync,
-  mkdirSync,
-  readFileSync as readFileSync2,
-  renameSync,
-  writeFileSync
-} from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { join as join2, resolve } from "node:path";
-var RUNTIME_EVIDENCE_SCHEMA_VERSION = 1;
-function canonicalize(value) {
-  if (Array.isArray(value)) return value.map(canonicalize);
-  if (!value || typeof value !== "object") return value;
-  return Object.fromEntries(
-    Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, canonicalize(child)])
-  );
-}
-function canonicalConfigJson(config) {
-  return JSON.stringify({ schemaVersion: RUNTIME_EVIDENCE_SCHEMA_VERSION, config: canonicalize(config) });
-}
-function configFingerprint(config, hmacKeyHex) {
-  if (!/^[a-f0-9]{64}$/u.test(hmacKeyHex)) throw new Error("runtime evidence HMAC key is invalid");
-  return createHmac("sha256", Buffer.from(hmacKeyHex, "hex")).update(canonicalConfigJson(config)).digest("hex");
-}
-function runtimeEvidenceDir(stateDir) {
-  return resolve(stateDir ?? process.env.OPENCLAW_STATE_DIR ?? join2(homedir3(), ".openclaw"), "perkos-a2a");
-}
-function runtimeAttemptPath(stateDir) {
-  return join2(runtimeEvidenceDir(stateDir), "active-attempt.json");
-}
-function runtimeStatusPath(stateDir) {
-  return join2(runtimeEvidenceDir(stateDir), "runtime-status.json");
-}
-function configAgentId(config) {
-  if (config.platform?.agentId) return config.platform.agentId;
-  const match = config.platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u);
-  return match?.[1] ?? "unknown";
-}
-function recordRuntimeLoadEvidence(input) {
-  const evidenceDir = runtimeEvidenceDir(input.stateDir);
-  let attempt;
-  try {
-    attempt = JSON.parse(readFileSync2(runtimeAttemptPath(input.stateDir), "utf8"));
-  } catch {
-    input.logger.info(`[perkos-a2a] config loaded version=${input.version} agentId=${configAgentId(input.config)} attemptId=none`);
-    return null;
-  }
-  const agentId = configAgentId(input.config);
-  if (attempt.schemaVersion !== RUNTIME_EVIDENCE_SCHEMA_VERSION || attempt.targetVersion !== input.version || attempt.expectedAgentId !== agentId) {
-    input.logger.warn?.("[perkos-a2a] runtime evidence attempt does not match the loaded plugin identity");
-    return null;
-  }
-  const status = {
-    schemaVersion: RUNTIME_EVIDENCE_SCHEMA_VERSION,
-    loadedAt: (input.now?.() ?? /* @__PURE__ */ new Date()).toISOString(),
-    version: input.version,
-    agentId,
-    fingerprint: configFingerprint(input.config, attempt.hmacKeyHex),
-    attemptId: attempt.attemptId,
-    pid: process.pid,
-    pluginRoot: resolve(input.pluginRoot)
-  };
-  mkdirSync(evidenceDir, { recursive: true, mode: 448 });
-  const target = runtimeStatusPath(input.stateDir);
-  const temporary = `${target}.${process.pid}.tmp`;
-  writeFileSync(temporary, `${JSON.stringify(status, null, 2)}
-`, { mode: 384 });
-  renameSync(temporary, target);
-  chmodSync(target, 384);
-  input.logger.info(
-    `[perkos-a2a] config loaded version=${status.version} agentId=${status.agentId} attemptId=${status.attemptId} fingerprint=${status.fingerprint}`
-  );
-  return status;
-}
-
 // src/types.ts
 function isWebhookEvent(msg) {
   return msg.type === "webhook_event";
@@ -28614,7 +29149,7 @@ function isWebhookEvent(msg) {
 // src/index.ts
 function loadedPluginVersion() {
   try {
-    const manifest = JSON.parse(readFileSync3(new URL("../openclaw.plugin.json", import.meta.url), "utf8"));
+    const manifest = JSON.parse(readFileSync4(new URL("../openclaw.plugin.json", import.meta.url), "utf8"));
     return typeof manifest.version === "string" ? manifest.version : "unknown";
   } catch {
     return "unknown";
@@ -28709,7 +29244,7 @@ async function prepareOpenClawChatSession(api, config, sessionKey, logger) {
   try {
     await patchSessionEntry({
       sessionKey,
-      fallbackEntry: { sessionId: randomUUID6(), updatedAt: Date.now() },
+      fallbackEntry: { sessionId: randomUUID7(), updatedAt: Date.now() },
       preserveActivity: true,
       replaceEntry: true,
       update: (entry) => alignOpenClawChatSessionModel(entry, config.runtime?.model)
@@ -28729,7 +29264,7 @@ async function forceNativeOpenClawChatRuntime(api, config, sessionKey, logger) {
   try {
     await patchSessionEntry({
       sessionKey,
-      fallbackEntry: { sessionId: randomUUID6(), updatedAt: Date.now() },
+      fallbackEntry: { sessionId: randomUUID7(), updatedAt: Date.now() },
       preserveActivity: true,
       replaceEntry: true,
       update: (entry) => ({
@@ -28770,7 +29305,7 @@ async function runOpenClawChatTurn(api, config, sessionKey, prompt, transcriptPr
   const runtimeConfig = currentConfig();
   const workspaceDir = resolveAgentWorkspaceDir(runtimeConfig, agentId);
   const entry = api.runtime?.agent?.session?.getSessionEntry?.({ agentId, sessionKey });
-  const sessionId = typeof entry?.sessionId === "string" && entry.sessionId.trim() ? entry.sessionId : randomUUID6();
+  const sessionId = typeof entry?.sessionId === "string" && entry.sessionId.trim() ? entry.sessionId : randomUUID7();
   const configuredTimeout = api.runtime?.agent?.resolveAgentTimeoutMs?.(runtimeConfig);
   const timeoutMs = Math.min(
     75e3,
@@ -28785,7 +29320,7 @@ async function runOpenClawChatTurn(api, config, sessionKey, prompt, transcriptPr
     prompt,
     transcriptPrompt,
     timeoutMs,
-    runId: randomUUID6(),
+    runId: randomUUID7(),
     trigger: "user",
     messageChannel: "perkos-chat",
     disableTools: true,
@@ -28871,6 +29406,23 @@ async function deliverToHermes(config, message, logger) {
   }
   logger.info(`[perkos-a2a] Delivered inbound A2A task to Hermes API session ${sessionKey} via ${url}`);
 }
+function a2aLifecycleKey(config) {
+  const rawRelayUrl = (config.relay?.url || "no-relay").trim();
+  let relayUrl = rawRelayUrl.replace(/[?#].*$/u, "").replace(/\/+$/u, "").toLowerCase();
+  try {
+    const parsed = new URL(rawRelayUrl);
+    parsed.username = "";
+    parsed.password = "";
+    parsed.search = "";
+    parsed.hash = "";
+    relayUrl = parsed.toString().replace(/\/+$/u, "").toLowerCase();
+  } catch {
+  }
+  const heartbeatUrl = config.platform?.heartbeatUrl || "";
+  const idFromHeartbeat = heartbeatUrl.match(/\/agents\/([^/]+)\/heartbeat(?:\?|$)/u)?.[1];
+  const agentId = config.platform?.agentId || idFromHeartbeat || config.agentName.trim().toLowerCase();
+  return `${relayUrl}|${agentId}`;
+}
 function register(api) {
   const pluginConfig = api.config?.plugins?.entries?.["perkos-a2a"]?.config || {
     agentName: "agent",
@@ -28883,10 +29435,12 @@ function register(api) {
   recordRuntimeLoadEvidence({
     config: pluginConfig,
     version: pluginVersion,
-    pluginRoot: resolve2(dirname(fileURLToPath(import.meta.url)), ".."),
+    pluginRoot: resolve3(dirname2(fileURLToPath2(import.meta.url)), ".."),
     logger
   });
   const server = new A2AServer(pluginConfig, logger);
+  const lifecycleKey = a2aLifecycleKey(pluginConfig);
+  const lifecycleInstanceId = randomUUID7();
   const pendingTasks = [];
   const enqueueSystemEvent = api.runtime?.system?.enqueueSystemEvent;
   const requestHeartbeatNow = api.runtime?.system?.requestHeartbeatNow;
@@ -28941,7 +29495,7 @@ function register(api) {
       await deliverToHermes(pluginConfig, eventText, logger);
       task.artifacts.push({
         kind: "artifact",
-        artifactId: randomUUID6(),
+        artifactId: randomUUID7(),
         parts: [{ kind: "text", text: `debug: delivered task ${task.id} to Hermes API Server` }]
       });
       const finalText2 = await generateRuntimeReply(pluginConfig, text, marker);
@@ -28951,14 +29505,14 @@ function register(api) {
     if (runtimeKind === "none") {
       task.artifacts.push({
         kind: "artifact",
-        artifactId: randomUUID6(),
+        artifactId: randomUUID7(),
         parts: [{ kind: "text", text: `debug: runtime delivery disabled for ${marker}` }]
       });
       return;
     }
     task.artifacts.push({
       kind: "artifact",
-      artifactId: randomUUID6(),
+      artifactId: randomUUID7(),
       parts: [{ kind: "text", text: `debug: enqueued system event for ${marker}` }]
     });
     if (enqueueSystemEvent) {
@@ -29042,7 +29596,7 @@ function register(api) {
       if (!finalText) continue;
       task.artifacts.push({
         kind: "artifact",
-        artifactId: randomUUID6(),
+        artifactId: randomUUID7(),
         parts: [{ kind: "text", text: finalText }]
       });
       task.status = {
@@ -29056,169 +29610,137 @@ function register(api) {
       logger.info(`[perkos-a2a] Task ${task.id} completed from transcript update`);
     }
   });
-  api.registerService({
-    id: "perkos-a2a",
-    start: () => {
-      server.start();
-      logger.info(`[perkos-a2a] A2A server started for ${pluginConfig.agentName}`);
-    },
-    stop: () => {
-      logger.info("[perkos-a2a] A2A server stopping");
-    }
-  });
   const chatApiKey = pluginConfig.chat?.apiKey || pluginConfig.relay?.apiKey;
-  const chatClient = pluginConfig.chat?.enabled && chatApiKey ? new ChatClient({
-    agentName: pluginConfig.agentName,
-    config: {
-      enabled: true,
-      url: pluginConfig.chat?.url || "wss://chat.perkos.xyz/chat",
-      apiKey: chatApiKey,
-      storeRoot: pluginConfig.chat?.storeRoot,
-      defaultHistoryLimit: pluginConfig.chat?.defaultHistoryLimit,
-      minReconnectMs: pluginConfig.chat?.minReconnectMs,
-      maxReconnectMs: pluginConfig.chat?.maxReconnectMs,
-      heartbeatIntervalMs: pluginConfig.chat?.heartbeatIntervalMs
-    },
-    handlers: {
-      logger,
-      onChatDeliver: async (frame) => {
-        const walletAddress = parseWalletFromIdentity(frame.from);
-        const marker = `[PERKOS_CHAT:${frame.convId}]`;
-        const recentPage = await chatClient?.getStore().readPage(frame.convId, {
-          limit: CHAT_CONTEXT_MESSAGE_LIMIT + 1
+  const chatEnabled = Boolean(pluginConfig.chat?.enabled && chatApiKey);
+  const chatStore = chatEnabled ? new ChatStore({ storeRoot: pluginConfig.chat?.storeRoot }) : null;
+  let supervisorClient;
+  const handleSupervisorChatDeliver = async (frame) => {
+    const walletAddress = parseWalletFromIdentity(frame.from);
+    const marker = `[PERKOS_CHAT:${frame.convId}]`;
+    const recentPage = await chatStore?.readPage(frame.convId, {
+      limit: CHAT_CONTEXT_MESSAGE_LIMIT + 1
+    });
+    const recentContext = formatRecentChatContext(recentPage?.messages ?? [], frame.id);
+    const eventText = [
+      marker,
+      `From: ${frame.from}`,
+      `Conversation: ${frame.convId}`,
+      frame.projectId ? `Canonical projectId: ${frame.projectId}` : "",
+      walletAddress ? `Wallet: ${walletAddress}` : "",
+      "",
+      "A user is messaging you in a PerkOS chat conversation.",
+      "To respond, call the `perkos_chat_reply` tool with:",
+      `  convId: "${frame.convId}"`,
+      walletAddress ? `  walletAddress: "${walletAddress}"` : `  walletAddress: <derived from From>`,
+      `  text: <your reply>`,
+      "",
+      "Recent conversation context (oldest to newest):",
+      recentContext,
+      "",
+      "Use the recent context. Do not ask again for information the user already provided.",
+      "",
+      "Message body:",
+      frame.text
+    ].filter(Boolean).join("\n");
+    const directRunPrompt = [
+      marker,
+      `From: ${frame.from}`,
+      `Conversation: ${frame.convId}`,
+      frame.projectId ? `Canonical projectId: ${frame.projectId}` : "",
+      "",
+      "Reply to this PerkOS chat message using your current runtime configuration.",
+      "Return only the reply text. Do not call messaging tools; the PerkOS plugin delivers the returned text.",
+      "Use the recent context and do not ask again for information already provided.",
+      "",
+      "Recent conversation context (oldest to newest):",
+      recentContext,
+      "",
+      "Message body:",
+      frame.text
+    ].filter(Boolean).join("\n");
+    const runtimeKind = pluginConfig.runtime?.kind || "openclaw";
+    if (runtimeKind === "hermes" || runtimeKind === "hermes-api") {
+      try {
+        await deliverToHermes(pluginConfig, eventText, logger);
+      } catch (err) {
+        logger.error(`[perkos-chat] hermes delivery failed: ${err instanceof Error ? err.message : String(err)}`);
+      }
+      return;
+    }
+    if (runtimeKind === "none") {
+      logger.info(`[perkos-chat] dropped chat_deliver for ${frame.convId} (runtime=none)`);
+      return;
+    }
+    const chatSessionKey = openclawChatSessionKey(pluginConfig, frame.convId);
+    await prepareOpenClawChatSession(api, pluginConfig, chatSessionKey, logger);
+    if (walletAddress) {
+      const reply = await runOpenClawChatTurn(api, pluginConfig, chatSessionKey, directRunPrompt, frame.text, logger);
+      if (reply) {
+        const result = await supervisorClient.sendChatReply({
+          convId: frame.convId,
+          walletAddress,
+          text: reply,
+          replyTo: frame.id
         });
-        const recentContext = formatRecentChatContext(
-          recentPage?.messages ?? [],
-          frame.id
-        );
-        const eventText = [
-          marker,
-          `From: ${frame.from}`,
-          `Conversation: ${frame.convId}`,
-          frame.projectId ? `Canonical projectId: ${frame.projectId}` : "",
-          walletAddress ? `Wallet: ${walletAddress}` : "",
-          "",
-          "A user is messaging you in a PerkOS chat conversation.",
-          "To respond, call the `perkos_chat_reply` tool with:",
-          `  convId: "${frame.convId}"`,
-          walletAddress ? `  walletAddress: "${walletAddress}"` : `  walletAddress: <derived from From>`,
-          `  text: <your reply>`,
-          "",
-          "Recent conversation context (oldest to newest):",
-          recentContext,
-          "",
-          "Use the recent context. Do not ask again for information the user already provided.",
-          "",
-          "Message body:",
-          frame.text
-        ].filter(Boolean).join("\n");
-        const directRunPrompt = [
-          marker,
-          `From: ${frame.from}`,
-          `Conversation: ${frame.convId}`,
-          frame.projectId ? `Canonical projectId: ${frame.projectId}` : "",
-          "",
-          "Reply to this PerkOS chat message using your current runtime configuration.",
-          "Return only the reply text. Do not call messaging tools; the PerkOS plugin delivers the returned text.",
-          "Use the recent context and do not ask again for information already provided.",
-          "",
-          "Recent conversation context (oldest to newest):",
-          recentContext,
-          "",
-          "Message body:",
-          frame.text
-        ].filter(Boolean).join("\n");
-        const runtimeKind = pluginConfig.runtime?.kind || "openclaw";
-        if (runtimeKind === "hermes" || runtimeKind === "hermes-api") {
-          try {
-            await deliverToHermes(pluginConfig, eventText, logger);
-          } catch (err) {
-            logger.error(`[perkos-chat] hermes delivery failed: ${err instanceof Error ? err.message : String(err)}`);
-          }
-          return;
-        }
-        if (runtimeKind === "none") {
-          logger.info(`[perkos-chat] dropped chat_deliver for ${frame.convId} (runtime=none)`);
-          return;
-        }
-        const chatSessionKey = openclawChatSessionKey(pluginConfig, frame.convId);
-        await prepareOpenClawChatSession(api, pluginConfig, chatSessionKey, logger);
-        if (walletAddress) {
-          const reply = await runOpenClawChatTurn(
-            api,
-            pluginConfig,
-            chatSessionKey,
-            directRunPrompt,
-            frame.text,
-            logger
-          );
-          if (reply) {
-            const result = await chatClient?.sendReply({
-              convId: frame.convId,
-              walletAddress,
-              text: reply,
-              replyTo: frame.id
-            });
-            logger.info(
-              `[perkos-chat] embedded reply ${result?.delivered ? "delivered" : "queued (offline)"} for ${frame.convId}`
-            );
-            return;
-          }
-        }
-        if (enqueueSystemEvent) {
-          enqueueSystemEvent(eventText, { sessionKey: chatSessionKey });
-        }
-        wakeGatewayAgent(
-          requestHeartbeatNow,
-          `[PerkOS-Chat] inbound message in ${frame.convId}`,
-          logger,
-          chatSessionKey
-        );
-      },
-      onChannelJoin: async (frame) => {
-        logger.info(`[perkos-chat] joined conv ${frame.convId} (host: ${frame.historyHost}, ${frame.participants.length} participants)`);
+        logger.info(`[perkos-chat] embedded reply ${result.delivered ? "delivered" : "queued (offline)"} for ${frame.convId}`);
+        return;
       }
     }
-  }) : null;
+    if (enqueueSystemEvent) enqueueSystemEvent(eventText, { sessionKey: chatSessionKey });
+    wakeGatewayAgent(requestHeartbeatNow, `[PerkOS-Chat] inbound message in ${frame.convId}`, logger, chatSessionKey);
+  };
   if (pluginConfig.chat?.enabled && !chatApiKey) {
     logger.error("[perkos-chat] chat.enabled=true but no apiKey (set chat.apiKey or fall back from relay.apiKey)");
   }
-  if (chatClient) {
-    api.registerService({
-      id: "perkos-a2a-chat",
-      start: () => {
-        chatClient.start();
-        logger.info(`[perkos-chat] client started for ${pluginConfig.agentName}`);
-      },
-      stop: () => {
-        chatClient.stop();
-        logger.info("[perkos-chat] client stopped");
-      }
-    });
-  }
-  if (pluginConfig.platform?.heartbeatUrl) {
-    let platformHeartbeat = null;
-    api.registerService({
-      id: "perkos-a2a-platform-heartbeat",
-      start: () => {
-        platformHeartbeat = startPlatformHeartbeat({
-          logger: {
-            info: (message) => logger.info(message),
-            warn: (message) => (logger.warn || logger.info).call(logger, message)
-          },
-          url: pluginConfig.platform?.heartbeatUrl,
-          relayKey: pluginConfig.relay?.apiKey,
-          runtimeKind: "openclaw",
-          version: pluginVersion,
-          intervalMs: pluginConfig.platform?.heartbeatIntervalMs
-        });
-      },
-      stop: () => {
-        platformHeartbeat?.stop();
-        platformHeartbeat = null;
+  const platformAgentId = pluginConfig.platform?.agentId || pluginConfig.platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u)?.[1] || pluginConfig.agentName.trim().toLowerCase();
+  supervisorClient = new OpenClawSupervisorClient({
+    ownerHash: supervisorOwnerHash(lifecycleKey),
+    generation: Date.now(),
+    instanceId: lifecycleInstanceId,
+    config: {
+      agentName: pluginConfig.agentName,
+      agentId: platformAgentId,
+      version: pluginVersion,
+      relay: pluginConfig.relay,
+      chat: chatEnabled ? {
+        enabled: true,
+        url: pluginConfig.chat?.url || "wss://chat.perkos.xyz/chat",
+        apiKey: chatApiKey || "",
+        storeRoot: pluginConfig.chat?.storeRoot,
+        defaultHistoryLimit: pluginConfig.chat?.defaultHistoryLimit,
+        minReconnectMs: pluginConfig.chat?.minReconnectMs,
+        maxReconnectMs: pluginConfig.chat?.maxReconnectMs,
+        heartbeatIntervalMs: pluginConfig.chat?.heartbeatIntervalMs
+      } : void 0,
+      platform: {
+        heartbeatUrl: pluginConfig.platform?.heartbeatUrl,
+        heartbeatIntervalMs: pluginConfig.platform?.heartbeatIntervalMs
+      },
+      agentCard: server.getAgentCard()
+    },
+    logger,
+    handlers: {
+      onRelayTask: (message) => server.handleTransportTask(message),
+      onChatDeliver: handleSupervisorChatDeliver,
+      onChannelJoin: async (frame) => {
+        logger.info(`[perkos-chat] joined conv ${frame.convId} (host: ${frame.historyHost}, ${frame.participants.length} participants)`);
       }
-    });
-  }
+    }
+  });
+  server.setRelayTransport(supervisorClient);
+  api.registerService({
+    id: "perkos-a2a",
+    start: async () => {
+      await supervisorClient.start();
+      await server.start();
+      logger.info(`[perkos-a2a] A2A server started for ${pluginConfig.agentName}`);
+    },
+    stop: async () => {
+      logger.info("[perkos-a2a] A2A server stopping");
+      await server.stop({ reason: "openclaw-service-stop", timeoutMs: 8e3, drainMs: 3e3 });
+      await supervisorClient.stop();
+    }
+  });
   api.registerTool({
     name: "perkos_a2a_send",
     description: "Send a task to another agent via PerkOS A2A. Use this to delegate work, ask a peer to research, or route a chain/circular workflow. The message may name additional agents and a final notification target; the bridge preserves the route and prevents loops.",
@@ -29405,13 +29927,13 @@ function register(api) {
       required: ["convId", "walletAddress", "text"]
     },
     async execute(_id, params) {
-      if (!chatClient) {
+      if (!chatEnabled) {
         return {
           content: [{ type: "text", text: "PerkOS-Chat client is not enabled in this agent's config." }]
         };
       }
       try {
-        const result = await chatClient.sendReply({
+        const result = await supervisorClient.sendChatReply({
           convId: params.convId,
           walletAddress: params.walletAddress,
           text: params.text,
@@ -29452,14 +29974,13 @@ function register(api) {
       required: ["convId"]
     },
     async execute(_id, params) {
-      if (!chatClient) {
+      if (!chatStore) {
         return {
           content: [{ type: "text", text: "PerkOS-Chat client is not enabled in this agent's config." }]
         };
       }
       try {
-        const store = chatClient.getStore();
-        const page = await store.readPage(params.convId, {
+        const page = await chatStore.readPage(params.convId, {
           before: params.before ?? null,
           limit: params.limit ?? 50
         });
@@ -29488,9 +30009,9 @@ function register(api) {
       hasSystemEventInjection: !!enqueueSystemEvent,
       protocol: "a2a",
       version: "0.8.4",
-      chat: chatClient ? {
+      chat: chatEnabled ? {
         enabled: true,
-        connected: chatClient.isConnected(),
+        connected: supervisorClient.isChatConnected(),
         url: pluginConfig.chat?.url || "wss://chat.perkos.xyz/chat"
       } : { enabled: false, connected: false, url: null }
     });
@@ -29508,8 +30029,8 @@ function register(api) {
         console.log(`Auth required: ${pluginConfig.auth?.requireApiKey || false}`);
         console.log(`Peers: ${Object.keys(pluginConfig.peers).join(", ") || "(none)"}`);
         console.log(`System event injection: ${!!enqueueSystemEvent}`);
-        if (chatClient) {
-          console.log(`Chat: enabled (connected=${chatClient.isConnected()}, url=${pluginConfig.chat?.url || "wss://chat.perkos.xyz/chat"})`);
+        if (chatEnabled) {
+          console.log(`Chat: enabled (connected=${supervisorClient.isChatConnected()}, url=${pluginConfig.chat?.url || "wss://chat.perkos.xyz/chat"})`);
         } else {
           console.log("Chat: disabled");
         }
@@ -29530,26 +30051,26 @@ function register(api) {
         console.log("[perkos-a2a] Detecting environment...\n");
         const isMac = process.platform === "darwin";
         console.log(`Platform: ${process.platform}${isMac ? " (macOS)" : ""}`);
-        const net = await detectNetworking();
-        console.log(`Public IP: ${net.publicIp || "unknown"}`);
-        console.log(`Local IPs: ${net.localIps.join(", ") || "none"}`);
-        console.log(`Behind NAT: ${net.isBehindNat ? "yes" : "no"}`);
-        console.log(`Tailscale: ${net.hasTailscale ? "installed" : "not found"}${net.tailscaleIp ? ` (${net.tailscaleIp})` : ""}`);
+        const net2 = await detectNetworking();
+        console.log(`Public IP: ${net2.publicIp || "unknown"}`);
+        console.log(`Local IPs: ${net2.localIps.join(", ") || "none"}`);
+        console.log(`Behind NAT: ${net2.isBehindNat ? "yes" : "no"}`);
+        console.log(`Tailscale: ${net2.hasTailscale ? "installed" : "not found"}${net2.tailscaleIp ? ` (${net2.tailscaleIp})` : ""}`);
         let portAvailable = true;
         try {
           const netMod = await import("net");
-          await new Promise((resolve3, reject) => {
+          await new Promise((resolve4, reject) => {
             const srv = netMod.createServer();
             srv.once("error", (err) => {
               if (err.code === "EADDRINUSE") {
                 portAvailable = false;
-                resolve3();
+                resolve4();
               } else {
                 reject(err);
               }
             });
             srv.listen(pluginConfig.port, () => {
-              srv.close(() => resolve3());
+              srv.close(() => resolve4());
             });
           });
         } catch {
@@ -29569,14 +30090,14 @@ Relay: ${pluginConfig.relay?.enabled ? "enabled" : "disabled"}`);
         console.log(`  Local loopback URL for this agent: http://127.0.0.1:${pluginConfig.port}/a2a/jsonrpc`);
         console.log("  Configure same-host peers as http://127.0.0.1:<peer-port>, not by shared public IP.");
         console.log("");
-        if (!net.isBehindNat) {
+        if (!net2.isBehindNat) {
           console.log("You have a public IP. Use it only for remote peers that cannot reach a local/tunnel URL.");
-          console.log(`  Public A2A URL candidate: http://${net.publicIp}:${pluginConfig.port}/a2a/jsonrpc`);
+          console.log(`  Public A2A URL candidate: http://${net2.publicIp}:${pluginConfig.port}/a2a/jsonrpc`);
         } else if (pluginConfig.relay?.enabled) {
           console.log("You are behind NAT but relay is configured. Bidirectional communication via relay.");
-        } else if (net.hasTailscale && net.tailscaleIp) {
+        } else if (net2.hasTailscale && net2.tailscaleIp) {
           console.log("Use your Tailscale IP for peers.");
-          console.log(`  Your A2A URL: http://${net.tailscaleIp}:${pluginConfig.port}/a2a/jsonrpc`);
+          console.log(`  Your A2A URL: http://${net2.tailscaleIp}:${pluginConfig.port}/a2a/jsonrpc`);
         } else {
           console.log("You are behind NAT. Options:");
           console.log("  1) Configure a relay hub (recommended) - set relay.url and relay.enabled in config");
@@ -29600,6 +30121,7 @@ export {
   ChatStore,
   RelayClient,
   RelayHub,
+  a2aLifecycleKey,
   alignOpenClawChatSessionModel,
   register as default,
   detectNetworking,