@zhushanwen/pi-subagent-workflow 0.1.0

package/src/execution/output-collector.ts

@@ -0,0 +1,88 @@
+// src/core/output-collector.ts
+//
+// 结果收集器（Record + CollectResultArgs → AgentResult）。
+//
+// 收口设计（2026-06-22）：collectResult 全部从 record 读——
+//   text ← getFullText(record)（聚合 turns[].text，不再读 session.messages）
+//   turns ← record.turnCount
+//   toolCalls ← getAllToolCalls(record)（扁平化 turns[].toolCalls）
+//   usage ← getTotalUsage(record)（聚合 turns[].usageDelta）
+//
+// 基础层模块：依赖 execution-record（派生函数）+ types。
+
+import type {
+  AgentResult,
+  ExecutionRecord,
+  ToolCall,
+} from "./types.ts";
+import {
+  getAllToolCalls,
+  getFullText,
+  getTotalUsage,
+} from "./execution-record.ts";
+
+// ============================================================
+// Result 收集
+// ============================================================
+
+/** collectResult 的入参（session 身份 + 执行控制字段，执行内容从 record 读）。 */
+export interface CollectResultArgs {
+  startTime: number;
+  success: boolean;
+  error: string | undefined;
+  sessionId: string;
+  sessionFile: string | undefined;
+}
+
+/** structured-output tool 名（与 structured-output 扩展 TOOL_NAME 一致，见 session-runner.ts）。 */
+const STRUCTURED_OUTPUT_TOOL = "structured-output";
+
+/**
+ * 从 toolCalls 提取 structured-output 的 result.details（schema 模式产出）。
+ * schema enforcement 保证 agent 调过该 tool（漏调会 steer 重试）；这里只做逆向提取。
+ * 未调或无 details 返回 undefined。
+ *
+ * 导出以便直接单测（纯函数契约）。
+ */
+export function extractParsedOutput(toolCalls: ToolCall[]): unknown {
+  for (let i = toolCalls.length - 1; i >= 0; i--) {
+    const tc = toolCalls[i]!;
+    if (tc.toolName === STRUCTURED_OUTPUT_TOOL && tc.result?.details !== undefined) {
+      return tc.result.details;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * 从 record + args 组装 AgentResult。每个字段来源单一且收口于 record：
+ *   text      ← getFullText(record)（聚合 turns[].text，单一数据源）
+ *   turns     ← record.turnCount
+ *   toolCalls ← getAllToolCalls(record)（扁平化 turns[].toolCalls）
+ *   usage     ← getTotalUsage(record)（聚合 turns[].usageDelta，全零则 undefined）
+ *   parsedOutput ← extractParsedOutput(toolCalls)
+ *
+ * startTime 算 durationMs。
+ *
+ * success 双来源判定（调用方传入）：
+ *   ① session.prompt() 抛错 → args.success=false
+ *   ② prompt 成功但 record.lastError 非空（message_end stopReason=error）→ success=false
+ */
+export function collectResult(
+  record: ExecutionRecord,
+  args: CollectResultArgs,
+): AgentResult {
+  const toolCalls = getAllToolCalls(record);
+  return {
+    text: getFullText(record),
+    turns: record.turnCount,
+    durationMs: Date.now() - args.startTime,
+    success: args.success,
+    error: args.error,
+    sessionId: args.sessionId,
+    toolCalls,
+    usage: getTotalUsage(record),
+    sessionFile: args.sessionFile,
+    parsedOutput: extractParsedOutput(toolCalls),
+  };
+}

package/src/execution/path-encoding.ts

@@ -0,0 +1,34 @@
+// src/core/path-encoding.ts
+//
+// cwd → 安全目录名的编码逻辑。Core 叶子原语（零依赖）。
+//
+// 被 session-runner（subagent session 持久化目录）与 session-file-gc（清理过期
+// session 文件）共用——两处需要相同的编码，否则同一 cwd 会落到两个不同目录。
+
+import * as path from "node:path";
+
+/**
+ * cwd → 安全目录名。复用 Pi SDK getDefaultSessionDir 的编码逻辑：
+ * 去开头单个分隔符，全量替换剩余分隔符/冒号为 `-`，首尾补 `--`。
+ * 例：`/Users/x/proj` → `--Users-x-proj--`。
+ */
+export function encodeCwd(cwd: string): string {
+  return "--" + cwd.replace(/^[/\\]/, "").replace(/[/\\:]/g, "-") + "--";
+}
+
+/**
+ * 获取 subagent session 持久化目录路径。
+ *
+ * D-004: 用主 cwd 编码——保证同一主 cwd 下所有 subagent 的 session 文件
+ * 存放在同一目录，便于 session-file-gc 统一清理。
+ *
+ * @param agentDir agent 配置目录（如 ~/.pi/agent）
+ * @param mainCwd 主 agent 的工作目录（非 subagent 的 effectiveCwd）
+ * @returns session 持久化目录绝对路径
+ */
+export function getSubagentSessionDir(agentDir: string, mainCwd: string): string {
+  // [MF#1] 保持既有布局 subagents/<enc>/sessions/——曾改为 subagents/sessions/<enc>/ 会让
+  // 升级用户的既有 session 文件全部落到扫描目录外（历史记录消失 + GC 扫不到，双重 orphan）。
+  // 本分支未发布，回退到既有布局即无需迁移、无数据丢失。
+  return path.join(agentDir, "subagents", encodeCwd(mainCwd), "sessions");
+}

package/src/execution/pi-invocation.ts

@@ -0,0 +1,70 @@
+// src/core/pi-invocation.ts
+//
+// 定位 pi 二进制并组装 spawn 调用。Core 叶子原语（仅依赖 node 内置）。
+//
+// spawn 改造（in-process → spawn pi --mode json）的基座模块。
+// 被 runSpawn（session-runner）调用，决定子进程用哪个命令启动。
+//
+// 移植自 nicobailon subagent example 的 getPiInvocation，处理三种运行时：
+//   1. bun bundle（/$bunfs/root/ 虚拟脚本）→ 退化到 pi-in-PATH
+//   2. 有真实脚本路径（node + script）→ node <script> <args>
+//   3. node/bun generic runtime（无脚本）→ pi <args>（依赖 PATH）
+//
+// 注意：pi 在扩展进程内运行时 process.execPath 是 node/bun，process.argv[1]
+// 是 pi 的入口脚本。子进程需要复现同样的启动方式才能保证扩展/配置一致加载。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+/** spawn 调用描述符：command + args（透传给 child_process.spawn）。 */
+export interface PiInvocation {
+  /** 可执行文件路径（node/bun/pi 二进制）。 */
+  command: string;
+  /** 命令行参数（可能含 [scriptPath, ...userArgs] 或直接 [...userArgs]）。 */
+  args: string[];
+}
+
+/**
+ * bun 虚拟文件系统前缀。bun bundle 模式下 process.argv[1] 形如
+ * /$bunfs/root/pi——这不是磁盘上的真实文件，不能直接 spawn。
+ */
+const BUN_VIRTUAL_PREFIX = "/$bunfs/root/";
+
+/**
+ * 判断 execPath 的 basename 是否为通用运行时（node/bun）。
+ * 通用运行时需要脚本路径才能启动 pi；非通用（如 pi 的 standalone binary）可直接执行。
+ */
+function isGenericRuntime(execPath: string): boolean {
+  const execName = path.basename(execPath).toLowerCase();
+  return /^(node|bun)(\.exe)?$/.test(execName);
+}
+
+/**
+ * 组装 pi 子进程的 spawn 调用。
+ *
+ * @param userArgs pi CLI 参数（如 ["--mode", "json", "-p", "Task: ..."]）
+ * @returns spawn 描述符（command + 完整 args）
+ *
+ * 决策链（按优先级）：
+ *   1. process.argv[1] 是真实磁盘文件且非 bun 虚拟路径 → <execPath> <argv[1]> <userArgs>
+ *      （复现当前 pi 进程的启动方式，确保扩展/配置/版本一致）
+ *   2. execPath 非通用运行时（pi standalone binary）→ <execPath> <userArgs>
+ *   3. 通用运行时但无可用脚本路径 → "pi" <userArgs>（依赖 PATH 中可找到 pi）
+ */
+export function getPiInvocation(userArgs: string[]): PiInvocation {
+  const currentScript = process.argv[1];
+  const isBunVirtualScript = currentScript?.startsWith(BUN_VIRTUAL_PREFIX);
+
+  // 分支 1：有真实脚本路径 → 复现启动方式（node <pi-script> <args>）
+  if (currentScript && !isBunVirtualScript && fs.existsSync(currentScript)) {
+    return { command: process.execPath, args: [currentScript, ...userArgs] };
+  }
+
+  // 分支 2：非通用运行时（pi 自带 binary）→ 直接执行
+  if (!isGenericRuntime(process.execPath)) {
+    return { command: process.execPath, args: userArgs };
+  }
+
+  // 分支 3：通用运行时但脚本不可用 → 依赖 PATH
+  return { command: "pi", args: userArgs };
+}

package/src/execution/record-store.ts

@@ -0,0 +1,350 @@
+// src/runtime/execution/record-store.ts
+//
+// Record 的统一容器。内存只留 running record；终态从 session.jsonl 重建。
+//
+// 职责：
+//   - 持有 running record（终态 record 在 archive 时立即从内存移除）
+//   - onChange 订阅（TUI widget/list 据此重渲）
+//   - collectRecords：内存(running) + 磁盘(sessions/*.jsonl 重建) 合并
+//   - 提供 snapshot() 只读视图给 TUI（永不返回可变引用）
+
+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 { reconstructFromFile } from "./session-reconstructor.ts";
+import type {
+  ExecutionRecord,
+  ExecutionStatus,
+  RecordSnapshot,
+  SubagentRecord,
+} from "./types.ts";
+import { isProcessAlive, readAliveMarker } from "./alive-store.ts";
+import { readFinalized } from "./finalized-marker.ts";
+import { readCancelledTombstone } from "./tombstone-store.ts";
+
+// ============================================================
+// 常量
+// ============================================================
+
+/** status → 排序优先级（值小排前）：running < failed < crashed < cancelled < done。 */
+const STATUS_PRIORITY: Record<ExecutionStatus, number> = {
+  running: 0,
+  failed: 1,
+  crashed: 1,
+  cancelled: 2,
+  done: 3,
+};
+
+/** .alive sidecar 的 24 小时软超时（超过此时间即使 pid 存活也判 crashed）。 */
+const ALIVE_SOFT_TIMEOUT_MS = 86_400_000; // 24h in ms
+
+/** store 变更监听器（返回取消订阅函数）。 */
+export type ChangeListener = () => void;
+
+/** status 过滤模式（collectRecords 的核心能力参数）。 */
+export type StatusFilter = "running" | "all";
+
+// ============================================================
+// RecordStore
+// ============================================================
+
+/**
+ * Record 容器。进程单例（随 SubagentService 重建）。
+ *
+ * 内存只留 running record——终态 record 在 archive 时立即移除，collectRecords
+ * 读时从 sessions/*.jsonl 重建（reconstructFromFile）。重建结果有缓存，在
+ * notifyChange 时失效（终态 record 不再变化，但新 finalize 触发重扫）。
+ *
+ * 任何 mutate → notifyChange()。
+ */
+export class RecordStore {
+  private readonly records = new Map<string, ExecutionRecord>();
+  private readonly listeners = new Set<ChangeListener>();
+  private _disposed = false;
+
+  /** 重建缓存：sessionFile → SubagentRecord。notifyChange 时失效。 */
+  private reconCache: Map<string, SubagentRecord> | undefined;
+
+  constructor(private readonly sessionsDir: string) {}
+
+  /** 注册新 record。触发 onChange。 */
+  register(record: ExecutionRecord): void {
+    this.records.set(record.id, record);
+    this.notifyChange();
+  }
+
+  /**
+   * 归档：record 已被 completeRecord 设置了终态 status。
+   * 立即从内存移除（终态 record 下次读时从 session.jsonl 重建）。
+   * cancelled record 由调用方先写 tombstone（cancel 路径），此处只负责移除。
+   */
+  archive(record: ExecutionRecord): void {
+    this.records.delete(record.id);
+    this.notifyChange();
+  }
+
+  /** 按 id 查找。返回可变 record（仅 runtime 内部用）。 */
+  getMutable(id: string): ExecutionRecord | undefined {
+    return this.records.get(id);
+  }
+
+  /**
+   * abort 所有 running record 的 controller（background 子进程 SIGTERM）。
+   *
+   * 仅在 SubagentService.dispose（进程退出路径）调用。不做 CAS/tombstone——dispose
+   * 是终局，状态机收尾无意义；目的是让 background 子进程的 AbortSignal 触发 →
+   * runSpawn 的 signal listener → child.kill("SIGTERM")，防止主进程退出后子进程成孤儿。
+   *
+   * sync record 无 controller（undefined），跳过——sync 是阻塞调用，主进程不会先于
+   * sync subagent 退出（除非 SIGKILL/崩溃，此时任何清理都无效）。
+   *
+   * 返回被 abort 的 record 数（诊断用）。
+   */
+  abortRunningControllers(): number {
+    let n = 0;
+    for (const r of this.records.values()) {
+      if (r.status === "running" && r.controller) {
+        r.controller.abort();
+        n++;
+      }
+    }
+    return n;
+  }
+
+  /** 列出所有 running record 的只读快照（widget 计数、诊断用）。 */
+  listRunning(): RecordSnapshot[] {
+    return [...this.records.values()]
+      .filter((r) => r.status === "running")
+      .map((r) => toSnapshot(r));
+  }
+
+  /**
+   * 合并内存(running) + 磁盘(sessions/*.jsonl 重建) → SubagentRecord[]。
+   *
+   *   ╔══════════════════════════════════════════════════════════════════╗
+   *   ║  1. 磁盘源：扫 sessionsDir 的 .jsonl，逐个 reconstructFromFile   ║
+   *   ║     （命中缓存则跳过读文件）。cancelled tombstone override status ║
+   *   ║  2. 内存源覆盖（同 id 内存优先——running record 更新鲜）          ║
+   *   ║  3. session 过滤：只留 rootSessionId === rootSessionFilter 的       ║
+   *   ║     record。rootSessionId 缺失（旧文件）的 record 一律排除        ║
+   *   ║     （无法判定归属，隔离优先）。rootSessionFilter 为 undefined       ║
+   *   ║     时不过滤（向后兼容）。                                          ║
+   *   ║  4. statusFilter："running" → 只留 running（内存源）；            ║
+   *   ║                   "all"（默认）→ 内存 + 磁盘                       ║
+   *   ║  5. 排序：STATUS_PRIORITY + startedAt desc                        ║
+   *   ║  6. slice(limit)                                                  ║
+   *   ╚══════════════════════════════════════════════════════════════════╝
+   *
+   * statusFilter="running" 时仍先取够多再过滤（防 limit 截断把 running 滤没），
+   * 与旧 listHandler 的防截断逻辑一致，下沉到此。
+   *
+   * session 隔离：同一 cwd 下多个 Pi session 共享 sessionsDir，靠 rootSessionId
+   * 区分。内存与磁盘源都按 rootSessionFilter 过滤后再 merge/sort/slice。
+   */
+  collectRecords(
+    limit: number,
+    statusFilter: StatusFilter = "all",
+    rootSessionFilter?: string,
+  ): SubagentRecord[] {
+    const byId = new Map<string, SubagentRecord>();
+
+    // 1. 磁盘源（重建终态 record）。 reconstructAll 已按 rootSessionFilter 过滤。
+    for (const rec of this.reconstructAll(rootSessionFilter)) {
+      byId.set(rec.id, rec);
+    }
+
+    // 2. 内存源覆盖（running record 优先——它是活态，比磁盘重建更新鲜）。同样按 session 过滤。
+    for (const r of this.records.values()) {
+      if (rootSessionFilter !== undefined && r.rootSessionId !== rootSessionFilter) continue;
+      byId.set(r.id, RecordStore.recordToSubagent(r));
+    }
+
+    // 3. statusFilter。
+    let result = [...byId.values()];
+    if (statusFilter === "running") {
+      result = result.filter((r) => r.status === "running");
+    }
+
+    // 4-5. 排序 + slice。
+    return result
+      .sort(RecordStore.compareRecords)
+      .slice(0, limit);
+  }
+
+  /** 订阅变更。返回取消订阅函数。 */
+  onChange(listener: ChangeListener): () => void {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+
+  /** 触发所有监听器（TUI widget/list requestRender）。dispose 后短路。同时失效重建缓存。 */
+  notifyChange(): void {
+    if (this._disposed) return;
+    this.reconCache = undefined; // 失效缓存（新 finalize 可能产出新 session.jsonl）。
+    for (const listener of this.listeners) {
+      listener();
+    }
+  }
+
+  /** session 结束清理。 */
+  dispose(): void {
+    this._disposed = true;
+    this.listeners.clear();
+  }
+
+  /** /resume /fork /new 后复活（dispose 的逆操作）。 */
+  revive(): void {
+    this._disposed = false;
+  }
+
+  // ── 内部 ──────────────────────────────────────────────────
+
+  /**
+   * 四分支 sidecar 矩阵重建。
+   *
+   * 优先级：
+   *   1. .cancelled → cancelled
+   *   2. .finalized → done/failed（按 recon.stopReason 推）
+   *   3. .alive + pid 存活 + 未超 24h → running, externalInstance=true
+   *   4. 兜底 → crashed
+   *
+   * 所有分支经 markReconstructedStatus（不裸 .status=）。
+   *
+   * session 隔离：rootSessionFilter 非空时，只保留 rootSessionId 匹配的 record。
+   * rootSessionId 缺失（旧文件，未带身份字段）一律排除（无法判定归属）。
+   * 缓存以 undefined 过滤结果为基底，带 filter 时在基底上再筛（避免缓存碎片化）。
+   */
+  private reconstructAll(rootSessionFilter?: string): SubagentRecord[] {
+    if (this.reconCache) {
+      const all = [...this.reconCache.values()];
+      if (rootSessionFilter === undefined) return all;
+      return all.filter((r) => r.rootSessionId === rootSessionFilter);
+    }
+
+    const cache = new Map<string, SubagentRecord>();
+    let files: string[];
+    try {
+      files = fs.readdirSync(this.sessionsDir)
+        .filter((f) => f.endsWith(".jsonl"))
+        .map((f) => path.join(this.sessionsDir, f));
+    } catch {
+      this.reconCache = cache;
+      return [];
+    }
+
+    const now = Date.now();
+
+    for (const file of files) {
+      const recon = reconstructFromFile(file);
+      if (!recon) continue; // 文件缺失/损坏/缺 identity → 跳过。
+
+      // 读取三个 sidecar（best-effort，不存在返回 falsy）。
+      const tomb = readCancelledTombstone(file);
+      const finalized = readFinalized(file);
+      const alive = readAliveMarker(file);
+
+      // 构造 base record（status/error/endedAt/externalInstance 后续按分支覆盖）。
+      const rec: SubagentRecord = {
+        id: recon.id,
+        agent: recon.agent,
+        status: recon.status, // 临时值，各分支覆盖
+        mode: recon.mode,
+        startedAt: recon.startedAt,
+        rootSessionId: recon.rootSessionId,
+        parentRecordId: recon.parentRecordId,
+        depth: recon.depth,
+        endedAt: undefined,
+        turns: recon.turnCount,
+        totalTokens: recon.totalTokens,
+        model: recon.model,
+        thinkingLevel: recon.thinkingLevel,
+        task: recon.task,
+        // 磁盘重建是离线快照，无实时活动状态。
+        currentActivity: undefined,
+        // worktreeHandle 不从磁盘重建（session.jsonl 未持久化路径/分支）。
+        // 已结束的 worktree record 的 checkout 已被 cleanup 回收，重建句柄无意义。
+        // forkDepth 从 identity 重建（用于 TUI 深度标记），worktree 信息仅内存 running 时可见。
+        eventLog: recon.eventLog,
+        // [STEP3] displayItems 从重建的 turns[] 派生（getDisplayItems 参数放宽为
+        // { turns }，ReconstructedRecord 满足）。终态 record 详情可看完整 text 输出。
+        displayItems: getDisplayItems(recon),
+        result: recon.result,
+        error: recon.error,
+        sessionFile: recon.sessionFile,
+      };
+
+      // ── 分支 1: .cancelled ──
+      if (tomb) {
+        markReconstructedStatus(rec, "cancelled");
+        rec.error = "cancelled by user";
+        rec.endedAt = tomb.endedAt;
+      }
+      // ── 分支 2: .finalized ──
+      else if (finalized) {
+        // done/failed 按 recon 推导的 stopReason（reconstructFromFile 已映射为 status）。
+        const status: ExecutionStatus = recon.status === "failed" ? "failed" : "done";
+        markReconstructedStatus(rec, status);
+        // 用最后一条 entry 的时间戳作为 endedAt（避免重建后耗时随墙钟无限增长）。
+        rec.endedAt = recon.endedAt;
+      }
+      // ── 分支 3: .alive + pid 存活 + 未超 24h 软超时 ──
+      else if (
+        alive !== undefined &&
+        isProcessAlive(alive.pid) &&
+        now - alive.startedAt < ALIVE_SOFT_TIMEOUT_MS
+      ) {
+        markReconstructedStatus(rec, "running");
+        rec.externalInstance = alive;
+      }
+      // ── 分支 4: 兜底（都无 / .alive 但 pid 死 / 超 24h）──
+      else {
+        markReconstructedStatus(rec, "crashed");
+        // crashed 以最后已知活动时间为准（pid 死亡时间未知，用最后 entry 时间近似）。
+        rec.endedAt = recon.endedAt;
+      }
+
+      cache.set(file, rec);
+    }
+
+    this.reconCache = cache;
+    // 带 filter 时在缓存上筛（上面已构造全量缓存，便于后续调用复用）。
+    if (rootSessionFilter === undefined) return [...cache.values()];
+    return [...cache.values()].filter((r) => r.rootSessionId === rootSessionFilter);
+  }
+
+  /** 排序比较器：status priority（running<failed<cancelled<done）+ startedAt desc。 */
+  private static compareRecords(a: SubagentRecord, b: SubagentRecord): number {
+    const pdiff = STATUS_PRIORITY[a.status] - STATUS_PRIORITY[b.status];
+    if (pdiff !== 0) return pdiff;
+    return b.startedAt - a.startedAt; // 新→旧
+  }
+
+  /** ExecutionRecord → SubagentRecord（内存源投影）。 */
+  private static recordToSubagent(r: ExecutionRecord): SubagentRecord {
+    return {
+      id: r.id,
+      agent: r.agent,
+      status: r.status,
+      mode: r.mode,
+      startedAt: r.startedAt,
+      rootSessionId: r.rootSessionId,
+      parentRecordId: r.parentRecordId,
+      depth: r.depth,
+      endedAt: r.endedAt,
+      turns: r.turnCount,
+      totalTokens: r.totalTokens,
+      model: r.model,
+      thinkingLevel: r.thinkingLevel,
+      task: r.task,
+      currentActivity: getCurrentActivity(r),
+      eventLog: getEventLog(r),
+      displayItems: getDisplayItems(r),
+      result: r.result,
+      error: r.error,
+      sessionFile: r.sessionFile,
+    };
+  }
+}

package/src/execution/session-context-resolver.ts

@@ -0,0 +1,64 @@
+// src/core/session-context-resolver.ts
+//
+// resolveSessionContext 纯函数——解析 fork/worktree 意图，返回执行上下文。
+// D-014: 零副作用，零 Pi import。只返回意图，不调 forkFrom/不创建 sessionDir。
+
+import type { ResolvedSessionContext, SessionResolveInput } from "./types.ts";
+import { ForkDepthExceededError } from "./types.ts";
+import { getSubagentSessionDir } from "./path-encoding.ts";
+
+/**
+ * fork 深度硬限。export 供 session-runner 注入 LLM env block 时引用同一常量，
+ * 避免硬限（拦截）与展示（`N/10`）两处 10 漂移。
+ *
+ * 双层护栏（互补，共享本常量）：
+ *   1. resolveSessionContext 的 fork 护栏（parentForkDepth >= MAX_FORK_DEPTH → 拒）：
+ *      只计 fork 链（fork=true 才递增 parentForkDepth），控 session 体积（每层 createBranchedSession）。
+ *   2. SubagentService.execute 入口的通用嵌套护栏（nestingDepth > MAX_FORK_DEPTH → 拒）：
+ *      经 execCtxAls 计所有 subagent 嵌套（fork + 非 fork），更严——混合链
+ *      （fork→非fork→fork）下 nestingDepth >= parentForkDepth，通用护栏先生效。
+ * 两者均允许深度 0..MAX_FORK_DEPTH（共 MAX+1 层），第 MAX+1 层（深度=MAX+1）被拒。
+ */
+export const MAX_FORK_DEPTH = 10;
+
+/**
+ * 纯函数：解析 fork/worktree 意图 → 执行上下文。
+ *
+ * 只返回意图（shouldFork/forkSource/effectiveCwd/sessionDir），
+ * 不调 forkFrom / 不创建 sessionDir / 不 git worktree add。
+ *
+ * @throws {ForkDepthExceededError} fork=true 且 parentForkDepth >= 10
+ */
+export function resolveSessionContext(input: SessionResolveInput): ResolvedSessionContext {
+  const { fork, cwd, mainCwd, mainSessionFile, parentForkDepth, agentDir, worktreePath } =
+    input;
+
+  // fork 深度检查（D-007）
+  if (fork && (parentForkDepth ?? 0) >= MAX_FORK_DEPTH) {
+    throw new ForkDepthExceededError(
+      `fork depth ${parentForkDepth ?? 0} >= ${MAX_FORK_DEPTH}, refusing to fork`,
+    );
+  }
+
+  const shouldFork = fork === true;
+  const forkSource = shouldFork ? mainSessionFile : undefined;
+
+  // [MF#5] fork 显式请求但主 session 文件不可用（session_start 未缓存）时直接抛错，
+  // 不静默降级到 from-scratch——否则用户显式 fork 却得到无继承 session，且无任何告警。
+  if (shouldFork && !forkSource) {
+    throw new Error(
+      "fork requested but main session file is unavailable " +
+        "(session_start did not cache it); cannot fork without a source session",
+    );
+  }
+
+  // effectiveCwd: worktree 模式用 handle.path（真实 checkout，由调用方传入），
+  // 否则用显式 cwd 或 mainCwd。worktreePath 与 worktree 标志同源（都来自 WorktreeHandle），
+  // 不再靠 tmpdir 拼凑，保证 effectiveCwd 与实际 checkout 严格一致。
+  const effectiveCwd = worktreePath ?? (cwd ?? mainCwd);
+
+  // sessionDir 用 mainCwd 编码（D-004: 同一主 cwd 下所有 subagent 存同一目录）
+  const sessionDir = getSubagentSessionDir(agentDir, mainCwd);
+
+  return { shouldFork, forkSource, effectiveCwd, sessionDir };
+}