clawspec 1.0.15 → 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.15",
+  "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/control/keywords.ts

@@ -1,3 +1,4 @@
+
 export type ClawSpecKeywordKind =
   | "plan"
   | "work"
@@ -59,11 +60,26 @@ export function extractEmbeddedClawSpecKeyword(text: string): ClawSpecKeywordInt
     return direct;
   }
 
-  for (const line of text.split(/\r?\n/)) {
-    const parsed = parseClawSpecKeyword(line.trim());
+  const lines = text.split(/\r?\n/);
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+
+
+    // Try parsing the whole line first
+    const parsed = parseClawSpecKeyword(trimmed);
     if (parsed) {
       return parsed;
     }
+
+    // Try each word in the line
+    const words = trimmed.split(/\s+/);
+    for (const word of words) {
+      const wordParsed = parseClawSpecKeyword(word);
+      if (wordParsed) {
+        return wordParsed;
+      }
+    }
   }
 
   return null;

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,
@@ -6,7 +7,6 @@ import type {
   PluginCommandResult,
   PluginLogger,
 } from "openclaw/plugin-sdk";
-import { debugLog } from "../utils/debug-log.ts";
 import { ProjectMemoryStore } from "../memory/store.ts";
 import { OpenSpecClient, OpenSpecCommandError } from "../openspec/cli.ts";
 import { parseTasksFile } from "../openspec/tasks.ts";
@@ -237,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()}`);
       }
@@ -250,9 +252,7 @@ export class ClawSpecService {
     event: PromptBuildEvent,
     ctx: PromptBuildContext,
   ): Promise<{ prependContext?: string; prependSystemContext?: string } | void> {
-    debugLog(`[handleBeforePromptBuild] prompt="${event.prompt}", trigger=${ctx.trigger}`);
     if (!shouldHandleUserVisiblePrompt(ctx.trigger)) {
-      debugLog(`[handleBeforePromptBuild] Skipped: non-user trigger`);
       this.logger.debug?.(
         `[clawspec] skipping prompt injection for non-user trigger "${ctx.trigger ?? "unknown"}".`,
       );
@@ -260,7 +260,6 @@ export class ClawSpecService {
     }
 
     const keyword = extractEmbeddedClawSpecKeyword(event.prompt);
-    debugLog(`[handleBeforePromptBuild] keyword=${keyword?.command}`);
     if (keyword) {
       this.logger.debug?.(
         `[clawspec] detected control keyword "${keyword.command}" for prompt build (session=${ctx.sessionKey ?? "unknown"}).`,
@@ -320,21 +319,16 @@ export class ClawSpecService {
 
     switch (keyword.kind) {
       case "plan": {
-        debugLog(`[cs-plan] Triggered for project: ${match?.project.changeName}`);
         if (!match?.project.repoPath || !match.project.changeName) {
-          debugLog(`[cs-plan] Missing repoPath or changeName`);
           return this.buildPluginReplyInjection(
             event.prompt,
             "Select a project and create a change first with `/clawspec use <project-name>` and `/clawspec proposal <change-name> [description]`.",
           );
         }
-        debugLog(`[cs-plan] Calling startVisiblePlanningSync`);
         const planningSync = await this.startVisiblePlanningSync(match.channelKey, match.project, ctx, event.prompt, "apply");
         if ("prependContext" in planningSync || "prependSystemContext" in planningSync) {
-          debugLog(`[cs-plan] Returning prompt injection`);
           return planningSync;
         }
-        debugLog(`[cs-plan] Returning plugin reply`);
         return this.buildPluginReplyInjection(event.prompt, planningSync.text ?? "");
       }
       case "work":
@@ -684,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) {
@@ -767,19 +754,15 @@ export class ClawSpecService {
     userPrompt: string,
     mode: ExecutionMode,
   ): Promise<{ prependContext?: string; prependSystemContext?: string } | PluginCommandResult> {
-    debugLog(`[startVisiblePlanningSync] Called for ${project.changeName}`);
-    this.logger.info(`[clawspec] startVisiblePlanningSync called for ${project.changeName}`);
     void project;
     void mode;
 
     const prepared = await this.preparePlanningSync(channelKey);
     if ("result" in prepared) {
-      debugLog(`[startVisiblePlanningSync] preparePlanningSync failed`);
       this.logger.warn(`[clawspec] preparePlanningSync returned error: ${prepared.result.text}`);
       return prepared.result;
     }
 
-    debugLog(`[startVisiblePlanningSync] Updating state to planning`);
     const startedAt = new Date().toISOString();
     const runningProject = await this.stateStore.updateProject(channelKey, (current) => ({
       ...current,
@@ -793,8 +776,6 @@ export class ClawSpecService {
       execution: undefined,
       lastExecutionAt: startedAt,
     }));
-    debugLog(`[startVisiblePlanningSync] State updated: status=${runningProject.status}, phase=${runningProject.phase}, sessionKey=${runningProject.boundSessionKey}`);
-    this.logger.info(`[clawspec] Project state updated: status=planning, phase=planning_sync, boundSessionKey=${runningProject.boundSessionKey}`);
 
     return await this.buildPlanningSyncInjection(runningProject, userPrompt, prepared.instructionResults);
   }
@@ -912,7 +893,6 @@ export class ClawSpecService {
   }
 
   async handleAgentEnd(event: AgentEndEvent, ctx: PromptBuildContext): Promise<void> {
-    debugLog(`[agent_end] Called, sessionKey=${ctx.sessionKey}`);
     const runningProject = await this.findRunningProjectBySessionKey(ctx.sessionKey);
     if (runningProject?.repoPath && runningProject.changeName) {
       const project = runningProject;
@@ -977,10 +957,7 @@ export class ClawSpecService {
 
     const planningProject = await this.findPlanningProjectBySessionKey(ctx.sessionKey)
       ?? await this.findPlanningProjectByContext(ctx);
-    debugLog(`[agent_end] Planning project: ${planningProject?.changeName}, status=${planningProject?.status}, phase=${planningProject?.phase}`);
     if (planningProject) {
-      debugLog(`[agent_end] Calling finalizePlanningTurn`);
-      this.logger.info(`[clawspec] agent_end: found planning project ${planningProject.changeName}, calling finalizePlanningTurn`);
       await this.finalizePlanningTurn(planningProject, event);
       return;
     }
@@ -1930,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) {
@@ -2428,10 +2410,7 @@ export class ClawSpecService {
   }
 
   private async finalizePlanningTurn(project: ProjectState, event: AgentEndEvent): Promise<void> {
-    debugLog(`[finalizePlanningTurn] Called for ${project.changeName}, success=${event.success}`);
-    this.logger.info(`[clawspec] finalizePlanningTurn called for ${project.changeName}, success=${event.success}`);
     if (!project.repoPath || !project.changeName) {
-      debugLog(`[finalizePlanningTurn] Skipped: missing repoPath or changeName`);
       this.logger.warn(`[clawspec] finalizePlanningTurn skipped: missing repoPath or changeName`);
       return;
     }
@@ -2491,11 +2470,7 @@ export class ClawSpecService {
       }
     }
 
-    debugLog(`[finalizePlanningTurn] Writing snapshot`);
     const snapshot = await journalStore.writeSnapshot(repoStatePaths.planningJournalSnapshotFile, project.changeName, timestamp);
-    debugLog(`[finalizePlanningTurn] Snapshot written: entryCount=${snapshot.entryCount}, lastEntryAt=${snapshot.lastEntryAt}`);
-    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) => ({
@@ -3323,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/watchers/notifier.ts

@@ -50,6 +50,7 @@ export class ClawSpecNotifier {
           });
           return;
         default:
+          // Webchat and other channels: log only (no direct API available)
           this.logger.info(`[clawspec] watcher update (${route.channel} ${route.channelId}): ${text}`);
       }
     } catch (error) {

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/);