@zhushanwen/pi-cw-tool 0.4.1 → 0.4.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-cw-tool",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "description": "Pi extension wrapping the `cw` CLI as role-restricted tools (cw_planning / cw_wave / cw_dev / cw_review) with per-tool action whitelists — hard-guarantees no self-review by layer-owner agents.",
   "type": "module",
   "main": "index.ts",

package/src/__tests__/cw-tool.test.ts

@@ -750,4 +750,33 @@ describe("cw 路径解析", () => {
 		expect(result.stderr).toContain("spawn cw ENOENT");
 		expect(result.stdout).toBe("");
 	});
+
+	it("[worktree-reaper-fix] cwd 不存在 → 不 spawn，exitCode:-1 + 可操作错误（含 cwd 路径与恢复指引）", async () => {
+		// worktree 被 orphan reaper 误删后，子进程 cwd 指向虚空。spawn 前检查必须拦截并返回
+		// 含完整 cwd + 恢复指引的错误（否则 Node ENOENT 只报 command 名，误导诊断为"node 被卸载"）。
+		const result = await defaultCwSpawner(
+			["status", "--unitId", "u1"],
+			undefined,
+			"/nonexistent-cwd-for-reaper-test",
+		);
+
+		expect(result.exitCode).toBe(-1);
+		expect(result.stderr).toContain("/nonexistent-cwd-for-reaper-test");
+		expect(result.stderr).toContain("worktrees.json");
+		// 前置检查拦截：不进入 spawn
+		expect(spawnMock).not.toHaveBeenCalled();
+	});
+
+	it("[worktree-reaper-fix] spawn error ENOENT → stderr 拼 cwd 路径（TOCTOU 兜底）", async () => {
+		// existsSync 检查通过后目录被删（TOCTOU）：error handler 必须兜底拼 cwd。
+		const child = makeFakeChild();
+		spawnMock.mockImplementation(() => child as unknown as cp.ChildProcess);
+		const err = Object.assign(new Error("spawn cw ENOENT"), { code: "ENOENT" });
+		queueMicrotask(() => child.emit("error", err));
+
+		const result = await defaultCwSpawner(["status", "--unitId", "u1"], undefined, "/tmp");
+
+		expect(result.exitCode).toBe(-1);
+		expect(result.stderr).toContain("cwd: /tmp");
+	});
 });

package/src/__tests__/detect-repo-workspace.test.ts

@@ -40,6 +40,24 @@ function createGitRepo(parentDir: string, name: string): string {
 	return realpathSync(repo);
 }
 
+/** 建 bare repo + worktree workspace（xyz-agent 模式：.bare + worktree 子目录）。
+ *  返回 realpath 规范化的 worktree 路径。bare repo worktree 内 git-common-dir basename 是 .bare（非 .git），
+ *  是 detectRepoWorkspace 加固分支的核心场景（设计文档 §2.4 / 决策 2）。 */
+function createBareRepoWorkspace(parentDir: string, name: string): string {
+	const wsRoot = path.join(parentDir, name);
+	mkdirSync(wsRoot);
+	// 先建普通 seed repo（含初始 commit，bare repo 不能直接 commit）
+	const seed = path.join(parentDir, `${name}-seed`);
+	mkdirSync(seed);
+	execSync("git init -q", { cwd: seed });
+	execSync("git -c user.name=test -c user.email=test@test.local commit -q --allow-empty -m init", { cwd: seed });
+	// clone --bare 成 .bare，再 worktree add
+	execSync(`git clone -q --bare ${seed} .bare`, { cwd: wsRoot });
+	const worktree = path.join(wsRoot, "main");
+	execSync('git --git-dir=.bare worktree add -q main', { cwd: wsRoot });
+	return realpathSync(worktree);
+}
+
 afterEach(() => {
 	for (const dir of tmpDirs.splice(0)) {
 		rmSync(dir, { recursive: true, force: true });
@@ -93,6 +111,37 @@ describe("detectRepoWorkspace（真实 git）", () => {
 	});
 });
 
+// ── detectRepoWorkspace（bare repo + worktree 模式）──────────────
+
+describe("detectRepoWorkspace（bare repo + worktree 模式）", () => {
+	it("bare repo worktree（.bare）→ undefined（dirname(.bare)=容器根非 git 目录，不传 --workspace）", () => {
+		const base = makeTempDir("cw-bare-");
+		const worktree = createBareRepoWorkspace(base, "ws");
+		expect(detectRepoWorkspace(worktree)).toBeUndefined();
+	});
+
+	it("防误用：--is-bare-repository 在 worktree 内返回 false（不可作 bare 判据）", () => {
+		const base = makeTempDir("cw-bare-isbare-");
+		const worktree = createBareRepoWorkspace(base, "ws");
+		const isBare = execSync("git rev-parse --is-bare-repository", { cwd: worktree })
+			.toString()
+			.trim();
+		expect(isBare).toBe("false");
+	});
+
+	it("bare repo worktree：common-dir basename 是 .bare（非 .git）", () => {
+		const base = makeTempDir("cw-bare-commondir-");
+		const worktree = createBareRepoWorkspace(base, "ws");
+		const commonDir = execSync(
+			"git -C . rev-parse --path-format=absolute --git-common-dir",
+			{ cwd: worktree },
+		)
+			.toString()
+			.trim();
+		expect(path.basename(commonDir)).toBe(".bare");
+	});
+});
+
 // ── buildCwArgs 纯函数（workspace 参数）─────────────────────────
 
 describe("buildCwArgs（workspace 参数）", () => {

package/src/__tests__/workspace-gate.test.ts

@@ -1,9 +1,9 @@
 /**
  * workspace 门控测试：probeCwCliNormalization 纯函数 + executeCwAction 门控决策。
  *
- * 门控语义（差异文档 §3 §4 + ADR-0045 Superseded）：cw-cli 支持 store 内部归一化
+ * 门控语义（cw-cli ADR-0014 store-workspace decoupling）：cw-cli 支持 store 内部归一化
  * （probe 版本 >= MIN_CW_CLI_VERSION_FOR_NORMALIZATION）→ write action 不传 --workspace（纯封装）；
- * 不支持 → 兜底 ADR-0045 的 detectRepoWorkspace + --workspace。只读 action 始终不传（S-3）。
+ * 不支持 → 兜底 cw-cli ADR-0014 的 detectRepoWorkspace + --workspace。只读 action 始终不传（S-3）。
  *
  * detectRepoWorkspace 探测纯函数 + buildCwArgs 构造的测试在 detect-repo-workspace.test.ts，
  * 本文件只测门控决策（probe 三态 × action 两类 × git 环境）。
@@ -62,6 +62,8 @@ interface GateSpawnerOpts {
 	versionExitCode?: number;
 	/** cw --version spawn 抛异常（模拟 cw 不在 PATH）。 */
 	versionThrow?: boolean;
+	/** action 调用的返回（默认成功 `{ stdout: "{}", exitCode: 0 }`，覆盖以测失败分支）。 */
+	actionResult?: CwSpawnResult;
 }
 
 /**
@@ -84,7 +86,7 @@ function gateSpawner(opts: GateSpawnerOpts = {}): {
 				exitCode: opts.versionExitCode ?? 0,
 			};
 		}
-		return { stdout: "{}", stderr: "", exitCode: 0 };
+		return opts.actionResult ?? { stdout: "{}", stderr: "", exitCode: 0 };
 	});
 	return { spawner, calls };
 }
@@ -109,13 +111,13 @@ describe("probeCwCliNormalization", () => {
 
 	it("版本 === MIN（等号边界）→ supported:true（门控用 >=，锁定等号语义，S-7）", async () => {
 		const cwd = makeTempDir("probe-eq-");
-		const { spawner } = gateSpawner({ versionStdout: "cw 99.0.0" });
+		const { spawner } = gateSpawner({ versionStdout: "cw 1.6.2" });
 		const cap = await probeCwCliNormalization(spawner, cwd);
 		expect(cap.supported).toBe(true);
-		expect(cap.version).toBe("99.0.0");
+		expect(cap.version).toBe("1.6.2");
 	});
 
-	it("版本 < MIN → supported:false（当前 placeholder 99.0.0，真实 cw 1.6.1 不支持）", async () => {
+	it("版本 < MIN → supported:false（1.6.2 是归一化首版，1.6.1 不支持）", async () => {
 		const cwd = makeTempDir("probe-unsupported-");
 		const { spawner } = gateSpawner({ versionStdout: "cw 1.6.1" });
 		const cap = await probeCwCliNormalization(spawner, cwd);
@@ -196,7 +198,7 @@ describe("executeCwAction workspace 门控", () => {
 		expect(actionCall(calls).args).not.toContain("--workspace");
 	});
 
-	it("TC2: probe 不支持 → write action 兜底传 --workspace（ADR-0045 行为）", async () => {
+	it("TC2: probe 不支持 → write action 兜底传 --workspace（cw-cli ADR-0014 行为）", async () => {
 		const base = makeTempDir("gate-tc2-");
 		const repo = createGitRepo(base, "repo");
 		const { spawner, calls } = gateSpawner({ versionStdout: "cw 1.6.1" });
@@ -230,4 +232,30 @@ describe("executeCwAction workspace 门控", () => {
 		await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, plain);
 		expect(actionCall(calls).args).not.toContain("--workspace");
 	});
+
+	it("TC6: 非 git 目录 + probe 不支持 + action 失败（exitCode 1）→ error 含升级指引（degradedNoWorkspace 分支回归）", async () => {
+		const plain = makeTempDir("gate-tc6-plain-");
+		const { spawner } = gateSpawner({
+			versionStdout: "cw 1.6.1",
+			actionResult: { stdout: "", stderr: "boom", exitCode: 1 },
+		});
+		const result = await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, plain);
+		expect(result.ok).toBe(false);
+		// 升级指引文案锚点（准则 6：错误指向恢复动作）
+		expect(result.error).toContain("cw-cli 版本过低");
+		expect(result.error).toContain("@zhushanwen/coding-workflow@latest");
+	});
+
+	it("TC7: git 目录 + probe 不支持 + action 失败 → error 不含升级指引（非降级路径不追加）", async () => {
+		const base = makeTempDir("gate-tc7-");
+		const repo = createGitRepo(base, "repo");
+		const { spawner } = gateSpawner({
+			versionStdout: "cw 1.6.1",
+			actionResult: { stdout: "", stderr: "boom", exitCode: 1 },
+		});
+		const result = await executeCwAction("execute", DEV_ALLOWED, "cw_dev", "u1", {}, spawner, repo);
+		expect(result.ok).toBe(false);
+		expect(result.error).toContain("exit code 1");
+		expect(result.error).not.toContain("cw-cli 版本过低");
+	});
 });

package/src/cw-runner.ts

@@ -84,13 +84,19 @@ export function rejectDisallowedAction(
 const GIT_PROBE_TIMEOUT_MS = 5000;
 
 /**
- * 探测 cwd 所属 repo 的主目录（repo 级 workspace）。
+ * 探测 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 级（ADR-0045）后，spawn cw 时附带 --workspace 让 cw
+ * 从 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 {
@@ -103,6 +109,11 @@ export function detectRepoWorkspace(cwd: string): string | undefined {
 		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;
@@ -114,14 +125,16 @@ export function detectRepoWorkspace(cwd: string): string | undefined {
  *
  * cw-tool 与 cw-cli 是两个独立 npm 包（cw-tool 经 PATH 裸调 cw、零依赖声明），
  * 两包独立升级。cw-tool 退回纯封装前需探测 cw-cli 是否已落地 store 归一化
- * （coding-workflow S1：getCwJsonPath 用 git-common-dir），支持则不传 --workspace
- * （纯封装），不支持则兜底 ADR-0045 的 detectRepoWorkspace + --workspace。
+ * （cw-cli commit a90e8e8 / 首个 tag v1.6.2：getCwJsonPath 改用 detectCommonDir 归一化
+ * 到 git-common-dir），支持则不传 --workspace（纯封装），不支持则兜底 cw-cli ADR-0014
+ * 的 detectRepoWorkspace + --workspace。
  *
- * TODO(S1): 当前 placeholder "99.0.0" 使门控永远判定为「不支持」→ 永远走兜底
- * （=现状 dirname 行为，不引入回归）。cw-cli S1 落地并发布后，改为实际版本号
- * （如 "1.7.0"），门控自动激活。详见 docs/architecture/cw-store-workspace-decoupling.md §3 §4。
+ * 门控激活（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 = "99.0.0";
+const MIN_CW_CLI_VERSION_FOR_NORMALIZATION = "1.6.2";
 
 /** probe 超时（ms）：cw --version 卡死时 fail-safe 为「不支持」。 */
 const CW_VERSION_PROBE_TIMEOUT_MS = 5000;
@@ -170,7 +183,7 @@ function compareSemver(a: number[], b: number[]): number {
  * 探测 cw-cli 是否支持 store 内部归一化（门控）。
  *
  * 用 spawner 跑 `cw --version`，parse 版本号与 {@link MIN_CW_CLI_VERSION_FOR_NORMALIZATION}
- * 比较。失败（spawn 失败/parse 不到/超时）→ supported:false（fail-safe，兜底 ADR-0045 行为）。
+ * 比较。失败（spawn 失败/parse 不到/超时）→ supported:false（fail-safe，兜底 cw-cli ADR-0014 行为）。
  * 进程内 memoize（全局单值，cw 版本 cwd 无关）：首次探测后缓存，消除重复 spawn。
  *
  * @param parentSignal 调用方 SDK abort signal，与内部 5s 超时合并转发给 spawner（S-4）：
@@ -185,7 +198,7 @@ export async function probeCwCliNormalization(
 
 	const minVersion = parseCwVersion(MIN_CW_CLI_VERSION_FOR_NORMALIZATION);
 	if (!minVersion) {
-		// placeholder 本身非法（不应发生）——保守不支持
+		// MIN_CW_CLI_VERSION_FOR_NORMALIZATION 本身非法（不应发生）——保守不支持
 		const fallback: CwCliCapability = { supported: false, version: undefined, reason: "MIN_CW_CLI_VERSION_FOR_NORMALIZATION 非法" };
 		cachedCapability = fallback;
 		return fallback;
@@ -336,16 +349,24 @@ export async function executeCwAction(
 	const unitIdErr = rejectMissingUnitId(action, unitId);
 	if (unitIdErr) return { ok: false, ...base, error: unitIdErr };
 
-	// workspace 门控（差异文档 §3 §4 + ADR-0045 Superseded）：cw-cli 支持 store 内部归一化
+	// workspace 门控（cw-cli ADR-0014 store-workspace decoupling）：cw-cli 支持 store 内部归一化
 	// （probe 版本 >= MIN_CW_CLI_VERSION_FOR_NORMALIZATION）→ 纯封装不传 --workspace；
-	// 不支持 → 兜底 ADR-0045 的 detectRepoWorkspace + --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);
-		workspace = capability.supported ? undefined : detectRepoWorkspace(cwd);
+		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;
@@ -388,7 +409,15 @@ export async function executeCwAction(
 	if (exitCode !== 0) {
 		const parts: string[] = [`exit code ${exitCode ?? "null"}`];
 		if (stderr.trim()) parts.push(stderr.trim());
-		return { ok: false, ...base, error: parts.join(" | ") };
+		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 };
 	}
 
 	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）。 */
@@ -47,6 +66,13 @@ export type CwSpawner = (
  */
 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,
@@ -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 });