pi-skill-evolve 0.0.0-stage → 0.1.2

package/extensions/skill-evolve/lib/web/approvals.ts

@@ -0,0 +1,58 @@
+/**
+ * 「待审批」视图的数据：只收 `status === "pending" && level === "approval"` 的队列条目。
+ *
+ * 为什么不复用 pending 视图的条目：待处理页混了正在跑 / 卡死 / 待入队，那一页是「现在发生了什么」；
+ * 待审批页要能直接点按钮，所以每条必须自带批与不批所需的最小事实 ——
+ * 改了哪个文件（targets）、改了多少行（proposal）、评审怎么说（verdict + blocking 条数）。
+ *
+ * 纪律与 data.ts 相同：只读、坏数据当空、绝不因为一条烂 run.json 让整页 500。
+ */
+import * as path from "node:path";
+import type { QueueItem } from "../queue.ts";
+import { readProposalSummary } from "../proposal.ts";
+import { asNumber, asText, readJson } from "./json-read.ts";
+
+export interface ApprovalItem {
+  runId: string;
+  skill: string;
+  level: string;
+  /** 相对仓库根的落盘目标（队列里就存着，不重算） */
+  targets: string[];
+  createdAt: number | null;
+  /** 提案摘要：类型与增删行数（读不到 02-proposal.json 就是 null） */
+  proposal: { type: string; added: number; removed: number } | null;
+  /** 评审结论：verdict 与 blocking 条数（读不到 03-review.json 就是 null） */
+  review: { verdict: string | null; blocking: number } | null;
+  /** 队列里记的备注（入队时写的层级理由等） */
+  detail: string;
+}
+
+function readReview(runDir: string): ApprovalItem["review"] {
+  const raw = readJson<Record<string, unknown>>(path.join(runDir, "03-review.json"));
+  if (!raw) return null;
+  return {
+    verdict: typeof raw.verdict === "string" ? raw.verdict : null,
+    blocking: Array.isArray(raw.blocking) ? raw.blocking.length : 0,
+  };
+}
+
+/** 待批条目：只有 approval 级要人看；auto 级由 session_start / settle 自己跑掉 */
+export function buildApprovals(evolutionDir: string, items: readonly QueueItem[]): ApprovalItem[] {
+  return items
+    .filter((item) => item.status === "pending" && item.level === "approval")
+    .sort((a, b) => a.createdAt - b.createdAt)
+    .map((item) => {
+      const runDir = path.join(evolutionDir, "runs", item.runId);
+      const summary = readProposalSummary(runDir);
+      return {
+        runId: item.runId,
+        skill: item.skill,
+        level: item.level,
+        targets: item.targets,
+        createdAt: asNumber(item.createdAt),
+        proposal: summary ? { type: summary.type, added: summary.added, removed: summary.removed } : null,
+        review: readReview(runDir),
+        detail: asText(item.detail),
+      };
+    });
+}

package/extensions/skill-evolve/lib/web/audit-log.ts

@@ -0,0 +1,115 @@
+/**
+ * 操作审计：`.pi/evolution/actions.log`（JSONL，一行一个动作）。
+ *
+ * 三条纪律：
+ * 1. **只追加**：审计是事后追溯用的，绝不改写既有行（读写同一份文件时，改写必然丢别人的尾行）；
+ * 2. **写失败不反噬动作**：动作已经生效（或已经失败）了，日志写不进去只能留 console，
+ *    不能把结果改写成报错 —— 与 lib/telemetry.ts「运行态写失败只记日志」同一口径；
+ * 3. **只读尾部**：文件会一直长，读的时候只取尾部 64KB；从半行开始的那半截解析必然失败，靠坏行跳过自然吃掉。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export const AUDIT_FILE = "actions.log";
+/** 读尾部窗口：够装上千条动作，又不至于让一页面板去读一个几百 MB 的日志 */
+const READ_WINDOW_BYTES = 64 * 1024;
+
+export const AUDIT_ACTIONS = ["toggle", "run", "rerun", "cleanup", "approve", "reject"] as const;
+export type AuditAction = (typeof AUDIT_ACTIONS)[number];
+
+/**
+ * `ok` = 全部生效；`partial` = 命令跑完但没派发（总开关关 / 已有复盘在跑 / 去抖窗口里）；
+ * `error: …` = 没做成，后面跟一句原因（校验失败、回调抛错都走这条）。
+ */
+export type AuditResult = "ok" | "partial" | `error: ${string}`;
+
+export interface AuditEntry {
+  /** 毫秒时间戳：与 runs/config 用同一种时间，渲染层才能算出「几分钟前」 */
+  at: number;
+  action: AuditAction;
+  /** 只有 rerun / cleanup 这类针对具体 run 的动作才有 */
+  runId?: string;
+  /**
+   * 只有开关动作（`/toggle?field=`）才有：`telemetry`（采集）/ `enabled`（复盘），
+   * 越界被拒时写的是原样的查询值 —— 事后才能分清「他点的是哪个开关」。
+   */
+  field?: string;
+  result: AuditResult;
+  /**
+   * 来源标记固定 `web`：将来 TUI 也记审计时，靠它区分「谁点的」，
+   * 现在写死也留字段，是因为日志是 append-only，事后补不回来。
+   */
+  via: "web";
+}
+
+export function auditFile(evolutionDir: string): string {
+  return path.join(evolutionDir, AUDIT_FILE);
+}
+
+export function appendAudit(evolutionDir: string, entry: AuditEntry): void {
+  try {
+    fs.mkdirSync(evolutionDir, { recursive: true });
+    fs.appendFileSync(auditFile(evolutionDir), `${JSON.stringify(entry)}\n`, "utf8");
+  } catch (error) {
+    console.error(`[skill-evolve] 审计写入失败（${auditFile(evolutionDir)}）：${String(error)}`);
+  }
+}
+
+/** 读文件尾部窗口的文本；不存在或读失败返回空串（文件不存在 = 还没发生过动作，不是错误） */
+function tailText(file: string): string {
+  let fd: number | null = null;
+  try {
+    const size = fs.statSync(file).size;
+    const start = Math.max(0, size - READ_WINDOW_BYTES);
+    fd = fs.openSync(file, "r");
+    const buffer = Buffer.alloc(size - start);
+    fs.readSync(fd, buffer, 0, buffer.length, start);
+    return buffer.toString("utf8");
+  } catch {
+    return "";
+  } finally {
+    if (fd !== null) {
+      try {
+        fs.closeSync(fd);
+      } catch {
+        // 关不掉不影响已读到的内容，下一次读还会重新 open
+      }
+    }
+  }
+}
+
+/**
+ * 尾部 `limit` 条，按文件顺序返回（老的在前）。
+ * 坏行一律跳过：半行、手改、并发截断都当不存在 —— 审计不该因为一行写坏了整页打不开。
+ */
+export function readAudit(evolutionDir: string, limit = 20): AuditEntry[] {
+  const entries: AuditEntry[] = [];
+  for (const line of tailText(auditFile(evolutionDir)).split("\n")) {
+    if (line.trim().length === 0) continue;
+    let parsed: Partial<AuditEntry>;
+    try {
+      parsed = JSON.parse(line) as Partial<AuditEntry>;
+    } catch {
+      continue;
+    }
+    if (typeof parsed.at !== "number" || !Number.isFinite(parsed.at)) continue;
+    if (typeof parsed.action !== "string" || !isAction(parsed.action)) continue;
+    if (typeof parsed.result !== "string" || parsed.result.length === 0) continue;
+    if (parsed.via !== "web") continue;
+    const entry: AuditEntry = {
+      at: parsed.at,
+      action: parsed.action,
+      result: parsed.result as AuditResult,
+      via: "web",
+    };
+    if (typeof parsed.runId === "string" && parsed.runId.length > 0) entry.runId = parsed.runId;
+    if (typeof parsed.field === "string" && parsed.field.length > 0) entry.field = parsed.field;
+    entries.push(entry);
+  }
+  return limit > 0 ? entries.slice(-limit) : [];
+}
+
+/** 未知动作不往页面上渲染：日志里出现新动作（老版本 / 手改）时面板不能崩 */
+function isAction(value: string): value is AuditAction {
+  return (AUDIT_ACTIONS as readonly string[]).includes(value);
+}

package/extensions/skill-evolve/lib/web/autostart.ts

@@ -0,0 +1,177 @@
+/**
+ * Web 面板的生命周期：跟着 pi 进程走（用户 2026-11-08：「期望是 pi 启动，他也启动，reload 就退出重启」）。
+ *
+ * 四条边界：
+ * 1. **面板是附属物**：自动启动失败只记日志，绝不阻塞会话启动，也不抛给事件回调；
+ * 2. **端口占用要分清主人**：`locks/web.json` 里是别的活 pid 就不抢（那是另一个 pi 窗口的面板）；
+ *    是本进程 pid 才允许重试 —— `/reload` 不换 pid，旧实例的残影只能这样认出来；
+ * 3. **关停要真释放**：`/reload` 先给旧实例发 `session_shutdown`、再给新实例发 `session_start`，
+ *    旧实例必须等监听真的关闭，否则新实例第一次 listen 必吃 EADDRINUSE（重试就是兜这一手）；
+ * 4. **本文件不 import node:http**：真启动由 index.ts 注入（`startWebPanel`），单测喂假 start 即可，
+ *    所以这里一个端口都不占。
+ */
+import { loadConfig, saveWebConfig, type EvolutionConfig } from "../config.ts";
+import type { MutationQueue } from "../telemetry.ts";
+import { isAlive, readWebPid } from "./panel-pid.ts";
+import type { WebPanel, WebPanelErrorCode, WebPanelResult } from "./server.ts";
+
+/** 首次之外最多重试 3 次；间隔按 reload 实测节奏放大（旧实例关 socket 基本在第一次重试前完成） */
+const RETRY_DELAYS_MS: readonly number[] = [300, 600, 900];
+
+/** 自动启动只关心「成没成 + 地址 / 失败码」，面板对象由 WebLifecycle 自己持有 */
+export type WebStartResult =
+  | { ok: true; url: string }
+  | { ok: false; code: WebPanelErrorCode; message: string };
+
+export type WebAutostartResult =
+  | { started: true; url: string }
+  | {
+      started: false;
+      /** disabled：配置没开；owned-elsewhere：别的活实例占着；failed：重试到底仍失败 */
+      reason: "disabled" | "owned-elsewhere" | "failed";
+      /** owned-elsewhere 时是抢手面板的地址 */
+      url?: string;
+      message?: string;
+    };
+
+export interface WebAutostartDeps {
+  config: EvolutionConfig;
+  evolutionDir: string;
+  /** 起监听；端口来自配置（已校验过 1..65535） */
+  start(port: number): Promise<WebStartResult>;
+  /** 注入 sleep 便于断言重试节奏（真实现是 setTimeout） */
+  sleep?(ms: number): Promise<void>;
+  log?(msg: string): void;
+}
+
+/**
+ * 会话启动时的自动起面板。
+ *
+ * 计时口径：第一次失败后重试 3 次，间隔 300 / 600 / 900ms（即总共最多 4 次 start 调用）。
+ * 只有端口占用值得重试：没权限（EACCES）与未知错误重试还是同一个结果，直接判失败。
+ */
+export async function maybeStartWeb(deps: WebAutostartDeps): Promise<WebAutostartResult> {
+  if (deps.config.web.enabled !== true) return { started: false, reason: "disabled" };
+  const log = deps.log ?? (() => {});
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((done) => setTimeout(done, ms)));
+  const port = deps.config.web.port;
+  let message = "";
+  for (let retry = 0; ; retry += 1) {
+    const result = await deps.start(port);
+    if (result.ok) {
+      log(`[skill-evolve] web 面板随会话启动：${result.url}`);
+      return { started: true, url: result.url };
+    }
+    message = result.message;
+    if (result.code !== "EADDRINUSE") break;
+    const owner = readWebPid(deps.evolutionDir);
+    // pid 等于本进程 = /reload 后旧实例的残影（进程没换），可以抢；别人的活面板不许抢
+    if (owner && owner.pid !== process.pid && isAlive(owner.pid)) {
+      log(`[skill-evolve] web 面板由 pid ${owner.pid} 持有（${owner.url}），本实例不抢`);
+      return { started: false, reason: "owned-elsewhere", url: owner.url };
+    }
+    const delay = RETRY_DELAYS_MS[retry];
+    if (delay === undefined) break;
+    log(`[skill-evolve] web 面板重试 ${retry + 1}/3：端口 ${port} 仍被占用`);
+    await sleep(delay);
+  }
+  log(`[skill-evolve] web 面板未启动（端口 ${port}）：${message}`);
+  return { started: false, reason: "failed", message };
+}
+
+/** `/skill-evolve web [--port N] [--once]` 的参数：端口由命令层校验，这里只管语义 */
+export interface WebLaunchRequest {
+  /** 显式端口；不给就用配置里的值 */
+  port?: number;
+  /** true → 只本次会话有效，不写回配置 */
+  once: boolean;
+}
+
+export interface WebLifecycleDeps {
+  /** 演化目录随会话工作区变（换工作区后配置要读新的那份），所以给 getter */
+  evolutionDir(): string;
+  /** 真正的启动实现（index.ts 注入 startWebPanel；单测注入假实现，零端口） */
+  start(port?: number): Promise<WebPanelResult>;
+  queue: MutationQueue;
+  log(msg: string): void;
+}
+
+export interface WebLifecycle {
+  /** `session_start`：配置开着就起，任何失败只记日志 */
+  startForSession(): Promise<void>;
+  /** 命令路径：起面板，非 `--once` 时把 web.enabled 写回配置 */
+  command(request: WebLaunchRequest): Promise<string>;
+  /** `session_shutdown`：等监听真的关闭（reason 只进日志，用于自证是哪条路走的） */
+  shutdown(reason: string): Promise<void>;
+  /** `/skill-evolve off`：关面板 + 写 web.enabled=false */
+  disable(): Promise<string>;
+  /** 当前面板地址；没跑就是 undefined（命令与 status 用） */
+  url(): string | undefined;
+}
+
+/** 面板单例 + 起停 + 配置写回：一个会话（一个扩展实例）只该有一个面板 */
+export function createWebLifecycle(deps: WebLifecycleDeps): WebLifecycle {
+  let panel: WebPanel | null = null;
+
+  /** 自动启动的入口：成功时顺手把面板记成单例，shutdown 才有东西可关 */
+  const launch = async (port: number): Promise<WebStartResult> => {
+    const result = await deps.start(port);
+    if (!result.ok) return result;
+    panel = result.panel;
+    return { ok: true, url: result.panel.url };
+  };
+
+  const startForSession = async (): Promise<void> => {
+    // 单例：同一实例重复 session_start（new / resume / fork）不重复起
+    if (panel) return;
+    try {
+      const evolutionDir = deps.evolutionDir();
+      await maybeStartWeb({ config: loadConfig(evolutionDir, deps.log), evolutionDir, start: launch, log: deps.log });
+    } catch (error) {
+      // 自动起是锦上添花：异常只记日志，绝不冒到会话启动
+      deps.log(`[skill-evolve] web 面板自动启动异常：${String(error)}`);
+    }
+  };
+
+  const command = async (request: WebLaunchRequest): Promise<string> => {
+    if (panel) return `面板已在 ${panel.url} 运行`;
+    const result = await deps.start(request.port);
+    if (!result.ok) return result.message;
+    panel = result.panel;
+    const url = panel.url;
+    const boundary = "只绑 127.0.0.1（无鉴权，别转发到公网）；待审批页 ?view=approvals 可直接批；机器可读副本 /api/state";
+    if (request.once) return `面板已起：${url}（--once：只本次会话有效，没写进配置）\n${boundary}`;
+    try {
+      // 端口一起写：下次自动起必须落在同一个地址，否则「pi 启动时会自动起」就是句空话
+      await saveWebConfig(deps.evolutionDir(), { enabled: true, port: panel.port }, deps.queue);
+    } catch (error) {
+      return `面板已起：${url}（写配置失败，下次 pi 启动不会自动起：${String(error)}）\n${boundary}`;
+    }
+    return `面板已起：${url}（已在配置里开启，pi 启动时会自动起；换端口 --port 7799）\n${boundary}`;
+  };
+
+  const shutdown = async (reason: string): Promise<void> => {
+    const current = panel;
+    panel = null;
+    if (!current) return;
+    try {
+      // close() 内含 server.closeAsync 语义：回调返回时监听已释放，端口可被立刻重新 listen
+      await current.close();
+      deps.log(`[skill-evolve] web 面板关闭（reason=${reason}）`);
+    } catch (error) {
+      deps.log(`[skill-evolve] web 面板关闭失败（reason=${reason}）：${String(error)}`);
+    }
+  };
+
+  const disable = async (): Promise<string> => {
+    await shutdown("off");
+    try {
+      await saveWebConfig(deps.evolutionDir(), { enabled: false }, deps.queue);
+    } catch (error) {
+      return `Web 面板已关，但写 web.enabled=false 失败：${String(error)}`;
+    }
+    return "Web 面板已关，配置已写 web.enabled=false（下次 pi 启动不再自动起；重开：/skill-evolve web）";
+  };
+
+  return { startForSession, command, shutdown, disable, url: () => panel?.url };
+}

package/extensions/skill-evolve/lib/web/data.ts

@@ -0,0 +1,298 @@
+/**
+ * 只读 Web 面板的数据聚合：把 `.pi/evolution/` 的散落文件拼成三个视图要的形状。
+ *
+ * 三条纪律：
+ * 1. **只读**：这里不写盘、不开监听、不改任何状态 —— 面板永远不能变成第二个写入方；
+ * 2. **坏数据当空**：run.json / 队列 / 各类产出一律可能「写到一半被 kill」，任何字段缺失都退化成
+ *    null / []，绝不因为一条烂记录让整页 500（用户从飞书点进来只想要个概览）；
+ * 3. **数字不重算**：summary 直接复用 collectPanelState，和 TUI 状态栏同一口径 ——
+ *    两处各算一套，迟早出现「TUI 说待批 2、网页说待批 3」。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { collectPanelState } from "../panel.ts";
+import { readQueue, type QueueItem } from "../queue.ts";
+import { listRuns, type RunSummary } from "../runs.ts";
+import { CHILD_LOG } from "../spawn-plan.ts";
+import { classifyStale, readLogTail } from "../stale.ts";
+import { readRunError } from "../stale.ts";
+import { asNumber, asText } from "./json-read.ts";
+import { buildApplied, type AppliedItem } from "./applied.ts";
+import { buildApprovals, type ApprovalItem } from "./approvals.ts";
+import { buildReports, type RunReport } from "./reports.ts";
+
+export { MAX_FINDING_ROWS } from "./reports.ts";
+export type { FindingRow, RunReport } from "./reports.ts";
+export type { ApprovalItem } from "./approvals.ts";
+export type { AppliedItem } from "./applied.ts";
+
+/** 列表页（技能管理页 `skills` 与两个详情页 `run` / `skill` 不在这个联合里，见 filter.ts 的 PANEL_VIEWS） */
+export const WEB_VIEWS = ["pending", "approvals", "applied", "done", "reports"] as const;
+export type WebView = (typeof WEB_VIEWS)[number];
+
+/** 已处理列表上限：网页是「翻最近发生了什么」，不是审计日志（审计看 runs/ 目录本身） */
+export const DONE_LIMIT = 50;
+/** 扫描最近多少个 run：卡死 / 待入队这类判断只需要看近期，runs/ 里可能有几百个历史目录 */
+const SCAN_LIMIT = 100;
+
+/** 单 run 默认上限：与 DEFAULT_CONFIG.maxRuntimeMs 同值，面板只用来算「上限 N 分钟」 */
+const DEFAULT_MAX_RUNTIME_MS = 20 * 60_000;
+
+/** 待处理四来源：正在跑 / 已判卡死 / 队列待批 / 评审通过但还没入队 */
+export type PendingKind = "running" | "approval" | "stale" | "reviewed";
+
+export interface PendingItem {
+  runId: string;
+  kind: PendingKind;
+  skill: string;
+  at: number | null;
+  /** 展开后的纯文本（渲染层负责转义） */
+  detail: string;
+}
+
+export interface DoneItem {
+  runId: string;
+  status: string;
+  /** queue = 采纳队列（有层级与详情）；run = 只有 run.json 的终态（比如 rejected 从未入队） */
+  source: "queue" | "run";
+  level: string;
+  skill: string;
+  at: number | null;
+  detail: string;
+}
+
+export interface WebSummary {
+  reviewing: number;
+  stale: number;
+  pendingApprovals: number;
+  appliedTotal: number;
+  rollbackRate: number;
+}
+
+export interface WebState {
+  pending: PendingItem[];
+  /** 待审批：只收 pending + approval 级，带按钮所需的最小事实（见 ./approvals.ts） */
+  approvals: ApprovalItem[];
+  /** 已采纳：只收队列 applied，且**不再**进 done（两个 tab 不许混） */
+  applied: AppliedItem[];
+  done: DoneItem[];
+  reports: RunReport[];
+  summary: WebSummary;
+}
+
+export interface WebStateDeps {
+  /** 现时（单测注入固定时钟） */
+  now?: number;
+  /** pid 存活判定（默认 process.kill(pid,0)；单测注入，测试里不起真进程） */
+  alive?: (pid: number) => boolean;
+  /** 单 run 上限（毫秒），只用于「上限 N 分钟」那一行 */
+  maxRuntimeMs?: number;
+}
+
+function defaultAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0); // 信号 0 只探测存在性，不真发信号
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** 把毫秒压成「Xm Ys」：面板上人只关心量级，不关心毫秒 */
+function duration(ms: number): string {
+  const total = Math.max(0, Math.floor(ms / 1000));
+  return `${Math.floor(total / 60)}m ${total % 60}s`;
+}
+
+/**
+ * 「正在跑」那一条：光看 `复盘 1` 这个数字不知道是谁、跑到哪、要不要杀，
+ * 所以把阶段 / 进程 / 最近输出 / 看日志的命令四行摊开（用户 2026-11-08：「复盘中我也想看到状态呢」）。
+ */
+function runningItem(
+  run: RunSummary,
+  evolutionDir: string,
+  now: number,
+  alive: (pid: number) => boolean,
+  maxRuntimeMs: number,
+): PendingItem | null {
+  if (run.status !== "dispatched" || run.pid === null || !alive(run.pid)) return null;
+  const reviewing = run.supervisorPid !== null && alive(run.supervisorPid);
+  const logPath = path.join(evolutionDir, "runs", run.runId, CHILD_LOG);
+  let mtime: number | null = null;
+  try {
+    mtime = fs.statSync(logPath).mtimeMs; // 拿不到就是还没写过日志
+  } catch {
+    mtime = null;
+  }
+  const tail = readLogTail(logPath, 1);
+  const lastLine = tail.length > 0 ? tail[tail.length - 1]!.trim() : "";
+  const progressLine =
+    mtime === null
+      ? "最近输出：（还没有输出）"
+      : `最近输出：${Math.max(0, Math.round((now - mtime) / 1000))}s 前 · 末行：${lastLine.length > 0 ? lastLine : "（还没有输出）"}`;
+  return {
+    runId: run.runId,
+    kind: "running",
+    skill: run.proposal?.skill ?? "",
+    at: run.dispatchedAt,
+    detail: [
+      `阶段：${reviewing ? "评审中" : "复盘产出中"}`,
+      `进程：pid ${run.pid} · 已跑 ${duration(now - (run.dispatchedAt ?? now))}（上限 ${Math.round(maxRuntimeMs / 60_000)} 分钟）`,
+      progressLine,
+      `日志：tail -f .pi/evolution/runs/${run.runId}/${CHILD_LOG}`,
+    ].join("\n"),
+  };
+}
+
+/** 四类条目的展示优先级：正在跑最上头，然后卡死、待批、待入队 */
+const PENDING_RANK: Record<PendingKind, number> = { running: 0, stale: 1, approval: 2, reviewed: 3 };
+
+function buildPending(
+  items: readonly QueueItem[],
+  runs: readonly RunSummary[],
+  evolutionDir: string,
+  deps: WebStateDeps = {},
+): PendingItem[] {
+  const now = deps.now ?? Date.now();
+  const alive = deps.alive ?? defaultAlive;
+  const maxRuntimeMs = deps.maxRuntimeMs ?? DEFAULT_MAX_RUNTIME_MS;
+  const pending: PendingItem[] = [];
+  // ⓪ 正在跑的：有活 pid 就是「进行中」，先列出来（它不是等批也不是失败）
+  const running = new Set<string>();
+  for (const run of runs) {
+    const item = runningItem(run, evolutionDir, now, alive, maxRuntimeMs);
+    if (!item) continue;
+    running.add(run.runId);
+    pending.push(item);
+  }
+  // ① 队列里待人批的（approval 级；auto 级不需要人，出现 pending 只是还没轮到执行）
+  for (const item of items) {
+    if (item.status !== "pending" || item.level !== "approval") continue;
+    pending.push({
+      runId: item.runId,
+      kind: "approval",
+      skill: item.skill,
+      at: asNumber(item.createdAt),
+      detail: [
+        "层级：approval（必须人批，auto 不会替你执行）",
+        `目标：${item.targets.join("、") || "（未写 targets）"}`,
+        item.detail ? `备注：${item.detail}` : "",
+        `操作：去「待审批」页（?view=approvals）直接点批准 / 拒绝，也可以在这里回 TUI 敲 /skill-evolve approve ${item.runId}`,
+      ]
+        .filter((line) => line.length > 0)
+        .join("\n"),
+    });
+  }
+  // ② 已判定卡死的 run：它是「失败」而不是「等批」，单独一类，别混进待批数字里。
+  //    这里必须包含「判据命中、run.json 还没落盘」的那一批：顶部 summary.stale 用的是
+  //    collectPanelState 的同一口径，少一类就会出现「头顶说卡死 5、列表只有 3 条」。
+  for (const run of runs) {
+    if (running.has(run.runId)) continue; // 同一个 run 不能既「进行中」又「卡死」
+    const persisted = run.status === "stale";
+    if (!persisted && !classifyStale(run, now).stale) continue;
+    const error = readRunError(path.join(evolutionDir, "runs", run.runId));
+    const tail = error?.childLogTail ?? [];
+    const lastLine = tail.length > 0 ? tail[tail.length - 1]!.trim() : "";
+    pending.push({
+      runId: run.runId,
+      kind: "stale",
+      skill: run.proposal?.skill ?? "",
+      at: error?.at ?? run.dispatchedAt,
+      detail: [
+        `原因：${error?.reason === "timeout" ? "超时（子进程还活着但超过单 run 上限）" : "子进程已退出"}`,
+        lastLine.length > 0 ? `日志末行：${lastLine}` : "日志末行：（子进程没留下任何输出）",
+        `排查：cat ${path.join(evolutionDir, "runs", run.runId, "run-error.json")}`,
+        "不会自动重跑：需要重新复盘就 /skill-evolve run",
+      ].join("\n"),
+    });
+  }
+  // ④ 子进程已产出结论、评审还没跑的：不是失败（子进程本来就该退出），属于「等下一轮接上」
+  for (const run of runs) {
+    if (run.status !== "analyzed" && run.status !== "proposed") continue;
+    pending.push({
+      runId: run.runId,
+      kind: "reviewed",
+      skill: run.proposal?.skill ?? "",
+      at: run.dispatchedAt,
+      detail: [
+        `状态：已出结论（${run.status}），评审还没跑`,
+        "会自动接上：下次 settle 或 session_start 继续；想立即接上就 /skill-evolve run",
+        `证据：cat ${path.join(evolutionDir, "runs", run.runId, "01-findings.json")}`,
+      ].join("\n"),
+    });
+  }
+  // ③ 评审通过但还没进队列（入队发生在 settle / session_start，中间可能还没轮到）
+  const queued = new Set(items.map((item) => item.runId));
+  for (const run of runs) {
+    if (run.status !== "reviewed" || queued.has(run.runId)) continue;
+    pending.push({
+      runId: run.runId,
+      kind: "reviewed",
+      skill: run.proposal?.skill ?? "",
+      at: run.dispatchedAt,
+      detail: [
+        `评审：${asText(run.review?.verdict, "（未写 verdict）")} · 建议动作 ${asText(run.review?.action, "无")}`,
+        "状态：评审已通过，尚未入队（settle / session_start 会自动补）",
+        `兜底：/skill-evolve approve ${run.runId}`,
+      ].join("\n"),
+    });
+  }
+  return pending.sort((a, b) => PENDING_RANK[a.kind] - PENDING_RANK[b.kind] || (b.at ?? 0) - (a.at ?? 0));
+}
+
+/**
+ * 「已处理」收的终态：回滚 / 失败 / 否决 / 被取代。
+ * **不含 applied** —— 采纳有自己的页（见 ./applied.ts），两边都收就等于两个 tab 都算一遍。
+ */
+const DONE_STATUSES = new Set(["rolled-back", "failed", "rejected", "superseded"]);
+
+function buildDone(items: readonly QueueItem[], runs: readonly RunSummary[]): DoneItem[] {
+  const byRun = new Map<string, DoneItem>();
+  for (const run of runs) {
+    if (!DONE_STATUSES.has(run.status)) continue;
+    byRun.set(run.runId, {
+      runId: run.runId,
+      status: run.status,
+      source: "run",
+      level: asText(run.review?.action, "-"),
+      skill: run.proposal?.skill ?? "",
+      at: run.dispatchedAt,
+      detail: run.review?.verdict ? `评审：${run.review.verdict}` : "",
+    });
+  }
+  // 队列记录覆盖同 runId：它有层级（auto/approval）与失败详情，比 run.json 只有状态有用
+  for (const item of items) {
+    if (!DONE_STATUSES.has(item.status)) continue;
+    byRun.set(item.runId, {
+      runId: item.runId,
+      status: item.status,
+      source: "queue",
+      level: item.level,
+      skill: item.skill,
+      at: asNumber(item.createdAt),
+      detail: item.detail ?? "",
+    });
+  }
+  return [...byRun.values()].sort((a, b) => (b.at ?? 0) - (a.at ?? 0)).slice(0, DONE_LIMIT);
+}
+
+export function collectWebState(input: { evolutionDir: string } & WebStateDeps): WebState {
+  const { evolutionDir, ...deps } = input;
+  const items = readQueue(evolutionDir);
+  const runs = listRuns(evolutionDir, SCAN_LIMIT);
+  const panel = collectPanelState({ evolutionDir });
+  return {
+    pending: buildPending(items, runs, evolutionDir, deps),
+    approvals: buildApprovals(evolutionDir, items),
+    applied: buildApplied(items, evolutionDir),
+    done: buildDone(items, runs),
+    reports: buildReports(evolutionDir, runs),
+    summary: {
+      reviewing: panel.reviewing,
+      stale: panel.staleCount,
+      pendingApprovals: panel.pendingApprovals,
+      appliedTotal: items.filter((item) => item.status === "applied").length,
+      rollbackRate: panel.rollbackRate,
+    },
+  };
+}