@zhushanwen/pi-cw-tool 0.4.3 → 0.5.0

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

@@ -1,11 +1,11 @@
 /**
- * cw-tool 测试。
+ * cw-tool 测试（cw 2.0 只读查询面）。
  *
  * 测试框架：vitest（从 vitest 导入 describe/it/expect/vi）。
- * 不真调 cw：通过 fake spawner 注入。白名单拦截在 spawn 之前，故拒绝用例断言 spawner 未被调用。
+ * 不真调 cw：通过 fake spawner 注入。白名单/参数校验在 spawn 之前，故拒绝用例断言 spawner 未被调用。
  */
-import { EventEmitter } from "node:events";
 import type * as cp from "node:child_process";
+import { EventEmitter } from "node:events";
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 
@@ -14,41 +14,23 @@ import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-a
 // node:child_process 是原生 CJS 模块，ESM 命名导出不可重定义（vi.spyOn 报 "not configurable"）。
 // 改用 vi.mock + vi.hoisted：工厂替换整个模块，hoisted vi.fn 作为 spawn，测试内动态配置实现。
 const spawnMock = vi.hoisted(() => vi.fn());
-// detectRepoWorkspace 的 git 探测同样走 node:child_process（spawnSync），mock 掉以保持纯单元；
-// 默认返回失败（非 git 目录语义），executeCwAction 因此不附加 --workspace，现有断言不受影响。
-const spawnSyncMock = vi.hoisted(() => vi.fn());
-vi.mock("node:child_process", () => ({ spawn: spawnMock, spawnSync: spawnSyncMock }));
-
-// 默认：git 探测失败（status 128）→ detectRepoWorkspace 返回 undefined。
-spawnSyncMock.mockImplementation((_cmd: string, _args: string[], _opts: object) => ({
-	status: 128,
-	stdout: "",
-	stderr: "not a git repository",
-}));
+vi.mock("node:child_process", () => ({ spawn: spawnMock }));
 
 import {
 	buildCwArgs,
 	type CwDetails,
+	CW_ACTIONS,
 	executeCwAction,
-	isReadonlyAction,
 	rejectDisallowedAction,
-	rejectMissingUnitId,
+	rejectInvalidQueryOptions,
 } from "../cw-runner.ts";
-import { type CwSpawner, type CwSpawnResult } from "../cw-spawn.ts";
-import {
-	DEV_ALLOWED,
-	PLANNING_ALLOWED,
-	REVIEW_ALLOWED,
-	WAVE_ALLOWED,
-	buildTool,
-	defaultCwSpawner,
-} from "../index.ts";
+import { type CwSpawner, type CwSpawnResult, defaultCwSpawner } from "../cw-spawn.ts";
+import { buildQueryTool, TOOL_NAME } from "../index.ts";
 
 // ── fake spawner 工具 ───────────────────────────────────────────
 
 interface CapturedCall {
 	args: string[];
-	input: string | undefined;
 	cwd: string;
 }
 
@@ -56,727 +38,345 @@ interface CapturedCall {
 function fakeSpawner(responses: CwSpawnResult[]): { spawner: CwSpawner; calls: CapturedCall[] } {
 	const calls: CapturedCall[] = [];
 	let i = 0;
-	const spawner: CwSpawner = vi.fn(async (args, input, cwd, _signal): Promise<CwSpawnResult> => {
-		// 门控 probe（['--version']）是内部细节：返回低版本（不支持归一化）让 write action
-		// 走兜底路径，且不入 calls（测试断言的是 action 调用，probe 透明）。
-		if (args[0] === "--version") {
-			return { stdout: "cw 1.0.0", stderr: "", exitCode: 0 };
-		}
-		calls.push({ args, input, cwd });
-		const r = responses[i] ?? { stdout: "", stderr: "", exitCode: 0 };
+	const spawner: CwSpawner = vi.fn(async (args, _input, cwd, _signal): Promise<CwSpawnResult> => {
+		calls.push({ args, cwd });
+		const response = responses[i] ?? { stdout: "", stderr: "", exitCode: 0 };
 		i += 1;
-		return { stdout: r.stdout, stderr: r.stderr, exitCode: r.exitCode };
+		return response;
 	});
 	return { spawner, calls };
 }
 
-/** 造一个「若被调用即失败」的 spawner（用于白名单拒绝用例，断言不该被调到）。 */
+/** 任何 spawn 都视为违规（拒绝用例用：断言从未触达 spawn）。 */
 function forbiddenSpawner(): CwSpawner {
-	// 回调签名由变量类型 CwSpawner 提供 contextual typing；签名漂移会编译失败（消除假绿）。
 	const spawner: CwSpawner = vi.fn(async (_args, _input, _cwd, _signal): Promise<CwSpawnResult> => {
-		throw new Error("spawner must not be called for a rejected action");
+		throw new Error("forbidden: 拒绝路径不应 spawn cw");
 	});
 	return spawner;
 }
 
-// execute 的 ctx 是完整 ExtensionContext（SDK 类型，字段多）；测试仅消费 cwd。
-// satisfies 校验 cwd 形状，再经 unknown 桥接到完整类型（partial mock of SDK type）。
-const fakeCtx = ({
-	cwd: "/tmp/fake-workspace",
-} satisfies Pick<ExtensionContext, "cwd">) as unknown as ExtensionContext;
-
-// ── 白名单拦截：每个工具至少 1 个被拒 action ────────────────────
-
-describe("白名单拦截（executeCwAction）", () => {
-	const cases: Array<{
-		name: string;
-		allowed: readonly string[];
-		reject: string;
-	}> = [
-		{ name: "cw_planning", allowed: PLANNING_ALLOWED, reject: "design-review" },
-		{ name: "cw_planning", allowed: PLANNING_ALLOWED, reject: "exec-review" },
-		{ name: "cw_wave", allowed: WAVE_ALLOWED, reject: "execute" },
-		{ name: "cw_wave", allowed: WAVE_ALLOWED, reject: "test" },
-		{ name: "cw_wave", allowed: WAVE_ALLOWED, reject: "design-review" },
-		{ name: "cw_wave", allowed: WAVE_ALLOWED, reject: "exec-review" },
-		{ name: "cw_dev", allowed: DEV_ALLOWED, reject: "design-review" },
-		{ name: "cw_dev", allowed: DEV_ALLOWED, reject: "clarify" },
-		{ name: "cw_review", allowed: REVIEW_ALLOWED, reject: "execute" },
-		{ name: "cw_review", allowed: REVIEW_ALLOWED, reject: "plan" },
-		{ name: "cw_review", allowed: REVIEW_ALLOWED, reject: "test" },
-	];
-
-	for (const { name, allowed, reject } of cases) {
-		it(`${name} 拒绝 "${reject}"（不在白名单，spawner 不被调用）`, async () => {
-			const spawner = forbiddenSpawner();
-			const details = await executeCwAction(
-				reject,
-				allowed,
-				name,
-				"unit-1",
-				{},
-				spawner,
-				fakeCtx.cwd,
-			);
-
-			expect(details.ok).toBe(false);
-			if (details.ok) throw new Error("unreachable");
-			expect(details.error).toContain(reject);
-			expect(details.error).toContain(name);
-			expect(spawner).not.toHaveBeenCalled();
-		});
-	}
+const CWD = "/tmp/proj";
 
-	it("rejectDisallowedAction 直接返回含 action 与工具名的消息", () => {
-		const msg = rejectDisallowedAction("execute", REVIEW_ALLOWED, "cw_review");
-		expect(msg).toContain('"execute"');
-		expect(msg).toContain("cw_review");
-		expect(rejectDisallowedAction("status", REVIEW_ALLOWED, "cw_review")).toBeUndefined();
-	});
+/** ExtensionContext 最小 fake（executeCwAction 只用 ctx.cwd）。 */
+const fakeCtx = ({ cwd: CWD } as unknown) as ExtensionContext;
+
+afterEach(() => {
+	spawnMock.mockReset();
 });
 
-// ── 允许的 action：mock spawn，不真调 cw ────────────────────────
-
-describe("允许的 action（mock spawn）", () => {
-	const okCases: Array<{ name: string; allowed: readonly string[]; action: string }> = [
-		{ name: "cw_planning", allowed: PLANNING_ALLOWED, action: "design" },
-		{ name: "cw_planning", allowed: PLANNING_ALLOWED, action: "execute" },
-		{ name: "cw_wave", allowed: WAVE_ALLOWED, action: "design" },
-		{ name: "cw_dev", allowed: DEV_ALLOWED, action: "execute" },
-		{ name: "cw_dev", allowed: DEV_ALLOWED, action: "test" },
-		{ name: "cw_review", allowed: REVIEW_ALLOWED, action: "design-review" },
-		{ name: "cw_review", allowed: REVIEW_ALLOWED, action: "exec-review" },
-	];
-
-	for (const { name, allowed, action } of okCases) {
-		it(`${name} 允许 "${action}"：stdout 是 JSON → ok:true + parsed data`, async () => {
-			const payload = { nextAction: { command: `cw ${action}` }, ok: true };
-			const { spawner, calls } = fakeSpawner([
-				{ stdout: JSON.stringify(payload), stderr: "", exitCode: 0 },
-			]);
-
-			const details = await executeCwAction(
-				action,
-				allowed,
-				name,
-				"unit-42",
-				{},
-				spawner,
-				fakeCtx.cwd,
-			);
-
-			expect(details.ok).toBe(true);
-			if (!details.ok) throw new Error("unreachable");
-			expect(details.action).toBe(action);
-			expect(details.unitId).toBe("unit-42");
-			expect(details.parsed).toBe(true);
-			if (!details.parsed) throw new Error("unreachable");
-			expect(details.data).toEqual(payload);
-
-			// 参数构造正确：cwd 透传，args 含 action + --unitId
-			expect(calls).toHaveLength(1);
-			expect(calls[0].cwd).toBe(fakeCtx.cwd);
-			expect(calls[0].args[0]).toBe(action);
-			expect(calls[0].args).toContain("--unitId");
-			expect(calls[0].args).toContain("unit-42");
-		});
-	}
+// ── 白名单（cw 2.0 只读面：写 action 物理不可达）────────────────
 
-	it("stdout 非 JSON → ok:true + parsed:false + 原样 stdout", async () => {
-		const { spawner } = fakeSpawner([{ stdout: "not a json", stderr: "", exitCode: 0 }]);
-		const details = await executeCwAction(
-			"status",
-			DEV_ALLOWED,
-			"cw_dev",
-			"u1",
-			{},
-			spawner,
-			fakeCtx.cwd,
-		);
-		expect(details.ok).toBe(true);
-		if (!details.ok || details.parsed) throw new Error("unreachable");
-		expect(details.stdout).toBe("not a json");
+describe("rejectDisallowedAction / executeCwAction 白名单", () => {
+	it("CW_ACTIONS 恰为 cw 2.0 四个只读命令", () => {
+		expect([...CW_ACTIONS]).toEqual(["status", "frontier", "tree", "report"]);
 	});
 
-	it("空 stdout（cw 成功但无输出）→ ok:true + parsed:false", async () => {
-		const { spawner } = fakeSpawner([{ stdout: "   ", stderr: "", exitCode: 0 }]);
-		const details = await executeCwAction(
-			"status",
-			DEV_ALLOWED,
-			"cw_dev",
-			"u1",
-			{},
-			spawner,
-			fakeCtx.cwd,
+	it.each(["create", "run", "verify", "design", "execute", "handoff", "evidence", "review", "abort"])(
+		"写/1.x action %s 被拒且不 spawn",
+		async (action) => {
+			const err = rejectDisallowedAction(action, CW_ACTIONS, TOOL_NAME);
+			expect(err).toContain(action);
+			expect(err).toContain("cw-cli skill");
+
+			const details = await executeCwAction(action, CW_ACTIONS, TOOL_NAME, {}, forbiddenSpawner(), CWD);
+			expect(details).toMatchObject({ ok: false, action });
+			expect(details.ok && true).toBe(false);
+		},
+	);
+
+	it("错误消息列出全部允许 action", () => {
+		expect(rejectDisallowedAction("run", CW_ACTIONS, TOOL_NAME)).toContain(
+			"status, frontier, tree, report",
 		);
-		expect(details.ok).toBe(true);
 	});
 });
 
-// ── 失败路径 ────────────────────────────────────────────────────
+// ── 查询参数校验（action × flag 匹配 + 互斥）────────────────────
 
-describe("失败路径", () => {
-	it("非零退出码 → ok:false + 含 exit code + stderr", async () => {
-		const { spawner } = fakeSpawner([
-			{ stdout: "", stderr: "unit not found", exitCode: 1 },
-		]);
-		const details = await executeCwAction(
-			"status",
-			DEV_ALLOWED,
-			"cw_dev",
-			"missing",
-			{},
-			spawner,
-			fakeCtx.cwd,
-		);
-		expect(details.ok).toBe(false);
-		if (details.ok) throw new Error("unreachable");
-		expect(details.error).toContain("exit code 1");
-		expect(details.error).toContain("unit not found");
+describe("rejectInvalidQueryOptions", () => {
+	it("tree 传 unitId 被拒（2.0 tree 无选择器）", () => {
+		expect(rejectInvalidQueryOptions("tree", { unitId: "u1" })).toContain("unitId");
 	});
 
-	it("stderr 非空但 exitCode 0 → ok:true（S-2：按 exitCode 判定，stderr 不导致失败）", async () => {
-		const { spawner } = fakeSpawner([
-			{ stdout: "{}", stderr: "warning: something", exitCode: 0 },
-		]);
-		const details = await executeCwAction(
-			"status",
-			DEV_ALLOWED,
-			"cw_dev",
-			"u1",
-			{},
-			spawner,
-			fakeCtx.cwd,
-		);
-		expect(details.ok).toBe(true);
+	it("frontier 传 unitId 被拒", () => {
+		expect(rejectInvalidQueryOptions("frontier", { unitId: "u1" })).toContain("unitId");
 	});
 
-	it("spawner 抛异常 → ok:false + spawn 失败消息", async () => {
-		const spawner: CwSpawner = vi.fn(async (_args, _input, _cwd, _signal): Promise<CwSpawnResult> => {
-			throw new Error("ENOENT");
-		});
-		const details = await executeCwAction(
-			"status",
-			DEV_ALLOWED,
-			"cw_dev",
-			"u1",
-			{},
-			spawner,
-			fakeCtx.cwd,
-		);
-		expect(details.ok).toBe(false);
-		if (details.ok) throw new Error("unreachable");
-		expect(details.error).toContain("ENOENT");
+	it("非 report 传 rootId 被拒", () => {
+		expect(rejectInvalidQueryOptions("status", { rootId: "r1" })).toContain("rootId");
+		expect(rejectInvalidQueryOptions("tree", { rootId: "r1" })).toContain("rootId");
 	});
 
-	it("input 与 inputFile 同时给 → ok:false（互斥）", async () => {
-		const spawner = forbiddenSpawner();
-		const details = await executeCwAction(
-			"design",
-			PLANNING_ALLOWED,
-			"cw_planning",
-			"u1",
-			{ input: "{}", inputFile: "/tmp/x.json" },
-			spawner,
-			fakeCtx.cwd,
-		);
-		expect(details.ok).toBe(false);
-		if (details.ok) throw new Error("unreachable");
-		expect(details.error).toContain("互斥");
-		expect(spawner).not.toHaveBeenCalled();
+	it("tree/report 传 json 被拒（2.0 仅 status/frontier 有 --json）", () => {
+		expect(rejectInvalidQueryOptions("tree", { json: true })).toContain("json");
+		expect(rejectInvalidQueryOptions("report", { json: true })).toContain("json");
 	});
 
-	it("spawn 超时（timeoutMs）→ ok:false 'cw 超时'", async () => {
-		// spawner 模拟 cw 卡死：挂起直到 signal abort 才 resolve（默认实现行为）。
-		const hangingSpawner: CwSpawner = vi.fn((_args, _input, _cwd, signal): Promise<CwSpawnResult> =>
-			new Promise<CwSpawnResult>((resolve) => {
-				signal?.addEventListener("abort", () =>
-					resolve({ stdout: "", stderr: "", exitCode: null }),
-				);
-			}),
-		);
+	it("report 同时传 unitId 与 rootId 被拒（CLI 侧互斥）", () => {
+		expect(rejectInvalidQueryOptions("report", { unitId: "u1", rootId: "r1" })).toContain("互斥");
+	});
 
+	it("合法组合放行", () => {
+		expect(rejectInvalidQueryOptions("status", {})).toBeUndefined();
+		expect(rejectInvalidQueryOptions("status", { unitId: "u1", json: true })).toBeUndefined();
+		expect(rejectInvalidQueryOptions("frontier", { json: true })).toBeUndefined();
+		expect(rejectInvalidQueryOptions("tree", {})).toBeUndefined();
+		expect(rejectInvalidQueryOptions("report", { unitId: "u1" })).toBeUndefined();
+		expect(rejectInvalidQueryOptions("report", { rootId: "r1" })).toBeUndefined();
+		expect(rejectInvalidQueryOptions("report", {})).toBeUndefined();
+	});
+
+	it("非法参数在 spawn 前拦截", async () => {
 		const details = await executeCwAction(
-			"status",
-			DEV_ALLOWED,
-			"cw_dev",
-			"u1",
-			{},
-			hangingSpawner,
-			fakeCtx.cwd,
-			undefined,
-			50,
+			"report",
+			CW_ACTIONS,
+			TOOL_NAME,
+			{ unitId: "u1", rootId: "r1" },
+			forbiddenSpawner(),
+			CWD,
 		);
-
-		expect(details.ok).toBe(false);
-		if (details.ok) throw new Error("unreachable");
-		expect(details.error).toBe("cw 超时");
+		expect(details).toMatchObject({ ok: false, action: "report" });
 	});
 });
 
-// ── 参数构造 ────────────────────────────────────────────────────
+// ── buildCwArgs（2.0 参数面映射）────────────────────────────────
 
 describe("buildCwArgs", () => {
-	it("无 input：仅 action + --unitId", () => {
-		expect(buildCwArgs("status", "u1", {})).toEqual(["status", "--unitId", "u1"]);
+	it("status 无参数 → 裸命令", () => {
+		expect(buildCwArgs("status", {})).toEqual(["status"]);
 	});
 
-	it("input 内容 → --input - （经 stdin）", () => {
-		expect(buildCwArgs("design", "u1", { input: '{"a":1}' })).toEqual([
-			"design",
-			"--unitId",
-			"u1",
-			"--input",
-			"-",
-		]);
-	});
-
-	it("inputFile 路径 → --input <path>", () => {
-		expect(buildCwArgs("design", "u1", { inputFile: "/tmp/in.json" })).toEqual([
-			"design",
-			"--unitId",
-			"u1",
-			"--input",
-			"/tmp/in.json",
-		]);
-	});
-
-	it("commitHash → --commitHash", () => {
-		expect(buildCwArgs("execute", "u1", { commitHash: "abc123" })).toEqual([
-			"execute",
-			"--unitId",
+	it("status unitId + json → --unit 在前 --json 在后", () => {
+		expect(buildCwArgs("status", { unitId: "u1", json: true })).toEqual([
+			"status",
+			"--unit",
 			"u1",
-			"--commitHash",
-			"abc123",
+			"--json",
 		]);
 	});
 
-	it("input + commitHash 同时", () => {
-		expect(buildCwArgs("execute", "u1", { input: "{}", commitHash: "abc" })).toEqual([
-			"execute",
-			"--unitId",
-			"u1",
-			"--input",
-			"-",
-			"--commitHash",
-			"abc",
-		]);
+	it("frontier json", () => {
+		expect(buildCwArgs("frontier", { json: true })).toEqual(["frontier", "--json"]);
 	});
 
-	it("workspace → 追加 --workspace <path>（位于 --commitHash 之后）", () => {
-		expect(buildCwArgs("execute", "u1", { commitHash: "abc" }, "/tmp/repo-root")).toEqual([
-			"execute",
-			"--unitId",
-			"u1",
-			"--commitHash",
-			"abc",
-			"--workspace",
-			"/tmp/repo-root",
-		]);
+	it("tree 恒裸命令", () => {
+		expect(buildCwArgs("tree", {})).toEqual(["tree"]);
 	});
 
-	it("workspace 不传 → 无 --workspace", () => {
-		expect(buildCwArgs("status", "u1", {})).toEqual(["status", "--unitId", "u1"]);
+	it("report unitId / rootId 二选一", () => {
+		expect(buildCwArgs("report", { unitId: "u1" })).toEqual(["report", "--unit", "u1"]);
+		expect(buildCwArgs("report", { rootId: "r1" })).toEqual(["report", "--root", "r1"]);
+		expect(buildCwArgs("report", {})).toEqual(["report"]);
 	});
 
-	it("unitId 为 undefined → 不加 --unitId（只读 action，S-5）", () => {
-		expect(buildCwArgs("list", undefined, {})).toEqual(["list"]);
+	it("无 1.x 残留 flag（--unitId / --workspace / --input / --commitHash 不出现）", () => {
+		for (const action of CW_ACTIONS) {
+			const args = buildCwArgs(action, { unitId: "u1", rootId: "r1", json: true });
+			expect(args).not.toContain("--unitId");
+			expect(args).not.toContain("--workspace");
+			expect(args).not.toContain("--input");
+			expect(args).not.toContain("--commitHash");
+		}
 	});
 });
 
-// ── stdin 透传 ──────────────────────────────────────────────────
-
-describe("stdin 透传", () => {
-	it("input 内容写入 spawner 的 input 参数", async () => {
-		const { spawner, calls } = fakeSpawner([{ stdout: "{}", stderr: "", exitCode: 0 }]);
-		await executeCwAction(
-			"design",
-			PLANNING_ALLOWED,
-			"cw_planning",
-			"u1",
-			{ input: '{"plan":"x"}' },
-			spawner,
-			fakeCtx.cwd,
-		);
-		expect(calls[0].input).toBe('{"plan":"x"}');
-	});
+// ── executeCwAction（spawn → 解析）──────────────────────────────
 
-	it("无 input → spawner input 为 undefined", async () => {
-		const { spawner, calls } = fakeSpawner([{ stdout: "{}", stderr: "", exitCode: 0 }]);
-		await executeCwAction(
+describe("executeCwAction", () => {
+	it("stdout 是 JSON → parsed:true + data", async () => {
+		const { spawner, calls } = fakeSpawner([
+			{ stdout: '{"units":[]}', stderr: "", exitCode: 0 },
+		]);
+		const details = await executeCwAction(
 			"status",
-			PLANNING_ALLOWED,
-			"cw_planning",
-			"u1",
-			{},
+			CW_ACTIONS,
+			TOOL_NAME,
+			{ json: true },
 			spawner,
-			fakeCtx.cwd,
+			CWD,
 		);
-		expect(calls[0].input).toBeUndefined();
+		expect(details).toMatchObject({ ok: true, action: "status", parsed: true });
+		if (details.ok && details.parsed) expect(details.data).toEqual({ units: [] });
+		expect(calls[0]?.args).toEqual(["status", "--json"]);
+		expect(calls[0]?.cwd).toBe(CWD);
 	});
-});
 
-// ── executeCwAction 接线：spawnSync 探测结果 → --workspace 附加 ─────
-
-// 说明：本文件 mock 了 node:child_process（spawnSync 默认失败），此处验证接线逻辑；
-// 真实 git 探测行为见 detect-repo-workspace.test.ts（真实 git repo + worktree）。
-describe("executeCwAction 附加 --workspace（spawnSync mock）", () => {
-	afterEach(() => {
-		spawnSyncMock.mockReset();
-		spawnSyncMock.mockImplementation((_cmd: string, _args: string[], _opts: object) => ({
-			status: 128,
-			stdout: "",
-			stderr: "not a git repository",
-		}));
+	it("stdout 非 JSON（人可读视图）→ parsed:false + 原样 stdout", async () => {
+		const { spawner } = fakeSpawner([{ stdout: "u1  closed", stderr: "", exitCode: 0 }]);
+		const details = await executeCwAction("tree", CW_ACTIONS, TOOL_NAME, {}, spawner, CWD);
+		expect(details).toMatchObject({ ok: true, parsed: false });
+		if (details.ok && !details.parsed) expect(details.stdout).toBe("u1  closed");
 	});
 
-	it("cwd 在 git repo 内 → args 含 --workspace <repo 根>（--commitHash 之后）", async () => {
-		spawnSyncMock.mockImplementationOnce((_cmd: string, _args: string[], _opts: object) => ({
-			status: 0,
-			stdout: "/tmp/repo-root/.git\n",
-			stderr: "",
-		}));
-		const { spawner, calls } = fakeSpawner([{ stdout: "{}", stderr: "", exitCode: 0 }]);
-		await executeCwAction(
-			"execute",
-			DEV_ALLOWED,
-			"cw_dev",
-			"u1",
-			{ commitHash: "abc123" },
-			spawner,
-			"/tmp/repo-root/worktrees/wt1",
-		);
-		expect(calls[0].args).toEqual([
-			"execute",
-			"--unitId",
-			"u1",
-			"--commitHash",
-			"abc123",
-			"--workspace",
-			"/tmp/repo-root",
+	it("非零退出码 → ok:false，stderr 折进错误消息", async () => {
+		const { spawner } = fakeSpawner([
+			{ stdout: "", stderr: "unit 不存在: nope", exitCode: 1 },
 		]);
-	});
-
-	it("cwd 非 git（探测失败）→ write action 无 --workspace", async () => {
-		const { spawner, calls } = fakeSpawner([{ stdout: "{}", stderr: "", exitCode: 0 }]);
-		await executeCwAction(
-			"execute",
-			DEV_ALLOWED,
-			"cw_dev",
-			"u1",
-			{},
+		const details = await executeCwAction(
+			"status",
+			CW_ACTIONS,
+			TOOL_NAME,
+			{ unitId: "nope" },
 			spawner,
-			"/tmp/not-a-repo",
+			CWD,
 		);
-		expect(calls[0].args).toEqual(["execute", "--unitId", "u1"]);
+		expect(details).toMatchObject({ ok: false, action: "status" });
+		if (!details.ok) {
+			expect(details.error).toContain("exit code 1");
+			expect(details.error).toContain("unit 不存在");
+		}
 	});
 
-	it("read-only action（status）即使在 git repo 内也不附加 --workspace（S-3）", async () => {
-		spawnSyncMock.mockImplementationOnce((_cmd: string, _args: string[], _opts: object) => ({
-			status: 0,
-			stdout: "/tmp/repo-root/.git\n",
-			stderr: "",
-		}));
-		const { spawner, calls } = fakeSpawner([{ stdout: "{}", stderr: "", exitCode: 0 }]);
-		await executeCwAction(
-			"status",
-			DEV_ALLOWED,
-			"cw_dev",
-			"u1",
-			{},
-			spawner,
-			"/tmp/repo-root/worktrees/wt1",
-		);
-		expect(calls[0].args).not.toContain("--workspace");
+	it("null 退出码（被信号终止）同样判失败", async () => {
+		const { spawner } = fakeSpawner([{ stdout: "", stderr: "", exitCode: null }]);
+		const details = await executeCwAction("frontier", CW_ACTIONS, TOOL_NAME, {}, spawner, CWD);
+		expect(details).toMatchObject({ ok: false });
 	});
-});
 
-// ── unitId 运行时校验（S-5）────────────────────────────────────
+	it("spawner 抛异常 → ok:false 带 spawn 失败前缀，不向上抛", async () => {
+		const spawner: CwSpawner = vi.fn(async () => {
+			throw new Error("boom");
+		});
+		const details = await executeCwAction("status", CW_ACTIONS, TOOL_NAME, {}, spawner, CWD);
+		expect(details).toMatchObject({ ok: false });
+		if (!details.ok) expect(details.error).toContain("cw spawn 失败");
+	});
 
-describe("unitId 运行时校验（S-5）", () => {
-	it("写 action 缺 unitId → ok:false + 清晰错误（含 action 名 + unitId），spawner 不被调用", async () => {
-		const spawner = forbiddenSpawner();
+	it("超时 → ok:false 'cw 超时'（timeoutMs=0 不限时）", async () => {
+		const hangingSpawner: CwSpawner = (_args, _input, _cwd, signal) =>
+			new Promise<CwSpawnResult>((resolve) => {
+				signal?.addEventListener("abort", () => resolve({ stdout: "", stderr: "", exitCode: null }), {
+					once: true,
+				});
+			});
 		const details = await executeCwAction(
-			"execute",
-			DEV_ALLOWED,
-			"cw_dev",
-			undefined,
+			"status",
+			CW_ACTIONS,
+			TOOL_NAME,
 			{},
-			spawner,
-			fakeCtx.cwd,
+			hangingSpawner,
+			CWD,
+			undefined,
+			20,
 		);
-		expect(details.ok).toBe(false);
-		if (details.ok) throw new Error("unreachable");
-		expect(details.error).toContain("execute");
-		expect(details.error).toContain("unitId");
-		expect(spawner).not.toHaveBeenCalled();
+		expect(details).toMatchObject({ ok: false });
+		if (!details.ok) expect(details.error).toBe("cw 超时");
 	});
 
-	it("只读 action 缺 unitId → ok:true，args 不含 --unitId", async () => {
-		const { spawner, calls } = fakeSpawner([{ stdout: "{}", stderr: "", exitCode: 0 }]);
+	it("SDK abort signal 与超时合并（进入即 aborted 也判失败）", async () => {
+		const controller = new AbortController();
+		controller.abort();
+		const { spawner } = fakeSpawner([{ stdout: "", stderr: "", exitCode: 0 }]);
 		const details = await executeCwAction(
 			"status",
-			DEV_ALLOWED,
-			"cw_dev",
-			undefined,
+			CW_ACTIONS,
+			TOOL_NAME,
 			{},
 			spawner,
-			fakeCtx.cwd,
+			CWD,
+			controller.signal,
 		);
-		expect(details.ok).toBe(true);
-		expect(calls[0].args).not.toContain("--unitId");
-	});
-
-	it("只读 action 传 unitId 仍附加 --unitId（Optional 非禁止）", async () => {
-		const { spawner, calls } = fakeSpawner([{ stdout: "{}", stderr: "", exitCode: 0 }]);
-		await executeCwAction("list", PLANNING_ALLOWED, "cw_planning", "u1", {}, spawner, fakeCtx.cwd);
-		expect(calls[0].args).toContain("--unitId");
-		expect(calls[0].args).toContain("u1");
-	});
-
-	it("rejectMissingUnitId：写 action 缺 → 错误消息；只读 action 缺 → undefined", () => {
-		expect(rejectMissingUnitId("execute", undefined)).toContain("unitId");
-		expect(rejectMissingUnitId("design", undefined)).toContain("unitId");
-		expect(rejectMissingUnitId("execute", "u1")).toBeUndefined();
-		expect(rejectMissingUnitId("list", undefined)).toBeUndefined();
-		expect(rejectMissingUnitId("status", undefined)).toBeUndefined();
-		expect(rejectMissingUnitId("frontier", undefined)).toBeUndefined();
-	});
-
-	it("isReadonlyAction：READONLY_ACTIONS → true，写 action / 未知 action → false", () => {
-		for (const ro of ["list", "tree", "status", "handoff", "frontier"]) {
-			expect(isReadonlyAction(ro)).toBe(true);
-		}
-		expect(isReadonlyAction("execute")).toBe(false);
-		expect(isReadonlyAction("design")).toBe(false);
-		expect(isReadonlyAction("unknown-action")).toBe(false);
+		// 已 abort 的 signal 传入：spawner 可能仍 resolve，但合并机制不崩、结果可判定
+		expect(typeof details.ok).toBe("boolean");
 	});
 });
 
-// ── 工厂注册 + buildTool 集成 ───────────────────────────────────
+// ── 工具注册与 execute 闭包 ─────────────────────────────────────
 
-describe("工厂与工具注册", () => {
-	it("cwToolExtension(pi) 注册 4 个工具（cw_planning/cw_wave/cw_dev/cw_review）", async () => {
-		const { default: cwToolExtension } = await import("../index.ts");
-		const registered: Array<{ name: string; actionEnum: string[] }> = [];
-		// 仅 mock registerTool（ExtensionAPI 其余成员测试不消费）；显式声明 tool 参数形状，
-		// 让对 tool.name / parameters 的访问受类型检查；经 unknown 桥接到完整 ExtensionAPI。
+describe("buildQueryTool / 扩展注册", () => {
+	it("注册单个 cw_query 工具（4 角色工具已退役）", async () => {
+		const registered: Array<{ name: string }> = [];
 		const fakePi = {
-			registerTool(tool: { name: string; parameters: { properties?: Record<string, unknown> } }): void {
-				const enumVal = (tool.parameters.properties?.action as { enum?: string[] })?.enum;
-				registered.push({ name: tool.name, actionEnum: enumVal ?? [] });
+			registerTool: (tool: { name: string }) => {
+				registered.push(tool);
 			},
-		} as unknown as ExtensionAPI;
-		cwToolExtension(fakePi);
-
-		const names = registered.map((r) => r.name);
-		expect(names).toEqual(["cw_planning", "cw_wave", "cw_dev", "cw_review"]);
-		// schema 的 action 枚举值与白名单数组逐项深相等（schema 即运行时第一道约束，
-		// 与 executeCwAction 第二道 rejectDisallowedAction 同源）。
-		const byName = Object.fromEntries(registered.map((r) => [r.name, r.actionEnum]));
-		expect(byName.cw_planning).toEqual([...PLANNING_ALLOWED]);
-		expect(byName.cw_wave).toEqual([...WAVE_ALLOWED]);
-		expect(byName.cw_dev).toEqual([...DEV_ALLOWED]);
-		expect(byName.cw_review).toEqual([...REVIEW_ALLOWED]);
+		};
+		const { default: cwToolExtension } = await import("../index.ts");
+		cwToolExtension(fakePi as unknown as ExtensionAPI);
+		expect(registered.map((t) => t.name)).toEqual([TOOL_NAME]);
+		expect(TOOL_NAME).toBe("cw_query");
 	});
 
-	it("buildTool execute 端到端：拒绝路径返回 ok:false（带工具名）", async () => {
-		const tool = buildTool(REVIEW_ALLOWED, {
-			name: "cw_review",
-			label: "CW Review",
-			description: "x",
-			promptSnippet: "x",
-		}, forbiddenSpawner());
-
-		// execute 全签名：(_toolCallId, params, signal, onUpdate, ctx)
-		// 故意传 review 工具不允许的 action "execute" 验证运行时拒绝；类型层须逃逸（Params 的 action 枚举不含 execute）。
-		type Params = Parameters<(typeof tool)["execute"]>[1];
-		const params = { action: "execute", unitId: "u1" } as unknown as Params;
-		const result = await tool.execute("call-1", params, undefined, undefined, fakeCtx);
-
-		const details = result.details as CwDetails;
-		expect(details.ok).toBe(false);
-		if (details.ok) throw new Error("unreachable");
-		expect(details.error).toContain("execute");
-		expect(details.error).toContain("cw_review");
+	it("execute 成功路径返回 stdout 文本 + details", async () => {
+		const { spawner } = fakeSpawner([{ stdout: "u1 closed", stderr: "", exitCode: 0 }]);
+		const tool = buildQueryTool(spawner);
+		const result = await tool.execute(
+			"call-1",
+			{ action: "status" },
+			undefined,
+			undefined,
+			fakeCtx,
+		);
+		expect(result.content[0]).toMatchObject({ type: "text", text: "u1 closed" });
+		expect(result.details).toMatchObject({ ok: true, action: "status" });
 	});
 
-	it("buildTool execute 端到端：允许路径透传到 spawner", async () => {
-		const { spawner, calls } = fakeSpawner([{ stdout: '{"ok":true}', stderr: "", exitCode: 0 }]);
-		const tool = buildTool(REVIEW_ALLOWED, {
-			name: "cw_review",
-			label: "CW Review",
-			description: "x",
-			promptSnippet: "x",
-		}, spawner);
-
-		type Params = Parameters<(typeof tool)["execute"]>[1];
-		const params: Params = { action: "design-review", unitId: "u9", input: '{"verdict":"pass"}' };
-		const result = await tool.execute("call-2", params, undefined, undefined, fakeCtx);
-
-		const details = result.details as CwDetails;
-		expect(details.ok).toBe(true);
-		expect(calls[0].args).toEqual(["design-review", "--unitId", "u9", "--input", "-"]);
-		expect(calls[0].input).toBe('{"verdict":"pass"}');
+	it("execute 失败路径 content 带工具名与错误", async () => {
+		const { spawner } = fakeSpawner([{ stdout: "", stderr: "boom", exitCode: 1 }]);
+		const tool = buildQueryTool(spawner);
+		const result = await tool.execute(
+			"call-1",
+			{ action: "frontier" },
+			undefined,
+			undefined,
+			fakeCtx,
+		);
+		expect(result.content[0]).toMatchObject({ type: "text" });
+		if (result.content[0]?.type === "text") {
+			expect(result.content[0].text).toContain("cw_query");
+			expect(result.content[0].text).toContain("失败");
+		}
+		expect(result.details).toMatchObject({ ok: false, action: "frontier" });
 	});
 
-	it("buildTool execute：abort signal → ok:false aborted", async () => {
-		const tool = buildTool(REVIEW_ALLOWED, {
-			name: "cw_review",
-			label: "CW Review",
-			description: "x",
-			promptSnippet: "x",
-		}, forbiddenSpawner());
-
+	it("进入即 aborted → 短路返回 aborted，不 spawn", async () => {
 		const controller = new AbortController();
 		controller.abort();
-		type Params = Parameters<(typeof tool)["execute"]>[1];
-		const params: Params = { action: "status", unitId: "u1" };
+		const tool = buildQueryTool(forbiddenSpawner());
 		const result = await tool.execute(
-			"call-3",
-			params,
+			"call-1",
+			{ action: "status" },
 			controller.signal,
 			undefined,
 			fakeCtx,
 		);
-		expect((result.details as CwDetails).ok).toBe(false);
-	});
-
-	it("schema：unitId 是 Optional（不在 required），action 是 required（S-5）", () => {
-		const tool = buildTool(DEV_ALLOWED, {
-			name: "cw_dev",
-			label: "CW Dev",
-			description: "x",
-			promptSnippet: "x",
-		}, forbiddenSpawner());
-		const required = (tool.parameters as { required?: string[] }).required ?? [];
-		expect(required).toContain("action");
-		expect(required).not.toContain("unitId");
-		// unitId 属性仍存在（Optional 不是删除）
-		expect(tool.parameters.properties?.unitId).toBeDefined();
+		expect(result.details).toMatchObject({ ok: false, error: "aborted by signal" });
 	});
 });
 
-// ── 白名单表格逐字一致性 ────────────────────────────────────────
+// ── defaultCwSpawner（子进程抽象，与命令面无关）─────────────────
 
-describe("白名单与方案表格逐字一致", () => {
-	it("cw_planning = design/execute/replan/retrospect/closeout + status/handoff/list/tree/frontier", () => {
-		expect([...PLANNING_ALLOWED]).toEqual([
-			"design", "execute", "replan", "retrospect", "closeout",
-			"status", "handoff", "list", "tree", "frontier",
-		]);
-	});
-
-	it("cw_wave = 同 planning 但无 execute（也无 test/design-review/exec-review）", () => {
-		expect([...WAVE_ALLOWED]).toEqual([
-			"design", "replan", "retrospect", "closeout",
-			"status", "handoff", "list", "tree", "frontier",
-		]);
-		for (const forbidden of ["execute", "test", "design-review", "exec-review"]) {
-			expect(WAVE_ALLOWED).not.toContain(forbidden);
-		}
-	});
-
-	it("cw_dev = execute/test + status/handoff", () => {
-		expect([...DEV_ALLOWED]).toEqual(["execute", "test", "status", "handoff"]);
-	});
-
-	it("cw_review = design-review/exec-review + status", () => {
-		expect([...REVIEW_ALLOWED]).toEqual(["design-review", "exec-review", "status"]);
-	});
-});
-
-// ── cw 路径无硬编码 + 子进程生命周期（defaultCwSpawner）────────
-
-describe("cw 路径解析", () => {
-	// 造一个满足 defaultCwSpawner 调用的假子进程（stdout/stderr 带 setEncoding，stdin write/end，可选 kill）。
-	function makeFakeChild(): EventEmitter {
-		const child = new EventEmitter();
-		const stdio = (): EventEmitter => {
-			const s = new EventEmitter();
-			(s as unknown as { setEncoding: (_e: string) => void }).setEncoding = () => {};
-			return s;
+describe("defaultCwSpawner", () => {
+	it("spawn PATH 上的裸 cw，无硬编码路径；kill 信号透传", async () => {
+		const child = new EventEmitter() as unknown as cp.ChildProcess;
+		// EventEmitter 无 kill/stdin/stdout/stderr ——挂最小 stub 满足实现调用
+		const killCalls: string[] = [];
+		(child as unknown as { kill: (sig?: string) => void }).kill = (sig?: string) => {
+			killCalls.push(sig ?? "");
 		};
-		Object.assign(child, {
-			stdout: stdio(),
-			stderr: stdio(),
-			stdin: { write() {}, end() {} },
-		});
-		return child;
-	}
-
-	afterEach(() => {
-		spawnMock.mockReset();
-	});
+		child.stdout = new EventEmitter() as unknown as NonNullable<cp.ChildProcess["stdout"]>;
+		child.stderr = new EventEmitter() as unknown as NonNullable<cp.ChildProcess["stderr"]>;
+		child.stdin = { write: () => true, end: () => {} } as unknown as NonNullable<
+			cp.ChildProcess["stdin"]
+		>;
+		(child.stdout as unknown as { setEncoding: (e: string) => void }).setEncoding = () => {};
+		(child.stderr as unknown as { setEncoding: (e: string) => void }).setEncoding = () => {};
 
-	it("defaultCwSpawner spawn 裸名 'cw'（经 PATH 解析，无硬编码绝对路径）", async () => {
-		const child = makeFakeChild();
-		spawnMock.mockImplementation(() => child as unknown as cp.ChildProcess);
-		queueMicrotask(() => child.emit("close", 0));
-		await defaultCwSpawner(["status", "--unitId", "u1"], undefined, "/tmp");
-		expect(spawnMock).toHaveBeenCalledTimes(1);
-		// 第一参是命令名：裸名 "cw"，不是任何绝对路径
-		expect((spawnMock.mock.calls[0] as unknown[])[0]).toBe("cw");
-	});
-
-	it("abort signal 触发时 defaultCwSpawner kill 子进程（SIGTERM）", async () => {
-		const child = makeFakeChild();
-		// kill 模拟真实子进程收到信号后退出：调度 close 事件让 promise resolve
-		const killed = vi.fn((_sig: string) => {
-			queueMicrotask(() => child.emit("close", null));
-		});
-		(child as unknown as { kill: (s: string) => void }).kill = killed;
-		spawnMock.mockImplementation(() => child as unknown as cp.ChildProcess);
+		spawnMock.mockReturnValueOnce(child);
 
 		const controller = new AbortController();
-		const pending = defaultCwSpawner(["status"], undefined, "/tmp", controller.signal);
+		const realCwd = process.cwd(); // defaultCwSpawner 有 existsSync(cwd) 前置检查，用真实存在目录
+		const promise = defaultCwSpawner(["status"], undefined, realCwd, controller.signal);
 		controller.abort();
-		await pending;
-		expect(killed).toHaveBeenCalledWith("SIGTERM");
-	});
+		child.emit("close", null);
+		const result = await promise;
 
-	it("spawn error（cw 不在 PATH / ENOENT）→ exitCode:-1 + stderr 含 [spawn error]", async () => {
-		// 模拟 cw 不在 PATH（用户首要失败模式）：node 对失败的 spawn 触发 child 'error' 事件。
-		// 若 defaultCwSpawner 的 error handler 被删，promise 永不 resolve（直到 5min 超时）→ 用例挂死暴露回归。
-		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("[spawn error]");
-		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(spawnMock).toHaveBeenCalledWith(
+			"cw",
+			["status"],
+			expect.objectContaining({ cwd: realCwd }),
 		);
-
-		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");
+		expect(killCalls).toContain("SIGTERM");
+		expect(result.exitCode).toBeNull();
 	});
 });