pi-skill-evolve 0.0.0-stage → 0.1.2

package/extensions/skill-evolve/test/config-command.test.ts

@@ -0,0 +1,73 @@
+/**
+ * `/skill-evolve config` 单测：TUI 用 select，非 TUI 只打印当前值。
+ * tools 用假实现，验证的是「选了哪一项 → 写成什么值」以及取消行为。
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { runConfigCommand } from "../lib/config-command.ts";
+import type { ModelTools } from "../lib/evolution-model.ts";
+import { INHERIT, modelChoices } from "../lib/model-config.ts";
+
+function fakeTools(calls: string[]): ModelTools {
+  let config = { propose: INHERIT, review: INHERIT };
+  return {
+    config: () => config,
+    reviewModel: () => config.review,
+    setModel: async (kind, spec) => {
+      calls.push(`${kind}=${spec}`);
+      config = { ...config, [kind]: spec };
+      return `${kind} 已设为 ${spec}`;
+    },
+    selftestText: async () => "自检：通过",
+    selftestFailed: () => false,
+    lastSelftest: () => undefined,
+  };
+}
+
+const MODELS = [{ provider: "deepseek", id: "deepseek-v3.2" }, { provider: "openai", id: "gpt-5" }];
+
+test("非 TUI：不提问，只打印当前值与手改入口", async () => {
+  const calls: string[] = [];
+  const text = await runConfigCommand(null, fakeTools(calls));
+  assert.match(text, /无法交互选择/);
+  assert.match(text, /propose\.model/);
+  assert.deepEqual(calls, []);
+});
+
+test("TUI：选『跟随主会话』写 inherit，两个键都会问", async () => {
+  const calls: string[] = [];
+  const asked: string[] = [];
+  const text = await runConfigCommand(
+    {
+      models: MODELS,
+      select: async (title: string, options: string[]) => {
+        asked.push(`${title}|${options.join(",")}`);
+        return options[0];
+      },
+    },
+    fakeTools(calls),
+  );
+  assert.deepEqual(calls, [`propose=${INHERIT}`, `review=${INHERIT}`]);
+  assert.equal(asked.length, 2);
+  assert.ok(asked[0].includes(MODELS[0].provider));
+  assert.match(text, /当前配置/);
+});
+
+test("TUI：选具体模型写 provider/id；只问 review 时只改 review", async () => {
+  const calls: string[] = [];
+  const choices = modelChoices(MODELS);
+  const text = await runConfigCommand(
+    { models: MODELS, select: async (_title: string, options: string[]) => options[2] ?? choices[1] },
+    fakeTools(calls),
+    "review",
+  );
+  assert.deepEqual(calls, ["review=openai/gpt-5"]);
+  assert.match(text, /review/);
+});
+
+test("取消选择：写回中止，配置不动", async () => {
+  const calls: string[] = [];
+  const text = await runConfigCommand({ models: MODELS, select: async () => undefined }, fakeTools(calls));
+  assert.deepEqual(calls, []);
+  assert.match(text, /已取消/);
+});

package/extensions/skill-evolve/test/config.test.ts

@@ -0,0 +1,154 @@
+/**
+ * 配置默认值：别人 clone 下来必须「什么都不做」—— 默认全关、无 config.json 也不生成。
+ * on/off 只切 enabled + telemetry 两个键，其余（去抖 / 超时 / 上限）原样保留。
+ */
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import test from "node:test";
+import { configFile, DEFAULT_CONFIG, loadConfig, normalizeConfig, saveConfigSwitch, saveFlag, saveWebConfig } from "../lib/config.ts";
+import { TELEMETRY_OFF_WARNING } from "../lib/flags.ts";
+import { switchLine } from "../lib/report.ts";
+import { directQueue } from "../lib/telemetry.ts";
+
+function workspace(): string {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "skill-evolve-config-"));
+  return path.join(cwd, ".pi", "evolution");
+}
+
+test("DEFAULT_CONFIG：采集与派生都默认关（clone 即静默）", () => {
+  assert.deepEqual([DEFAULT_CONFIG.enabled, DEFAULT_CONFIG.telemetry], [false, false]);
+});
+
+test("loadConfig：没有 config.json 时全关，且不会顺手造文件", () => {
+  const evolutionDir = workspace();
+  const config = loadConfig(evolutionDir);
+  assert.deepEqual([config.enabled, config.telemetry], [false, false]);
+  assert.equal(fs.existsSync(configFile(evolutionDir)), false, "读配置不能有副作用");
+});
+
+test("normalizeConfig：空对象与缺字段都回落到全关", () => {
+  assert.deepEqual([normalizeConfig({}).enabled, normalizeConfig({}).telemetry], [false, false]);
+  const onlyEnabled = normalizeConfig({ enabled: true });
+  assert.deepEqual([onlyEnabled.enabled, onlyEnabled.telemetry], [true, false], "只写 enabled 不等于打开采集");
+});
+
+test("saveConfigSwitch：on 两个键都开，其余字段原样保留", async () => {
+  const evolutionDir = workspace();
+  fs.mkdirSync(evolutionDir, { recursive: true });
+  fs.writeFileSync(
+    configFile(evolutionDir),
+    JSON.stringify({ enabled: false, telemetry: false, idleMs: 1_234, perSessionCap: 3 }),
+    "utf8",
+  );
+  const next = await saveConfigSwitch(evolutionDir, true, directQueue);
+  assert.deepEqual([next.enabled, next.telemetry, next.idleMs, next.perSessionCap], [true, true, 1_234, 3]);
+  const raw = JSON.parse(fs.readFileSync(configFile(evolutionDir), "utf8"));
+  assert.deepEqual([raw.enabled, raw.telemetry, raw.idleMs, raw.perSessionCap], [true, true, 1_234, 3]);
+});
+
+test("saveConfigSwitch：off 两个键都关", async () => {
+  const evolutionDir = workspace();
+  fs.mkdirSync(evolutionDir, { recursive: true });
+  fs.writeFileSync(configFile(evolutionDir), JSON.stringify({ enabled: true, telemetry: true, idleMs: 5_000 }), "utf8");
+  await saveConfigSwitch(evolutionDir, false, directQueue);
+  const raw = JSON.parse(fs.readFileSync(configFile(evolutionDir), "utf8"));
+  assert.deepEqual([raw.enabled, raw.telemetry, raw.idleMs], [false, false, 5_000]);
+});
+
+test("normalizeConfig：web 默认开 + 7788（采集/派生仍关），端口边界 1/65535 合法、整块类型不对回退", () => {
+  assert.deepEqual(normalizeConfig({}).web, { enabled: true, port: 7788 });
+  assert.deepEqual([normalizeConfig({}).enabled, normalizeConfig({}).telemetry], [false, false], "面板默认开 ≠ 开始烧 token");
+  assert.equal(normalizeConfig({ web: { port: 1 } }).web.port, 1, "1 是合法端口，不能当假值丢掉");
+  assert.equal(normalizeConfig({ web: { port: 65_535 } }).web.port, 65_535);
+  assert.equal(normalizeConfig({ web: { port: 65_536 } }).web.port, 7788);
+  assert.equal(normalizeConfig({ web: { port: 7788.5 } }).web.port, 7788, "非整数端口回落");
+  assert.deepEqual(normalizeConfig({ web: "on" }).web, { enabled: true, port: 7788 }, "整块类型不对就整块回退");
+});
+
+test("saveConfigSwitch：不碰 web 块（开关采集/派生不该顺手关掉面板）", async () => {
+  const evolutionDir = workspace();
+  fs.mkdirSync(evolutionDir, { recursive: true });
+  fs.writeFileSync(
+    configFile(evolutionDir),
+    JSON.stringify({ enabled: false, telemetry: false, web: { enabled: true, port: 7799 } }),
+    "utf8",
+  );
+  await saveConfigSwitch(evolutionDir, true, directQueue);
+  const raw = JSON.parse(fs.readFileSync(configFile(evolutionDir), "utf8"));
+  assert.deepEqual(raw.web, { enabled: true, port: 7799 });
+});
+
+test("saveWebConfig：只改 web，其余键原样保留", async () => {
+  const evolutionDir = workspace();
+  fs.mkdirSync(evolutionDir, { recursive: true });
+  fs.writeFileSync(
+    configFile(evolutionDir),
+    JSON.stringify({ enabled: true, telemetry: true, idleMs: 1_234, web: { enabled: false, port: 7788 } }),
+    "utf8",
+  );
+  const next = await saveWebConfig(evolutionDir, { enabled: true, port: 7799 }, directQueue);
+  assert.deepEqual([next.enabled, next.telemetry, next.idleMs, next.web.port], [true, true, 1_234, 7799]);
+  const raw = JSON.parse(fs.readFileSync(configFile(evolutionDir), "utf8"));
+  assert.deepEqual([raw.enabled, raw.telemetry, raw.idleMs], [true, true, 1_234], "写 web 不能把开关或去抖改掉");
+  assert.deepEqual(raw.web, { enabled: true, port: 7799 });
+});
+
+test("loadConfig：坏 JSON 回落默认值，并留一行日志", () => {
+  const evolutionDir = workspace();
+  fs.mkdirSync(evolutionDir, { recursive: true });
+  fs.writeFileSync(configFile(evolutionDir), "{ 坏掉", "utf8");
+  const logs: string[] = [];
+  const config = loadConfig(evolutionDir, (msg) => logs.push(msg));
+  assert.deepEqual([config.enabled, config.telemetry], [false, false]);
+  assert.equal(logs.length, 1);
+  assert.match(logs[0]!, /配置读取失败/);
+});
+
+test("saveFlag：只改目标字段，其余键（含 web 块）原样保留", async () => {
+  const evolutionDir = workspace();
+  fs.mkdirSync(evolutionDir, { recursive: true });
+  fs.writeFileSync(
+    configFile(evolutionDir),
+    JSON.stringify({ enabled: false, telemetry: false, idleMs: 1_234, web: { enabled: true, port: 7799 } }),
+    "utf8",
+  );
+  const next = await saveFlag(evolutionDir, "telemetry", true, directQueue);
+  const raw = JSON.parse(fs.readFileSync(configFile(evolutionDir), "utf8"));
+  // 返回值与盘上都要是「只翻采集」：复盘、去抖、web 端口一个都不许跟着动
+  assert.deepEqual([next.enabled, next.telemetry, next.idleMs, next.web.port], [false, true, 1_234, 7799]);
+  assert.deepEqual([raw.enabled, raw.telemetry, raw.idleMs, raw.web], [false, true, 1_234, { enabled: true, port: 7799 }]);
+});
+
+test("saveFlag：两个字段互不牵连（先开复盘再关采集）", async () => {
+  const evolutionDir = workspace();
+  fs.mkdirSync(evolutionDir, { recursive: true });
+  await saveFlag(evolutionDir, "enabled", true, directQueue);
+  const raw = JSON.parse(fs.readFileSync(configFile(evolutionDir), "utf8"));
+  assert.deepEqual([raw.enabled, raw.telemetry], [true, false], "只开复盘时采集仍关");
+  await saveFlag(evolutionDir, "telemetry", false, directQueue);
+  const after = JSON.parse(fs.readFileSync(configFile(evolutionDir), "utf8"));
+  assert.deepEqual([after.enabled, after.telemetry], [true, false], "关采集不动复盘");
+});
+
+test("switchLine：采集与复盘分两段写，第四种组合带警告", () => {
+  const base = { idleMs: 1, maxRuntimeMs: 1, perSessionCap: 1 };
+  const off = "采集：关（不写遥测）｜复盘：关（不会派生 agent）";
+  const collectOnly = "采集：开（遥测写入 .pi/evolution/telemetry/）｜复盘：关（不会派生 agent）";
+  const both = "采集：开（遥测写入 .pi/evolution/telemetry/）｜复盘：开（会派生 agent）";
+  assert.equal(switchLine({ ...base, enabled: false, telemetry: false }), `${off}（/skill-evolve on 全开；collect / review 单独控制）`);
+  assert.equal(switchLine({ ...base, enabled: false, telemetry: true }), `${collectOnly}（/skill-evolve on 全开；collect / review 单独控制）`);
+  assert.equal(switchLine({ ...base, enabled: true, telemetry: true }), `${both}（/skill-evolve off 全关；collect / review 单独控制）`);
+  const warn = switchLine({ ...base, enabled: true, telemetry: false });
+  assert.equal(warn.startsWith("采集：关（不写遥测）｜复盘：开（会派生 agent）"), true);
+  assert.equal(warn.includes(TELEMETRY_OFF_WARNING), true, "只开复盘不采集：必须带警告，不许静默");
+});
+
+test("normalizeConfig：ui 两个开关缺字段回退 false，显式打开才生效", () => {
+  // 2026-11-08 用户「tui 的这些推送不看了」：默认零推送是硬默认，不许因为老配置没写 ui 就回到开
+  assert.deepEqual(normalizeConfig({}).ui, { widget: false, entries: false });
+  assert.deepEqual(normalizeConfig({ ui: { widget: true } }).ui, { widget: true, entries: false });
+  assert.deepEqual(normalizeConfig({ ui: { widget: "yes", entries: 1 } }).ui, { widget: false, entries: false }, "非布尔值一律回退");
+  assert.deepEqual(normalizeConfig({ ui: "on" }).ui, { widget: false, entries: false }, "整块类型不对就整块回退");
+});

package/extensions/skill-evolve/test/detect.test.ts

@@ -0,0 +1,71 @@
+/**
+ * 技能文件识别单测（零依赖，node --test）。
+ *
+ * 运行：
+ *   cd .pi/extensions/skill-evolve
+ *   node --experimental-strip-types --test test/detect.test.ts
+ *
+ * 覆盖：read 的绝对/相对/带 @ 路径、非技能文件不误判、bash 命令带引号与不带引号、
+ * 同一条命令里两个技能、以及路径以 `skills` 之外的目录名结尾时不误判。
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import { detectFromBash, detectFromRead, skillNameFromPath } from "../lib/detect.ts";
+
+const CWD = "/home/suveng/doger/ev/vkk_client_flutter";
+
+test("read：绝对路径命中技能", () => {
+  const hit = detectFromRead(`${CWD}/.pi/skills/kb-test-map/SKILL.md`, CWD);
+  assert.deepEqual(hit, { skill: "kb-test-map", how: "read", raw: `${CWD}/.pi/skills/kb-test-map/SKILL.md` });
+});
+
+test("read：相对路径按 cwd 解析成绝对路径", () => {
+  const hit = detectFromRead(".pi/skills/fast-test/SKILL.md", CWD);
+  assert.equal(hit?.skill, "fast-test");
+  assert.equal(hit?.raw, `${CWD}/.pi/skills/fast-test/SKILL.md`);
+});
+
+test("read：带 @ 前缀与反斜杠路径同样命中", () => {
+  assert.equal(detectFromRead("@.pi/skills/file-size/SKILL.md", CWD)?.skill, "file-size");
+  assert.equal(detectFromRead("C:\\repo\\.pi\\skills\\file-size\\SKILL.md", CWD)?.skill, "file-size");
+});
+
+test("read：非技能文件不误判", () => {
+  assert.equal(detectFromRead(".pi/skills/fast-test/reference.md", CWD), null);
+  assert.equal(detectFromRead("AGENTS.md", CWD), null);
+  assert.equal(detectFromRead("", CWD), null);
+});
+
+test("路径规则只认「父目录名 + SKILL.md」，是否真属曝光技能由上层过滤", () => {
+  // 裸 `SKILL.md` 会被解析成 <cwd>/SKILL.md，父目录名是仓库名；它永远不会命中本轮的曝光清单，
+  // 所以上层按 advertised 名字过滤后不会错记（见 evolution.ts 的 noteToolCall）
+  assert.equal(detectFromRead("SKILL.md", CWD)?.skill, "vkk_client_flutter");
+  assert.equal(skillNameFromPath("/repo/SKILL.md"), "repo");
+  assert.equal(skillNameFromPath("/repo/.pi/skills/"), null);
+  assert.equal(skillNameFromPath("/repo/.pi/skills/foo/assets/SKILL.md"), "assets");
+});
+
+test("bash：不带引号的 cat 命中", () => {
+  const hits = detectFromBash("cat .pi/skills/kb-test-map/SKILL.md | head -40");
+  assert.deepEqual(hits.map((hit) => hit.skill), ["kb-test-map"]);
+  assert.equal(hits[0].how, "bash");
+});
+
+test("bash：带双引号/单引号同样命中", () => {
+  assert.deepEqual(detectFromBash('sed -n "1,20p" ".pi/skills/fast-test/SKILL.md"').map((h) => h.skill), ["fast-test"]);
+  assert.deepEqual(detectFromBash("rg -n 标题 '.pi/skills/git-workflow/SKILL.md'").map((h) => h.skill), ["git-workflow"]);
+});
+
+test("bash：绝对路径 + 一条命令里两个技能，按名字去重", () => {
+  const hits = detectFromBash(
+    `diff -u ${CWD}/.pi/skills/rust/SKILL.md /tmp/rust/SKILL.md && cat .pi/skills/rust/SKILL.md`,
+  );
+  assert.deepEqual(hits.map((hit) => hit.skill), ["rust"]);
+});
+
+test("bash：不含 SKILL.md 的命令直接返回空数组", () => {
+  assert.deepEqual(detectFromBash("ls .pi/skills"), []);
+  assert.deepEqual(detectFromBash("cat README.md"), []);
+  assert.deepEqual(detectFromBash(""), []);
+});

package/extensions/skill-evolve/test/diff-apply.test.ts

@@ -0,0 +1,46 @@
+/**
+ * diff 应用单测：评审要看「改后全文」，diff 能不能精确落到基线上必须先证明。
+ * 不支持模糊定位是刻意的——定位失败时宁可如实说失败，也不能拼出一份假的改后全文。
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import { applyUnifiedDiff } from "../lib/diff-apply.ts";
+
+const BASE = ["---", "name: demo", "description: 旧描述", "---", "", "正文第一行", "正文第二行"].join("\n");
+
+test("标准 hunk 精确替换并返回文件名", () => {
+  const diff = ["--- a/.pi/skills/demo/SKILL.md", "+++ b/.pi/skills/demo/SKILL.md", "@@ -2,2 +2,2 @@", " name: demo", "-description: 旧描述", "+description: 新描述"].join("\n");
+  const result = applyUnifiedDiff(BASE, diff);
+  assert.equal(result.ok, true);
+  assert.equal(result.file, ".pi/skills/demo/SKILL.md");
+  assert.ok(result.text.includes("description: 新描述"));
+  assert.ok(!result.text.includes("旧描述"));
+  assert.ok(result.text.includes("正文第二行"));
+});
+
+test("行尾空白差异不算不匹配", () => {
+  const diff = ["+++ b/.pi/skills/demo/SKILL.md", "@@ -3,1 +3,1 @@", "-description: 旧描述   ", "+description: 新描述"].join("\n");
+  const result = applyUnifiedDiff(BASE, diff);
+  assert.equal(result.ok, true);
+});
+
+test("基线对不上就返回 ok:false 并给原因", () => {
+  const diff = ["+++ b/.pi/skills/demo/SKILL.md", "@@ -3,1 +3,1 @@", "-description: 完全不存在的行", "+description: 新描述"].join("\n");
+  const result = applyUnifiedDiff(BASE, diff);
+  assert.equal(result.ok, false);
+  assert.match(result.reason ?? "", /不一致/);
+});
+
+test("空 diff 视为失败而不是返回原文", () => {
+  const result = applyUnifiedDiff(BASE, "");
+  assert.equal(result.ok, false);
+  assert.equal(result.file, null);
+});
+
+test("多行增删都落到结果里", () => {
+  const diff = ["+++ b/.pi/skills/demo/SKILL.md", "@@ -6,2 +6,3 @@", " 正文第一行", "-正文第二行", "+正文第二行（改）", "+新增第三行"].join("\n");
+  const result = applyUnifiedDiff(BASE, diff);
+  assert.equal(result.ok, true);
+  assert.ok(result.text.includes("正文第二行（改）"));
+  assert.ok(result.text.includes("新增第三行"));
+});

package/extensions/skill-evolve/test/dispatch-busy.test.ts

@@ -0,0 +1,223 @@
+/**
+ * 全局单飞闸的三处接入点（用户 2026-11-08：「每次最多一个复盘agent」）：
+ * 派发 / 退出补发 / 评审督导都必须在已有活着子进程时**不 spawn**，并写 `skipped(busy)` 遥测。
+ *
+ * spawn 一律换成抛错或计数的假函数：这个文件不产生任何真进程。
+ */
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import test from "node:test";
+
+import { DEFAULT_CONFIG } from "../lib/config.ts";
+import { createDispatcher } from "../lib/dispatch.ts";
+import { spawnReviewSupervisor } from "../lib/review-spawn.ts";
+import { flushPendingSync } from "../lib/shutdown-dispatch.ts";
+import type { SpawnedChild, SpawnLike } from "../lib/spawn-plan.ts";
+import { directQueue, type TelemetryInput, type TelemetryWriter } from "../lib/telemetry.ts";
+
+const TEMPLATE = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "prompts", "复盘.md");
+const NOW = 1_760_000_000_000;
+const OCCUPIED_PID = 7777;
+
+class FakeChild {
+  readonly pid: number;
+  constructor(pid: number) {
+    this.pid = pid;
+  }
+  unref(): void {
+    // 测试里不存在真子进程，无需交还
+  }
+  once(): this {
+    // 不收尸：本文件只验证「有没有 spawn」，退出一条另有用例
+    return this;
+  }
+}
+
+interface Ctx {
+  cwd: string;
+  evolutionDir: string;
+  spawns: number;
+  supervisorSpawns: number;
+  events: TelemetryInput[];
+  syncEvents: TelemetryInput[];
+  telemetry: TelemetryWriter;
+  /** 只有 OCCUPIED_PID 算活着：其余 pid（含本进程）一律当已退出 */
+  alive: (pid: number) => boolean;
+}
+
+function workspace(): Ctx {
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "skill-evolve-busy-"));
+  const events: TelemetryInput[] = [];
+  const syncEvents: TelemetryInput[] = [];
+  const ctx: Ctx = {
+    cwd,
+    evolutionDir: path.join(cwd, ".pi", "evolution"),
+    spawns: 0,
+    supervisorSpawns: 0,
+    events,
+    syncEvents,
+    telemetry: {
+      append: (event) => events.push(event),
+      appendSync: (event) => syncEvents.push(event),
+      flush: async () => undefined,
+    },
+    alive: (pid) => pid === OCCUPIED_PID,
+  };
+  return ctx;
+}
+
+/** 造一条「已被别人占着」的 run：pid 活着 */
+function occupy(ctx: Ctx, runId = "other"): string {
+  const runDir = path.join(ctx.evolutionDir, "runs", runId);
+  fs.mkdirSync(runDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(runDir, "run.json"),
+    JSON.stringify({ runId, status: "dispatched", pid: OCCUPIED_PID, dispatchedAt: NOW - 60_000 }),
+    "utf8",
+  );
+  return runDir;
+}
+
+function readRun(runDir: string): Record<string, unknown> {
+  return JSON.parse(fs.readFileSync(path.join(runDir, "run.json"), "utf8"));
+}
+
+const noSpawn: SpawnLike = () => {
+  throw new Error("全局单飞闸挡住的派发不该 spawn");
+};
+
+test("dispatch：已有活的复盘子进程 → 不 spawn，返回 busy 并写遥测", async () => {
+  const ctx = workspace();
+  occupy(ctx);
+  const dispatcher = createDispatcher({
+    evolutionDir: ctx.evolutionDir,
+    cwd: ctx.cwd,
+    config: { ...DEFAULT_CONFIG, enabled: true, telemetry: true },
+    telemetry: ctx.telemetry,
+    queue: directQueue,
+    promptTemplatePath: TEMPLATE,
+    log: () => {},
+    now: () => NOW,
+    env: {},
+    spawnFn: noSpawn,
+    alive: ctx.alive,
+    supervisorSpawnFn: () => {
+      throw new Error("被挡住时也不该起督导");
+    },
+  });
+  const outcome = await dispatcher.dispatch({ sessionId: "s1", skills: ["fast-test"] });
+  assert.deepEqual(outcome, { status: "skipped", why: "busy", ownerPid: OCCUPIED_PID });
+  const busy = ctx.events.filter((event) => event.kind === "skipped" && event.why === "busy");
+  assert.equal(busy.length, 1);
+  assert.deepEqual(busy[0]!.occupant, { runId: "other", pid: OCCUPIED_PID, kind: "复盘" });
+  assert.equal(fs.existsSync(path.join(ctx.evolutionDir, "runs", "other", "child.log")), false, "占用者的东西不能被改");
+});
+
+test("dispatch：没有占用时照常派发（闸门不误伤正常路径）", async () => {
+  const ctx = workspace();
+  const calls: string[][] = [];
+  const spawnFn: SpawnLike = (_command, args) => {
+    calls.push(args);
+    return new FakeChild(4242) as unknown as SpawnedChild;
+  };
+  const dispatcher = createDispatcher({
+    evolutionDir: ctx.evolutionDir,
+    cwd: ctx.cwd,
+    config: { ...DEFAULT_CONFIG, enabled: true, telemetry: true },
+    telemetry: ctx.telemetry,
+    queue: directQueue,
+    promptTemplatePath: TEMPLATE,
+    log: () => {},
+    now: () => NOW,
+    env: {},
+    spawnFn,
+    alive: ctx.alive,
+    supervisorSpawnFn: () => null,
+  });
+  const outcome = await dispatcher.dispatch({ sessionId: "s1", skills: ["fast-test"] });
+  assert.equal(outcome.status, "dispatched");
+  assert.equal(calls.length, 1);
+});
+
+test("shutdown-dispatch：已有活的督导 → 不 spawn，同步写 busy，且不建新 run 目录", () => {
+  const ctx = workspace();
+  const runDir = occupy(ctx);
+  // 占用者只有督导活着（复盘 pid 已退出）：闸门看 supervisorPid 这一位
+  fs.writeFileSync(
+    path.join(runDir, "run.json"),
+    JSON.stringify({ runId: "other", status: "analyzed", pid: null, supervisorPid: OCCUPIED_PID, dispatchedAt: NOW }),
+    "utf8",
+  );
+  const before = fs.readdirSync(path.join(ctx.evolutionDir, "runs")).length;
+  const result = flushPendingSync(
+    { sessionId: "s1", since: NOW - 1000, rounds: 2, skills: ["fast-test"] },
+    {
+      evolutionDir: ctx.evolutionDir,
+      cwd: ctx.cwd,
+      promptTemplatePath: TEMPLATE,
+      maxRuntimeMs: 20 * 60_000,
+      telemetry: ctx.telemetry,
+      env: {},
+      spawnFn: noSpawn,
+      alive: ctx.alive,
+      log: () => {},
+    },
+    NOW,
+  );
+  assert.equal(result, "skipped");
+  assert.equal(fs.readdirSync(path.join(ctx.evolutionDir, "runs")).length, before, "被挡住就不该留下半成品 run");
+  const busy = ctx.syncEvents.filter((event) => event.kind === "skipped" && event.why === "busy");
+  assert.equal(busy.length, 1, "退出路径必须同步落盘（异步 append 可能来不及写）");
+  assert.equal(busy[0]!.trigger, "shutdown");
+  assert.equal(busy[0]!.rounds, 2);
+});
+
+test("review-spawn：别的 run 的复盘活着 → 不起督导，写 busy 遥测", () => {
+  const ctx = workspace();
+  occupy(ctx);
+  const runDir = path.join(ctx.evolutionDir, "runs", "mine");
+  fs.mkdirSync(runDir, { recursive: true });
+  fs.writeFileSync(path.join(runDir, "run.json"), JSON.stringify({ runId: "mine", status: "dispatched" }), "utf8");
+
+  const pid = spawnReviewSupervisor({
+    runDir,
+    cwd: ctx.cwd,
+    env: {},
+    telemetry: ctx.telemetry,
+    alive: ctx.alive,
+    log: () => {},
+    spawnFn: () => {
+      throw new Error("被挡住时不该起督导");
+    },
+  });
+  assert.equal(pid, null);
+  const busy = ctx.events.filter((event) => event.kind === "skipped" && event.why === "busy");
+  assert.equal(busy.length, 1);
+  assert.equal(busy[0]!.occupant.runId, "other");
+  assert.equal(readRun(runDir).supervisorPid, undefined, "没起督导就不能写 supervisorPid");
+});
+
+test("review-spawn：自己这条 run 的复盘活着不算占用，起督导并把 pid 写进 supervisorPid", () => {
+  const ctx = workspace();
+  const runDir = path.join(ctx.evolutionDir, "runs", "mine");
+  fs.mkdirSync(runDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(runDir, "run.json"),
+    JSON.stringify({ runId: "mine", status: "dispatched", pid: OCCUPIED_PID }),
+    "utf8",
+  );
+  const pid = spawnReviewSupervisor({
+    runDir,
+    cwd: ctx.cwd,
+    env: {},
+    telemetry: ctx.telemetry,
+    alive: ctx.alive,
+    log: () => {},
+    spawnFn: () => ({ pid: 9090, unref: () => undefined }),
+  });
+  assert.equal(pid, 9090);
+  assert.equal(readRun(runDir).supervisorPid, 9090, "督导 pid 是第二个占用位，必须落盘");
+});

package/extensions/skill-evolve/test/dispatch-supervisor.test.ts

@@ -0,0 +1,88 @@
+/**
+ * 派发 ↔ 评审督导的接线单测：同一次派发里必须同时起复盘与督导，
+ * 而「自检没过」这道门禁必须早于任何 spawn（否则白起一个 900 秒的轮询进程）。
+ */
+import { test } from "node:test";
+import assert from "node:assert/strict";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { DEFAULT_CONFIG, type EvolutionConfig } from "../lib/config.ts";
+import { createDispatcher } from "../lib/dispatch.ts";
+import type { SpawnedChild, SpawnLike } from "../lib/spawn-plan.ts";
+import { directQueue, type TelemetryEvent, type TelemetryInput, type TelemetryWriter } from "../lib/telemetry.ts";
+import { fakeSupervisorSpawn } from "./fake-review-spawn.ts";
+
+const TEMPLATE = path.join(path.dirname(fileURLToPath(import.meta.url)), "..", "prompts", "复盘.md");
+const NOW = 1_760_000_000_000;
+
+class FakeChild {
+  readonly pid = process.pid;
+  unref(): void {}
+  once(): this {
+    return this;
+  }
+}
+
+function harness(options: { config?: Partial<EvolutionConfig>; selftestFailed?: () => boolean; reviewModel?: () => string } = {}) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-evolve-sup-"));
+  const events: TelemetryEvent[] = [];
+  const supervisorCalls: { args: string[]; options: Record<string, unknown> }[] = [];
+  const writer: TelemetryWriter = {
+    append: (event: TelemetryInput) => {
+      events.push({ ...event, ts: NOW, iso: "" } as TelemetryEvent);
+    },
+    appendSync: (event: TelemetryInput) => {
+      events.push({ ...event, ts: NOW, iso: "" } as TelemetryEvent);
+    },
+    flush: async () => undefined,
+  };
+  const spawnFn: SpawnLike = () => new FakeChild() as unknown as SpawnedChild;
+  const dispatcher = createDispatcher({
+    evolutionDir: path.join(dir, ".pi", "evolution"),
+    cwd: dir,
+    // 生产默认全关（clone 即静默）：夹具必须显式打开，否则派发用例会被「未启用」跳过
+    config: { ...DEFAULT_CONFIG, enabled: true, telemetry: true, ...options.config },
+    telemetry: writer,
+    queue: directQueue,
+    promptTemplatePath: TEMPLATE,
+    log: () => {},
+    now: () => NOW,
+    env: {},
+    spawnFn,
+    // 假子进程 pid = 本进程 pid：单飞闸靠注入的 alive 模拟「子进程已退出」，否则督导那一跳被自己的复盘挡住
+    alive: () => false,
+    ...(options.reviewModel ? { reviewModel: options.reviewModel } : {}),
+    ...(options.selftestFailed ? { selftestFailed: options.selftestFailed } : {}),
+    supervisorSpawnFn: fakeSupervisorSpawn(supervisorCalls),
+  });
+  return { dir, events, supervisorCalls, dispatch: dispatcher.dispatch };
+}
+
+test("派发成功时同一轮就起评审督导，并把评审模型透传过去", async () => {
+  const h = harness({ reviewModel: () => "deepseek/deepseek-v3.2" });
+  const outcome = await h.dispatch({ sessionId: "sess-1", skills: ["alpha"] });
+  assert.equal(outcome.status, "dispatched");
+  assert.equal(h.supervisorCalls.length, 1, "必须起且只起一个督导");
+  const args = h.supervisorCalls[0].args;
+  assert.ok(args[args.length - 2].endsWith("run-1") || args[2].includes("runs"), `args=${args.join(" ")}`);
+  assert.equal(args[args.length - 1], "deepseek/deepseek-v3.2");
+});
+
+test("总开关关闭：既不复盘也不起督导", async () => {
+  const h = harness({ config: { enabled: false } });
+  const outcome = await h.dispatch({ sessionId: "sess-1", skills: ["alpha"] });
+  assert.equal(outcome.status, "skipped");
+  assert.equal(h.supervisorCalls.length, 0);
+});
+
+test("必红自检没过：跳过派发并记 skipped/selftest-failed", async () => {
+  const h = harness({ selftestFailed: () => true });
+  const outcome = await h.dispatch({ sessionId: "sess-1", skills: ["alpha"] });
+  assert.equal(outcome.status, "skipped");
+  assert.equal(outcome.status === "skipped" ? outcome.why : "", "selftest-failed");
+  assert.equal(h.supervisorCalls.length, 0, "自检没过时不得起督导");
+  const skipped = h.events.find((event) => event.kind === "skipped");
+  assert.equal((skipped as unknown as { why?: string }).why, "selftest-failed");
+});