clawspec 1.0.1 → 1.0.2

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.2",
   "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/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,

package/src/index.ts

@@ -18,6 +18,7 @@ import { ClawSpecNotifier } from "./watchers/notifier.ts";
 import { WatcherManager } from "./watchers/manager.ts";
 import { ensureOpenSpecCli } from "./dependencies/openspec.ts";
 import { ensureAcpxCli } from "./dependencies/acpx.ts";
+import { getConfiguredDefaultWorkerAgent } from "./acp/openclaw-config.ts";
 
 const PLUGIN_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
 const LOCAL_BIN_DIR = path.join(PLUGIN_ROOT, "node_modules", ".bin");
@@ -71,8 +72,9 @@ const plugin = {
           pluginRoot: PLUGIN_ROOT,
           logger: api.logger,
         });
+        const configuredDefaultWorkerAgent = getConfiguredDefaultWorkerAgent(api.config) ?? "codex";
         const acpClient = new AcpWorkerClient({
-          agentId: config.workerAgentId,
+          agentId: configuredDefaultWorkerAgent,
           logger: api.logger,
           command: acpx.command,
           env: acpx.env,
@@ -96,7 +98,7 @@ const plugin = {
           archiveDirName: config.archiveDirName,
           allowedChannels: config.allowedChannels,
           defaultWorkspace: config.defaultWorkspace,
-          defaultWorkerAgentId: config.workerAgentId,
+          defaultWorkerAgentId: undefined,
           workspaceStore,
           watcherManager,
         });

package/src/orchestrator/service.ts

@@ -83,6 +83,12 @@ import { slugToTitle } from "../utils/slug.ts";
 import { WorkspaceStore } from "../workspace/store.ts";
 import { isExecutionTriggerText, readExecutionResult } from "../execution/state.ts";
 import { createWorkerSessionKey, matchesExecutionSession } from "../execution/session.ts";
+import {
+  buildWorkerAgentSetupHint,
+  buildWorkerAgentSetupMessage,
+  getConfiguredDefaultWorkerAgent,
+  listConfiguredWorkerAgents,
+} from "../acp/openclaw-config.ts";
 import {
   buildExecutionPrependContext,
   buildExecutionSystemContext,
@@ -130,7 +136,7 @@ type ClawSpecServiceOptions = {
   openSpec: OpenSpecClient;
   archiveDirName: string;
   defaultWorkspace: string;
-  defaultWorkerAgentId: string;
+  defaultWorkerAgentId?: string;
   workspaceStore: WorkspaceStore;
   allowedChannels?: string[];
   maxAutoContinueTurns?: number;
@@ -155,7 +161,7 @@ export class ClawSpecService {
   readonly openSpec: OpenSpecClient;
   readonly archiveDirName: string;
   readonly defaultWorkspace: string;
-  readonly defaultWorkerAgentId: string;
+  readonly defaultWorkerAgentId?: string;
   readonly workspaceStore: WorkspaceStore;
   readonly allowedChannels?: string[];
   readonly watcherManager?: WatcherManager;
@@ -1062,7 +1068,7 @@ export class ClawSpecService {
         ...base,
         contextMode: "attached",
         workspacePath: project.workspacePath ?? workspacePath,
-        workerAgentId: base.workerAgentId ?? current.workerAgentId ?? this.defaultWorkerAgentId,
+        workerAgentId: base.workerAgentId ?? current.workerAgentId,
         repoPath,
         projectName,
         projectTitle: sameRepo ? base.projectTitle : projectName,
@@ -1325,7 +1331,8 @@ export class ClawSpecService {
     const project = await this.ensureSessionProject(channelKey, workspacePath);
     const requestedAgent = rawArgs.trim();
     const availableAgents = this.listAvailableWorkerAgents();
-    const currentAgent = project.workerAgentId ?? this.defaultWorkerAgentId;
+    const currentAgent = project.workerAgentId ?? this.getDefaultWorkerAgentId();
+    const defaultAgent = this.getDefaultWorkerAgentId();
 
     if (requestedAgent.toLowerCase() === "status") {
       return okReply(await this.buildWorkerStatusText(project, availableAgents));
@@ -1335,9 +1342,12 @@ export class ClawSpecService {
       const lines = [
         heading("Worker Agent"),
         "",
-        `Current worker agent: \`${currentAgent}\``,
-        `Default worker agent: \`${this.defaultWorkerAgentId}\``,
+        `Current worker agent: ${formatWorkerAgent(currentAgent)}`,
+        `Default worker agent: ${formatWorkerAgent(defaultAgent)}`,
         availableAgents.length > 0 ? `Available agents: ${availableAgents.map((agentId) => `\`${agentId}\``).join(", ")}` : "",
+        !defaultAgent && !project.workerAgentId
+          ? `OpenClaw ACP default is missing. ${buildWorkerAgentSetupHint("work")}`
+          : "",
         "",
         "Use `/clawspec worker <agent-id>` to change the ACP worker agent for this channel/project context.",
       ].filter(Boolean);
@@ -1364,7 +1374,7 @@ export class ClawSpecService {
       [
         heading("Worker Agent Updated"),
         "",
-        `Worker agent: \`${updated.workerAgentId ?? this.defaultWorkerAgentId}\``,
+        `Worker agent: ${formatWorkerAgent(updated.workerAgentId)}`,
         "Future background implementation turns will use this ACP agent.",
       ].join("\n"),
     );
@@ -1415,6 +1425,10 @@ export class ClawSpecService {
     if (hasBlockingExecution(project)) {
       return errorReply(BLOCKING_EXECUTION_MSG);
     }
+    const workerConfig = this.validateWorkerAgentConfiguration(project, "work");
+    if (!workerConfig.ok) {
+      return workerConfig.result;
+    }
 
     const repoStatePaths = getRepoStatePaths(project.repoPath, this.archiveDirName);
     const outputs: OpenSpecCommandResult[] = [];
@@ -1483,6 +1497,7 @@ export class ClawSpecService {
     }
 
     const armedAt = new Date().toISOString();
+    const workerAgentId = workerConfig.agentId;
 
     await removeIfExists(repoStatePaths.executionResultFile);
     const remainingTasks = apply.tasks.filter((task) => !task.done);
@@ -1503,12 +1518,12 @@ export class ClawSpecService {
         mode,
         action: "work",
         state: "armed",
-        workerAgentId: current.workerAgentId ?? this.defaultWorkerAgentId,
+        workerAgentId,
         workerSlot: "primary",
         armedAt,
         sessionKey: createWorkerSessionKey(current, {
           workerSlot: "primary",
-          workerAgentId: current.workerAgentId ?? this.defaultWorkerAgentId,
+          workerAgentId,
           attemptKey: armedAt,
         }),
       },
@@ -1885,14 +1900,13 @@ export class ClawSpecService {
   private async ensureSessionProject(channelKey: string, workspacePath: string): Promise<ProjectState> {
     const existing = await this.stateStore.getActiveProject(channelKey);
     if (existing) {
-      if (existing.workspacePath && existing.workerAgentId) {
+      if (existing.workspacePath) {
         return existing;
       }
       return await this.stateStore.updateProject(channelKey, (current) => ({
         ...current,
         contextMode: current.contextMode ?? "attached",
         workspacePath: current.workspacePath ?? workspacePath,
-        workerAgentId: current.workerAgentId ?? this.defaultWorkerAgentId,
         status: current.status || "idle",
         phase: current.phase || "init",
       }));
@@ -1904,29 +1918,22 @@ export class ClawSpecService {
       ...current,
       contextMode: current.contextMode ?? "attached",
       workspacePath,
-      workerAgentId: current.workerAgentId ?? this.defaultWorkerAgentId,
       status: "idle",
       phase: "init",
     }));
   }
 
   private listAvailableWorkerAgents(): string[] {
-    const config = this.config as Record<string, unknown>;
-    const acp = config.acp as Record<string, unknown> | undefined;
-    const allowed = Array.isArray(acp?.allowedAgents)
-      ? acp.allowedAgents.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
-      : [];
-    const agentsConfig = config.agents as Record<string, unknown> | undefined;
-    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)
-      : [];
-    return Array.from(new Set([...allowed, ...listed])).sort((left, right) => left.localeCompare(right));
+    const configured = listConfiguredWorkerAgents(this.config);
+    if (configured.length > 0) {
+      return configured;
+    }
+    return this.defaultWorkerAgentId ? [this.defaultWorkerAgentId] : [];
   }
 
   private async buildWorkerStatusText(project: ProjectState, availableAgents: string[]): Promise<string> {
-    const configuredAgent = project.workerAgentId ?? this.defaultWorkerAgentId;
+    const configuredAgent = this.getEffectiveWorkerAgentId(project);
+    const defaultAgent = this.getDefaultWorkerAgentId();
     const execution = project.execution;
     const taskCounts = project.taskCounts;
     const runtimeStatus = this.watcherManager?.getWorkerRuntimeStatus
@@ -1961,9 +1968,10 @@ export class ClawSpecService {
       `Context: \`${isProjectContextAttached(project) ? "attached" : "detached"}\``,
       `Phase: \`${project.phase}\``,
       `Lifecycle: \`${project.status}\``,
-      `Configured worker agent: \`${configuredAgent}\``,
-      `Default worker agent: \`${this.defaultWorkerAgentId}\``,
+      `Configured worker agent: ${formatWorkerAgent(configuredAgent)}`,
+      `Default worker agent: ${formatWorkerAgent(defaultAgent)}`,
       availableAgents.length > 0 ? `Available agents: ${availableAgents.map((agentId) => `\`${agentId}\``).join(", ")}` : "",
+      !configuredAgent ? `Worker setup: ${buildWorkerAgentSetupHint("work")}` : "",
       `Execution state: \`${execution?.state ?? "idle"}\``,
       `Worker transport: \`${transportMode}\``,
       `Action: \`${execution?.action ?? "none"}\``,
@@ -2667,7 +2675,7 @@ export class ClawSpecService {
       : project.status === "planning"
         ? "visible-chat"
         : "idle";
-    const workerAgent = project.execution?.workerAgentId ?? project.workerAgentId ?? this.defaultWorkerAgentId;
+    const workerAgent = this.getEffectiveWorkerAgentId(project);
     const showLastExecution = !project.execution;
     const latestExecutionSummary = showLastExecution && project.lastExecution
       ? formatExecutionSummary(project.lastExecution)
@@ -2696,12 +2704,13 @@ export class ClawSpecService {
       `Repo path: ${project.repoPath ? `\`${project.repoPath}\`` : "_unset_"}`,
       `Change: ${project.changeName ? `\`${project.changeName}\`` : "_none_"}`,
       `Context: \`${isProjectContextAttached(project) ? "attached" : "detached"}\``,
-      `Worker agent: \`${workerAgent}\``,
+      `Worker agent: ${formatWorkerAgent(workerAgent)}`,
       `Lifecycle: \`${project.status}\``,
       `Phase: \`${project.phase}\``,
       `Execution: \`${executionStatus}\``,
       formatProjectTaskCounts(project, taskCounts),
       `Planning journal: ${project.planningJournal?.dirty ? "dirty" : "clean"} (${project.planningJournal?.entryCount ?? 0} entries)`,
+      !workerAgent ? `Worker setup: ${buildWorkerAgentSetupHint("work")}` : "",
       nextStepHint ? `Next step: ${nextStepHint}` : "",
       project.latestSummary ? `Latest summary: ${project.latestSummary}` : "Latest summary: _none_",
       project.blockedReason ? `Blocked reason: ${project.blockedReason}` : "",
@@ -2717,6 +2726,39 @@ export class ClawSpecService {
 
     return lines.filter((line, index, array) => !(line === "" && array[index - 1] === "")).join("\n");
   }
+
+  private getDefaultWorkerAgentId(): string | undefined {
+    return getConfiguredDefaultWorkerAgent(this.config) ?? this.defaultWorkerAgentId;
+  }
+
+  private getEffectiveWorkerAgentId(project: ProjectState): string | undefined {
+    return project.execution?.workerAgentId ?? project.workerAgentId ?? this.getDefaultWorkerAgentId();
+  }
+
+  private validateWorkerAgentConfiguration(
+    project: ProjectState,
+    action: "plan" | "work",
+  ): { ok: true; agentId: string } | { ok: false; result: PluginCommandResult } {
+    const workerAgentId = this.getEffectiveWorkerAgentId(project);
+    if (workerAgentId) {
+      return { ok: true, agentId: workerAgentId };
+    }
+    return {
+      ok: false,
+      result: errorReply(
+        [
+          heading("Worker Setup Required"),
+          "",
+          buildWorkerAgentSetupMessage(action),
+          "ClawSpec manages the `acpx` command automatically; only the OpenClaw ACP agent selection is missing.",
+        ].join("\n"),
+      ),
+    };
+  }
+}
+
+function formatWorkerAgent(agentId: string | undefined): string {
+  return agentId ? `\`${agentId}\`` : "_not configured_";
 }
 
 function describeWorkerTransportMode(project: ProjectState): string {

package/src/utils/paths.ts

@@ -7,6 +7,7 @@ export type RepoStatePaths = {
   executionControlFile: string;
   executionResultFile: string;
   workerProgressFile: string;
+  workerIoFile: string;
   progressFile: string;
   changedFilesFile: string;
   decisionLogFile: string;
@@ -66,6 +67,7 @@ export function getRepoStatePaths(repoPath: string, archiveDirName: string): Rep
     executionControlFile: path.join(root, "execution-control.json"),
     executionResultFile: path.join(root, "execution-result.json"),
     workerProgressFile: path.join(root, "worker-progress.jsonl"),
+    workerIoFile: path.join(root, "worker_io.mjs"),
     progressFile: path.join(root, "progress.md"),
     changedFilesFile: path.join(root, "changed-files.md"),
     decisionLogFile: path.join(root, "decision-log.md"),

package/src/watchers/manager.ts

@@ -30,8 +30,10 @@ import {
 } from "../utils/fs.ts";
 import { getChangeDir, getRepoStatePaths, getTasksPath, resolveProjectScopedPath } from "../utils/paths.ts";
 import { loadClawSpecSkillBundle } from "../worker/skills.ts";
+import { ensureWorkerIoHelper } from "../worker/io-helper.ts";
 import { buildAcpImplementationTurnPrompt, buildAcpPlanningTurnPrompt } from "../worker/prompts.ts";
 import { AcpWorkerClient, type AcpWorkerEvent, type AcpWorkerStatus } from "../acp/client.ts";
+import { buildWorkerAgentSetupHint } from "../acp/openclaw-config.ts";
 import { ClawSpecNotifier } from "./notifier.ts";
 
 type WatcherManagerOptions = {
@@ -228,7 +230,7 @@ export class WatcherManager {
 
     const action: ProjectExecutionState["action"] =
       project.phase === "planning_sync" || project.status === "planning" ? "plan" : "work";
-    const workerAgentId = project.workerAgentId ?? this.acpClient.agentId;
+    const workerAgentId = project.execution?.workerAgentId ?? project.workerAgentId ?? this.acpClient.agentId;
     const armedAt = new Date().toISOString();
     const sessionKey = createWorkerSessionKey(project, {
       workerSlot: "primary",
@@ -2121,6 +2123,7 @@ function toRepoRelative(project: ProjectState, targetPath: string): string {
 
 async function ensureSupportFiles(repoStatePaths: ReturnType<typeof getRepoStatePaths>): Promise<void> {
   await ensureDir(repoStatePaths.root);
+  await ensureWorkerIoHelper(repoStatePaths);
   if (!(await pathExists(repoStatePaths.progressFile))) {
     await writeUtf8(repoStatePaths.progressFile, "# Progress\n");
   }
@@ -2177,6 +2180,7 @@ async function resetRunSupportFiles(
   latestSummary: string,
 ): Promise<void> {
   await ensureDir(repoStatePaths.root);
+  await ensureWorkerIoHelper(repoStatePaths);
   await writeUtf8(repoStatePaths.progressFile, "# Progress\n");
   await writeUtf8(repoStatePaths.workerProgressFile, "");
   await writeUtf8(repoStatePaths.changedFilesFile, "# Changed Files\n");
@@ -2329,9 +2333,7 @@ function isUnavailableAcpBackendFailure(message: string): boolean {
 }
 
 function buildAcpSetupHint(action: ProjectExecutionState["action"]): string {
-  return action === "plan"
-    ? "Enable `plugins.entries.acpx` + backend `acpx`; install/load `acpx` if needed; rerun `cs-plan`."
-    : "Enable `plugins.entries.acpx` + backend `acpx`; install/load `acpx` if needed; rerun `cs-work`.";
+  return buildWorkerAgentSetupHint(action);
 }
 
 function buildBlockedNextStep(project: ProjectState, blocker: string): string {
@@ -2362,7 +2364,7 @@ function buildWorkerRestartMessage(params: {
   delayMs: number;
 }): string {
   if (isUnavailableAcpBackendFailure(params.failureMessage)) {
-    return `Restarting ACP worker (attempt ${params.restartCount}) failed because ACPX is unavailable. Next: enable \`plugins.entries.acpx\` and backend \`acpx\`, or install/load \`acpx\`.`;
+    return `Restarting ACP worker (attempt ${params.restartCount}) failed because OpenClaw ACP is unavailable. Next: ${buildAcpSetupHint(params.action)}`;
   }
   const retryDelaySeconds = Math.ceil(params.delayMs / 1000);
   const retryTarget = formatWorkerRetryTarget(params.action, params.nextDetail);
@@ -2612,7 +2614,7 @@ const WORKER_STATUS_POLL_INTERVAL_MS = 1_000;
 const DEAD_SESSION_GRACE_MS = 2_000;
 const WORKER_STARTUP_GRACE_MS = 3_000;
 const WORKER_STARTUP_WAIT_NOTIFY_DELAY_MS = 8_000;
-const WORKER_STARTUP_WAIT_NOTIFY_INTERVAL_MS = 20_000;
+const WORKER_STARTUP_WAIT_NOTIFY_INTERVAL_MS = 60_000;
 const QUEUE_OWNER_UNAVAILABLE_STARTUP_GRACE_MS = 4_500;
 const RUN_TURN_SETTLE_GRACE_MS = 1_500;
 const MAX_WORKER_RESTART_ATTEMPTS = 10;

package/src/worker/io-helper.ts

@@ -0,0 +1,126 @@
+import type { RepoStatePaths } from "../utils/paths.ts";
+import { tryReadUtf8, writeUtf8 } from "../utils/fs.ts";
+
+const WORKER_IO_HELPER_SOURCE = [
+  'import fs from "node:fs";',
+  'import path from "node:path";',
+  'import { fileURLToPath } from "node:url";',
+  "",
+  'const ROOT = path.dirname(fileURLToPath(import.meta.url));',
+  'const PROGRESS_FILE = path.join(ROOT, "worker-progress.jsonl");',
+  'const RESULT_FILE = path.join(ROOT, "execution-result.json");',
+  "",
+  "function nowIso() {",
+  "  return new Date().toISOString();",
+  "}",
+  "",
+  "function usage(message) {",
+  "  if (message) {",
+  "    console.error(message);",
+  "  }",
+  '  console.error("usage:");',
+  '  console.error("  worker_io.mjs event --kind <kind> --current <n> --total <n> --task-id <id> --message <text>");',
+  '  console.error("  worker_io.mjs result --file <json-file>");',
+  "  process.exit(1);",
+  "}",
+  "",
+  "function parseFlags(argv) {",
+  "  const flags = {};",
+  "  for (let index = 0; index < argv.length; index += 1) {",
+  "    const token = argv[index];",
+  '    if (!token || !token.startsWith("--")) {',
+  '      usage(`unexpected argument: ${token ?? "<missing>"}`);',
+  "    }",
+  "    const key = token.slice(2);",
+  "    const value = argv[index + 1];",
+  "    if (!key) {",
+  '      usage("flag name cannot be empty");',
+  "    }",
+  "    if (value === undefined) {",
+  '      usage(`missing value for --${key}`);',
+  "    }",
+  "    flags[key] = value;",
+  "    index += 1;",
+  "  }",
+  "  return flags;",
+  "}",
+  "",
+  "function requireFlag(flags, key) {",
+  "  const value = flags[key];",
+  '  if (typeof value !== "string" || value.trim() === "") {',
+  '    usage(`missing --${key}`);',
+  "  }",
+  "  return value;",
+  "}",
+  "",
+  "function requireInteger(flags, key) {",
+  "  const raw = requireFlag(flags, key);",
+  "  const parsed = Number.parseInt(raw, 10);",
+  "  if (!Number.isFinite(parsed) || parsed < 0) {",
+  '    usage(`invalid integer for --${key}: ${raw}`);',
+  "  }",
+  "  return parsed;",
+  "}",
+  "",
+  "function appendEvent(flags) {",
+  "  const payload = {",
+  "    version: 1,",
+  "    timestamp: nowIso(),",
+  '    kind: requireFlag(flags, "kind"),',
+  '    current: requireInteger(flags, "current"),',
+  '    total: requireInteger(flags, "total"),',
+  '    taskId: requireFlag(flags, "task-id"),',
+  '    message: requireFlag(flags, "message"),',
+  "  };",
+  "  fs.mkdirSync(path.dirname(PROGRESS_FILE), { recursive: true });",
+  '  fs.appendFileSync(PROGRESS_FILE, JSON.stringify(payload) + "\\n", "utf8");',
+  "}",
+  "",
+  "function writeResult(flags) {",
+  '  const inputFile = requireFlag(flags, "file");',
+  '  const payload = JSON.parse(fs.readFileSync(inputFile, "utf8"));',
+  '  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {',
+  '    usage("result payload must be a JSON object");',
+  "  }",
+  "  if (!payload.version) {",
+  "    payload.version = 1;",
+  "  }",
+  "  if (!payload.timestamp) {",
+  "    payload.timestamp = nowIso();",
+  "  }",
+  "  fs.mkdirSync(path.dirname(RESULT_FILE), { recursive: true });",
+  '  fs.writeFileSync(RESULT_FILE, `${JSON.stringify(payload, null, 2)}\\n`, "utf8");',
+  "}",
+  "",
+  "function main(argv) {",
+  "  const command = argv[2];",
+  '  if (command === "event") {',
+  "    appendEvent(parseFlags(argv.slice(3)));",
+  "    return;",
+  "  }",
+  '  if (command === "result") {',
+  "    writeResult(parseFlags(argv.slice(3)));",
+  "    return;",
+  "  }",
+  '  usage(command ? `unknown command: ${command}` : "missing command");',
+  "}",
+  "",
+  "main(process.argv);",
+  "",
+].join("\n");
+
+export async function ensureWorkerIoHelper(repoStatePaths: RepoStatePaths): Promise<void> {
+  const existing = await tryReadUtf8(repoStatePaths.workerIoFile);
+  if (existing === WORKER_IO_HELPER_SOURCE) {
+    return;
+  }
+  await writeUtf8(repoStatePaths.workerIoFile, WORKER_IO_HELPER_SOURCE);
+}
+
+export function buildWorkerIoEventCommandPrefix(repoStatePaths: RepoStatePaths): string {
+  return `node ${quoteForShell(repoStatePaths.workerIoFile)} event`;
+}
+
+function quoteForShell(value: string): string {
+  return `"${value.replace(/"/g, '\\"')}"`;
+}

package/src/worker/prompts.ts

@@ -7,6 +7,7 @@ import type {
 } from "../types.ts";
 import type { RepoStatePaths } from "../utils/paths.ts";
 import { resolveProjectScopedPath } from "../utils/paths.ts";
+import { buildWorkerIoEventCommandPrefix } from "./io-helper.ts";
 
 export function buildExecutionSystemContext(repoPath: string, importedSkills?: string): string {
   return [
@@ -368,6 +369,11 @@ export function buildAcpImplementationTurnPrompt(params: {
   const contextLabels = contextPaths.map((contextPath) => displayPath(contextPath));
   const firstContextLabel = contextLabels[0] ?? displayPath(tasksPath);
   const afterContextLabel = contextLabels[1] ?? `start task ${params.task.id}`;
+  const workerIoCommandPrefix = buildWorkerIoEventCommandPrefix(params.repoStatePaths);
+  const progressCommandTemplate =
+    `${workerIoCommandPrefix} --kind <status|task_start|task_done|blocked> --current <n> --total ${params.tasks.length} --task-id "<task-id>" --message "<message>"`;
+  const preparingCommandExample =
+    `${workerIoCommandPrefix} --kind status --current 1 --total ${params.tasks.length} --task-id "${params.task.id}" --message "Preparing ${params.task.id}: loading context. Next: read ${firstContextLabel}."`;
 
   const taskList = params.tasks.map((task) => `- ${task.id} ${task.description}`).join("\n");
 
@@ -388,7 +394,8 @@ export function buildAcpImplementationTurnPrompt(params: {
     "- Keep changes minimal and scoped to the active change.",
     "- Do not inspect or modify sibling `openspec/changes/<other-change>` directories.",
     `- Update ${tasksPath} by switching each task from \`- [ ]\` to \`- [x]\` as you complete it.`,
-    `- Append short progress events to ${params.repoStatePaths.workerProgressFile} as valid JSON Lines.`,
+    `- Use the worker IO helper instead of editing ${params.repoStatePaths.workerProgressFile} directly.`,
+    `- Worker IO helper command template: ${progressCommandTemplate}`,
     "- Progress events must be human-readable, one line each, and must match the actual work completed.",
     `- Every progress event must include \`current\` (current task number) and \`total\` (total task count for this run).`,
     `- Do not stay silent until \`task_start\`. Emit context-loading progress first.`,
@@ -407,6 +414,9 @@ export function buildAcpImplementationTurnPrompt(params: {
     "Context files to read first:",
     ...contextPaths.map((contextPath) => `- ${contextPath}`),
     "",
+    "Worker IO helper example:",
+    fence(preparingCommandExample, "bash"),
+    "",
     "Worker progress JSONL event template:",
     fence(JSON.stringify({
       version: 1,

package/test/config.test.ts

@@ -5,7 +5,7 @@ import { parsePluginConfig } from "../src/config.ts";
 test("parsePluginConfig returns defaults for empty input", () => {
   const config = parsePluginConfig(undefined);
   assert.equal(config.enabled, true);
-  assert.equal(config.workerAgentId, "codex");
+  assert.equal(config.workerAgentId, undefined);
   assert.equal(config.archiveDirName, "archives");
   assert.equal(config.openSpecTimeoutMs, 120_000);
   assert.equal(config.watcherPollIntervalMs, 4_000);
@@ -48,7 +48,7 @@ test("parsePluginConfig ignores invalid types", () => {
   });
   assert.equal(config.enabled, true); // falls back to default
   assert.equal(config.maxAutoContinueTurns, 3); // falls back to default
-  assert.equal(config.workerAgentId, "codex"); // falls back to default
+  assert.equal(config.workerAgentId, undefined); // deprecated and ignored unless explicitly set
 });
 
 test("parsePluginConfig filters allowedChannels", () => {

package/test/file-lock.test.ts

@@ -25,6 +25,7 @@ await withFileLock(lockPath, async () => {
   let childOutput = "";
   let childError = "";
   let child: ReturnType<typeof spawn> | undefined;
+  let childExit: Promise<number | null> | undefined;
 
   t.after(() => {
     if (child && !child.killed) {
@@ -41,6 +42,7 @@ await withFileLock(lockPath, async () => {
       cwd: process.cwd(),
       stdio: ["ignore", "pipe", "pipe"],
     });
+    childExit = waitForChildClose(child);
     child.stdout?.setEncoding("utf8");
     child.stderr?.setEncoding("utf8");
     child.stdout?.on("data", (chunk) => {
@@ -55,9 +57,7 @@ await withFileLock(lockPath, async () => {
   });
 
   await waitFor(() => childOutput.includes("acquired"));
-  const exitCode = await new Promise<number | null>((resolve) => {
-    child?.once("close", (code) => resolve(code));
-  });
+  const exitCode = await childExit;
 
   assert.equal(exitCode, 0, childError || undefined);
 });
@@ -76,3 +76,13 @@ async function waitFor(check: () => boolean, timeoutMs = 2_000): Promise<void> {
   }
   throw new Error("timed out waiting for lock handoff");
 }
+
+function waitForChildClose(child: ReturnType<typeof spawn>): Promise<number | null> {
+  if (child.exitCode !== null || child.signalCode !== null) {
+    return Promise.resolve(child.exitCode);
+  }
+
+  return new Promise<number | null>((resolve) => {
+    child.once("close", (code) => resolve(code));
+  });
+}

package/test/helpers/harness.ts

@@ -155,17 +155,41 @@ export async function createServiceHarness(prefix: string): Promise<{
   const watcherManager = createFakeWatcherManager();
   const service = new ClawSpecService({
     api: {
-      config: {},
+      config: {
+        acp: {
+          backend: "acpx",
+          defaultAgent: "codex",
+          allowedAgents: ["codex", "piper"],
+        },
+        agents: {
+          list: [
+            { id: "codex" },
+            { id: "piper" },
+          ],
+        },
+      },
       logger: createLogger(),
     } as any,
-    config: {} as any,
+    config: {
+      acp: {
+        backend: "acpx",
+        defaultAgent: "codex",
+        allowedAgents: ["codex", "piper"],
+      },
+      agents: {
+        list: [
+          { id: "codex" },
+          { id: "piper" },
+        ],
+      },
+    } as any,
     logger: createLogger(),
     stateStore,
     memoryStore,
     openSpec: openSpec as any,
     archiveDirName: "archives",
     defaultWorkspace: workspacePath,
-    defaultWorkerAgentId: "codex",
+    defaultWorkerAgentId: undefined,
     workspaceStore,
     watcherManager: watcherManager as any,
   });

package/test/queue-work.test.ts

@@ -108,3 +108,55 @@ test("main chat agent end does not clear a background worker run", async () => {
   assert.equal(project?.execution?.sessionKey, workerSessionKey);
   assert.equal(project?.latestSummary, "Worker is running in the background.");
 });
+
+test("work requires OpenClaw ACP default agent when no project override is set", async () => {
+  const harness = await createServiceHarness("clawspec-work-missing-acp-");
+  const { service, stateStore, watcherManager, repoPath, workspacePath, changeDir } = harness;
+  const channelKey = "discord:work-missing-acp:default:main";
+  const tasksPath = path.join(changeDir, "tasks.md");
+  await writeUtf8(tasksPath, "- [ ] 1.1 Build the demo endpoint\n");
+
+  (service as any).config = {
+    acp: {
+      backend: "acpx",
+    },
+  };
+
+  harness.openSpec.instructionsApply = async (cwd: string, changeName: string) => ({
+    command: `openspec instructions apply --change ${changeName} --json`,
+    cwd,
+    stdout: "{}",
+    stderr: "",
+    durationMs: 1,
+    parsed: {
+      changeName,
+      changeDir,
+      schemaName: "spec-driven",
+      contextFiles: { tasks: tasksPath },
+      progress: { total: 1, complete: 0, remaining: 1 },
+      tasks: [{ id: "1.1", description: "Build the demo endpoint", done: false }],
+      state: "ready",
+      instruction: "Implement the remaining task.",
+    },
+  });
+
+  await seedPlanningProject(stateStore, channelKey, {
+    workspacePath,
+    repoPath,
+    projectName: "demo-app",
+    changeName: "queue-work",
+    changeDir,
+    phase: "tasks",
+    status: "ready",
+    planningDirty: false,
+  });
+
+  const result = await service.queueWorkProject(channelKey, "apply");
+  const project = await stateStore.getActiveProject(channelKey);
+
+  assert.match(result.text ?? "", /Worker Setup Required/);
+  assert.match(result.text ?? "", /openclaw config set acp\.backend acpx/);
+  assert.match(result.text ?? "", /openclaw config set acp\.defaultAgent codex/);
+  assert.equal(project?.status, "ready");
+  assert.deepEqual(watcherManager.wakeCalls, []);
+});

package/test/service-archive.test.ts

@@ -57,14 +57,19 @@ test("service writes archive bundles from visible-execution state", async () =>
 
   const service = new ClawSpecService({
     api: fakeApi,
-    config: {} as any,
+    config: {
+      acp: {
+        backend: "acpx",
+        defaultAgent: "codex",
+      },
+    } as any,
     logger: fakeApi.logger,
     stateStore,
     memoryStore,
     openSpec: {} as any,
     archiveDirName: "archives",
     defaultWorkspace: workspacePath,
-    defaultWorkerAgentId: "codex",
+    defaultWorkerAgentId: undefined,
     workspaceStore,
   });
 

package/test/watcher-work.test.ts

@@ -1462,7 +1462,7 @@ test("watcher blocked message includes ACPX setup guidance when backend stays un
   assert.equal(project?.status, "blocked");
   assert.equal(project?.blockedReason?.includes("Blocked after 10 ACP restart attempts"), true);
   assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-blocked", "Blocked: ACPX backend unavailable"), true);
-  assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-blocked", "plugins.entries.acpx"), true);
+  assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-blocked", "openclaw config set acp.defaultAgent codex"), true);
   assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-blocked", "cs-work"), true);
 });
 
@@ -1590,8 +1590,8 @@ test("watcher retries when ACP runtime backend is temporarily unavailable", asyn
   assert.equal(project?.status, "done");
   assert.equal(runCount, 2);
   assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-unavailable", "Restarting ACP worker"), true);
-  assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-unavailable", "ACPX is unavailable"), true);
-  assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-unavailable", "plugins.entries.acpx"), true);
+  assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-unavailable", "OpenClaw ACP is unavailable"), true);
+  assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-unavailable", "openclaw config set acp.defaultAgent codex"), true);
   assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-backend-unavailable", "All tasks complete"), true);
 });
 

package/test/worker-io-helper.test.ts

@@ -0,0 +1,97 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, mkdir, writeFile } from "node:fs/promises";
+import { spawnSync } from "node:child_process";
+import { ensureWorkerIoHelper } from "../src/worker/io-helper.ts";
+import { buildAcpImplementationTurnPrompt } from "../src/worker/prompts.ts";
+import { getRepoStatePaths } from "../src/utils/paths.ts";
+import { readUtf8 } from "../src/utils/fs.ts";
+
+test("worker io helper appends progress events via node command", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-worker-io-helper-"));
+  const repoPath = path.join(tempRoot, "demo-app");
+  await mkdir(repoPath, { recursive: true });
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  await ensureWorkerIoHelper(repoStatePaths);
+
+  const result = spawnSync(
+    process.execPath,
+    [
+      repoStatePaths.workerIoFile,
+      "event",
+      "--kind",
+      "status",
+      "--current",
+      "1",
+      "--total",
+      "3",
+      "--task-id",
+      "1.1",
+      "--message",
+      "Preparing 1.1: loading context. Next: read proposal.md.",
+    ],
+    { encoding: "utf8" },
+  );
+
+  assert.equal(result.status, 0, result.stderr);
+  const raw = await readUtf8(repoStatePaths.workerProgressFile);
+  const lines = raw.trim().split(/\r?\n/);
+  assert.equal(lines.length, 1);
+  const payload = JSON.parse(lines[0]!);
+  assert.equal(payload.kind, "status");
+  assert.equal(payload.current, 1);
+  assert.equal(payload.total, 3);
+  assert.equal(payload.taskId, "1.1");
+  assert.equal(payload.message, "Preparing 1.1: loading context. Next: read proposal.md.");
+});
+
+test("implementation prompt instructs the worker to use the helper", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-worker-io-prompt-"));
+  const repoPath = path.join(tempRoot, "demo-app");
+  const changeDir = path.join(repoPath, "openspec", "changes", "demo-change");
+  await mkdir(changeDir, { recursive: true });
+  await writeFile(path.join(changeDir, "proposal.md"), "# Proposal\n", "utf8");
+  await writeFile(path.join(changeDir, "tasks.md"), "- [ ] 1.1 Demo task\n", "utf8");
+
+  const repoStatePaths = getRepoStatePaths(repoPath, "archives");
+  const prompt = buildAcpImplementationTurnPrompt({
+    project: {
+      version: 1,
+      projectId: "project-1",
+      channelKey: "discord:test:default:main",
+      storagePath: path.join(repoStatePaths.root, "state.json"),
+      status: "running",
+      phase: "implementing",
+      createdAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+      repoPath,
+      workspacePath: tempRoot,
+      projectName: "demo-app",
+      changeName: "demo-change",
+      changeDir,
+      pauseRequested: false,
+    },
+    repoStatePaths,
+    apply: {
+      changeName: "demo-change",
+      changeDir,
+      schemaName: "spec-driven",
+      contextFiles: {
+        proposal: path.join(changeDir, "proposal.md"),
+        tasks: path.join(changeDir, "tasks.md"),
+      },
+      progress: { total: 1, complete: 0, remaining: 1 },
+      tasks: [{ id: "1.1", description: "Demo task", done: false }],
+      state: "ready",
+      instruction: "Implement the remaining task.",
+    },
+    task: { id: "1.1", description: "Demo task" },
+    tasks: [{ id: "1.1", description: "Demo task" }],
+    mode: "apply",
+  });
+
+  assert.match(prompt, /Use the worker IO helper instead of editing .*worker-progress\.jsonl directly\./);
+  assert.match(prompt, /worker_io\.mjs" event --kind <status\|task_start\|task_done\|blocked>/);
+});