clawspec 1.0.2 → 1.0.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawspec",
-  "version": "1.0.2",
+  "version": "1.0.4",
   "type": "module",
   "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
   "keywords": [
@@ -32,7 +32,10 @@
   "openclaw": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.3.24"
+    }
   },
   "peerDependencies": {
     "openclaw": ">=0.0.0"

package/src/acp/client.ts

@@ -1,5 +1,5 @@
+import { spawn, type ChildProcess, type ChildProcessWithoutNullStreams } from "node:child_process";
 import { createInterface } from "node:readline";
-import type { ChildProcessWithoutNullStreams } from "node:child_process";
 import type { PluginLogger } from "openclaw/plugin-sdk";
 import { runShellCommand, spawnShellCommand, terminateChildProcess } from "../utils/shell-command.ts";
 
@@ -54,6 +54,8 @@ type AcpWorkerClientOptions = {
   env?: NodeJS.ProcessEnv;
   permissionMode?: "approve-all" | "approve-reads" | "deny-all";
   queueOwnerTtlSeconds?: number;
+  gatewayPid?: number;
+  gatewayWatchdogPollMs?: number;
 };
 
 type EnsureSessionParams = {
@@ -81,6 +83,7 @@ type SessionDescriptor = {
 type ActiveSessionProcess = {
   sessionKey: string;
   child: ChildProcessWithoutNullStreams;
+  watchdog?: ChildProcess;
   cwd: string;
   agentId: string;
   startedAt: string;
@@ -93,6 +96,7 @@ type SessionExitState = {
 
 const DEFAULT_QUEUE_OWNER_TTL_SECONDS = 30;
 const DEFAULT_PERMISSION_MODE = "approve-all";
+const DEFAULT_GATEWAY_WATCHDOG_POLL_MS = 1_000;
 
 export class AcpWorkerClient {
   readonly agentId: string;
@@ -101,6 +105,8 @@ export class AcpWorkerClient {
   readonly env?: NodeJS.ProcessEnv;
   readonly permissionMode: "approve-all" | "approve-reads" | "deny-all";
   readonly queueOwnerTtlSeconds: number;
+  readonly gatewayPid: number;
+  readonly gatewayWatchdogPollMs: number;
   readonly handles = new Map<string, AcpWorkerHandle>();
   readonly sessionDescriptors = new Map<string, SessionDescriptor>();
   readonly activeProcesses = new Map<string, ActiveSessionProcess>();
@@ -113,6 +119,8 @@ export class AcpWorkerClient {
     this.env = options.env;
     this.permissionMode = options.permissionMode ?? DEFAULT_PERMISSION_MODE;
     this.queueOwnerTtlSeconds = options.queueOwnerTtlSeconds ?? DEFAULT_QUEUE_OWNER_TTL_SECONDS;
+    this.gatewayPid = normalizePid(options.gatewayPid) ?? process.pid;
+    this.gatewayWatchdogPollMs = normalizeWatchdogPollMs(options.gatewayWatchdogPollMs);
   }
 
   async ensureSession(params: EnsureSessionParams): Promise<{
@@ -183,9 +191,11 @@ export class AcpWorkerClient {
     child.stdin.end(params.text);
 
     const startedAt = new Date().toISOString();
+    const watchdog = this.startGatewayWatchdog(params.sessionKey, child);
     this.activeProcesses.set(params.sessionKey, {
       sessionKey: params.sessionKey,
       child,
+      watchdog,
       cwd: descriptor.cwd,
       agentId: descriptor.agentId,
       startedAt,
@@ -243,14 +253,21 @@ export class AcpWorkerClient {
       if (exit.error) {
         throw exit.error;
       }
+      if (exit.signal && !sawError) {
+        throw new Error(formatAcpxExitMessage(stderr, exit.code, exit.signal));
+      }
       if ((exit.code ?? 0) !== 0 && !sawError) {
-        throw new Error(formatAcpxExitMessage(stderr, exit.code));
+        throw new Error(formatAcpxExitMessage(stderr, exit.code, exit.signal));
       }
       if (!sawDone && !sawError) {
         await params.onEvent?.({ type: "done" });
       }
       return ensured;
     } finally {
+      const active = this.activeProcesses.get(params.sessionKey);
+      if (active?.watchdog) {
+        safeKill(active.watchdog);
+      }
       this.activeProcesses.delete(params.sessionKey);
       lines.close();
       if (params.signal) {
@@ -360,6 +377,7 @@ export class AcpWorkerClient {
 
     const active = this.activeProcesses.get(sessionKey);
     if (active) {
+      safeKill(active.watchdog);
       safeKill(active.child);
       this.activeProcesses.delete(sessionKey);
       this.recordSessionExit(sessionKey, active, active.child.pid, null, "SIGTERM", reason);
@@ -385,6 +403,7 @@ export class AcpWorkerClient {
 
     const active = this.activeProcesses.get(sessionKey);
     if (active) {
+      safeKill(active.watchdog);
       safeKill(active.child);
       this.activeProcesses.delete(sessionKey);
       this.recordSessionExit(sessionKey, active, active.child.pid, null, "SIGTERM", reason);
@@ -513,6 +532,40 @@ export class AcpWorkerClient {
       `[clawspec] acpx worker exited: session=${sessionKey} pid=${pid ?? "unknown"} code=${code ?? "null"} signal=${signal ?? "null"}`,
     );
   }
+
+  private startGatewayWatchdog(
+    sessionKey: string,
+    child: ChildProcessWithoutNullStreams,
+  ): ChildProcess | undefined {
+    const workerPid = normalizePid(child.pid);
+    if (!workerPid) {
+      return undefined;
+    }
+
+    try {
+      const watchdog = spawn(process.execPath, [
+        "-e",
+        GATEWAY_WATCHDOG_SOURCE,
+        String(this.gatewayPid),
+        String(workerPid),
+        String(this.gatewayWatchdogPollMs),
+      ], {
+        stdio: "ignore",
+        windowsHide: true,
+        detached: true,
+      });
+      watchdog.unref();
+      this.logger.debug?.(
+        `[clawspec] gateway watchdog armed: session=${sessionKey} gatewayPid=${this.gatewayPid} workerPid=${workerPid}`,
+      );
+      return watchdog;
+    } catch (error) {
+      this.logger.warn(
+        `[clawspec] failed to start gateway watchdog for ${sessionKey}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+      return undefined;
+    }
+  }
 }
 
 function parseJsonLines(value: string): Array<Record<string, unknown>> {
@@ -660,7 +713,10 @@ async function waitForExit(child: ChildProcessWithoutNullStreams): Promise<{
   });
 }
 
-function safeKill(child: ChildProcessWithoutNullStreams): void {
+function safeKill(child: Pick<ChildProcess, "pid" | "killed" | "kill"> | undefined): void {
+  if (!child) {
+    return;
+  }
   terminateChildProcess(child);
 }
 
@@ -674,9 +730,19 @@ function buildPermissionArgs(mode: "approve-all" | "approve-reads" | "deny-all")
   return ["--approve-all"];
 }
 
-function formatAcpxExitMessage(stderr: string, exitCode: number | null | undefined): string {
+function formatAcpxExitMessage(
+  stderr: string,
+  exitCode: number | null | undefined,
+  signal?: NodeJS.Signals | null,
+): string {
   const detail = stderr.trim();
-  return detail || `acpx exited with code ${exitCode ?? "unknown"}`;
+  if (detail) {
+    return detail;
+  }
+  if (signal) {
+    return `acpx terminated by signal ${signal}`;
+  }
+  return `acpx exited with code ${exitCode ?? "unknown"}`;
 }
 
 function asTrimmedString(value: unknown): string {
@@ -691,3 +757,103 @@ function asOptionalString(value: unknown): string | undefined {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+
+function normalizePid(value: number | undefined): number | undefined {
+  return typeof value === "number" && Number.isFinite(value) && value > 0
+    ? Math.trunc(value)
+    : undefined;
+}
+
+function normalizeWatchdogPollMs(value: number | undefined): number {
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 50) {
+    return DEFAULT_GATEWAY_WATCHDOG_POLL_MS;
+  }
+  return Math.trunc(value);
+}
+
+const GATEWAY_WATCHDOG_SOURCE = String.raw`
+const { spawn } = require("node:child_process");
+
+const gatewayPid = Number(process.argv[1]);
+const workerPid = Number(process.argv[2]);
+const pollMs = Number(process.argv[3]);
+
+function normalizePid(value) {
+  return Number.isFinite(value) && value > 0 ? Math.trunc(value) : undefined;
+}
+
+function isAlive(pid) {
+  const normalized = normalizePid(pid);
+  if (!normalized) {
+    return false;
+  }
+  try {
+    process.kill(normalized, 0);
+    return true;
+  } catch (error) {
+    const code = error && typeof error === "object" ? error.code : undefined;
+    return code === "EPERM";
+  }
+}
+
+function killWorkerTree(pid) {
+  const normalized = normalizePid(pid);
+  if (!normalized) {
+    return;
+  }
+  if (process.platform === "win32") {
+    try {
+      const killer = spawn("taskkill", ["/PID", String(normalized), "/T", "/F"], {
+        stdio: "ignore",
+        windowsHide: true,
+        detached: true,
+      });
+      killer.unref();
+    } catch {}
+    return;
+  }
+  try {
+    process.kill(-normalized, "SIGTERM");
+  } catch {
+    try {
+      process.kill(normalized, "SIGTERM");
+    } catch {}
+  }
+  const escalator = setTimeout(() => {
+    try {
+      process.kill(-normalized, "SIGKILL");
+    } catch {
+      try {
+        process.kill(normalized, "SIGKILL");
+      } catch {}
+    }
+  }, 1000);
+  escalator.unref?.();
+}
+
+const safeGatewayPid = normalizePid(gatewayPid);
+const safeWorkerPid = normalizePid(workerPid);
+const safePollMs = Number.isFinite(pollMs) && pollMs >= 50 ? Math.trunc(pollMs) : 1000;
+
+if (!safeGatewayPid || !safeWorkerPid) {
+  process.exit(0);
+}
+
+if (!isAlive(safeWorkerPid)) {
+  process.exit(0);
+}
+
+const timer = setInterval(() => {
+  if (!isAlive(safeWorkerPid)) {
+    clearInterval(timer);
+    process.exit(0);
+    return;
+  }
+  if (!isAlive(safeGatewayPid)) {
+    clearInterval(timer);
+    killWorkerTree(safeWorkerPid);
+    const exitTimer = setTimeout(() => process.exit(0), 250);
+    exitTimer.unref?.();
+  }
+}, safePollMs);
+`;

package/src/dependencies/acpx.ts

@@ -178,10 +178,10 @@ async function checkAcpxVersion(
       message: "acpx --version did not return a parseable version",
     };
   }
-  if (version !== params.expectedVersion) {
+  if (compareSemver(version, params.expectedVersion) < 0) {
     return {
       ok: false,
-      message: `acpx version mismatch: found ${version}, expected ${params.expectedVersion}`,
+      message: `acpx version too old: found ${version}, require >= ${params.expectedVersion}`,
     };
   }
   return { ok: true, version };
@@ -219,3 +219,77 @@ function getBuiltInAcpxCommand(runtimeEntrypoint: string | undefined): string |
     process.platform === "win32" ? "acpx.cmd" : "acpx",
   );
 }
+
+function compareSemver(left: string, right: string): number {
+  const parsedLeft = parseSemver(left);
+  const parsedRight = parseSemver(right);
+  if (!parsedLeft || !parsedRight) {
+    return left.localeCompare(right);
+  }
+
+  for (let index = 0; index < 3; index += 1) {
+    const delta = parsedLeft.core[index] - parsedRight.core[index];
+    if (delta !== 0) {
+      return delta;
+    }
+  }
+
+  const leftPre = parsedLeft.prerelease;
+  const rightPre = parsedRight.prerelease;
+  if (leftPre.length === 0 && rightPre.length === 0) {
+    return 0;
+  }
+  if (leftPre.length === 0) {
+    return 1;
+  }
+  if (rightPre.length === 0) {
+    return -1;
+  }
+
+  const maxLength = Math.max(leftPre.length, rightPre.length);
+  for (let index = 0; index < maxLength; index += 1) {
+    const leftToken = leftPre[index];
+    const rightToken = rightPre[index];
+    if (leftToken === undefined) {
+      return -1;
+    }
+    if (rightToken === undefined) {
+      return 1;
+    }
+    const delta = comparePrereleaseToken(leftToken, rightToken);
+    if (delta !== 0) {
+      return delta;
+    }
+  }
+  return 0;
+}
+
+function parseSemver(value: string): { core: [number, number, number]; prerelease: string[] } | null {
+  const match = value.trim().match(/^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/);
+  if (!match) {
+    return null;
+  }
+  return {
+    core: [
+      Number.parseInt(match[1]!, 10),
+      Number.parseInt(match[2]!, 10),
+      Number.parseInt(match[3]!, 10),
+    ],
+    prerelease: match[4] ? match[4].split(".") : [],
+  };
+}
+
+function comparePrereleaseToken(left: string, right: string): number {
+  const leftNumeric = /^\d+$/.test(left);
+  const rightNumeric = /^\d+$/.test(right);
+  if (leftNumeric && rightNumeric) {
+    return Number.parseInt(left, 10) - Number.parseInt(right, 10);
+  }
+  if (leftNumeric) {
+    return -1;
+  }
+  if (rightNumeric) {
+    return 1;
+  }
+  return left.localeCompare(right);
+}

package/test/acp-client.test.ts

@@ -2,8 +2,10 @@ import test from "node:test";
 import assert from "node:assert/strict";
 import os from "node:os";
 import path from "node:path";
+import { spawn } from "node:child_process";
 import { chmod, mkdtemp, writeFile } from "node:fs/promises";
 import { AcpWorkerClient } from "../src/acp/client.ts";
+import { terminateChildProcess } from "../src/utils/shell-command.ts";
 
 test("AcpWorkerClient tracks active worker lifecycle through acpx CLI", async () => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-acpx-client-"));
@@ -46,6 +48,63 @@ test("AcpWorkerClient tracks active worker lifecycle through acpx CLI", async ()
   assert.match(finalStatus?.summary ?? "", /status=dead/);
 });
 
+test("AcpWorkerClient stops the worker when the gateway process disappears", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-acpx-watchdog-"));
+  const fake = await createFakeAcpx(tempRoot);
+  const gateway = spawn(process.execPath, ["-e", "setInterval(() => {}, 1000)"], {
+    stdio: "ignore",
+    windowsHide: true,
+    detached: true,
+  });
+  gateway.unref();
+  const client = new AcpWorkerClient({
+    agentId: "codex",
+    logger: createLogger(),
+    command: fake.command,
+    env: fake.env,
+    gatewayPid: gateway.pid,
+    gatewayWatchdogPollMs: 50,
+  });
+
+  const startedAt = Date.now();
+  let sawStarted = false;
+  const runPromise = client.runTurn({
+    sessionKey: "session-watchdog",
+    cwd: tempRoot,
+    text: "stay alive",
+    onEvent: async (event) => {
+      if (event.type === "text_delta" && event.text?.includes("Working on stay alive")) {
+        sawStarted = true;
+      }
+    },
+  });
+  const observedRunPromise = runPromise.catch((error) => {
+    throw error;
+  });
+
+  try {
+    await waitFor(async () => sawStarted === true);
+
+    terminateChildProcess(gateway, { force: true });
+
+    await assert.rejects(
+      observedRunPromise,
+      /acpx exited with code|signal=SIGTERM|terminated/i,
+    );
+  } finally {
+    terminateChildProcess(gateway, { force: true });
+    await observedRunPromise.catch(() => undefined);
+  }
+
+  assert.ok(Date.now() - startedAt < 4_000, "watchdog should stop the worker quickly");
+  const finalStatus = await client.getSessionStatus({
+    sessionKey: "session-watchdog",
+    cwd: tempRoot,
+    agentId: "codex",
+  });
+  assert.match(finalStatus?.summary ?? "", /status=dead/);
+});
+
 async function createFakeAcpx(tempRoot: string): Promise<{ command: string; env: NodeJS.ProcessEnv }> {
   const scriptPath = path.join(tempRoot, "fake-acpx.js");
   const wrapperPath = path.join(tempRoot, process.platform === "win32" ? "fake-acpx.cmd" : "fake-acpx");
@@ -93,6 +152,18 @@ async function readStdin() {
   return Buffer.concat(chunks).toString("utf8");
 }
 
+function isAlive(pid) {
+  if (!Number.isFinite(pid) || pid <= 0) {
+    return false;
+  }
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return error && typeof error === "object" && error.code === "EPERM";
+  }
+}
+
 async function writeJsonLine(value) {
   process.stdout.write(JSON.stringify(value) + "\\n");
 }
@@ -122,8 +193,8 @@ async function main() {
 
   async function runningExists() {
     try {
-      await fs.access(runningFile);
-      return true;
+      const payload = JSON.parse(await fs.readFile(runningFile, "utf8"));
+      return isAlive(payload && payload.pid);
     } catch {
       return false;
     }
@@ -167,13 +238,17 @@ async function main() {
 
   if (verb === "prompt") {
     const text = (await readStdin()).trim();
-    await fs.writeFile(runningFile, "running", "utf8");
+    await fs.writeFile(runningFile, JSON.stringify({ pid: process.pid }), "utf8");
     process.on("SIGTERM", async () => {
       await fs.rm(runningFile, { force: true });
       process.exit(143);
     });
     await new Promise((resolve) => setTimeout(resolve, 60));
     await writeJsonLine({ text: "Working on " + text });
+    if (sessionName === "session-watchdog" || text.includes("stay alive")) {
+      setInterval(() => {}, 1_000);
+      return;
+    }
     await new Promise((resolve) => setTimeout(resolve, 80));
     await fs.rm(runningFile, { force: true });
     await writeJsonLine({ type: "done" });

package/test/acpx-dependency.test.ts

@@ -52,6 +52,27 @@ test("ensureAcpxCli uses the global acpx command when available", async () => {
   assert.equal(calls.some((call) => call.command === "npm"), false);
 });
 
+test("ensureAcpxCli accepts a newer global acpx version", async () => {
+  const calls: Array<{ command: string; args: string[] }> = [];
+  const result = await ensureAcpxCli({
+    pluginRoot: ROOT_PREFIX,
+    runner: async ({ command, args }) => {
+      calls.push({ command, args });
+      if (command === LOCAL_COMMAND) {
+        return { code: 1, stdout: "", stderr: "not found" };
+      }
+      if (command === "acpx") {
+        return { code: 0, stdout: "0.3.2\n", stderr: "" };
+      }
+      return { code: 1, stdout: "", stderr: "unexpected command" };
+    },
+  });
+
+  assert.equal(result.source, "global");
+  assert.equal(result.version, "0.3.2");
+  assert.equal(calls.some((call) => call.command === "npm"), false);
+});
+
 test("ensureAcpxCli prefers the OpenClaw builtin acpx over an incompatible PATH acpx", async () => {
   const calls: Array<{ command: string; args: string[] }> = [];
   const result = await ensureAcpxCli({