pi-skill-evolve 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # 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 包安装时「评审 → 采纳」整条链原本一次都跑不起来，这个版本修掉它，并把每轮复盘画成五段流水线。
+
+- 修复（事故）：`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,31 @@ 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` | 自动采纳关着 → 面板待审批页批准 |
+
+### 一个工作区开两个 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 且会覆盖已有产物），有动作时用一行通知说明补了什么。
+
 ## 配置
 
 `.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/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

@@ -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(sessionId?: string): Promise<RecoveryAction[]>;
+  /** 最近一次恢复的结果（面板可视化用；本进程内有效） */
+  lastRecovery(): RecoveryAction[];
 }
 
 export function createEvolution(deps: EvolutionDeps): Evolution {
@@ -270,6 +278,33 @@ export function createEvolution(deps: EvolutionDeps): Evolution {
     return `${FLAG_LABEL[field]}已${value ? "开启" : "关闭"}：${configFile(evolutionDir)}（当前会话立即生效）\n${flagStateText(config)}`;
   };
 
+  /**
+   * 重启 / 重载后的接手：只补状态与重挂督导师，绝不重跑复盘。
+   * 同步抛错也在这里吞：会话起点不能被恢复流程搞挂。
+   */
+  let lastActions: RecoveryAction[] = [];
+  const recover = async (sessionId?: string): 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 } : {}),
+        ...(sessionId ? { sessionId } : {}),
+        log,
+      });
+    } catch (error) {
+      log(`[skill-evolve] 重启恢复失败：${String(error)}`);
+      lastActions = [];
+    }
+    return lastActions;
+  };
+
   return {
     recordAdvertised,
     noteToolCall,
@@ -288,5 +323,7 @@ export function createEvolution(deps: EvolutionDeps): Evolution {
     model: modelTools,
     apply: applyTools,
     observe: observer,
+    recover,
+    lastRecovery: () => lastActions,
   };
 }

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/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 };
+}