pi-skill-evolve 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,177 @@
+/**
+ * 退出前补发：`session_shutdown` 里把还没派发的轮次再试一次。
+ *
+ * 为什么单独一个文件：这条路径全部是**同步** fs + 同步 spawn —— 主进程马上就要退出，
+ * 用异步队列很可能写完进程就没了（设计稿「静默失败」原则：命令返回成功 ≠ 真的落盘）。
+ * 代价是这几步会阻塞退出几十毫秒，所以只在真的还有待复盘轮次时才走。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { Attribution } from "./attribution.ts";
+import { acquireLockSync, releaseLockSync, writeOwnerSync } from "./lock.ts";
+import { buildPrompt, readPromptTemplateSync } from "./prompt.ts";
+import { spawnReviewSupervisor, type SupervisorSpawn } from "./review-spawn.ts";
+import { guardBusy } from "./single-flight.ts";
+import { CHILD_LOG, uniqueRunId, sessionHashOf, resolvePiBin, spawnDetached, type SpawnLike } from "./spawn-plan.ts";
+import { writeRunRecordSync, type RunRecord } from "./runs.ts";
+import { writeSessionIndexSync } from "./session-index.ts";
+import type { TelemetryWriter } from "./telemetry.ts";
+
+/** 待复盘的轮次（去抖期间累计，退出时补发一次） */
+export interface PendingRounds {
+  sessionId: string;
+  /** 待复盘区间的起点：第一次被去抖掉的时刻 */
+  since: number;
+  /** 合并了几轮（superseded 的次数） */
+  rounds: number;
+  skills: string[];
+  sessionFile?: string;
+  /** 已经机械归因过的技能（A~E），多轮合并时去重 */
+  attributions?: Attribution[];
+}
+
+export interface ShutdownDeps {
+  evolutionDir: string;
+  cwd: string;
+  promptTemplatePath: string;
+  maxRuntimeMs: number;
+  telemetry: TelemetryWriter;
+  env: NodeJS.ProcessEnv;
+  spawnFn: SpawnLike;
+  /** 评审模型（"inherit" 或 provider/model），退出补发这条路径同样要起督导 */
+  reviewModel?: string;
+  supervisorSpawnFn?: SupervisorSpawn;
+  /** pid 存活判定（全局单飞闸用；单测注入，测试里不起真子进程） */
+  alive?: (pid: number) => boolean;
+  log: (msg: string) => void;
+}
+
+export type ShutdownResult = "dispatched" | "skipped" | "failed";
+
+/** 同步补发一次：任何异常都在内部吞掉，绝不阻塞退出、绝不抛给调用方 */
+export function flushPendingSync(item: PendingRounds, deps: ShutdownDeps, now: number): ShutdownResult {
+  // 全局单飞：退出补发也不能叠进程（已有活的复盘 / 督导就放弃本次，不建目录不抢锁）
+  const occupant = guardBusy({
+    evolutionDir: deps.evolutionDir,
+    sessionId: item.sessionId,
+    telemetry: deps.telemetry,
+    sync: true,
+    trigger: "shutdown",
+    rounds: item.rounds,
+    ...(deps.alive ? { alive: deps.alive } : {}),
+    log: deps.log,
+  });
+  if (occupant) return "skipped";
+
+  const runId = uniqueRunId(deps.evolutionDir, item.sessionId, now);
+  const runDir = path.join(deps.evolutionDir, "runs", runId);
+  const lock = acquireLockSync({
+    evolutionDir: deps.evolutionDir,
+    owner: { pid: process.pid, ts: now, sessionId: item.sessionId },
+    maxRuntimeMs: deps.maxRuntimeMs,
+    log: deps.log,
+    now: () => now,
+  });
+  if (!lock.ok) {
+    deps.telemetry.appendSync({
+      kind: "skipped",
+      ts: now,
+      sessionId: item.sessionId,
+      why: lock.why === "error" ? "lock-error" : "lock",
+      trigger: "shutdown",
+      ownerPid: lock.owner?.pid ?? null,
+      rounds: item.rounds,
+    });
+    deps.log(`[skill-evolve] 退出补发放弃：锁被占用（pid ${lock.owner?.pid ?? "未知"}）`);
+    return "skipped";
+  }
+
+  let childPid: number | null = null;
+  try {
+    const indexDir = path.join(runDir, "00-session");
+    const indexFile = path.join(indexDir, "index.json");
+    let evidenceMode: RunRecord["evidenceMode"] = "telemetry-only";
+    if (item.sessionFile && writeSessionIndexSync({ sessionFile: item.sessionFile, outDir: indexDir, log: deps.log })) {
+      evidenceMode = "session+telemetry";
+    }
+
+    const record: RunRecord = {
+      runId,
+      status: "dispatched",
+      trigger: "shutdown",
+      sessionId: item.sessionId,
+      sessionHash: sessionHashOf(item.sessionId),
+      sessionFile: item.sessionFile ?? null,
+      evidenceMode,
+      dispatchedAt: now,
+      dispatchedAtIso: new Date(now).toISOString(),
+      pid: null,
+      cwd: deps.cwd,
+      skills: [...item.skills],
+      coverage: { rounds: item.rounds, since: item.since },
+      stages: [{ name: "dispatch", model: null, usage: null, ms: 0 }],
+      artifacts: evidenceMode === "session+telemetry" ? { "00-session/index.json": indexFile } : {},
+    };
+    writeRunRecordSync(runDir, record);
+
+    const prompt = buildPrompt({
+      template: readPromptTemplateSync(deps.promptTemplatePath, deps.log),
+      sessionFile: item.sessionFile,
+      indexFile: evidenceMode === "session+telemetry" ? indexFile : undefined,
+      runDir,
+      sessionId: item.sessionId,
+      skills: item.skills,
+      attributions: item.attributions,
+      dispatchedAt: now,
+      coverage: record.coverage,
+    });
+    const child = spawnDetached(deps.spawnFn, resolvePiBin(deps.env), ["-p", "--no-session", "-ns", prompt], {
+      cwd: deps.cwd,
+      env: { ...deps.env, SKILL_EVOLVE_CHILD: "1" },
+      // 退出前补发这条路径最容易“静默失败”：日志落盘才知道子进程到底起没起来
+      logFile: path.join(runDir, CHILD_LOG),
+    });
+    childPid = child.pid ?? null;
+
+    record.pid = childPid;
+    writeRunRecordSync(runDir, record);
+    // 锁的 owner 换成子进程：主进程退出后 owner.pid 若指向死进程，下一次派发会把正在跑的 run 当孤儿回收
+    writeOwnerSync(deps.evolutionDir, { pid: childPid ?? process.pid, ts: now, sessionId: item.sessionId }, deps.log);
+    deps.telemetry.appendSync({
+      kind: "dispatched",
+      ts: now,
+      sessionId: item.sessionId,
+      runId,
+      pid: childPid,
+      trigger: "shutdown",
+      rounds: item.rounds,
+    });
+    deps.log(`[skill-evolve] 退出前补发复盘：runId ${runId} pid ${childPid ?? "未知"}（合并 ${item.rounds} 轮）`);
+    spawnReviewSupervisor({
+      runDir,
+      cwd: deps.cwd,
+      env: deps.env,
+      reviewModel: deps.reviewModel ?? "inherit",
+      spawnFn: deps.supervisorSpawnFn,
+      sessionId: item.sessionId,
+      telemetry: deps.telemetry,
+      sync: true,
+      ...(deps.alive ? { alive: deps.alive } : {}),
+      log: deps.log,
+    });
+    return "dispatched";
+  } catch (error) {
+    deps.log(`[skill-evolve] 退出补发失败：${String(error)}`);
+    // 子进程已经起来了就留着锁（它自己跑完会死，下一次按死 pid 回收）；没起来必须放锁
+    if (childPid === null) releaseLockSync(deps.evolutionDir, deps.log);
+    try {
+      const record = JSON.parse(fs.readFileSync(path.join(runDir, "run.json"), "utf8")) as RunRecord;
+      record.status = "abandoned";
+      record.abandonedReason = `shutdown-dispatch: ${String(error)}`;
+      writeRunRecordSync(runDir, record);
+    } catch {
+      // run.json 本身都写不进去：日志已经记过，到此为止
+    }
+    return "failed";
+  }
+}

package/extensions/skill-evolve/lib/single-flight.ts

@@ -0,0 +1,111 @@
+/**
+ * 全局单飞闸：任意时刻最多一个子进程（复盘或督导都算）。
+ *
+ * 用户 2026-11-08：「每次最多一个复盘agent」。这条约束**跨会话也成立** —— 两个 pi 会话同时结算时，
+ * 只让先到的那条跑；后来者不 spawn，只写一条 `skipped(busy)` 遥测，等占用者跑完的下一轮再派。
+ *
+ * 占用证据是**活着的 pid**：`runs/<runId>/run.json` 的 `pid`（复盘子进程）与 `supervisorPid`（评审督导）。
+ * pid 判死即自然释放，不需要谁去清场；督导退出时仍会把 `supervisorPid` 写成 `null`，
+ * 免得一个被系统复用的 pid 造成假占用。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { isPidAlive } from "./lock.ts";
+import type { TelemetryWriter } from "./telemetry.ts";
+
+/** 占用者：谁在跑、pid 多少、是复盘还是督导 */
+export interface Occupant {
+  runId: string;
+  pid: number;
+  kind: "复盘" | "督导";
+}
+
+export interface OccupantDeps {
+  /** pid 存活判定（默认 kill(pid,0)）；单测注入，测试里不许起真进程 */
+  alive?: (pid: number) => boolean;
+  /**
+   * 排除自己：督导与它那条复盘是同一 run 的配对进程（复盘子进程先起、督导后起）。
+   * 不排除的话督导永远看不到「空闲」，功能直接死掉。
+   */
+  ignoreRunId?: string;
+}
+
+interface Candidate {
+  occupant: Occupant;
+  dispatchedAt: number;
+}
+
+function readCandidates(evolutionDir: string, deps: OccupantDeps): Candidate[] {
+  const alive = deps.alive ?? isPidAlive;
+  const runsDir = path.join(evolutionDir, "runs");
+  let names: string[];
+  try {
+    names = fs.readdirSync(runsDir);
+  } catch {
+    return []; // 还没派过：没有 runs/ 目录就是没人占用
+  }
+  const found: Candidate[] = [];
+  for (const name of names) {
+    let raw: Record<string, unknown>;
+    try {
+      raw = JSON.parse(fs.readFileSync(path.join(runsDir, name, "run.json"), "utf8")) as Record<string, unknown>;
+    } catch {
+      continue; // run.json 不在 / 坏掉：没有可判的记录，坏记录不能永久占住闸门
+    }
+    const runId = typeof raw.runId === "string" ? raw.runId : name;
+    if (deps.ignoreRunId !== undefined && (runId === deps.ignoreRunId || name === deps.ignoreRunId)) continue;
+    const dispatchedAt = typeof raw.dispatchedAt === "number" ? raw.dispatchedAt : 0;
+    // 复盘在前、督导在后：同一 run 两个 pid 都活着时，先报花 token 的那个
+    const slots: [Occupant["kind"], unknown][] = [
+      ["复盘", raw.pid],
+      ["督导", raw.supervisorPid],
+    ];
+    for (const [kind, value] of slots) {
+      const pid = typeof value === "number" && value > 0 ? value : null;
+      if (pid !== null && alive(pid)) found.push({ occupant: { runId, pid, kind }, dispatchedAt });
+    }
+  }
+  return found;
+}
+
+/** 当前占用者：多条都在跑时返回最早派发的那条；没人占用返回 null */
+export function findOccupant(evolutionDir: string, deps: OccupantDeps = {}): Occupant | null {
+  // sort 是稳定排序：dispatchedAt 相同时保持「复盘先于督导」的先后
+  const found = readCandidates(evolutionDir, deps).sort((a, b) => a.dispatchedAt - b.dispatchedAt);
+  return found[0]?.occupant ?? null;
+}
+
+export interface BusyGuardInput extends OccupantDeps {
+  evolutionDir: string;
+  sessionId: string;
+  /** 遥测写入器；缺省时只记日志（督导启动那条路径理论上总有） */
+  telemetry?: TelemetryWriter;
+  /** 退出补发路径：主进程马上退出，只能同步写 */
+  sync?: boolean;
+  trigger?: "auto" | "manual" | "shutdown";
+  rounds?: number;
+  log?: (msg: string) => void;
+}
+
+/**
+ * 三处派发点共用的闸：占用时写一条 `skipped(busy)` 遥测并返回占用者，空闲返回 null。
+ * 已有 run 的状态一律不动 —— 被挡住的是「再来一个」，不是「把正在跑的收掉」。
+ */
+export function guardBusy(input: BusyGuardInput): Occupant | null {
+  const occupant = findOccupant(input.evolutionDir, input);
+  if (occupant === null) return null;
+  if (input.telemetry) {
+    const event = {
+      kind: "skipped" as const,
+      sessionId: input.sessionId,
+      why: "busy",
+      occupant,
+      ...(input.trigger === undefined ? {} : { trigger: input.trigger }),
+      ...(input.rounds === undefined ? {} : { rounds: input.rounds }),
+    };
+    if (input.sync === true) input.telemetry.appendSync(event);
+    else input.telemetry.append(event);
+  }
+  input.log?.(`[skill-evolve] 单飞闸拦下一次派生：已有子进程在跑（${occupant.kind} ${occupant.runId} pid ${occupant.pid}）`);
+  return occupant;
+}

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

@@ -0,0 +1,103 @@
+/**
+ * 派生的「开工参数」：pi 可执行文件、runId、会话 hash，以及子进程接口的最小形状。
+ *
+ * 单独成文件是为了让 dispatch.ts（常规派发）与 shutdown-dispatch.ts（退出前补发）
+ * 共享同一套命名与路径口径，而不互相 import 形成环。
+ */
+import { createHash } from "node:crypto";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** pi 不能靠 PATH 找：GUI / 非交互环境里 PATH 常常没有它 */
+export const DEFAULT_PI_BIN = "/home/suveng/.pi/agent/bin/pi";
+
+export interface SpawnedChild {
+  pid?: number;
+  unref(): void;
+  once(event: "exit", listener: (code: number | null) => void): unknown;
+  once(event: "error", listener: (error: unknown) => void): unknown;
+}
+
+export type SpawnLike = (command: string, args: string[], options: Record<string, unknown>) => SpawnedChild;
+
+export function resolvePiBin(env: NodeJS.ProcessEnv = process.env): string {
+  return env.SKILL_EVOLVE_PI_BIN || env.PI_SUBAGENT_PI_BINARY || DEFAULT_PI_BIN;
+}
+
+/** 复盘子进程的日志文件名（落在 run 目录下，与 run.json 同级） */
+export const CHILD_LOG = "child.log";
+
+export interface DetachedSpawnOptions {
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  /** stdout+stderr 追加到这个文件；null = 丢弃（只丢证据，不丢功能） */
+  logFile: string | null;
+}
+
+/**
+ * detached 派生子进程，并把它的 stdout+stderr 追加进 logFile。
+ *
+ * 为什么必须落盘：子进程静默死掉时，run.json 只会停在 dispatched、面板永远显示「复盘 1」，
+ * 连一行报错都拿不到 —— 那种现场根本查不出「为什么死」（2026-11-08 真实事故）。
+ *
+ * 日志文件开不出来（磁盘满 / 权限 / 目录不在）时退回 stdio:"ignore"：光有证据不如先有功能。
+ * 父进程 spawn 完立刻关掉自己那份 fd —— 子进程已拿到独立副本，父进程留着纯属泄漏。
+ * 单测注入假 spawnFn，本函数只负责拼 stdio 与关 fd，绝不真起进程。
+ */
+export function spawnDetached<T extends { unref?: () => void }>(
+  spawnFn: (command: string, args: string[], options: Record<string, unknown>) => T,
+  command: string,
+  args: string[],
+  options: DetachedSpawnOptions,
+): T {
+  let fd: number | null = null;
+  if (options.logFile !== null) {
+    try {
+      fs.mkdirSync(path.dirname(options.logFile), { recursive: true });
+      fd = fs.openSync(options.logFile, "a");
+    } catch {
+      fd = null;
+    }
+  }
+  try {
+    const child = spawnFn(command, args, {
+      cwd: options.cwd,
+      detached: true,
+      // stdin 不给（子进程不读输入），stdout 与 stderr 共用同一个 fd
+      stdio: fd === null ? "ignore" : ["ignore", fd, fd],
+      env: options.env,
+    });
+    child.unref?.();
+    return child;
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // 关 fd 失败无影响：父进程退出时内核也会收
+      }
+    }
+  }
+}
+
+export function sessionHashOf(sessionId: string): string {
+  return createHash("sha256").update(sessionId).digest("hex").slice(0, 16);
+}
+
+/** runId = 会话 hash 前 8 位 + 秒级时间戳，肉眼可排序、可回溯到会话 */
+export function runIdFor(sessionId: string, ts: number): string {
+  return `${sessionHashOf(sessionId).slice(0, 8)}-${Math.floor(ts / 1000)}`;
+}
+
+/**
+ * 同一秒内可能派发两次（自动结算 + 手动 `/skill-evolve run`），或两个会话刚好撞秒。
+ * run.json 是按 runId 建的目录，撞了就会互相覆盖，所以撞号时加序号后缀。
+ */
+export function uniqueRunId(evolutionDir: string, sessionId: string, ts: number): string {
+  const base = runIdFor(sessionId, ts);
+  let candidate = base;
+  for (let suffix = 2; fs.existsSync(path.join(evolutionDir, "runs", candidate)); suffix += 1) {
+    candidate = `${base}-${suffix}`;
+  }
+  return candidate;
+}

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

@@ -0,0 +1,217 @@
+/**
+ * 卡死判定（设计稿 14 章的可观测补丁）：复盘子进程死掉之后，run.json 会永远停在 dispatched，
+ * 面板永远显示「复盘 1」，run 目录里也没有一行日志 —— 这种「静默失败」靠人肉 ps 才查得出来。
+ *
+ * 三条纪律：
+ * 1. 只判「派发出去还没出结论」的三种状态（dispatched / analyzed / proposed）：
+ *    reviewed / applied 已经不缺结论，超不超时都无所谓；
+ * 2. **绝不自动重跑**：一次复盘要烧一整段会话的 token，重跑必须人来点（`/skill-evolve run`）；
+ * 3. 判定必须留下能查的证据：run.json 改成 stale，同目录落 run-error.json（含子进程日志尾部）。
+ *
+ * 读/写在同一个文件里：这条链路只有「读 run.json → 判 → 写 run.json + run-error.json」三步，
+ * 拆开反而要让三个模块共享路径口径。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { DEFAULT_CONFIG } from "./config.ts";
+import { isPidAlive } from "./lock.ts";
+import { CHILD_LOG } from "./spawn-plan.ts";
+import { writeRunRecordSync, type RunRecord } from "./runs.ts";
+
+/** 在途状态：只有这些状态的 run「没结论」才叫卡死 */
+/**
+ * 只有 `dispatched` 算「可能卡住」：run 一旦进到 analyzed/proposed，说明子进程已经把结论写回磁盘，
+ * 它的进程晚一点退出是正常的（本来就是一次性 CLI）。把 analyzed 也算成卡死，等于把「已经成功的复盘」
+ * 报成「复盘失败」—— 面板宁可少报一类，也不能误报。
+ */
+export const STALE_STATUSES = new Set(["dispatched"]);
+
+/** 判「子进程已死」前要等多久：5 分钟足够躲开 pi 启动慢与机器抖动，又不至于让人等半天 */
+export const STALE_MS = 5 * 60_000;
+
+/** run-error.json 保留的日志行数：够看出最后一句报错，又不会把文件撑大 */
+export const LOG_TAIL_LINES = 20;
+
+/** child-exited = 子进程没了；timeout = 还活着但超过单 run 上限 */
+export type StaleReason = "child-exited" | "timeout";
+
+export interface StaleVerdict {
+  stale: boolean;
+  reason?: StaleReason;
+}
+
+export interface StaleDeps {
+  /** 判「子进程已死」的等待时长（默认 STALE_MS） */
+  staleMs?: number;
+  /** 判「还在跑但太久」的上限（默认配置的 maxRuntimeMs） */
+  maxRuntimeMs?: number;
+  /** pid 存活判定：生产用 lock.ts 的 isPidAlive（kill(pid,0) 抛 ESRCH 即死），单测注入 */
+  alive?: (pid: number) => boolean;
+}
+
+/** 判定只需要三个字段：状态、子进程 pid、派发时刻 */
+export interface StaleTarget {
+  status: string;
+  pid?: number | null;
+  dispatchedAt?: number | null;
+}
+
+export interface RunError {
+  reason: StaleReason;
+  at: number;
+  /** child.log 的最后 LOG_TAIL_LINES 行；没有日志就是空数组 —— 「一条日志都没有」本身是证据 */
+  childLogTail: string[];
+}
+
+export interface StaleRun {
+  runId: string;
+  runDir: string;
+  reason: StaleReason;
+  /** 日志最后一行（展示用）；没有日志为 null */
+  lastLine: string | null;
+  at: number;
+}
+
+/**
+ * 纯判定，不做任何副作用 —— 面板要拿它算数，不能因为「看一眼面板」就去 kill 进程。
+ * 返回 timeout 时由 scanStaleRuns 负责真的收尾（kill + 落盘）。
+ */
+export function classifyStale(run: StaleTarget, now: number, deps: StaleDeps = {}): StaleVerdict {
+  if (!STALE_STATUSES.has(run.status)) return { stale: false };
+  // 没有派发时刻就证明不了「卡了多久」：宁可漏报一条，也不误伤刚起来的 run
+  const started = typeof run.dispatchedAt === "number" && Number.isFinite(run.dispatchedAt) ? run.dispatchedAt : null;
+  if (started === null) return { stale: false };
+  const elapsed = now - started;
+  const pid = typeof run.pid === "number" && run.pid > 0 ? run.pid : null;
+  const alive = deps.alive ?? isPidAlive;
+  // pid 缺失也算已死：dispatch 是先写 pid=null 再补写 pid，中间被打断就是这个形态
+  if (pid === null || !alive(pid)) {
+    return elapsed > (deps.staleMs ?? STALE_MS) ? { stale: true, reason: "child-exited" } : { stale: false };
+  }
+  return elapsed > (deps.maxRuntimeMs ?? DEFAULT_CONFIG.maxRuntimeMs) ? { stale: true, reason: "timeout" } : { stale: false };
+}
+
+/** 日志尾部：文件不在 / 读不出来都返回空数组（缺日志是常态，不能因此抛） */
+export function readLogTail(file: string, maxLines = LOG_TAIL_LINES): string[] {
+  try {
+    const lines = fs.readFileSync(file, "utf8").split("\n");
+    while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+    return lines.slice(-maxLines);
+  } catch {
+    return [];
+  }
+}
+
+export interface ScanDeps extends StaleDeps {
+  /** 超时收尾用：默认 process.kill，单测注入，绝不真杀 */
+  kill?: (pid: number) => void;
+  log?: (msg: string) => void;
+}
+
+/** run-error.json 的内容口径：一条 reason + 判定时刻 + 日志尾部 */
+export function readRunError(runDir: string): RunError | null {
+  try {
+    const raw = JSON.parse(fs.readFileSync(path.join(runDir, "run-error.json"), "utf8")) as Partial<RunError>;
+    const reason = raw.reason === "timeout" || raw.reason === "child-exited" ? raw.reason : null;
+    if (!reason) return null;
+    return {
+      reason,
+      at: typeof raw.at === "number" ? raw.at : 0,
+      childLogTail: Array.isArray(raw.childLogTail) ? raw.childLogTail.map((line) => String(line)) : [],
+    };
+  } catch {
+    return null;
+  }
+}
+
+const lastLineOf = (tail: readonly string[]): string | null => {
+  const line = tail.length > 0 ? tail[tail.length - 1]!.trim() : "";
+  return line.length > 0 ? line : null;
+};
+
+/**
+ * 扫一遍 runs/：把卡死的 run 标成 stale 并落 run-error.json，返回本次新判定的条目。
+ * 已标过 stale 的 run 状态不再属于在途，所以重复扫描不会重复写（幂等）。
+ */
+export function scanStaleRuns(evolutionDir: string, now: number, deps: ScanDeps = {}): StaleRun[] {
+  let names: string[];
+  try {
+    names = fs.readdirSync(path.join(evolutionDir, "runs"));
+  } catch {
+    return [];
+  }
+  const found: StaleRun[] = [];
+  for (const name of names) {
+    const runDir = path.join(evolutionDir, "runs", name);
+    const file = path.join(runDir, "run.json");
+    let raw: Record<string, unknown> & StaleTarget;
+    try {
+      raw = JSON.parse(fs.readFileSync(file, "utf8")) as Record<string, unknown> & StaleTarget;
+    } catch {
+      continue; // run.json 不在或坏掉：没有可判的记录
+    }
+    const verdict = classifyStale(raw, now, deps);
+    if (!verdict.stale || !verdict.reason) continue;
+    const reason = verdict.reason;
+    // 超时的那类进程还活着：先杀掉，否则下一次扫描会再判一次、再 kill 一次
+    if (reason === "timeout" && typeof raw.pid === "number" && raw.pid > 0) {
+      try {
+        (deps.kill ?? ((pid: number) => process.kill(pid)))(raw.pid);
+      } catch (error) {
+        deps.log?.(`[skill-evolve] 超时收尾 kill(${raw.pid}) 失败：${String(error)}`);
+      }
+    }
+    const childLogTail = readLogTail(path.join(runDir, CHILD_LOG));
+    const error: RunError = { reason, at: now, childLogTail };
+    try {
+      raw.status = "stale";
+      writeRunRecordSync(runDir, raw as unknown as RunRecord);
+      fs.writeFileSync(path.join(runDir, "run-error.json"), `${JSON.stringify(error, null, 2)}\n`, "utf8");
+    } catch (caused) {
+      // 写不进去只记日志：扫描本身不能把面板刷新的调用方搞挂
+      deps.log?.(`[skill-evolve] 标记 stale 失败（${name}）：${String(caused)}`);
+      continue;
+    }
+    found.push({
+      runId: typeof raw.runId === "string" ? raw.runId : name,
+      runDir,
+      reason,
+      lastLine: lastLineOf(childLogTail),
+      at: now,
+    });
+    deps.log?.(`[skill-evolve] run ${name} 判定卡死（${reason}）`);
+  }
+  return found;
+}
+
+/** 已经标过 stale 的 run（只读，不重新判定、不写文件）：`/skill-evolve status` 用它列失败条目 */
+export function listStaleRuns(evolutionDir: string, limit = 5): StaleRun[] {
+  let names: string[];
+  try {
+    names = fs.readdirSync(path.join(evolutionDir, "runs"));
+  } catch {
+    return [];
+  }
+  const found: { run: StaleRun; dispatchedAt: number }[] = [];
+  for (const name of names) {
+    const runDir = path.join(evolutionDir, "runs", name);
+    try {
+      const raw = JSON.parse(fs.readFileSync(path.join(runDir, "run.json"), "utf8")) as Record<string, unknown>;
+      if (raw.status !== "stale") continue;
+      const error = readRunError(runDir);
+      found.push({
+        run: {
+          runId: typeof raw.runId === "string" ? raw.runId : name,
+          runDir,
+          reason: error?.reason ?? "child-exited",
+          lastLine: lastLineOf(error?.childLogTail ?? []),
+          at: error?.at ?? 0,
+        },
+        dispatchedAt: typeof raw.dispatchedAt === "number" ? raw.dispatchedAt : 0,
+      });
+    } catch {
+      continue;
+    }
+  }
+  return found.sort((a, b) => b.dispatchedAt - a.dispatchedAt).slice(0, limit).map((item) => item.run);
+}