@zhushanwen/pi-cw-tool 0.4.2 → 0.5.0

package/src/cw-runner.ts

@@ -1,66 +1,55 @@
 /**
- * cw action 执行核心：白名单校验 + 参数构造 + spawn + 输出解析。
+ * cw 只读查询核心：白名单校验 + 参数构造 + spawn + 输出解析。
+ *
+ * cw 2.0 适配（Phase 2-B）：cw 2.0 删除了 1.x 的声明推进命令面（design/execute/
+ * handoff 等），编排智能收进引擎（`cw run` runner + 账本 gate）。本扩展不再包写
+ * 命令——写操作（create / evidence submit / review submit / verify / run）由
+ * agent 经 bash 直接调 `cw`（用法见 cw-cli skill），本扩展只提供只读查询的结构化
+ * 工具入口（cw_query：status / frontier / tree / report）。
+ *
+ * 1.x 的 workspace 门控（detectRepoWorkspace + --workspace 透传 + cw 版本探测）
+ * 已随 2.0 适配删除：cw 2.0 store 布局为 `~/.cw/<encoded-cwd>/`（per-cwd，无
+ * --workspace 参数），spawn 时传 cwd 即可。
  *
  * 与 Pi SDK 解耦（不 import pi 类型），纯逻辑 + 可注入 spawner，便于单测。
  * 所有错误路径返回 `{ ok: false, error }`，不抛异常（由调用方映射为 tool 返回）。
  */
-import { spawnSync } from "node:child_process";
-import * as path from "node:path";
-
 import type { CwSpawner } from "./cw-spawn.ts";
 
-/** cw 全部 action 名（E1 后：clarify 已删、plan→design）。透传 cw，与 cw-cli ALL_ACTIONS 对齐。 */
-export const CW_ACTIONS = [
-	"create",
-	"design",
-	"design-review",
-	"execute",
-	"test",
-	"exec-review",
-	"retrospect",
-	"closeout",
-	"replan",
-	"abort",
-	"list",
-	"tree",
-	"status",
-	"handoff",
-	"frontier",
-] as const;
-export type CwAction = (typeof CW_ACTIONS)[number];
-
-/** 只读 action（不推进状态机，query only）。 */
-export const READONLY_ACTIONS = ["list", "tree", "status", "handoff", "frontier"] as const;
-
 /**
- * 判断 action 是否为只读（属于 {@link READONLY_ACTIONS}）。
- *
- * 只读 action 的两个边界复用此判定（S-3/S-5）：
- * - 不附加 `--workspace`（保守避免 cw 子命令拒收未知选项导致 readonly 查询失败，S-3）；
- * - 不强制 unitId（list/tree/frontier 等全局查询不需要具体 unit，S-5）。
+ * cw_query 工具的 action 白名单 = cw 2.0 只读命令面（dist/readonly/index.ts，
+ * 2026-08-22 以 coding-workflow@2.0.1 核实）。
  *
- * 用 `.some(===)` 而非 `.includes()` 以保持 string 入参的类型安全（readonly tuple 的
- * `.includes()` 要求字面量联合类型，传 string 会报错，无需 `as` 宽化）。
+ * 写命令（create / evidence submit / review submit / verify / run）不在工具面——
+ * 需要推进流程时经 bash 调 `cw`，用法以 cw-cli skill 为 SSOT。
  */
-export function isReadonlyAction(action: string): boolean {
-	return READONLY_ACTIONS.some((a) => a === action);
-}
+export const CW_ACTIONS = ["status", "frontier", "tree", "report"] as const;
+export type CwAction = (typeof CW_ACTIONS)[number];
+
+/** 支持 `--json` 的 action（cw 2.0 规格锁定：仅 status / frontier）。 */
+const JSON_ACTIONS = ["status", "frontier"] as const;
 
-/** 透传给 cw 的可选参数（flags）。 */
+/** 支持 `--unit` 选择器的 action（status / report；tree / frontier 为全局视图）。 */
+const UNIT_ACTIONS = ["status", "report"] as const;
+
+/** 支持 `--root` 子树选择器的 action（仅 report；2.0 frontier 无 --root）。 */
+const ROOT_ACTIONS = ["report"] as const;
+
+/** 透传给 cw 的可选查询参数。 */
 export interface CwToolOptions {
-	/** JSON 内容字符串，经 stdin 传给 cw（`cw --input -`）。与 inputFile 互斥。 */
-	input?: string;
-	/** input 文件路径，直接传 `--input <path>`。与 input 互斥。 */
-	inputFile?: string;
-	/** execute 关联的 commit（wave 层），传 `--commitHash`。 */
-	commitHash?: string;
+	/** unit id → `--unit <id>`（status 单 unit 详情 / report 单 unit 证据链）。 */
+	unitId?: string;
+	/** 子树根 id → `--root <id>`（report 子树汇总；与 unitId 互斥）。 */
+	rootId?: string;
+	/** 结构化输出 → `--json`（仅 status / frontier）。 */
+	json?: boolean;
 }
 
 /** 工具返回的 details 结构（结构化成功/失败，调用方按 `ok` 区分）。 */
 export type CwDetails =
-	| { ok: true; action: string; unitId: string | undefined; stdout: string; parsed: true; data: unknown }
-	| { ok: true; action: string; unitId: string | undefined; stdout: string; parsed: false }
-	| { ok: false; action: string; unitId: string | undefined; error: string };
+	| { ok: true; action: string; stdout: string; parsed: true; data: unknown }
+	| { ok: true; action: string; stdout: string; parsed: false }
+	| { ok: false; action: string; error: string };
 
 /**
  * 白名单校验。返回错误消息（string）或 undefined（放行）。
@@ -75,224 +64,56 @@ export function rejectDisallowedAction(
 	toolName: string,
 ): string | undefined {
 	if (!allowed.includes(action)) {
-		return `action "${action}" 不在 ${toolName} 白名单。允许的 action: ${allowed.join(", ")}`;
+		return `action "${action}" 不在 ${toolName} 白名单。允许的 action: ${allowed.join(", ")}。写命令（create / evidence / review / verify / run）请经 bash 调 cw，用法见 cw-cli skill。`;
 	}
 	return undefined;
 }
 
-/** git 探测超时（ms）：git 卡死时避免阻塞 agent turn。 */
-const GIT_PROBE_TIMEOUT_MS = 5000;
-
-/**
- * 探测 cwd 所属 repo 的主目录（repo 级 workspace），供老 cw-cli（<1.6.2，无 store 归一化）兜底。
- *
- * 用 `git rev-parse --path-format=absolute --git-common-dir` 取 git common dir：
- * 同一 repo 的所有 worktree 返回相同路径，dirname 即 repo 主目录。cw store 键控
- * 从 per-cwd 升级为 repo 级（cw-cli ADR-0014）后，spawn cw 时附带 --workspace 让 cw
- * 在 repo 主目录解析/共享状态，避免同一 repo 的 worktree 间状态各自为政。
- *
- * **bare repo + worktree 模式（.bare）**：common-dir basename 是 `.bare` 而非 `.git`，
- * dirname 指向 workspace 容器根（非 git 目录）——传给 cw 会让它 fallback 到错误的 store-key
- * （unit not found）。检测到 basename 非 `.git` 时返回 undefined（不传 --workspace），让老 cw-cli
- * 退回 per-cwd store（读写一致但无 repo 级共享）。新 cw-cli（≥1.6.2）自己归一化，门控支持→不调本函数。
- * 不可用 `--is-bare-repository` 判据——worktree 内它永远返回 false（bare 是 .bare 目录本身）。
- *
- * 任何失败（非 git 目录、git 不在 PATH、路径不存在、超时）→ undefined（不抛）。
- */
-export function detectRepoWorkspace(cwd: string): string | undefined {
-	try {
-		const result = spawnSync(
-			"git",
-			["-C", cwd, "rev-parse", "--path-format=absolute", "--git-common-dir"],
-			{ encoding: "utf8", timeout: GIT_PROBE_TIMEOUT_MS },
-		);
-		if (result.status !== 0) return undefined;
-		const gitCommonDir = result.stdout.trim();
-		if (gitCommonDir.length === 0) return undefined;
-		// 非标准 git-dir 一律退回 per-cwd（fail-safe）：bare repo worktree（basename=.bare，
-		// dirname 指向容器根，非 git 目录）、submodule（common-dir=.git/modules/<name>）、
-		// --separate-git-dir / GIT_DIR 等。把 dirname 传给 cw 会导致 store-key fallback 错误
-		// → unit not found。返回 undefined 退回 per-cwd（读写一致）。
-		if (path.basename(gitCommonDir) !== ".git") return undefined;
-		return path.dirname(gitCommonDir);
-	} catch {
-		return undefined;
-	}
-}
-
-/**
- * cw-cli 支持 store 内部归一化的最低版本（门控阈值）。
- *
- * cw-tool 与 cw-cli 是两个独立 npm 包（cw-tool 经 PATH 裸调 cw、零依赖声明），
- * 两包独立升级。cw-tool 退回纯封装前需探测 cw-cli 是否已落地 store 归一化
- * （cw-cli commit a90e8e8 / 首个 tag v1.6.2：getCwJsonPath 改用 detectCommonDir 归一化
- * 到 git-common-dir），支持则不传 --workspace（纯封装），不支持则兜底 cw-cli ADR-0014
- * 的 detectRepoWorkspace + --workspace。
- *
- * 门控激活（1.6.2）：cw-cli ≥1.6.2 自我用 detectCommonDir 归一化 store-key，同一 repo 的
- * 所有 worktree（含 bare repo）共享 store，cw-tool 无需传 --workspace。旧值 "99.0.0"（placeholder）
- * 使门控永远判定「不支持」→ 永远走兜底，在 bare repo worktree 下 detectRepoWorkspace 返回容器根
- * → cw 定位到不存在的 store → unit not found。
- */
-const MIN_CW_CLI_VERSION_FOR_NORMALIZATION = "1.6.2";
-
-/** probe 超时（ms）：cw --version 卡死时 fail-safe 为「不支持」。 */
-const CW_VERSION_PROBE_TIMEOUT_MS = 5000;
-
-/** 版本 parse 失败时 reason 截断长度（避免 stdout 过长污染日志）。 */
-const VERSION_REASON_MAX_LEN = 60;
-
-/** cw-cli 能力探测结果。 */
-export interface CwCliCapability {
-	/** true = cw-cli 支持 store 内部归一化（cw-tool 应纯封装，不传 --workspace）。 */
-	supported: boolean;
-	/** parse 到的 cw 版本号（如 "1.6.1"），parse 失败 = undefined。 */
-	version: string | undefined;
-	/** 不支持/失败的简要原因（日志/调试用）。 */
-	reason?: string;
-}
-
-/**
- * 进程内 memoize 缓存：全局单值（cw --version 输出与 cwd 无关，cw-cli 安装版本在进程
- * 生命周期内不变，按 cwd 做 key 多余）。首次探测后整个进程复用；测试用
- * {@link _resetCapabilityCacheForTest} 在 beforeEach 隔离。
- */
-let cachedCapability: CwCliCapability | undefined;
-
-/** 测试用：重置 capability 缓存（全局单值，测试 beforeEach 隔离避免串台）。 */
-export function _resetCapabilityCacheForTest(): void {
-	cachedCapability = undefined;
-}
-
-/** 从 cw --version stdout 提取版本号（如 "cw 1.6.1" → [1,6,1]）。失败返回 undefined。 */
-function parseCwVersion(stdout: string): number[] | undefined {
-	const match = stdout.match(/(\d+)\.(\d+)\.(\d+)/);
-	if (!match) return undefined;
-	return [Number.parseInt(match[1], 10), Number.parseInt(match[2], 10), Number.parseInt(match[3], 10)];
-}
-
-/** semver 三段比较：a < b → -1，a === b → 0，a > b → 1。 */
-function compareSemver(a: number[], b: number[]): number {
-	for (let i = 0; i < a.length; i++) {
-		if (a[i] !== b[i]) return a[i] < b[i] ? -1 : 1;
-	}
-	return 0;
-}
+const includesStr = (list: readonly string[], v: string): boolean => list.some((a) => a === v);
 
 /**
- * 探测 cw-cli 是否支持 store 内部归一化（门控）。
+ * 查询参数合法性校验（action × flag 匹配 + 互斥）。返回错误消息或 undefined（放行）。
  *
- * 用 spawner 跑 `cw --version`，parse 版本号与 {@link MIN_CW_CLI_VERSION_FOR_NORMALIZATION}
- * 比较。失败（spawn 失败/parse 不到/超时）→ supported:false（fail-safe，兜底 cw-cli ADR-0014 行为）。
- * 进程内 memoize（全局单值，cw 版本 cwd 无关）：首次探测后缓存，消除重复 spawn。
- *
- * @param parentSignal 调用方 SDK abort signal，与内部 5s 超时合并转发给 spawner（S-4）：
- *   任一 abort 即 abort，让卡死的 `cw --version` 尽快收尾。
+ * report 的 `--unit` / `--root` 在 cw 2.0 互斥；非 report 传 rootId、非 status/frontier
+ * 传 json 属于本工具面错误（cw 2.0 对应命令不接受该 flag），前置拦截给出可操作错误。
  */
-export async function probeCwCliNormalization(
-	spawner: CwSpawner,
-	cwd: string,
-	parentSignal?: AbortSignal,
-): Promise<CwCliCapability> {
-	if (cachedCapability) return cachedCapability;
-
-	const minVersion = parseCwVersion(MIN_CW_CLI_VERSION_FOR_NORMALIZATION);
-	if (!minVersion) {
-		// MIN_CW_CLI_VERSION_FOR_NORMALIZATION 本身非法（不应发生）——保守不支持
-		const fallback: CwCliCapability = { supported: false, version: undefined, reason: "MIN_CW_CLI_VERSION_FOR_NORMALIZATION 非法" };
-		cachedCapability = fallback;
-		return fallback;
+export function rejectInvalidQueryOptions(
+	action: string,
+	opts: CwToolOptions,
+): string | undefined {
+	if (opts.unitId !== undefined && !includesStr(UNIT_ACTIONS, action)) {
+		return `action "${action}" 不支持 unitId（仅 ${UNIT_ACTIONS.join(" / ")} 接受 --unit）。`;
 	}
-
-	const controller = new AbortController();
-	const timer = setTimeout(() => controller.abort(), CW_VERSION_PROBE_TIMEOUT_MS);
-	// 合并调用方 SDK signal：任一 abort（5s 超时 fail-safe 或调用方主动 abort）即 abort（S-4）。
-	const onParentAbort = (): void => controller.abort();
-	if (parentSignal) {
-		if (parentSignal.aborted) controller.abort();
-		else parentSignal.addEventListener("abort", onParentAbort, { once: true });
+	if (opts.rootId !== undefined && !includesStr(ROOT_ACTIONS, action)) {
+		return `action "${action}" 不支持 rootId（仅 ${ROOT_ACTIONS.join(" / ")} 接受 --root）。`;
 	}
-	let result: CwCliCapability;
-	try {
-		const spawnResult = await spawner(["--version"], undefined, cwd, controller.signal);
-		if (spawnResult.exitCode !== 0) {
-			result = { supported: false, version: undefined, reason: `cw --version exit ${spawnResult.exitCode ?? "null"}` };
-		} else {
-			const v = parseCwVersion(spawnResult.stdout);
-			if (!v) {
-				result = { supported: false, version: undefined, reason: `version parse fail: ${spawnResult.stdout.trim().slice(0, VERSION_REASON_MAX_LEN)}` };
-			} else {
-				const supported = compareSemver(v, minVersion) >= 0;
-				result = { supported, version: v.join("."), reason: supported ? undefined : `version ${v.join(".")} < ${MIN_CW_CLI_VERSION_FOR_NORMALIZATION}` };
-			}
-		}
-	} catch (err) {
-		const msg = err instanceof Error ? err.message : String(err);
-		result = { supported: false, version: undefined, reason: `probe failed: ${msg}` };
-	} finally {
-		clearTimeout(timer);
-		if (parentSignal) parentSignal.removeEventListener("abort", onParentAbort);
+	if (opts.json === true && !includesStr(JSON_ACTIONS, action)) {
+		return `action "${action}" 不支持 json（cw 2.0 仅 ${JSON_ACTIONS.join(" / ")} 提供 --json）。`;
 	}
-
-	cachedCapability = result;
-	return result;
-}
-
-/** input / inputFile 互斥校验。 */
-export function rejectConflictingInput(opts: CwToolOptions): string | undefined {
-	if (opts.input !== undefined && opts.inputFile !== undefined) {
-		return "'input' 和 'inputFile' 互斥，只能传其中一个。";
+	if (opts.unitId !== undefined && opts.rootId !== undefined) {
+		return "unitId 与 rootId 互斥（cw report 的 --unit / --root 只能传其中一个）。";
 	}
 	return undefined;
 }
 
 /**
- * unitId 缺失校验（S-5）。写 action 缺 unitId → 返回错误消息；只读 action 或已传 unitId → undefined（放行）。
+ * 构建 cw 命令行参数（action 后接 flags），flag 顺序 = 上方各 action 的注释序。
  *
- * schema 已把 unitId 改为 Optional（只读 action 不需要），此函数是写 action 的运行时第二道约束
- * （直接/程序化调用、宽松 provider 兜底），与 rejectDisallowedAction / rejectConflictingInput 同族。
+ * - status：`[--unit <id>] [--json]`
+ * - frontier：`[--json]`
+ * - tree：无 flag
+ * - report：`--unit <id>` 或 `--root <id>`（互斥，均省略 = 全账本）
  */
-export function rejectMissingUnitId(action: string, unitId: string | undefined): string | undefined {
-	if (unitId === undefined && !isReadonlyAction(action)) {
-		return `action "${action}" 需要 unitId（只读 action ${READONLY_ACTIONS.join("/")} 可省略）`;
-	}
-	return undefined;
-}
-
-/**
- * 构建 cw 命令行参数（action 后接 flags）。
- *
- * - unitId（若提供）→ `--unitId <id>`；undefined 则省略（只读 action 不需要，S-5）
- * - input 内容 → `--input -`（经 stdin，见 executeCwAction）
- * - inputFile 路径 → `--input <path>`
- * - commitHash → `--commitHash <sha>`
- * - workspace（repo 主目录，由调用方经 detectRepoWorkspace 探测）→ `--workspace <path>`，位于 --commitHash 之后
- */
-export function buildCwArgs(
-	action: string,
-	unitId: string | undefined,
-	opts: CwToolOptions,
-	workspace?: string,
-): string[] {
+export function buildCwArgs(action: string, opts: CwToolOptions): string[] {
 	const args: string[] = [action];
-	if (unitId !== undefined) {
-		args.push("--unitId", unitId);
+	if (opts.unitId !== undefined) {
+		args.push("--unit", opts.unitId);
+	} else if (opts.rootId !== undefined) {
+		args.push("--root", opts.rootId);
 	}
-
-	if (opts.inputFile) {
-		args.push("--input", opts.inputFile);
-	} else if (opts.input !== undefined) {
-		args.push("--input", "-");
+	if (opts.json === true) {
+		args.push("--json");
 	}
-
-	if (opts.commitHash) {
-		args.push("--commitHash", opts.commitHash);
-	}
-
-	if (workspace) {
-		args.push("--workspace", workspace);
-	}
-
 	return args;
 }
 
@@ -311,68 +132,42 @@ function tryParseJson(text: string): unknown | undefined {
 const DEFAULT_CW_TIMEOUT_MS = 300_000;
 
 /**
- * 执行 cw action 的核心逻辑：白名单校验 → 参数冲突校验 → spawn → 解析。
+ * 执行 cw 只读查询的核心逻辑：白名单校验 → 参数校验 → spawn → 解析。
  *
- * 失败判定：非零退出码（含被信号终止的 null）→ ok:false（stderr 折进错误消息；S-2 按 exitCode 判定）。
+ * 失败判定：非零退出码（含被信号终止的 null）→ ok:false（stderr 折进错误消息）。
  * 成功后 stdout 尝试 JSON.parse：成功 → parsed:true + data；失败 → parsed:false + 原样 stdout。
  *
  * @param action   调用方请求的 action（运行时再校验白名单）。
  * @param allowed  该工具允许的 action 白名单。
  * @param toolName 工具名（错误消息归属用）。
- * @param unitId   cw unit id（写 action 必传；只读 action 可省略，见 rejectMissingUnitId）。
- * @param opts     可选 flags。
- * @param spawner   spawn 实现（默认走真实 cw，测试注入 fake）。
- * @param cwd       子进程工作目录。
- * @param signal    可选 SDK abort signal；与超时合并后透传给 spawner，abort 时 spawner kill 子进程。
+ * @param opts     查询参数（unitId / rootId / json）。
+ * @param spawner  spawn 实现（默认走真实 cw，测试注入 fake）。
+ * @param cwd      子进程工作目录（cw 2.0 以 cwd 定位 `~/.cw/<encoded-cwd>/` 账本）。
+ * @param signal   可选 SDK abort signal；与超时合并后透传给 spawner，abort 时 spawner kill 子进程。
  * @param timeoutMs spawn 超时（ms），默认 5 分钟；0 表示不限时。超时返回 ok:false "cw 超时"。
  */
 export async function executeCwAction(
 	action: string,
 	allowed: readonly string[],
 	toolName: string,
-	unitId: string | undefined,
 	opts: CwToolOptions,
 	spawner: CwSpawner,
 	cwd: string,
 	signal?: AbortSignal,
 	timeoutMs: number = DEFAULT_CW_TIMEOUT_MS,
 ): Promise<CwDetails> {
-	const base = { action, unitId };
+	const base = { action };
 
 	const actionErr = rejectDisallowedAction(action, allowed, toolName);
 	if (actionErr) return { ok: false, ...base, error: actionErr };
 
-	const inputErr = rejectConflictingInput(opts);
-	if (inputErr) return { ok: false, ...base, error: inputErr };
+	const queryErr = rejectInvalidQueryOptions(action, opts);
+	if (queryErr) return { ok: false, ...base, error: queryErr };
 
-	// unitId 运行时校验（S-5）：写 action 缺 unitId → 清晰错误（schema 已把 unitId 改 Optional）。
-	const unitIdErr = rejectMissingUnitId(action, unitId);
-	if (unitIdErr) return { ok: false, ...base, error: unitIdErr };
-
-	// workspace 门控（cw-cli ADR-0014 store-workspace decoupling）：cw-cli 支持 store 内部归一化
-	// （probe 版本 >= MIN_CW_CLI_VERSION_FOR_NORMALIZATION）→ 纯封装不传 --workspace；
-	// 不支持 → 兜底 cw-cli ADR-0014 的 detectRepoWorkspace + --workspace（保持向后兼容）。
-	// 只读 action 始终不传（S-3：保守避免 cw 子命令拒收未知选项导致 readonly 查询失败）。
-	let workspace: string | undefined;
-	// 降级标记：老 cw-cli（不支持归一化）+ bare repo / 非 git（detectRepoWorkspace 返回 undefined）。
-	// 写动作若失败，错误消息追加升级指引（准则 6：错误指向恢复动作）。
-	let degradedNoWorkspace = false;
-	if (isReadonlyAction(action)) {
-		workspace = undefined;
-	} else {
-		const capability = await probeCwCliNormalization(spawner, cwd, signal);
-		if (capability.supported) {
-			workspace = undefined;
-		} else {
-			workspace = detectRepoWorkspace(cwd);
-			degradedNoWorkspace = workspace === undefined;
-		}
-	}
-	const args = buildCwArgs(action, unitId, opts, workspace);
-	const stdinPayload = opts.input !== undefined ? opts.input : undefined;
+	const args = buildCwArgs(action, opts);
 
 	// 合并 SDK abort signal 与超时为单个 signal 传给 spawner：spawner（默认实现）在 abort
-	// 时 kill 子进程，避免 abort/超时后僵尸 cw 继续推进状态机。
+	// 时 kill 子进程，避免 abort/超时后僵尸 cw 进程。
 	const combined = new AbortController();
 	let timedOut = false;
 	const onSdkAbort = (): void => combined.abort();
@@ -390,7 +185,7 @@ export async function executeCwAction(
 
 	let result;
 	try {
-		result = await spawner(args, stdinPayload, cwd, combined.signal);
+		result = await spawner(args, undefined, cwd, combined.signal);
 	} catch (err) {
 		const msg = err instanceof Error ? err.message : String(err);
 		return { ok: false, ...base, error: `cw spawn 失败: ${msg}` };
@@ -404,20 +199,12 @@ export async function executeCwAction(
 
 	const { stdout, stderr, exitCode } = result;
 
-	// S-2：按 exitCode 判定失败（防御性，不依赖 cw 是否向 stderr 写非错误诊断信息）。
+	// 按 exitCode 判定失败（防御性，不依赖 cw 是否向 stderr 写非错误诊断信息）。
 	// 非零退出码（含 null=被信号终止）→ 失败；stderr 折进错误消息（成功时 stderr 不导致失败）。
 	if (exitCode !== 0) {
 		const parts: string[] = [`exit code ${exitCode ?? "null"}`];
 		if (stderr.trim()) parts.push(stderr.trim());
-		let error = parts.join(" | ");
-		// 老 cw-cli（<1.6.2）+ 探测不到 repo 级 workspace（非 git 目录 / bare repo worktree /
-		// git 不可用）：写动作退回 per-cwd store（读写一致但无 repo 级共享），多数情况能跑通；
-		// 若仍失败，追加升级指引帮用户切到归一化 cw-cli（准则 6：错误指向恢复动作）。
-		// 措辞同时覆盖两种降级原因（非 git 场景不误导为 bare repo 问题）。
-		if (degradedNoWorkspace) {
-			error += "\n👉 cw-cli 版本过低（<1.6.2 不支持 store-key 归一化），且当前目录未探测到 repo 级 workspace（非 git 目录 / bare repo worktree / git 不可用），写动作退回 per-cwd store（读写一致但无 repo 级共享）。建议升级：npm i -g @zhushanwen/coding-workflow@latest";
-		}
-		return { ok: false, ...base, error };
+		return { ok: false, ...base, error: parts.join(" | ") };
 	}
 
 	const data = tryParseJson(stdout);

package/src/cw-spawn.ts

@@ -6,9 +6,28 @@
  *
  * cw 路径解析：spawn 裸命令名 `cw`，由 OS execvp 语义在 `process.env.PATH` 中
  * 查找（架构约定 #16：禁止写死绝对路径）。env 继承自 process.env，确保 PATH 可用。
+ *
+ * [worktree-reaper-fix] cwd 可能已被 orphan reaper 清理（pi-subagent-workflow 误删活
+ * worktree 后子进程 cwd 指向虚空）。Node spawn 对不存在的 cwd 报 ENOENT，错误消息只含
+ * command 名（"cw"）不含 cwd——2026-08-11 事故中导致 AI 误诊"node 被卸载"。故 spawn 前
+ * 检查 cwd 存在性，失败时返回可操作错误（含完整 cwd + 恢复指引）。
  */
+import { existsSync } from "node:fs";
 import { spawn } from "node:child_process";
 
+/**
+ * cwd 不存在时的可操作错误文案（错误 → 权威源 worktrees.json → 重试闭环）。
+ * @param cwd 不存在的路径
+ */
+function cwdMissingError(cwd: string): string {
+	return [
+		`cwd 不存在：${cwd}`,
+		"该 worktree 可能已被 orphan reaper 清理，或子 agent 已结束。",
+		"恢复：1) 检查 pi agent 目录下 subagents/worktrees.json 中该 branch 的 pid 是否已补全；",
+		"      2) 若子 agent 仍在运行，重新派发（worktree 重建）；3) 若已结束，忽略此错误。",
+	].join("\n");
+}
+
 /** cw 子进程执行结果。 */
 export interface CwSpawnResult {
 	/** stdout 内容（cw action 通常把结果 JSON 输出到 stdout）。 */
@@ -26,7 +45,7 @@ export interface CwSpawnResult {
  * @param input  要写入子进程 stdin 的内容；undefined 表示不写（cw 不读 stdin）。
  * @param cwd    子进程工作目录。
  * @param signal 可选 abort signal；实现应在 abort 时 kill 子进程（见 defaultCwSpawner），
- *               避免 abort 后僵尸 cw 子进程继续推进状态机（executeCwAction 把 SDK signal +
+ *               避免 abort 后僵尸 cw 子进程继续运行（executeCwAction 把 SDK signal +
  *               超时合并为此 signal 传入）。
  */
 export type CwSpawner = (
@@ -42,11 +61,18 @@ export type CwSpawner = (
  * - stdout/stderr 设 utf8 编码后全量捕获（data 回调收 string，无需 Buffer 处理）。
  * - input（若提供）写入 stdin 后关闭；未提供则直接 end（cw 不阻塞等待 stdin）。
  * - spawn 自身失败（如 cw 不在 PATH）走 'error' 事件，拼进 stderr、exitCode=-1 标记异常。
- * - signal abort 时 kill 子进程（SIGTERM），避免 abort 后僵尸 cw 继续推进状态机；
+ * - signal abort 时 kill 子进程（SIGTERM），避免 abort 后僵尸 cw 继续运行；
  *   signal 进入时已 aborted 则立即 kill。listener 在 settle 时移除防泄漏。
  */
 export const defaultCwSpawner: CwSpawner = (args, input, cwd, signal) =>
 	new Promise<CwSpawnResult>((resolve) => {
+		// [worktree-reaper-fix] spawn 前检查 cwd 存在性（TOCTOU 兜底见下方 error handler）。
+		// 与现有 error 路径返回形态一致：resolve + exitCode=-1 + stderr，不 reject。
+		if (!existsSync(cwd)) {
+			resolve({ stdout: "", stderr: cwdMissingError(cwd), exitCode: -1 });
+			return;
+		}
+
 		const child = spawn("cw", args, {
 			cwd,
 			env: process.env,
@@ -65,7 +91,7 @@ export const defaultCwSpawner: CwSpawner = (args, input, cwd, signal) =>
 			stderr += chunk;
 		});
 
-		// abort → kill 子进程，防止 cw 状态机被已 abort 的僵尸子进程推进。
+		// abort → kill 子进程，防止已 abort 的调用仍留下运行中的 cw 子进程。
 		const onAbort = (): void => {
 			child.kill("SIGTERM");
 		};
@@ -92,8 +118,13 @@ export const defaultCwSpawner: CwSpawner = (args, input, cwd, signal) =>
 		};
 
 		child.on("error", (err: NodeJS.ErrnoException) => {
-			// spawn 失败（cw 不在 PATH / 无执行权限等）。exitCode=-1 区分于正常退出码。
-			finish({ stdout, stderr: `${stderr}\n[spawn error] ${err.message}`, exitCode: -1 });
+			// spawn 失败（cw 不在 PATH / 无执行权限 / TOCTOU：检查后 cwd 被删等）。
+			// [worktree-reaper-fix] 拼 cwd 进错误消息：ENOENT 的 err.message 只有 command 名，
+			// 无 cwd 线索会导致误诊（2026-08-11 事故 AI 误判"node 被卸载"）。
+			// exitCode=-1 区分于正常退出码。
+			const errCwd = err.code === "ENOENT" ? `\ncwd: ${cwd}` : "";
+			const hint = err.code === "ENOENT" && !existsSync(cwd) ? `\n${cwdMissingError(cwd)}` : "";
+			finish({ stdout, stderr: `${stderr}\n[spawn error] ${err.message}${errCwd}${hint}`, exitCode: -1 });
 		});
 		child.on("close", (code: number | null) => {
 			finish({ stdout, stderr, exitCode: code });