@zhushanwen/pi-subagent-workflow 8.0.0 → 8.1.0

package/src/execution/__tests__/worktree-registry.test.ts

@@ -45,29 +45,29 @@ describe("WorktreeRegistry", () => {
   });
 
   describe("add + load", () => {
-    it("add 后 load 能读到", () => {
+    it("add 后 load 能读到", async () => {
       const entry = makeEntry();
-      registry.add(entry);
+      await registry.add(entry);
       const loaded = registry.load();
       expect(loaded).toHaveLength(1);
       expect(loaded[0]).toEqual(entry);
     });
 
-    it("多条目跨 repo 共存", () => {
+    it("多条目跨 repo 共存", async () => {
       const entryA = makeEntry({ repo: REPO_A, branch: "pi-sub-bg-1" });
       const entryB = makeEntry({ repo: REPO_B, branch: "pi-sub-bg-2" });
-      registry.add(entryA);
-      registry.add(entryB);
+      await registry.add(entryA);
+      await registry.add(entryB);
       const loaded = registry.load();
       expect(loaded).toHaveLength(2);
     });
 
-    it("同 branch add 覆盖（去重）", () => {
+    it("同 branch add 覆盖（去重）", async () => {
       const entry = makeEntry({ pid: 0 });
-      registry.add(entry);
+      await registry.add(entry);
       // 同 branch 再次 add（覆盖）
       const updated = makeEntry({ pid: 999 });
-      registry.add(updated);
+      await registry.add(updated);
       const loaded = registry.load();
       expect(loaded).toHaveLength(1);
       expect(loaded[0].pid).toBe(999);
@@ -75,25 +75,25 @@ describe("WorktreeRegistry", () => {
   });
 
   describe("updatePid", () => {
-    it("补全 pid（create 占位 → first header 补全）", () => {
-      registry.add(makeEntry({ branch: "pi-sub-bg-1", pid: 0 }));
-      registry.updatePid("pi-sub-bg-1", 12345);
+    it("补全 pid（create 占位 → first header 补全）", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1", pid: 0 }));
+      await registry.updatePid("pi-sub-bg-1", 12345);
       const loaded = registry.load();
       expect(loaded[0].pid).toBe(12345);
     });
 
-    it("branch 不存在时忽略（幂等）", () => {
-      registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
-      registry.updatePid("pi-sub-nonexistent", 12345);
+    it("branch 不存在时忽略（幂等）", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
+      await registry.updatePid("pi-sub-nonexistent", 12345);
       const loaded = registry.load();
       expect(loaded).toHaveLength(1);
       expect(loaded[0].pid).toBe(0); // 原条目未变
     });
 
-    it("update 不改变其他字段", () => {
+    it("update 不改变其他字段", async () => {
       const entry = makeEntry({ branch: "pi-sub-bg-1", repo: REPO_A, checkout: "/tmp/x" });
-      registry.add(entry);
-      registry.updatePid("pi-sub-bg-1", 999);
+      await registry.add(entry);
+      await registry.updatePid("pi-sub-bg-1", 999);
       const loaded = registry.load();
       expect(loaded[0].repo).toBe(REPO_A);
       expect(loaded[0].checkout).toBe("/tmp/x");
@@ -102,60 +102,98 @@ describe("WorktreeRegistry", () => {
   });
 
   describe("remove", () => {
-    it("移除指定 branch", () => {
-      registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
-      registry.add(makeEntry({ branch: "pi-sub-bg-2" }));
-      registry.remove("pi-sub-bg-1");
+    it("移除指定 branch", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
+      await registry.add(makeEntry({ branch: "pi-sub-bg-2" }));
+      await registry.remove("pi-sub-bg-1");
       const loaded = registry.load();
       expect(loaded).toHaveLength(1);
       expect(loaded[0].branch).toBe("pi-sub-bg-2");
     });
 
-    it("branch 不存在时忽略（幂等）", () => {
-      registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
-      registry.remove("pi-sub-nonexistent");
+    it("branch 不存在时忽略（幂等）", async () => {
+      await registry.add(makeEntry({ branch: "pi-sub-bg-1" }));
+      await registry.remove("pi-sub-nonexistent");
       expect(registry.load()).toHaveLength(1);
     });
 
-    it("空注册表 remove 不报错", () => {
-      expect(() => registry.remove("pi-sub-anything")).not.toThrow();
+    it("空注册表 remove 不报错", async () => {
+      await expect(registry.remove("pi-sub-anything")).resolves.not.toThrow();
     });
   });
 
   describe("降级与健壮性", () => {
-    it("文件不存在时 load 返回空数组", () => {
+    it("文件不存在时 load 返回空数组", async () => {
       expect(registry.load()).toEqual([]);
     });
 
-    it("损坏 JSON 时 load 返回空数组", () => {
+    it("损坏 JSON 时 load 返回空数组", async () => {
       fs.mkdirSync(path.dirname(registryFile), { recursive: true });
       fs.writeFileSync(registryFile, "{ not valid json }}}", "utf-8");
       expect(registry.load()).toEqual([]);
     });
 
-    it("entries 字段缺失时 load 返回空数组", () => {
+    it("entries 字段缺失时 load 返回空数组", async () => {
       fs.mkdirSync(path.dirname(registryFile), { recursive: true });
       fs.writeFileSync(registryFile, '{"other": 123}', "utf-8");
       expect(registry.load()).toEqual([]);
     });
 
-    it("save 创建不存在的父目录", () => {
+    it("save 创建不存在的父目录", async () => {
       // registryFile 在 tmpAgentDir/subagents/ 下，subagents 目录不存在
       expect(fs.existsSync(path.dirname(registryFile))).toBe(false);
-      registry.add(makeEntry());
+      await registry.add(makeEntry());
       expect(fs.existsSync(registryFile)).toBe(true);
     });
 
-    it("save 后无残留 .tmp 文件（原子写）", () => {
-      registry.add(makeEntry());
+    it("save 后无残留 .tmp 文件（原子写）", async () => {
+      await registry.add(makeEntry());
       const tmpFile = `${registryFile}.tmp`;
       expect(fs.existsSync(tmpFile)).toBe(false);
     });
   });
 
   describe("SPAWN_GRACE_MS 常量", () => {
-    it("值为 60s", () => {
+    it("值为 60s", async () => {
       expect(SPAWN_GRACE_MS).toBe(60_000);
     });
   });
+
+  describe("D5a 锁互斥（两写方并发不丢条目）", () => {
+    // [HISTORICAL] 2026-08-20 PR #185：真实 proper-lockfile 文件锁 RMW 用例显式超时——
+    // 单跑 >1s，整包满并行 + 系统余载下 100/31 次持锁 load→mutate→save 超过 vitest
+    // 默认 5s testTimeout（隔离跑通过，纯环境饿死），对齐本包 record-store-index 口径。
+    it("两个 registry 实例（模拟两 pi 进程写方）并发各 add 50 条，零丢失", { timeout: 30_000 }, async () => {
+      // 失败模式 G 的复现形态：无锁时两实例 load→mutate→save 交错，后写者覆盖
+      // 先写者 → 条目丢失。锁内 RMW 应保证 100 条全部落盘。
+      const r1 = new WorktreeRegistry(tmpAgentDir);
+      const r2 = new WorktreeRegistry(tmpAgentDir);
+      const tasks: Promise<void>[] = [];
+      for (let i = 0; i < 50; i++) {
+        tasks.push(r1.add(makeEntry({ branch: `pi-sub-w1-${i}` })));
+        tasks.push(r2.add(makeEntry({ branch: `pi-sub-w2-${i}` })));
+      }
+      await Promise.all(tasks);
+      const loaded = r1.load();
+      expect(loaded).toHaveLength(100);
+      // 两写方的条目都在（非「后写者全量覆盖」形态）
+      expect(loaded.filter((e) => e.branch.startsWith("pi-sub-w1-"))).toHaveLength(50);
+      expect(loaded.filter((e) => e.branch.startsWith("pi-sub-w2-"))).toHaveLength(50);
+    });
+
+    it("并发 add + remove 交错：remove 只删自己的 branch", { timeout: 30_000 }, async () => {
+      const r1 = new WorktreeRegistry(tmpAgentDir);
+      const r2 = new WorktreeRegistry(tmpAgentDir);
+      await r1.add(makeEntry({ branch: "pi-sub-keep" }));
+      const tasks: Promise<void>[] = [];
+      for (let i = 0; i < 30; i++) {
+        tasks.push(r2.add(makeEntry({ branch: `pi-sub-n-${i}` })));
+      }
+      tasks.push(r1.remove("pi-sub-keep"));
+      await Promise.all(tasks);
+      const loaded = r1.load();
+      expect(loaded).toHaveLength(30);
+      expect(loaded.find((e) => e.branch === "pi-sub-keep")).toBeUndefined();
+    });
+  });
 });

package/src/execution/agent-result-mapper.ts

@@ -8,6 +8,9 @@
 import type { AgentResult as WorkflowAgentResult, AgentUsage as WorkflowAgentUsage, ToolCallEntry } from "../orchestration/models/types.ts";
 import type { AgentResult as SubagentsAgentResult, AgentUsageTotal, ToolCall } from "./types.ts";
 
+/** safeStringify 的 JSON 截断长度（字符），防大对象拼进 toolCalls 挤爆 trace。 */
+const TOOL_ARGS_JSON_MAX_CHARS = 500;
+
 /**
  * D-A10: subagents AgentResult → workflow AgentResult 映射。
  *
@@ -80,7 +83,7 @@ function mapToolCalls(calls: ToolCall[]): ToolCallEntry[] {
 function safeStringify(value: unknown): string {
   try {
     const s = JSON.stringify(value);
-    return s.length > 500 ? `${s.slice(0, 500)}...` : s;
+    return s.length > TOOL_ARGS_JSON_MAX_CHARS ? `${s.slice(0, TOOL_ARGS_JSON_MAX_CHARS)}...` : s;
   } catch {
     return String(value);
   }

package/src/execution/argv-mirror.ts

@@ -41,7 +41,7 @@ const ARGV_FLAG_START = 2;
  * 解析规则：
  * - --no-extensions / -ne、--approve / -a：布尔 flag
  * - --no-context-files / -nc：布尔 flag（镜像理由：--extension 镜像会把
- *   xyz-system-prompt-extension.js 带进每个 subagent，该扩展靠子进程自己的
+ *   @zhushanwen/pi-system-prompt 带进每个 subagent，该扩展靠子进程自己的
  *   argv 检测此 flag 决定是否注入全局 AGENTS.md——不镜像则用户 opt-out
  *   在 subagent 路径失效）
  * - --extension / -e：支持 `--extension <path>`（空格）与 `--extension=<path>`（等号）

package/src/execution/channel-registry-access.ts

@@ -76,7 +76,9 @@ function readHandshakeSlot(): ChannelRegistryHandshake | undefined {
     );
     return undefined;
   }
-  const version = (slot as { version?: unknown }).version;
+  // 断言目标含必填 version 字段（object/null 已守卫；version 值本身在下一行校验），
+  // 对齐 format.ts extractAgentName 的必填字段断言先例，避免全可选断言零校验。
+  const version = (slot as { version: unknown }).version;
   if (version !== HANDSHAKE_VERSION) {
     logger.warn(
       `[pi-subagent-workflow] channel handshake version mismatch (got ${String(

package/src/execution/finalize-record.ts

@@ -191,12 +191,14 @@ export async function doFinalizeRoundToIdle(
 ): Promise<void> {
   // MF-2：设 record.result 供 notifier idle 回复正文（否则恒 "(empty)"，G1/G2 不成立）。
   // MF-6 兜底：失败轮次（success=false）的 result.text 可能为空，用 error 让 notify 可读。
-  // [增量 G2] 第三分支 chatMode 条件占位：本写点被 one-shot 成功路径共用（subagent-service
-  // runAndFinalize 的 `!record.chatMode && !aborted && result.success` 分支 → finalizeRoundToIdle），
-  // 非 chatMode 必须保持 `|| record.result` 现状——one-shot 空文本成功完成（collectResult
-  // getFullText 返回 ""、success=true、真实可达）时 result 前值 undefined → notifier
-  // buildLlmContent 的 `record.result ?? "(empty)"` 兜底确定性产出 "(empty)"，通知逐字节
-  // 不变（G4）；无条件替换会把文案漂移为占位。chatMode 空增量轮 → 固定占位
+  // [R2-1] 轮终写点恒写非空：one-shot 空文本成功完成（collectResult getFullText 返回 ""、
+  // success=true、真实可达，本写点被 subagent-service runAndFinalize 的成功分支共用）首轮
+  // result 前值 undefined，兜底补 "(empty)" 占位——措辞与 notifier buildLlmContent 的
+  // `record.result ?? "(empty)"` 兜底同款，通知文案逐字节不变（[增量 G2] G4 取舍保持）。
+  // 轮终信号优先：record.result 非 undefined 是 renderer hasRunning 排除「轮终
+  // running-resumable」的判据（shared SubagentRecord.result 契约），保持 undefined 会让
+  // 完成注入后末位 turn 永久「工作中」。续轮（前值存在）沿用前值：one-shot 无增量语义，
+  // record.result = 该 subagent 最终输出。chatMode 空增量轮 → 固定占位
   // "(no output this round)"（D5：增量语义下沿用旧 record.result = 上一轮增量，本轮通知
   // 正文 = 上一轮内容，父 agent 误读为原样重复回复）。
   let nextResult: string | undefined;
@@ -207,7 +209,7 @@ export async function doFinalizeRoundToIdle(
   } else if (record.chatMode) {
     nextResult = "(no output this round)";
   } else {
-    nextResult = record.result;
+    nextResult = record.result ?? "(empty)";
   }
   record.result = nextResult;
 
@@ -236,6 +238,13 @@ export async function doFinalizeRoundToIdle(
   record.closedReason = undefined;
   record.round = (record.round ?? 0) + 1;
   record.idleSince = Date.now();
+  // 执行态信号（residual-fixes）：轮终回 running-resumable = 无活进程驱动（idle timer
+  // 回收/保活等待续聊），GUI 侧据此判 waiting（非 streaming）。冷路径续轮（进程启动）清除。
+  record.resumable = true;
+
+  // W16 [D4]：轮终回 running-resumable 是类外状态写点（record 留内存不走 archive），
+  // 显式上报迁移——entry 携带新 round 与本轮 result，pi 文件的重建源不滞后。
+  deps.store.reportRecordTransition(record);
 
   // [review 修复] 已删除残留 pendingMessages 的 redeliverPending 补投段（MF-1 消费
   // 确认安全网）：三段消费链随 deliverToRunning 一并移除，本段不可达。

package/src/execution/idle-gc.ts

@@ -0,0 +1,47 @@
+/**
+ * SP-4 idle record GC：30 天 TTL 定时归档，防 idle record 永久驻留内存。
+ * 从 subagent-service.ts 抽出（文件超 max-lines；逻辑自包含：interval + TTL 扫描）。
+ * 启动幂等由调用方（service.startGcTimer）守卫；返回 stop 函数供 dispose 清理。
+ */
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { bestEffort } from "./best-effort.ts";
+import { isResumable } from "./lifecycle-predicates.ts";
+import type { RecordStore } from "./record-store.ts";
+
+const logger = getLogger("subagents");
+
+/** GC 扫描间隔：1 小时。 */
+// eslint-disable-next-line no-magic-numbers -- 60*60*1000 = 1h 的毫秒换算常数
+const GC_INTERVAL_MS = 60 * 60 * 1000;
+/** idle record TTL：30 天（超龄归档）。 */
+// eslint-disable-next-line no-magic-numbers -- 30*24*60*60*1000 = 30d 的毫秒换算常数
+const IDLE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
+/** 毫秒/天（GC 日志的 d 换算）。 */
+// eslint-disable-next-line no-magic-numbers -- 24*60*60*1000 = 1d 的毫秒换算常数
+const MS_PER_DAY = 24 * 60 * 60 * 1000;
+
+/**
+ * 启动 idle record GC 定时器，返回 stop 函数（清理 interval；幂等）。
+ * 每个扫描周期：对 store 内全部 active record 中 resumable 且带 idleSince 的，
+ * 超过 IDLE_TTL_MS 的归档（archive 单条失败不阻断其余，bestEffort 留痕）。
+ */
+export function startIdleGc(store: RecordStore): () => void {
+  const timer = setInterval(() => {
+    const now = Date.now();
+    for (const record of store.listAllActive()) {
+      if (isResumable(record) && record.idleSince) {
+        const age = now - record.idleSince;
+        if (age > IDLE_TTL_MS) {
+          logger.warn(`[subagents] GC: archiving idle record ${record.id} (idle for ${Math.round(age / MS_PER_DAY)}d)`);
+          try {
+            store.archive(record);
+          } catch (err) {
+            bestEffort(err, `GC archive record ${record.id}`);
+          }
+        }
+      }
+    }
+  }, GC_INTERVAL_MS);
+  timer.unref?.();
+  return () => clearInterval(timer);
+}

package/src/execution/lifecycle-manager.ts

@@ -28,13 +28,19 @@
 // 默认常量
 // ============================================================
 
+/** 毫秒/秒（时间换算常数）。 */
+const MS_PER_SECOND = 1000;
+/** 秒/分钟（时间换算常数）。 */
+const SECONDS_PER_MINUTE = 60;
+
 /**
  * 默认 idle 超时（per-record）。
  *
  * V2 §5.4 / 决策 4：初拟 ≤ prompt cache TTL（~5min）——超出 cacheTTL 的活进程白占
  * 内存（续聊仍 cache miss），小于则 kill 丢热 cache。实测定（P-timeout）。
  */
-export const DEFAULT_IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 分钟
+const IDLE_TIMEOUT_MINUTES = 5;
+export const DEFAULT_IDLE_TIMEOUT_MS = IDLE_TIMEOUT_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND;
 
 /**
  * 从环境变量 XYZ_SUBAGENT_IDLE_TIMEOUT_MS 读取全局默认超时。
@@ -376,7 +382,8 @@ const activateLockTails = new Map<string, Promise<void>>();
  * 的错误（调用方可用 message action 重试）。30s 远超正常冷路径 resume spawn 耗时（~ms 级），
  * 留足异常恢复余量而不误伤正常排队。
  */
-const ACTIVATE_LOCK_TIMEOUT_MS = 30 * 1000;
+const ACTIVATE_LOCK_TIMEOUT_SECONDS = 30;
+const ACTIVATE_LOCK_TIMEOUT_MS = ACTIVATE_LOCK_TIMEOUT_SECONDS * MS_PER_SECOND;
 
 export function acquireActivateLock(recordId: string): Promise<() => void> {
   const prev = activateLockTails.get(recordId) ?? Promise.resolve();

package/src/execution/record-entry.ts

@@ -0,0 +1,118 @@
+// src/execution/record-entry.ts
+//
+// W16 [D4]：subagent record 自描述持久化 entry 的形态权威。
+//
+// pi 文件（session JSONL）是扩展数据持久化权威：record 状态每次迁移都经
+// pi.appendEntry 落一条自描述完整快照（字段即 SubagentRecord），读取方无需
+// 逆向解析 toolCall/toolResult。内存 record-store 保持运行时权威，entry 是
+// 重建源（两者不冲突）。
+//
+// customType 与既有 `subagent-identity`（session 文件首行身份 entry）同族命名
+//（连字符风格）；写点见 record-store.ts 的状态迁移点（register/archive/
+// reportRecordTransition），custom entry 由 pi 写进 session JSONL，不进 LLM context。
+
+import type {
+  AgentEventLogEntry,
+  ClosedReason,
+  DisplayItem,
+  ExecutionMode,
+  ExecutionStatus,
+  SubagentRecord,
+} from "./types.ts";
+
+/** 自描述 record entry 的 customType。写点字面量与本常量的等值由
+ *  __tests__/record-store.test.ts 断言钉住（消费方引用本常量，勿用裸字符串）。 */
+export const SUBAGENT_RECORD_CUSTOM_TYPE = "subagent-record";
+
+/**
+ * `subagent-record` entry 的 data schema（v1）。
+ *
+ * = 完整 SubagentRecord 快照（GUI 侧列表/详情需要的全部持久化字段）+ 版本号。
+ * 显式排除三个非持久化字段（与 SubagentRecord 的差集）：
+ *   - currentActivity：running 时的瞬时流态，重开 session 无重建价值；
+ *   - externalInstance：跨重启探活态（pid/startedAt），由 .alive sidecar 重建；
+ *   - worktreeHandle：不可 JSON 序列化的运行时句柄（布尔投影 worktree 保留）。
+ *
+ * undefined 字段经 JSON.stringify 自然缺省（与 SubagentRecord 重建侧语义一致）。
+ */
+export interface SubagentRecordEntryData {
+  /** schema 版本（W16 起 v1）。消费方按 v 判别解析，不认识的版本跳过而非猜测。 */
+  v: 1;
+  id: string;
+  agent: string;
+  /** 任务提示词（详情面板置顶展示）。 */
+  task: string;
+  /** 短标签（≤35 字符）。 */
+  slug: string;
+  status: ExecutionStatus;
+  /** L2 关闭原因（仅 status="closed" 时有意义）。 */
+  closedReason?: ClosedReason;
+  mode: ExecutionMode;
+  startedAt: number;
+  /** 根 Pi session ID（session 隔离过滤用）。 */
+  rootSessionId: string | undefined;
+  /** 直接父 subagent record ID（层级树构建用）。顶层为 undefined。 */
+  parentRecordId: string | undefined;
+  /** subagent 递归深度。顶层 = 0。 */
+  depth: number;
+  endedAt: number | undefined;
+  /** turn 计数。 */
+  turns: number;
+  totalTokens: number;
+  model: string;
+  thinkingLevel: string | undefined;
+  /** 详情事件日志（/subagents 详情面板）。 */
+  eventLog: AgentEventLogEntry[];
+  /** 从 turns[] 派生的展示项。 */
+  displayItems: DisplayItem[];
+  result?: string;
+  error?: string;
+  sessionFile?: string;
+  /** [MF#3] worktree 模式改动 patch 文件路径。 */
+  patchFile?: string;
+  /** 创建时是否启用 worktree 隔离。 */
+  worktree?: boolean;
+  /** 对话轮次计数（仅 chatMode 有意义；round+1 由轮终迁移写点携带）。 */
+  round?: number;
+  /**
+   * 对话模式标志（residual-fixes）：chat 与否——GUI 侧 done/waiting 细分判据
+   * （one-shot 轮终 chatMode=false + result 有值 → 完成态）。register 起写入显式值
+   * （one-shot 为显式 false）；v1 前存量 entry 缺省，消费端按保守方向处理。
+   */
+  chatMode?: boolean;
+  /** 执行态信号（residual-fixes）：true = 无活进程驱动的 running（轮终/孤儿兜底）。 */
+  resumable?: boolean;
+}
+
+/** SubagentRecord → 自描述 entry data（快照投影，不 mutate 源）。 */
+export function toSubagentRecordEntry(record: SubagentRecord): SubagentRecordEntryData {
+  return {
+    v: 1,
+    id: record.id,
+    agent: record.agent,
+    task: record.task,
+    slug: record.slug,
+    status: record.status,
+    closedReason: record.closedReason,
+    mode: record.mode,
+    startedAt: record.startedAt,
+    rootSessionId: record.rootSessionId,
+    parentRecordId: record.parentRecordId,
+    depth: record.depth,
+    endedAt: record.endedAt,
+    turns: record.turns,
+    totalTokens: record.totalTokens,
+    model: record.model,
+    thinkingLevel: record.thinkingLevel,
+    eventLog: record.eventLog,
+    displayItems: record.displayItems,
+    result: record.result,
+    error: record.error,
+    sessionFile: record.sessionFile,
+    patchFile: record.patchFile,
+    worktree: record.worktree,
+    round: record.round,
+    chatMode: record.chatMode,
+    resumable: record.resumable,
+  };
+}