@zhushanwen/pi-subagent-workflow 7.3.4 → 8.0.0

package/src/execution/session-pending.ts

@@ -25,18 +25,47 @@ const RECENT_UNREGISTER_WINDOW_MS = 60_000;
 
 /** 判定结果：count > 0 = 有活跃后代（应保持进程等唤醒）。 */
 export interface ActivePendingResult {
-	count: number;
-	/** 最近窗口内（60s）有 pending:unregister——后代刚完成，唤醒通知可能在路上。 */
-	recentUnregister: boolean;
-	/** 读取/解析失败的原因（undefined = 成功）。调用方对 error 采取保守策略（不 kill）。 */
-	error?: string;
+  count: number;
+  /** 最近窗口内（60s）有 pending:unregister——后代刚完成，唤醒通知可能在路上。 */
+  recentUnregister: boolean;
+  /** 读取/解析失败的原因（undefined = 成功）。调用方对 error 采取保守策略（不 kill）。 */
+  error?: string;
 }
 
 /**
- * 读 session 文件计算活跃 pending 数。
+ * [perf] per-file 增量游标：session 文件 append-only，同文件重复判定（层主被多个
+ * 后代唤醒 N 次 → N 次 agent_end）只需读上次 offset 之后的新增行，累计 entries
+ * 差集语义与全量读完全一致。fork 继承的大 session（数十 MB）从「每次整读」降为
+ * 「首读全量 + 后续增量」。
+ * truncate/重建防御：size < offset → 重置全读。EOF 半行（写入竞态）不入账，
+ * offset 只推进到完整行边界，下次补读。
+ * 内存量级：每 sessionFile 一条（offset + 后代 entries，均有限）；测试隔离用
+ * clearPendingCursors()。
+ */
+interface PendingReadCursor {
+  offset: number;
+  entries: unknown[];
+  latestUnregisterMs: number;
+}
+
+const cursors = new Map<string, PendingReadCursor>();
+
+/** 清空增量游标缓存（测试隔离用）。 */
+export function clearPendingCursors(): void {
+  cursors.clear();
+}
+
+/** [taste/no-unsafe-cast] pending 行的最小结构守卫：非 null object 即可（字段访问
+ *  侧均做了 undefined 检查，全可选类型断言无校验意义，改守卫带运行时检查）。 */
+function isPendingLineLike(v: unknown): v is { customType?: string; timestamp?: string } {
+  return typeof v === "object" && v !== null;
+}
+
+/**
+ * 读 session 文件计算活跃 pending 数（增量读，见 PendingReadCursor）。
  *
  * 快速路径：行内含 pending 值（`"pending:register"` / `"pending:unregister"`）才解析，
- * 大文件（fork 继承主 session）只付 includes 扫描跳过大量 message 行的 JSON.parse。
+ * 大量 message 行只付 includes 扫描跳过 JSON.parse。
  * [S-4] 按值匹配而非 `"customType":"pending:` 序列化格式——后者耦合 pi 的 JSON 序列化
  * 空格习惯（冒号后无空格），pi 改 pretty-print 会导致全过滤 → count=0 → keep-alive
  * 静默失效 → recursive tree 被杀、steer 丢失。值字符串本身不受序列化空格影响。
@@ -45,45 +74,87 @@ export interface ActivePendingResult {
  * 坏行跳过（append 中途崩溃的截断行）。
  */
 export function readActivePendingFromSessionFile(
-	sessionFile: string | undefined,
+  sessionFile: string | undefined,
 ): ActivePendingResult {
-	if (!sessionFile) {
-		return { count: 0, recentUnregister: false, error: "no sessionFile (handshake not settled)" };
-	}
-	let raw: string;
-	try {
-		raw = fs.readFileSync(sessionFile, "utf-8");
-	} catch (err) {
-		return {
-			count: 0,
-			recentUnregister: false,
-			error: `session file unreadable: ${err instanceof Error ? err.message : String(err)}`,
-		};
-	}
+  if (!sessionFile) {
+    return { count: 0, recentUnregister: false, error: "no sessionFile (handshake not settled)" };
+  }
+
+  let size: number;
+  try {
+    size = fs.statSync(sessionFile).size;
+  } catch (err) {
+    return {
+      count: 0,
+      recentUnregister: false,
+      error: `session file unreadable: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  let cursor = cursors.get(sessionFile);
+  if (cursor === undefined || size < cursor.offset) {
+    // 首次（全量）或文件被 truncate/重建（offset 越界）→ 重置从头读
+    cursor = { offset: 0, entries: [], latestUnregisterMs: 0 };
+  }
+
+  let chunk: string;
+  try {
+    if (cursor.offset === 0) {
+      chunk = fs.readFileSync(sessionFile, "utf-8");
+    } else {
+      const fd = fs.openSync(sessionFile, "r");
+      try {
+        const len = size - cursor.offset;
+        const buf = Buffer.alloc(len);
+        let total = 0;
+        while (total < len) {
+          const n = fs.readSync(fd, buf, total, len - total, cursor.offset + total);
+          if (n <= 0) break;
+          total += n;
+        }
+        chunk = buf.toString("utf-8", 0, total);
+      } finally {
+        fs.closeSync(fd);
+      }
+    }
+  } catch (err) {
+    return {
+      count: 0,
+      recentUnregister: false,
+      error: `session file unreadable: ${err instanceof Error ? err.message : String(err)}`,
+    };
+  }
+
+  // 只消费到最后一个完整行：EOF 半行（append 写入竞态）不入账，offset 不推进，
+  // 下次从该行起点重读（补全后正常入账）。
+  const lastNl = chunk.lastIndexOf("\n");
+  const complete = lastNl === -1 ? "" : chunk.slice(0, lastNl);
+  cursor.offset += Buffer.byteLength(complete, "utf-8");
+  cursors.set(sessionFile, cursor);
 
-	const entries: unknown[] = [];
-	let latestUnregisterMs = 0;
-	for (const line of raw.split("\n")) {
-		// [S-4] 按值匹配：countActiveFromEntries 只消费 register/unregister 两种 customType，
-		// 故只需检测这两个值字符串；冒号前后空格变化不影响（值始终是连续子串）。
-		if (!line.includes('"pending:register"') && !line.includes('"pending:unregister"')) continue;
-		try {
-			const entry = JSON.parse(line) as { customType?: string; timestamp?: string };
-			entries.push(entry);
-			if (entry.customType === "pending:unregister" && entry.timestamp) {
-				const ts = Date.parse(entry.timestamp);
-				if (Number.isFinite(ts) && ts > latestUnregisterMs) latestUnregisterMs = ts;
-			}
-		} catch {
-			// 截断行/坏行跳过——不影响其余 entry 的差集判定（罕见：append 中途崩溃）
-			console.debug("[session-pending] skipped malformed pending line in", sessionFile);
-		}
-	}
+  for (const line of complete.split("\n")) {
+    // [S-4] 按值匹配：countActiveFromEntries 只消费 register/unregister 两种 customType，
+    // 故只需检测这两个值字符串；冒号前后空格变化不影响（值始终是连续子串）。
+    if (!line.includes('"pending:register"') && !line.includes('"pending:unregister"')) continue;
+    try {
+      const entry: unknown = JSON.parse(line);
+      if (!isPendingLineLike(entry)) continue;
+      cursor.entries.push(entry);
+      if (entry.customType === "pending:unregister" && entry.timestamp) {
+        const ts = Date.parse(entry.timestamp);
+        if (Number.isFinite(ts) && ts > cursor.latestUnregisterMs) cursor.latestUnregisterMs = ts;
+      }
+    } catch {
+      // 截断行/坏行跳过——不影响其余 entry 的差集判定（罕见：append 中途崩溃）
+      console.debug("[session-pending] skipped malformed pending line in", sessionFile);
+    }
+  }
 
-	const active = countActiveFromEntries(entries);
-	return {
-		count: active.count,
-		recentUnregister:
-			latestUnregisterMs > 0 && Date.now() - latestUnregisterMs < RECENT_UNREGISTER_WINDOW_MS,
-	};
+  const active = countActiveFromEntries(cursor.entries);
+  return {
+    count: active.count,
+    recentUnregister:
+      cursor.latestUnregisterMs > 0 &&
+      Date.now() - cursor.latestUnregisterMs < RECENT_UNREGISTER_WINDOW_MS,
+  };
 }

package/src/execution/session-reconstructor.ts

@@ -98,6 +98,17 @@ export interface SubagentIdentityData {
   depth?: number;
   /** [MF#4] 本 session 的 fork 深度（session-runner 写入 parentForkDepth+1）。旧文件可能缺失。 */
   forkDepth?: number;
+  /**
+   * 对话模式标志（可持续对话 subagent）。旧文件缺失 → undefined（按一次性模式处理）。
+   * session-runner 写入；reconstructFromFile 经 ...identity 展开自动透传到 ReconstructedRecord。
+   */
+  chatMode?: boolean;
+  /**
+   * [review round2] worktree 隔离标志（该 subagent 创建时 worktree:true）。旧文件缺失 →
+   * undefined。仅供跨重启重建路径判定「worktree 绑定已丢失」——WorktreeHandle 本身不可
+   * 序列化，跨重启后无法 reattach，续聊须拒绝（防 resume cwd 静默回落主 repo 破坏隔离）。
+   */
+  worktree?: boolean;
   /** @deprecated 兼容旧文件：旧 identity entry 写的是 parentSessionId，读取时 fallback 到 rootSessionId。 */
   parentSessionId?: string;
 }
@@ -142,9 +153,21 @@ export interface ReconstructedRecord {
   depth: number;
   /** [MF#4] 本 session 的 fork 深度（来自 identity custom entry；旧文件为 undefined）。 */
   forkDepth: number | undefined;
+  /** 对话模式标志（来自 identity custom entry；旧文件为 undefined）。 */
+  chatMode?: boolean;
+  /** [review round2] worktree 隔离标志（见 SubagentIdentityData.worktree）。 */
+  worktree?: boolean;
+  /**
+   * 对话轮次计数（非 identity entry 字段，reconstructFromFile 不填）。
+   * V2 idle record 的 round 只在内存维护（doFinalizeRoundToIdle 递增），磁盘重建不恢复。
+   */
+  round?: number;
   sessionFile: string;
   // ── 可变状态（来自 message entries）──
   status: ExecutionStatus;
+  /** L2 关闭原因子枚举（仅 status="closed" 时有意义）。SP-1 新增。
+   *  从 stopReason 推导：error/aborted → gc；其余 → gc。 */
+  closedReason?: import("./types.ts").ClosedReason;
   turns: Turn[];
   turnCount: number;
   totalTokens: number;
@@ -276,6 +299,9 @@ interface PendingToolCall {
  *
  * status 由最后一条 assistant message 的 stopReason 推导（error/aborted → failed，
  * 其余 → done）。cancelled 由 tombstone override（record-store 层），本函数不感知。
+ *
+ * [perf] 本函数是重路径（全文读 + 全 entry 解析）。列表扫描用 readIdentityHeader
+ * （只读头部 identity），详情才走本函数（RecordStore.getFullRecord 懒加载）。
  */
 export function reconstructFromFile(sessionFile: string): ReconstructedRecord | undefined {
   // 读文件 + 逐行 JSON.parse（session.jsonl = newline-delimited JSON）。
@@ -338,8 +364,6 @@ export function reconstructFromFile(sessionFile: string): ReconstructedRecord |
   const pending: PendingToolCall[] = [];
   let lastError: string | undefined;
   let totalTokens = 0;
-  /** 最后一条 assistant message 的 stopReason（推导终态 status）。 */
-  let lastStopReason: string | undefined;
   /** 最后一条 entry 的时间戳（ms），推导 endedAt（避免重建 record 耗时随墙钟无限增长）。 */
   let lastEntryTsMs: number | undefined;
 
@@ -386,7 +410,7 @@ export function reconstructFromFile(sessionFile: string): ReconstructedRecord |
       // stopReason 驱动 lastError（与 updateFromEvent 一致）：
       // error/aborted → 设 lastError；stop（正常结束）→ 清 lastError（镜像 turn_end 的清除语义，
       // 即前序 turn 的瞬态 error 在后续成功 turn 后恢复，不误判 success=false）。
-      lastStopReason = msg.stopReason;
+      // [v4 B-1] status 恒 closed 后 lastStopReason 不再参与推导，死变量已删。
       if (msg.stopReason === "error" || msg.stopReason === "aborted") {
         lastError = msg.errorMessage ?? msg.stopReason;
       } else if (msg.stopReason === "stop") {
@@ -429,10 +453,10 @@ export function reconstructFromFile(sessionFile: string): ReconstructedRecord |
   const eventLog = deriveEventLog(turns, lastError, identity.startedAt);
 
   // 终态 status：最后一条 assistant message 的 stopReason 推导（与 finalizeRecord 的判定一致）。
-  // error/aborted → failed；其余（stop/toolUse/length）→ done。
-  // cancelled 由 tombstone override（record-store 层），本函数不感知。
-  const status: ExecutionStatus =
-    lastStopReason === "error" || lastStopReason === "aborted" ? "failed" : "done";
+  // SP-1：done/failed 合并为 closed，cancelled 由 tombstone override（record-store 层），本函数不感知。
+  const status: ExecutionStatus = "closed";
+  // closedReason 统 gc（通用完成/失败）。error/aborted 的区分由 error 字段保留。
+  const closedReason: import("./types.ts").ClosedReason = "gc";
 
   // rootSessionId 归一化：新文件读 rootSessionId，旧文件 fallback parentSessionId。
   const rootSessionId = identity.rootSessionId ?? identity.parentSessionId;
@@ -447,6 +471,7 @@ export function reconstructFromFile(sessionFile: string): ReconstructedRecord |
     forkDepth: identity.forkDepth,
     sessionFile,
     status,
+    closedReason,
     turns,
     turnCount,
     totalTokens,
@@ -459,3 +484,195 @@ export function reconstructFromFile(sessionFile: string): ReconstructedRecord |
     eventLog,
   };
 }
+
+// ============================================================
+// 轻量头部读取（列表扫描用）
+// ============================================================
+
+/** 头部读取字节数。首轮会话 identity 在第 2-3 行；但续聊（resume）场景 session_start
+ *  再次触发，identity append 到文件尾部附近（实测真实目录 1186/1744 文件的 identity
+ *  不在头 64KB）。头部 miss 时由 RecordStore.scanFile 调 readIdentityAnywhere 全文 fallback。 */
+export const IDENTITY_HEAD_BYTES = 65536;
+
+/** 轻量重建产出：仅身份字段 + 头部可见的 model/thinkingLevel（详情字段一律缺省）。 */
+export interface IdentityHeaderRecon {
+  id: string;
+  agent: string;
+  mode: ExecutionMode;
+  task: string;
+  slug: string;
+  startedAt: number;
+  rootSessionId: string | undefined;
+  parentRecordId: string | undefined;
+  depth: number;
+  forkDepth: number | undefined;
+  chatMode?: boolean;
+  /** [review round2] worktree 隔离标志（见 SubagentIdentityData.worktree）。 */
+  worktree?: boolean;
+  model: string;
+  thinkingLevel: string | undefined;
+  sessionFile: string;
+}
+
+/**
+ * 只读文件头部，解析 identity custom entry（+途经的 model/thinking_level change）。
+ *
+ * 列表扫描专用：单次 readSync 读头部 IDENTITY_HEAD_BYTES 字节，逐行解析到 identity
+ * 即停。不解析 message entries（turns/eventLog/result 等重数据由
+ * RecordStore.getFullRecord 懒加载 reconstructFromFile 补齐）。
+ *
+ * 与 reconstructFromFile 的行为差异（有意）：本函数只要头部有 identity 就返回，
+ * 不要求存在 assistant message——pi 延迟写入策略下无 assistant 的文件几乎不存在，
+ * 若存在（崩溃前 flush）也按分支 4 running 呈现（v4 B-1 可续聊语义），
+ * 而非静默不可见。
+ *
+ * 返回 undefined：文件缺失/读失败/头部无 identity。不抛。
+ * 头部无 identity ≠ 文件无 identity（续聊场景 identity 在尾部附近）——需要覆盖全文件
+ * 时用 readIdentityAnywhere。
+ */
+export function readIdentityHeader(sessionFile: string): IdentityHeaderRecon | undefined {
+  let text: string;
+  try {
+    const fd = fs.openSync(sessionFile, "r");
+    try {
+      const buf = Buffer.alloc(IDENTITY_HEAD_BYTES);
+      let total = 0;
+      while (total < buf.length) {
+        const n = fs.readSync(fd, buf, total, buf.length - total, total);
+        if (n <= 0) break;
+        total += n;
+      }
+      text = buf.toString("utf-8", 0, total);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return undefined; // 文件缺失/不可读 → 降级跳过
+  }
+  return parseIdentityFromText(text, sessionFile);
+}
+
+/**
+ * 全文件找 identity：头部/尾部都 miss 后的最后 fallback（真实数据仅 ~0.2% 走到）。
+ *
+ * 全量 readFileSync + indexOf 预筛（只有含特征串的行才 JSON.parse），从后往前找
+ * （续聊轮次的 identity 靠尾部，最后一次的 identity 最新鲜）。读全文是成本主体
+ * （预筛/parse 可忽略）——调用方（RecordStore）应缓存结果避免重复读。
+ */
+export function readIdentityAnywhere(sessionFile: string): IdentityHeaderRecon | undefined {
+  let text: string;
+  try {
+    text = fs.readFileSync(sessionFile, "utf-8");
+  } catch {
+    return undefined;
+  }
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const s = lines[i];
+    if (!s.includes(IDENTITY_CUSTOM_TYPE)) continue; // 预筛：identity 行必含特征串
+    const recon = parseIdentityFromText(s, sessionFile);
+    if (recon) return recon;
+  }
+  return undefined;
+}
+
+/**
+ * 只读文件尾部找 identity（续聊场景主力命中点：最后一轮 session_start 追加的
+ * identity 离文件尾近，实测真实目录 65% 文件 identity 在尾 64KB）。
+ *
+ * 尾部块首行可能残缺（从行中间开始）——JSON.parse 失败自然跳过，不影响后续行。
+ * model/thinking_level 在尾部块中拿不到 identity 之前的途经 entry，返回空/undefined
+ * （best-effort，详情场景由全量重建补齐）。
+ */
+export function readIdentityTail(sessionFile: string): IdentityHeaderRecon | undefined {
+  let text: string;
+  try {
+    const { size } = fs.statSync(sessionFile);
+    const start = Math.max(0, size - IDENTITY_HEAD_BYTES);
+    const fd = fs.openSync(sessionFile, "r");
+    try {
+      const buf = Buffer.alloc(size - start);
+      let total = 0;
+      while (total < buf.length) {
+        const n = fs.readSync(fd, buf, total, buf.length - total, start + total);
+        if (n <= 0) break;
+        total += n;
+      }
+      text = buf.toString("utf-8", 0, total);
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return undefined;
+  }
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const s = lines[i];
+    if (!s.includes(IDENTITY_CUSTOM_TYPE)) continue;
+    const recon = parseIdentityFromText(s, sessionFile);
+    if (recon) return recon;
+  }
+  return undefined;
+}
+
+/** 从文本片段解析 identity（头部/全文两入口共享）。解析到 identity 即停（返回）；
+ *  找不到返回 undefined。model/thinking_level 仅在 identity 之前的途经 entry 中
+ *  best-effort 提取，详情场景由全量重建补齐。 */
+function parseIdentityFromText(text: string, sessionFile: string): IdentityHeaderRecon | undefined {
+  let identity: SubagentIdentityData | undefined;
+  let model = "";
+  let thinkingLevel: string | undefined;
+  for (const line of text.split("\n")) {
+    const s = line.trim();
+    if (!s) continue;
+    // 预筛（[S-4] 同款值匹配）：只有含三种目标 entry 值串的行才值得 JSON.parse——
+    // head 64KB 内大 toolResult 行（数十 KB/行）占多数，全量 parse 是冷扫描 CPU 大头。
+    // 值字符串在任意序列化格式下连续出现，不耦合 pi 的空格习惯。
+    if (
+      !s.includes(IDENTITY_CUSTOM_TYPE) &&
+      !s.includes('"model_change"') &&
+      !s.includes('"thinking_level_change"')
+    ) {
+      continue;
+    }
+    let entry: JsonlEntry;
+    try {
+      entry = JSON.parse(s) as JsonlEntry;
+    } catch {
+      continue; // 损坏行/截断行（头部读取边界）跳过
+    }
+    if (entry.type === "custom" && entry.customType === IDENTITY_CUSTOM_TYPE) {
+      if (isIdentityData(entry.data)) {
+        identity = entry.data;
+        break; // 找到即停（后续行不再解析）
+      }
+    } else if (entry.type === "model_change") {
+      if (typeof entry.provider === "string" && typeof entry.modelId === "string") {
+        model = `${entry.provider}/${entry.modelId}`;
+      }
+    } else if (entry.type === "thinking_level_change") {
+      if (typeof entry.thinkingLevel === "string") thinkingLevel = entry.thinkingLevel;
+    }
+  }
+  if (!identity) return undefined;
+
+  // 归一化与全量 recon 同源：rootSessionId fallback 旧字段、slug 兜底空串。
+  const rootSessionId = identity.rootSessionId ?? identity.parentSessionId;
+  return {
+    id: identity.id,
+    agent: identity.agent,
+    mode: identity.mode,
+    task: identity.task,
+    slug: identity.slug ?? "",
+    startedAt: identity.startedAt,
+    rootSessionId,
+    parentRecordId: identity.parentRecordId,
+    depth: identity.depth ?? 0,
+    forkDepth: identity.forkDepth,
+    chatMode: identity.chatMode,
+    worktree: identity.worktree,
+    model,
+    thinkingLevel,
+    sessionFile,
+  };
+}