@zhushanwen/pi-subagent-workflow 8.3.0 → 8.5.0

package/src/execution/__tests__/subprocess-agent-runner.test.ts

@@ -13,9 +13,14 @@
 //   T3.18 (NFR): dispose 兜底覆盖（delegate 后子进程进 spawnedChildren）
 //   T3.19 (NFR): AgentCallOpts→ExecuteOptions 映射保真
 
+import { mkdtempSync, readdirSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
 import { describe, expect, it, vi } from "vitest";
 
 import type { AgentCallOpts, AgentResult } from "../../orchestration/models/types.ts";
+import { replayJournal } from "../engine/common/event-journal.ts";
 import type { SubprocessAgentRunnerDeps } from "../subprocess-agent-runner.ts";
 import { SubprocessAgentRunner } from "../subprocess-agent-runner.ts";
 
@@ -284,12 +289,12 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
       });
     });
 
-    it("无 workflow onEvent → 不传 bridgedOnEvent", async () => {
-      let bridgedOnEvent: ((e: Record<string, unknown>) => void) | undefined;
+    it("无 workflow onEvent → 引擎仍收到包装 onEvent（P2 journal 通道恒开）", async () => {
+      let engineOnEvent: ((e: Record<string, unknown>) => void) | undefined;
       const mockService = createMockService(
         vi.fn().mockImplementation(
           (_opts: Record<string, unknown>, _signal?: AbortSignal, onEvent?: (e: Record<string, unknown>) => void) => {
-            bridgedOnEvent = onEvent;
+            engineOnEvent = onEvent;
             return Promise.resolve(makeMockResult());
           },
         ),
@@ -299,8 +304,51 @@ describe("SubprocessAgentRunner (wave-4 delegate)", () => {
 
       await sar.run(makeBaseOpts(), new AbortController().signal);
 
-      // 不传 workflow onEvent → bridgedOnEvent 应为 undefined
-      expect(bridgedOnEvent).toBeUndefined();
+      // P2 接线（设计 D6 第②级）：SAR 包装 onEvent 写 journal 后转发——原 onEvent
+      // 未传时也恒传包装版（全引擎免费获得 journal；P1「undefined 透传」细节已被
+      // 有意变更，本用例锁定新语义：引擎侧 onEvent 通道恒开）
+      expect(typeof engineOnEvent).toBe("function");
+      // 包装版不向外抛（journal append 是同步入队）
+      expect(() => engineOnEvent?.({ type: "turn_end" })).not.toThrow();
+    });
+
+    it("P2 journal 接线：run 期间事件落盘 journal-<taskId>.jsonl（中立格式，可重放）", async () => {
+      vi.useFakeTimers({ toFake: [] }); // 真实 timers：journal 写盘走真实 fs
+      const dataDir = mkdtempSync(join(tmpdir(), "sar-journal-test-"));
+      const prevEnv = process.env.XYZ_AGENT_DATA_DIR;
+      process.env.XYZ_AGENT_DATA_DIR = dataDir;
+      try {
+        const mockService = createMockService(
+          vi.fn().mockImplementation(
+            (_opts: Record<string, unknown>, _signal?: AbortSignal, onEvent?: (e: Record<string, unknown>) => void) => {
+              onEvent?.({ type: "tool_start", toolName: "bash", args: { cmd: "ls" } });
+              onEvent?.({ type: "turn_end" });
+              return Promise.resolve(makeMockResult());
+            },
+          ),
+        );
+        const deps: SubprocessAgentRunnerDeps = { subagentService: mockService };
+        const sar = new SubprocessAgentRunner(deps);
+
+        const workflowOnEvent = vi.fn();
+        await sar.run(makeBaseOpts(), new AbortController().signal, workflowOnEvent);
+
+        // journal 落在 <dataDir>/engines/pi/shared/journal-<taskId>.jsonl
+        const journalFile = join(dataDir, "engines", "pi", "shared");
+        const files = readdirSync(journalFile).filter((f) => f.startsWith("journal-") && f.endsWith(".jsonl"));
+        expect(files.length).toBe(1);
+        const replayed = replayJournal(join(journalFile, files[0] ?? ""));
+        expect(replayed).toEqual([
+          { type: "tool_start", toolName: "bash", args: { cmd: "ls" } },
+          { type: "turn_end" },
+        ]);
+        // workflow onEvent 照常透传（journal 包装不吞事件）
+        expect(workflowOnEvent).toHaveBeenCalledTimes(2);
+      } finally {
+        if (prevEnv === undefined) delete process.env.XYZ_AGENT_DATA_DIR;
+        else process.env.XYZ_AGENT_DATA_DIR = prevEnv;
+        rmSync(dataDir, { recursive: true, force: true });
+      }
     });
   });
 

package/src/execution/agent-registry.ts

@@ -20,6 +20,7 @@ import { parseResourceMeta } from "../shared/meta-parser.ts";
 import { lintAgentMeta } from "../orchestration/script-lint.ts";
 import type { AgentMeta } from "../shared/resource-meta.ts";
 import type { AgentConfig } from "./model-resolver.ts";
+import { hasEngine, listEngines, EngineNotFoundError } from "./engine/registry.ts";
 
 const logger = getLogger("subagents");
 
@@ -100,6 +101,14 @@ export function parseAgentWithMeta(
     );
   }
   const defaultBackgroundRaw = extractYamlField(yamlBlock, "defaultBackground");
+  // engine 字段（D9）：结构化优先（IF1），legacy fallback 与 model/tools 同判——
+  // agentMeta 未通过 IF1 时配置不丢
+  const engine = agentMeta?.engine ?? extractYamlField(yamlBlock, "engine");
+  // 解析期校验（D9：未注册 id 前置暴露，不留到运行时神秘失败）。为什么在解析期而非
+  // 路由期：配置错误的根源在 .md 文件，越早报错定位越准（错误含文件路径 + 注册清单）
+  if (engine !== undefined && !hasEngine(engine)) {
+    throw new EngineNotFoundError(engine, listEngines(), filePath);
+  }
 
   return {
     config: {
@@ -107,6 +116,7 @@ export function parseAgentWithMeta(
       systemPrompt: body,
       model: agentMeta?.model ?? modelFallback ?? undefined,
       thinkingLevel: extractYamlField(yamlBlock, "thinkingLevel") ?? undefined,
+      ...(engine !== undefined ? { engine } : {}),
       tools: agentMeta?.tools && agentMeta.tools.length > 0
         ? agentMeta.tools
         : (toolsFallback && toolsFallback.length > 0 ? toolsFallback : undefined),

package/src/execution/config.ts

@@ -20,15 +20,16 @@ import type { SubagentsGlobalConfig } from "./types.ts";
  * 但 config.json 被 .gitignore 排除且不应随 npm 包分发用户私有配置——导致
  * npm pack 后读不到文件，catch 兜底用空字段，pi install 后首次执行抛错。
  * 修复：默认值内联在代码里，不依赖任何包内文件。
+ *
+ * export 供守护测试断言 package.json startupConfig 声明与此深相等（防漂移）。
  */
-const DEFAULT_CONFIG: SubagentsGlobalConfig = {
+export const DEFAULT_CONFIG: SubagentsGlobalConfig = {
   version: 1,
   maxConcurrent: 6,
 };
 
 /** 默认 maxConcurrent（DEFAULT_CONFIG 的镜像，sanitize 用）。 */
 const DEFAULT_MAX_CONCURRENT = 6;
-
 // ============================================================
 // 路径
 // ============================================================
@@ -56,9 +57,15 @@ export function loadGlobalConfig(agentDir: string): SubagentsGlobalConfig {
   try {
     const raw = fs.readFileSync(configPath, "utf-8");
     const parsed = JSON.parse(raw) as Partial<SubagentsGlobalConfig>;
+    // P4 引擎路由（D9）：全局默认引擎 + strict 模式。非法值静默回缺省（'pi' /
+    // false）——config.json 是用户手编文件，坏值不炸启动（与 maxConcurrent 同判）
+    const defaultEngine = sanitizeDefaultEngine(parsed.defaultEngine);
+    const engineRouting = sanitizeEngineRouting(parsed.engineRouting);
     return {
       version: parsed.version ?? DEFAULT_CONFIG.version,
       maxConcurrent: sanitizeMaxConcurrent(parsed.maxConcurrent),
+      ...(defaultEngine !== undefined ? { defaultEngine } : {}),
+      ...(engineRouting !== undefined ? { engineRouting } : {}),
     };
   } catch {
     return { ...DEFAULT_CONFIG };
@@ -71,3 +78,19 @@ function sanitizeMaxConcurrent(value: unknown): number {
     ? value
     : DEFAULT_MAX_CONCURRENT;
 }
+
+/**
+ * defaultEngine 校验：非空字符串透传，其余 undefined（缺省引擎由路由层落 'pi'）。
+ * 为什么不在加载期对注册表校验 hasEngine：加载早于组合根注册（agentDir 解析在
+ * session_start），注册表此刻可能为空——校验归路由层（getEngine 抛 EngineNotFoundError）。
+ */
+function sanitizeDefaultEngine(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() !== "" ? value : undefined;
+}
+
+/** engineRouting 校验：仅认 strict 布尔，其余键忽略（向前兼容追加）。 */
+function sanitizeEngineRouting(value: unknown): { strict: boolean } | undefined {
+  if (typeof value !== "object" || value === null) return undefined;
+  const strict = (value as Record<string, unknown>).strict;
+  return typeof strict === "boolean" ? { strict } : undefined;
+}

package/src/execution/engine/__tests__/common/data-dir.test.ts

@@ -0,0 +1,53 @@
+// data-dir.test.ts —— dataDir 通道解析（XYZ_AGENT_DATA_DIR 权威通道 + piAgentDir 回退）。
+//
+// 三视角：①构建者——两级解析顺序正确；②使用者——独立 pi 用户（无 xyz env）拿到
+// piAgentDir 作根；③观察者——回退路径 warn 一次（不留静默漂移），不刷屏。
+//
+// 注意：getAgentDir 在 vitest 下 alias 到 mocks/pi-coding-agent.ts（返回
+// /home/user/.pi/agent）——本测试只断言两级解析顺序与 warn 行为，不测 pi SDK 内部。
+
+import { beforeEach, describe, expect, it } from "vitest";
+
+import { getEngineDataDir, resetDataDirWarnForTests, XYZ_DATA_DIR_ENV } from "../../common/data-dir.ts";
+
+beforeEach(() => {
+  resetDataDirWarnForTests();
+});
+
+describe("getEngineDataDir", () => {
+  it("XYZ_AGENT_DATA_DIR 存在 → 权威通道直取，不 warn", () => {
+    const warnings: string[] = [];
+    const dir = getEngineDataDir({ [XYZ_DATA_DIR_ENV]: "/data/xyz-agent" }, (m) => warnings.push(m));
+    expect(dir).toBe("/data/xyz-agent");
+    expect(warnings).toEqual([]);
+  });
+
+  it("空串/空白串视为缺失（truthy 语义与 shared getDataDir 的 || 归一对齐）", () => {
+    const warnings: string[] = [];
+    const dir = getEngineDataDir({ [XYZ_DATA_DIR_ENV]: "   " }, (m) => warnings.push(m));
+    expect(dir).not.toBe("   ");
+    expect(warnings.length).toBe(1);
+  });
+
+  it("缺 env → 回退 piAgentDir（getAgentDir()，mock 值）并 warn 一次", () => {
+    const warnings: string[] = [];
+    const warn = (m: string): void => warnings.push(m);
+    const dir1 = getEngineDataDir({}, warn);
+    expect(dir1).toBe("/home/user/.pi/agent"); // vitest mock 的 getAgentDir
+    expect(warnings.length).toBe(1);
+    expect(warnings[0]).toContain("XYZ_AGENT_DATA_DIR");
+
+    // warn once：第二次调用不再刷
+    const dir2 = getEngineDataDir({}, warn);
+    expect(dir2).toBe(dir1);
+    expect(warnings.length).toBe(1);
+  });
+
+  it("reset 后再次回退会重新 warn（测试隔离钩子可用）", () => {
+    const warnings: string[] = [];
+    getEngineDataDir({}, (m) => warnings.push(m));
+    resetDataDirWarnForTests();
+    getEngineDataDir({}, (m) => warnings.push(m));
+    expect(warnings.length).toBe(2);
+  });
+});

package/src/execution/engine/__tests__/common/errors.test.ts

@@ -0,0 +1,132 @@
+// errors.test.ts —— 引擎层错误 SSOT 的结构锁定。
+//
+// 三视角：①构建者——11 条 code 与设计 §3.3.3 全表一致；②使用者——错误消息
+// code 前缀格式可被字符串匹配分流；③观察者——每条错误必有非空恢复指引（可操作）。
+
+import { describe, expect, it } from "vitest";
+
+import {
+  DEFAULT_RECOVERY_HINTS,
+  ENGINE_ERROR_CODES,
+  EngineError,
+  engineRunFailedDetail,
+  engineTimeoutDetail,
+  isEngineErrorCode,
+  nestedSpawnRejectedError,
+  promptTooLargeError,
+  schemaEmulationFailedDetail,
+  STDOUT_TAIL_ECHO_CHARS,
+} from "../../common/errors.ts";
+
+describe("ENGINE_ERROR_CODES（§3.3.3 全表）", () => {
+  it("11 条错误码与设计文档错误规格表逐条一致", () => {
+    expect([...ENGINE_ERROR_CODES]).toEqual([
+      "engine_not_found",
+      "engine_probe_failed",
+      "engine_credential_missing",
+      "nested_spawn_rejected",
+      "schema_emulation_failed",
+      "engine_timeout",
+      "engine_capability_unsupported",
+      "engine_session_not_resumable",
+      "model_not_available",
+      "prompt_too_large",
+      "engine_run_failed",
+    ]);
+  });
+
+  it("isEngineErrorCode 收窄：表内 code 为 true，表外/非字符串为 false", () => {
+    expect(isEngineErrorCode("engine_timeout")).toBe(true);
+    expect(isEngineErrorCode("engine_not_found")).toBe(true);
+    expect(isEngineErrorCode("engine_oops")).toBe(false);
+    expect(isEngineErrorCode(42)).toBe(false);
+    expect(isEngineErrorCode(undefined)).toBe(false);
+  });
+});
+
+describe("DEFAULT_RECOVERY_HINTS（恢复指引全集）", () => {
+  it("11 条 code 每条都有非空恢复指引（可操作，非安慰性文案）", () => {
+    for (const code of ENGINE_ERROR_CODES) {
+      const hint = DEFAULT_RECOVERY_HINTS[code];
+      expect(hint, `recovery hint for ${code}`).toMatch(/\S/);
+      expect(hint.length).toBeGreaterThan(20);
+    }
+  });
+
+  it("关键恢复动作在指引中（抽查三条错误规格的载体系数）", () => {
+    expect(DEFAULT_RECOVERY_HINTS.engine_timeout).toMatch(/stdout tail/i);
+    expect(DEFAULT_RECOVERY_HINTS.prompt_too_large).toMatch(/stdin/);
+    expect(DEFAULT_RECOVERY_HINTS.nested_spawn_rejected).toMatch(/inside the current task/);
+  });
+});
+
+describe("EngineError", () => {
+  it("message 为 <code>: <detail> 前缀格式（outcome.error 分流依据）", () => {
+    const err = new EngineError("engine_timeout", "chain exhausted", "retry with pi");
+    expect(err.message).toBe("engine_timeout: chain exhausted");
+    expect(err.code).toBe("engine_timeout");
+    expect(err.recovery).toBe("retry with pi");
+    expect(err.name).toBe("EngineError");
+  });
+
+  it("toStructured 投影 code/message/recovery 三字段", () => {
+    const structured = new EngineError("model_not_available", "no such model", "pick another").toStructured();
+    expect(structured).toEqual({
+      code: "model_not_available",
+      message: "model_not_available: no such model",
+      recovery: "pick another",
+    });
+  });
+});
+
+describe("具名构造器", () => {
+  it("promptTooLargeError：detail 含实际/上限字节数，recovery 含三条恢复建议", () => {
+    const err = promptTooLargeError(200_000, 131_072);
+    expect(err.code).toBe("prompt_too_large");
+    expect(err.message).toContain("200000");
+    expect(err.message).toContain("131072");
+    expect(err.recovery).toMatch(/shorten the task/i);
+    expect(err.recovery).toMatch(/file channel/);
+    expect(err.recovery).toMatch(/stdin/);
+  });
+
+  it("nestedSpawnRejectedError：说明防护规则 + 指向 task 内自行完成", () => {
+    const err = nestedSpawnRejectedError();
+    expect(err.code).toBe("nested_spawn_rejected");
+    expect(err.message).toContain("XYZ_AGENT_SUBAGENT");
+    expect(err.recovery).toMatch(/inside the current task/);
+  });
+
+  it("engineTimeoutDetail：含 stdout 尾部 + engine: pi 重跑建议", () => {
+    const detail = engineTimeoutDetail("partial stdout output");
+    expect(detail).toContain("partial stdout output");
+    expect(detail).toMatch(/SIGTERM/);
+    expect(detail).toMatch(/SIGKILL/);
+    expect(detail).toMatch(/`engine: pi`/);
+  });
+
+  it(`engineTimeoutDetail：stdout 尾部截断到 ${STDOUT_TAIL_ECHO_CHARS} 字符`, () => {
+    const longTail = "x".repeat(STDOUT_TAIL_ECHO_CHARS + 500);
+    const detail = engineTimeoutDetail(longTail);
+    // 截断后含省略号标记，总长有界（不含前后固定文案不超过 2000 + 常量开销）
+    expect(detail).toContain("...");
+    expect(detail.length).toBeLessThan(STDOUT_TAIL_ECHO_CHARS + 600);
+  });
+
+  it("engineRunFailedDetail：含 reason / exit code / 尾部 / 恢复指引", () => {
+    const detail = engineRunFailedDetail("stdout parse failed", 3, "some output");
+    expect(detail).toContain("stdout parse failed");
+    expect(detail).toContain("exit code 3");
+    expect(detail).toContain("some output");
+    expect(detail).toMatch(/probe/);
+    // exitCode=null（被信号杀死）的形态
+    expect(engineRunFailedDetail("crash", null, "t")).toContain("killed by signal");
+  });
+
+  it("schemaEmulationFailedDetail：含错误明细 + 原始输出尾部 + 重试一次语义", () => {
+    const detail = schemaEmulationFailedDetail("Schema validation failed: /a must be number", '{"a":"x"}');
+    expect(detail).toContain("Schema validation failed");
+    expect(detail).toContain('{"a":"x"}');
+    expect(detail).toMatch(/retry once/i);
+  });
+});

package/src/execution/engine/__tests__/common/event-journal.test.ts

@@ -0,0 +1,177 @@
+// event-journal.test.ts —— JournalWriter 写入-重放往返一致 + 中立格式字段断言。
+//
+// 三视角：①构建者——行格式 v/ts/taskId/engineId/seq/event 逐字段、seq 单调；②使用者
+// ——replayJournal 重放即得事件流（read 第②级），文件不存在/坏行不 throw；③观察者
+// ——写失败 warn 留痕且 close 不抛（journal 是尽力而为的②级数据源）。
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync, existsSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { JournalWriter, replayJournal } from "../../common/event-journal.ts";
+import type { JournalFsDeps } from "../../common/event-journal.ts";
+import type { AgentEvent } from "../../../types.ts";
+
+let tmpRoot: string | undefined;
+
+function tmpPath(name: string): string {
+  tmpRoot ??= mkdtempSync(join(tmpdir(), "engine-journal-test-"));
+  const path = join(tmpRoot, name);
+  mkdirSync(dirname(path), { recursive: true });
+  return path;
+}
+
+afterEach(() => {
+  if (tmpRoot !== undefined) {
+    rmSync(tmpRoot, { recursive: true, force: true });
+    tmpRoot = undefined;
+  }
+});
+
+const EVENTS: AgentEvent[] = [
+  { type: "text_delta", delta: "hello " },
+  { type: "text_delta", delta: "world" },
+  { type: "tool_start", toolName: "bash", args: { cmd: "ls" } },
+  { type: "tool_end", toolName: "bash", isError: false },
+  { type: "turn_end" },
+];
+
+describe("JournalWriter 写入 + replayJournal 重放", () => {
+  it("写入-重放往返一致：append N 事件 → close → replay 深等事件流", async () => {
+    const path = tmpPath("roundtrip/journal-bg-1.jsonl");
+    const writer = new JournalWriter({ path, taskId: "bg-1", engineId: "zcode" });
+    for (const ev of EVENTS) writer.append(ev);
+    await writer.close();
+
+    expect(replayJournal(path)).toEqual(EVENTS);
+  });
+
+  it("中立格式字段断言：每行 {v:1, ts, taskId, engineId, seq, event}，seq 单调递增", async () => {
+    const path = tmpPath("format/journal-bg-2.jsonl");
+    const writer = new JournalWriter({ path, taskId: "bg-2", engineId: "pi" });
+    const before = Date.now();
+    for (const ev of EVENTS) writer.append(ev);
+    await writer.close();
+
+    const lines = readFileSync(path, "utf8").trim().split("\n");
+    expect(lines.length).toBe(EVENTS.length);
+    const parsed = lines.map((l) => JSON.parse(l) as Record<string, unknown>);
+    let prevSeq = -1;
+    for (const [i, row] of parsed.entries()) {
+      expect(row.v).toBe(1);
+      expect(typeof row.ts).toBe("number");
+      expect(row.ts).toBeGreaterThanOrEqual(before);
+      expect(row.taskId).toBe("bg-2");
+      expect(row.engineId).toBe("pi");
+      expect(row.seq).toBe(i);
+      expect((row.seq as number) > prevSeq).toBe(true);
+      prevSeq = row.seq as number;
+      expect(row.event).toEqual(EVENTS[i]);
+    }
+  });
+
+  it("close 幂等（二次 close 不追加不抛错）；close 后 append 丢弃", async () => {
+    const path = tmpPath("idempotent/journal-bg-3.jsonl");
+    const writer = new JournalWriter({ path, taskId: "bg-3", engineId: "pi" });
+    writer.append({ type: "turn_end" });
+    await writer.close();
+    writer.append({ type: "error", message: "late" });
+    await writer.close();
+    expect(replayJournal(path)).toEqual([{ type: "turn_end" }]);
+  });
+
+  it("无事件任务不产生空 journal 文件（惰性创建）", async () => {
+    const path = tmpPath("empty/journal-bg-4.jsonl");
+    const writer = new JournalWriter({ path, taskId: "bg-4", engineId: "pi" });
+    await writer.close();
+    expect(existsSync(path)).toBe(false);
+    expect(replayJournal(path)).toEqual([]);
+  });
+});
+
+describe("JournalWriter 写失败（尽力而为语义）", () => {
+  function failingFs(): { fs: JournalFsDeps; warnings: string[] } {
+    const warnings: string[] = [];
+    const fs: JournalFsDeps = {
+      mkdir: async () => undefined,
+      appendFile: async () => {
+        throw new Error("disk full");
+      },
+      open: async () => {
+        throw new Error("unreachable in failed path");
+      },
+    };
+    return { fs, warnings };
+  }
+
+  it("appendFile 失败 → warn 留痕 + failed，close 不抛，后续 append 丢弃", async () => {
+    const path = tmpPath("failing/journal-bg-5.jsonl");
+    const { fs } = failingFs();
+    const warnings: string[] = [];
+    const writer = new JournalWriter(
+      { path, taskId: "bg-5", engineId: "zcode" },
+      fs,
+      (msg) => warnings.push(msg),
+    );
+    writer.append({ type: "turn_end" });
+    await writer.flush();
+    expect(writer.isFailed).toBe(true);
+    expect(warnings.length).toBe(1);
+    expect(warnings[0]).toContain("bg-5");
+    expect(warnings[0]).toContain("disk full");
+
+    writer.append({ type: "error", message: "dropped" });
+    await writer.close(); // 不抛
+    expect(existsSync(path)).toBe(false);
+  });
+});
+
+describe("replayJournal 容错", () => {
+  it("文件不存在 → []（②级不可达不算错误，降级链语义）", () => {
+    expect(replayJournal(tmpPath("missing/journal-none.jsonl"))).toEqual([]);
+  });
+
+  it("损坏行跳过（追加写末行可能截断），好行保留", () => {
+    const path = tmpPath("corrupt/journal-bg-6.jsonl");
+    const good = JSON.stringify({
+      v: 1, ts: 1, taskId: "bg-6", engineId: "pi", seq: 0, event: { type: "turn_end" },
+    });
+    writeFileSync(path, `${good}\n{"v":1,"truncated...\n`, "utf8");
+    expect(replayJournal(path)).toEqual([{ type: "turn_end" }]);
+  });
+
+  it("行序乱 → 按 seq 稳定排序返回（重放顺序权威是 seq）", () => {
+    const path = tmpPath("unordered/journal-bg-7.jsonl");
+    const line = (seq: number, delta: string): string =>
+      JSON.stringify({ v: 1, ts: seq, taskId: "bg-7", engineId: "pi", seq, event: { type: "text_delta", delta } });
+    writeFileSync(path, `${line(2, "c")}\n${line(0, "a")}\n${line(1, "b")}\n`, "utf8");
+    expect(replayJournal(path)).toEqual([
+      { type: "text_delta", delta: "a" },
+      { type: "text_delta", delta: "b" },
+      { type: "text_delta", delta: "c" },
+    ]);
+  });
+
+  it("空文件 → []", () => {
+    const path = tmpPath("blank/journal-bg-8.jsonl");
+    writeFileSync(path, "\n\n", "utf8");
+    expect(replayJournal(path)).toEqual([]);
+  });
+
+  it("结构不符的行（缺 event / v≠1）跳过", () => {
+    const path = tmpPath("shape/journal-bg-9.jsonl");
+    writeFileSync(
+      path,
+      [
+        JSON.stringify({ v: 1, ts: 1, taskId: "t", engineId: "pi", seq: 0, event: { type: "compaction" } }),
+        JSON.stringify({ v: 1, ts: 2, taskId: "t", engineId: "pi", seq: 1 }), // 无 event
+        JSON.stringify({ v: 2, ts: 3, taskId: "t", engineId: "pi", seq: 2, event: { type: "turn_end" } }), // v≠1
+        JSON.stringify({ v: 1, ts: 4, taskId: "t", engineId: "pi", seq: 3, event: "not-an-object" }),
+      ].join("\n") + "\n",
+      "utf8",
+    );
+    expect(replayJournal(path)).toEqual([{ type: "compaction" }]);
+  });
+});