@zhushanwen/pi-subagent-workflow 0.2.0 → 0.3.0

package/src/execution/manifest-store.ts

@@ -0,0 +1,206 @@
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as path from "node:path";
+
+import { bestEffort } from "./best-effort.ts";
+
+export interface ManifestRecord {
+  id: string;
+  rootSessionId: string;
+  agentName: string;
+  /**
+   * 终态枚举：finalizeRecord 写 running/completed/failed/cancelled 四态；cancelled 不再
+   * 归并 failed。crashed 不进 manifest——crashed 是重启重建时靠 sidecar 四分支推断的派生态
+   * （见 record-store.ts reconstructAll），持久化会与 sidecar source of truth 形成双源；
+   * manifest 职责保持纯粹，只记录 finalize 明确产出的终态。
+   * 历史 "error" 值已移除——读侧 isValidManifest 守卫拒绝，mapManifestStatus 越界返回 null。
+   */
+  status: "running" | "completed" | "failed" | "cancelled";
+  createdAt: number;
+  completedAt?: number;
+  sessionFile?: string;
+  /** FR-7 补字段：manifest 写入时从 ExecutionRecord 抓取，供 manifestToSubagent 投影真实值。 */
+  task?: string;
+  slug?: string;
+  model?: string;
+}
+
+/** 合法 manifest status 集合（4 态；运行时守卫用，磁盘文件可能陈旧/损坏）。crashed 不在其中。 */
+const VALID_MANIFEST_STATUSES: ReadonlySet<string> = new Set([
+  "running",
+  "completed",
+  "failed",
+  "cancelled",
+]);
+
+/**
+ * 校验 JSON.parse 产物是否为合法 ManifestRecord。
+ * 关键字段类型检查——不合法返回 false，调用方据此过滤（防损坏/陈旧文件污染投影）。
+ */
+function isValidManifest(value: unknown): value is ManifestRecord {
+  if (typeof value !== "object" || value === null) return false;
+  const v = value as Record<string, unknown>;
+  return (
+    typeof v.id === "string" &&
+    typeof v.rootSessionId === "string" &&
+    typeof v.agentName === "string" &&
+    typeof v.createdAt === "number" &&
+    typeof v.status === "string" &&
+    VALID_MANIFEST_STATUSES.has(v.status)
+  );
+}
+
+export class ManifestStore {
+  private readonly dir: string;
+
+  constructor(dir: string) {
+    this.dir = dir;
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+  }
+
+  /**
+   * 原子写：tmp → fsync → rename → fsync dir。真异步（fs.promises，不阻塞 event loop）。
+   *
+   * rename 失败时 best-effort 清理残留 tmp（用 renamed 标志在 catch 中决定是否 unlink），
+   * 不掩盖原错误。失败向上抛——调用方（finalizeRecord）决定降级策略。
+   */
+  async writeManifest(record: ManifestRecord): Promise<void> {
+    const filePath = path.join(this.dir, `${record.id}.json`);
+    const tmpPath = `${filePath}.tmp.${process.pid}`;
+    const content = JSON.stringify(record, null, 2);
+
+    let renamed = false;
+    try {
+      // 1. 写 tmp → fsync 文件
+      const fh = await fsPromises.open(tmpPath, "w");
+      try {
+        await fh.writeFile(content, "utf-8");
+        await fh.sync();
+      } finally {
+        await fh.close();
+      }
+
+      // 2. rename tmp → final（放入 try：失败时 catch 清理 tmp）
+      await fsPromises.rename(tmpPath, filePath);
+      renamed = true;
+
+      // 3. fsync 目录（best-effort：POSIX 不要求，失败不否定已成功的 rename）
+      try {
+        const dirFh = await fsPromises.open(this.dir, "r");
+        try {
+          await dirFh.sync();
+        } finally {
+          await dirFh.close();
+        }
+      } catch (dirSyncErr) {
+        bestEffort(dirSyncErr, "fsync dir (writeManifest)");
+      }
+    } catch (err) {
+      // rename 未成功 → 清理残留 tmp（best-effort，不掩盖原错误）
+      if (!renamed) {
+        try {
+          await fsPromises.unlink(tmpPath);
+        } catch (cleanupErr) {
+          // best-effort：tmp 可能已被 rename 消费或从未创建。不影响主错误（下面 re-throw err）
+          bestEffort(cleanupErr, "unlink tmp (writeManifest)");
+        }
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * 按 id 读 manifest。文件不存在/JSON 损坏/schema 不合法均返回 null。
+   * 调用方需处理 null。
+   */
+  async readManifest(id: string): Promise<ManifestRecord | null> {
+    const filePath = path.join(this.dir, `${id}.json`);
+    try {
+      const content = await fsPromises.readFile(filePath, "utf-8");
+      const parsed: unknown = JSON.parse(content);
+      return isValidManifest(parsed) ? parsed : null;
+    } catch {
+      // 文件缺失（ENOENT）或 JSON 损坏（SyntaxError）均降级为 null
+      return null;
+    }
+  }
+
+  /**
+   * 同步读取所有 manifest 记录（best-effort，损坏/非法文件跳过）。
+   * 供 RecordStore.collectRecords 投影 orphan 记录使用——替代对私有 dir 的反射访问。
+   * 仅返回通过 isValidManifest 校验的记录。
+   */
+  listAllSync(): readonly ManifestRecord[] {
+    let files: string[];
+    try {
+      files = fs.readdirSync(this.dir);
+    } catch {
+      return [];
+    }
+    const results: ManifestRecord[] = [];
+    for (const file of files) {
+      if (!file.endsWith(".json") || file.includes(".tmp.")) continue;
+      try {
+        const content = fs.readFileSync(path.join(this.dir, file), "utf-8");
+        const parsed: unknown = JSON.parse(content);
+        if (isValidManifest(parsed)) {
+          results.push(parsed);
+        }
+      } catch (fileErr) {
+        // best-effort：损坏/非法文件跳过（debug 记录便于排查）
+        bestEffort(fileErr, `read manifest ${file} (listAllSync)`);
+      }
+    }
+    return results;
+  }
+
+  /**
+   * 启动时恢复 tmp 文件。
+   * 3 分支逻辑：
+   * 1. manifest 已存在 → 删 tmp（陈旧）
+   * 2. tmp 合法 + manifest 缺失 → rename tmp 为 manifest
+   * 3. tmp 非法 + manifest 缺失 → 删 tmp
+   */
+  async recoverTmpFiles(): Promise<{ deleted: number; recovered: number }> {
+    let deleted = 0;
+    let recovered = 0;
+
+    const files = fs.readdirSync(this.dir);
+    const tmpFiles = files.filter((f) => f.includes(".json.tmp."));
+
+    for (const tmpFile of tmpFiles) {
+      const tmpPath = path.join(this.dir, tmpFile);
+      const manifestId = tmpFile.split(".json.tmp.")[0];
+      const manifestPath = path.join(this.dir, `${manifestId}.json`);
+
+      if (fs.existsSync(manifestPath)) {
+        // 分支 1: manifest 已存在，删 tmp
+        fs.unlinkSync(tmpPath);
+        deleted++;
+      } else {
+        // 试解析 tmp
+        try {
+          const content = fs.readFileSync(tmpPath, "utf-8");
+          const parsed: unknown = JSON.parse(content);
+          if (isValidManifest(parsed)) {
+            // 分支 2: tmp 是合法 manifest，rename 为正式文件
+            fs.renameSync(tmpPath, manifestPath);
+            recovered++;
+          } else {
+            // 分支 3b: 合法 JSON 但非合法 manifest（缺必填字段），删
+            fs.unlinkSync(tmpPath);
+            deleted++;
+          }
+        } catch {
+          // 分支 3a: JSON.parse 失败，删
+          fs.unlinkSync(tmpPath);
+          deleted++;
+        }
+      }
+    }
+
+    return { deleted, recovered };
+  }
+}

package/src/execution/notifier.ts

@@ -129,7 +129,11 @@ export class BgNotifier {
       content,
       display: true,
       details,
-    }, { triggerTurn: true, deliverAs: "followUp" });
+      // [W2 修复] followUp → steer：subagent 完成通知需立即抢占主 agent 下一个 turn，
+      // 即使主 agent 处于轮询 subagent_list 的 processing 状态（followUp 永远排不上）。
+      // 与 workflow helpers.ts:151 同语义对齐（commit d214d0d83 验证 steer 能避免
+      // 'Agent is already processing' 错误）。
+    }, { triggerTurn: true, deliverAs: "steer" });
   }
 
   private buildLlmContent(record: BgNotifyRecord): string {

package/src/execution/path-encoding.ts

@@ -32,3 +32,21 @@ export function getSubagentSessionDir(agentDir: string, mainCwd: string): string
   // 本分支未发布，回退到既有布局即无需迁移、无数据丢失。
   return path.join(agentDir, "subagents", encodeCwd(mainCwd), "sessions");
 }
+
+/**
+ * 获取 subagent records（manifest）持久化目录路径。
+ *
+ * 与 getSubagentSessionDir 同用 encodeCwd(mainCwd)，保证 records 与 sessions 在同一
+ * <enc> 段下物理相邻——worktree 场景三者恒等（init.cwd /
+ * buildSessionRunnerContext.mainCwd / record.worktreeHandle.mainCwd 指向同一主 cwd）。
+ *
+ * D-004 同源：用主 cwd 编码做物理隔离，使 session-file-gc 按 <enc>/records/ 子目录
+ * 匹配 manifest .json 时天然限定在当前 cwd 范围内，不会越界清理其他 cwd 的 manifest。
+ *
+ * @param agentDir agent 配置目录（如 ~/.pi/agent）
+ * @param mainCwd 主 agent 的工作目录（非 subagent 的 effectiveCwd）
+ * @returns records 持久化目录绝对路径
+ */
+export function getSubagentRecordsDir(agentDir: string, mainCwd: string): string {
+  return path.join(agentDir, "subagents", encodeCwd(mainCwd), "records");
+}

package/src/execution/pi-invocation.ts

@@ -42,7 +42,7 @@ function isGenericRuntime(execPath: string): boolean {
 /**
  * 组装 pi 子进程的 spawn 调用。
  *
- * @param userArgs pi CLI 参数（如 ["--mode", "json", "-p", "Task: ..."]）
+ * @param userArgs pi CLI 参数（如 ["--mode", "rpc", "--session-dir", "..."]）
  * @returns spawn 描述符（command + 完整 args）
  *
  * 决策链（按优先级）：

package/src/execution/record-store.ts

@@ -12,6 +12,7 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 
 import { getCurrentActivity, getDisplayItems, getEventLog, markReconstructedStatus, snapshot as toSnapshot } from "./execution-record.ts";
+import type { ManifestRecord, ManifestStore } from "./manifest-store.ts";
 import { reconstructFromFile } from "./session-reconstructor.ts";
 import type {
   ExecutionRecord,
@@ -37,7 +38,25 @@ const STATUS_PRIORITY: Record<ExecutionStatus, number> = {
 };
 
 /** .alive sidecar 的 24 小时软超时（超过此时间即使 pid 存活也判 crashed）。 */
-const ALIVE_SOFT_TIMEOUT_MS = 86_400_000; // 24h in ms
+const ALIVE_SOFT_TIMEOUT_MS = 3_600_000; // 1h in ms (reduced from 24h to minimize PID reuse window)
+
+/**
+ * manifest status → ExecutionStatus 运行时守卫映射。
+ *
+ * manifest 写 running/completed/failed/cancelled 四态（ManifestRecord.status union），但磁盘
+ * 文件可能陈旧（含历史 "error" 值、被外部篡改、或意外出现 crashed 值）。越界值返回 null——
+ * manifestToSubagent 据此返回 null，collectRecords 跳过损坏 record 并 console.warn，不因单个
+ * 坏文件崩溃，也不把损坏 record 错误降级为 failed（failed 会触发重试/告警，是误报）。
+ *
+ * 提取为纯函数：同时解决 PR#85 反射问题（三元 + `as ExecutionStatus` cast）。
+ */
+function mapManifestStatus(s: string): ExecutionStatus | null {
+  if (s === "completed") return "done";
+  if (s === "failed") return "failed";
+  if (s === "running") return "running";
+  if (s === "cancelled") return "cancelled";
+  return null; // 越界=数据损坏（含历史 "error"、意外 crashed 值），返回 null 让调用方跳过
+}
 
 /** store 变更监听器（返回取消订阅函数）。 */
 export type ChangeListener = () => void;
@@ -45,6 +64,12 @@ export type ChangeListener = () => void;
 /** status 过滤模式（collectRecords 的核心能力参数）。 */
 export type StatusFilter = "running" | "all";
 
+/** Pi ExtensionAPI 的最小子集（仅 collectRecords 跳过损坏 manifest 时上报用）。
+ *  解构为局部类型，避免与 subagent-service 的 PiLike 循环依赖。 */
+export type RecordStorePi = {
+    appendEntry?: (customType: string, data: unknown) => void;
+} | null | undefined;
+
 // ============================================================
 // RecordStore
 // ============================================================
@@ -62,11 +87,31 @@ export class RecordStore {
   private readonly records = new Map<string, ExecutionRecord>();
   private readonly listeners = new Set<ChangeListener>();
   private _disposed = false;
+  /** Pi handle（用于 appendEntry 上报损坏 manifest）。构造时可空，setPi() 后续注入。
+   *  显式存为字段而非构造参数 readonly：setPi 需要写权限。 */
+  private pi: RecordStorePi = null;
 
   /** 重建缓存：sessionFile → SubagentRecord。notifyChange 时失效。 */
   private reconCache: Map<string, SubagentRecord> | undefined;
 
-  constructor(private readonly sessionsDir: string) {}
+  constructor(
+    private readonly sessionsDir: string,
+    private readonly manifestStore?: ManifestStore,
+    /** Pi 入口（注入 appendEntry 用于上报损坏 manifest）。
+     *  SubagentService 构造时 this.pi 尚未注入（session_start 之前），传 undefined 兜底；
+     *  后续通过 setPi() 注入（见下）。允许 null = 兼容 PiLike 字段类型。 */
+    pi?: RecordStorePi,
+  ) {
+    this.pi = pi ?? null;
+  }
+
+  /** session_start 后由 SubagentService.initSession 调，注入真实 Pi handle。
+   *  设计为独立方法而非要求构造时必传——RecordStore 在 SubagentService 构造时即建
+   *  （与 sessionsDir/manifestStore 一同初始化），但 this.pi 此时尚未注入。
+   *  后续构造期外的 appendEntry 上报才有意义。 */
+  setPi(pi: RecordStorePi): void {
+    this.pi = pi ?? null;
+  }
 
   /** 注册新 record。触发 onChange。 */
   register(record: ExecutionRecord): void {
@@ -154,6 +199,32 @@ export class RecordStore {
       byId.set(rec.id, rec);
     }
 
+    // 1.5 FR-8: manifest 源补充 orphan 记录。
+    // 优先级：内存 > 磁盘重建 > manifest。manifest 仅补充 session.jsonl 重建失败的记录。
+    if (this.manifestStore) {
+      for (const manifest of this.readManifestsSync()) {
+        if (byId.has(manifest.id)) continue; // 已被磁盘/内存源覆盖
+        if (rootSessionFilter !== undefined && manifest.rootSessionId !== rootSessionFilter) continue;
+        const rec = RecordStore.manifestToSubagent(manifest);
+        if (!rec) {
+          // manifest status 越界=数据损坏（含历史 "error"、意外 crashed 值）：跳过而非降级 failed，
+          // 避免损坏 record 被误显示为 failed（触发错误重试/告警）。
+          // 双通道上报：console.warn 给开发者（终端调试）；pi.appendEntry 给用户（session 内可见，
+          // 即使退出后也能从 session.jsonl 复盘事故原因）。SubagentService 构造时 pi 未注入
+          // （session_start 之前），appendEntry 走可选链安全降级。
+          console.warn("[subagents] skip manifest with invalid status:", manifest.id, manifest.status);
+          this.pi?.appendEntry?.("subagent:manifest-invalid-status", {
+            id: manifest.id,
+            status: manifest.status,
+            rootSessionId: manifest.rootSessionId,
+            agentName: manifest.agentName,
+          });
+          continue;
+        }
+        byId.set(rec.id, rec);
+      }
+    }
+
     // 2. 内存源覆盖（running record 优先——它是活态，比磁盘重建更新鲜）。同样按 session 过滤。
     for (const r of this.records.values()) {
       if (rootSessionFilter !== undefined && r.rootSessionId !== rootSessionFilter) continue;
@@ -323,6 +394,41 @@ export class RecordStore {
     return b.startedAt - a.startedAt; // 新→旧
   }
 
+  /** FR-8: 同步读取所有 manifest 记录（封装 ManifestStore.listAllSync，消除反射访问）。 */
+  private readManifestsSync(): readonly ManifestRecord[] {
+    return this.manifestStore?.listAllSync() ?? [];
+  }
+
+  /** FR-8: ManifestRecord → SubagentRecord（manifest 源投影）。
+   *  task/slug/model 从 manifest 真实值投影（配合 writeManifest 补字段），缺失兜底空串。
+   *  status 越界（mapManifestStatus 返回 null）时返回 null，由 collectRecords 跳过。 */
+  private static manifestToSubagent(m: ManifestRecord): SubagentRecord | null {
+    const status = mapManifestStatus(m.status);
+    if (status === null) return null;
+    return {
+      id: m.id,
+      agent: m.agentName,
+      task: m.task ?? "",
+      slug: m.slug ?? "",
+      status,
+      mode: "background" as const,
+      startedAt: m.createdAt,
+      rootSessionId: m.rootSessionId || undefined,
+      parentRecordId: undefined,
+      depth: 0,
+      endedAt: m.completedAt,
+      turns: 0,
+      totalTokens: 0,
+      model: m.model ?? "",
+      thinkingLevel: undefined,
+      eventLog: [],
+      displayItems: [],
+      result: undefined,
+      error: status === "failed" ? "manifest record" : undefined,
+      sessionFile: m.sessionFile,
+    };
+  }
+
   /** ExecutionRecord → SubagentRecord（内存源投影）。 */
   private static recordToSubagent(r: ExecutionRecord): SubagentRecord {
     return {

package/src/execution/session-file-gc.ts

@@ -44,8 +44,11 @@ export function maybeCleanupExpiredSessionFiles(agentDir: string, cwd: string):
   }
 }
 
-/** 递归扫描目录，unlink 超 TTL 的 .jsonl 文件及其 .cancelled sidecar。 */
-function walkAndClean(dir: string, now: number): void {
+/** 递归扫描目录，unlink 超 TTL 的 .jsonl 文件及其 .cancelled sidecar。
+ *  [F2] 进入名为 records 的子目录时，额外清理超 TTL 的 manifest .json（跳过 .tmp.——
+ *  recoverTmpFiles 同步处理）。allowManifestJson 仅由父调用按目录名开启，其他位置
+ *  （如 subagents/worktrees.json）不匹配 .json，避免误删 worktree reaper 状态文件。 */
+function walkAndClean(dir: string, now: number, allowManifestJson = false): void {
   let entries: fs.Dirent[];
   try {
     entries = fs.readdirSync(dir, { withFileTypes: true });
@@ -56,7 +59,26 @@ function walkAndClean(dir: string, now: number): void {
   for (const entry of entries) {
     const full = path.join(dir, entry.name);
     if (entry.isDirectory()) {
-      walkAndClean(full, now);
+      // 只在进入名为 records 的子目录时打开 manifest .json 清理。
+      // records 在 <enc>/records/ 下递归自动覆盖；其他位置（如 subagents/worktrees.json）
+      // 不能匹配 .json——否则会误删 worktree reaper 依赖的状态文件。
+      walkAndClean(full, now, entry.name === "records");
+    } else if (
+      allowManifestJson &&
+      entry.name.endsWith(".json") &&
+      // 跳过 .tmp.：recoverTmpFiles（session_start）同步处理 tmp，GC 不重复。
+      // 不校验内容——30 天 mtime 已是强 orphan 信号，扩展名 + 文件名足够。
+      !entry.name.includes(".tmp.")
+    ) {
+      try {
+        const stat = fs.statSync(full);
+        if (now - stat.mtimeMs > TTL_MS) {
+          fs.unlinkSync(full);
+        }
+      } catch (_e) {
+        // 文件可能已被删除，忽略
+        void _e;
+      }
     } else if (entry.name.endsWith(".jsonl")) {
       try {
         const stat = fs.statSync(full);