clawspec 1.0.16 → 1.0.20

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.20",
   "type": "module",
   "description": "OpenClaw plugin that orchestrates OpenSpec project workflows with visible main-agent execution.",
   "keywords": [
@@ -23,7 +23,6 @@
     "index.ts",
     "src",
     "skills",
-    "test",
     "README.md",
     "README.zh-CN.md",
     "openclaw.plugin.json",
@@ -46,7 +45,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;
     }
@@ -2781,7 +2795,7 @@ function parseWorkerProgressEvent(line: string): WorkerProgressEvent | undefined
 
 function formatWorkerProgressMessage(project: ProjectState, event: WorkerProgressEvent): string | undefined {
   const rawMessage = typeof event.message === "string" ? event.message : "";
-  const message = shortenActivityText(rawMessage, 120);
+  const message = shortenActivityText(compactWorkerProgressDisplayPaths(project, rawMessage), 120);
   if (!message) {
     return undefined;
   }
@@ -2902,6 +2916,74 @@ function compactProjectLabel(project: ProjectState): string {
   return `${projectName}-${changeName}`;
 }
 
+function compactWorkerProgressDisplayPaths(project: ProjectState, text: string): string {
+  try {
+    const compactRoot = compactWorkerProgressRoot(project);
+    if (!compactRoot) {
+      return text;
+    }
+
+    let compacted = text;
+    if (project.changeDir) {
+      compacted = replaceDisplayPathPrefix(compacted, project.changeDir, `${compactRoot}:`);
+    }
+    if (project.repoPath) {
+      compacted = replaceDisplayPathPrefix(compacted, project.repoPath, `${compactRoot}:`);
+    }
+    compacted = normalizeCompactedDisplayPaths(compacted, compactRoot);
+    return compacted.length < text.length ? compacted : text;
+  } catch {
+    return text;
+  }
+}
+
+function compactWorkerProgressRoot(project: ProjectState): string | undefined {
+  const changeName = project.changeName?.trim();
+  if (!changeName) {
+    return undefined;
+  }
+  const projectName = project.projectName?.trim()
+    || (project.repoPath ? path.basename(project.repoPath) : undefined)
+    || "project";
+  return `${projectName}@${changeName}`;
+}
+
+function replaceDisplayPathPrefix(text: string, targetPath: string, replacement: string): string {
+  const pattern = buildDisplayPathPrefixPattern(targetPath);
+  if (!pattern) {
+    return text;
+  }
+  return text.replace(pattern, replacement);
+}
+
+function normalizeCompactedDisplayPaths(text: string, compactRoot: string): string {
+  const prefix = escapeRegExp(`${compactRoot}:`);
+  const pattern = new RegExp("(" + prefix + ")([^\\s\"'`,)\\]}]+)", "g");
+  return text.replace(pattern, (_match, prefix: string, suffix: string) => `${prefix}${suffix.replace(/\\/g, "/")}`);
+}
+
+function buildDisplayPathPrefixPattern(targetPath: string): RegExp | undefined {
+  const normalized = normalizeSlashes(targetPath).replace(/\/+$/, "");
+  if (!normalized) {
+    return undefined;
+  }
+
+  const escaped = normalized
+    .split("/")
+    .map((segment) => escapeRegExp(segment))
+    .join("[/\\\\]+");
+  if (!escaped) {
+    return undefined;
+  }
+
+  const flags = /^[A-Za-z]:/.test(normalized) ? "gi" : "g";
+  return new RegExp(`${escaped}(?:[/\\\\]+)?`, flags);
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
 function compactProgressMarker(current?: number, total?: number): string {
   if (!total || total <= 0 || !current || current <= 0) {
     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`;
 }