@zhushanwen/pi-subagent-workflow 0.1.0 → 0.3.0

package/src/execution/finalize-record.ts

@@ -0,0 +1,160 @@
+// src/execution/finalize-record.ts
+//
+// 时序收尾逻辑（从 subagent-service.ts 提取，降低主文件行数 < 1000 上限）。
+//
+// D-017 时序：collectPatch → completeRecord → archive → cleanup(finalized+worktree+
+// aliveMarker+pending注销) → manifest(最后 best-effort)。
+//
+// [Critical #1 / PR #85] cleanup 全部在 manifest 写之前执行——manifest 是诊断辅助
+//（orphan recovery），写失败仅记录不阻断。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup，
+// 导致磁盘满/权限错时 worktree 泄漏 + finalized marker 不写 + alive marker 残留 +
+// pending 记账错乱。现 manifest 写移到 Step 4（最后），best-effort（console.error +
+// appendEntry，不 throw）。
+//
+// B9 兜底：completeRecord/archive 抛错→后续 cleanup/manifest 仍执行。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import { removeAliveMarker } from "./alive-store.ts";
+import { bestEffort } from "./best-effort.ts";
+import { completeRecord } from "./execution-record.ts";
+import { writeFinalized } from "./finalized-marker.ts";
+import type { ManifestStore } from "./manifest-store.ts";
+import type { ModelConfigService } from "./model-config-service.ts";
+import { getSubagentSessionDir } from "./path-encoding.ts";
+import type { RecordStore } from "./record-store.ts";
+import { writeCancelledTombstone } from "./tombstone-store.ts";
+import type { AgentResult, ExecutionRecord } from "./types.ts";
+import type { WorktreeManager } from "./worktree-manager.ts";
+
+/** doFinalizeRecord 的依赖（从 SubagentService 注入，避免 this 绑定 + 解耦可测试）。 */
+export interface FinalizeDeps {
+  manifestStore: ManifestStore;
+  worktreeManager: WorktreeManager;
+  store: RecordStore;
+  modelService: ModelConfigService;
+  /** Pi ExtensionAPI（仅用 appendEntry 记录 manifest 写失败事件）。null 在 dispose 后。 */
+  pi: { appendEntry?: (type: string, data: unknown) => void } | null;
+  /** 清节流状态（防 trailing timer 在 record 归档后误发陈旧 onUpdate）。 */
+  clearThrottle(id: string): void;
+  /** pending-notifications 终态注销（绑定 pi.events.emit，由调用方闭包提供）。 */
+  emitUnregister(id: string, status: string): void;
+}
+
+/**
+ * 时序收尾（D-017）。步骤 0→4 全部 best-effort 互不阻断（除 manifest 外都幂等）。
+ *
+ * [Critical #1] Step 3 cleanup 全部在 Step 4 manifest 之前——manifest 写失败仅 console.error +
+ * appendEntry，不 throw 不跳过 cleanup。task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord
+ * 补字段），manifestToSubagent 投影真实值而非硬编码空串。
+ */
+export async function doFinalizeRecord(
+  deps: FinalizeDeps,
+  record: ExecutionRecord,
+  result: AgentResult,
+  status: "done" | "failed" | "cancelled",
+): Promise<void> {
+  // 终态清节流状态：防 trailing timer 在 record 归档后误发陈旧 onUpdate
+  deps.clearThrottle(record.id);
+
+  // ── Step 0: collectPatch（best-effort）──
+  // [MF#3] patchFile 写到 worktree 之外（sessionsDir/<branch>.patch），避免被 cleanup 删除；
+  //        路径回填 record.patchFile，供调用方（tool result / /subagents list）应用。
+  if (record.worktreeHandle) {
+    try {
+      const sessionsDir = getSubagentSessionDir(
+        deps.modelService.getAgentDir(),
+        record.worktreeHandle.mainCwd,
+      );
+      fs.mkdirSync(sessionsDir, { recursive: true });
+      const patchFile = path.join(sessionsDir, `${record.worktreeHandle.branch}.patch`);
+      const patch = deps.worktreeManager.collectPatch(record.worktreeHandle, patchFile);
+      if (patch.written) record.patchFile = patchFile;
+    } catch (pe: unknown) {
+      bestEffort(pe, "collectPatch (finalizeRecord Step0)");
+    }
+  }
+
+  // ── Step 1: completeRecord（B9: 抛错→后续仍执行）──
+  try {
+    completeRecord(record, result, status);
+  } catch (err) {
+    bestEffort(err, "completeRecord (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 2: archive（B9: 抛错→后续仍执行）──
+  try {
+    deps.store.archive(record);
+  } catch (err) {
+    bestEffort(err, "store.archive (finalizeRecord B9)", "error");
+  }
+
+  // ── Step 3: finalized + cleanup + aliveMarker + pending注销（全部先执行，幂等）──
+  // [Critical] 清理必须在 manifest 写入之前：worktree cleanup / finalized marker / aliveMarker
+  //   都是幂等且不可跳过的副作用。绝不能因 manifest 写失败而跳过 worktree cleanup
+  //   （否则 worktree 泄漏）。各件独立 try/catch，互不阻断。
+  if (record.sessionFile) {
+    try {
+      // MF-1 fix: cancelled 状态写 tombstone 而非 finalized，防重建丢失 cancelled
+      if (status === "cancelled") {
+        writeCancelledTombstone(record.sessionFile, {
+          id: record.id,
+          status: "cancelled",
+          agent: record.agent,
+          startedAt: record.startedAt,
+          endedAt: record.endedAt ?? Date.now(),
+        });
+      } else {
+        writeFinalized(record.sessionFile);
+      }
+    } catch (err) {
+      bestEffort(err, "writeFinalized/tombstone (finalizeRecord Step3)");
+    }
+  }
+  if (record.worktreeHandle) {
+    try {
+      deps.worktreeManager.cleanup(record.worktreeHandle);
+    } catch (err) {
+      bestEffort(err, "worktree cleanup (finalizeRecord Step3)");
+    }
+  }
+  if (record.sessionFile) {
+    try {
+      removeAliveMarker(record.sessionFile);
+    } catch (err) {
+      bestEffort(err, "removeAliveMarker (finalizeRecord Step3)");
+    }
+  }
+
+  // pending-notifications：终态注销（只记 registry 状态，通知由 BgNotifier 发）
+  deps.emitUnregister(record.id, status);
+
+  // ── Step 4 (last): manifest 持久化（best-effort，不阻断、不 throw）──
+  // [Critical #1] manifest 是诊断辅助（orphan recovery），不是正确性依赖。写失败时
+  //   仅记录（console.error + appendEntry），绝不让 manifest 写失败跳过上面的 worktree
+  //   cleanup 或抛出打断 finalize 链。旧实现 Step 2.5 throw 会跳过 Step 3 cleanup。
+  //   task/slug/model 从 ExecutionRecord 抓取（配合 ManifestRecord 补字段），
+  //   manifestToSubagent 投影时用真实值而非硬编码空串。
+  try {
+    await deps.manifestStore.writeManifest({
+      id: record.id,
+      rootSessionId: record.rootSessionId ?? "",
+      agentName: record.agent,
+      status: status === "done" ? "completed" : status,
+      createdAt: record.startedAt,
+      completedAt: record.endedAt ?? Date.now(),
+      sessionFile: record.sessionFile,
+      task: record.task,
+      slug: record.slug,
+      model: record.model,
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`[subagent] manifest 写入失败 (record=${record.id}): ${msg}`);
+    deps.pi?.appendEntry?.("subagent:manifest-write-failed", {
+      id: record.id,
+      error: msg,
+    });
+  }
+}

package/src/execution/get-state-handshake.ts

@@ -0,0 +1,104 @@
+// src/execution/get-state-handshake.ts
+//
+// FR-4: get_state RPC 握手逻辑。
+//
+// 从 session-runner.ts 提取（保持文件 < 1000 行）。职责单一：通过 get_state RPC
+// 查询子进程 sessionFile/sessionId，带超时重试。session-runner spawn 后无条件调用。
+//
+// 设计要点：
+//   - 重试节奏：单次超时 GET_STATE_TIMEOUT_MS（2s）后，等 GET_STATE_RETRY_INTERVAL_MS（500ms）
+//     再发起下一次 get_state，最多 GET_STATE_MAX_RETRIES（3）次。修复点：旧实现超时后
+//     立即递归 tryOnce()，GET_STATE_RETRY_INTERVAL_MS 声明了却从未使用（eslint error 阻断），
+//     现在让常量名与行为一致——重试前真的等间隔。
+//   - 加速路径：sessionFile 一旦拿到立即 resolve（不等剩余重试）。
+//   - 全部超时：resolve 空对象（调用方走兜底查找）。
+
+import type { ChildProcess } from "node:child_process";
+
+import { sendGetStateCommand } from "./stdin-writer.ts";
+
+/** FR-4: get_state RPC 握手最大重试次数。 */
+const GET_STATE_MAX_RETRIES = 3;
+/** FR-4: get_state RPC 握手重试间隔（ms）——单次超时后等待此间隔再重试。 */
+const GET_STATE_RETRY_INTERVAL_MS = 500;
+/** FR-4: get_state RPC 握手单次超时（ms）。 */
+const GET_STATE_TIMEOUT_MS = 2000;
+
+/** get_state 握手结果。 */
+export interface GetStateResult {
+  sessionFile?: string;
+  sessionId?: string;
+}
+
+/**
+ * FR-4: 通过 get_state RPC 查询子进程获取 sessionFile/sessionId。
+ *
+ * 当 stdout header 未获取到 sessionFile 时，尝试通过 get_state RPC 查询。
+ * 最多重试 GET_STATE_MAX_RETRIES 次，单次超时 GET_STATE_TIMEOUT_MS 后等待
+ * GET_STATE_RETRY_INTERVAL_MS 再发起下一次重试。
+ *
+ * @param child 子进程（stdin 写入 get_state 命令）
+ * @param addResponseListener 注册 response 监听器的函数（stdout pump 中调用）
+ * @returns 握手结果（可能为空——所有重试均超时/失败）
+ */
+export function performGetStateHandshake(
+  child: ChildProcess,
+  addResponseListener: (id: string, resolver: (data: unknown) => void) => void,
+): Promise<GetStateResult> {
+  return new Promise<GetStateResult>((resolve) => {
+    const collected: GetStateResult = {};
+    let attempts = 0;
+    let resolved = false;
+
+    function tryOnce(): void {
+      if (resolved) return;
+      attempts++;
+      const reqId = sendGetStateCommand(child);
+
+      // [#15] 本次 tryOnce 私有的 timer（2s 超时 + 超时后派生的 retry）。
+      // 关键：response 回调通过闭包引用的是"本次 tryOnce 对应的 timer"，而非某个
+      // 外层共享变量——即便后续 tryOnce(#2) 重新发起请求，旧 reqId 的迟到 response 回调
+      // 闭包仍指向它自己那次 tryOnce 的 timer，不会误清新 reqId 的 timer。retry 句柄也
+      // 一并捕获，response 到达时同步取消"已在排队但尚未触发的下一次重试"。
+      let pendingRetry: ReturnType<typeof setTimeout> | undefined;
+      const timer: ReturnType<typeof setTimeout> = setTimeout(() => {
+        pendingRetry = undefined;
+        // 单次超时：等待间隔后重试，或放弃
+        if (attempts < GET_STATE_MAX_RETRIES && !resolved) {
+          // [Bug fix] 旧实现直接 tryOnce() 立即重试，GET_STATE_RETRY_INTERVAL_MS 声明却
+          // 从未使用（eslint error 阻断 commit）。现在重试前等待间隔，让常量名与行为一致。
+          pendingRetry = setTimeout(() => tryOnce(), GET_STATE_RETRY_INTERVAL_MS);
+          pendingRetry.unref();
+        } else if (!resolved) {
+          resolved = true;
+          resolve(collected);
+        }
+      }, GET_STATE_TIMEOUT_MS);
+      timer.unref();
+
+      addResponseListener(reqId, (data: unknown) => {
+        if (resolved) return;
+        // [#15] 闭包清理本次 tryOnce 的 timer（2s 超时 + 排队中的 retry），不碰其他 reqId 的 timer。
+        clearTimeout(timer);
+        if (pendingRetry) clearTimeout(pendingRetry);
+        if (data && typeof data === "object") {
+          const d = data as Record<string, unknown>;
+          if (typeof d.sessionFile === "string" && d.sessionFile.length > 0) {
+            collected.sessionFile = d.sessionFile;
+          }
+          if (typeof d.sessionId === "string" && d.sessionId.length > 0) {
+            collected.sessionId = d.sessionId;
+          }
+        }
+        // sessionFile 已获取——立即 resolve（无需更多重试）
+        if (collected.sessionFile) {
+          resolved = true;
+          resolve(collected);
+        }
+        // 否则等待超时重试
+      });
+    }
+
+    tryOnce();
+  });
+}

package/src/execution/host-mode.ts

@@ -0,0 +1,52 @@
+// src/execution/host-mode.ts
+//
+// 主进程运行模式分类工具。
+//
+// 将 Pi 的 ExtensionMode（"tui"|"rpc"|"json"|"print"）聚合为业务语义的
+// HostMode（"tui"|"gui"|"headless"），供 session-runner 的 W4 提示词守卫、
+// handler 工厂分流、stdio 选择等消费点统一调用。
+//
+// 判定依据见 AGENTS.md「运行时环境区分」章节 +
+// docs/pi-tui-development-guide.md 第四部分第 8 节。
+// ExtensionMode 来自 Pi 源码 packages/coding-agent/src/core/extensions/types.ts:299
+// （dist 中 core/extensions/types.d.ts:207）。
+//
+// 设计动机（.fix-plans/00-master-summary.md §一冲突 4）：
+//   - 把散落多处的 `ctx.mode === "tui" || ctx.mode === "rpc"` 字面量比较
+//     集中到单一修改点，未来 Pi 新增 mode 值时只改本文件。
+//   - 业务语义命名（"gui"/"headless"）比原始枚举值更清晰表达意图。
+
+import type { ExtensionMode } from "@mariozechner/pi-coding-agent";
+
+/** 主进程运行模式分类。基于 ExtensionMode 聚合为业务语义。
+ *  - "tui"：纯 Pi TUI，ctx.ui.custom 可用，用户在终端交互
+ *  - "gui"：xyz-agent GUI，通过 rpc sidecar 通道与前端 Vue 组件交互
+ *  - "headless"：无交互 UI 通道（json/print 输出模式，或 mode 未穿透） */
+export type HostMode = "tui" | "gui" | "headless";
+
+/** 从 ExtensionContext.mode 解析主进程模式分类。
+ *  - "tui" → tui（纯 Pi TUI，ctx.ui.custom 可用）
+ *  - "rpc" → gui（xyz-agent GUI，sidecar 通道可用）
+ *  - "json"/"print"/undefined → headless（无交互通道）
+ *
+ *  undefined 归入 headless 是向后兼容：mode 未穿透 SessionRunnerContext 时
+ *  按「无 UI」保守处理，避免误注入依赖 UI 的逻辑。 */
+export function resolveHostMode(mode: ExtensionMode | undefined): HostMode {
+  if (mode === "tui") return "tui";
+  if (mode === "rpc") return "gui";
+  return "headless"; // json/print/undefined
+}
+
+/** 主进程是否会响应子进程的 ask_user（UI 透传）。
+ *  tui + gui 都会（冲突 3 裁决：TUI 必须注入 handler；GUI 透传所有 UI），
+ *  headless 不会（无 UI 通道，注入 W4 提示词会误导 LLM）。 */
+export function willRespondToAskUser(mode: ExtensionMode | undefined): boolean {
+  const host = resolveHostMode(mode);
+  return host === "tui" || host === "gui";
+}
+
+/** 主进程是否有交互 UI 通道（TUI 组件 / GUI sidecar）。
+ *  非 headless 即有。用于 stdio 选择等不区分 tui/gui 的决策点。 */
+export function hasInteractiveUI(mode: ExtensionMode | undefined): boolean {
+  return resolveHostMode(mode) !== "headless";
+}

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）
  *
  * 决策链（按优先级）：