pi-skill-evolve 0.1.10 → 0.1.12

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## [0.1.12] - 2026-11-09
+
+按 npm 包安装时「评审 → 采纳」整条链原本一次都跑不起来，这个版本修掉它，并把每轮复盘画成五段流水线。
+
+- 修复（事故）：`review-supervisor` 在 `node_modules` 里被 `node --experimental-strip-types` 拒绝（`ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING`），督导一起就崩。新增 `lib/supervisor-runtime.ts`：把督导依赖闭包先复制到 `.pi/evolution/runtime/supervisor/<版本-指纹>/`（排除 `*.test.*`、`.ready` 标记、升级清旧目录），搬不动回退原路径只记日志
+- 修复：督导「起来但什么都不做，退出码 0」——`import.meta.url` 与 `process.argv[1]` 直接比字符串，macOS `/tmp` 软链（`/private/tmp`）会判成「不是直接运行」。改 `isDirectInvocation()` 用 `realpathSync` 双向比对
+- 新增：`lib/pipeline.ts` 五段流水线（派发 → 分析 → 提案 → 评审 → 采纳），每段状态取 `done/running/waiting/blocked/failed/skipped`，只看磁盘产物与 pid，不猜进度；卡住那段直接写「下次会话起点自动重挂」之类的接手方式
+- 面板：run 详情页顶部新增「流水线」一排格子（状态色 + 明细 + 时刻 + 一句话 hint），排在概要之前；待处理页的「正在跑」条目多一行 `流水线：派发✓ 分析… 提案· 评审· 采纳·`
+- 新增：`lib/recover.ts` 重启 / `/reload` 后自动接手 —— 分析产物在而状态还是 `dispatched` 就补成 `analyzed`；有提案但督导已死就重挂督导；复盘子进程还活着则不打扰；**绝不重跑复盘**
+- 会话起点（`session_start`）会调 `recover()`，有动作时用一行通知说明补了什么
+- 测试：664 → 685 条（新增 `supervisor-runtime`、`recover`、`pipeline` 三组用例）
+
 ## [0.1.0] - 2026-11-08
 
 首个可用版本。

package/README.md

@@ -36,6 +36,22 @@ pi install git:github.com/suveng/pi-skill-evolve
 
 只绑 `127.0.0.1`、零鉴权、写操作带 CSRF 与同源校验；远程看用 `ssh -L 7788:127.0.0.1:7788`。
 
+### 流水线
+
+每条 run 都走五段，run 详情页顶部会画出这五格（状态词 + 明细 + 时刻 + 一句话 hint）：
+
+| 段 | 完成的标志 | 卡住时谁接手 |
+|---|---|---|
+| 派发 | `run.json` | — |
+| 分析 | `01-findings.json` | 子进程退出没产物 → 卡死判定收尾 |
+| 提案 | `02-proposal.json` | 分析已结束却没提案 = 判定「不该改」，正常结束 |
+| 评审 | `03-review.json` | 提案在、督导不在 → 下次会话起点自动重挂 |
+| 采纳 | `04-decision.json` | 自动采纳关着 → 面板待审批页批准 |
+
+### 重启恢复
+
+`/reload` 或重启会丢掉内存里的收尸逻辑（`watchRunChild` 的回调），所以 `session_start` 会跑一次恢复：补 `analyzed` 状态、重挂被带走的督导、其余不动。**永不重跑复盘**（花 token 且会覆盖已有产物），有动作时用一行通知说明补了什么。
+
 ## 配置
 
 `.pi/evolution/config.json`（建议 gitignore，开关是本机偏好）：

package/extensions/skill-evolve/index.ts

@@ -16,6 +16,7 @@ import { createEvolution, type Evolution } from "./lib/evolution.js";
 import { logLine } from "./lib/logfile.js";
 import { deliverNotifications } from "./lib/notify.js";
 import { entryLines, type PanelEntry, type PanelState } from "./lib/panel.js";
+import { renderRecovery } from "./lib/recover.js";
 import { renderPanel, writeEntry, type UiPanelHost } from "./lib/ui-gate.js";
 import { startWebPanel } from "./lib/web/server.js";
 import { createWebLifecycle } from "./lib/web/autostart.js";
@@ -233,6 +234,15 @@ export default function skillEvolve(pi: ExtensionAPI): void {
   pi.on("session_start", async (_event, ctx) => {
     guarded(ctx, "session_start", (evo) => {
       evo.apply.sessionStart();
+      // `/reload` 与重启会丢掉内存里的收尸逻辑：这里补状态、重挂被带走的督导（不重跑复盘）
+      void evo.recover().then((actions) => {
+        if (actions.length > 0) {
+          // 通知只有一行：把多行恢复报告压成 ` / ` 分隔
+          const brief = renderRecovery(actions).replace(/\n\s*/g, " / ");
+          ctx.ui.notify(brief, "info");
+        }
+        evo.observe.refresh();
+      });
       evo.observe.refresh();
       // 上一轮没送出去的失败/待批，这里补发（notified.json 保证不重复）
       notifyEvents(ctx.cwd);

package/extensions/skill-evolve/lib/dispatch-types.ts

@@ -51,7 +51,7 @@ export type DispatchOutcome =
   | { status: "dispatched"; run: DispatchedRun }
   | {
       status: "skipped";
-      why: "disabled" | "cap" | "lock" | "lock-error" | "selftest-failed" | "busy";
+      why: "disabled" | "cap" | "lock" | "lock-error" | "selftest-failed" | "busy" | "pi-not-found";
       ownerPid: number | null;
     }
   | { status: "superseded"; rounds: number }

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

@@ -16,7 +16,7 @@ import { acquireLock, releaseLock, writeOwnerSync } from "./lock.ts";
 import { buildPrompt, readPromptTemplateSync } from "./prompt.ts";
 import { writeRunRecord } from "./runs.ts";
 import { writeSessionIndex } from "./session-index.ts";
-import { CHILD_LOG, resolvePiBin, spawnDetached, uniqueRunId, sessionHashOf } from "./spawn-plan.ts";
+import { CHILD_LOG, isExecutableFile, resolvePiBin, spawnDetached, uniqueRunId, sessionHashOf } from "./spawn-plan.ts";
 import { mergePendingRounds } from "./pending.ts";
 import { watchRunChild } from "./run-watch.ts";
 import { spawnReviewSupervisor } from "./review-spawn.ts";
@@ -160,6 +160,23 @@ export function createDispatcher(deps: DispatchDeps): Dispatcher {
     lockHeld = true;
 
     try {
+      // 先验 pi 真的可执行：spawn 的 ENOENT 是**异步** emit 的，早于收尸 listener 挂载，
+      // 会把整个 pi 进程 uncaughtException 打死（2026-11-09 写死路径事故）。宁可不派，也不炸宿主。
+      // 注入了 spawnFn = 单测/嵌入式宿主，路径由调用方自负，这里不做磁盘校验。
+      const piBin = resolvePiBin(env);
+      if (!deps.spawnFn && !isExecutableFile(piBin)) {
+        log(`[skill-evolve] 未派生：找不到可执行的 pi（${piBin}）。设 SKILL_EVOLVE_PI_BIN 或先装好 pi`);
+        deps.telemetry.append({
+          kind: "skipped",
+          sessionId: input.sessionId,
+          why: "pi-not-found",
+          ownerPid: lock.owner?.pid ?? null,
+          trigger,
+        });
+        await releaseOnce();
+        return { status: "skipped", why: "pi-not-found", ownerPid: lock.owner?.pid ?? null };
+      }
+
       const indexFile = path.join(runDir, "00-session", "index.json");
       const sessionFile = input.sessionFile ?? carried?.sessionFile;
       let evidenceMode: RunRecord["evidenceMode"] = "telemetry-only";
@@ -199,7 +216,6 @@ export function createDispatcher(deps: DispatchDeps): Dispatcher {
         dispatchedAt: at,
         coverage,
       });
-      const piBin = resolvePiBin(env);
       const spawnFn: SpawnLike = deps.spawnFn ?? (spawn as unknown as SpawnLike);
       const child = spawnDetached(spawnFn, piBin, ["-p", "--no-session", "-ns", prompt], {
         cwd: deps.cwd,
@@ -207,6 +223,11 @@ export function createDispatcher(deps: DispatchDeps): Dispatcher {
         // stdout+stderr 落到 run 目录：子进程怎么死的，只有这份日志答得出来
         logFile: path.join(runDir, CHILD_LOG),
       });
+      // 兜底 listener：spawn 仍可能失败（权限、架构不匹配），没 listener 的 error 事件在 Node 里
+      // 会直接抛成 uncaughtException。真正的收尸仍由 watchRunChild 负责，这里只保证不炸宿主。
+      child.once("error", (error) => {
+        log(`[skill-evolve] 复盘子进程启动失败：${String(error)}`);
+      });
 
       record.pid = child.pid ?? null;
       await writeRunRecord(runDir, record, deps.queue);
@@ -258,6 +279,8 @@ export function createDispatcher(deps: DispatchDeps): Dispatcher {
         ...(deps.reviewModel ? { reviewModel: deps.reviewModel } : {}),
         ...(deps.supervisorSpawnFn ? { supervisorSpawnFn: deps.supervisorSpawnFn } : {}),
         ...(deps.alive ? { alive: deps.alive } : {}),
+        // 注入了 spawnFn = 单测/嵌入式宿主：路径由调用方自负，退出补发也不做磁盘校验
+        ...(deps.spawnFn ? { piBinExists: () => true } : {}),
         log,
       },
       at,

package/extensions/skill-evolve/lib/drain-pending.ts

@@ -26,6 +26,8 @@ export interface DrainPendingOptions {
   reviewModel?: () => string;
   supervisorSpawnFn?: SupervisorSpawn;
   alive?: (pid: number) => boolean;
+  /** pi 可执行文件判定（dispatch 注入假 spawnFn 时直接传「都在」，单测不碰真磁盘） */
+  piBinExists?: (candidate: string) => boolean;
   log: (msg: string) => void;
 }
 
@@ -49,6 +51,7 @@ export function drainPending(pending: Map<string, PendingRounds>, options: Drain
           ...(options.reviewModel ? { reviewModel: options.reviewModel() } : {}),
           ...(options.supervisorSpawnFn ? { supervisorSpawnFn: options.supervisorSpawnFn } : {}),
           ...(options.alive ? { alive: options.alive } : {}),
+          ...(options.piBinExists ? { piBinExists: options.piBinExists } : {}),
           log: options.log,
         },
         at,

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

@@ -14,6 +14,7 @@ import { createDispatcher } from "./dispatch.ts";
 import { createApplyTools, type ApplyTools } from "./evolution-apply.ts";
 import { createModelTools, type ModelTools } from "./evolution-model.ts";
 import { createObserver, type Observer, type PanelDeps } from "./evolution-observe.ts";
+import { recoverRuns, type RecoveryAction } from "./recover.ts";
 import { createViews } from "./evolution-views.ts";
 import { flagStateText, FLAG_LABEL } from "./flags.ts";
 import type { GitRunner } from "./gate0.ts";
@@ -92,6 +93,13 @@ export interface Evolution {
   apply: ApplyTools;
   /** M6：面板刷新（状态变迁转 /tree 条目）与周报 + 指标落盘 */
   observe: Observer;
+  /**
+   * 重启 / `/reload` 后的接手：补状态、重挂督导师（详见 lib/recover.ts）。
+   * 返回本次做了什么，面板与日志都靠它告诉用户「后台任务没丢」。
+   */
+  recover(): Promise<RecoveryAction[]>;
+  /** 最近一次恢复的结果（面板可视化用；本进程内有效） */
+  lastRecovery(): RecoveryAction[];
 }
 
 export function createEvolution(deps: EvolutionDeps): Evolution {
@@ -270,6 +278,32 @@ export function createEvolution(deps: EvolutionDeps): Evolution {
     return `${FLAG_LABEL[field]}已${value ? "开启" : "关闭"}：${configFile(evolutionDir)}（当前会话立即生效）\n${flagStateText(config)}`;
   };
 
+  /**
+   * 重启 / 重载后的接手：只补状态与重挂督导师，绝不重跑复盘。
+   * 同步抛错也在这里吞：会话起点不能被恢复流程搞挂。
+   */
+  let lastActions: RecoveryAction[] = [];
+  const recover = async (): Promise<RecoveryAction[]> => {
+    try {
+      lastActions = await recoverRuns({
+        evolutionDir,
+        cwd: deps.cwd,
+        queue: deps.queue,
+        now,
+        env,
+        autoReview: () => config.autoReview,
+        reviewModel: modelTools.reviewModel,
+        ...(deps.alive ? { alive: deps.alive } : {}),
+        ...(deps.supervisorSpawnFn ? { spawnSupervisor: deps.supervisorSpawnFn } : {}),
+        log,
+      });
+    } catch (error) {
+      log(`[skill-evolve] 重启恢复失败：${String(error)}`);
+      lastActions = [];
+    }
+    return lastActions;
+  };
+
   return {
     recordAdvertised,
     noteToolCall,
@@ -288,5 +322,7 @@ export function createEvolution(deps: EvolutionDeps): Evolution {
     model: modelTools,
     apply: applyTools,
     observe: observer,
+    recover,
+    lastRecovery: () => lastActions,
   };
 }

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

@@ -0,0 +1,206 @@
+/**
+ * 五段流水线：派发 → 分析 → 提案 → 评审 → 采纳。
+ *
+ * 为什么单列一层：用户看「已分析」四个字永远不知道后台卡在哪一步（2026-11-09 真实困惑：
+ * 面板写「已分析」，提案却永远不出现，其实督导崩在 import 阶段）。这里把「一步做什么、
+ * 现在到哪一步、卡住时下一步谁来接」摊平成五个格子，面板与 `/tree` 都读同一份结论。
+ *
+ * 纪律：只看磁盘产物与 pid 存活，**不猜进度**。没有的产物就是没有，缺文件写缺哪个。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** done=已完成 / running=正在跑 / waiting=等上一步 / blocked=卡住等人或等重启 / failed=失败 / skipped=按配置跳过 */
+export type StageState = "done" | "running" | "waiting" | "blocked" | "failed" | "skipped";
+
+export type StageKey = "dispatch" | "analyze" | "propose" | "review" | "apply";
+
+export interface PipelineStage {
+  key: StageKey;
+  label: string;
+  state: StageState;
+  /** 一句话说清「这一步现在是什么情况」：谁在跑、缺哪个文件、等谁 */
+  detail: string;
+  /** 该步完成/开始的时刻：没有就 null（不编时间） */
+  at: number | null;
+}
+
+export interface Pipeline {
+  stages: PipelineStage[];
+  /** 第一处不是 done 的说明 + 下一步动作；全 done 时给结论 */
+  hint: string;
+}
+
+export interface PipelineInput {
+  runDir: string;
+  /** run.json 的 status */
+  status: string;
+  pid: number | null;
+  supervisorPid: number | null;
+  dispatchedAt: number | null;
+  /** 采纳队列里这条 run 的状态（pending / applied / rejected …）；不在队列为 null */
+  queued?: string | null;
+  /** 自动评审 / 自动采纳开关；null = 面板不知道（CLI 上下文）就不下结论 */
+  autoReview?: boolean | null;
+  autoApply?: boolean | null;
+  alive?: (pid: number) => boolean;
+}
+
+const LABELS: Record<StageKey, string> = {
+  dispatch: "派发",
+  analyze: "分析",
+  propose: "提案",
+  review: "评审",
+  apply: "采纳",
+};
+
+/** 终态里不该再往后走的那些 */
+const DEAD_STATUS = new Set(["stale", "abandoned", "failed", "unauthorized_write"]);
+
+function statOf(file: string): { at: number } | null {
+  try {
+    const stat = fs.statSync(file);
+    return stat.isFile() ? { at: stat.mtimeMs } : null;
+  } catch {
+    return null;
+  }
+}
+
+function jsonOf(file: string): Record<string, unknown> | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(file, "utf8")) as unknown;
+    return typeof raw === "object" && raw !== null ? (raw as Record<string, unknown>) : null;
+  } catch {
+    return null;
+  }
+}
+
+function textOf(value: unknown, fallback = ""): string {
+  return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+
+/**
+ * 五段状态。同一份产物只读一次：这里的判断全在文件系统上，多一次 stat 只是浪费。
+ */
+export function buildPipeline(input: PipelineInput): Pipeline {
+  const alive = input.alive ?? (() => false);
+  const dir = input.runDir;
+  const findings = statOf(path.join(dir, "01-findings.json"));
+  const proposalFile = statOf(path.join(dir, "02-proposal.json"));
+  const reviewFile = statOf(path.join(dir, "03-review.json"));
+  const decision = statOf(path.join(dir, "04-decision.json"));
+  const verify = statOf(path.join(dir, "06-verify.json"));
+  const proposal = proposalFile ? jsonOf(path.join(dir, "02-proposal.json")) : null;
+  const review = reviewFile ? jsonOf(path.join(dir, "03-review.json")) : null;
+  const dead = DEAD_STATUS.has(input.status);
+  const childAlive = input.pid !== null && alive(input.pid);
+  const supervisorAlive = input.supervisorPid !== null && alive(input.supervisorPid);
+
+  const stages: PipelineStage[] = [];
+
+  // 1. 派发：run.json 存在就算完成（时间取 dispatchedAt，没有就 null）
+  stages.push({
+    key: "dispatch",
+    label: LABELS.dispatch,
+    state: "done",
+    detail: input.pid === null ? "已派发（pid 未记）" : childAlive ? `复盘子进程 pid ${input.pid} 在跑` : `复盘子进程 pid ${input.pid} 已退出`,
+    at: input.dispatchedAt,
+  });
+
+  // 2. 分析：产物是 01-findings.json
+  const analyze: PipelineStage = findings
+    ? { key: "analyze", label: LABELS.analyze, state: "done", detail: "01-findings.json 已落盘", at: findings.at }
+    : dead
+      ? { key: "analyze", label: LABELS.analyze, state: "failed", detail: `分析没出结论就结束了（${input.status}）`, at: null }
+      : childAlive
+        ? { key: "analyze", label: LABELS.analyze, state: "running", detail: `子进程 pid ${input.pid} 正在读会话`, at: null }
+        : { key: "analyze", label: LABELS.analyze, state: "waiting", detail: "子进程已退出但没写 01-findings.json（等卡死判定收尾）", at: null };
+  stages.push(analyze);
+
+  // 3. 提案：产物是 02-proposal.json（候选 diff 由同一步写入 candidate/）
+  const propose: PipelineStage = proposalFile
+    ? {
+        key: "propose",
+        label: LABELS.propose,
+        state: "done",
+        detail: `${textOf(proposal?.type, "提案")} → ${textOf(proposal?.skill, "未写技能")}`,
+        at: proposalFile.at,
+      }
+    : dead
+      ? { key: "propose", label: LABELS.propose, state: "waiting", detail: "分析没走完，没到提案", at: null }
+      : childAlive
+        ? { key: "propose", label: LABELS.propose, state: "running", detail: "分析在跑，提案随后写", at: null }
+        : findings
+          ? { key: "propose", label: LABELS.propose, state: "waiting", detail: "分析已结束但没写提案（多半是判定「不该改」）", at: null }
+          : { key: "propose", label: LABELS.propose, state: "waiting", detail: "等分析结论", at: null };
+  stages.push(propose);
+
+  // 4. 评审：产物是 03-review.json；有提案但督导不在 = 需要重启恢复接手
+  const reviewStatus = review ? textOf(review.status, "未知") : null;
+  let reviewStage: PipelineStage;
+  if (reviewFile) {
+    const failed = reviewStatus === "review_failed" || reviewStatus === "error";
+    reviewStage = {
+      key: "review",
+      label: LABELS.review,
+      state: failed ? "failed" : "done",
+      detail: `${reviewStatus}${textOf(review?.verdict) ? ` / ${textOf(review?.verdict)}` : ""}`,
+      at: reviewFile.at,
+    };
+  } else if (proposalFile) {
+    reviewStage = supervisorAlive
+      ? { key: "review", label: LABELS.review, state: "running", detail: `督导 pid ${input.supervisorPid} 正在评审`, at: null }
+      : input.autoReview === false
+        ? { key: "review", label: LABELS.review, state: "skipped", detail: "自动评审关着：等人工 /skill-evolve approve", at: null }
+        : { key: "review", label: LABELS.review, state: "blocked", detail: "提案在但督导不在：下次会话起点自动重挂", at: null };
+  } else {
+    reviewStage = { key: "review", label: LABELS.review, state: "waiting", detail: "等提案出来再评审", at: null };
+  }
+  stages.push(reviewStage);
+
+  // 5. 采纳：需要 04-decision.json（队列 applied / 五闸）；rejected 的到此为止
+  let applyStage: PipelineStage;
+  if (decision) {
+    applyStage = { key: "apply", label: LABELS.apply, state: "done", detail: "04-decision.json 已写（技能文件已改）", at: decision.at };
+  } else if (reviewStatus === "rejected" || input.status === "rejected") {
+    applyStage = { key: "apply", label: LABELS.apply, state: "skipped", detail: "评审驳回，不会采纳", at: null };
+  } else if (reviewStatus === "approved" || reviewStatus === "needs_human") {
+    applyStage = input.queued === "pending" && input.autoApply !== false
+      ? { key: "apply", label: LABELS.apply, state: "running", detail: "队列 pending，自动采纳正在走五闸", at: null }
+      : { key: "apply", label: LABELS.apply, state: "blocked", detail: input.autoApply === false ? "自动采纳关着：等面板批准" : "已入队 pending，等采纳扫描", at: null };
+  } else if (verify) {
+    applyStage = { key: "apply", label: LABELS.apply, state: "blocked", detail: "五闸跑过但没写决定：看 06-verify.json", at: verify.at };
+  } else {
+    applyStage = { key: "apply", label: LABELS.apply, state: "waiting", detail: "等评审通过", at: null };
+  }
+  stages.push(applyStage);
+
+  return { stages, hint: hintOf(stages) };
+}
+
+/**
+ * 「下一步」的挑选顺序：先看**真在跑 / 真卡住 / 真失败**的那一步（用户能立刻行动），
+ * 再退回第一处「等上一步」；全 done 时明说结束。只按顺序找第一处会让「分析等收尾」
+ * 盖掉「提案在、督导死了」这种更该被看见的状态。
+ */
+function hintOf(stages: PipelineStage[]): string {
+  const first =
+    stages.find((stage) => stage.state === "running" || stage.state === "blocked" || stage.state === "failed") ??
+    stages.find((stage) => stage.state === "waiting");
+  if (!first) {
+    const skipped = stages.find((stage) => stage.state === "skipped");
+    return skipped ? `流程结束：卡在「${skipped.label}」— ${skipped.detail}` : "流程走完：五段全部完成";
+  }
+  return `下一步「${first.label}」— ${first.detail}`;
+}
+
+/** 面板用的一句话：`派发✓ 分析✓ 提案✓ 评审… 采纳·`，一眼看出卡在哪 */
+export function renderPipelineLine(pipeline: Pipeline): string {
+  const mark: Record<StageState, string> = { done: "✓", running: "…", waiting: "·", blocked: "!", failed: "✗", skipped: "–" };
+  return pipeline.stages.map((stage) => `${stage.label}${mark[stage.state]}`).join(" ");
+}
+
+/** 把 stages 折成「进度 3/5」这种数字，列表列用 */
+export function pipelineProgress(pipeline: Pipeline): { done: number; total: number } {
+  return { done: pipeline.stages.filter((stage) => stage.state === "done").length, total: pipeline.stages.length };
+}

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

@@ -0,0 +1,182 @@
+/**
+ * 重启 / `/reload` 之后的自动恢复。
+ *
+ * 为什么需要它：派发出去的两个子进程都是 detached 的，但**收尸逻辑在内存里**。
+ * 主进程一重启，`watchRunChild` 的 exit 回调就没了；督导若也被带走了（机器重启、
+ * 端口没放开被旧实例挡掉、面板手动清理），run 会永久停在 `dispatched` / `analyzed`，
+ * 用户看到的就是「已分析」但提案永远不出 —— 2026-11-09 的事故现场。
+ *
+ * 恢复只做三件保守的事，绝不重跑复盘（花 token 且会覆盖已有产物）：
+ * 1. 有 `01-findings.json` 却还写着 `dispatched` → 补成 `analyzed`（分析其实已经跑完）
+ * 2. 有 `02-proposal.json` 但没 `03-review.json`、督导进程已死 → 重挂一个督导接着评审
+ * 3. 其余情况只报告，不动手（复盘子进程还在跑就别打扰它）
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { spawnReviewSupervisor, type SpawnSupervisorOptions } from "./review-spawn.ts";
+import { listRuns, updateRunStatus, type RunRecord } from "./runs.ts";
+import type { MutationQueue } from "./telemetry.ts";
+
+/** 只恢复最近这么多小时内派发的 run：更老的多半是用户已经不管的历史 */
+export const RECOVER_WINDOW_MS = 6 * 60 * 60 * 1000;
+
+/** 还在「半路」的状态：出终态的不该被碰 */
+const RESUMABLE = new Set(["dispatched", "analyzed", "proposed"]);
+
+export type RecoveryKind =
+  /** 分析产物在、状态落后：只补状态 */
+  | "advanced-analyzed"
+  /** 提案在、督导不在：重挂督导 */
+  | "supervisor-respawned"
+  /** 提案在、督导还在跑：不打扰 */
+  | "waiting-review"
+  /** 还没出提案，复盘子进程还活着 */
+  | "waiting-proposal"
+  /** 还没出提案，复盘子进程也没了：不重跑，等 stale 收尾 */
+  | "interrupted"
+  /** 已有评审结论：交给会话起点的入队 / 自动采纳 */
+  | "review-done"
+  /** 重挂被挡下（单飞闸占满 / 关着自动评审 / 起不来） */
+  | "respawn-blocked";
+
+export interface RecoveryAction {
+  runId: string;
+  kind: RecoveryKind;
+  detail: string;
+}
+
+export interface RecoverDeps {
+  evolutionDir: string;
+  cwd: string;
+  queue: MutationQueue;
+  now?: () => number;
+  env?: NodeJS.ProcessEnv;
+  alive?: (pid: number) => boolean;
+  /** 现读配置：自动评审关着就不重挂督导（用户手动关的不该被重启偷偷打开） */
+  autoReview?: () => boolean;
+  reviewModel?: () => string;
+  spawnSupervisor?: (options: SpawnSupervisorOptions) => number | null;
+  log?: (msg: string) => void;
+  windowMs?: number;
+}
+
+function exists(runDir: string, name: string): boolean {
+  try {
+    return fs.statSync(path.join(runDir, name)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** 生产里就是读 run.json：坏数据当「没有」处理，宁可不动手 */
+function readRecord(runDir: string): RunRecord | null {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(runDir, "run.json"), "utf8")) as RunRecord;
+  } catch {
+    return null;
+  }
+}
+
+export async function recoverRuns(deps: RecoverDeps): Promise<RecoveryAction[]> {
+  const log = deps.log ?? (() => {});
+  const now = deps.now ?? (() => Date.now());
+  const alive = deps.alive ?? ((pid: number) => {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch {
+      return false;
+    }
+  });
+  const windowMs = deps.windowMs ?? RECOVER_WINDOW_MS;
+  const spawnSupervisor = deps.spawnSupervisor ?? spawnReviewSupervisor;
+  const actions: RecoveryAction[] = [];
+  const runsRoot = path.join(deps.evolutionDir, "runs");
+  let entries: string[];
+  try {
+    entries = fs.readdirSync(runsRoot);
+  } catch {
+    return actions;
+  }
+  const cutoff = now() - windowMs;
+  for (const runId of entries.sort()) {
+    const runDir = path.join(runsRoot, runId);
+    const record = readRecord(runDir);
+    if (!record) continue;
+    if (!RESUMABLE.has(record.status ?? "")) continue;
+    if (typeof record.dispatchedAt === "number" && record.dispatchedAt < cutoff) continue;
+
+    const hasFindings = exists(runDir, "01-findings.json");
+    const hasProposal = exists(runDir, "02-proposal.json");
+    const hasReview = exists(runDir, "03-review.json");
+    const childAlive = typeof record.pid === "number" && alive(record.pid);
+    const supervisorAlive = typeof record.supervisorPid === "number" && alive(record.supervisorPid);
+
+    if (hasReview) {
+      actions.push({ runId, kind: "review-done", detail: "评审已落盘，等会话起点入队 / 自动采纳" });
+      continue;
+    }
+
+    // 1. 分析跑完了但状态没跟上：补状态（不重跑、不花 token）
+    if (record.status === "dispatched" && hasFindings) {
+      const ok = await updateRunStatus(deps.evolutionDir, runId, "analyzed", deps.queue);
+      actions.push({
+        runId,
+        kind: ok ? "advanced-analyzed" : "interrupted",
+        detail: ok ? "01-findings.json 已在，状态补成 analyzed（未重跑）" : "补状态失败：run.json 写不进去",
+      });
+      if (!ok) continue;
+    }
+
+    if (!hasProposal) {
+      if (childAlive) {
+        actions.push({ runId, kind: "waiting-proposal", detail: `复盘子进程 pid ${record.pid} 还活着，不打扰` });
+      } else {
+        actions.push({ runId, kind: "interrupted", detail: "还没出提案，复盘子进程已不在：不自动重跑，等 stale 收尾" });
+      }
+      continue;
+    }
+
+    // 2. 提案在、评审没做：重挂督导（这才是「后台任务丢了」的正解）
+    if (supervisorAlive) {
+      actions.push({ runId, kind: "waiting-review", detail: `督导 pid ${record.supervisorPid} 还在跑，等它出结论` });
+      continue;
+    }
+    if (deps.autoReview && !deps.autoReview()) {
+      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,
+    });
+    actions.push(
+      pid === null
+        ? { runId, kind: "respawn-blocked", detail: "督导没起来（单飞闸占满或 spawn 失败），下次会话起点还会再试" }
+        : { runId, kind: "supervisor-respawned", detail: `提案已在、督导原本不在：重挂 pid ${pid}` },
+    );
+  }
+  return actions;
+}
+
+/** 面板文案：一句话说清「重启后补了什么」 */
+export function renderRecovery(actions: RecoveryAction[]): string {
+  if (actions.length === 0) return "重启恢复：没有需要接手的 run";
+  const label: Record<RecoveryKind, string> = {
+    "advanced-analyzed": "补状态",
+    "supervisor-respawned": "重挂督导",
+    "waiting-review": "等评审",
+    "waiting-proposal": "等提案",
+    interrupted: "已中断",
+    "review-done": "评审完成",
+    "respawn-blocked": "未能重挂",
+  };
+  const lines = [`重启恢复：${actions.length} 条 run 被检查`];
+  for (const action of actions) lines.push(`  · ${action.runId}  ${label[action.kind]} — ${action.detail}`);
+  return lines.join("\n");
+}

package/extensions/skill-evolve/lib/review-spawn.ts

@@ -13,6 +13,7 @@ import { fileURLToPath } from "node:url";
 import { patchRunRecordSync } from "./runs.ts";
 import { guardBusy } from "./single-flight.ts";
 import { spawnDetached } from "./spawn-plan.ts";
+import { ensureSupervisorRuntime, type RuntimeOptions } from "./supervisor-runtime.ts";
 import type { TelemetryWriter } from "./telemetry.ts";
 
 /** 督导脚本绝对路径：dispatch 与 shutdown-dispatch 两条路径共用 */
@@ -50,6 +51,13 @@ export interface SpawnSupervisorOptions {
   alive?: (pid: number) => boolean;
   /** 退出补发路径：主进程马上退，遥测只能同步写 */
   sync?: boolean;
+  /**
+   * 督导入口解析：默认走 supervisor-runtime 的「node_modules 里先搬家」逻辑。
+   * 单测注入它，避免真去拷源码目录。
+   */
+  resolveScript?: (options: RuntimeOptions) => string;
+  /** 包版本：参与运行目录的缓存键 */
+  version?: string;
 }
 
 /** 返回 pid；被单飞闸挡住或起不来返回 null（只记日志，绝不抛到主会话） */
@@ -74,7 +82,16 @@ export function spawnReviewSupervisor(options: SpawnSupervisorOptions): number |
   const env = { ...(options.env ?? process.env) };
   // 督导自己不是 pi 子代理：把「别再采集」的标记去掉，避免它起评审子进程时语义混乱
   delete env.SKILL_EVOLVE_CHILD;
-  const args = ["--experimental-strip-types", SUPERVISOR_SCRIPT, options.runDir];
+  // node_modules 里的 .ts 不能直接跑（ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING）：先搬到工作区的
+  // runtime 目录再起进程，否则按 npm 包安装时督导**每次**都崩在 import 阶段（2026-11-09 事故）
+  const resolveScript = options.resolveScript ?? ensureSupervisorRuntime;
+  const script = resolveScript({
+    evolutionDir: path.dirname(path.dirname(options.runDir)),
+    scriptPath: SUPERVISOR_SCRIPT,
+    ...(options.version ? { version: options.version } : {}),
+    ...(options.log ? { log: options.log } : {}),
+  });
+  const args = ["--experimental-strip-types", script, options.runDir];
   if (options.reviewModel && options.reviewModel !== "inherit") args.push(options.reviewModel);
   const spawnFn = options.spawnFn ?? (nodeSpawn as unknown as SupervisorSpawn);
   try {