pi-skill-evolve 0.1.12 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [0.1.13] - 2026-11-09
+
+同一个工作区开两个 pi（两个窗口 / 一个窗口执行中另开一个）时的两条竞态。
+
+- 修复：两个实例的 `session_start` 都会重挂督导，单飞闸只认「已经写进 `run.json` 的活 pid」，两边 spawn 之间的空档会各起一个督导（双花 token、双写 `03-review.json`）。现在重挂前先抢 `locks/supervisor`，抢到后再复核一次 `supervisorPid`，后到者直接写 `respawn-blocked`「另一个 pi 实例正在重挂督导」
+- 修复：两个实例同时扫队列采纳会互相覆盖 `queue.json`（读-改-写），同一份 diff 甚至可能被各应用一次。`session_start` / `settle` 的「扫队列 → 应用」整段现在抢 `locks/apply`，抢不到就跳过，下一次会话起点再来
+- 新增：`lockDir(evolutionDir, name)` 支持多把锁（`dispatch` / `supervisor` / `apply`，缺省仍是 `dispatch`，老行为不变）；`withLock()` 跨进程互斥执行，异常也保证释放
+- 测试：685 → 688（新增「两个 pi 同时恢复只起一个督导」「两把锁互不干扰」「withLock 忙时让位 + 抛错也释放」）；另用两个真实 node 进程并发跑恢复验证：`spawn` 计数 1，一个 `supervisor-respawned`、一个 `respawn-blocked`
+
 ## [0.1.12] - 2026-11-09
 
 按 npm 包安装时「评审 → 采纳」整条链原本一次都跑不起来，这个版本修掉它，并把每轮复盘画成五段流水线。

package/README.md

@@ -48,6 +48,15 @@ pi install git:github.com/suveng/pi-skill-evolve
 | 评审 | `03-review.json` | 提案在、督导不在 → 下次会话起点自动重挂 |
 | 采纳 | `04-decision.json` | 自动采纳关着 → 面板待审批页批准 |
 
+### 一个工作区开两个 pi
+
+同时开两个 pi 窗口（或一个在跑、另开一个）时：
+
+- **复盘派发**：`locks/dispatch` 原子锁，任意时刻只有一个 run 在跑，另一个只写一条 `skipped(busy)`
+- **重挂督导**：`locks/supervisor` + 抢到锁后复核 `supervisorPid`，只有一边起督导，另一边记「另一个 pi 实例正在重挂督导」
+- **扫队列 / 采纳**：`locks/apply` 独占，「读-改-写 `queue.json`」与应用 diff 不会被两边同时做；抢不到的那一边跳过，下次 `settle` / 会话起点再来
+- **Web 面板**：`locks/web.json` 记持有者，第二个实例不抢端口，只在日志里说「由 pid N 持有」；`/skill-evolve status` 在任何一边都能看到面板地址
+
 ### 重启恢复
 
 `/reload` 或重启会丢掉内存里的收尸逻辑（`watchRunChild` 的回调），所以 `session_start` 会跑一次恢复：补 `analyzed` 状态、重挂被带走的督导、其余不动。**永不重跑复盘**（花 token 且会覆盖已有产物），有动作时用一行通知说明补了什么。

package/extensions/skill-evolve/lib/evolution-apply.ts

@@ -14,6 +14,7 @@ import { classifyChange } from "./classify-action.ts";
 import { captureGate0, saveGate0, type GitRunner } from "./gate0.ts";
 import { buildPrunePlan, renderPrunePlan } from "./prune-plan.ts";
 import { enqueue, findItem, markDone, readQueue, takePending, type QueueItem, type QueueStatus } from "./queue.ts";
+import { withLock } from "./lock.ts";
 import { logLine } from "./logfile.ts";
 import { updateRunStatus } from "./runs.ts";
 import type { MutationQueue } from "./telemetry.ts";
@@ -56,6 +57,8 @@ const READY_STATUS = "reviewed";
 /** 评审关着时 run 停在这里：提案写完了、没人看过，仍然入队等人工批准 */
 const PROPOSED_STATUS = "proposed";
 const MAX_SCAN = 50;
+/** 采纳链的锁上限：一次扫队列 + 应用几份 diff，正常两秒内完成；锁主崩了 5 分钟后可回收 */
+const APPLY_LOCK_MS = 5 * 60_000;
 
 function readText(file: string): string | null {
   try {
@@ -225,10 +228,33 @@ export function createApplyTools(deps: ApplyToolsDeps): ApplyTools {
     return applied;
   };
 
+  /**
+   * 采纳链（扫队列 → 应用）跨实例互斥。
+   *
+   * 为什么需要：同一个工作区开两个 pi 时，两边的 `session_start` / `settle` 都会扫同一份 queue.json。
+   * 队列是「读-改-写」，两个进程同时写会互相覆盖；`autoApplyPending` 更糟 —— 同一份 diff 可能被
+   * 两个进程各应用一次。抢不到锁的那一方直接跳过，下一次 settle / 会话起点还会再来。
+   */
+  const withApplyLock = async (run: () => Promise<unknown>): Promise<void> => {
+    const got = await withLock(
+      {
+        evolutionDir: deps.evolutionDir,
+        name: "apply",
+        owner: { pid: process.pid, ts: now() },
+        maxRuntimeMs: APPLY_LOCK_MS,
+        log,
+      },
+      run,
+    );
+    if (!got.ok) {
+      log(`[skill-evolve] 采纳链由另一个 pi 实例持有（locks/apply pid ${got.owner?.pid ?? "?"}），本次跳过`);
+    }
+  };
+
   const scanAndApply = (): void => {
-    void enqueueReady()
-      .then(() => autoApplyPending())
-      .catch((error: unknown) => log(`[skill-evolve] 采纳扫描失败：${String(error)}`));
+    void withApplyLock(() => enqueueReady().then(() => autoApplyPending())).catch((error: unknown) =>
+      log(`[skill-evolve] 采纳扫描失败：${String(error)}`),
+    );
   };
 
   const sessionStart: ApplyTools["sessionStart"] = () => {
@@ -239,8 +265,7 @@ export function createApplyTools(deps: ApplyToolsDeps): ApplyTools {
       log(`[skill-evolve] 备份清理失败：${String(error)}`);
     }
     void saveGate0(deps.evolutionDir, captureGate0(deps.git, deps.cwd, time), deps.queue)
-      .then(() => enqueueReady())
-      .then(() => autoApplyPending())
+      .then(() => withApplyLock(() => enqueueReady().then(() => autoApplyPending())))
       .catch((error: unknown) => log(`[skill-evolve] 会话起点初始化失败：${String(error)}`));
   };
 

package/extensions/skill-evolve/lib/evolution.ts

@@ -97,7 +97,7 @@ export interface Evolution {
    * 重启 / `/reload` 后的接手：补状态、重挂督导师（详见 lib/recover.ts）。
    * 返回本次做了什么，面板与日志都靠它告诉用户「后台任务没丢」。
    */
-  recover(): Promise<RecoveryAction[]>;
+  recover(sessionId?: string): Promise<RecoveryAction[]>;
   /** 最近一次恢复的结果（面板可视化用；本进程内有效） */
   lastRecovery(): RecoveryAction[];
 }
@@ -283,7 +283,7 @@ export function createEvolution(deps: EvolutionDeps): Evolution {
    * 同步抛错也在这里吞：会话起点不能被恢复流程搞挂。
    */
   let lastActions: RecoveryAction[] = [];
-  const recover = async (): Promise<RecoveryAction[]> => {
+  const recover = async (sessionId?: string): Promise<RecoveryAction[]> => {
     try {
       lastActions = await recoverRuns({
         evolutionDir,
@@ -295,6 +295,7 @@ export function createEvolution(deps: EvolutionDeps): Evolution {
         reviewModel: modelTools.reviewModel,
         ...(deps.alive ? { alive: deps.alive } : {}),
         ...(deps.supervisorSpawnFn ? { spawnSupervisor: deps.supervisorSpawnFn } : {}),
+        ...(sessionId ? { sessionId } : {}),
         log,
       });
     } catch (error) {

package/extensions/skill-evolve/lib/lock.ts

@@ -27,8 +27,11 @@ export function isPidAlive(pid: number): boolean {
   }
 }
 
-export function lockDir(evolutionDir: string): string {
-  return path.join(evolutionDir, "locks", "dispatch");
+/** 锁名 → 目录名。`dispatch` 是复盘派发的老锁；`supervisor` / `apply` 是 0.1.13 加的跨实例锁 */
+export type LockName = "dispatch" | "supervisor" | "apply";
+
+export function lockDir(evolutionDir: string, name: LockName = "dispatch"): string {
+  return path.join(evolutionDir, "locks", name);
 }
 
 /**
@@ -71,6 +74,8 @@ export async function readOwner(dir: string): Promise<LockOwner | null> {
 
 export interface AcquireOptions {
   evolutionDir: string;
+  /** 哪把锁，缺省 `dispatch`（老行为不变） */
+  name?: LockName;
   owner: LockOwner;
   maxRuntimeMs: number;
   log?: (msg: string) => void;
@@ -86,7 +91,7 @@ export interface AcquireResult {
 
 export async function acquireLock(options: AcquireOptions): Promise<AcquireResult> {
   const log = options.log ?? (() => {});
-  const dir = lockDir(options.evolutionDir);
+  const dir = lockDir(options.evolutionDir, options.name);
   const now = options.now?.() ?? Date.now();
 
   for (let attempt = 0; attempt < 2; attempt += 1) {
@@ -119,7 +124,7 @@ export async function acquireLock(options: AcquireOptions): Promise<AcquireResul
     } catch (error) {
       // 目录建好了但 owner 写不进去：立刻还回去，避免留下无人认领的锁
       log(`[skill-evolve] 写 owner.json 失败：${String(error)}`);
-      await releaseLock(options.evolutionDir, options.log);
+      await releaseLock(options.evolutionDir, options.log, options.name);
       return { ok: false, why: "error" };
     }
   }
@@ -127,8 +132,12 @@ export async function acquireLock(options: AcquireOptions): Promise<AcquireResul
 }
 
 /** 释放锁（幂等）：目录不在也算成功 */
-export async function releaseLock(evolutionDir: string, log: (msg: string) => void = () => {}): Promise<void> {
-  const dir = lockDir(evolutionDir);
+export async function releaseLock(
+  evolutionDir: string,
+  log: (msg: string) => void = () => {},
+  name: LockName = "dispatch",
+): Promise<void> {
+  const dir = lockDir(evolutionDir, name);
   try {
     await fs.promises.rm(dir, { recursive: true, force: true });
   } catch (error) {
@@ -146,7 +155,7 @@ function writeOwnerFile(dir: string, owner: LockOwner): void {
  */
 export function acquireLockSync(options: AcquireOptions): AcquireResult {
   const log = options.log ?? (() => {});
-  const dir = lockDir(options.evolutionDir);
+  const dir = lockDir(options.evolutionDir, options.name);
   const now = options.now?.() ?? Date.now();
 
   for (let attempt = 0; attempt < 2; attempt += 1) {
@@ -177,7 +186,7 @@ export function acquireLockSync(options: AcquireOptions): AcquireResult {
       return { ok: true };
     } catch (error) {
       log(`[skill-evolve] 写 owner.json 失败：${String(error)}`);
-      releaseLockSync(options.evolutionDir, options.log);
+      releaseLockSync(options.evolutionDir, options.log, options.name);
       return { ok: false, why: "error" };
     }
   }
@@ -189,9 +198,10 @@ export function writeOwnerSync(
   evolutionDir: string,
   owner: LockOwner,
   log: (msg: string) => void = () => {},
+  name: LockName = "dispatch",
 ): boolean {
   try {
-    writeOwnerFile(lockDir(evolutionDir), owner);
+    writeOwnerFile(lockDir(evolutionDir, name), owner);
     return true;
   } catch (error) {
     log(`[skill-evolve] 改写 owner.json 失败：${String(error)}`);
@@ -200,9 +210,13 @@ export function writeOwnerSync(
 }
 
 /** 同步放锁：只给同步补发路径用（失败也只记日志） */
-export function releaseLockSync(evolutionDir: string, log: (msg: string) => void = () => {}): void {
+export function releaseLockSync(
+  evolutionDir: string,
+  log: (msg: string) => void = () => {},
+  name: LockName = "dispatch",
+): void {
   try {
-    fs.rmSync(lockDir(evolutionDir), { recursive: true, force: true });
+    fs.rmSync(lockDir(evolutionDir, name), { recursive: true, force: true });
   } catch (error) {
     log(`[skill-evolve] 释放锁失败：${String(error)}`);
   }
@@ -213,3 +227,30 @@ export async function lockState(evolutionDir: string): Promise<{ held: boolean;
   const held = fs.existsSync(dir);
   return { held, owner: held ? await readOwner(dir) : null };
 }
+
+export interface WithLockResult<T> {
+  ok: boolean;
+  value?: T;
+  why?: "busy" | "error";
+  /** 抢失败时的持有者：调用方可以据此说「另一个 pi 实例正在做」 */
+  owner?: LockOwner | null;
+}
+
+/**
+ * 跨实例互斥执行：抢到锁就执行并保证在 finally 里释放；抢不到立刻返回（不排队、不重试）。
+ *
+ * 为什么不做「等一会儿再抢」：这些锁护的都是毫秒级动作（spawn 督导、扫一遍队列采纳），
+ * 排队只会把两个 pi 会话互相拖慢；抢不到的那一方跳过即可，下一次 session_start 还会再来。
+ */
+export async function withLock<T>(
+  options: AcquireOptions & { name: LockName },
+  run: () => Promise<T> | T,
+): Promise<WithLockResult<T>> {
+  const got = await acquireLock(options);
+  if (!got.ok) return { ok: false, why: got.why ?? "busy", owner: got.owner ?? null };
+  try {
+    return { ok: true, value: await run() };
+  } finally {
+    await releaseLock(options.evolutionDir, options.log, options.name);
+  }
+}

package/extensions/skill-evolve/lib/recover.ts

@@ -13,6 +13,7 @@
  */
 import * as fs from "node:fs";
 import * as path from "node:path";
+import { withLock } from "./lock.ts";
 import { spawnReviewSupervisor, type SpawnSupervisorOptions } from "./review-spawn.ts";
 import { listRuns, updateRunStatus, type RunRecord } from "./runs.ts";
 import type { MutationQueue } from "./telemetry.ts";
@@ -56,10 +57,26 @@ export interface RecoverDeps {
   autoReview?: () => boolean;
   reviewModel?: () => string;
   spawnSupervisor?: (options: SpawnSupervisorOptions) => number | null;
+  /** 本会话 ID：写进锁 owner.json，排查「谁在重挂」时有用 */
+  sessionId?: string;
   log?: (msg: string) => void;
   windowMs?: number;
 }
 
+/** 督导锁只护「起来 + 写 supervisorPid」这几毫秒，留 60 秒足够，锁主崩了也不会长期占住 */
+const SUPERVISOR_LOCK_MS = 60_000;
+
+/** 抢到锁后重新确认「这条 run 的督导确实不在」，防止两边都判死、抢完各起一个 */
+function supervisorStillGone(
+  runDir: string,
+  record: RunRecord,
+  alive: (pid: number) => boolean,
+): boolean {
+  const fresh = readRecord(runDir) ?? record;
+  const pid = fresh.supervisorPid;
+  return !(typeof pid === "number" && alive(pid));
+}
+
 function exists(runDir: string, name: string): boolean {
   try {
     return fs.statSync(path.join(runDir, name)).isFile();
@@ -146,15 +163,45 @@ export async function recoverRuns(deps: RecoverDeps): Promise<RecoveryAction[]>
       actions.push({ runId, kind: "respawn-blocked", detail: "自动评审关着：停在待人工 /skill-evolve approve" });
       continue;
     }
-    const pid = spawnSupervisor({
-      runDir,
-      cwd: deps.cwd,
-      autoReview: true,
-      reviewModel: deps.reviewModel?.() ?? "inherit",
-      ...(deps.env ? { env: deps.env } : {}),
-      ...(deps.alive ? { alive: deps.alive } : {}),
-      log,
-    });
+    // 3. 跨实例互斥：同一个工作区开两个 pi 时，两边 session_start 都会走到这里。
+    //    单飞闸只认「已经写进 run.json 的活 pid」，两边的 spawn 之间有空档，会各起一个督导（双花 token、双写 03-review）。
+    //    所以先用 locks/supervisor 抢一下，抢不到说明对面那份正在重挂，让它挂。
+    const spawned = await withLock(
+      {
+        evolutionDir: deps.evolutionDir,
+        name: "supervisor",
+        owner: { pid: process.pid, ts: now(), ...(deps.sessionId ? { sessionId: deps.sessionId } : {}) },
+        maxRuntimeMs: SUPERVISOR_LOCK_MS,
+        log,
+        ...(deps.now ? { now: deps.now } : {}),
+      },
+      () =>
+        // 抢到锁后再判一次：对面可能刚好在抢锁之前写完 supervisorPid
+        supervisorStillGone(runDir, record, alive)
+          ? spawnSupervisor({
+              runDir,
+              cwd: deps.cwd,
+              autoReview: true,
+              reviewModel: deps.reviewModel?.() ?? "inherit",
+              ...(deps.env ? { env: deps.env } : {}),
+              ...(deps.alive ? { alive: deps.alive } : {}),
+              log,
+            })
+          : "taken", 
+    );
+    if (!spawned.ok) {
+      actions.push({
+        runId,
+        kind: "respawn-blocked",
+        detail: `另一个 pi 实例正在重挂督导（locks/supervisor 被 pid ${spawned.owner?.pid ?? "?"} 持有）`,
+      });
+      continue;
+    }
+    const pid = spawned.value;
+    if (pid === "taken") {
+      actions.push({ runId, kind: "waiting-review", detail: "等到锁时督导已经在了（另一个实例刚挂上），不重复起" });
+      continue;
+    }
     actions.push(
       pid === null
         ? { runId, kind: "respawn-blocked", detail: "督导没起来（单飞闸占满或 spawn 失败），下次会话起点还会再试" }

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

@@ -14,7 +14,7 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
-import { acquireLock, acquireLockSync, isPidAlive, lockDir, readOwnerSync, releaseLock, releaseLockSync, shouldReclaim, writeOwnerSync } from "../lib/lock.ts";
+import { acquireLock, acquireLockSync, isPidAlive, lockDir, readOwnerSync, releaseLock, releaseLockSync, shouldReclaim, withLock, writeOwnerSync } from "../lib/lock.ts";
 
 const MAX = 20 * 60_000;
 const NOW = 1_760_000_000_000;
@@ -136,3 +136,40 @@ test("writeOwnerSync：把持有者换成子进程 pid，供 status 与孤儿判
   assert.deepEqual(readOwnerSync(lockDir(dir)), { pid: 4321, ts: NOW + 1, sessionId: "s1" });
   releaseLockSync(dir);
 });
+
+test("lockDir：不同名字的锁互不干扰（派发锁被占不影响督导锁）", async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-evolve-lock-name-"));
+  const base = { evolutionDir: dir, owner: { pid: process.pid, ts: NOW }, maxRuntimeMs: MAX, now: () => NOW };
+  const dispatch = await acquireLock(base);
+  assert.equal(dispatch.ok, true);
+  const supervisor = await acquireLock({ ...base, name: "supervisor" });
+  assert.equal(supervisor.ok, true, "另一个名字的锁应当能独立抢到");
+  assert.equal(fs.existsSync(path.join(dir, "locks", "supervisor")), true);
+  await releaseLock(dir, () => {}, "supervisor");
+  await releaseLock(dir);
+  assert.equal(fs.existsSync(path.join(dir, "locks")), true, "locks 父目录留着，空的子目录删干净");
+  assert.deepEqual(fs.readdirSync(path.join(dir, "locks")), []);
+});
+
+test("withLock：忙时直接返回 why=busy 不执行；跑完一定释放（抛错也释放）", async () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "skill-evolve-withlock-"));
+  const options = { evolutionDir: dir, name: "apply" as const, owner: { pid: process.pid, ts: NOW }, maxRuntimeMs: MAX, now: () => NOW };
+  const first = await withLock(options, async () => {
+    const inner = await withLock(options, () => "不该执行");
+    assert.equal(inner.ok, false);
+    assert.equal(inner.why, "busy");
+    return "done";
+  });
+  assert.equal(first.ok, true);
+  assert.equal(first.value, "done");
+  // 异常要往上抛（调用方自己决定记什么日志），但锁必须已经放掉
+  await assert.rejects(
+    withLock(options, () => {
+      throw new Error("模拟采纳中途崩");
+    }),
+    /模拟采纳中途崩/,
+  );
+  assert.equal(fs.existsSync(path.join(dir, "locks", "apply")), false, "抛错也要释放，否则下次永远 busy");
+  const again = await withLock(options, () => "又抢到了");
+  assert.equal(again.ok, true);
+});

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

@@ -151,3 +151,27 @@ test("面板文案带 kinds 与明细", () => {
   assert.match(text, /r-1 {2}重挂督导 — 重挂 pid 9/);
   assert.match(text, /r-2 {2}已中断 — 没提案/);
 });
+
+test("一个工作区两个 pi 同时启动恢复：督导只起一个（另一个看到锁里已经挂上了）", async () => {
+  const { evolutionDir, write } = setup();
+  write("r-9", { status: "analyzed", pid: null, supervisorPid: null }, ["01-findings.json", "02-proposal.json"]);
+  let spawns = 0;
+  const spawnSupervisor = (options: SpawnSupervisorOptions): number => {
+    spawns += 1;
+    // 模拟真实现：spawn 之后立刻把 supervisorPid 写回 run.json（这就是后到者的判断依据）
+    const file = path.join(options.runDir, "run.json");
+    const raw = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown>;
+    fs.writeFileSync(file, JSON.stringify({ ...raw, supervisorPid: process.pid }, null, 2));
+    return process.pid;
+  };
+  // 督导 pid 就是本进程 pid：重挂后它「活着」，这正是后到者的判断依据
+  const deps = base({ evolutionDir, spawnSupervisor, alive: (pid) => pid === process.pid });
+  const both = await Promise.all([recoverRuns(deps), recoverRuns(deps)]);
+  assert.equal(spawns, 1, "两个实例各起一个督导 = 双花 token + 双写 03-review");
+  const kinds = both.flat().map((action) => action.kind);
+  assert.ok(
+    kinds.includes("supervisor-respawned") || kinds.includes("respawn-blocked"),
+    `应当有人挂上、有人让位（实际 ${kinds.join(",")}）`,
+  );
+  assert.ok(!kinds.includes("interrupted"), "提案在、督导被重挂，不该判成中断");
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-skill-evolve",
-  "version": "0.1.12",
+  "version": "0.1.13",
   "description": "技能进化：采集会话中的技能曝光/加载，异步复盘、生成改进提案并独立评审，附本机 Web 管理面板",
   "keywords": [
     "pi-package",