clawspec 1.0.1 → 1.0.3

package/README.md

@@ -236,7 +236,7 @@ Current OpenClaw builds do not accept raw GitHub URLs as ordinary plugin install
 
 If you want an unreleased commit before npm publish, clone the repository and install from the local checkout or a downloaded `.tgz` archive instead.
 
-### 2. Enable ACP and ACPX in OpenClaw
+### 2. Enable ACP in OpenClaw
 
 Example `~/.openclaw/openclaw.json`:
 
@@ -249,18 +249,10 @@ Example `~/.openclaw/openclaw.json`:
   },
   "plugins": {
     "entries": {
-      "acpx": {
-        "enabled": true,
-        "config": {
-          "permissionMode": "approve-all",
-          "expectedVersion": "any"
-        }
-      },
       "clawspec": {
         "enabled": true,
         "config": {
           "defaultWorkspace": "~/clawspec/workspace",
-          "workerAgentId": "codex",
           "openSpecTimeoutMs": 120000,
           "watcherPollIntervalMs": 4000
         }
@@ -273,21 +265,21 @@ Example `~/.openclaw/openclaw.json`:
 Important notes:
 
 - Recent OpenClaw builds often bundle `acpx` under the host install. ClawSpec checks that builtin copy before falling back to `acpx` on `PATH` or a plugin-local install.
-- If your OpenClaw build does not bundle `acpx`, install or load it separately before relying on `cs-work`.
-- ClawSpec itself does not ship its own ACP runtime backend.
-- When ACPX is unavailable, the watcher now reports a short recovery hint in chat telling the user to enable `plugins.entries.acpx` and backend `acpx`.
-- `acp.defaultAgent` is the OpenClaw ACP default. ClawSpec background workers use `plugins.entries.clawspec.config.workerAgentId` by default.
-- For ClawSpec worker selection, precedence is: `/clawspec worker <agent-id>` for the current channel/project, then `clawspec.config.workerAgentId`, then the built-in ClawSpec fallback.
-- In other words, ClawSpec does not currently inherit `acp.defaultAgent` automatically. If you want both to use the same agent, set both values explicitly.
+- If your OpenClaw build does not bundle `acpx`, ClawSpec can fall back to a plugin-local install automatically.
+- ClawSpec manages the `acpx` command path itself. You do not need to hardcode `plugins.entries.acpx.config.command`.
+- `acp.defaultAgent` is now the global default used by ClawSpec background workers.
+- `/clawspec worker <agent-id>` is still available as an explicit channel/project override.
+- When ACP setup is incomplete, ClawSpec now shows ready-to-run commands such as `openclaw config set acp.backend acpx` and `openclaw config set acp.defaultAgent codex`.
 
 ### 2.5. Choose the default worker agent
 
-ClawSpec can run background work with different ACP agents such as `codex` or `claude`, but there are two separate defaults to understand:
+ClawSpec can run background work with different ACP agents such as `codex` or `claude`.
+There is now one global default source plus an optional per-channel override:
 
-- `acp.defaultAgent`: the OpenClaw ACP default used by the host ACP system
-- `plugins.entries.clawspec.config.workerAgentId`: the ClawSpec default used by `cs-work`
+- `acp.defaultAgent`: the OpenClaw ACP default used by ClawSpec workers
+- `/clawspec worker <agent-id>`: an explicit override persisted for the current channel/project context
 
-Recommended if you want both layers aligned:
+Recommended global setup:
 
 ```json
 {
@@ -295,16 +287,6 @@ Recommended if you want both layers aligned:
     "enabled": true,
     "backend": "acpx",
     "defaultAgent": "claude"
-  },
-  "plugins": {
-    "entries": {
-      "clawspec": {
-        "enabled": true,
-        "config": {
-          "workerAgentId": "claude"
-        }
-      }
-    }
   }
 }
 ```
@@ -320,7 +302,7 @@ Notes:
 
 - `/clawspec worker <agent-id>` is persisted at the current channel/project scope
 - the chosen agent must exist in your OpenClaw agent list or ACP allowlist
-- if you want a global default, set `workerAgentId` in OpenClaw config
+- if you want a global default, set `acp.defaultAgent` in OpenClaw config
 - if you want a one-off override for the active project conversation, use `/clawspec worker <agent-id>`
 
 ### 2.6. ClawSpec plugin config reference
@@ -330,7 +312,6 @@ Common `plugins.entries.clawspec.config` fields:
 | Key | Purpose | Notes |
 | --- | --- | --- |
 | `defaultWorkspace` | Default base directory used by `/clawspec workspace` and `/clawspec use` | Channel-specific workspace selection overrides this after first use |
-| `workerAgentId` | Default ACP agent used by background workers | Can be overridden per channel/project with `/clawspec worker <agent-id>` |
 | `openSpecTimeoutMs` | Timeout for each OpenSpec CLI invocation | Increase this if your repo or host is slow |
 | `watcherPollIntervalMs` | Background watcher recovery poll interval | Controls how quickly recovery scans and replay checks run |
 | `archiveDirName` | Directory name under `.openclaw/clawspec/` for archived bundles | Keep the default unless you need a different archive layout |
@@ -340,6 +321,7 @@ Backward-compatibility keys still accepted but currently treated as no-ops:
 
 - `maxAutoContinueTurns`
 - `maxNoProgressTurns`
+- `workerAgentId`
 - `workerBackendId`
 - `workerWaitTimeoutMs`
 - `subagentLane`
@@ -823,16 +805,15 @@ Cause:
 
 - `acp.enabled` is false
 - `acp.backend` is not `acpx`
-- `plugins.entries.acpx.enabled` is false
-- your OpenClaw build does not bundle `acpx` and it was never installed/loaded
+- `acp.defaultAgent` is missing
+- your OpenClaw build does not bundle `acpx` and ClawSpec could not find or install a usable copy
 
 What to do:
 
-1. enable ACP
-2. set backend to `acpx`
-3. enable `plugins.entries.acpx`
-4. if your host does not bundle ACPX, install/load it first
-5. rerun `cs-work` or `/clawspec continue`
+1. run `openclaw config set acp.backend acpx`
+2. run `openclaw config set acp.defaultAgent codex`
+3. if your host does not bundle ACPX, let ClawSpec install a plugin-local copy or install `acpx` manually
+4. rerun `cs-work` or `/clawspec continue`
 
 ### Ordinary chat is polluting the planning journal
 

package/README.zh-CN.md

@@ -241,7 +241,7 @@ openclaw plugins install clawspec@latest
 
 如果你要安装一个还没发布到 npm 的提交，请改用本地 checkout 或下载好的 `.tgz` 包安装。
 
-### 2. 在 OpenClaw 里启用 ACP 和 ACPX
+### 2. 在 OpenClaw 里启用 ACP
 
 示例 `~/.openclaw/openclaw.json`：
 
@@ -254,18 +254,10 @@ openclaw plugins install clawspec@latest
   },
   "plugins": {
     "entries": {
-      "acpx": {
-        "enabled": true,
-        "config": {
-          "permissionMode": "approve-all",
-          "expectedVersion": "any"
-        }
-      },
       "clawspec": {
         "enabled": true,
         "config": {
           "defaultWorkspace": "~/clawspec/workspace",
-          "workerAgentId": "codex",
           "openSpecTimeoutMs": 120000,
           "watcherPollIntervalMs": 4000
         }
@@ -278,21 +270,20 @@ openclaw plugins install clawspec@latest
 这里要注意：
 
 - 新版 OpenClaw 往往已经自带 `acpx`，ClawSpec 现在会先检查这份 builtin ACPX，再回退到系统 `PATH` 或插件本地安装。
-- 如果你的 OpenClaw 没有自带 `acpx`，那就要先单独安装或加载 `acpx`。
-- ClawSpec 自己不携带 ACP runtime backend。
-- 当 ACPX 不可用时，watcher 会在聊天里发一条简短提示，告诉用户去启用 `plugins.entries.acpx` 和 backend `acpx`。
-- `acp.defaultAgent` 是 OpenClaw 自己的 ACP 默认 agent；ClawSpec 的后台 worker 默认看的是 `plugins.entries.clawspec.config.workerAgentId`。
-- 对 ClawSpec 来说，worker 选择优先级是：当前 channel/project 上的 `/clawspec worker <agent-id>` 覆盖，其次是 `clawspec.config.workerAgentId`，最后才是 ClawSpec 自己的内置默认值。
-- 也就是说，ClawSpec 现在不会自动继承 `acp.defaultAgent`。如果你希望两边都用同一个 agent，需要把两处都显式配成一样。
+- 如果你的 OpenClaw 没有自带 `acpx`，ClawSpec 会优先尝试自动落一份插件本地可用的 `acpx`。
+- `acpx` 的命令路径现在由 ClawSpec 自己管理，不需要你再手工写 `plugins.entries.acpx.config.command`。
+- `acp.defaultAgent` 现在就是 ClawSpec 后台 worker 的全局默认 agent。
+- `/clawspec worker <agent-id>` 仍然可以作为当前 channel/project 的显式覆盖。
+- 如果 ACP 配置不完整，ClawSpec 会直接提示可执行命令，比如 `openclaw config set acp.backend acpx` 和 `openclaw config set acp.defaultAgent codex`。
 
 ### 2.5. 选择默认 worker agent
 
-ClawSpec 可以让后台任务跑在不同的 ACP agent 上，比如 `codex` 或 `claude`，但这里有两个“默认值”要区分：
+ClawSpec 可以让后台任务跑在不同的 ACP agent 上，比如 `codex` 或 `claude`。现在默认值来源只有一层，再加一个可选覆盖：
 
-- `acp.defaultAgent`：OpenClaw 自己 ACP 系统的默认 agent
-- `plugins.entries.clawspec.config.workerAgentId`：ClawSpec 执行 `cs-work` 时使用的默认 worker agent
+- `acp.defaultAgent`：ClawSpec 后台 worker 读取的全局默认 ACP agent
+- `/clawspec worker <agent-id>`：当前 channel/project 的显式覆盖
 
-如果你希望两层都统一成同一个 agent，建议同时这样配置：
+推荐的全局配置：
 
 ```json
 {
@@ -300,16 +291,6 @@ ClawSpec 可以让后台任务跑在不同的 ACP agent 上，比如 `codex` 或
     "enabled": true,
     "backend": "acpx",
     "defaultAgent": "claude"
-  },
-  "plugins": {
-    "entries": {
-      "clawspec": {
-        "enabled": true,
-        "config": {
-          "workerAgentId": "claude"
-        }
-      }
-    }
   }
 }
 ```
@@ -325,7 +306,7 @@ ClawSpec 可以让后台任务跑在不同的 ACP agent 上，比如 `codex` 或
 
 - `/clawspec worker <agent-id>` 的覆盖范围是当前 channel/project
 - 你填写的 agent id 必须已经存在于 OpenClaw 的 agent 列表或 ACP allowlist 中
-- 如果你想配置“全局默认”，改的是 `clawspec.config.workerAgentId`
+- 如果你想配置“全局默认”，改的是 `acp.defaultAgent`
 - 如果你想临时对当前项目改用另一个 agent，就直接执行 `/clawspec worker <agent-id>`
 
 ### 2.6. ClawSpec 插件配置项参考
@@ -335,7 +316,6 @@ ClawSpec 可以让后台任务跑在不同的 ACP agent 上，比如 `codex` 或
 | Key | 用途 | 说明 |
 | --- | --- | --- |
 | `defaultWorkspace` | `/clawspec workspace` 和 `/clawspec use` 的默认 workspace | 某个 channel 第一次选定 workspace 后，会优先使用该 channel 自己记住的值 |
-| `workerAgentId` | 后台 worker 默认使用的 ACP agent | 可以被 `/clawspec worker <agent-id>` 在当前 channel/project 覆盖 |
 | `openSpecTimeoutMs` | 每次 OpenSpec CLI 调用的超时时间 | repo 较大或主机较慢时可以调大 |
 | `watcherPollIntervalMs` | watcher 的后台恢复扫描周期 | 影响恢复检查和进度补发的灵敏度 |
 | `archiveDirName` | `.openclaw/clawspec/` 下归档目录名称 | 除非你要调整归档布局，否则保持默认即可 |
@@ -345,6 +325,7 @@ ClawSpec 可以让后台任务跑在不同的 ACP agent 上，比如 `codex` 或
 
 - `maxAutoContinueTurns`
 - `maxNoProgressTurns`
+- `workerAgentId`
 - `workerBackendId`
 - `workerWaitTimeoutMs`
 - `subagentLane`
@@ -835,16 +816,15 @@ OpenSpec change 本身仍然放在标准目录：
 
 - `acp.enabled` 没开
 - `acp.backend` 不是 `acpx`
-- `plugins.entries.acpx.enabled` 没开
-- 你的 OpenClaw 没有自带 ACPX，也没有单独安装/加载
+- `acp.defaultAgent` 没配
+- 你的 OpenClaw 没有自带 ACPX，且 ClawSpec 也没能找到或安装可用副本
 
 处理方式：
 
-1. 打开 ACP
-2. 把 backend 设成 `acpx`
-3. 启用 `plugins.entries.acpx`
-4. 如果宿主没自带 ACPX，就先安装或加载它
-5. 再运行 `cs-work` 或 `/clawspec continue`
+1. 运行 `openclaw config set acp.backend acpx`
+2. 运行 `openclaw config set acp.defaultAgent codex`
+3. 如果宿主没自带 ACPX，就让 ClawSpec 自动安装插件本地副本，或手工安装 `acpx`
+4. 再运行 `cs-work` 或 `/clawspec continue`
 
 ### 普通聊天污染了 planning journal
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawspec",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "type": "module",
   "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
   "keywords": [
@@ -43,7 +43,7 @@
   "scripts": {
     "check": "node --experimental-strip-types -e \"import('./index.ts')\"",
     "test": "node --experimental-strip-types --test --test-reporter spec test/*.test.ts",
-    "test:fast": "node --experimental-strip-types --test --test-reporter spec test/acp-client.test.ts test/acpx-dependency.test.ts test/assistant-journal.test.ts test/command-surface.test.ts test/config.test.ts test/detach-attach.test.ts test/file-lock.test.ts test/fs-utils.test.ts test/helpers.test.ts test/keywords.test.ts test/notifier.test.ts test/openspec-dependency.test.ts test/pause-cancel.test.ts test/planning-journal.test.ts test/plugin-registration.test.ts test/project-memory.test.ts test/proposal.test.ts test/queue-planning.test.ts test/queue-work.test.ts test/service-archive.test.ts test/shell-command.test.ts test/state-store.test.ts test/tasks-and-checkpoint.test.ts test/use-project.test.ts test/worker-command.test.ts test/worker-skills.test.ts",
+    "test:fast": "node --experimental-strip-types --test --test-reporter spec test/acp-client.test.ts test/acpx-dependency.test.ts test/assistant-journal.test.ts test/command-surface.test.ts test/config.test.ts test/detach-attach.test.ts test/file-lock.test.ts test/fs-utils.test.ts test/helpers.test.ts test/keywords.test.ts test/notifier.test.ts test/openspec-dependency.test.ts test/pause-cancel.test.ts test/planning-journal.test.ts test/plugin-registration.test.ts test/project-memory.test.ts test/proposal.test.ts test/queue-planning.test.ts test/queue-work.test.ts test/service-archive.test.ts test/shell-command.test.ts test/state-store.test.ts test/tasks-and-checkpoint.test.ts test/use-project.test.ts test/worker-command.test.ts test/worker-io-helper.test.ts test/worker-skills.test.ts",
     "test:slow": "node --experimental-strip-types --test --test-reporter spec test/watcher-planning.test.ts test/watcher-work.test.ts test/recovery.test.ts"
   },
   "engines": {

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/acp/openclaw-config.ts

@@ -0,0 +1,66 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+type ConfigLike = OpenClawConfig | Record<string, unknown> | undefined;
+
+export function getConfiguredDefaultWorkerAgent(config: ConfigLike): string | undefined {
+  const acp = getAcpConfig(config);
+  return asOptionalString(acp?.defaultAgent);
+}
+
+export function listConfiguredWorkerAgents(config: ConfigLike): string[] {
+  const acp = getAcpConfig(config);
+  const allowed = Array.isArray(acp?.allowedAgents)
+    ? acp.allowedAgents.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+  const agentsConfig = getAgentsConfig(config);
+  const listed = Array.isArray(agentsConfig?.list)
+    ? agentsConfig.list
+      .map((entry) => (entry && typeof entry === "object" ? (entry as Record<string, unknown>).id : undefined))
+      .filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+    : [];
+  const defaultAgent = getConfiguredDefaultWorkerAgent(config);
+  return Array.from(new Set([
+    ...(defaultAgent ? [defaultAgent] : []),
+    ...allowed,
+    ...listed,
+  ])).sort((left, right) => left.localeCompare(right));
+}
+
+export function buildWorkerAgentSetupHint(action: "plan" | "work"): string {
+  const rerunCommand = action === "plan" ? "`cs-plan`" : "`cs-work`";
+  return `Run \`openclaw config set acp.defaultAgent codex\`, then rerun ${rerunCommand}.`;
+}
+
+export function buildWorkerAgentSetupMessage(action: "plan" | "work"): string {
+  const rerunCommand = action === "plan" ? "`cs-plan`" : "`cs-work`";
+  const scope = action === "plan" ? "planning" : "workers";
+  return [
+    `OpenClaw ACP is not configured for ClawSpec ${scope}.`,
+    "Run:",
+    "- `openclaw config set acp.backend acpx`",
+    "- `openclaw config set acp.defaultAgent codex`",
+    `Then rerun ${rerunCommand}. Replace \`codex\` with another ACP agent id if needed.`,
+  ].join("\n");
+}
+
+function getAcpConfig(config: ConfigLike): Record<string, unknown> | undefined {
+  const record = asRecord(config);
+  return record?.acp && typeof record.acp === "object"
+    ? record.acp as Record<string, unknown>
+    : undefined;
+}
+
+function getAgentsConfig(config: ConfigLike): Record<string, unknown> | undefined {
+  const record = asRecord(config);
+  return record?.agents && typeof record.agents === "object"
+    ? record.agents as Record<string, unknown>
+    : undefined;
+}
+
+function asRecord(value: ConfigLike): Record<string, unknown> | undefined {
+  return value && typeof value === "object" ? value as Record<string, unknown> : undefined;
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}

package/src/config.ts

@@ -11,7 +11,7 @@ export type ClawSpecPluginConfig = {
   maxAutoContinueTurns: number;
   maxNoProgressTurns: number;
   workerWaitTimeoutMs: number;
-  workerAgentId: string;
+  workerAgentId?: string;
   workerBackendId?: string;
   watcherPollIntervalMs: number;
   subagentLane?: string;
@@ -105,8 +105,8 @@ export const clawspecPluginConfigSchema: OpenClawPluginConfigSchema = {
       advanced: true,
     },
     workerAgentId: {
-      label: "Worker Agent",
-      help: "Agent id used for background ACP planning and implementation turns",
+      label: "Deprecated Worker Agent",
+      help: "Deprecated no-op. Configure `acp.defaultAgent` in OpenClaw instead.",
       advanced: true,
     },
     workerBackendId: {
@@ -142,7 +142,6 @@ const DEFAULT_CONFIG: ClawSpecPluginConfig = {
   maxNoProgressTurns: 2,
   openSpecTimeoutMs: 120_000,
   workerWaitTimeoutMs: 300_000,
-  workerAgentId: "codex",
   watcherPollIntervalMs: 4_000,
   archiveDirName: "archives",
   defaultWorkspace: getDefaultWorkspacePath(),
@@ -181,7 +180,7 @@ export function parsePluginConfig(
       10_000,
       3_600_000,
     ),
-    workerAgentId: asOptionalString(config.workerAgentId) ?? DEFAULT_CONFIG.workerAgentId,
+    workerAgentId: asOptionalString(config.workerAgentId),
     workerBackendId: asOptionalString(config.workerBackendId),
     watcherPollIntervalMs: asInt(
       config.watcherPollIntervalMs,