clawspec 1.0.16 → 1.0.19

package/README.md

@@ -552,6 +552,8 @@ That loop is the normal operating model:
 | `/clawspec status` | Any time you want a reconciled project snapshot | Renders current workspace, project, change, lifecycle, task counts, journal status, and next step |
 | `/clawspec archive` | After all tasks are complete and you want to close the change | Validates and archives the finished OpenSpec change, then clears active change state |
 | `/clawspec cancel` | When you want to abandon the active change | Restores tracked files from snapshots, removes the change, stops execution state, and clears the active change |
+| `/clawspec doctor` | When something isn't working as expected | Runs automated diagnostics on your environment and configuration, reports detected issues with suggested fixes |
+| `/clawspec doctor fix` | After `/clawspec doctor` reports a fixable issue | Automatically applies safe fixes for all detected issues that support auto-repair |
 
 Auxiliary host CLI:
 
@@ -858,6 +860,20 @@ Use one of:
 
 That is by design. Cancel restores tracked files from the ClawSpec snapshot baseline for the active change. It is intentionally narrower than a blanket Git restore.
 
+### Worker fails with "stdin is not a terminal" or session creation returns no result
+
+Cause:
+
+- `~/.acpx/config.json` has a custom agent entry (e.g. `agents.codex` pointing to a local CLI binary)
+- acpx cannot spawn the agent in a non-interactive environment when it is configured as a raw CLI command
+
+What to do:
+
+1. Run `/clawspec doctor` to check for known configuration issues.
+2. If `/clawspec doctor` reports custom agent entries, run `/clawspec doctor fix` to clear them automatically.
+3. Alternatively, edit `~/.acpx/config.json` manually and set `"agents": {}`.
+4. Retry `cs-work` or `/clawspec continue`.
+
 ## Development And Validation
 
 Useful checks while editing the plugin:

package/README.zh-CN.md

@@ -556,6 +556,8 @@ cs-work
 | `/clawspec status` | 任何时候想看一次统一状态快照时 | 输出当前 workspace、project、change、生命周期、任务计数、journal 状态和下一步建议 |
 | `/clawspec archive` | 所有任务完成，准备收尾时 | 校验并归档当前 OpenSpec change，同时清理活动 change 状态 |
 | `/clawspec cancel` | 想放弃当前 change 时 | 按快照恢复已跟踪文件、删除 change、停止执行状态，并清掉活动 change |
+| `/clawspec doctor` | 遇到异常行为时 | 对环境和配置进行自动化诊断，报告检测到的问题并给出修复建议 |
+| `/clawspec doctor fix` | `/clawspec doctor` 检测到可修复问题后 | 自动应用所有支持自动修复的安全修复 |
 
 辅助 host CLI：
 
@@ -869,6 +871,20 @@ cs-detach
 
 这是设计如此。Cancel 只会恢复 ClawSpec 为当前 change 跟踪的文件快照，而不是做整仓库级别的 Git 还原。
 
+### Worker 报错 "stdin is not a terminal" 或 session 创建无结果
+
+原因：
+
+- `~/.acpx/config.json` 中的 `agents` 字段存在自定义配置（例如 `agents.codex` 指向了本地 CLI 路径）
+- acpx 在非交互式环境下无法通过 raw CLI 方式启动 agent
+
+解决方法：
+
+1. 运行 `/clawspec doctor` 检查配置问题。
+2. 如果 doctor 报告了自定义 agent 配置，运行 `/clawspec doctor fix` 自动修复。
+3. 也可以手动编辑 `~/.acpx/config.json`，将 `"agents"` 设置为 `{}`。
+4. 然后重新运行 `cs-work` 或 `/clawspec continue`。
+
 ## 开发与验证
 
 开发时常用检查：

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "clawspec",
-  "version": "1.0.16",
+  "version": "1.0.19",
   "type": "module",
   "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
   "keywords": [
@@ -46,7 +46,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/paths-utils.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: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/doctor.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/paths-utils.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

@@ -141,7 +141,7 @@ export class AcpWorkerClient {
       allowErrorCodes: ["NO_SESSION"],
     });
 
-    if (events.some((event) => toAcpxErrorEvent(event)?.code === "NO_SESSION")) {
+    if (events.some((event) => toAcpxErrorEvent(event)?.code === "NO_SESSION") || events.length === 0) {
       events = await this.runControlCommand({
         agentId: descriptor.agentId,
         cwd: descriptor.cwd,
@@ -149,6 +149,14 @@ export class AcpWorkerClient {
       });
     }
 
+    if (events.length === 0 || !extractSessionIdentifiers(events).backendSessionId) {
+      throw new Error(
+        `Failed to create acpx session for agent "${descriptor.agentId}".\n`
+        + `The session command returned no result. This usually means the agent is misconfigured.\n\n`
+        + `Run \`/clawspec doctor\` to diagnose and fix common acpx configuration issues.`,
+      );
+    }
+
     const identifiers = extractSessionIdentifiers(events);
     const handle: AcpWorkerHandle = {
       sessionKey: descriptor.sessionKey,
@@ -186,6 +194,13 @@ export class AcpWorkerClient {
       cwd: descriptor.cwd,
       env: this.env,
     });
+
+    const args = this.buildPromptArgs({
+      agentId: descriptor.agentId,
+      cwd: descriptor.cwd,
+      sessionKey: descriptor.sessionKey,
+    });
+
     child.stdout.setEncoding("utf8");
     child.stderr.setEncoding("utf8");
     child.stdin.end(params.text);
@@ -250,6 +265,7 @@ export class AcpWorkerClient {
 
       const exit = await waitForExit(child);
       this.recordSessionExit(params.sessionKey, descriptor, child.pid, exit.code, exit.signal, stderr);
+
       if (exit.error) {
         throw exit.error;
       }

package/src/orchestrator/helpers.ts

@@ -125,6 +125,7 @@ export function buildHelpText(): string {
     "- `/clawspec status`",
     "- `/clawspec archive`",
     "- `/clawspec cancel`",
+    "- `/clawspec doctor`",
     "",
     "Visible chat keywords:",
     "- `cs-plan`",

package/src/orchestrator/service.ts

@@ -1,3 +1,4 @@
+import os from "node:os";
 import path from "node:path";
 import type {
   OpenClawConfig,
@@ -236,6 +237,8 @@ export class ClawSpecService {
           return await this.archiveProject(channelKey);
         case "cancel":
           return await this.cancelProject(channelKey);
+        case "doctor":
+          return await this.runDoctor(rest);
         default:
           return errorReply(`Unknown subcommand \`${subcommand}\`.\n\n${buildHelpText()}`);
       }
@@ -675,13 +678,6 @@ export class ClawSpecService {
         repoStatePaths.planningJournalSnapshotFile,
         project.planningJournal?.lastSyncedAt,
       );
-      const snapshot = await journalStore.readSnapshot(repoStatePaths.planningJournalSnapshotFile);
-      const digest = await journalStore.digest(project.changeName);
-      this.logger.info(`[clawspec] cs-work check for ${project.changeName}:`);
-      this.logger.info(`  - hasUnsyncedChanges: ${hasUnsyncedChanges}`);
-      this.logger.info(`  - Snapshot: entryCount=${snapshot?.entryCount}, lastEntryAt=${snapshot?.lastEntryAt}, hash=${snapshot?.contentHash?.slice(0, 8)}`);
-      this.logger.info(`  - Current digest: entryCount=${digest.entryCount}, lastEntryAt=${digest.lastEntryAt}, hash=${digest.contentHash.slice(0, 8)}`);
-      this.logger.info(`  - fallbackLastSyncedAt: ${project.planningJournal?.lastSyncedAt}`);
       if (!hasUnsyncedChanges) {
         const isDetached = !isProjectContextAttached(project);
         if (isDetached) {
@@ -758,7 +754,6 @@ export class ClawSpecService {
     userPrompt: string,
     mode: ExecutionMode,
   ): Promise<{ prependContext?: string; prependSystemContext?: string } | PluginCommandResult> {
-    this.logger.info(`[clawspec] startVisiblePlanningSync called for ${project.changeName}`);
     void project;
     void mode;
 
@@ -781,7 +776,6 @@ export class ClawSpecService {
       execution: undefined,
       lastExecutionAt: startedAt,
     }));
-    this.logger.info(`[clawspec] Project state updated: status=planning, phase=planning_sync, boundSessionKey=${runningProject.boundSessionKey}`);
 
     return await this.buildPlanningSyncInjection(runningProject, userPrompt, prepared.instructionResults);
   }
@@ -964,7 +958,6 @@ export class ClawSpecService {
     const planningProject = await this.findPlanningProjectBySessionKey(ctx.sessionKey)
       ?? await this.findPlanningProjectByContext(ctx);
     if (planningProject) {
-      this.logger.info(`[clawspec] agent_end: found planning project ${planningProject.changeName}, calling finalizePlanningTurn`);
       await this.finalizePlanningTurn(planningProject, event);
       return;
     }
@@ -1914,6 +1907,11 @@ export class ClawSpecService {
     );
   }
 
+  async runDoctor(rawArgs?: string): Promise<PluginCommandResult> {
+    const acpxConfigPath = path.join(os.homedir(), ".acpx", "config.json");
+    return await runDoctorCommand(acpxConfigPath, rawArgs);
+  }
+
   private async captureIncomingMessage(channelKey: string, project: ProjectState, text: string): Promise<ProjectState> {
     const trimmed = sanitizePlanningMessageText(text).trim();
     if (!trimmed || trimmed.startsWith("/clawspec") || !project.repoPath || !project.changeName) {
@@ -2412,7 +2410,6 @@ export class ClawSpecService {
   }
 
   private async finalizePlanningTurn(project: ProjectState, event: AgentEndEvent): Promise<void> {
-    this.logger.info(`[clawspec] finalizePlanningTurn called for ${project.changeName}, success=${event.success}`);
     if (!project.repoPath || !project.changeName) {
       this.logger.warn(`[clawspec] finalizePlanningTurn skipped: missing repoPath or changeName`);
       return;
@@ -2474,8 +2471,6 @@ export class ClawSpecService {
     }
 
     const snapshot = await journalStore.writeSnapshot(repoStatePaths.planningJournalSnapshotFile, project.changeName, timestamp);
-    this.logger.info(`[clawspec] Planning snapshot written for ${project.changeName}: entryCount=${snapshot.entryCount}, lastEntryAt=${snapshot.lastEntryAt}`);
-    this.logger.info(`[clawspec] Updating project state: status=${status}, phase=${phase}, dirty=${journalDirty}`);
     await this.writeLatestSummary(repoStatePaths, latestSummary);
 
     const finalized = await this.stateStore.updateProject(project.channelKey, (current) => ({
@@ -3303,3 +3298,138 @@ function parseOptionalNumber(value: string): number | undefined {
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null;
 }
+
+type DoctorIssue = {
+  id: string;
+  message: string;
+  fix: string;
+};
+
+type DoctorContext = {
+  acpxConfigPath: string;
+  acpxConfig: Record<string, unknown> | null;
+  acpxConfigError: boolean;
+};
+
+type DoctorCheck = {
+  id: string;
+  check: (ctx: DoctorContext) => DoctorIssue | undefined;
+  applyFix?: (ctx: DoctorContext) => Promise<void>;
+};
+
+const DOCTOR_CHECKS: DoctorCheck[] = [
+  {
+    id: "acpx-config-json",
+    check: (ctx) => {
+      if (ctx.acpxConfigError) {
+        return {
+          id: "acpx-config-json",
+          message: `\`${ctx.acpxConfigPath}\` contains invalid JSON. acpx may fail to start.`,
+          fix: `Fix the JSON syntax in \`${ctx.acpxConfigPath}\`, or delete the file to use defaults.`,
+        };
+      }
+      return undefined;
+    },
+  },
+  {
+    id: "acpx-custom-agents",
+    check: (ctx) => {
+      if (!ctx.acpxConfig) return undefined;
+      const agents = ctx.acpxConfig.agents;
+      if (agents && typeof agents === "object" && Object.keys(agents as object).length > 0) {
+        const agentKeys = Object.keys(agents as object).map((k) => `\`${k}\``).join(", ");
+        return {
+          id: "acpx-custom-agents",
+          message:
+            `\`${ctx.acpxConfigPath}\` has custom agent entries: ${agentKeys}.\n`
+            + `  Custom agent configurations (e.g. pointing to a local CLI) can cause session creation to fail with "stdin is not a terminal".`,
+          fix:
+            `Set \`"agents": {}\` in \`${ctx.acpxConfigPath}\` to use the default agent launcher.\n`
+            + `  Run \`/clawspec doctor fix\` to apply this fix automatically.`,
+        };
+      }
+      return undefined;
+    },
+    applyFix: async (ctx) => {
+      if (ctx.acpxConfig) {
+        ctx.acpxConfig.agents = {};
+        await writeJsonFile(ctx.acpxConfigPath, ctx.acpxConfig);
+      }
+    },
+  },
+];
+
+export async function runDoctorCommand(acpxConfigPath: string, rawArgs?: string): Promise<PluginCommandResult> {
+  const action = rawArgs?.trim().toLowerCase();
+
+  let acpxConfig: Record<string, unknown> | null = null;
+  let acpxConfigError = false;
+  const raw = await tryReadUtf8(acpxConfigPath);
+  if (raw !== undefined && raw.trim() !== "") {
+    try {
+      acpxConfig = JSON.parse(raw) as Record<string, unknown>;
+    } catch {
+      acpxConfigError = true;
+    }
+  }
+
+  const ctx: DoctorContext = { acpxConfigPath, acpxConfig, acpxConfigError };
+  const issues: DoctorIssue[] = [];
+  for (const check of DOCTOR_CHECKS) {
+    const issue = check.check(ctx);
+    if (issue) {
+      issues.push(issue);
+    }
+  }
+
+  if (action === "fix") {
+    if (issues.length === 0) {
+      return okReply("Nothing to fix. acpx configuration is already clean.");
+    }
+    const fixable = DOCTOR_CHECKS.filter((c) => c.applyFix && issues.some((i) => i.id === c.id));
+    if (fixable.length === 0) {
+      return errorReply(
+        "Cannot auto-fix the detected issues. Please fix them manually:\n\n"
+        + issues.map((i) => `- ${i.fix}`).join("\n"),
+      );
+    }
+    for (const check of fixable) {
+      await check.applyFix!(ctx);
+    }
+    return okReply(
+      [
+        heading("Doctor Fix Applied"),
+        "",
+        ...fixable.map((c) => {
+          const issue = issues.find((i) => i.id === c.id);
+          return `Fixed: ${issue?.message.split("\n")[0] ?? c.id}`;
+        }),
+        "",
+        "Please retry your previous command.",
+      ].join("\n"),
+    );
+  }
+
+  if (issues.length === 0) {
+    return okReply(
+      [
+        heading("Doctor"),
+        "",
+        "No issues found. acpx configuration looks healthy.",
+      ].join("\n"),
+    );
+  }
+
+  return okReply(
+    [
+      heading("Doctor"),
+      "",
+      `Found ${issues.length} issue${issues.length > 1 ? "s" : ""}:`,
+      "",
+      ...issues.flatMap((issue, i) => [`**${i + 1}.** ${issue.message}`, ""]),
+      "Suggested fixes:",
+      "",
+      ...issues.flatMap((issue, i) => [`**${i + 1}.** ${issue.fix}`, ""]),
+    ].join("\n"),
+  );
+}

package/src/watchers/manager.ts

@@ -823,7 +823,7 @@ class ExecutionWatcher {
         },
       };
     });
-    await this.writeExecutionControl(this.channelKey);
+    await this.writeExecutionControl(queued);
     const nextPlanningStep = nextForcedArtifactId
       ? (nextPlanningArtifactId(forcedArtifactIds, selectedArtifactId) ?? await this.describeNextPlanningStep(queued))
       : await this.describeNextPlanningStep(queued);
@@ -906,6 +906,7 @@ class ExecutionWatcher {
       await writeUtf8(repoStatePaths.workerProgressFile, "");
 
       const importedSkills = await loadClawSpecSkillBundle(["apply"]);
+
       ({ runError } = await this.runAcpTurnWithTracking(
         runningProject,
         repoStatePaths,
@@ -1023,7 +1024,7 @@ class ExecutionWatcher {
         },
       };
     });
-    await this.writeExecutionControl(this.channelKey);
+    await this.writeExecutionControl(queued);
     return true;
   }
 
@@ -1205,6 +1206,17 @@ class ExecutionWatcher {
       await flushProgress();
       return { runError };
     }
+
+    this.logger.debug?.(
+      `[clawspec] calling acpClient.runTurn: ${JSON.stringify({
+        sessionKey,
+        cwd: project.repoPath,
+        agentId: workerAgentId,
+        promptLength: prompt.length,
+        acpxCommand: this.acpClient.command,
+      })}`,
+    );
+
     const runTurnPromise = this.acpClient.runTurn({
       sessionKey,
       cwd: project.repoPath!,
@@ -1637,7 +1649,7 @@ class ExecutionWatcher {
       },
     }));
 
-    await this.writeExecutionControl(this.channelKey);
+    await this.writeExecutionControl(recovered);
     await this.notify(
       recovered,
       buildWatcherStatusMessage(
@@ -1698,7 +1710,7 @@ class ExecutionWatcher {
         lastFailure: current.execution?.lastFailure,
       },
     }));
-    await this.writeExecutionControl(this.channelKey);
+    await this.writeExecutionControl(updated);
     return updated;
   }
 
@@ -1942,8 +1954,10 @@ class ExecutionWatcher {
     };
   }
 
-  private async writeExecutionControl(channelKey: string): Promise<void> {
-    const project = await this.stateStore.getActiveProject(channelKey);
+  private async writeExecutionControl(projectOrChannelKey: string | ProjectState): Promise<void> {
+    const project = typeof projectOrChannelKey === "string"
+      ? await this.stateStore.getActiveProject(projectOrChannelKey)
+      : projectOrChannelKey;
     if (!project?.repoPath || !project.changeName || !project.execution) {
       return;
     }

package/src/worker/io-helper.ts

@@ -118,9 +118,10 @@ export async function ensureWorkerIoHelper(repoStatePaths: RepoStatePaths): Prom
 }
 
 export function buildWorkerIoEventCommandPrefix(repoStatePaths: RepoStatePaths): string {
-  return `node ${quoteForShell(repoStatePaths.workerIoFile)} event`;
-}
-
-function quoteForShell(value: string): string {
-  return `"${value.replace(/"/g, '\\"')}"`;
+  const ioPath = repoStatePaths.workerIoFile;
+  // Use single quotes on POSIX, double quotes on Windows for cross-platform compatibility
+  if (process.platform === "win32") {
+    return `node "${ioPath.replace(/"/g, '""')}" event`;
+  }
+  return `node '${ioPath.replace(/'/g, `'\\''`)}' event`;
 }

package/test/command-surface.test.ts

@@ -8,6 +8,7 @@ test("help text only advertises the clawspec command surface", () => {
   assert.match(help, /\/clawspec workspace/);
   assert.match(help, /\/clawspec proposal <change-name> \[description\]/);
   assert.match(help, /\/clawspec continue/);
+  assert.match(help, /\/clawspec doctor/);
   assert.match(help, /\/clawspec detach/);
   assert.match(help, /cs-detach/);
   assert.match(help, /legacy aliases/);

package/test/doctor.test.ts

@@ -0,0 +1,142 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import os from "node:os";
+import path from "node:path";
+import { mkdtemp, mkdir } from "node:fs/promises";
+import { runDoctorCommand } from "../src/orchestrator/service.ts";
+import { writeJsonFile, readJsonFile } from "../src/utils/fs.ts";
+
+test("doctor reports no issues when config file does not exist", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-doctor-"));
+  const configPath = path.join(tempRoot, ".acpx", "config.json");
+
+  const result = await runDoctorCommand(configPath);
+
+  assert.equal(result.isError, undefined);
+  assert.match(result.text ?? "", /No issues found/);
+});
+
+test("doctor reports no issues when agents is empty", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-doctor-"));
+  const configDir = path.join(tempRoot, ".acpx");
+  await mkdir(configDir, { recursive: true });
+  const configPath = path.join(configDir, "config.json");
+
+  await writeJsonFile(configPath, {
+    defaultAgent: "codex",
+    agents: {},
+  });
+
+  const result = await runDoctorCommand(configPath);
+
+  assert.equal(result.isError, undefined);
+  assert.match(result.text ?? "", /No issues found/);
+});
+
+test("doctor detects custom agent entries", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-doctor-"));
+  const configDir = path.join(tempRoot, ".acpx");
+  await mkdir(configDir, { recursive: true });
+  const configPath = path.join(configDir, "config.json");
+
+  await writeJsonFile(configPath, {
+    defaultAgent: "codex",
+    agents: {
+      codex: { command: "/usr/local/bin/codex" },
+    },
+  });
+
+  const result = await runDoctorCommand(configPath);
+
+  assert.equal(result.isError, undefined);
+  assert.match(result.text ?? "", /custom agent entries/);
+  assert.match(result.text ?? "", /`codex`/);
+  assert.match(result.text ?? "", /doctor fix/);
+});
+
+test("doctor reports no issues when config file is empty", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-doctor-"));
+  const configDir = path.join(tempRoot, ".acpx");
+  await mkdir(configDir, { recursive: true });
+  const configPath = path.join(configDir, "config.json");
+
+  const { writeUtf8 } = await import("../src/utils/fs.ts");
+  await writeUtf8(configPath, "");
+
+  const result = await runDoctorCommand(configPath);
+
+  assert.equal(result.isError, undefined);
+  assert.match(result.text ?? "", /No issues found/);
+});
+
+test("doctor detects invalid JSON", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-doctor-"));
+  const configDir = path.join(tempRoot, ".acpx");
+  await mkdir(configDir, { recursive: true });
+  const configPath = path.join(configDir, "config.json");
+
+  const { writeUtf8 } = await import("../src/utils/fs.ts");
+  await writeUtf8(configPath, '{ "agents": { broken }');
+
+  const result = await runDoctorCommand(configPath);
+
+  assert.equal(result.isError, undefined);
+  assert.match(result.text ?? "", /invalid JSON/);
+});
+
+test("doctor fix clears custom agent entries", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-doctor-"));
+  const configDir = path.join(tempRoot, ".acpx");
+  await mkdir(configDir, { recursive: true });
+  const configPath = path.join(configDir, "config.json");
+
+  await writeJsonFile(configPath, {
+    defaultAgent: "codex",
+    authPolicy: "skip",
+    agents: {
+      codex: { command: "/usr/local/bin/codex" },
+    },
+  });
+
+  const result = await runDoctorCommand(configPath, "fix");
+
+  assert.equal(result.isError, undefined);
+  assert.match(result.text ?? "", /Doctor Fix Applied/);
+
+  const updated = await readJsonFile<Record<string, unknown>>(configPath, {});
+  assert.deepEqual(updated.agents, {});
+  assert.equal(updated.defaultAgent, "codex");
+  assert.equal(updated.authPolicy, "skip");
+});
+
+test("doctor fix reports nothing to fix when agents is already empty", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-doctor-"));
+  const configDir = path.join(tempRoot, ".acpx");
+  await mkdir(configDir, { recursive: true });
+  const configPath = path.join(configDir, "config.json");
+
+  await writeJsonFile(configPath, {
+    defaultAgent: "codex",
+    agents: {},
+  });
+
+  const result = await runDoctorCommand(configPath, "fix");
+
+  assert.equal(result.isError, undefined);
+  assert.match(result.text ?? "", /Nothing to fix/);
+});
+
+test("doctor fix reports error when config has invalid JSON", async () => {
+  const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-doctor-"));
+  const configDir = path.join(tempRoot, ".acpx");
+  await mkdir(configDir, { recursive: true });
+  const configPath = path.join(configDir, "config.json");
+
+  const { writeUtf8 } = await import("../src/utils/fs.ts");
+  await writeUtf8(configPath, '{ broken json');
+
+  const result = await runDoctorCommand(configPath, "fix");
+
+  assert.equal(result.isError, true);
+  assert.match(result.text ?? "", /Cannot auto-fix/);
+});

package/test/helpers/harness.ts

@@ -55,13 +55,17 @@ export function createLogger() {
   };
 }
 
-export async function waitFor(check: () => Promise<boolean>, timeoutMs = 4_000): Promise<void> {
+export async function waitFor(
+  check: () => Promise<boolean>,
+  timeoutMs = 4_000,
+  pollIntervalMs = 250,
+): Promise<void> {
   const startedAt = Date.now();
   while (Date.now() - startedAt < timeoutMs) {
     if (await check()) {
       return;
     }
-    await new Promise((resolve) => setTimeout(resolve, 25));
+    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
   }
   throw new Error("Timed out waiting for test condition.");
 }

package/test/recovery.test.ts

@@ -1,15 +1,18 @@
-import test from "node:test";
+import test, { type TestContext } from "node:test";
 import assert from "node:assert/strict";
 import os from "node:os";
 import path from "node:path";
 import { mkdtemp, mkdir } from "node:fs/promises";
-import { pathExists, readUtf8, writeJsonFile, writeUtf8 } from "../src/utils/fs.ts";
+import { pathExists, readJsonFile, readUtf8, writeJsonFile, writeUtf8 } from "../src/utils/fs.ts";
 import { getRepoStatePaths } from "../src/utils/paths.ts";
 import { RollbackStore } from "../src/rollback/store.ts";
 import { ProjectStateStore } from "../src/state/store.ts";
 import { WatcherManager } from "../src/watchers/manager.ts";
 import { createLogger, waitFor } from "./helpers/harness.ts";
 
+const TEST_WATCHER_POLL_INTERVAL_MS = 250;
+const TEST_WAIT_TIMEOUT_MS = 15_000;
+
 function createWorkOpenSpec(changeDir: string, tasksPath: string) {
   return {
     instructionsApply: async (cwd: string, cn: string) => {
@@ -39,7 +42,25 @@ function createWorkOpenSpec(changeDir: string, tasksPath: string) {
   } as any;
 }
 
-test("recovery from orphaned state (armed, no execution field)", async () => {
+function registerManagerCleanup(t: TestContext, manager: WatcherManager): () => Promise<void> {
+  let stopped = false;
+  const stop = async () => {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    await manager.stop();
+  };
+  t.after(stop);
+  return stop;
+}
+
+async function waitForProjectStatus(repoPath: string, status: "done", timeoutMs = TEST_WAIT_TIMEOUT_MS): Promise<void> {
+  const stateFile = getRepoStatePaths(repoPath, "archives").stateFile;
+  await waitFor(async () => (await readJsonFile<any>(stateFile, null))?.status === status, timeoutMs);
+}
+
+test("recovery from orphaned state (armed, no execution field)", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-recovery-orphan-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -105,12 +126,13 @@ test("recovery from orphaned state (armed, no execution field)", async () => {
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   await manager.start();
-  await waitFor(async () => (await stateStore.getActiveProject(channelKey))?.status === "done");
-  await manager.stop();
+  await waitForProjectStatus(repoPath, "done");
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.equal(project?.status, "done");
@@ -120,7 +142,7 @@ test("recovery from orphaned state (armed, no execution field)", async () => {
   assert.equal(await pathExists(path.join(clawspecDir, "state.json.12345.999999.tmp")), false);
 });
 
-test("recovery from mid-crash running state", async () => {
+test("recovery from mid-crash running state", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-recovery-midcrash-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -178,19 +200,20 @@ test("recovery from mid-crash running state", async () => {
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   await manager.start();
-  await waitFor(async () => (await stateStore.getActiveProject(channelKey))?.status === "done");
-  await manager.stop();
+  await waitForProjectStatus(repoPath, "done");
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.equal(project?.status, "done");
   assert.equal(notifierMessages.some((m) => m.includes("Gateway restarted")), true);
 });
 
-test("startup recovery adopts a live implementation session instead of spawning a new worker", async () => {
+test("startup recovery adopts a live implementation session instead of spawning a new worker", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-recovery-adopt-live-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -274,8 +297,9 @@ test("startup recovery adopts a live implementation session instead of spawning
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   setTimeout(() => {
     void (async () => {
@@ -308,8 +332,8 @@ test("startup recovery adopts a live implementation session instead of spawning
   }, 120);
 
   await manager.start();
-  await waitFor(async () => (await stateStore.getActiveProject(channelKey))?.status === "done");
-  await manager.stop();
+  await waitForProjectStatus(repoPath, "done");
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.equal(project?.status, "done");
@@ -328,7 +352,7 @@ test("startup recovery adopts a live implementation session instead of spawning
   assert.equal(notifierMessages.some((m) => m.includes("Watcher active. Starting codex worker")), false);
 });
 
-test("recovery from recoverable blocked implementation state", async () => {
+test("recovery from recoverable blocked implementation state", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-recovery-blocked-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -421,12 +445,13 @@ test("recovery from recoverable blocked implementation state", async () => {
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   await manager.start();
-  await waitFor(async () => (await stateStore.getActiveProject(channelKey))?.status === "done");
-  await manager.stop();
+  await waitForProjectStatus(repoPath, "done");
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.equal(project?.status, "done");
@@ -435,7 +460,7 @@ test("recovery from recoverable blocked implementation state", async () => {
   assert.equal(notifierMessages.some((m) => m.includes("All tasks complete")), true);
 });
 
-test("rearm never drops execution field (batch mode)", async () => {
+test("rearm never drops execution field (batch mode)", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-rearm-safe-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -497,13 +522,14 @@ test("rearm never drops execution field (batch mode)", async () => {
     logger: createLogger(),
     notifier: { send: async () => undefined } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () => (await stateStore.getActiveProject(channelKey))?.status === "done");
-  await manager.stop();
+  await waitForProjectStatus(repoPath, "done");
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.equal(project?.status, "done");
@@ -511,7 +537,7 @@ test("rearm never drops execution field (batch mode)", async () => {
   assert.equal(turnCount, 1);
 });
 
-test("startup recovery does not spawn a worker for visible chat planning", async () => {
+test("startup recovery does not spawn a worker for visible chat planning", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-recovery-visible-plan-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -561,12 +587,13 @@ test("startup recovery does not spawn a worker for visible chat planning", async
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   await manager.start();
   await new Promise((resolve) => setTimeout(resolve, 150));
-  await manager.stop();
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.equal(runCount, 0);

package/test/watcher-planning.test.ts

@@ -1,15 +1,18 @@
-import test from "node:test";
+import test, { type TestContext } from "node:test";
 import assert from "node:assert/strict";
 import os from "node:os";
 import path from "node:path";
 import { mkdtemp, mkdir } from "node:fs/promises";
-import { pathExists, writeJsonFile, writeUtf8 } from "../src/utils/fs.ts";
+import { pathExists, readJsonFile, writeJsonFile, writeUtf8 } from "../src/utils/fs.ts";
 import { PlanningJournalStore } from "../src/planning/journal.ts";
 import { getRepoStatePaths } from "../src/utils/paths.ts";
 import { ProjectStateStore } from "../src/state/store.ts";
 import { WatcherManager } from "../src/watchers/manager.ts";
 import { createLogger, waitFor } from "./helpers/harness.ts";
 
+const TEST_WATCHER_POLL_INTERVAL_MS = 1_000;
+const TEST_WAIT_TIMEOUT_MS = 35_000;
+
 function createPlanningOpenSpec(changeDir: string, proposalPath: string) {
   return {
     status: async (cwd: string, changeName: string) => ({
@@ -71,7 +74,29 @@ function createPlanningOpenSpec(changeDir: string, proposalPath: string) {
   } as any;
 }
 
-test("watcher planning flow completes", async () => {
+function registerManagerCleanup(t: TestContext, manager: WatcherManager): () => Promise<void> {
+  let stopped = false;
+  const stop = async () => {
+    if (stopped) {
+      return;
+    }
+    stopped = true;
+    await manager.stop();
+  };
+  t.after(stop);
+  return stop;
+}
+
+async function waitForProjectStatus(
+  repoPath: string,
+  status: "ready" | "done" | "blocked" | "planning" | "armed" | "running",
+  timeoutMs = TEST_WAIT_TIMEOUT_MS,
+): Promise<void> {
+  const stateFile = getRepoStatePaths(repoPath, "archives").stateFile;
+  await waitFor(async () => (await readJsonFile<any>(stateFile, null))?.status === status, timeoutMs);
+}
+
+test("watcher planning flow completes", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-watcher-plan-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -113,8 +138,9 @@ test("watcher planning flow completes", async () => {
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   const channelKey = "discord:watch-plan:default:main";
   await stateStore.createProject(channelKey);
@@ -143,8 +169,8 @@ test("watcher planning flow completes", async () => {
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () => (await stateStore.getActiveProject(channelKey))?.status === "ready");
-  await manager.stop();
+  await waitForProjectStatus(repoPath, "ready");
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.equal(project?.status, "ready");
@@ -155,7 +181,7 @@ test("watcher planning flow completes", async () => {
   assert.equal(notifierMessages.some((m) => m.includes("Planning ready") && m.includes("Next: run `cs-work` to start implementation")), true);
 });
 
-test("planning fallback normalizes artifact path", async () => {
+test("planning fallback normalizes artifact path", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-watcher-plan-fallback-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -215,8 +241,9 @@ test("planning fallback normalizes artifact path", async () => {
       cancelSession: async () => undefined,
       closeSession: async () => undefined,
     } as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   const channelKey = "discord:watch-plan-fallback:default:main";
   await stateStore.createProject(channelKey);
@@ -230,14 +257,14 @@ test("planning fallback normalizes artifact path", async () => {
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () => (await stateStore.getActiveProject(channelKey))?.status === "ready");
-  await manager.stop();
+  await waitForProjectStatus(repoPath, "ready");
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.deepEqual(project?.lastExecution?.changedFiles, ["openspec/changes/watch-plan-fallback/proposal.md"]);
 });
 
-test("watcher force-refreshes planning artifacts when journal is dirty and OpenSpec reports all artifacts done", async () => {
+test("watcher force-refreshes planning artifacts when journal is dirty and OpenSpec reports all artifacts done", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-watcher-plan-forced-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -358,8 +385,9 @@ test("watcher force-refreshes planning artifacts when journal is dirty and OpenS
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   const channelKey = "discord:watch-plan-forced:default:main";
   await stateStore.createProject(channelKey);
@@ -398,8 +426,8 @@ test("watcher force-refreshes planning artifacts when journal is dirty and OpenS
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () => (await stateStore.getActiveProject(channelKey))?.status === "ready");
-  await manager.stop();
+  await waitForProjectStatus(repoPath, "ready");
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.deepEqual(runOrder, ["proposal", "specs", "design", "tasks"]);
@@ -412,7 +440,7 @@ test("watcher force-refreshes planning artifacts when journal is dirty and OpenS
   );
 });
 
-test("watcher restarts planning worker after ACP runtime exit", async () => {
+test("watcher restarts planning worker after ACP runtime exit", async (t) => {
   const tempRoot = await mkdtemp(path.join(os.tmpdir(), "clawspec-watcher-plan-restart-"));
   const workspacePath = path.join(tempRoot, "workspace");
   const repoPath = path.join(workspacePath, "demo-app");
@@ -460,8 +488,9 @@ test("watcher restarts planning worker after ACP runtime exit", async () => {
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
+  const stopManager = registerManagerCleanup(t, manager);
 
   const channelKey = "discord:watch-plan-restart:default:main";
   await stateStore.createProject(channelKey);
@@ -490,8 +519,8 @@ test("watcher restarts planning worker after ACP runtime exit", async () => {
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () => (await stateStore.getActiveProject(channelKey))?.status === "ready", 8_000);
-  await manager.stop();
+  await waitForProjectStatus(repoPath, "ready");
+  await stopManager();
 
   const project = await stateStore.getActiveProject(channelKey);
   assert.equal(project?.status, "ready");

package/test/watcher-work.test.ts

@@ -3,17 +3,32 @@ import assert from "node:assert/strict";
 import os from "node:os";
 import path from "node:path";
 import { mkdtemp, mkdir } from "node:fs/promises";
-import { pathExists, readUtf8, writeJsonFile, writeUtf8 } from "../src/utils/fs.ts";
+import { pathExists, readJsonFile, readUtf8, writeJsonFile, writeUtf8 } from "../src/utils/fs.ts";
 import { getRepoStatePaths } from "../src/utils/paths.ts";
 import { RollbackStore } from "../src/rollback/store.ts";
 import { ProjectStateStore } from "../src/state/store.ts";
 import { WatcherManager, describeWorkerStartupTimeout, shouldAbortWorkerStartup } from "../src/watchers/manager.ts";
 import { createLogger, waitFor } from "./helpers/harness.ts";
 
+const TEST_WATCHER_POLL_INTERVAL_MS = 1_000;
+const TEST_WAIT_TIMEOUT_MS = 60_000;
+
 function hasMessage(messages: string[], ...parts: string[]): boolean {
   return messages.some((message) => parts.every((part) => message.includes(part)));
 }
 
+async function readProjectState(repoPath: string) {
+  return await readJsonFile<any>(getRepoStatePaths(repoPath, "archives").stateFile, null);
+}
+
+async function waitForProjectState(
+  repoPath: string,
+  predicate: (project: any) => boolean,
+  timeoutMs = TEST_WAIT_TIMEOUT_MS,
+): Promise<void> {
+  await waitFor(async () => predicate(await readProjectState(repoPath)), timeoutMs);
+}
+
 test("queue owner unavailable is treated as a non-fatal startup state", () => {
   const status = {
     summary: "status=dead acpxRecordId=session-1",
@@ -129,7 +144,7 @@ test("watcher work flow completes", async (t) => {
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -166,9 +181,11 @@ test("watcher work flow completes", async (t) => {
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "done"
-    && hasMessage(notifierMessages, "demo-app-watch-work", "All tasks complete", "/clawspec archive"),
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "done"
+      && hasMessage(notifierMessages, "demo-app-watch-work", "All tasks complete", "/clawspec archive"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);
@@ -325,7 +342,7 @@ test("worker progress events keep running state in sync before execution finishe
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -362,20 +379,17 @@ test("worker progress events keep running state in sync before execution finishe
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () => {
-    const project = await stateStore.getActiveProject(channelKey);
-    return project?.status === "running"
+  await waitForProjectState(repoPath, (project) =>
+    project?.status === "running"
       && project.taskCounts?.complete === 1
       && project.taskCounts?.remaining === 1
       && project.currentTask === "1.2 Add multipart parsing"
       && project.latestSummary?.includes("Start 1.2") === true
-      && project.execution?.currentTaskId === "1.2";
-  });
+      && project.execution?.currentTaskId === "1.2",
+  );
 
   releaseFinalStep();
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "done",
-  );
+  await waitForProjectState(repoPath, (project) => project?.status === "done");
 
   assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-progress-sync", "1/2", "Done 1.1"), true);
   assert.equal(hasMessage(notifierMessages, "demo-app-watch-work-progress-sync", "2/2", "Start 1.2"), true);
@@ -483,7 +497,7 @@ test("watcher restarts implementation worker after ACP runtime exit", async (t)
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -520,10 +534,11 @@ test("watcher restarts implementation worker after ACP runtime exit", async (t)
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "done"
-    && hasMessage(notifierMessages, "demo-app-watch-work-restart", "All tasks complete", "/clawspec archive"),
-    8_000,
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "done"
+      && hasMessage(notifierMessages, "demo-app-watch-work-restart", "All tasks complete", "/clawspec archive"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);
@@ -651,7 +666,7 @@ test("watcher restarts a dead ACP session after progress stalls", async (t) => {
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -688,9 +703,11 @@ test("watcher restarts a dead ACP session after progress stalls", async (t) => {
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "done",
-    8_000,
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "done"
+      && hasMessage(notifierMessages, "demo-app-watch-work-dead-session", "All tasks complete", "/clawspec archive"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);
@@ -798,7 +815,7 @@ test("watcher restarts a dead ACP session that dies before first progress", asyn
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -835,9 +852,11 @@ test("watcher restarts a dead ACP session that dies before first progress", asyn
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "done",
-    8_000,
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "done"
+      && hasMessage(notifierMessages, "demo-app-watch-work-dead-startup", "All tasks complete", "/clawspec archive"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);
@@ -958,7 +977,7 @@ test("status-only ACP heartbeats do not keep a dead session alive", async (t) =>
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -995,9 +1014,11 @@ test("status-only ACP heartbeats do not keep a dead session alive", async (t) =>
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "done",
-    8_000,
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "done"
+      && hasMessage(notifierMessages, "demo-app-watch-work-status-heartbeats", "All tasks complete"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);
@@ -1124,7 +1145,7 @@ test("dead ACP session that ignores abort is restarted without hanging the watch
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     if (heartbeatTimer) {
@@ -1165,9 +1186,11 @@ test("dead ACP session that ignores abort is restarted without hanging the watch
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "done",
-    8_000,
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "done"
+      && hasMessage(notifierMessages, "demo-app-watch-work-hung-dead-session", "All tasks complete"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);
@@ -1205,7 +1228,7 @@ test("manager stop closes active worker sessions and rearms project recovery sta
         closedSessions.push({ sessionKey, reason });
       },
     } as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
 
   const channelKey = "discord:watch-stop:default:main";
@@ -1309,7 +1332,7 @@ test("watcher stops retrying after 10 ACP restart attempts", async (t) => {
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -1347,9 +1370,11 @@ test("watcher stops retrying after 10 ACP restart attempts", async (t) => {
   }));
 
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "blocked",
-    8_000,
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "blocked"
+      && hasMessage(notifierMessages, "demo-app-watch-work-restart-cap", "Blocked after 10 ACP restart attempts"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);
@@ -1415,7 +1440,7 @@ test("watcher blocked message includes ACPX setup guidance when backend stays un
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -1453,9 +1478,11 @@ test("watcher blocked message includes ACPX setup guidance when backend stays un
   }));
 
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "blocked",
-    8_000,
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "blocked"
+      && hasMessage(notifierMessages, "demo-app-watch-work-backend-blocked", "Blocked: ACPX backend unavailable"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);
@@ -1545,7 +1572,7 @@ test("watcher retries when ACP runtime backend is temporarily unavailable", asyn
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -1581,9 +1608,11 @@ test("watcher retries when ACP runtime backend is temporarily unavailable", asyn
   }));
 
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "done",
-    8_000,
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "done"
+      && hasMessage(notifierMessages, "demo-app-watch-work-backend-unavailable", "All tasks complete"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);
@@ -1689,7 +1718,7 @@ test("watcher finalizes when terminal result exists before ACP turn exits", asyn
     logger: createLogger(),
     notifier: { send: async (_: string, text: string) => { notifierMessages.push(text); } } as any,
     acpClient: fakeAcpClient as any,
-    pollIntervalMs: 25,
+    pollIntervalMs: TEST_WATCHER_POLL_INTERVAL_MS,
   });
   t.after(async () => {
     await manager.stop();
@@ -1726,10 +1755,11 @@ test("watcher finalizes when terminal result exists before ACP turn exits", asyn
 
   await manager.start();
   await manager.wake(channelKey);
-  await waitFor(async () =>
-    (await stateStore.getActiveProject(channelKey))?.status === "done"
-    && hasMessage(notifierMessages, "demo-app-watch-work-terminal", "All tasks complete"),
-    8_000,
+  await waitForProjectState(
+    repoPath,
+    (project) =>
+      project?.status === "done"
+      && hasMessage(notifierMessages, "demo-app-watch-work-terminal", "All tasks complete"),
   );
 
   const project = await stateStore.getActiveProject(channelKey);

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

@@ -93,5 +93,5 @@ test("implementation prompt instructs the worker to use the helper", async () =>
   });
 
   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>/);
+  assert.match(prompt, /worker_io\.mjs['"] event --kind <status\|task_start\|task_done\|blocked>/);
 });