@zhushanwen/pi-subagent-workflow 7.0.1 → 7.2.0

package/src/execution/subagent-service.ts

@@ -145,6 +145,19 @@ export interface SubagentServiceSessionInit {
 /** background 优先级（保留 priority 排序机制，单一值）。 */
 const PRIORITY_BACKGROUND = 1000;
 
+/** 跨进程身份贯穿的 env 名（父进程 spawn 子进程时注入，子进程 initSession 读取）。
+ *  仿照 PI_SUBAGENT_FORK_DEPTH 机制，让递归 subagent 的身份（rootSessionId / parentRecordId / depth）
+ *  跨进程传递，使主进程 /subagents 能看到完整递归树（设计见 docs/design/recursive-subagent-visibility.md）。
+ *  语义：env 描述「子进程自己的身份」，不是父的身份（决策 1）。
+ *  [MF-3] 第 4 个 env：真 ROOT 的 cwd（PI_SUBAGENT_ROOT_CWD）。worktree 模式下子进程 spawn cwd =
+ *  checkout 路径，若按各自 cwd 编码落盘目录，深层 record 写到 enc(worktree) 段、ROOT 磁盘重建
+ *  扫不到 → 全树可见性深度 ≥ 2 断裂。子进程经本 env 拿 ROOT cwd，sessions 与 records 两套目录
+ *  统一编码在 enc(ROOT cwd) 段（与身份贯穿同构，见 session-runner 注入点）。 */
+const ENV_ROOT_SESSION_ID = "PI_SUBAGENT_ROOT_SESSION_ID";
+const ENV_SELF_RECORD_ID = "PI_SUBAGENT_SELF_RECORD_ID";
+const ENV_DEPTH = "PI_SUBAGENT_DEPTH";
+const ENV_ROOT_CWD = "PI_SUBAGENT_ROOT_CWD";
+
 /** 触发 onUpdate 的事件类型（streaming delta 不触发，避免每 token 刷新）。 */
 const TRIGGERING_EVENT_TYPES = new Set<AgentEvent["type"]>([
   "tool_start",
@@ -196,8 +209,31 @@ export class SubagentService {
   /** UI 请求可观测性（sessionMode + handler 缺失告警去重，提取自本类降低行数）。 */
   private readonly uiObservability = new UiRequestObservability();
   private pi: PiLike | null = null;
-  /** 当前 Pi session ID（session 隔离过滤用）。initSession 时注入。 */
+  /** 当前 Pi session ID（本进程 pi session，事件路由等用；record 过滤不用它）。initSession 时注入。 */
   private sessionId: string | null = null;
+  /** 所属根 session ID（record 归属过滤用）。根进程 = sessionId（自己是 root）；
+   *  子进程 = env PI_SUBAGENT_ROOT_SESSION_ID 贯穿的真 ROOT（initSession 读取）。
+   *  与 sessionId 正交：sessionId 是本进程 pi session（事件路由等），sessionRootId 是所属根
+   *  （collectRecords filter 用，与 createRecordForMode 的 rootSessionId 盖章同源——子进程
+   *  因此看到整棵 ROOT 树）。设计见 recursive-subagent-visibility.md 决策 3。 */
+  private sessionRootId: string | null = null;
+  /** 进程级执行上下文基线（不依赖 ALS 贯穿——pi RPC mode 的 stdin JSONL 是事件回调式
+   *  （attachJsonlLineReader stream.on("data")），每个命令是独立异步链，initSession 里
+   *  execCtxAls.enterWith 的 store 不会贯穿到后续 tool 调用事件（实测：递归第二层
+   *  parentRecordId/depth 丢失而 rootSessionId 正确——rootSessionId 是实例字段所以不受影响）。
+   *  基线 = 本进程自己的身份（initSession 从 env 读取，与 sessionRootId 同机制）：
+   *  读 ALS store 失败时兜底，保证「本进程派发的 subagent 都是本进程记录的孩子」
+   *  这一跨进程树形关系成立。
+   *  initSession 设置：有 env PI_SUBAGENT_SELF_RECORD_ID → {recordId: env 值, depth: env DEPTH}；
+   *  无 env（根进程）→ null（顶层）。 */
+  private execCtxBaseline: { recordId: string | undefined; depth: number } | null = null;
+  /** fork 深度基线（同 ALS 断裂问题：forkDepthAls.getStore() 兜底用）。根进程=0。 */
+  private forkDepthBaseline = 0;
+  /** [MF-3] 所属根进程 cwd（sessions/records 落盘目录编码键）。
+   *  根进程=自身 cwd（构造时 init.cwd）；子进程=env PI_SUBAGENT_ROOT_CWD 贯穿的真 ROOT cwd。
+   *  worktree 模式下子进程 this.cwd 是 checkout 路径，若按它编码目录，深层 record 落到
+   *  enc(worktree) 段、ROOT 扫描不到 → 全树可见性深度 ≥ 2 断裂（与 sessionRootId 同构）。 */
+  private rootCwd: string;
   /** UI streaming sink（ctx.ui.setWidget）。workflow 域经 getStreamSink() 取用。 */
   private streamSink: StreamSink | null = null;
   /** [竞态修复] 主 agent isIdle 查询（ctx.isIdle）。notifier flush gate 用。
@@ -229,8 +265,15 @@ export class SubagentService {
     this.uiRequestHandler = init.uiRequestHandler;
     this.pool = new DefaultConcurrencyPool(this.modelService.getGlobalConfig().maxConcurrent);
     this.worktreeManager = new WorktreeManager(this.modelService.getAgentDir());
-    const sessionsDir = getSubagentSessionDir(this.modelService.getAgentDir(), init.cwd);
-    const recordsDir = getSubagentRecordsDir(this.modelService.getAgentDir(), init.cwd);
+    // [MF-3] worktree 隔离下全树落盘目录统一到 ROOT cwd：子进程（spawn cwd = worktree checkout 路径）
+    // 若按自身 cwd 编码目录，深层 record 写到 enc(worktree) 段，ROOT 磁盘重建扫不到。
+    // 读 env PI_SUBAGENT_ROOT_CWD（根进程无 env → init.cwd）。sessions 与 records 两套目录
+    // 必须同源（同一 rootCwd），否则 enc 段不变量断裂（只改其一会让同 record 的
+    // session 文件与 manifest 分落两段，GC/重建互相找不到）。
+    const envRootCwd = process.env[ENV_ROOT_CWD];
+    this.rootCwd = envRootCwd && envRootCwd !== "" ? envRootCwd : init.cwd;
+    const sessionsDir = getSubagentSessionDir(this.modelService.getAgentDir(), this.rootCwd);
+    const recordsDir = getSubagentRecordsDir(this.modelService.getAgentDir(), this.rootCwd);
     this.manifestStore = new ManifestStore(recordsDir);
     this.store = new RecordStore(sessionsDir, this.manifestStore, this.pi ?? undefined);
     this.notifier = new BgNotifier(this.piAdapter());
@@ -286,6 +329,32 @@ export class SubagentService {
       const base = Number.parseInt(envDepth, 10);
       if (!Number.isNaN(base) && base > 0) {
         this.forkDepthAls.enterWith(base);
+        this.forkDepthBaseline = base;
+      }
+    }
+    // [递归可见性] 跨进程身份贯穿（设计 recursive-subagent-visibility.md）。
+    // 父进程 spawn 时注入这 4 个 env 描述「子进程自己的身份」：
+    //   - rootSessionId：所属根 session（贯穿真 ROOT，子进程不覆盖）
+    //   - selfRecordId：子进程自己的 record id（孙 subagent 的直接父）
+    //   - depth：子进程的嵌套深度
+    //   - rootCwd：真 ROOT 的 cwd（[MF-3] 落盘目录编码键，worktree 下与自身 cwd 不同）
+    // 子进程读 env 建立基线后，createRecordForMode 读 execCtxAls 自动正确（孙挂到子名下）。
+    // 根进程无 env → sessionRootId = init.sessionId（自己是 root），execCtxAls 不 enterWith（顶层）。
+    // enterWith 贯穿整个 session 生命周期（与 forkDepthAls 同构，决策 4）。
+    const envRoot = process.env[ENV_ROOT_SESSION_ID];
+    this.sessionRootId = envRoot ?? init.sessionId;
+    const envSelfRecord = process.env[ENV_SELF_RECORD_ID];
+    if (envSelfRecord !== undefined && envSelfRecord !== "") {
+      const envNestingDepth = Number.parseInt(process.env[ENV_DEPTH] ?? "0", 10);
+      const nestingDepth = Number.isNaN(envNestingDepth) ? 0 : envNestingDepth;
+      // [ALS 断裂修复] 基线兜底：enterWith 在 pi 事件回调模型下不可靠（见 execCtxBaseline 注释），
+      // 基线是 createRecordForMode / 护栏读 ALS store 失败时的权威回退。
+      this.execCtxBaseline = { recordId: envSelfRecord, depth: nestingDepth };
+      this.execCtxAls.enterWith({ recordId: envSelfRecord, depth: nestingDepth });
+      if (process.env.PI_EXT_DEBUG) {
+        logger.debug(
+          `[subagents] execCtxAls initialized: recordId=${envSelfRecord} depth=${nestingDepth} rootSessionId=${envRoot ?? init.sessionId}`,
+        );
       }
     }
     // revive（dispose 的逆操作：/resume /fork /new 后复活）
@@ -413,7 +482,8 @@ export class SubagentService {
     // 但耗资源且 LLM 易陷入「委派→再委派」死循环。在所有副作用之前拦截，错误直达调用方。
     // 计数基准：顶层 nestingDepth=0，nestingDepth>MAX 被拒。与 fork 体积护栏（parentForkDepth 检查）
     // 互补：本护栏更严（计所有嵌套），混合链下先生效；两者共享 MAX_FORK_DEPTH 上限不漂移。
-    const parentNesting = this.execCtxAls.getStore();
+    // [ALS 断裂修复] getStore() 在 pi 事件回调模型下可能读空（enterWith 不贯穿），基线兜底。
+    const parentNesting = this.execCtxAls.getStore() ?? this.execCtxBaseline;
     const nestingDepth = parentNesting ? parentNesting.depth + 1 : 0;
     if (nestingDepth > MAX_FORK_DEPTH) {
       throw new ForkDepthExceededError(
@@ -421,16 +491,6 @@ export class SubagentService {
       );
     }
 
-    // [MF#7] worktree:true 需要 fork:true——否则下面三个 worktree 分支都不命中，
-    // worktreeHandle 恒 undefined → 子 agent 零文件隔离且零报错（静默 no-op）。此处在
-    // 任何副作用（record 创建 / worktree 创建）之前 fail-fast，不吞误用。
-    if (opts.worktree === true && !opts.fork) {
-      throw new Error(
-        "worktree:true requires fork:true (worktree isolation only applies to forked sessions). " +
-          "Set fork:true together with worktree:true.",
-      );
-    }
-
     // mode 固定 background（sync 模式已删除）
     const mode: ExecutionMode = "background";
     const ctx = this.buildSessionRunnerContext(opts.cwd);
@@ -451,7 +511,7 @@ export class SubagentService {
       // 传入的是已创建的 WorktreeHandle
       worktreeHandle = opts.worktree;
     } else if (opts.worktree === true) {
-      // worktree===true（显式要求）——创建新 worktree。MF#7 已保证此处 fork 必为 true。
+      // worktree===true（显式要求）——创建新 worktree。与 fork 正交（worktree 文件隔离不依赖 fork 上下文继承）。
       try {
         worktreeHandle = this.worktreeManager.create(this.cwd, record.id);
         record.worktreeHandle = worktreeHandle;
@@ -516,7 +576,8 @@ export class SubagentService {
     this.assertReady();
 
     // ── BC-12 嵌套护栏：复用 execute() 的 execCtxAls 深度检查 ──
-    const parentNesting = this.execCtxAls.getStore();
+    // [ALS 断裂修复] getStore() 可能读空，基线兜底（与 execute 同）。
+    const parentNesting = this.execCtxAls.getStore() ?? this.execCtxBaseline;
     const nestingDepth = parentNesting ? parentNesting.depth + 1 : 0;
     if (nestingDepth > MAX_FORK_DEPTH) {
       throw new ForkDepthExceededError(
@@ -524,15 +585,6 @@ export class SubagentService {
       );
     }
 
-    // [MF#7] worktree:true requires fork:true — symmetric with execute() guard.
-    // Fails fast before any side effect (record creation / worktree creation).
-    if (opts.worktree === true && !opts.fork) {
-      throw new Error(
-        "worktree:true requires fork:true (worktree isolation only applies to forked sessions). " +
-          "Set fork:true together with worktree:true.",
-      );
-    }
-
     // ── 步骤 1: IDENTITY 解析 ──
     const identity = await this.resolveIdentity(opts);
 
@@ -543,8 +595,8 @@ export class SubagentService {
     // ── 步骤 2.5: worktree creation (only worktree===true; handle injection is execute()'s path) ──
     // Workflow path receives boolean only (AgentCallOpts.worktree: boolean) — WorktreeHandle is a
     // main-thread non-serializable object that cannot cross worker postMessage, so no object branch
-    // here (unlike execute() :445-447 which serves the subagent-tool path). MF#7 guard above ensures
-    // fork===true when worktree===true. On create failure, finalizeFailed cleans up the record, then
+    // here (unlike execute() :445-447 which serves the subagent-tool path).
+    // On create failure, finalizeFailed cleans up the record, then
     // throw lets SAR.run() convert it to an AgentResult.error (not return-handle like execute()).
     let worktreeHandle: WorktreeHandle | undefined;
     if (opts.worktree === true) {
@@ -618,9 +670,10 @@ export class SubagentService {
   }
 
   /** 合并内存(running) + 磁盘(session.jsonl 重建) record（/subagents list + tool list 消费）。
-   *  按 rootSessionId 过滤，只返回当前 session 创建的 record（session 隔离）。 */
+   *  按 rootSessionId 过滤：根进程=本 session（sessionRootId===sessionId）；
+   *  子进程=env 贯穿的真 ROOT（sessionRootId≠sessionId）→ 看到整棵 ROOT 树（决策 3）。 */
   collectRecords(limit: number, statusFilter: StatusFilter = "all"): SubagentRecord[] {
-    return this.store.collectRecords(limit, statusFilter, this.sessionId ?? undefined);
+    return this.store.collectRecords(limit, statusFilter, this.sessionRootId ?? this.sessionId ?? undefined);
   }
 
   // ── 执行内部：身份解析 + record 创建 ──────────
@@ -657,7 +710,9 @@ export class SubagentService {
     // 从 async 调用链读父执行上下文：主 session 链上无 store → 顶层 record；
     // B run() 期间包了 execCtxAls，B 内创建 C 时读到 B → C.parentRecordId=B.id, C.depth=B.depth+1。
     // depth 语义：顶层（无父）=0；有父=父 depth+1。靠 recordId 是否存在区分，不用负数魔数。
-    const parentCtx = this.execCtxAls.getStore();
+    // [ALS 断裂修复] getStore() 在 pi 事件回调模型下可能读空（enterWith 不贯穿），
+    // 基线兜底——本进程的身份在 initSession 已确定（env 注入），任何上下文下都能正确挂父链。
+    const parentCtx = this.execCtxAls.getStore() ?? this.execCtxBaseline;
     const parentRecordId = parentCtx?.recordId;
     const depth = parentCtx ? parentCtx.depth + 1 : 0;
 
@@ -669,7 +724,7 @@ export class SubagentService {
       task: opts.task,
       slug: opts.slug,
       startedAt: Date.now(),
-      rootSessionId: this.sessionId ?? undefined,
+      rootSessionId: this.sessionRootId ?? undefined,
       parentRecordId,
       depth,
       controller,
@@ -724,7 +779,7 @@ export class SubagentService {
       worktreeHandle = opts.worktree;
     }
     // [MF#4][MF#2] fork 深度护栏：ALS 传递深度（主 session 链无 store→0，fork 推进 +1）。
-    const parentDepth = this.forkDepthAls.getStore() ?? 0;
+    const parentDepth = this.forkDepthAls.getStore() ?? this.forkDepthBaseline;
     const effectiveDepth = opts.fork ? parentDepth + 1 : parentDepth;
 
     let result: AgentResult;
@@ -1001,6 +1056,15 @@ export class SubagentService {
       dialogQueue: this.dialogQueue,
       // 主进程运行模式：session-runner W4 守卫据此决定是否注入 ask_user RPC 提示词。
       mode: this.uiObservability.getMode(),
+      // [递归可见性] 透传所属根 session（runSpawn 注入为子进程 env PI_SUBAGENT_ROOT_SESSION_ID）。
+      // sessionRootId 在 initSession 设定（根进程=sessionId，子进程=env 贯穿的真 ROOT）。
+      // execute/executeAndAwait 调本方法前必经 initSession，此时 sessionRootId 已非空；
+      // ?? 兑底防类型漂移（运行时不可达）。
+      sessionRootId: this.sessionRootId ?? this.sessionId ?? "",
+      // [MF-3] 透传 ROOT cwd（runSpawn 落盘目录编码键 + 注入子进程 env PI_SUBAGENT_ROOT_CWD）。
+      // worktree 模式下 mainCwd = 本进程 checkout 路径，rootCwd 才是真 ROOT——session 文件
+      // 落盘统一用 rootCwd 编码，ROOT 磁盘重建才扫得到深层 record（与 sessionRootId 同构）。
+      rootCwd: this.rootCwd,
     };
   }
 }

package/src/execution/types.ts

@@ -231,7 +231,7 @@ export interface AgentResult {
  */
 /**
  * worktree handle 值对象。仅 worktree:true 时持有——worktree 是独立维度，
- * 需显式开启（且要求 fork:true），fork alone 不创建 worktree。
+ * 需显式开启，fork alone 不创建 worktree。
  * Object.freeze 守卫保证不可变。
  */
 export interface WorktreeHandle {
@@ -339,7 +339,7 @@ export interface ExecutionRecord {
   /** session jsonl 文件名。session 创建成功后由 session-runner.run() 回填（窗口期内 undefined）。 */
   sessionFile?: string;
 
-  /** [MF#3] fork+worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
+  /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
   patchFile?: string;
 
   /** worktree 隔离时的 handle（仅 worktree:true 时存在；fork alone 无此字段）。 */
@@ -383,7 +383,7 @@ export interface SubagentToolDetails {
   parsedOutput?: unknown;
   /** session jsonl 文件名（不含目录）。窗口期内可能 undefined（session 尚未创建成功）。 */
   sessionFile?: string;
-  /** [MF#3] fork+worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
+  /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
   patchFile?: string;
 }
 
@@ -419,7 +419,7 @@ export interface ExecuteOptions {
   onComplete?: (record: RecordSnapshot) => void;
   /** 是否继承父会话上下文（fork 模式，只继承上下文）。 */
   fork?: boolean;
-  /** 文件系统隔离：true=创建新 git worktree（要求 fork:true），WorktreeHandle=复用外部已创建的；undefined=不隔离（parent cwd）。 */
+  /** 文件系统隔离：true=创建新 git worktree，WorktreeHandle=复用外部已创建的；undefined=不隔离（parent cwd）。 */
   worktree?: boolean | WorktreeHandle;
   /** 覆盖执行 cwd（默认 mainCwd）。 */
   cwd?: string;
@@ -527,7 +527,7 @@ export interface SubagentRecord {
   result?: string;
   error?: string;
   sessionFile?: string;
-  /** [MF#3] fork+worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
+  /** [MF#3] worktree 模式下子 agent 改动的 patch 文件路径（worktree 外，供调用方应用）。 */
   patchFile?: string;
   /** 外部 Pi 实例（进程隔离模式下由外部启动的子进程）。 */
   externalInstance?: AliveMarker;

package/src/interface/bg-notify-render.ts

@@ -57,7 +57,7 @@ interface BgNotifyRecord {
   model?: string;
   result?: string;
   error?: string;
-  /** [MF#1] fork+worktree background 完成通知携带的 patch 文件路径。 */
+  /** [MF#1] worktree background 完成通知携带的 patch 文件路径。 */
   patchFile?: string;
 }
 
@@ -275,7 +275,7 @@ function extractBgNotifyRecord(details: unknown): BgNotifyRecord | undefined {
     model: typeof d.model === "string" ? d.model : undefined,
     result: typeof d.result === "string" ? d.result : undefined,
     error: typeof d.error === "string" ? d.error : undefined,
-    // [MF#1] 提取 patchFile（fork+worktree background 完成通知携带）。
+    // [MF#1] 提取 patchFile（worktree background 完成通知携带）。
     patchFile: typeof d.patchFile === "string" ? d.patchFile : undefined,
   };
 }

package/src/interface/subagent-actions.ts

@@ -226,7 +226,21 @@ export async function cancelHandler(
 
   // step 1: id 不存在（findRecord 只查内存 running record，不从 session.jsonl 重建）
   const rec = service.findRecord(id);
-  if (!rec) throw new Error(`No subagent record with id "${id}". It may have finished — use action:'list' with includeFinished:true to verify.`);
+  if (!rec) {
+    // [S-19] MF-1 全树可见后，list/completion 可能列出其他进程（父/兄弟）的 running record
+    //（collectRecords 扫共享 sessionsDir 按 rootSessionId 过滤，跨进程互相可见），而 cancel
+    // 只作用于本进程内存 record。区分两种失败，避免「may have finished」误导（该 record 正
+    // 被列出且未 finished，只是不属于本进程内存）。仅文案区分，不改 cancel 作用域。
+    const treeRec = service.collectRecords(DEFAULT_LIST_LIMIT, "all").find((r) => r.id === id);
+    if (treeRec && treeRec.status === "running") {
+      throw new Error(
+        `Subagent record "${id}" is running but owned by another process in the tree ` +
+          `(it was spawned by a different subagent process) — this process cannot cancel it; ` +
+          `cancel only works for subagents spawned by the current process.`,
+      );
+    }
+    throw new Error(`No subagent record with id "${id}". It may have finished — use action:'list' with includeFinished:true to verify.`);
+  }
   // step 2: controller 检查（controller 为 undefined 表示 record 已终态或未启动）
   if (rec.mode !== "background") {
     throw new Error(`Cannot cancel subagent ${id} (unsupported mode: ${rec.mode})`);

package/src/interface/subagent-tool.ts

@@ -105,10 +105,10 @@ const SubagentParams = Type.Object({
     description: "Extra turns allowed after maxTurns is reached before SIGTERM (default 2). Only meaningful when maxTurns is set.",
   })),
   fork: Type.Optional(Type.Boolean({
-    description: "Fork mode: inherit the parent's conversation context. When true, the subagent receives the parent's session file via --fork and builds a branched conversation (it sees prior turns/messages). The subagent still runs in a separate spawned child process (process isolation) — fork is about context inheritance, not process sharing. Use worktree:true (requires fork:true) for file-system isolation.",
+    description: "Fork mode: inherit the parent's conversation context. When true, the subagent receives the parent's session file via --fork and builds a branched conversation (it sees prior turns/messages). The subagent still runs in a separate spawned child process (process isolation) — fork is about context inheritance, not process sharing; independent of worktree (file-system isolation, see worktree param). When to use: only when the task extends from the parent and genuinely needs key information from the parent's conversation history that a self-contained task prompt cannot carry — most tasks a plain prompt can describe do NOT need fork, so keep false by default and enable only when the user explicitly asks or the task truly depends on seeing prior turns. Caveat: fork drags in the parent's dispatch records and unrelated task context, polluting the subagent (it cannot tell 'context meant for me' from 'parent dispatching me'); when state lives in an external store the subagent can query (e.g., cw handoff), prefer that over fork.",
   })),
   worktree: Type.Optional(Type.Boolean({
-    description: "Worktree isolation (requires fork:true): run the subagent in a dedicated git worktree, providing file-system level isolation from the parent session. Prevents concurrent file-write conflicts between parent and subagent. Only takes effect when fork:true; passing worktree:true without fork:true throws an error.",
+    description: "Worktree isolation: run the subagent in a dedicated git worktree, providing file-system level isolation from the parent session (prevents concurrent file-write conflicts). Independent of fork — worktree may be combined with fork:false (file isolation does not require context inheritance). When to use: parallel development scenarios where multiple agents write files concurrently and need isolated working directories (each gets its own checkout; merge later); leave false for single-agent or read-only tasks.",
   })),
   cwd: Type.Optional(Type.String({
     description: 'Override the working directory for the subagent execution. Must be an absolute path. Defaults to the parent session\'s cwd.',

package/src/interface/subagents.ts

@@ -32,7 +32,7 @@ export function registerSubagentsCommand(pi: ExtensionAPI): void {
         try {
           const service = getSubagentService();
           if (!service) return null;
-          // collectRecords 合并内存(running) + 磁盘重建 record，按 session 过滤。
+          // collectRecords 合并内存(running) + 磁盘重建 record，按 rootSessionId 过滤。
           // cancel 只对 running 有效，但全部列出便于用户辨认（终态 record 会被 service 拒绝）。
           const records = service.collectRecords(LIST_LIMIT);
           if (records.length === 0) return null;

package/src/orchestration/__tests__/jsonl-run-store-session-file.test.ts

@@ -175,3 +175,55 @@ describe("W2: RunStore.stateFilePath 暴露 run 状态文件路径", () => {
     expect(result).toBe(path.join(tmpDir, "workflow-state", "run-xyz.jsonl"));
   });
 });
+
+// W3: save 兜底容错——run 工作目录被并发清理时 mkdir 抛 ENOENT，save 静默返回。
+//
+// 防的 bug（PR #166 CI 回归）：review-fix-loop-e2e 等 runAndWait 测试中，
+// handleReturn 的 run.transition("done") 同步改 status 后，runAndWait 轮询发现 done
+// 并 resolve，测试 afterEach 随即 rmSync 删除 sessionDir；此时 handleReturn 内 in-flight
+// 的 await save 尚未完成，mkdir 遇到目录链被并发删除 → ENOENT。原实现 await save 让错误
+// 冒泡为 unhandled promise rejection（worker-host onMessage 无 catch），CI exit 1。
+// 修复：save 仅容错 ENOENT（run 已终态，状态不再变化，持久化无意义也无法完成）→ silent return；
+// 非 ENOENT 错误（EACCES/ENOSPC 等真实磁盘问题）仍重新抛出，不掩盖。
+//
+// 注：真正的 ENOENT 只在 rmSync 与 mkdir 并发时出现（串行 rmSync 后 mkdir {recursive:true}
+// 会重建目录而非抛 ENOENT），故用 mock 直接锁定 save 的容错判定逻辑，不依赖竞态时序复现。
+describe("W3: JsonlRunStore.save 兜底容错（run 工作目录被并发清理时的竞态）", () => {
+  let tmpDir: string;
+  let store: JsonlRunStore;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "wf-store-enoent-"));
+    store = new JsonlRunStore({ sessionDir: tmpDir });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("mkdir 抛 ENOENT（sessionDir 被并发清理）→ save 静默返回，不抛 unhandled rejection", async () => {
+    const run = makeRunWithDoneCall();
+    const spy = vi
+      .spyOn(fs.promises, "mkdir")
+      .mockRejectedValueOnce(
+        Object.assign(new Error("ENOENT: no such file or directory, mkdir"), {
+          code: "ENOENT",
+        }),
+      );
+    // run 已终态 + 工作目录消失 → save 放弃持久化，resolve undefined（不抛）
+    await expect(store.save(run)).resolves.toBeUndefined();
+    expect(spy).toHaveBeenCalled();
+  });
+
+  it("mkdir 抛非 ENOENT 错误（EACCES）→ save 重新抛出，不掩盖真实磁盘问题", async () => {
+    const run = makeRunWithDoneCall();
+    const spy = vi
+      .spyOn(fs.promises, "mkdir")
+      .mockRejectedValueOnce(
+        Object.assign(new Error("permission denied"), { code: "EACCES" }),
+      );
+    await expect(store.save(run)).rejects.toThrow("permission denied");
+    expect(spy).toHaveBeenCalled();
+  });
+});

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

@@ -241,7 +241,26 @@ export class JsonlRunStore {
  */
   async save(run: WorkflowRun): Promise<void> {
     const filePath = this.filePathFor(run.runId);
-    await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    // 兜底容错：run 工作目录（sessionDir）已被清理时，mkdir 抛 ENOENT，save 放弃。
+    // 竞态场景（review-fix-loop-e2e 等 runAndWait 测试）：handleReturn 内
+    // run.transition("done") 同步改 status 后，runAndWait 轮询发现 done 并 resolve，
+    // 测试 afterEach 随即 rmSync 删除 sessionDir；此时本方法 in-flight 的 mkdir
+    // 遇到目录链已删除 → ENOENT（{recursive:true} 在并发 rmSync 下仍可抛 ENOENT）。
+    // run 既已终态（状态不再变化），持久化无意义也无法完成 → silent return。
+    // 仅容错 ENOENT，重新抛出其他错误（EACCES/ENOSPC 等真实磁盘问题不掩盖）。
+    try {
+      await fs.promises.mkdir(path.dirname(filePath), { recursive: true });
+    } catch (err) {
+      if (
+        typeof err === "object" &&
+        err !== null &&
+        "code" in err &&
+        (err as { code: unknown }).code === "ENOENT"
+      ) {
+        return;
+      }
+      throw err;
+    }
     const snapshot = serializeRun(run);
     await fs.promises.writeFile(filePath, JSON.stringify(snapshot) + "\n", "utf8");
     if (this.pi) {

package/src/orchestration/models/types.ts

@@ -142,9 +142,9 @@ export interface AgentCallOpts {
  * undefined 时 spawn 继承 workflow 进程的 cwd（向后兼容）。
  */
   cwd?: string;
-  /** Inherit parent session context (fork mode). Required when worktree isolation is enabled. */
+  /** Inherit parent session context (fork mode). Independent of worktree (file isolation). */
   fork?: boolean;
-  /** Filesystem isolation: when true, creates a new git worktree for the agent (requires fork: true). */
+  /** Filesystem isolation: when true, creates a new git worktree for the agent. Independent of fork. */
   worktree?: boolean;
   /** When true, agent() resolves {value, sessionFile, worktreePath, error} instead of a bare value.
    * Worker-layer flag only — not forwarded to ExecuteOptions (mapToExecuteOptions drops it). */