pi-skill-evolve 0.0.0-stage → 0.1.2

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

@@ -0,0 +1,131 @@
+/**
+ * 跑一次评审子进程：`pi -p --no-session -ns <prompt>`，带超时与「invalid 重评一次」。
+ *
+ * 这里是评审流水线唯一会起外部进程的地方，评审督导（review-supervisor）与必红自检
+ * （selftest）共用，避免两处各写一套超时/重试导致行为不一致。
+ * spawnFn / now / sleep 全部可注入：单测不真起 pi、不真等 300 秒。
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import { resolvePiBin } from "./spawn-plan.ts";
+import { postProcessReview, type ReviewResult } from "./review-post.ts";
+
+export interface ReviewChild {
+  pid?: number;
+  stdout?: { on(event: "data", cb: (chunk: unknown) => void): void } | null;
+  once(event: "exit" | "error", cb: (arg?: unknown) => void): void;
+  unref?: () => void;
+  kill?: (signal?: NodeJS.Signals) => void;
+}
+
+export type ReviewSpawn = (command: string, args: string[], options: Record<string, unknown>) => ReviewChild;
+
+export interface ReviewChildOptions {
+  prompt: string;
+  cwd: string;
+  /** "inherit" 或空 → 不传 --model，让子进程用默认模型 */
+  model?: string;
+  env?: NodeJS.ProcessEnv;
+  spawnFn?: ReviewSpawn;
+  timeoutMs?: number;
+  pollMs?: number;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  log?: (msg: string) => void;
+}
+
+export interface ReviewChildOutcome {
+  status: "text" | "timeout" | "spawn-error";
+  text: string;
+  ms: number;
+  detail?: string;
+}
+
+export const DEFAULT_REVIEW_TIMEOUT_MS = 300_000;
+const DEFAULT_POLL_MS = 250;
+
+export function reviewArgs(prompt: string, model?: string): string[] {
+  const args = ["-p", "--no-session", "-ns", prompt];
+  if (model && model !== "inherit") args.push("--model", model);
+  return args;
+}
+
+export async function runReviewChild(options: ReviewChildOptions): Promise<ReviewChildOutcome> {
+  const env = options.env ?? process.env;
+  const now = options.now ?? Date.now;
+  const sleep = options.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const spawnFn = options.spawnFn ?? (nodeSpawn as unknown as ReviewSpawn);
+  const timeoutMs = options.timeoutMs ?? DEFAULT_REVIEW_TIMEOUT_MS;
+  const pollMs = Math.max(1, options.pollMs ?? DEFAULT_POLL_MS);
+  const started = now();
+  let text = "";
+  let settled = false;
+  let failure: string | undefined;
+  const child = spawnFn(resolvePiBin(env), reviewArgs(options.prompt, options.model), {
+    cwd: options.cwd,
+    detached: true,
+    stdio: ["ignore", "pipe", "ignore"],
+    // 评审进程也是子代理进程：带上标记，避免它自己被扩展的采集钩子挂上去
+    env: { ...env, SKILL_EVOLVE_CHILD: "1" },
+  });
+  child.stdout?.on("data", (chunk) => {
+    text += String(chunk);
+  });
+  child.once("exit", () => {
+    settled = true;
+  });
+  child.once("error", (error) => {
+    failure = (error as Error | undefined)?.message ?? "spawn 失败";
+    settled = true;
+  });
+  const deadline = started + timeoutMs;
+  while (!settled && now() < deadline) await sleep(pollMs);
+  const ms = now() - started;
+  if (!settled) {
+    try {
+      child.kill?.("SIGKILL");
+    } catch {
+      // 已经退出或权限不足：超时结论不变，不必再喊
+    }
+    options.log?.(`[skill-evolve] 评审子进程超时（${timeoutMs}ms），已放弃`);
+    return { status: "timeout", text, ms, detail: `review-timeout: 超过 ${timeoutMs}ms` };
+  }
+  if (failure) return { status: "spawn-error", text, ms, detail: `spawn-error: ${failure}` };
+  return { status: "text", text, ms };
+}
+
+export interface ReviewWithRetryOptions extends ReviewChildOptions {
+  /** 机械复验：返回非空字符串表示候选文件不合法（frontmatter 坏） */
+  recheck?: () => string | null;
+}
+
+export interface ReviewWithRetryOutcome {
+  result: ReviewResult;
+  attempts: number;
+  ms: number;
+  /** 每次尝试的结论摘要，写进 03-review.md 便于人工复盘 */
+  attemptsLog: string[];
+}
+
+/**
+ * 12.3 后处理 + 重试规则：结构不合格（invalid）重评一次，仍不合格就是 review_failed；
+ * 超时与 spawn 失败不重试（再来一次只是再赔 300 秒）。
+ */
+export async function reviewWithRetry(options: ReviewWithRetryOptions): Promise<ReviewWithRetryOutcome> {
+  const started = (options.now ?? Date.now)();
+  const attemptsLog: string[] = [];
+  let last: ReviewResult = { status: "invalid", blocking: [], detail: "not-run" };
+  let attempts = 0;
+  for (let round = 1; round <= 2; round += 1) {
+    attempts = round;
+    const outcome = await runReviewChild(options);
+    if (outcome.status !== "text") {
+      last = { status: "invalid", blocking: [], detail: outcome.detail ?? outcome.status };
+      attemptsLog.push(`第 ${round} 次：${last.detail}`);
+      break;
+    }
+    last = postProcessReview(outcome.text, { ...(options.recheck ? { recheck: options.recheck } : {}) });
+    attemptsLog.push(`第 ${round} 次：${last.status}${last.verdict ? `/${last.verdict}` : ""}${last.detail ? `（${last.detail}）` : ""}`);
+    if (last.status !== "invalid") break;
+  }
+  return { result: last, attempts, ms: (options.now ?? Date.now)() - started, attemptsLog };
+}

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

@@ -0,0 +1,83 @@
+/**
+ * 起评审督导进程：与复盘子进程同一次派发里、同一条「detached + unref」纪律。
+ *
+ * 为什么用 `process.execPath` 而不是 `pi`：督导本身是普通 node 脚本（只读产物、写 03-review.*），
+ * 评审才需要 pi。这样即使 `pi` 不可见也不影响督导先把 900 秒超时落成一条记录。
+ *
+ * 全局单飞闸在这里也拦一次：督导算第二个子进程，已有别的复盘在跑就不叠（用户 2026-11-08：
+ * 「每次最多一个复盘agent」）。与**自己**那条 run 的复盘子进程不冲突，靠 ignoreRunId 排除。
+ */
+import { spawn as nodeSpawn } from "node:child_process";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { patchRunRecordSync } from "./runs.ts";
+import { guardBusy } from "./single-flight.ts";
+import { spawnDetached } from "./spawn-plan.ts";
+import type { TelemetryWriter } from "./telemetry.ts";
+
+/** 督导脚本绝对路径：dispatch 与 shutdown-dispatch 两条路径共用 */
+export const SUPERVISOR_SCRIPT = fileURLToPath(new URL("./review-supervisor.ts", import.meta.url));
+
+/** 督导日志文件名：督导自己也可能静默死掉，日志跟子进程一样落到 run 目录 */
+export const SUPERVISOR_LOG = "supervisor.log";
+
+export interface SupervisorChild {
+  pid?: number;
+  unref?: () => void;
+}
+
+export type SupervisorSpawn = (command: string, args: string[], options: Record<string, unknown>) => SupervisorChild;
+
+export interface SpawnSupervisorOptions {
+  runDir: string;
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  /** "inherit" / 空 → 不传参，督导按默认模型评审 */
+  reviewModel?: string;
+  spawnFn?: SupervisorSpawn;
+  log?: (msg: string) => void;
+  /** 同一条 run 的会话 ID：busy 遥测要带它（缺省退化到 runId，事件不能丢） */
+  sessionId?: string;
+  telemetry?: TelemetryWriter;
+  /** pid 存活判定（单测注入；生产用默认 kill(pid,0)） */
+  alive?: (pid: number) => boolean;
+  /** 退出补发路径：主进程马上退，遥测只能同步写 */
+  sync?: boolean;
+}
+
+/** 返回 pid；被单飞闸挡住或起不来返回 null（只记日志，绝不抛到主会话） */
+export function spawnReviewSupervisor(options: SpawnSupervisorOptions): number | null {
+  const runId = path.basename(options.runDir);
+  const occupant = guardBusy({
+    evolutionDir: path.dirname(path.dirname(options.runDir)),
+    sessionId: options.sessionId ?? runId,
+    // 自己这条 run 的复盘子进程本来就该在跑，不能把自己当占用者
+    ignoreRunId: runId,
+    ...(options.telemetry ? { telemetry: options.telemetry } : {}),
+    ...(options.alive ? { alive: options.alive } : {}),
+    ...(options.sync === true ? { sync: true } : {}),
+    ...(options.log ? { log: options.log } : {}),
+  });
+  if (occupant) return null;
+
+  const env = { ...(options.env ?? process.env) };
+  // 督导自己不是 pi 子代理：把「别再采集」的标记去掉，避免它起评审子进程时语义混乱
+  delete env.SKILL_EVOLVE_CHILD;
+  const args = ["--experimental-strip-types", SUPERVISOR_SCRIPT, options.runDir];
+  if (options.reviewModel && options.reviewModel !== "inherit") args.push(options.reviewModel);
+  const spawnFn = options.spawnFn ?? (nodeSpawn as unknown as SupervisorSpawn);
+  try {
+    const child = spawnDetached(spawnFn, process.execPath, args, {
+      cwd: options.cwd,
+      env,
+      logFile: path.join(options.runDir, SUPERVISOR_LOG),
+    });
+    // 占用登记：督导 pid 写进同一条 run.json；它退出 / 失败时清成 null
+    if (child.pid) patchRunRecordSync(options.runDir, { supervisorPid: child.pid });
+    options.log?.(`[skill-evolve] 已起评审督导 pid ${child.pid ?? "未知"}（${runId}）`);
+    return child.pid ?? null;
+  } catch (error) {
+    options.log?.(`[skill-evolve] 评审督导启动失败：${String(error)}`);
+    return null;
+  }
+}

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

@@ -0,0 +1,267 @@
+/**
+ * 评审督导（设计稿 12）——独立 node 进程，由派发方在起复盘子进程的同一次派发里拉起。
+ *
+ * 为什么必须是独立进程而不是复盘 agent 自己评：复盘 agent 刚写完提案，让它评审等于自评，
+ * 而且它的上下文里全是自己的推理，评不出自己的错。这里只等产物落盘，再按固定模板另起评审子进程。
+ *
+ * 职责：
+ *   1. 轮询 `02-proposal.json`（默认 900s 超时 → 写 skipped/proposal-timeout）
+ *   2. 组装评审 prompt（只给硬约束 + diff + 改后全文 + 验收标准）
+ *   3. 起评审子进程（默认 300s 超时），invalid 重评一次
+ *   4. 代码后处理 + 机械复验（新增 P0 命中、candidate frontmatter 坏 → 一票 reject）
+ *   5. 写 `03-review.json` / `03-review.md`，更新 `run.json`
+ *
+ * 本进程不做 git 操作、不写 `.pi/skills`、不写别的 run 目录（闸 0 / 闸 1 的边界）。
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { pathToFileURL } from "node:url";
+import { loadHardRules, scanText, type CompiledRules, type HardRuleHit } from "./hard-rules.ts";
+import { buildReviewPrompt } from "./review-prompt.ts";
+import { classifyChange } from "./classify-action.ts";
+import { renderReviewMarkdown, stageModel, type ReviewRecord, type SupervisorStatus } from "./review-record.ts";
+import { reviewWithRetry, type ReviewSpawn } from "./review-run.ts";
+import { patchRunRecordSync } from "./runs.ts";
+import { applyUnifiedDiff } from "./diff-apply.ts";
+
+export const PROPOSAL_TIMEOUT_MS = 900_000;
+const PROPOSAL_POLL_MS = 2000;
+
+export interface ReviewSupervisorDeps {
+  runDir: string;
+  evolutionDir?: string;
+  env?: NodeJS.ProcessEnv;
+  log?: (msg: string) => void;
+  now?: () => number;
+  sleep?: (ms: number) => Promise<void>;
+  spawnFn?: ReviewSpawn;
+  /** 读文本；undefined = 文件不存在（单测注入） */
+  readText?: (file: string) => string | undefined;
+  writeText?: (file: string, text: string) => void;
+  /** 评审模型："inherit" 或 provider/model */
+  reviewModel?: string;
+  rules?: CompiledRules;
+  proposalTimeoutMs?: number;
+  reviewTimeoutMs?: number;
+  pollMs?: number;
+}
+
+export interface SupervisorOutcome {
+  status: SupervisorStatus;
+  record: ReviewRecord;
+  ms: number;
+}
+
+function defaultReadText(file: string): string | undefined {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return undefined;
+  }
+}
+
+/** 先写临时文件再 rename：督导被 SIGKILL 时不会留下半截 JSON */
+function defaultWriteText(file: string, text: string): void {
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, text, "utf8");
+  fs.renameSync(tmp, file);
+}
+
+interface ProposalMeta {
+  type: string;
+  skill: string;
+  diffFile?: string;
+  candidateFile?: string;
+}
+
+export function parseProposal(text: string | undefined): ProposalMeta | undefined {
+  if (!text) return undefined;
+  try {
+    const raw = JSON.parse(text) as Record<string, unknown>;
+    if (typeof raw.skill !== "string" || raw.skill.trim().length === 0) return undefined;
+    return {
+      type: typeof raw.type === "string" ? raw.type : "improve",
+      skill: raw.skill.trim(),
+      ...(typeof raw.diffFile === "string" ? { diffFile: raw.diffFile } : {}),
+      ...(typeof raw.candidateFile === "string" ? { candidateFile: raw.candidateFile } : {}),
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+/** 只查「新增」的 P0 命中：存量债不该拦住一次正当的文案改动 */
+export function newHardRuleHits(before: string, after: string, rules: CompiledRules, skill: string): HardRuleHit[] {
+  const key = (hit: HardRuleHit) => `${hit.ruleId}\u0000${hit.quote.trim()}`;
+  const known = new Set(scanText(before, rules.compiled, skill).map(key));
+  return scanText(after, rules.compiled, skill).filter((hit) => !known.has(key(hit)));
+}
+
+/** candidate 的最小 frontmatter 校验：独立进程里拿不到 loadSkillsFromDir，这是兜底 */
+export function checkCandidateFrontmatter(text: string): string | null {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(text);
+  if (!match) return "缺 frontmatter";
+  const front = match[1];
+  if (!/^name:\s*\S/m.test(front)) return "frontmatter 缺 name";
+  if (!/^description:\s*\S/m.test(front)) return "frontmatter 缺 description";
+  return null;
+}
+
+function cwdOf(runRaw: string | undefined): string {
+  if (runRaw) {
+    try {
+      const raw = JSON.parse(runRaw) as Record<string, unknown>;
+      if (typeof raw.cwd === "string" && raw.cwd.length > 0) return raw.cwd;
+    } catch {
+      // run.json 坏掉就退回当前工作目录，后面读不到原文会走「只有 diff 可信」的降级
+    }
+  }
+  return process.cwd();
+}
+
+/** 等提案文件出现；超时也再读一次（可能刚好落盘） */
+async function waitForProposal(
+  file: string,
+  deps: ReviewSupervisorDeps,
+  read: (file: string) => string | undefined,
+): Promise<string | undefined> {
+  const now = deps.now ?? Date.now;
+  const sleep = deps.sleep ?? ((ms: number) => new Promise<void>((resolve) => setTimeout(resolve, ms)));
+  const deadline = now() + (deps.proposalTimeoutMs ?? PROPOSAL_TIMEOUT_MS);
+  while (now() < deadline) {
+    const text = read(file);
+    if (text !== undefined) return text;
+    await sleep(deps.pollMs ?? PROPOSAL_POLL_MS);
+  }
+  return read(file);
+}
+
+function stamp(ts: number): { reviewedAt: number; reviewedAtIso: string } {
+  return { reviewedAt: ts, reviewedAtIso: new Date(ts).toISOString() };
+}
+
+export async function runReviewSupervisor(deps: ReviewSupervisorDeps): Promise<SupervisorOutcome> {
+  const now = deps.now ?? Date.now;
+  const started = now();
+  const read = deps.readText ?? defaultReadText;
+  const write = deps.writeText ?? defaultWriteText;
+  const log = deps.log ?? (() => {});
+  const runDir = path.resolve(deps.runDir);
+  const evolutionDir = deps.evolutionDir ?? path.resolve(runDir, "..", "..");
+  const runFile = path.join(runDir, "run.json");
+  const runRaw = read(runFile);
+  const proposerModel = stageModel(runRaw);
+  const reviewerModel = deps.reviewModel ?? "inherit";
+  const sameModel = proposerModel.length > 0 && proposerModel === reviewerModel;
+  const base = { reviewerModel, proposerModel, sameModel };
+
+  const proposalText = await waitForProposal(path.join(runDir, "02-proposal.json"), deps, read);
+  const proposal = parseProposal(proposalText);
+  if (!proposal) {
+    const record: ReviewRecord = {
+      ...base,
+      status: "skipped",
+      reason: proposalText === undefined ? "proposal-timeout" : "proposal-unreadable",
+      blocking: [],
+      ...stamp(now()),
+    };
+    write(path.join(runDir, "03-review.json"), `${JSON.stringify(record, null, 2)}\n`);
+    log(`[skill-evolve] 评审跳过：${record.reason}（${path.basename(runDir)}）`);
+    return { status: "skipped", record, ms: now() - started };
+  }
+
+  const cwd = cwdOf(runRaw);
+  const rules = deps.rules ?? loadHardRules(path.join(evolutionDir, "rules", "hard-rules.json"));
+  const target = path.join(cwd, ".pi", "skills", proposal.skill, "SKILL.md");
+  const candidateFile = path.join(runDir, proposal.candidateFile ?? path.posix.join("candidate", proposal.skill, "SKILL.md"));
+  const diffFile = proposal.diffFile ?? "02-proposal.diff";
+  const diffText = read(path.join(runDir, diffFile)) ?? "";
+  // 改动前全文：优先 candidate（新建技能没有基线文件），其次工作区里当前的技能
+  const beforeText = read(candidateFile) ?? read(target) ?? "";
+  const applied = diffText.length > 0 ? applyUnifiedDiff(beforeText, diffText) : null;
+  const afterText = applied !== null && applied.ok ? applied.text : beforeText;
+  const recheck = (): string | null => {
+    if (proposal.type === "create") return checkCandidateFrontmatter(read(candidateFile) ?? "");
+    const hits = newHardRuleHits(beforeText, afterText, rules, proposal.skill);
+    return hits.length > 0 ? `新增 P0 命中 ${hits[0].ruleId}（${hits[0].skill}:${hits[0].line}）` : null;
+  };
+
+  const prompt = buildReviewPrompt({
+    skillName: proposal.skill,
+    skillText: afterText,
+    diffApplied: applied !== null && applied.ok,
+    diff: diffText,
+    hardRules: rules.compiled,
+  });
+  const outcome = await reviewWithRetry({
+    prompt,
+    cwd,
+    model: reviewerModel,
+    ...(deps.env ? { env: deps.env } : {}),
+    ...(deps.spawnFn ? { spawnFn: deps.spawnFn } : {}),
+    ...(deps.now ? { now: deps.now } : {}),
+    ...(deps.sleep ? { sleep: deps.sleep } : {}),
+    ...(deps.reviewTimeoutMs ? { timeoutMs: deps.reviewTimeoutMs } : {}),
+    ...(deps.log ? { log: deps.log } : {}),
+    recheck,
+  });
+
+  const verdict = outcome.result.verdict;
+  // invalid = 评审输出不可用（重评也没救）；reject 是机械复验的定论，按「被否决」记，不算失败
+  const status: SupervisorStatus =
+    outcome.result.status === "invalid" ? "review_failed" : verdict === "pass" ? "reviewed" : "rejected";
+  const record: ReviewRecord = {
+    ...base,
+    status,
+    ...(verdict ? { verdict } : {}),
+    blocking: outcome.result.blocking,
+    ...(outcome.result.notes ? { notes: outcome.result.notes } : {}),
+    action: classifyChange({ diffText, proposalType: proposal.type, skill: proposal.skill }).level,
+    attempts: outcome.attempts,
+    ...(outcome.result.detail ? { detail: outcome.result.detail } : {}),
+    ...stamp(now()),
+  };
+  write(path.join(runDir, "03-review.json"), `${JSON.stringify(record, null, 2)}\n`);
+  write(path.join(runDir, "03-review.md"), renderReviewMarkdown(record, proposal.skill));
+
+  if (runRaw) {
+    try {
+      const runJson = JSON.parse(runRaw) as Record<string, unknown>;
+      runJson.status = status === "reviewed" ? "reviewed" : status === "rejected" ? "rejected" : "review_failed";
+      runJson.review = { status, verdict: verdict ?? null, action: record.action, reviewerModel, proposerModel, sameModel };
+      write(runFile, `${JSON.stringify(runJson, null, 2)}\n`);
+    } catch (error) {
+      log(`[skill-evolve] 评审结论写不回 run.json：${(error as Error).message}`);
+    }
+  }
+  log(`[skill-evolve] 评审完成：${status}${verdict ? `/${verdict}` : ""}（${path.basename(runDir)}，${outcome.attempts} 次）`);
+  return { status, record, ms: now() - started };
+}
+
+async function main(): Promise<void> {
+  const runDir = process.argv[2];
+  if (!runDir) {
+    console.error("[skill-evolve] 用法：review-supervisor.ts <runDir> [reviewModel]");
+    process.exitCode = 2;
+    return;
+  }
+  try {
+    const outcome = await runReviewSupervisor({
+      runDir,
+      ...(process.argv[3] ? { reviewModel: process.argv[3] } : {}),
+      log: (msg) => console.error(msg),
+    });
+    process.exitCode = outcome.status === "review_failed" ? 1 : 0;
+  } finally {
+    // 退出即释放单飞占用位：留着旧 pid 会被系统复用的 pid 假挡住后续派发
+    patchRunRecordSync(runDir, { supervisorPid: null });
+  }
+}
+
+const invokedDirectly = process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href;
+if (invokedDirectly) {
+  void main().catch((error: Error) => {
+    console.error(`[skill-evolve] 评审督导异常：${error.message}`);
+    process.exitCode = 1;
+  });
+}

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

@@ -0,0 +1,116 @@
+/**
+ * 一轮（一条用户消息）内的曝光 / 加载状态机：曝光 → 待确认 → 回填 → 结算。
+ *
+ * 单独成文件是因为它只有内存状态、不碰派发与文件：演进层把「什么时候动手」留在自己那儿，
+ * 这里只负责把 pi 的事件流变成「本轮曝光了几个、真加载了几个、谁没被加载」。
+ */
+import { createHash } from "node:crypto";
+import { detectFromBash, detectFromRead, type SkillHit } from "./detect.ts";
+import type { TelemetryInput, TelemetrySkill } from "./telemetry.ts";
+
+export interface RoundAdvertisedInput {
+  sessionId: string;
+  cwd: string;
+  prompt: string;
+  skills: TelemetrySkill[];
+  activeTools: string[];
+}
+
+export interface RoundResult {
+  /** 真被曝光（disabled 的不算，它们没进 prompt）的技能 */
+  exposed: TelemetrySkill[];
+  missed: string[];
+  activeTools: string[];
+}
+
+export interface RoundTracker {
+  recordAdvertised(input: RoundAdvertisedInput): void;
+  noteToolCall(input: { sessionId: string; toolCallId: string; toolName: string; input: Record<string, unknown> }): void;
+  resolveToolResult(input: { sessionId: string; toolCallId: string; isError: boolean }): void;
+  /** 结算并清空本轮；没有本轮 / 会话不匹配 / 零曝光时返回 null（零曝光既不记未命中也不派生） */
+  settle(sessionId: string): RoundResult | null;
+}
+
+interface RoundState {
+  sessionId: string;
+  skills: TelemetrySkill[];
+  loaded: Set<string>;
+  /** toolCallId → 该次调用碰到的技能，等 tool_result 回填 ok/failed */
+  pending: Map<string, SkillHit[]>;
+  activeTools: string[];
+}
+
+function hashOf(text: string): string {
+  return createHash("sha256").update(text).digest("hex").slice(0, 16);
+}
+
+export function createRoundTracker(options: {
+  cwd: string;
+  append: (event: TelemetryInput) => void;
+}): RoundTracker {
+  let round: RoundState | null = null;
+
+  const recordAdvertised: RoundTracker["recordAdvertised"] = (input) => {
+    round = { sessionId: input.sessionId, skills: input.skills, loaded: new Set(), pending: new Map(), activeTools: input.activeTools };
+    options.append({
+      kind: "advertised",
+      sessionId: input.sessionId,
+      cwd: input.cwd,
+      promptHash: hashOf(input.prompt),
+      promptExcerpt: input.prompt.slice(0, 200),
+      skills: input.skills,
+      activeTools: input.activeTools,
+    });
+  };
+
+  const noteToolCall: RoundTracker["noteToolCall"] = (input) => {
+    if (!round || round.sessionId !== input.sessionId) return;
+    const hits: SkillHit[] = [];
+    if (input.toolName === "read") {
+      const hit = detectFromRead(String(input.input.path ?? ""), options.cwd);
+      if (hit) hits.push(hit);
+    } else if (input.toolName === "bash") {
+      hits.push(...detectFromBash(String(input.input.command ?? "")));
+    }
+    // 路径规则只能判定「这看起来像技能文件」；只有本轮真被曝光的技能才算加载证据，
+    // 否则仓库里任何一个 <目录>/SKILL.md 都会被错记成一次加载。
+    const advertised = new Set(round.skills.map((skill) => skill.name));
+    const owned = hits.filter((hit) => advertised.has(hit.skill));
+    if (owned.length > 0) round.pending.set(input.toolCallId, owned);
+  };
+
+  const resolveToolResult: RoundTracker["resolveToolResult"] = (input) => {
+    if (!round || round.sessionId !== input.sessionId) return;
+    const hits = round.pending.get(input.toolCallId);
+    if (!hits) return;
+    round.pending.delete(input.toolCallId);
+    for (const hit of hits) {
+      options.append({
+        kind: input.isError ? "failed" : "loaded",
+        sessionId: input.sessionId,
+        skill: hit.skill,
+        how: hit.how,
+        ok: !input.isError,
+        raw: hit.raw,
+      });
+      if (!input.isError) round.loaded.add(hit.skill);
+    }
+  };
+
+  const settle: RoundTracker["settle"] = (sessionId) => {
+    const current = round;
+    round = null; // 一轮只结算一次，杜绝同一个 round 被重复记未命中
+    if (!current || current.sessionId !== sessionId) return null;
+    // 门禁①：本轮没有任何技能曝光（没走到技能系统），既不算未命中也不派生
+    if (current.skills.length === 0) return null;
+
+    // disabled 的技能根本没进 prompt，不算「曝光未命中」，留待归因阶段按 A 类处理
+    const exposed = current.skills.filter((skill) => !skill.disabled);
+    const missed = exposed.filter((skill) => !current.loaded.has(skill.name)).map((skill) => skill.name);
+    options.append({ kind: "pending", sessionId, exposed: exposed.length, missed: missed.length });
+    for (const name of missed) options.append({ kind: "missed", sessionId, skill: name });
+    return { exposed, missed, activeTools: current.activeTools };
+  };
+
+  return { recordAdvertised, noteToolCall, resolveToolResult, settle };
+}

package/extensions/skill-evolve/lib/run-watch.ts

@@ -0,0 +1,34 @@
+/**
+ * 盯着复盘子进程收尾：非正常退出就把 run 标 abandoned，无论成败都释放全局锁。
+ *
+ * 单独一个文件是因为 dispatch.ts 已经贴着 300 行闸门，而这段逻辑与派发主流程无耦合：
+ * 它只关心「子进程死了没有」，由调用方把释放锁的回调传进来。
+ */
+import { markRunAbandoned } from "./runs.ts";
+import type { SpawnedChild } from "./spawn-plan.ts";
+import type { MutationQueue } from "./telemetry.ts";
+
+export interface WatchRunDeps {
+  runDir: string;
+  queue: MutationQueue;
+  log: (msg: string) => void;
+  /** 子进程结束（无论成败）后调用：派发方用它释放全局锁 */
+  onExit: () => Promise<void>;
+}
+
+export function watchRunChild(child: SpawnedChild, deps: WatchRunDeps): void {
+  let done = false;
+  const finish = (reason: string | null): void => {
+    if (done) return;
+    done = true;
+    void (async () => {
+      if (reason) {
+        deps.log(`[skill-evolve] 复盘子进程异常退出：${reason}`);
+        await markRunAbandoned(deps.runDir, reason, deps.queue, deps.log);
+      }
+      await deps.onExit();
+    })();
+  };
+  child.once("exit", (code) => finish(code === 0 ? null : `exit ${String(code)}`));
+  child.once("error", (error) => finish(`spawn-error: ${String(error)}`));
+}