@zhushanwen/pi-subagents 0.0.1

package/src/core/turn-limiter.ts

@@ -0,0 +1,71 @@
+// src/core/turn-limiter.ts
+//
+// soft/hard turn 限制器。maxTurns 到达 → steer 提醒收尾；
+// graceTurns 后仍不结束 → abort。
+
+/** steer 提醒消息：要求 agent 总结已完成/未完成/下一步，不得谎报完成。 */
+const WRAP_UP_MESSAGE = [
+  "You have reached your turn limit. Wrap up now:",
+  "1. Summarize what you have completed (with evidence: file paths, command output).",
+  "2. List what remains undone and why.",
+  "3. State the single most important next step for whoever continues.",
+  "Do NOT claim the task is complete if any part remains unfinished.",
+].join(" ");
+
+/** turn limiter 配置。 */
+export interface TurnLimiterOptions {
+  maxTurns: number;
+  graceTurns: number;
+  steer: (msg: string) => void;
+  abort: () => void;
+}
+
+/**
+ * soft/hard turn 限制。
+ *
+ *   onTurnEnd(currentTurns):
+ *     已 aborted 或 maxTurns<=0（禁用）→ 直接 return
+ *     currentTurns >= maxTurns 且未 steer → steer(WRAP_UP_MESSAGE)（仅一次）
+ *     已 steer 且 currentTurns >= maxTurns + graceTurns → abort()（仅一次）
+ *
+ * maxTurns<=0 表示不限（limit=Infinity，永不触发）。
+ * graceTurns<=0 时 steer 后下一 turn 即 abort。
+ */
+export interface TurnLimiter {
+  /** 每次 turn_end 调用。 */
+  onTurnEnd(currentTurns: number): void;
+  /** 是否已发过 steer（诊断用）。 */
+  readonly didSteer: boolean;
+  /** 是否已 abort（诊断用）。 */
+  readonly didAbort: boolean;
+}
+
+/** 工厂函数。 */
+export function createTurnLimiter(opts: TurnLimiterOptions): TurnLimiter {
+  let steered = false;
+  let aborted = false;
+  const limit = opts.maxTurns > 0 ? opts.maxTurns : Infinity;
+  const grace = opts.graceTurns > 0 ? opts.graceTurns : 0;
+
+  const onTurnEnd = (turn: number): void => {
+    if (aborted || !Number.isFinite(limit)) return;
+    if (!steered && turn >= limit) {
+      steered = true;
+      opts.steer(WRAP_UP_MESSAGE);
+    }
+    if (steered && turn >= limit + grace) {
+      aborted = true;
+      opts.abort();
+    }
+  };
+
+  return {
+    onTurnEnd,
+    get didSteer(): boolean {
+      return steered;
+    },
+    get didAbort(): boolean {
+      return aborted;
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,104 @@
+// src/index.ts
+//
+// Pi extension 工厂。只做注册胶水——不含业务逻辑。
+// 注册项：tool / command / messageRenderer / session 事件。
+
+import type { ExtensionAPI, ExtensionContext, ResourcesDiscoverEvent, ResourcesDiscoverResult, SessionShutdownEvent, SessionStartEvent } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+
+import { registerSubagentsCommand } from "./commands/subagents.ts";
+import { DiscoveryConfigLoader } from "./runtime/discovery-config.ts";
+import {
+  getModelConfigService,
+  ModelConfigService,
+  setModelConfigService,
+} from "./runtime/model-config-service.ts";
+import { maybeCleanupExpiredSessionFiles } from "./runtime/session-file-gc.ts";
+import {
+  getSubagentService,
+  setSubagentService,
+  SubagentService,
+} from "./runtime/subagent-service.ts";
+import { registerSubagentTool } from "./tools/subagent-tool.ts";
+import { renderBgNotifyMessage } from "./tui/bg-notify-render.ts";
+
+/**
+ * FR-10.2: Pi extension 工厂。
+ *
+ *   ╔══════════════════════════════════════════════════════════════════╗
+//   ║  注册（进程级，一次）:                                             ║
+//   ║    registerSubagentsCommand(pi)  → /subagents                      ║
+//   ║    registerSubagentTool(pi)      → subagent tool                   ║
+//   ║    pi.registerMessageRenderer("subagent-bg-notify", renderBgNotify)║
+//   ║                                                                    ║
+//   ║  session_start(event, ctx):                                        ║
+//   ║    1. modelService = getModelConfigService() ?? new ModelConfigService(...)║
+//   ║    2. service = getSubagentService() ?? new SubagentService({cwd, modelService})║
+//   ║    3. modelService.initModel({modelRegistry, sessionId, entries}) ║
+//   ║    4. service.initSession({pi, sessionId})                        ║
+//   ║    5. maybeCleanupExpiredSessionFiles(homeDir, cwd)                ║
+//   ║                                                                    ║
+//   ║  session_shutdown(event):                                          ║
+//   ║    rt.dispose()                                                    ║
+//   ╚══════════════════════════════════════════════════════════════════╝
+ */
+export default function subagentsExtension(pi: ExtensionAPI): void {
+  registerSubagentsCommand(pi);
+  registerSubagentTool(pi);
+  pi.registerMessageRenderer("subagent-bg-notify", renderBgNotifyMessage);
+
+  // discovery.json 契约加载器（进程级单例，跨 session 复用 mtime 缓存）。
+  // 宿主启动 pi 前写入 <agentDir>/subagents/discovery.json 声明多 skill/agent 目录。
+  // 详见 ADR-025。
+  const discoveryLoader = new DiscoveryConfigLoader(getAgentDir());
+
+  // resources_discover：把 discovery 的 skillDirs 注入主 session 的 resourceLoader。
+  // 主 agent 的 skill 走此通道（pi 原生官方机制），子 session 的 skill 由 session-factory 另读。
+  pi.on("resources_discover", (_event: ResourcesDiscoverEvent, _ctx: ExtensionContext): ResourcesDiscoverResult => {
+    const discovery = discoveryLoader.load();
+    return { skillPaths: discovery.skillDirs.length > 0 ? [...discovery.skillDirs] : undefined };
+  });
+
+  pi.on("session_start", (_event: SessionStartEvent, ctx: ExtensionContext) => {
+    const cwd = ctx.cwd;
+    // agentDir 由 Pi 核心 getAgentDir() 决定（读 PI_CODING_AGENT_DIR，默认 ~/.pi/agent），
+    // 与 Pi 主进程目录约定完全一致——宿主可经环境变量整体重定向配置/agent/skill 目录。
+    const agentDir = getAgentDir();
+
+    // 双 Service 装配：ModelConfigService（配置/模型域）+ SubagentService（执行/记录/通知域）
+    const existingService = getSubagentService();
+    const existingModelService = getModelConfigService();
+    const modelService = existingModelService ?? new ModelConfigService({ agentDir, discoveryLoader });
+    const service = existingService ?? new SubagentService({ cwd, modelService });
+
+    // 分别 init（两个域的生命周期独立）
+    modelService.initModel({
+      modelRegistry: ctx.modelRegistry,
+      sessionId: ctx.sessionManager.getSessionId(),
+      entries: ctx.sessionManager.getEntries() ?? [],
+    });
+    service.initSession({
+      pi,
+      sessionId: ctx.sessionManager.getSessionId(),
+    });
+
+    // 先注册 Service（让 execute 可用），再做 best-effort 清理。
+    // 顺序很重要：清理若 throw 不能阻塞 service 注册，否则 getSubagentService() 永远返回 undefined。
+    if (!existingService) {
+      setModelConfigService(modelService);
+      setSubagentService(service);
+    }
+
+    // best-effort 清理（GC），失败不应阻断 session——但额外兜底：
+    // 万一仍抛错，catch 住防止 session_start 整体崩。
+    try {
+      maybeCleanupExpiredSessionFiles(agentDir, cwd);
+    } catch {
+      // best-effort 清理失败，忽略——service 已注册，session 可用
+    }
+  });
+
+  pi.on("session_shutdown", (_event: SessionShutdownEvent) => {
+    getSubagentService()?.dispose();
+  });
+}

package/src/runtime/config/config.ts

@@ -0,0 +1,170 @@
+// src/runtime/config/config.ts
+//
+// 全局配置（~/.pi/agent/subagents/config.json）+ session 级状态（内存）。
+//
+// 开箱默认值内联在代码里（见 DEFAULT_CONFIG），不依赖任何包内文件。
+// 用户私有 category models 走 ~/.pi/agent/subagents/config.json（loadGlobalConfig）。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type {
+  SessionModelState,
+  SubagentsGlobalConfig,
+} from "../../types.ts";
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** JSON 序列化缩进。 */
+const JSON_INDENT = 2;
+
+/** appendEntry 的 customType（restoreSessionState 据此匹配）。 */
+const CONFIG_ENTRY_TYPE = "subagent-config-entry";
+
+/**
+ * 开箱默认配置（单一真相源，内联在代码里）。
+ *
+ * 历史教训 [HISTORICAL]：曾用包内 config.json（与 src/ 同级）作为默认值源，
+ * 但 config.json 被 .gitignore 排除且不应随 npm 包分发用户私有配置——导致
+ * npm pack 后 BUILTIN_CONFIG_PATH 读不到文件，catch 兜底用 fallback.model=""，
+ * 进而 resolveModelForAgent 第 5 级 lookupModel("") 必失败，pi install 后首次
+ * 执行 subagent tool 抛 "No available model"。修复：默认值内联在代码里，不依赖
+ * 任何包内文件。用户私有配置仍走 ~/.pi/agent/subagents/config.json（loadGlobalConfig）。
+ *
+ * fallback.model 选 Anthropic claude-sonnet-4-5 作为公开可用默认——Pi 默认环境通常
+ * 已配置 Anthropic 凭证。即便用户未配置，resolveModelForAgent 会 fall through 到
+ * tried 列表并抛清晰错误（列出可用 model），不会静默崩溃。
+ */
+const DEFAULT_CONFIG: SubagentsGlobalConfig = {
+  version: 1,
+  yoloByDefault: false,
+  maxConcurrent: 4,
+  categories: {},
+  agentCategoryOverrides: {},
+  fallback: { model: "anthropic/claude-sonnet-4-5", thinkingLevel: undefined },
+};
+
+// ============================================================
+// 路径
+// ============================================================
+
+/**
+ * 配置文件路径（<agentDir>/subagents/config.json）。
+ * agentDir 由 Pi 核心 getAgentDir() 决定（读 PI_CODING_AGENT_DIR，默认 ~/.pi/agent），
+ * 与 Pi 主进程的目录约定完全一致——支持宿主经环境变量整体重定向。
+ */
+export function getGlobalConfigPath(agentDir: string): string {
+  return path.join(agentDir, "subagents", "config.json");
+}
+
+// ============================================================
+// 全局配置加载/保存
+// ============================================================
+
+/** 默认配置的深拷贝（避免调用方 mutate DEFAULT_CONFIG 常量）。 */
+function defaultConfig(): SubagentsGlobalConfig {
+  return {
+    ...DEFAULT_CONFIG,
+    categories: { ...DEFAULT_CONFIG.categories },
+    agentCategoryOverrides: { ...DEFAULT_CONFIG.agentCategoryOverrides },
+    fallback: { ...DEFAULT_CONFIG.fallback },
+  };
+}
+
+/** 校验 categories 最小结构（label + model 字符串），非法值回退默认。 */
+function sanitizeCategories(input: unknown): SubagentsGlobalConfig["categories"] {
+  const result = { ...DEFAULT_CONFIG.categories };
+  if (!input || typeof input !== "object") return result;
+  for (const [name, def] of Object.entries(input as Record<string, unknown>)) {
+    if (!def || typeof def !== "object") continue;
+    const d = def as Record<string, unknown>;
+    if (typeof d.label !== "string" || typeof d.model !== "string") continue;
+    result[name] = {
+      label: d.label,
+      model: d.model,
+      thinkingLevel: typeof d.thinkingLevel === "string" ? d.thinkingLevel : undefined,
+    };
+  }
+  return result;
+}
+
+/**
+ * 加载全局配置。文件不存在时返回默认配置（保证 categories/fallback 完整）。
+ * 与默认配置 deep-merge——新增字段有默认值，旧 config 缺字段不崩溃。
+ */
+export function loadGlobalConfig(agentDir: string): SubagentsGlobalConfig {
+  const configPath = getGlobalConfigPath(agentDir);
+  try {
+    const raw = fs.readFileSync(configPath, "utf-8");
+    const parsed = JSON.parse(raw) as Partial<SubagentsGlobalConfig>;
+    return {
+      version: parsed.version ?? DEFAULT_CONFIG.version,
+      yoloByDefault: parsed.yoloByDefault ?? DEFAULT_CONFIG.yoloByDefault,
+      maxConcurrent: parsed.maxConcurrent ?? DEFAULT_CONFIG.maxConcurrent,
+      categories: sanitizeCategories(parsed.categories),
+      agentCategoryOverrides: { ...DEFAULT_CONFIG.agentCategoryOverrides, ...parsed.agentCategoryOverrides },
+      fallback: { ...DEFAULT_CONFIG.fallback, ...parsed.fallback },
+    };
+  } catch {
+    // 文件不存在 / JSON 解析失败 → 返回默认配置的深拷贝
+    return defaultConfig();
+  }
+}
+
+/** 保存全局配置（config-wizard 调用）。原子写入（temp + rename）。 */
+export function saveGlobalConfig(agentDir: string, config: SubagentsGlobalConfig): Promise<void> {
+  const configPath = getGlobalConfigPath(agentDir);
+  const configDir = path.dirname(configPath);
+  return new Promise((resolve, reject) => {
+    try {
+      fs.mkdirSync(configDir, { recursive: true });
+      const tempPath = `${configPath}.tmp.${process.pid}`;
+      fs.writeFileSync(tempPath, `${JSON.stringify(config, null, JSON_INDENT)}\n`, "utf-8");
+      fs.renameSync(tempPath, configPath);
+      resolve();
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+// ============================================================
+// Session 级状态（内存，可经 appendEntry 持久化/恢复）
+// ============================================================
+
+/**
+ * 创建初始 session 状态（session_start 时调用）。
+ *
+ * categoryConfirmed 默认 true——不拦截执行（D-1：取消首次确认）。
+ * 用户改 category 模型走 /subagents config（写 globalConfig）；感知模型靠 tool block
+ * 醒目显示。categoryModels/agentModels 保留为 inert 字段（resolveModel 有兜底不崩）。
+ */
+export function createSessionState(): SessionModelState {
+  return { yoloMode: false, categoryConfirmed: true, categoryModels: {}, agentModels: {} };
+}
+
+/**
+ * 从 entries 恢复 session 状态（/resume 时）。
+ * 倒序遍历——取最新一条 subagent-config-entry 快照（与仓库约定一致）。
+ * 反序列化字段缺失时用默认值（向后兼容）。
+ */
+export function restoreSessionState(entries: ReadonlyArray<{ type: string; data?: unknown }>): SessionModelState {
+  const state = createSessionState();
+  for (let i = entries.length - 1; i >= 0; i--) {
+    const entry = entries[i];
+    if (entry.type !== CONFIG_ENTRY_TYPE || !entry.data) continue;
+    const d = entry.data as Partial<SessionModelState>;
+    if (typeof d.yoloMode === "boolean") state.yoloMode = d.yoloMode;
+    if (typeof d.categoryConfirmed === "boolean") state.categoryConfirmed = d.categoryConfirmed;
+    if (d.categoryModels && typeof d.categoryModels === "object") {
+      state.categoryModels = { ...d.categoryModels };
+    }
+    if (d.agentModels && typeof d.agentModels === "object") {
+      state.agentModels = { ...d.agentModels };
+    }
+    break;
+  }
+  return state;
+}

package/src/runtime/discovery-config.ts

@@ -0,0 +1,135 @@
+// src/runtime/discovery-config.ts
+//
+// 资源发现契约（<agentDir>/subagents/discovery.json）。
+//
+// 宿主（xyz-agent GUI 等）启动 pi 前写入本文件，声明要加载的 skill 目录与
+// agent 目录（按覆盖顺序排列）。subagents 在 session_start 与 resources_discover
+// 时读取，主 agent 与子 session 的资源注入都以此文件为单一真相源。
+// 文件缺失或字段非法时，skillDirs/agentDirs 视为空数组，走默认行为（零破坏）。
+//
+// 详见 ADR-025。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { DiscoveryConfig } from "../types.ts";
+
+// ============================================================
+// 常量与默认值
+// ============================================================
+
+/** discovery.json 的当前版本。字段结构变更时递增。 */
+const DISCOVERY_VERSION = 1;
+
+/** 空契约（文件缺失/解析失败时返回，保证调用方拿到统一形状）。 */
+const EMPTY_DISCOVERY: DiscoveryConfig = {
+  version: DISCOVERY_VERSION,
+  skillDirs: [],
+  agentDirs: [],
+};
+
+// ============================================================
+// 路径
+// ============================================================
+
+/**
+ * discovery.json 路径（<agentDir>/subagents/discovery.json）。
+ * 与 config.json 同级，落在 subagents 专属子目录下。
+ */
+export function getDiscoveryConfigPath(agentDir: string): string {
+  return path.join(agentDir, "subagents", "discovery.json");
+}
+
+// ============================================================
+// 加载与校验
+// ============================================================
+
+/**
+ * 从字符串数组字段中提取合法的绝对路径条目。
+ * 去重（保序，靠前优先）、剔除非字符串/空串。
+ */
+function sanitizePathList(input: unknown): string[] {
+  if (!Array.isArray(input)) return [];
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const item of input) {
+    if (typeof item !== "string" || item.length === 0) continue;
+    if (seen.has(item)) continue;
+    seen.add(item);
+    result.push(item);
+  }
+  return result;
+}
+
+/**
+ * 解析 discovery.json 原始内容为 DiscoveryConfig。
+ * 宽容解析：任何字段非法都回退到空数组，不抛错（best-effort，不阻断 session）。
+ */
+function parseDiscoveryConfig(raw: string): DiscoveryConfig {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { ...EMPTY_DISCOVERY };
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return { ...EMPTY_DISCOVERY };
+  }
+  const obj = parsed as Record<string, unknown>;
+  return {
+    version: typeof obj.version === "number" ? obj.version : DISCOVERY_VERSION,
+    skillDirs: sanitizePathList(obj.skillDirs),
+    agentDirs: sanitizePathList(obj.agentDirs),
+  };
+}
+
+// ============================================================
+// mtime 缓存加载器
+// ============================================================
+
+/**
+ * 带 mtime 缓存的 discovery.json 读取器。
+ *
+ * discovery.json 在一次 session 内被读取两次（resources_discover + session-factory），
+ * 用 mtime 判断是否需要重新 read+parse，避免重复磁盘 IO。
+ *
+ * 跨 session 复用：mtime 变了才重读。宿主写文件时用原子写（temp + rename），
+ * mtime 会变化，触发下次读取重新解析。
+ */
+export class DiscoveryConfigLoader {
+  private cached: DiscoveryConfig | null = null;
+  private cachedMtimeMs: number | null = null;
+  private readonly filePath: string;
+
+  constructor(agentDir: string) {
+    this.filePath = getDiscoveryConfigPath(agentDir);
+  }
+
+  /**
+   * 读取 discovery.json（mtime 未变则复用缓存）。
+   * 文件不存在/不可读/解析失败均返回空契约，永不抛错。
+   */
+  load(): DiscoveryConfig {
+    let stat: fs.Stats;
+    try {
+      stat = fs.statSync(this.filePath);
+    } catch {
+      // 文件不存在 / 不可 stat → 清缓存返回空（宿主可能删了文件）
+      this.cached = null;
+      this.cachedMtimeMs = null;
+      return { ...EMPTY_DISCOVERY };
+    }
+    const mtimeMs = stat.mtimeMs;
+    if (this.cached !== null && this.cachedMtimeMs === mtimeMs) {
+      return this.cached;
+    }
+    try {
+      const raw = fs.readFileSync(this.filePath, "utf-8");
+      this.cached = parseDiscoveryConfig(raw);
+      this.cachedMtimeMs = mtimeMs;
+      return this.cached;
+    } catch {
+      return { ...EMPTY_DISCOVERY };
+    }
+  }
+}

package/src/runtime/execution/history-store.ts

@@ -0,0 +1,196 @@
+// src/runtime/execution/history-store.ts
+//
+// 跨 session 执行记录持久化。
+//   存储格式：history.jsonl，append-only，每行一个 PersistedAgentRecord。
+//   目录布局：<agentDir>/subagents/<encoded-cwd>/history.jsonl
+//   （agentDir 默认 ~/.pi/agent，可被 PI_CODING_AGENT_DIR 重定向）
+//   GC：超 HISTORY_MAX 时重写保留最近 N 条（每 GC_CHECK_INTERVAL 次写检查）。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { encodeCwd } from "../../core/path-encoding.ts";
+import type { PersistedAgentRecord } from "../../types.ts";
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** GC 上限（超过则重写保留最近 N 条）。 */
+const HISTORY_MAX = 500;
+
+/** GC 检查间隔（每 N 次写触发一次 forceGc）。 */
+const GC_CHECK_INTERVAL = 10;
+
+// ============================================================
+// 路径
+// ============================================================
+
+/**
+ * 计算 history 文件路径（<agentDir>/subagents/<encoded-cwd>/history.jsonl）。
+ * encoded-cwd 与 session-factory 的 encodeCwd 逻辑一致（复用 Pi SDK 编码约定，
+ * 共享 core/path-encoding.ts 的唯一定义）。
+ */
+export function getHistoryFilePath(agentDir: string, cwd: string): string {
+  const encoded = encodeCwd(cwd);
+  return path.join(agentDir, "subagents", encoded, "history.jsonl");
+}
+
+// ============================================================
+// 结构校验
+// ============================================================
+
+const VALID_STATUS = new Set(["running", "done", "failed", "cancelled"]);
+const VALID_MODE = new Set(["sync", "background"]);
+
+/** 校验 PersistedAgentRecord 最小结构（防旧版本字段漂移污染下游）。 */
+export function isValidPersistedRecord(value: unknown): value is PersistedAgentRecord {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.id === "string" &&
+    typeof v.agent === "string" &&
+    typeof v.status === "string" && VALID_STATUS.has(v.status) &&
+    typeof v.mode === "string" && VALID_MODE.has(v.mode) &&
+    typeof v.startedAt === "number" &&
+    typeof v.cwd === "string"
+  );
+}
+
+// ============================================================
+// HistoryStore
+// ============================================================
+
+/**
+ * 按 (agentDir, cwd) 隔离的执行记录存储。
+ *
+ *   ╔════════════════════════════════════════════════════════════════╗
+//   ║  append(record):                                                 ║
+//   ║    1. 串行化（writeChain，防并发行交错）                          ║
+//   ║    2. fs.appendFileSync(filePath, JSON + "\n")                   ║
+//   ║    3. maybeGc()：writesSinceLastGc++ 达阈值则 forceGc             ║
+//   ║    4. best-effort：失败静默（不阻断主流程）                       ║
+//   ║                                                                  ║
+//   ║  recent(limit, sessionId?):                                      ║
+//   ║    1. read(sessionId) 过滤                                        ║
+//   ║    2. 同 id 去重：last-writer-wins；endedAt 相同 cancelled 优先   ║
+//   ║       （cancel 先写 cancelled，runAgent catch 再写 failed）       ║
+//   ║    3. endedAt desc + startedAt desc 排序                         ║
+//   ║    4. slice(limit)                                               ║
+//   ╚════════════════════════════════════════════════════════════════╝
+ */
+export class HistoryStore {
+  private writeChain: Promise<void> = Promise.resolve();
+  private writesSinceLastGc = 0;
+  private readonly filePath: string;
+
+  constructor(
+    private readonly agentDir: string,
+    private readonly cwd: string,
+  ) {
+    this.filePath = getHistoryFilePath(agentDir, cwd);
+  }
+
+  /** 追加一条记录（串行化防并发交错，best-effort 失败静默）。 */
+  append(record: PersistedAgentRecord): Promise<void> {
+    this.writeChain = this.writeChain
+      .then(() => this.doAppend(record))
+      .catch(() => {
+        // best-effort：写入失败不阻断主流程（执行已完成，history 只是日志）
+      });
+    return this.writeChain;
+  }
+
+  /** 实际写入 + 惰性 GC。 */
+  private doAppend(record: PersistedAgentRecord): void {
+    try {
+      fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+      fs.appendFileSync(this.filePath, `${JSON.stringify(record)}\n`, "utf-8");
+    } catch {
+      // 目录创建/写入失败 → 静默（best-effort）
+      return;
+    }
+    this.maybeGc();
+  }
+
+  /** 读取全部（旧→新）。损坏行跳过。sessionId 过滤。 */
+  read(sessionId?: string): PersistedAgentRecord[] {
+    let raw: string;
+    try {
+      raw = fs.readFileSync(this.filePath, "utf-8");
+    } catch {
+      return []; // 文件不存在 → 空
+    }
+    const records: PersistedAgentRecord[] = [];
+    for (const line of raw.split("\n")) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      try {
+        const parsed = JSON.parse(trimmed);
+        if (isValidPersistedRecord(parsed)) {
+          if (!sessionId || parsed.sessionId === sessionId) {
+            records.push(parsed);
+          }
+        }
+      } catch (_err) {
+        // 有意吞掉：损坏行跳过（不阻断后续行解析）
+        void _err;
+      }
+    }
+    return records;
+  }
+
+  /** 最近 N 条（新→旧），同 id 去重（last-writer-wins，cancelled 优先）。 */
+  recent(limit: number, sessionId?: string): PersistedAgentRecord[] {
+    const all = this.read(sessionId);
+    // 同 id 去重：后写覆盖前写；endedAt 相同时 cancelled 优先
+    const byId = new Map<string, PersistedAgentRecord>();
+    for (const r of all) {
+      const existing = byId.get(r.id);
+      if (!existing) {
+        byId.set(r.id, r);
+        continue;
+      }
+      // cancelled 优先保留（用户意图，即使被后写覆盖）——与 record-store.merge 一致
+      if (existing.status === "cancelled" && r.status !== "cancelled") {
+        continue;
+      }
+      // 否则 last-writer-wins
+      byId.set(r.id, r);
+    }
+    // 排序：endedAt desc（running 用 startedAt 兜底）+ startedAt desc
+    return [...byId.values()]
+      .sort((a, b) => {
+        const aEnd = a.endedAt ?? a.startedAt;
+        const bEnd = b.endedAt ?? b.startedAt;
+        if (bEnd !== aEnd) return bEnd - aEnd;
+        return b.startedAt - a.startedAt;
+      })
+      .slice(0, limit);
+  }
+
+  /** 强制 GC（测试用）。重写文件保留最近 HISTORY_MAX 条。 */
+  forceGc(): void {
+    const all = this.read();
+    if (all.length <= HISTORY_MAX) return;
+    const keep = all.slice(all.length - HISTORY_MAX); // 保留最新 N 条
+    try {
+      const tempPath = `${this.filePath}.tmp.${process.pid}`;
+      const content = keep.map((r) => JSON.stringify(r)).join("\n") + "\n";
+      fs.writeFileSync(tempPath, content, "utf-8");
+      fs.renameSync(tempPath, this.filePath);
+    } catch (_err) {
+      // 有意吞掉：GC 失败不影响 append 主流程（下次 GC 重试）
+      void _err;
+    }
+  }
+
+  /** 惰性 GC（每 GC_CHECK_INTERVAL 次写触发一次）。 */
+  private maybeGc(): void {
+    this.writesSinceLastGc += 1;
+    if (this.writesSinceLastGc >= GC_CHECK_INTERVAL) {
+      this.writesSinceLastGc = 0;
+      this.forceGc();
+    }
+  }
+}