@zhushanwen/subagent-core 0.2.0

package/src/execution/sessions-index.ts

@@ -0,0 +1,304 @@
+// src/execution/sessions-index.ts
+//
+// [perf L-1] sessions-index.json —— identity 探测结果的磁盘种子。
+//
+// 背景：RecordStore 冷启动首扫需逐个探测 sessions/*.jsonl 的 identity（头部 64KB →
+// 尾部 64KB → 全文 fallback）。session 数量大时该探测是冷扫描的主要成本。本模块把
+// 「本目录的探测结论」（per-file identity 或负标记）持久化到 sessionsDir 的兄弟位置
+// （<enc> 段内），下次进程/实例首扫直接用索引条目构造缓存条目（零内容读取）。
+//
+// 语义：
+//   - 读侧（loadIndex）永不抛：文件缺失/JSON 损坏/结构不符/版本低 → 空索引（= 今天的
+//     全量行为，下轮 dirty 重写自愈）；版本高于自身 → 空索引 + higherVersion 标志
+//     （整体忽略不消费，RecordStore 据此抑制本轮及后续落盘，防 v1/v2 last-writer-wins
+//     覆盖振荡）。
+//   - 写侧（saveIndex）：tmp(pid+seq)+fsync+rename+目录 fsync 原子写（逐环复刻
+//     ManifestStore.writeManifest 的生产模式）。失败本身向上抛；fire-and-forget 的
+//     .catch 兜底在 RecordStore 侧。
+//   - 损坏/降级走 logger.debug（PI_EXT_DEBUG=1 可见，默认 no-op），不 console.error
+//     ——索引是纯性能缓存，降级自愈不应告警。
+//
+// 无状态纯函数模块：不依赖 RecordStore 任何内部状态。
+
+import * as fs from "node:fs";
+import * as fsPromises from "node:fs/promises";
+import * as path from "node:path";
+
+import { getLogger } from "../core/logger.ts";
+
+import { bestEffort } from "./best-effort.ts";
+import type { ExecutionMode } from "./types.ts";
+
+const logger = getLogger("subagents");
+
+// ============================================================
+// 常量（测试锚点 SSOT：RecordStore 与测试从同一来源引用，禁止内联字面量）
+// ============================================================
+
+/** 索引文件名（落 sessionsDir 兄弟位置——写索引不改 sessionsDir 目录 mtime，不击穿 L0 快路径）。 */
+export const INDEX_FILENAME = "sessions-index.json";
+
+/** 索引格式版本。schema 变更必须递增：低版本文件整体丢弃（空索引，下轮 dirty 重写自愈）；高版本整体忽略（higherVersion，不重写）。 */
+export const INDEX_VERSION = 1;
+
+/** 两次成功落盘的最小墙钟间隔（节流：overlay 打开期间的高频扫描不放大磁盘写）。 */
+export const INDEX_WRITE_MIN_INTERVAL_MS = 60_000;
+
+/** tmp 文件单调计数：同一进程内并发的 saveIndex 各用独立 tmp。节流基准只在写成功后
+ *  推进——W1 在途时新一轮过窗扫描可再 dispatch W2，共用同一 tmp 会交错（W2 truncate
+ *  落在 W1 write 与 rename 之间 → 半成品被 rename / rename 后失败 → 假失败日志）。
+ *  pid+seq 双后缀保证 tmp 唯一：交错 rename 的终态必为某次完整快照（last-writer-wins，
+ *  与跨进程 pid 隔离同语义；陈旧快照胜出时下轮戳不匹配自愈）。 */
+let tmpSeq = 0;
+
+// ============================================================
+// 类型（DM1 磁盘顶层 + DM2 条目）
+// ============================================================
+
+/**
+ * 正索引条目：「该文件有 identity」的身份字段 + stat 戳。
+ *
+ * 不含 sessionFile（加载侧由 sessionsDir + basename 重构，绝对路径因 agentDir 迁移
+ * 整体失效）；不含 forkDepth/chatMode（投影源 SubagentRecord 无此二字段，buildRecord
+ * 构造 light 时不读——存了也无消费方；未来需要时升 INDEX_VERSION）。
+ */
+export interface SessionsIndexEntry {
+  /** tagged union 判别（负条目为 true）。显式声明 false 供 TS narrowing（与 record-store.ts FileCacheEntry 同款）。 */
+  negative?: false;
+  /** jsonl stat 戳（mtime+size）——不匹配 = 内容变化，调用方回退重探测。 */
+  mtimeMs: number;
+  size: number;
+  id: string;
+  agent: string;
+  /** 执行模式。运行时校验宽容历史 "sync" 值（白名单 sync|background，镜像 isIdentityData）；类型层由 ExecutionMode 收窄。 */
+  mode: ExecutionMode;
+  task: string;
+  slug: string;
+  startedAt: number;
+  /** undefined 表示缺失（旧文件/顶层）。JSON 序列化时被丢弃，往返保持 undefined。 */
+  rootSessionId: string | undefined;
+  parentRecordId: string | undefined;
+  depth: number;
+  /** 空串合法：尾部探测（readIdentityTail）拿不到 model 时的合法结果，不当损坏。 */
+  model: string;
+  thinkingLevel: string | undefined;
+}
+
+/**
+ * 负索引条目：「该文件确认无 identity」（junk/异构文件）。与内存负缓存
+ * NegativeFileEntry 语义对齐——把「没有」这一事实持久化，跨实例零重探测。
+ */
+export interface SessionsIndexNegativeEntry {
+  negative: true;
+  mtimeMs: number;
+  size: number;
+}
+
+/** 磁盘 JSON 顶层结构（key = jsonl basename 不含路径）。 */
+export interface SessionsIndexFile {
+  version: 1;
+  pid: number;
+  entries: Record<string, SessionsIndexEntry | SessionsIndexNegativeEntry>;
+}
+
+/** saveIndex 输入（内存形态）。 */
+export interface SessionsIndexData {
+  entries: Map<string, SessionsIndexEntry | SessionsIndexNegativeEntry>;
+}
+
+/** loadIndex 输出。恒返回该形态对象（不抛、不返回 null）。 */
+export interface LoadedSessionsIndex {
+  entries: Map<string, SessionsIndexEntry | SessionsIndexNegativeEntry>;
+  /** true = 磁盘版本高于自身：条目整体不消费，且本进程及后续不得写盘（防 v1/v2 互相覆盖振荡）。 */
+  higherVersion: boolean;
+}
+
+// ============================================================
+// 条目级校验（ES3：单条目损坏仅丢弃该条目，不放大为整体失效）
+// ============================================================
+
+/** 正条目类型谓词：镜像 isIdentityData（session-reconstructor.ts:244-253）的字段检查 + 索引特有戳/形态字段。 */
+function isPositiveIndexEntry(raw: unknown): raw is SessionsIndexEntry {
+  if (typeof raw !== "object" || raw === null) return false;
+  const v = raw as Record<string, unknown>;
+  return (
+    typeof v.mtimeMs === "number" &&
+    typeof v.size === "number" &&
+    typeof v.id === "string" &&
+    typeof v.agent === "string" &&
+    // 宽容历史 "sync" 值（ExecutionMode 现值仅 "background"，"sync" 是旧数据合法值，放行不丢弃）
+    (v.mode === "sync" || v.mode === "background") &&
+    typeof v.task === "string" &&
+    typeof v.slug === "string" &&
+    typeof v.startedAt === "number" &&
+    (v.rootSessionId === undefined || typeof v.rootSessionId === "string") &&
+    (v.parentRecordId === undefined || typeof v.parentRecordId === "string") &&
+    typeof v.depth === "number" &&
+    typeof v.model === "string" && // 空串合法（DS4）
+    (v.thinkingLevel === undefined || typeof v.thinkingLevel === "string")
+  );
+}
+
+/** 负条目类型谓词（tagged union 形态检查）。 */
+function isNegativeIndexEntry(raw: unknown): raw is SessionsIndexNegativeEntry {
+  if (typeof raw !== "object" || raw === null) return false;
+  const v = raw as Record<string, unknown>;
+  return v.negative === true && typeof v.mtimeMs === "number" && typeof v.size === "number";
+}
+
+/**
+ * 校验单条索引条目。返回 undefined = 条目损坏，调用方仅丢弃该条目
+ * （该文件本轮回退探测，其余条目正常保留/命中）。
+ */
+export function validateIndexEntry(
+  raw: unknown,
+): SessionsIndexEntry | SessionsIndexNegativeEntry | undefined {
+  if (!isPositiveIndexEntry(raw) && !isNegativeIndexEntry(raw)) return undefined;
+  return raw;
+}
+
+// ============================================================
+// 读侧（IF1：永不抛）
+// ============================================================
+
+/**
+ * 读取指定目录（<enc> 段）的 sessions-index.json。永不抛：
+ *   - 文件不存在/读失败/JSON.parse 失败/顶层结构不符/版本低于自身
+ *     → { entries: 空 Map, higherVersion: false }（空索引 = 今天的全量行为）
+ *   - 版本高于自身 → { entries: 空 Map, higherVersion: true }
+ *     （整体忽略——即使 entries 合法也不消费，防陈旧 schema 灌入；RecordStore 据此抑制落盘）
+ *   - 版本匹配 → 逐条 validateIndexEntry（坏条目丢弃，其余保留）
+ *
+ * 只读精确路径 INDEX_FILENAME：.tmp. 残留文件不匹配文件名，天然被忽略。
+ */
+export function loadIndex(encDir: string): LoadedSessionsIndex {
+  const empty: LoadedSessionsIndex = { entries: new Map(), higherVersion: false };
+  const indexPath = path.join(encDir, INDEX_FILENAME);
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(indexPath, "utf-8");
+  } catch (err) {
+    // ENOENT = 正常首跑，保持静默；其余读失败（EACCES 等长期权限异常）留 debug 线索
+    // ——空索引回退本身可自愈，但权限类异常不会自己消失，需可诊断。
+    const code = err instanceof Error && "code" in err && typeof err.code === "string" ? err.code : undefined;
+    if (code !== "ENOENT") {
+      logger.debug("[subagents] sessions-index read failed, fallback to empty", {
+        detail: { dir: encDir, code },
+      });
+    }
+    return empty;
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    // 损坏（截断/外部编辑）走 debug：可降级自愈场景，不 console.error
+    logger.debug("[subagents] sessions-index corrupted JSON, fallback to empty", {
+      detail: { path: indexPath, error: err instanceof Error ? err.message : String(err) },
+    });
+    return empty;
+  }
+
+  if (typeof parsed !== "object" || parsed === null) {
+    logger.debug("[subagents] sessions-index invalid top-level shape, fallback to empty", {
+      detail: { path: indexPath },
+    });
+    return empty;
+  }
+  const top = parsed as Record<string, unknown>;
+  if (
+    typeof top.version !== "number" ||
+    typeof top.entries !== "object" ||
+    top.entries === null ||
+    Array.isArray(top.entries)
+  ) {
+    logger.debug("[subagents] sessions-index invalid header fields, fallback to empty", {
+      detail: { path: indexPath },
+    });
+    return empty;
+  }
+
+  if (top.version > INDEX_VERSION) {
+    // 高版本：整体忽略（entries 即使合法也不消费）；调用方据 higherVersion 抑制写盘
+    return { entries: new Map(), higherVersion: true };
+  }
+  if (top.version < INDEX_VERSION) {
+    // 低版本：整体丢弃 → 空索引；本轮全扫 dirty 后重写自愈
+    logger.debug("[subagents] sessions-index stale version, discarded", {
+      detail: { path: indexPath, version: top.version, expected: INDEX_VERSION },
+    });
+    return empty;
+  }
+
+  const entries = new Map<string, SessionsIndexEntry | SessionsIndexNegativeEntry>();
+  for (const [key, value] of Object.entries(top.entries)) {
+    const entry = validateIndexEntry(value);
+    if (entry !== undefined) entries.set(key, entry);
+  }
+  return { entries, higherVersion: false };
+}
+
+// ============================================================
+// 写侧（IF2：原子写；失败向上抛——fire-and-forget 的 .catch 兜底在调用方）
+// ============================================================
+
+/**
+ * 原子写索引（tmp(pid+seq) → fsync → rename → fsync 目录；逐环复刻
+ * ManifestStore.writeManifest 的生产模式）。tmp 带 pid+单调序号双后缀：pid 防两进程
+ * 共用同一 tmp，seq 防同进程内并发 saveIndex（节流基准在写成功后才推进，W1 在途时
+ * 新一轮过窗扫描可 dispatch W2）共用同一 tmp；rename 原子性保证读侧看到旧版或完整
+ * 新版，绝无半成品。
+ *
+ * 失败向上抛——RecordStore 的 flushIndexAfterScan 以 fire-and-forget .catch 消费
+ * （写失败不影响任何扫描结果，恢复 dirty 待下轮过窗重试）。
+ */
+export async function saveIndex(encDir: string, data: SessionsIndexData): Promise<void> {
+  const filePath = path.join(encDir, INDEX_FILENAME);
+  const tmpPath = `${filePath}.tmp.${process.pid}.${++tmpSeq}`;
+  const file: SessionsIndexFile = {
+    version: INDEX_VERSION,
+    pid: process.pid,
+    entries: Object.fromEntries(data.entries),
+  };
+  const content = JSON.stringify(file);
+
+  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(encDir, "r");
+      try {
+        await dirFh.sync();
+      } finally {
+        await dirFh.close();
+      }
+    } catch (dirSyncErr) {
+      bestEffort(dirSyncErr, "fsync dir (saveIndex)");
+    }
+  } catch (err) {
+    // rename 未成功 → 清理残留 tmp（best-effort，不掩盖原错误）
+    if (!renamed) {
+      try {
+        await fsPromises.unlink(tmpPath);
+      } catch (cleanupErr) {
+        bestEffort(cleanupErr, "unlink tmp (saveIndex)");
+      }
+    }
+    throw err;
+  }
+}

package/src/execution/spawn-event-adapter.ts

@@ -0,0 +1,363 @@
+// src/core/spawn-event-adapter.ts
+//
+// pi 子进程 stdout JSON 事件流的解析器。Core 叶子原语（仅依赖 types.ts）。
+//
+// spawn 改造的基座模块。session-runner runSpawn 用 `pi --mode rpc` spawn 子进程。
+// RPC mode 不向 stdout 输出 header 行（只有 json/print mode 才输出），故 runSpawn 额外
+// 通过 get_state RPC 握手回填 sessionFile/sessionId。两种 stdout 行形态本模块统一解析：
+//   1. header 行（json/print mode 首行）：{ type: "session", id, timestamp, cwd, ... }
+//      —— session 元信息，含 session id（RPC mode 不发，靠 get_state 握手替代）
+//   2. 事件行：{ type: "tool_execution_start" | "message_end" | ..., ... }
+//      —— 与 in-process session.subscribe 收到的 SdkEvent 同源同构
+//
+// 本模块只做「行 → 分类事件对象」的纯解析，不做累积/翻译（那是 runSpawn +
+// handleSdkEvent 的职责）。刻意保持薄，便于单测。
+//
+// 与 session-runner.handleSdkEvent 的契约：parseSpawnLine 返回 kind:"event" 的
+// event 字段即为 SdkEvent，可直接喂给 handleSdkEvent（事件 type schema 一致，
+// 由 print-mode.ts:106 JSON.stringify(event) 保证同源）。
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+import type { SdkEvent } from "./types.ts";
+
+/** pi stdout header 行（session 元信息）。type 固定为 "session"。 */
+export interface SpawnSessionHeader {
+  readonly type: "session";
+  readonly id: string;
+  readonly timestamp: string;
+  readonly cwd: string;
+  readonly parentSession?: string;
+  readonly version?: number;
+}
+
+/** Pi 原生 extension_ui_request 的方法特定字段（按 method 平铺）。
+ *  与 Pi rpc-types.ts L230-265 的 RpcExtensionUIRequest 1:1 对应。
+ *  method 是判别字段；每个变体仅列出该 method 的已知字段（可选字段保持可选）。
+ *  未知 method 走 string fallback（保留 raw 字段，避免协议演进时丢字段）。 */
+export type ExtensionUiRequest =
+  | { method: "select"; title: string; options: string[]; timeout?: number }
+  | { method: "confirm"; title: string; message: string; timeout?: number }
+  | { method: "input"; title: string; placeholder?: string; timeout?: number }
+  | { method: "editor"; title: string; prefill?: string }
+  | { method: "notify"; message: string; notifyType?: "info" | "warning" | "error" }
+  | { method: "setStatus"; statusKey: string; statusText: string | undefined }
+  | {
+      method: "setWidget";
+      widgetKey: string;
+      widgetLines: string[] | undefined;
+      widgetPlacement?: "aboveEditor" | "belowEditor";
+    }
+  | { method: "setTitle"; title: string }
+  | { method: "set_editor_text"; text: string }
+  // 未知 method fallback：保留原始字段，避免协议演进时丢信息
+  | { method: string; raw: Record<string, unknown> };
+
+/** 解析后的 extension_ui_request 顶层形状（type 守卫用）。
+ *  id 和 method 在顶层，method 特定字段平铺（与 Pi 原生格式一致）。 */
+interface ExtensionUiRequestEnvelope {
+  type: "extension_ui_request";
+  id: string;
+  method: string;
+  [key: string]: unknown;
+}
+
+/** Pi 原生 RPC response 顶层形状（type 守卫用）。
+ *  与 Pi rpc-types.ts 的 RpcResponse 一致：type:"response" + command + success。 */
+interface RpcResponseEnvelope {
+  type: "response";
+  command: string;
+  success: boolean;
+  id?: string;
+  data?: unknown;
+  error?: string;
+  [key: string]: unknown;
+}
+
+/** parseSpawnLine 的分类结果。
+ *
+ *  关键改动（W1 协议层重写）：
+ *    - extension_ui_request 分支：从 {id, params:Record} 改为 {id, request: ExtensionUiRequest}
+ *      （request 按 method 平铺，与 Pi rpc-types.ts 1:1）
+ *    - response 分支：从 {id, result, error} 改为 {id?, command, success, data?, error?}
+ *      （Pi 原生 RpcResponse 格式，SR-1 根因 1b） */
+export type ParsedSpawnLine =
+  | { kind: "header"; header: SpawnSessionHeader }
+  | { kind: "event"; event: SdkEvent }
+  | {
+      kind: "response";
+      id?: string;
+      command: string;
+      success: boolean;
+      data?: unknown;
+      error?: string;
+    }
+  | { kind: "extension_ui_request"; id: string; request: ExtensionUiRequest }
+  | { kind: "invalid"; raw: string; error: string };
+
+/**
+ * 判断解析出的 JSON 是否为 header 行（type === "session"）。
+ * 校验所有必需字段（id/timestamp/cwd），缺任一则不收窄——避免下游
+ * deriveSessionFilePath 访问 undefined 字段时抛 TypeError。
+ */
+function isSessionHeader(obj: unknown): obj is SpawnSessionHeader {
+  if (typeof obj !== "object" || obj === null) return false;
+  const r = obj as Record<string, unknown>;
+  return (
+    r.type === "session" &&
+    typeof r.id === "string" &&
+    typeof r.timestamp === "string" &&
+    typeof r.cwd === "string"
+  );
+}
+
+/**
+ * 判断解析出的 JSON 是否为 Pi 原生 RPC response。
+ *
+ * SR-1 根因 1b 修复：旧守卫判 JSON-RPC 2.0（jsonrpc + id + result/error），
+ * 但 Pi 实际发 {type:"response", command, success, data?, error?}。
+ * 新守卫只认 Pi 原生格式：
+ *   - type === "response"
+ *   - command: string（调用的命令名，如 "run_tool"）
+ *   - success: boolean
+ * id 可选（通知型 response 无 id）。
+ *
+ * 旧 JSON-RPC 2.0 response（{jsonrpc, id, result}）不再被识别 → 落 invalid 分支。
+ */
+function isRpcResponse(obj: unknown): obj is RpcResponseEnvelope {
+  if (typeof obj !== "object" || obj === null) return false;
+  const r = obj as Record<string, unknown>;
+  return (
+    r.type === "response" &&
+    typeof r.command === "string" &&
+    typeof r.success === "boolean"
+  );
+}
+
+/**
+ * 判断解析出的 JSON 是否为 Pi 原生 extension_ui_request。
+ *
+ * 关键改动（W1）：旧守卫判 JSON-RPC 2.0（jsonrpc + method:"extension_ui_request" + params），
+ * 但 Pi 实际发平铺格式 {type:"extension_ui_request", id, method, ...method特定字段}。
+ * 新守卫：
+ *   - type === "extension_ui_request"（顶层 type 字段，非 method 字段值）
+ *   - id: string
+ *   - method: string（select/confirm/.../set_editor_text 等具体方法名）
+ *
+ * 删掉 jsonrpc 守卫（Pi 不发 JSON-RPC 2.0 envelope）和 params 守卫（字段平铺，无 params 包裹）。
+ * 旧 JSON-RPC 2.0 格式（{jsonrpc, method:"extension_ui_request", params}）不再被识别。
+ */
+function isExtensionUiRequest(obj: unknown): obj is ExtensionUiRequestEnvelope {
+  if (typeof obj !== "object" || obj === null) return false;
+  const r = obj as Record<string, unknown>;
+  return (
+    r.type === "extension_ui_request" &&
+    typeof r.id === "string" &&
+    typeof r.method === "string"
+  );
+}
+
+/**
+ * 从已通过 isExtensionUiRequest 守卫的 envelope 构造 ExtensionUiRequest 变体。
+ *
+ * 按 method 平铺提取字段（与 Pi rpc-types.ts L230-265 1:1）。已知 method
+ * 走对应变体；未知 method 走 string fallback（保留 raw 字段全量字段）。
+ *
+ * 字段类型容错：协议字段类型不符（如 options 非数组）时，该字段降级为空数组/undefined
+ *（数组类字段做元素类型过滤，剔除非字符串元素），仍归类为已知 method（不丢 method 信息）。
+ */
+function buildExtensionUiRequest(env: ExtensionUiRequestEnvelope): ExtensionUiRequest {
+  const r: Record<string, unknown> = env;
+  switch (env.method) {
+    case "select":
+      return {
+        method: "select",
+        title: typeof r.title === "string" ? r.title : "",
+        options: Array.isArray(r.options)
+          ? r.options.filter((x): x is string => typeof x === "string")
+          : [],
+        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+      };
+    case "confirm":
+      return {
+        method: "confirm",
+        title: typeof r.title === "string" ? r.title : "",
+        message: typeof r.message === "string" ? r.message : "",
+        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+      };
+    case "input":
+      return {
+        method: "input",
+        title: typeof r.title === "string" ? r.title : "",
+        ...(typeof r.placeholder === "string" ? { placeholder: r.placeholder } : {}),
+        ...(typeof r.timeout === "number" ? { timeout: r.timeout } : {}),
+      };
+    case "editor":
+      return {
+        method: "editor",
+        title: typeof r.title === "string" ? r.title : "",
+        ...(typeof r.prefill === "string" ? { prefill: r.prefill } : {}),
+      };
+    case "notify":
+      return {
+        method: "notify",
+        message: typeof r.message === "string" ? r.message : "",
+        ...(r.notifyType === "info" || r.notifyType === "warning" || r.notifyType === "error"
+          ? { notifyType: r.notifyType }
+          : {}),
+      };
+    case "setStatus":
+      return {
+        method: "setStatus",
+        statusKey: typeof r.statusKey === "string" ? r.statusKey : "",
+        statusText: typeof r.statusText === "string" ? r.statusText : undefined,
+      };
+    case "setWidget": {
+      const placement = r.widgetPlacement;
+      const widgetLines = Array.isArray(r.widgetLines)
+        ? r.widgetLines.filter((x): x is string => typeof x === "string")
+        : undefined;
+      return {
+        method: "setWidget",
+        widgetKey: typeof r.widgetKey === "string" ? r.widgetKey : "",
+        widgetLines,
+        ...(placement === "aboveEditor" || placement === "belowEditor"
+          ? { widgetPlacement: placement }
+          : {}),
+      };
+    }
+    case "setTitle":
+      return {
+        method: "setTitle",
+        title: typeof r.title === "string" ? r.title : "",
+      };
+    case "set_editor_text":
+      return {
+        method: "set_editor_text",
+        text: typeof r.text === "string" ? r.text : "",
+      };
+    default:
+      // 未知 method：保留全部原始字段，避免协议演进时丢信息
+      return { method: env.method, raw: r };
+  }
+}
+
+/**
+ * 解析 pi stdout 的一行。
+ *
+ * @param line stdout 的一行（不含换行符；空行返回 null）
+ * @returns 分类结果，或 null（空行/仅空白）
+ *
+ * 分类规则（判定顺序关键，见 W1 bug 修复）：
+ *   - 空白行 → null（pi 可能输出空行，跳过）
+ *   - 合法 JSON + type:"session" + 必需字段 → header
+ *   - 合法 JSON + type:"extension_ui_request" + id + method → extension_ui_request
+ *     （必须在 event 分支之前，否则被 typeof obj.type===string 吞为 event）
+ *   - 合法 JSON + type:"response" + command + success → response
+ *   - 合法 JSON + 有 type 字段 → event（SdkEvent，type schema 由调用方校验）
+ *   - 合法 JSON 但无 type → invalid
+ *   - 非法 JSON → invalid（记录 error，不抛——单行损坏不应中断整个流）
+ *
+ * 容错原则：stdout 是流式输出，任何单行解析失败都不应中断进程。invalid 归类
+ * 由 runSpawn 决定是否记录/忽略，本函数不丢弃信息。
+ */
+export function parseSpawnLine(line: string): ParsedSpawnLine | null {
+  const trimmed = line.trim();
+  if (trimmed === "") return null;
+
+  let obj: unknown;
+  try {
+    obj = JSON.parse(trimmed);
+  } catch (err) {
+    return {
+      kind: "invalid",
+      raw: trimmed,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+
+  if (isSessionHeader(obj)) {
+    return { kind: "header", header: obj };
+  }
+
+  // extension_ui_request：必须在 event 分支之前判定（W1 判定顺序 bug 修复）。
+  // 原因：extension_ui_request 也有 type 字段，若 event 分支（typeof obj.type===string）
+  // 在前，会被当 event 静默吞掉。现在先于 event 判定，命中后按 method 构造 request。
+  if (isExtensionUiRequest(obj)) {
+    return { kind: "extension_ui_request", id: obj.id, request: buildExtensionUiRequest(obj) };
+  }
+
+  // RPC response：Pi 原生格式 {type:"response", command, success, data?, error?}
+  if (isRpcResponse(obj)) {
+    return {
+      kind: "response",
+      ...(typeof obj.id === "string" ? { id: obj.id } : {}),
+      command: obj.command,
+      success: obj.success,
+      ...(obj.data !== undefined ? { data: obj.data } : {}),
+      ...(typeof obj.error === "string" ? { error: obj.error } : {}),
+    };
+  }
+
+  // 事件行：必须有 type 字段（SdkEvent 契约）
+  if (
+    typeof obj === "object" &&
+    obj !== null &&
+    typeof (obj as Record<string, unknown>).type === "string"
+  ) {
+    return { kind: "event", event: obj as SdkEvent };
+  }
+
+  return {
+    kind: "invalid",
+    raw: trimmed,
+    error: "JSON missing string 'type' field",
+  };
+}
+
+/**
+ * 从已收集的 header + 事件流推导子进程的 session 文件路径。
+ *
+ * pi session 文件命名规则（session-manager.ts:846）：
+ *   `${fileTimestamp}_${sessionId}.jsonl`
+ * 其中 fileTimestamp = header.timestamp.replace(/[:.]/g, "-")
+ * （ISO 时间里的冒号和点替换为连字符，如 2026-07-03T12-34-56-789Z）。
+ *
+ * @param header spawn 解析出的 session header
+ * @param sessionDir 指定的 session 目录（spawn 时通过 --session-dir 传入）
+ * @returns 推导的 session 文件绝对路径（不保证文件存在——子进程可能仍在写入）
+ *
+ * 注意：这是基于 pi 命名规则的推导。runSpawn 会在进程结束后校验文件实际存在，
+ * 不存在时用 sessionId 后缀匹配兜底。
+ */
+export function deriveSessionFilePath(
+  header: SpawnSessionHeader,
+  sessionDir: string,
+): string {
+  const fileTimestamp = header.timestamp.replace(/[:.]/g, "-");
+  return `${sessionDir}/${fileTimestamp}_${header.id}.jsonl`;
+}
+
+/**
+ * 在 sessionDir 中按 sessionId 后缀匹配查找实际存在的 session 文件。
+ *
+ * 兜底机制：deriveSessionFilePath 基于命名规则推导，若 pi 命名规则变化导致
+ * 推导路径不存在，用 sessionId 作为后缀匹配实际文件。sessionId 是 header
+ * 的稳定标识，文件名必含它，匹配可靠。
+ *
+ * @returns 匹配到的文件绝对路径，或 undefined（无匹配）
+ */
+export function findSessionFileByHeaderId(
+  sessionDir: string,
+  sessionId: string,
+): string | undefined {
+  try {
+    const files = fs.readdirSync(sessionDir);
+    // 文件名格式：<fileTimestamp>_<sessionId>.jsonl，sessionId 是后缀（去掉 .jsonl）
+    const match = files.find((f) => f.endsWith(`_${sessionId}.jsonl`));
+    return match ? path.join(sessionDir, match) : undefined;
+  } catch {
+    return undefined;
+  }
+}