@perkos/perkos-a2a 0.12.34 → 0.12.36

package/README.md

@@ -183,24 +183,24 @@ schema, and protects identity, relay/chat credentials, endpoints, runtime kind,
 and session key. Bind-mounted `openclaw.json` files are updated in place when an
 atomic rename is unavailable, while a persistent backup and the quarantined
 legacy extension remain recoverable. A process lock prevents two simultaneous
-repairs from registering the same agent. Version 0.12.34 writes the signed
+repairs from registering the same agent. Version 0.12.35 writes the signed
 attempt before OpenClaw can load the newly enabled plugin, so a clean first
 generation started during `config validate` is attributable to that exact
 command rather than being rejected as pre-restart evidence.
 
 Every successful install is anchored by a private, content-addressed receipt;
 the resumable repair journal rolls forward after an install has committed
-instead of restoring an incompatible pre-upgrade source. On restart, the
-plugin writes HMAC-bound runtime evidence proving that the expected version and
-normalized config were actually loaded. The receipt, journal, attempt, and
-runtime status files are created with owner-only permissions.
-
-It validates config and plugin health, performs a verifiable restart, then reads
-only plugin-owned runtime evidence. It does not launch a second relay/chat client
-and does not scrape `openclaw gateway status` or gateway log files during the
-verification window. A normal service must return a new PID/start identity; a
-containerized PID 1 gateway restarts in-process through OpenClaw's authorized
-`SIGUSR1` path. Relay, registration, heartbeat, and chat authentication must
+instead of restoring an incompatible pre-upgrade source. The plugin writes
+HMAC-bound runtime evidence proving that the expected version and normalized
+config were actually loaded. The receipt, journal, attempt, and runtime status
+files are created with owner-only permissions.
+
+It validates config and plugin health, then reads only plugin-owned runtime
+evidence. It never mutates `commands.restart`, sends `SIGUSR1`, waits for an
+OpenClaw gateway drain, launches a second relay/chat client, or scrapes gateway
+status/logs. Clean installs complete through hot reload. Certified upgrades use
+a fenced supervisor rollover while the gateway and its active model/runtime
+remain untouched. Relay, registration, heartbeat, and chat authentication must
 remain healthy—with no duplicate plugin or registration messages—for three
 continuous minutes and at least three fresh successful heartbeats. Success or
 failure is emitted as one JSON object; secret values are never printed.
@@ -220,13 +220,15 @@ READY and accept the matching claim. The supervisor records its PID, process
 start identity, boot id, claim time, and transport counts in private health
 evidence so `connect` can distinguish a certified owner from stale files.
 
-For a clean first install, OpenClaw's PID 1 hot reload remains supported. When
-upgrading a pre-supervisor or otherwise uncertified installation, `connect`
-requires evidence that the gateway PID/start identity actually changed. If the
-current environment cannot perform that restart safely, it exits with the
-machine-readable action `ACTION_REQUIRED_REAL_RESTART`; rerunning the same
-idempotent command after the service/container restart resumes the migration
-without replacing identity or credentials.
+For a clean first install, OpenClaw's PID 1 hot reload remains supported without
+a gateway restart. A certified upgrade fences and stops the old supervisor,
+waits for `STOPPED` plus socket/process exit, starts the supervisor CLI from the
+new verified install root, and requires target-version health before opening a
+single relay client. When upgrading a pre-supervisor or otherwise uncertified
+installation, `connect` exits promptly with the machine-readable action
+`ACTION_REQUIRED_REAL_RESTART`; rerunning the same idempotent command after an
+out-of-band service/container restart resumes the migration without replacing
+identity or credentials.
 
 On successful verification, `connect` removes the active-attempt file and marks
 the private repair journal `done`. Stale OpenClaw install metadata is reported
@@ -237,14 +239,16 @@ version; stale metadata is never allowed to weaken those identity checks.
 Each claim carries the parent PID/start identity, boot id, instance id, and
 generation. Before accepting a newer generation, the supervisor waits for
 confirmed transport shutdown; a timeout fails closed with
-`OWNER_STOP_TIMEOUT`. Lease and health evidence are owner-only files and never
+`OWNER_STOP_TIMEOUT`. A private TTL rollover lock serializes concurrent upgrades,
+and health certifies the supervisor package version and real install root. Lease
+and health evidence are owner-only files and never
 contain relay or chat credentials. This ownership boundary applies to OpenClaw;
 Hermes/custom runtimes keep their existing runtime-owned model and transport
 routing.
 
 ```bash
 A2A_RELAY_API_KEY='<credential-from-invitation>' \
-npx --yes @perkos/perkos-a2a@0.12.34 connect \
+npx --yes @perkos/perkos-a2a@0.12.36 connect \
   --artifact ./perkos-a2a.tgz \
   --sha256 '<sha256-from-the-official-invitation>' \
   --agent-name '<agent-name>' \

package/dist/index.d.ts

@@ -53,5 +53,12 @@ export declare function runOpenClawChatTurn(api: any, config: A2APluginConfig, s
 export declare function formatRecentChatContext(messages: ChatMessage[], currentMessageId: string): string;
 /** The identity the relay treats as exclusive; names are display metadata. */
 export declare function a2aLifecycleKey(config: A2APluginConfig): string;
+/**
+ * OpenClaw may briefly call register while a plugin entry is being rewritten.
+ * Treat partial/empty config as an inert, valid shape instead of crashing the
+ * whole service on string operations. The repair CLI restores the complete
+ * identity atomically before the service is enabled.
+ */
+export declare function normalizeOpenClawPluginConfig(value: unknown): A2APluginConfig;
 export default function register(api: any): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAGV,WAAW,EAEZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,cAAc,YAAY,CAAC;AA0C3B,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAItF;AAED,KAAK,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AASpD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,oBAAoB,EAAE,MAAM,GAC3B,OAAO,CA2BT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,oBAAoB,EAC3B,eAAe,CAAC,EAAE,MAAM,GACvB,oBAAoB,CA+BtB;AAiED,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,CAAC,CAAC;IACH,IAAI,CAAC,EAAE;QACL,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;CACH,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAYrF;AAQD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,GAClF,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuFxB;AAYD,oFAAoF;AACpF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,EAAE,EACvB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAWR;AA4CD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAe/D;AAED,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QAqzBxC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAaH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAClD,OAAO,KAAK,EAGV,WAAW,EAEZ,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,cAAc,YAAY,CAAC;AA0C3B,kEAAkE;AAClE,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAItF;AAED,KAAK,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AASpD;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,oBAAoB,EAAE,MAAM,GAC3B,OAAO,CA2BT;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,oBAAoB,EAC3B,eAAe,CAAC,EAAE,MAAM,GACvB,oBAAoB,CA+BtB;AAiED,KAAK,qBAAqB,GAAG;IAC3B,QAAQ,CAAC,EAAE,KAAK,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,OAAO,CAAC,EAAE,OAAO,CAAC;QAClB,WAAW,CAAC,EAAE,OAAO,CAAC;QACtB,YAAY,CAAC,EAAE,OAAO,CAAC;KACxB,CAAC,CAAC;IACH,IAAI,CAAC,EAAE;QACL,yBAAyB,CAAC,EAAE,MAAM,CAAC;QACnC,qBAAqB,CAAC,EAAE,MAAM,CAAC;KAChC,CAAC;CACH,CAAC;AAEF,wBAAgB,wBAAwB,CAAC,MAAM,EAAE,qBAAqB,GAAG,MAAM,GAAG,IAAI,CAYrF;AAQD,wBAAsB,mBAAmB,CACvC,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,eAAe,EACvB,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,gBAAgB,EAAE,MAAM,EACxB,MAAM,EAAE;IAAE,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,IAAI,CAAA;CAAE,GAClF,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAuFxB;AAYD,oFAAoF;AACpF,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,WAAW,EAAE,EACvB,gBAAgB,EAAE,MAAM,GACvB,MAAM,CAWR;AA4CD,8EAA8E;AAC9E,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,GAAG,MAAM,CAe/D;AAMD;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAAC,KAAK,EAAE,OAAO,GAAG,eAAe,CAc7E;AAED,MAAM,CAAC,OAAO,UAAU,QAAQ,CAAC,GAAG,EAAE,GAAG,QAozBxC"}

package/dist/index.js

@@ -18429,7 +18429,7 @@ var require_view = __commonJS({
     var debug = require_src()("express:view");
     var path = __require("path");
     var fs = __require("fs");
-    var dirname3 = path.dirname;
+    var dirname4 = path.dirname;
     var basename = path.basename;
     var extname = path.extname;
     var join4 = path.join;
@@ -18468,7 +18468,7 @@ var require_view = __commonJS({
       for (var i = 0; i < roots.length && !path2; i++) {
         var root = roots[i];
         var loc = resolve4(root, name);
-        var dir = dirname3(loc);
+        var dir = dirname4(loc);
         var file = basename(loc);
         path2 = this.resolve(dir, file);
       }
@@ -27718,7 +27718,7 @@ var A2AServer = class {
 // src/index.ts
 import { randomUUID as randomUUID7 } from "crypto";
 import { readFileSync as readFileSync5 } from "node:fs";
-import { dirname as dirname2, resolve as resolve3 } from "node:path";
+import { dirname as dirname3, resolve as resolve3 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 
 // src/agentic-actions.ts
@@ -28339,10 +28339,10 @@ function isNotFound(err) {
 // src/openclaw-supervisor-client.ts
 import { randomUUID as randomUUID5 } from "node:crypto";
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync as readFileSync3, unlinkSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync as mkdirSync2, openSync, readFileSync as readFileSync3, realpathSync, unlinkSync, writeFileSync as writeFileSync2 } from "node:fs";
 import { homedir as homedir3 } from "node:os";
 import net from "node:net";
-import { resolve } from "node:path";
+import { dirname as dirname2, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // src/supervisor-protocol.ts
@@ -28352,6 +28352,7 @@ import { tmpdir } from "node:os";
 import { dirname, join as join2 } from "node:path";
 var SUPERVISOR_PROTOCOL_VERSION = 2;
 var SUPERVISOR_RENEW_MS = 5e3;
+var CURRENT_PROCESS_EPOCH_MS = Math.floor(Date.now() - process.uptime() * 1e3);
 function supervisorOwnerHash(lifecycleKey) {
   return createHash2("sha256").update(lifecycleKey).digest("hex");
 }
@@ -28367,6 +28368,9 @@ function supervisorSocketPath(stateDir, ownerHash) {
 function supervisorBootstrapPath(stateDir, ownerHash) {
   return join2(supervisorDir(stateDir), `${ownerHash}.bootstrap.json`);
 }
+function supervisorRolloverLockPath(stateDir, ownerHash) {
+  return join2(supervisorDir(stateDir), `${ownerHash}.rollover.lock`);
+}
 function currentBootId() {
   try {
     return readFileSync2("/proc/sys/kernel/random/boot_id", "utf8").trim();
@@ -28380,7 +28384,7 @@ function processStartIdentity(pid = process.pid) {
     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)}`;
+    if (pid === process.pid) return `epoch-ms:${CURRENT_PROCESS_EPOCH_MS}`;
     return "unknown";
   }
 }
@@ -28390,6 +28394,14 @@ function encodeSupervisorMessage(message) {
 }
 
 // src/openclaw-supervisor-client.ts
+function processIsAlive(pid) {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
 var OpenClawSupervisorClient = class {
   stateDir;
   ownerHash;
@@ -28398,6 +28410,7 @@ var OpenClawSupervisorClient = class {
   logger;
   handlers;
   supervisorCliPath;
+  spawnSupervisor;
   lease;
   socket = null;
   startPromise = null;
@@ -28410,10 +28423,16 @@ var OpenClawSupervisorClient = class {
     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;
+    let installRoot = resolve(input.config.installRoot);
+    try {
+      installRoot = realpathSync(installRoot);
+    } catch {
+    }
+    this.config = { ...input.config, installRoot };
     this.logger = input.logger;
     this.handlers = input.handlers;
     this.supervisorCliPath = input.supervisorCliPath;
+    this.spawnSupervisor = input.spawnSupervisor;
     this.lease = {
       ownerKey: input.ownerHash,
       instanceId: input.instanceId,
@@ -28439,15 +28458,18 @@ var OpenClawSupervisorClient = class {
     this.stopped = false;
     const starting = (async () => {
       await this.connectOrSpawn();
-      const claim = await this.requestWithMessage({
-        protocolVersion: 2,
-        type: "claim",
-        requestId: randomUUID5(),
-        lease: this.freshLease(),
-        config: this.config
-      }, 15e3);
+      let claim;
+      try {
+        claim = await this.claimCurrentSupervisor();
+      } catch (error) {
+        if (!String(error).includes("SUPERVISOR_TARGET_MISMATCH")) throw error;
+        claim = await this.rolloverSupervisor("target-mismatch");
+      }
+      if (!this.healthMatchesTarget(claim.health)) {
+        claim = await this.rolloverSupervisor("legacy-health-missing-target");
+      }
       const health = claim?.health;
-      if (claim?.state !== "READY" || health?.schemaVersion !== 2 || health.authority !== "process-external-supervisor" || health.state !== "running" || health.ownerKey !== this.ownerHash || health.instanceId !== this.lease.instanceId || health.generation !== this.lease.generation || health.relayClientCount !== (this.config.relay?.enabled && this.config.relay.url ? 1 : 0) || !health.claimedAt) {
+      if (claim?.state !== "READY" || health?.schemaVersion !== 2 || health.authority !== "process-external-supervisor" || health.state !== "running" || health.ownerKey !== this.ownerHash || health.instanceId !== this.lease.instanceId || health.generation !== this.lease.generation || !this.healthMatchesTarget(health) || health.relayClientCount !== (this.config.relay?.enabled && this.config.relay.url ? 1 : 0) || !health.claimedAt) {
         throw new Error("OWNERSHIP_PRIMITIVE_UNAVAILABLE:supervisor claim did not return certified READY/CLAIMED health");
       }
       this.health = health;
@@ -28460,6 +28482,148 @@ var OpenClawSupervisorClient = class {
     this.startPromise = starting;
     return starting;
   }
+  claimCurrentSupervisor() {
+    return this.requestWithMessage({
+      protocolVersion: 2,
+      type: "claim",
+      requestId: randomUUID5(),
+      lease: this.freshLease(),
+      config: this.config
+    }, 15e3);
+  }
+  healthMatchesTarget(health) {
+    if (!health || health.targetVersion !== this.config.version || !health.installRoot) return false;
+    let healthRoot = resolve(health.installRoot);
+    try {
+      healthRoot = realpathSync(healthRoot);
+    } catch {
+    }
+    return healthRoot === this.config.installRoot;
+  }
+  async rolloverSupervisor(reason) {
+    const releaseLock = await this.acquireRolloverLock();
+    try {
+      this.closeSocket(new Error("SUPERVISOR_ROLLOVER_RECHECK"));
+      await this.connectOrSpawn();
+      try {
+        const current = await this.claimCurrentSupervisor();
+        if (this.healthMatchesTarget(current.health)) return current;
+        const stopped = await this.requestWithMessage({
+          protocolVersion: 2,
+          type: "release",
+          requestId: randomUUID5(),
+          lease: this.freshLease()
+        }, 8e3);
+        if (stopped?.state !== "STOPPED") throw new Error("OWNER_STOP_TIMEOUT:legacy supervisor did not return STOPPED");
+      } catch (error) {
+        if (!String(error).includes("SUPERVISOR_TARGET_MISMATCH")) throw error;
+        const stopped = await this.requestWithMessage({
+          protocolVersion: 2,
+          type: "prepareRollover",
+          requestId: randomUUID5(),
+          lease: this.freshLease(),
+          targetVersion: this.config.version,
+          targetInstallRoot: this.config.installRoot
+        }, 8e3);
+        if (stopped?.state !== "STOPPED") throw new Error("OWNER_STOP_TIMEOUT:supervisor rollover did not return STOPPED");
+      }
+      const oldHealth = this.health;
+      this.closeSocket(new Error("SUPERVISOR_ROLLOVER"));
+      await this.waitForSupervisorStop(oldHealth, 1e4);
+      const target = await this.claimTargetAfterRollover(reason);
+      this.logger.info(`[perkos-a2a] Supervisor rollover complete targetVersion=${this.config.version}`);
+      return target;
+    } finally {
+      releaseLock();
+    }
+  }
+  /**
+   * OpenClaw can register two adjacent hot-reload generations while its config
+   * file is settling. The first generation may successfully bootstrap the
+   * target supervisor just as its client socket is replaced. Reconnect to that
+   * single fenced supervisor instead of abandoning the agent offline.
+   */
+  async claimTargetAfterRollover(reason) {
+    let lastError;
+    for (let attempt = 1; attempt <= 3; attempt += 1) {
+      try {
+        await this.connectOrSpawn();
+        const target = await this.claimCurrentSupervisor();
+        if (!this.healthMatchesTarget(target.health)) {
+          throw new Error(`SUPERVISOR_ROLLOVER_TARGET_MISMATCH:${reason}`);
+        }
+        return target;
+      } catch (error) {
+        lastError = error;
+        this.closeSocket(new Error("SUPERVISOR_ROLLOVER_TARGET_RETRY"));
+        this.logger.error(
+          `[perkos-a2a] Supervisor target claim retry ${attempt}/3: ${error instanceof Error ? error.message : String(error)}`
+        );
+        if (attempt < 3) await new Promise((resolveWait) => setTimeout(resolveWait, 250));
+      }
+    }
+    throw new Error(
+      `SUPERVISOR_ROLLOVER_TARGET_START_FAILED:${lastError instanceof Error ? lastError.message : String(lastError)}`
+    );
+  }
+  async acquireRolloverLock(timeoutMs = 15e3) {
+    const path = supervisorRolloverLockPath(this.stateDir, this.ownerHash);
+    mkdirSync2(dirname2(path), { recursive: true, mode: 448 });
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      try {
+        const fd = openSync(path, "wx", 384);
+        writeFileSync2(fd, `${JSON.stringify({
+          schemaVersion: 1,
+          instanceId: this.lease.instanceId,
+          pid: process.pid,
+          processStartTime: processStartIdentity(),
+          expiresAt: new Date(Date.now() + 2e4).toISOString()
+        })}
+`);
+        closeSync(fd);
+        return () => {
+          try {
+            const lock = JSON.parse(readFileSync3(path, "utf8"));
+            if (lock.instanceId === this.lease.instanceId) unlinkSync(path);
+          } catch {
+          }
+        };
+      } catch (error) {
+        if (error.code !== "EEXIST") throw error;
+        try {
+          const lock = JSON.parse(readFileSync3(path, "utf8"));
+          const expired = !lock.expiresAt || Date.parse(lock.expiresAt) <= Date.now();
+          const observedStart = lock.pid ? processStartIdentity(lock.pid) : "unknown";
+          const reusedLinuxPid = observedStart.startsWith("linux-start-ticks:") && Boolean(lock.processStartTime?.startsWith("linux-start-ticks:")) && observedStart !== lock.processStartTime;
+          const dead = !lock.pid || !processIsAlive(lock.pid) || reusedLinuxPid;
+          if (expired || dead) {
+            unlinkSync(path);
+            continue;
+          }
+        } catch {
+          try {
+            unlinkSync(path);
+          } catch {
+          }
+          continue;
+        }
+        await new Promise((resolveWait) => setTimeout(resolveWait, 100));
+      }
+    }
+    throw new Error("ROLLOVER_LOCK_TIMEOUT");
+  }
+  async waitForSupervisorStop(health, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+      const socketGone = !existsSync(this.socketPath);
+      const processGone = !health || processStartIdentity(health.pid) !== health.supervisorStartTime;
+      if (socketGone && (processGone || health?.state === "stopped")) return;
+      if (socketGone && processStartIdentity(health?.pid ?? -1) === "unknown") return;
+      await new Promise((resolveWait) => setTimeout(resolveWait, 100));
+    }
+    throw new Error("OWNER_STOP_TIMEOUT:old supervisor process/socket remained active");
+  }
   stop() {
     if (this.stopPromise) return this.stopPromise;
     if (this.stopped && !this.socket) return Promise.resolve();
@@ -28541,27 +28705,29 @@ var OpenClawSupervisorClient = class {
     } catch {
     }
     const cliPath = this.supervisorCliPath ?? fileURLToPath(new URL("./openclaw-supervisor-cli.js", import.meta.url));
-    if (!existsSync(cliPath)) {
-      throw new Error(`OWNERSHIP_PRIMITIVE_UNAVAILABLE:supervisor CLI is missing at ${cliPath}`);
-    }
+    if (!this.spawnSupervisor && !existsSync(cliPath)) throw new Error(`OWNERSHIP_PRIMITIVE_UNAVAILABLE:supervisor CLI is missing at ${cliPath}`);
     const bootstrapPath = supervisorBootstrapPath(this.stateDir, this.ownerHash);
     try {
       unlinkSync(bootstrapPath);
     } catch {
     }
     let childExit;
-    const child = spawn(process.execPath, [cliPath, "--state-dir", this.stateDir, "--owner-key", this.ownerHash], {
-      detached: true,
-      stdio: "ignore",
-      env: { ...process.env }
-    });
-    child.once("error", (error) => {
-      childExit = `spawn error: ${error.message}`;
-    });
-    child.once("exit", (code, signal) => {
-      childExit = `exit code=${code ?? "null"} signal=${signal ?? "none"}`;
-    });
-    child.unref();
+    if (this.spawnSupervisor) {
+      await this.spawnSupervisor();
+    } else {
+      const child = spawn(process.execPath, [cliPath, "--state-dir", this.stateDir, "--owner-key", this.ownerHash], {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env }
+      });
+      child.once("error", (error) => {
+        childExit = `spawn error: ${error.message}`;
+      });
+      child.once("exit", (code, signal) => {
+        childExit = `exit code=${code ?? "null"} signal=${signal ?? "none"}`;
+      });
+      child.unref();
+    }
     const deadline = Date.now() + 1e4;
     let lastError;
     while (Date.now() < deadline) {
@@ -28692,10 +28858,10 @@ var OpenClawSupervisorClient = class {
 import { createHmac } from "node:crypto";
 import {
   chmodSync as chmodSync2,
-  mkdirSync as mkdirSync2,
+  mkdirSync as mkdirSync3,
   readFileSync as readFileSync4,
   renameSync as renameSync2,
-  writeFileSync as writeFileSync2
+  writeFileSync as writeFileSync3
 } from "node:fs";
 import { homedir as homedir4 } from "node:os";
 import { join as join3, resolve as resolve2 } from "node:path";
@@ -28754,10 +28920,10 @@ function recordRuntimeLoadEvidence(input) {
     bootId: currentBootId(),
     pluginRoot: resolve2(input.pluginRoot)
   };
-  mkdirSync2(evidenceDir, { recursive: true, mode: 448 });
+  mkdirSync3(evidenceDir, { recursive: true, mode: 448 });
   const target = runtimeStatusPath(input.stateDir);
   const temporary = `${target}.${process.pid}.tmp`;
-  writeFileSync2(temporary, `${JSON.stringify(status, null, 2)}
+  writeFileSync3(temporary, `${JSON.stringify(status, null, 2)}
 `, { mode: 384 });
   renameSync2(temporary, target);
   chmodSync2(target, 384);
@@ -29466,22 +29632,36 @@ function a2aLifecycleKey(config) {
   }
   const heartbeatUrl = config.platform?.heartbeatUrl || "";
   const idFromHeartbeat = heartbeatUrl.match(/\/agents\/([^/]+)\/heartbeat(?:\?|$)/u)?.[1];
-  const agentId = config.platform?.agentId || idFromHeartbeat || config.agentName.trim().toLowerCase();
+  const agentId = config.platform?.agentId || idFromHeartbeat || safeAgentName(config.agentName).toLowerCase();
   return `${relayUrl}|${agentId}`;
 }
-function register(api) {
-  const pluginConfig = api.config?.plugins?.entries?.["perkos-a2a"]?.config || {
-    agentName: "agent",
-    port: 5050,
-    skills: [],
-    peers: {}
+function safeAgentName(value) {
+  return typeof value === "string" && value.trim() ? value.trim() : "agent";
+}
+function normalizeOpenClawPluginConfig(value) {
+  const raw = value && typeof value === "object" && !Array.isArray(value) ? value : {};
+  const platform = raw.platform && typeof raw.platform === "object" ? raw.platform : void 0;
+  const heartbeatAgentId = platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u)?.[1];
+  const agentName = safeAgentName(raw.agentName || platform?.agentId || heartbeatAgentId);
+  return {
+    ...raw,
+    agentName,
+    port: typeof raw.port === "number" ? raw.port : 5050,
+    skills: Array.isArray(raw.skills) ? raw.skills : [],
+    peers: raw.peers && typeof raw.peers === "object" ? raw.peers : {}
   };
+}
+function register(api) {
+  const pluginConfig = normalizeOpenClawPluginConfig(
+    api.config?.plugins?.entries?.["perkos-a2a"]?.config
+  );
   const logger = api.logger || console;
   const pluginVersion = loadedPluginVersion();
+  const pluginRoot = resolve3(dirname3(fileURLToPath2(import.meta.url)), "..");
   recordRuntimeLoadEvidence({
     config: pluginConfig,
     version: pluginVersion,
-    pluginRoot: resolve3(dirname2(fileURLToPath2(import.meta.url)), ".."),
+    pluginRoot,
     logger
   });
   const server = new A2AServer(pluginConfig, logger, { relayOwnership: "external-required" });
@@ -29738,7 +29918,7 @@ function register(api) {
   if (pluginConfig.chat?.enabled && !chatApiKey) {
     logger.error("[perkos-chat] chat.enabled=true but no apiKey (set chat.apiKey or fall back from relay.apiKey)");
   }
-  const platformAgentId = pluginConfig.platform?.agentId || pluginConfig.platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u)?.[1] || pluginConfig.agentName.trim().toLowerCase();
+  const platformAgentId = pluginConfig.platform?.agentId || pluginConfig.platform?.heartbeatUrl?.match(/\/agents\/([^/]+)\/heartbeat/u)?.[1] || safeAgentName(pluginConfig.agentName).toLowerCase();
   supervisorClient = new OpenClawSupervisorClient({
     ownerHash: supervisorOwnerHash(lifecycleKey),
     generation: Date.now(),
@@ -29747,6 +29927,7 @@ function register(api) {
       agentName: pluginConfig.agentName,
       agentId: platformAgentId,
       version: pluginVersion,
+      installRoot: pluginRoot,
       relay: pluginConfig.relay,
       chat: chatEnabled ? {
         enabled: true,
@@ -30182,6 +30363,7 @@ export {
   extractOpenClawChatReply,
   formatRecentChatContext,
   isWebhookEvent,
+  normalizeOpenClawPluginConfig,
   omitUnavailableAgentHarness,
   openclawChatSessionKey,
   runOpenClawChatTurn