@zhushanwen/subagent-core 0.2.0 → 0.5.1

package/src/orchestration/args-validator.ts

@@ -58,6 +58,57 @@ function formatMessage(name: string, errors: readonly unknown[]): string {
   );
 }
 
+// ── validateRunArgs 阶段 helper（按 预处理/编译 提取，主函数只留编排） ────
+
+/** schema.properties 提取（畸形/缺失 → {}，null-scan 在空 properties 上安全退化）。 */
+function extractSchemaProperties(schema: Record<string, unknown>): Record<string, unknown> {
+  return schema.properties !== null && typeof schema.properties === "object"
+    ? (schema.properties as Record<string, unknown>)
+    : {};
+}
+
+/** 单个 property 声明是否 nullable（type 含 "null" 或 type === "null"）。 */
+function isNullableProp(prop: unknown): boolean {
+  if (prop === null || typeof prop !== "object") return false;
+  const propType = (prop as Record<string, unknown>).type;
+  return Array.isArray(propType)
+    ? (propType as unknown[]).includes("null")
+    : propType === "null";
+}
+
+/**
+ * null-scan：null 值视为缺失（coerceTypes 会把 null→"" 放行 required，绕过 fail-fast）。
+ * 只删 schema 未声明 nullable 的键——type 含 "null"（如 ["string","null"]）的合法 null
+ * 输入保留（m3 exec-review M1 探针实证：全键删除会拒掉 nullable required 的合法值）。
+ */
+function deleteNonNullableNullArgs(
+  args: Record<string, unknown>,
+  schema: Record<string, unknown>,
+): void {
+  const properties = extractSchemaProperties(schema);
+  for (const key of Object.keys(args)) {
+    if (args[key] !== null) continue;
+    if (!isNullableProp(properties[key])) delete args[key];
+  }
+}
+
+/** ajv 编译（畸形 schema → 结构化 ArgsValidationError，不泄漏原始 throw）。 */
+function compileSchema(
+  parameters: Record<string, unknown>,
+  scriptName: string,
+): ReturnType<Ajv["compile"]> {
+  try {
+    return ajv.compile(parameters);
+  } catch (err) {
+    // 真畸形 schema（如 type:'not-a-type'）→ 结构化 ArgsValidationError，不泄漏原始 throw
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new ArgsValidationError(
+      scriptName,
+      `Workflow '${scriptName}' has an invalid parameter schema: ${detail}. Read the workflow script file (location from <available_workflows>) to inspect it.`,
+    );
+  }
+}
+
 /**
  * 校验 spec.parameters（JSON Schema draft-07）对 spec.args 的约束。
  *
@@ -79,38 +130,9 @@ export function validateRunArgs(spec: RunSpec): void {
     );
   }
 
-  // null-scan：null 值视为缺失（coerceTypes 会把 null→"" 放行 required，绕过 fail-fast）。
-  // 只删 schema 未声明 nullable 的键——type 含 "null"（如 ["string","null"]）的合法 null
-  // 输入保留（m3 exec-review M1 探针实证：全键删除会拒掉 nullable required 的合法值）。
-  const schema = parameters as Record<string, unknown>;
-  const properties =
-    schema.properties !== null && typeof schema.properties === "object"
-      ? (schema.properties as Record<string, unknown>)
-      : {};
-  for (const key of Object.keys(args)) {
-    if (args[key] !== null) continue;
-    const prop = properties[key];
-    let isNullable = false;
-    if (prop !== null && typeof prop === "object") {
-      const propType = (prop as Record<string, unknown>).type;
-      isNullable = Array.isArray(propType)
-        ? (propType as unknown[]).includes("null")
-        : propType === "null";
-    }
-    if (!isNullable) delete args[key];
-  }
+  deleteNonNullableNullArgs(args, parameters);
 
-  let validate: ReturnType<Ajv["compile"]>;
-  try {
-    validate = ajv.compile(parameters);
-  } catch (err) {
-    // 真畸形 schema（如 type:'not-a-type'）→ 结构化 ArgsValidationError，不泄漏原始 throw
-    const detail = err instanceof Error ? err.message : String(err);
-    throw new ArgsValidationError(
-      scriptName,
-      `Workflow '${scriptName}' has an invalid parameter schema: ${detail}. Read the workflow script file (location from <available_workflows>) to inspect it.`,
-    );
-  }
+  const validate = compileSchema(parameters, scriptName);
 
   if (!validate(args)) {
     throw new ArgsValidationError(

package/src/orchestration/execute-agent-call.ts

@@ -8,16 +8,23 @@
  * 职责：
  * - 重试：3 次 + 指数退避（BACKOFF_MS = [1000, 2000, 4000]）
  * - 预算：超限不重试（直接 markDone failed）
- * - stale-context：不重试（直接 markDone failed）
- * - [MF-1] 确定性 schema 失败：不重试（直接 markDone failed）
+ * - stale-context（result.failureKind="stale_context"）：不重试（直接 markDone failed）
+ * - [MF-1] 确定性 schema 失败（result.failureKind="schema_deterministic"）：不重试
+ *   （直接 markDone failed）
  * - 成功：consume usage + incrementCallCount + markDone + trace.update(completed)
  *
+ * [D5-③ 结构化分诊] 失败分诊读 AgentResult.failureKind 字段（产出侧唯一识别点 =
+ * execution/engine/engines/pi/output-collector.ts 的 classifyFailureKind，词表归属
+ * 见其文件头）。本模块不再扫 error 文案子串——**语义守恒（r1 MF4）**：unknown
+ * （含字段缺省）= 可重试，保持收敛前的默认重试语义；仅 stale_context（不重试、
+ * 换参重发场景由调用方编排）与 schema_deterministic 维持特判。
+ *
  * 关键设计：
  * - **usage 透传**：result.usage 直接交给 budget.consume，加权由 Budget 内部的权重常量
- * 处理（见 budget.ts）。此函数不再做 usage 形状的改写。
+ *   处理（见 budget.ts）。此函数不再做 usage 形状的改写。
  * - **参数显式化**：runner 直接传入（而非 ctx.getRun(runId).pool），无 runId 查找 / pool 守卫。
  * - **stale-state 检查**：signal.aborted 时早返回。WorkflowRun 状态由调用方 lifecycle
- * 持有，executeAgentCall 只关心单次 call 生命周期。
+ *   持有，executeAgentCall 只关心单次 call 生命周期。
  *
  * 层归属：Engine。零 infra 依赖（runner 是 AgentRunner port，budget/trace/call 是 Engine 模型）。
  *
@@ -41,69 +48,6 @@ const BACKOFF_EXPONENT_BASE = 2;
 /** 最大尝试次数（含首次）：initial + 2 retries = 3。 */
 const MAX_ATTEMPTS = 3;
 
-/**
- * Stale context 检测模式（P1-5；W4b 对齐 pi 0.84.x 真实文案）。
- *
- * pi session context 被 compact/cancel 时报告的模式。这种情况下重试无意义——
- * 同样的 call 会再次失败。直接 markDone failed 终止单次调用。
- *
- * W4b：原 "stale context"/"stalecontext" 与 pi 真实文案零匹配（真实文案为
- * "This extension ctx is stale after session replacement or reload. ..."——
- * runner.ts:544（dist runner.js:352），词序是 "ctx is stale" 而非 "stale context"），stale 分诊对
- * 真实文案失效。现对齐：
- * - "ctx is stale"：真实文案核心子串（词序修正）
- * - "stale after session replacement"：scheduler 已验证 marker（runtime.ts
- *   STALE_CTX_MARKER，同文案锚定）
- * - "context canceled"/"aborted"：保留——abort 族错误同样不重试（signal.aborted
- *   分支的先行分诊，防边界竞态漏网），删除会放宽重试语义。
- */
-export const STALE_CONTEXT_PATTERNS = [
-  "ctx is stale",
-  "stale after session replacement",
-  "context canceled",
-  "aborted",
-] as const;
-
-/**
- * 判断错误信息是否表示 stale/canceled pi session context。
- * 命中时不重试——重试只会再次失败（P1-5）。
- */
-export function isStaleContextErrorMsg(msg: string | undefined): boolean {
-  if (!msg) return false;
-  const lower = msg.toLowerCase();
-  return STALE_CONTEXT_PATTERNS.some((p) => lower.includes(p));
-}
-
-/**
- * [MF-1] 确定性 schema 失败标记（error 文本前缀，产出方 = output-collector 的
- * describeMissingParsedOutput）。
- *
- * 标记 SSOT 放本模块（与 STALE_CONTEXT_PATTERNS 同布局：orchestration 持表、
- * execution 值引用；反向引用会形成 execute-agent-call → output-collector →
- * execute-agent-call 运行时循环）。
- *
- * 标记词逐字核对不命中 STALE_CONTEXT_PATTERNS 任一 pattern 与
- * isStaleContextErrorMsg 的子串匹配（否则归因 error 被误诊 stale-context，
- * 虽然同样不重试但归因语义被污染；output-collector.test 有交叉锁定）。
- *
- * 三态可重试性矩阵（F-1 归因）：
- * | 归因态                     | 带本标记 | 可重试性 | 理由 |
- * |----------------------------|---------|---------|------|
- * | ① 从未调用 SO tool         | 是      | 不可重试 | 缺 extension 是环境确定性（C1 安装盲区），同环境重试必同结果 |
- * | ② SO 调用 isError（gate 终止/不可满足 schema） | 是 | 不可重试 | 同 schema 重试必同结果（第五轮实测：3 attempts/4 子进程/235s 纯烧钱） |
- * | ③ 调用过但无 details        | 否      | 可重试   | 可能瞬态（details 提取/序列化异常），保留既有重试语义 |
- */
-export const DETERMINISTIC_SCHEMA_FAILURE_PREFIX = "Structured output failed deterministically:";
-
-/**
- * [MF-1] 判断错误信息是否为确定性 schema 失败（命中标记前缀）。
- * 命中时不重试——同 schema 重试必同结果（矩阵见 DETERMINISTIC_SCHEMA_FAILURE_PREFIX）。
- */
-export function isDeterministicSchemaFailureMsg(msg: string | undefined): boolean {
-  if (!msg) return false;
-  return msg.includes(DETERMINISTIC_SCHEMA_FAILURE_PREFIX);
-}
-
 // ── 内部 helper ──────────────────────────────────────────────
 
 /**
@@ -124,7 +68,7 @@ function backoffDelay(retryIndex: number): number {
  * rebuild 竞态窗口中，重跑 dispatch 已 append 同 stepIndex 新节点，旧代际
  * finalize 的 update 会命中新节点，TUI/中间快照短暂可见错误终态。正确性论证：
  * 运行期 calls Map 写点仅 discardInFlightCalls 的 delete 与 dispatchAgentCall 的
- * set 两族（error-recovery.ts isOrphanedCall 文档注释既定），故实例不等 ⟺ 本
+ * set 两族（worker-message-pump.ts isOrphanedCall 文档注释既定），故实例不等 ⟺ 本
  * finalize 属于被丢弃/被替换的旧代际——与 dispatch 层 .then/.catch 守卫
  * （S7-second 修复，8353f6b60）同一判定语义，本守卫只是把它前移到 trace.update
  * 之前。markDone 与 sessionId/sessionFile 同步保留（markDone 在孤儿实例上无害，
@@ -203,44 +147,46 @@ export async function executeAgentCall(
 
   const result = await runner.run(call.opts, signal, onEvent, stream);
 
- // 累加 usage（加权由 budget.consume 内部按权重常量处理，见 budget.ts）
+  // 累加 usage（加权由 budget.consume 内部按权重常量处理，见 budget.ts）
   if (result.usage) {
     budget.consume(result.usage);
   }
 
- // stale-context：不重试（P1-5）
-  if (result.error !== undefined && isStaleContextErrorMsg(result.error)) {
+  // stale-context（D5-③ 结构化分诊：读 failureKind 字段，词表识别在产出侧
+  // output-collector）：不重试（P1-5）
+  if (result.error !== undefined && result.failureKind === "stale_context") {
     finalizeCall(call, result, trace, isOrphaned);
     budget.incrementCallCount();
     return;
   }
 
- // [MF-1] 确定性 schema 失败：不重试（gate 终止/不可满足 schema 同 schema 重试必同
- // 结果——重试纯烧钱；三态可重试性矩阵见 DETERMINISTIC_SCHEMA_FAILURE_PREFIX）
-  if (result.error !== undefined && isDeterministicSchemaFailureMsg(result.error)) {
+  // [MF-1] 确定性 schema 失败（failureKind="schema_deterministic"）：不重试
+  // （gate 终止/不可满足 schema 同 schema 重试必同结果——重试纯烧钱；三态矩阵
+  // 见产出侧 output-collector 的确定性失败标记注释）
+  if (result.error !== undefined && result.failureKind === "schema_deterministic") {
     finalizeCall(call, result, trace, isOrphaned);
     budget.incrementCallCount();
     return;
   }
 
- // signal 已 abort：调用方终止，不重试（避免无意义的递归）
+  // signal 已 abort：调用方终止，不重试（避免无意义的递归）
   if (signal.aborted) {
     finalizeCall(call, result, trace, isOrphaned);
     budget.incrementCallCount();
     return;
   }
 
- // 预算超限：不重试（重试只会突破预算且无意义）
+  // 预算超限：不重试（重试只会突破预算且无意义）
   if (result.error !== undefined && budget.isExceeded()) {
     finalizeCall(call, result, trace, isOrphaned);
     budget.incrementCallCount();
     return;
   }
 
- // 可重试失败：退避后递归
+  // 可重试失败：退避后递归
   if (result.error !== undefined && call.attempts < MAX_ATTEMPTS) {
     await delay(backoffDelay(call.attempts));
- // 退避期间 signal 可能 abort
+    // 退避期间 signal 可能 abort
     if (signal.aborted) {
       finalizeCall(call, result, trace, isOrphaned);
       budget.incrementCallCount();
@@ -250,7 +196,7 @@ export async function executeAgentCall(
     return;
   }
 
- // 终态（成功或达到重试上限的失败）
+  // 终态（成功或达到重试上限的失败）
   finalizeCall(call, result, trace, isOrphaned);
   budget.incrementCallCount();
 }

package/src/orchestration/file-run-store.ts

@@ -0,0 +1,327 @@
+// src/orchestration/file-run-store.ts
+//
+// RunStore port 的通用文件实现（D2 设计件——zsw 回接 host-surface 单元）。
+//
+// 为什么需要它：pi 壳的 JsonlRunStore 深耦合 pi session（appendEntry /
+// sessionManager，经 pi SDK 落盘 session JSONL），zcode 侧宿主没有这两个设施，
+// 无法复用。RunStore port 早在 ports.ts 定义却只有 pi 一份 Infra 实现——本文件
+// 补上「宿主无关」的第二份实现，双宿主的 workflow state 持久化从此同源（消灭
+// 失败模式 B：行为不一致各自修）。
+//
+// 落盘布局：<dataRoot>/workflow-state/<runId>.jsonl（D2 规定，与 pi 壳
+// <sessionDir>/workflow-state/<runId>.jsonl 同名分量、锚点不同：pi 锚 session，
+// 本实现锚宿主数据根——zcode 宿主无 session dir 概念，daemon 重启后按 dataRoot
+// 重水合孤儿 run）。
+//
+// dataRoot 通道选型：直接走 getHostServices().dataRoot()（core/host-services.ts），
+// 不用 getEngineDataDir（engine/common/data-dir.ts）——后者是引擎 journal/隔离池
+// 通道，带 XYZ_AGENT_DATA_DIR env 优先 + warn-once 语义（xyz-agent 宿主注入专用）；
+// workflow run 快照是宿主编排状态，语义归属宿主数据根本身，宿主 configureCore
+// 注入什么就落什么，不引入第二条 env 覆盖链。
+
+import { appendFile, mkdir, readdir, readFile, stat, unlink } from "node:fs/promises";
+import { join } from "node:path";
+
+import { getHostServices } from "../core/host-services.ts";
+import { getLogger } from "../core/logger.ts";
+import type { RunStore } from "./models/ports.ts";
+import { WorkflowRun } from "./models/workflow-run.ts";
+import { SNAPSHOT_VERSION, fromRunSnapshot, toRunSnapshot } from "./run-snapshot.ts";
+
+const logger = getLogger("file-run-store");
+
+/** run 状态目录名（<dataRoot> 下的固定分量）。 */
+const STATE_DIR_NAME = "workflow-state";
+
+// ── 磁盘保留（C1，语义对齐 pi jsonl-run-store mtime 裁剪） ─────────
+
+/** run state 文件名 glob：runId 形如 `wf-<ts>-<rand>`（lifecycle.ts 生成），只删命中者。
+ *  同目录可能存在的非 state 文件永不碰（对齐 pi STATE_FILE_GLOB）。 */
+const STATE_FILE_GLOB = /^wf-.*\.jsonl$/;
+
+/**
+ * 磁盘保留默认上限（OR-5 跨 run 保留修复）：envName 通道在 env 未设/空时生效。
+ *
+ * OR-5 将「STATE_MAX_RUNS opt-in 默认关」（无界累积）改为默认开：跨 run state
+ * 文件按 mtime 裁剪到本上限。取值 50 是无真实 run 体积分布数据下的保守值
+ * （设计 §11-4：标定待 S-A 验收后复核）——偏大不碍事（有界即达标），偏小会
+ * 误删仍被引用的 run 缓存，故取保守端。env 显式设置（有效正数）优先于本值；
+ * 显式非法值是 opt-out 通道（不清理，见 pruneStateFilesBeyondCap）。
+ */
+export const DEFAULT_STATE_MAX_RUNS = 50;
+
+// ── save 节流（OR-5 单 run 快照 O(n²) 主修） ──────────────────
+
+/**
+ * 同一 run 两次快照落盘的最小间隔（ms）。OR-5 单 run O(n²) 主修参数：现状每
+ * 次 save 都 append 全量快照（快照体积 O(calls) × save 次数 O(calls)），节流后
+ * 落盘次数有界为 ceil(run 时长 / 本间隔)（§11-4 量级推演见 impl-plan 偏差登记：
+ * 100-call run 从 ~200 次落盘 / ~50MB 降到 ~17 次 / ~8MB，增量 append diff 需
+ * 改造两宿主共享 codec（基线+delta 行 + loadAll 重放 + 版本兼容），收益不抵
+ * 复杂度，节流即终案）。取值对齐 jsonl-run-store 去抖同款考量：agent-call 间隔
+ * 秒级，60s 窗口把快照次数压到与「分钟级 run 时长」同量级，又不让崩溃窗口
+ * （未落盘的 running 尾部丢失，等价崩溃链由恢复路径收编）超出分钟级。
+ */
+export const DEFAULT_SAVE_MIN_INTERVAL_MS = 60_000;
+
+/** FileRunStore 构造参数（全部可选；缺省即生产形态）。 */
+export interface FileRunStoreOptions {
+  /**
+   * save 节流最小间隔（ms）；0 = 禁用节流（每次 save 都落盘）。缺省
+   * {@link DEFAULT_SAVE_MIN_INTERVAL_MS}。测试经此注入小窗口（fake timers 推进）。
+   */
+  saveMinIntervalMs?: number;
+}
+
+/** Node fs 错误 code 判定（ENOENT = 路径不存在，并发删除场景；对齐 pi isEnoentError）。 */
+function isEnoentError(err: unknown): boolean {
+  return typeof err === "object" && err !== null && "code" in err &&
+    (err as { code?: unknown }).code === "ENOENT";
+}
+
+// ── 快照形状 / 序列化 / 重水合 ────────────────────────────────
+//
+// 投影与版本衔接语义收敛于 ./run-snapshot.ts 单源 codec（下沉收口 D4/U8）：
+// 本 store 只保留 IO 策略（append-only + 从尾向头取最后有效行）。版本衔接的
+// 宿主侧职责（D4 裁决②③，见 parseLine）：「缺 v 宽容读」预处理与「版本不
+// 匹配 warn 可见性」在此实现——不内聚进 codec，保 pi 侧「v1 存量静默跳过」
+// 语义不被宽容化误读。
+
+// ── FileRunStore ────────────────────────────────────────────
+
+/**
+ * RunStore port 的宿主无关文件实现（port 见 models/ports.ts）。
+ *
+ * - save：append-only + 节流——快照行仍全量（崩溃时旧快照仍在，loadAll 取最后
+ *   一条有效行恢复到最后一致状态），但同一 running run 两次落盘有最小间隔
+ *   （OR-5 ⑥a：节流前每次状态变更都 append 全量快照，快照体积 O(calls) ×
+ *   save 次数 O(calls) = 单 run 磁盘 O(n²)；节流参数与语义见 save 注释）。
+ * - loadAll：扫 <dataRoot>/workflow-state/*.jsonl，每文件从尾向头取第一条形状
+ *   有效的快照行；损坏行（JSON.parse 失败 / 形状校验不过 / 版本不匹配）跳过并
+ *   warn——单行损坏不拖垮整个 run 的恢复（与 pi 壳 kill-9 恢复同容忍度）。
+ *   版本衔接（快照 codec 归 run-snapshot.ts 单源，D4）：存量无 v 行按当前版本
+ *   宽容读、写入恒补 v、v 不匹配跳过 + warn（三裁决明细见 parseLine 注释）。
+ * - stateFilePath：纯路径计算（<dataRoot>/workflow-state/<runId>.jsonl），不建目录。
+ *
+ * 未 configureCore 即 save/loadAll 会抛 core_host_not_configured（dataRoot 端口
+ * 语义，host-services.ts §3.4）——宿主壳必须在初始化最早期注入。
+ */
+export class FileRunStore implements RunStore {
+  /** run 状态目录绝对路径（dataRoot 每次现取——宿主覆盖配置即刻生效，对齐
+   *  data-dir.ts「不缓存路径防测试/宿主切换读到旧值」先例）。 */
+  private stateDir(): string {
+    return join(getHostServices().dataRoot(), STATE_DIR_NAME);
+  }
+
+  /** save 节流最小间隔（ms），0 = 禁用。 */
+  private readonly saveMinIntervalMs: number;
+  /**
+   * per-runId 上次实际落盘时刻（节流判据）。终态落盘成功即删（终态后 runId 不再
+   * save）；残留条目只出现在「running 中 run 消失（崩溃/宿主弃用）」场景，单条
+   * ~100B 可忽略（对齐 jsonl-run-store chains「每 runId 残留 settled Promise」
+   * 的取舍先例）。时间源 Date.now()（fake timers 下可推进，测试友好）。
+   */
+  private readonly lastSavedAt = new Map<string, number>();
+
+  constructor(opts?: FileRunStoreOptions) {
+    this.saveMinIntervalMs = Math.max(0, opts?.saveMinIntervalMs ?? DEFAULT_SAVE_MIN_INTERVAL_MS);
+  }
+
+  stateFilePath(runId: string): string {
+    return join(this.stateDir(), `${runId}.jsonl`);
+  }
+
+  /**
+   * 快照落盘（OR-5 ⑥a 节流后）：
+   * - 首写（该 runId 尚无落盘记录）永不节流——保证新 run 至少一条快照，
+   *   loadAll 重水合可发现；
+   * - 终态（status 非 running）永不节流——最终状态必落盘，末行即终态快照；
+   * - running 中间态距上次落盘不足 {@link saveMinIntervalMs} → 跳过本次 append
+   *   （状态仍在调用方内存 runs Map，下次落盘带全量最新快照；本文件最后一条
+   *   快照因此最多落后真实状态一个节流窗口——崩溃语义与 jsonl-run-store 去抖
+   *   同源：未落盘的 running 尾部丢失，等价崩溃链由恢复路径收编）。
+   *
+   * 节流判据在落盘成功后才更新（IO 失败不吞下一次重试机会）。
+   */
+  async save(run: WorkflowRun): Promise<void> {
+    const isTerminal = run.state.status !== "running";
+    const now = Date.now();
+    const last = this.lastSavedAt.get(run.runId);
+    if (!isTerminal && last !== undefined && now - last < this.saveMinIntervalMs) {
+      return; // 节流窗口内：跳过本次全量快照 append
+    }
+    // mkdir recursive 每次 save 前执行：幂等零成本（目录已存在时仅一次 stat），
+    // 且免「构造时预建」——构造时建会在宿主尚未 configureCore 的窗口抛错。
+    await mkdir(this.stateDir(), { recursive: true });
+    // toRunSnapshot 补 v 字段（D4 裁决②写入侧）+ strip live 落盘
+    const line = JSON.stringify(toRunSnapshot(run));
+    await appendFile(this.stateFilePath(run.runId), line + "\n", "utf8");
+    if (isTerminal) {
+      this.lastSavedAt.delete(run.runId);
+    } else {
+      this.lastSavedAt.set(run.runId, now);
+    }
+  }
+
+  async loadAll(): Promise<WorkflowRun[]> {
+    let files: string[];
+    try {
+      files = await readdir(this.stateDir());
+    } catch {
+      // 目录不存在 = 从未持久化过（首启/干净环境），空集是正常态不是错误。
+      return [];
+    }
+
+    const runs: WorkflowRun[] = [];
+    for (const file of files) {
+      if (!file.endsWith(".jsonl")) continue;
+      const run = await this.loadLatestValidLine(join(this.stateDir(), file), file);
+      if (run) runs.push(run);
+    }
+    return runs;
+  }
+
+  /** 单文件从尾向头取第一条有效快照行；整文件无有效行返回 undefined（warn）。 */
+  private async loadLatestValidLine(absPath: string, display: string): Promise<WorkflowRun | undefined> {
+    let content: string;
+    try {
+      content = await readFile(absPath, "utf8");
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.warn(`[file-run-store] skip unreadable state file ${display}: ${msg}`);
+      return undefined;
+    }
+
+    const lines = content.split("\n");
+    for (let i = lines.length - 1; i >= 0; i--) {
+      const line = lines[i].trim();
+      if (line === "") continue; // 尾部空行（末行 \n 产物）静默跳过
+      const run = this.parseLine(line, display, i);
+      if (run) return run;
+      // 损坏行 warn 后继续向前找——最后一条「有效」行可能早于文件尾部（半行写入崩溃）
+    }
+    logger.warn(`[file-run-store] no valid snapshot line in ${display} (empty or all corrupted)`);
+    return undefined;
+  }
+
+  /**
+   * 单行解析 + 版本衔接预处理（D4 裁决②③，宿主侧职责）+ 形状校验；损坏
+   * warn 并返回 undefined。
+   *
+   * - 缺 v 字段（core 存量行）→ 就地补当前版本再进 codec（「缺版本 = 当前
+   *   版本」宽容读，不做自动迁移——写回时经 toRunSnapshot 自然补 v 完成渐进
+   *   收敛）；预处理留在 store 层而非 codec，保 pi 侧「v1 存量静默跳过」语义
+   *   不被宽容化误读（D4 裁决②归属裁决）。
+   * - v 存在但不匹配（未知更高版本/降级写入）→ 跳过 + warn（补可见性，对齐
+   *   pi 静默跳过语义；字符串版本无大小序，不引入比较逻辑——D4 裁决③）。
+   *   此处版本判断仅为 warn 可见性，数据防线仍是 codec 内 guard（双保险，
+   *   pi 切换 codec 后共享同一防线）。
+   */
+  private parseLine(line: string, display: string, lineNo: number): WorkflowRun | undefined {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      logger.warn(`[file-run-store] skip corrupted line ${display}:${lineNo}: ${msg}`);
+      return undefined;
+    }
+    if (parsed !== null && typeof parsed === "object") {
+      const rec = parsed as { v?: unknown };
+      if (rec.v === undefined) {
+        rec.v = SNAPSHOT_VERSION;
+      } else if (rec.v !== SNAPSHOT_VERSION) {
+        logger.warn(
+          `[file-run-store] skip snapshot with unsupported version ${display}:${lineNo}: v=${JSON.stringify(rec.v)} (this build only reads v=${JSON.stringify(SNAPSHOT_VERSION)}; the run line is skipped). To recover: upgrade @zhushanwen/subagent-core, or migrate/delete this state file if its runs are no longer needed`,
+        );
+        return undefined;
+      }
+    }
+    const run = fromRunSnapshot(parsed);
+    if (run === undefined) {
+      logger.warn(`[file-run-store] skip malformed snapshot ${display}:${lineNo} (shape validation failed)`);
+      return undefined;
+    }
+    return run;
+  }
+
+  /**
+   * 把 workflow-state 目录裁剪到上限个最新 state 文件（mtime 升序删最旧，C1）。
+   *
+   * 语义对齐 pi jsonl-run-store.pruneStateFilesBeyondCap（逐段同构）：
+   * - 只删本目录内命中 {@link STATE_FILE_GLOB} 的文件；任何失败都不抛（清理是
+   *   旁路维护，不能拖垮持久化主链路）：readdir 失败静默放弃本轮（ENOENT =
+   *   从未持久化，正常态），单个 unlink 失败（非 ENOENT）warn 留证后继续删
+   *   其余——ENOENT 视为并发删除竞态下的已达成目标，不告警；
+   * - stat 全集取 mtime，allSettled 部分降级——单文件 stat 失败（并发删除
+   *   ENOENT 等）静默跳过该文件，不阻断本轮裁剪。
+   *
+ * 上限解析（envName 通道，OR-5 ⑥b 默认开；显式非法值 opt-out 对齐 pi 解析风格）：
+ * - `envName` 提供 → env 通道：`process.env[envName]` 未设/空 → 按默认上限
+ *   {@link DEFAULT_STATE_MAX_RUNS} 裁剪（**默认开**——OR-5 修复前的 opt-in
+ *   「默认关」正是跨 run 无界累积缺陷本身）；设了有限正数 → 上限 = env 值
+ *   （env 值即上限）；设了非法值（非有限数/≤0）→ 不清理（显式 opt-out 通道：
+ *   用户意图不明时不动磁盘——对齐本方法 readdir/stat 失败一律放弃的保守哲学，
+ *   宿主如需自管保留可设足够大的正数值）；
+ * - `envName` 缺省 → 无 env 通道，直接按 `max` 参数裁剪（上限 = max，调用方
+ *   自管启用时机）。
+   *
+   * 本方法只做磁盘裁剪，不动内存 runs Map（内存侧淘汰归
+   * lifecycle.evictDoneRunsBeyondCap，两域独立）。
+   *
+   * @param max 上限（envName 缺省时生效；env 通道启用时被 env 值覆盖）
+   * @param envName opt-in 开关 + 上限覆盖 env 变量名（可选；pi 先例
+   *   `XYZ_SUBAGENT_STATE_MAX_RUNS`）
+   */
+  async pruneStateFilesBeyondCap(max: number, envName?: string): Promise<void> {
+    let cap = max;
+    if (envName !== undefined) {
+      // 未设/空 → 默认开（OR-5 ⑥b：DEFAULT_STATE_MAX_RUNS）；非法/≤0 → 不清理
+      // （显式 opt-out 通道，见方法注释）；有效正数 → env 值覆盖
+      const raw = process.env[envName];
+      if (raw === undefined || raw === "") {
+        cap = DEFAULT_STATE_MAX_RUNS;
+      } else {
+        const parsed = Number(raw);
+        if (!Number.isFinite(parsed) || parsed <= 0) return;
+        cap = parsed;
+      }
+    }
+
+    const stateDir = this.stateDir();
+    let names: string[];
+    try {
+      names = await readdir(stateDir);
+    } catch (err) {
+      if (!isEnoentError(err)) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.warn(`[file-run-store] state retention: readdir ${stateDir} failed: ${reason}`);
+      }
+      return;
+    }
+    const stateFiles = names.filter((n) => STATE_FILE_GLOB.test(n)).sort();
+    if (stateFiles.length <= cap) return;
+
+    // stat 全集取 mtime；allSettled 部分降级（单文件失败静默跳过，不阻断本轮）
+    const settled = await Promise.allSettled(
+      stateFiles.map(async (name) => {
+        const full = join(stateDir, name);
+        return { full, mtimeMs: (await stat(full)).mtimeMs };
+      }),
+    );
+    const byMtimeAsc = settled
+      .flatMap((r) => (r.status === "fulfilled" ? [r.value] : []))
+      .sort((a, b) => a.mtimeMs - b.mtimeMs);
+    const victims = byMtimeAsc.slice(0, byMtimeAsc.length - cap);
+    for (const victim of victims) {
+      try {
+        await unlink(victim.full);
+        logger.debug(`[file-run-store] state retention: pruned ${victim.full}`);
+      } catch (err) {
+        if (isEnoentError(err)) continue; // 并发删除已达成目标
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.warn(`[file-run-store] state retention: failed to delete ${victim.full}: ${reason}`);
+      }
+    }
+  }
+}