@zhushanwen/subagent-core 0.2.0

package/src/execution/__tests__/output-collector.test.ts

@@ -0,0 +1,358 @@
+// src/__tests__/output-collector.test.ts
+//
+// 锁定 extractParsedOutput 纯函数契约——它被 collectResult 直接消费，决定
+// AgentResult.parsedOutput 字段。toUsageTotal / collectResponseText 已删除
+// （usage 收口进 getTotalUsage，text 收口进 getFullText，均在 execution-record.test 测）。
+import { describe, expect, it } from "vitest";
+
+import { isStaleContextErrorMsg, DETERMINISTIC_SCHEMA_FAILURE_PREFIX, isDeterministicSchemaFailureMsg, STALE_CONTEXT_PATTERNS } from "../../orchestration/execute-agent-call.ts";
+import { collectResult, describeMissingParsedOutput, extractParsedOutput, neutralizeStalePatterns } from "../output-collector.ts";
+import type { ExecutionRecord, ToolCall } from "../types.ts";
+
+// ============================================================
+// extractParsedOutput
+// ============================================================
+
+describe("extractParsedOutput", () => {
+  it("returns undefined for empty toolCalls", () => {
+    expect(extractParsedOutput([])).toBeUndefined();
+  });
+
+  it("returns undefined when no structured-output call exists", () => {
+    const calls: ToolCall[] = [
+      { toolName: "bash", result: { details: "x" } },
+      { toolName: "read", result: { details: "y" } },
+    ];
+    expect(extractParsedOutput(calls)).toBeUndefined();
+  });
+
+  it("returns undefined when structured-output has no result.details", () => {
+    const calls: ToolCall[] = [
+      { toolName: "structured-output", result: { content: [] } },
+      { toolName: "structured-output", result: {} },
+      { toolName: "structured-output" },
+    ];
+    expect(extractParsedOutput(calls)).toBeUndefined();
+  });
+
+  it("returns details when exactly one structured-output call has details", () => {
+    const calls: ToolCall[] = [
+      { toolName: "bash" },
+      { toolName: "structured-output", result: { details: { answer: 42 } } },
+    ];
+    expect(extractParsedOutput(calls)).toEqual({ answer: 42 });
+  });
+
+  it("returns the LAST structured-output details (reverse iteration)", () => {
+    const calls: ToolCall[] = [
+      { toolName: "structured-output", result: { details: "first" } },
+      { toolName: "bash" },
+      { toolName: "structured-output", result: { details: "second" } },
+    ];
+    expect(extractParsedOutput(calls)).toBe("second");
+  });
+
+  it("ignores isError structured-output calls without details, picks one with details", () => {
+    const calls: ToolCall[] = [
+      { toolName: "structured-output", isError: true, result: { content: [{ type: "text", text: "bad" }] } },
+      { toolName: "structured-output", result: { details: { ok: true } } },
+    ];
+    expect(extractParsedOutput(calls)).toEqual({ ok: true });
+  });
+
+  // [F-1 失败吞没修复] 失败调用（pi 失败路径 details 默认 {}）的 details 不是
+  // schema 校验产出——journal 实锤 tool_end isError=true details={} 曾被当
+  // parsedOutput，gate 终止/模型自弃的 run 以 parsedOutput={} 静默 completed。
+  it("skips failed structured-output call with details:{} (isError=true) — no parsedOutput", () => {
+    const calls: ToolCall[] = [
+      { toolName: "bash", result: { content: [] } },
+      { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text: "Schema validation failed: /target is required" }] } },
+    ];
+    expect(extractParsedOutput(calls)).toBeUndefined();
+  });
+
+  it("skips failed call with details, still picks later valid call (reverse order)", () => {
+    const calls: ToolCall[] = [
+      { toolName: "structured-output", isError: true, result: { details: {} } },
+      { toolName: "structured-output", result: { details: { fixed: true } } },
+    ];
+    expect(extractParsedOutput(calls)).toEqual({ fixed: true });
+  });
+
+  it("isError on non-structured-output calls does not affect extraction", () => {
+    const calls: ToolCall[] = [
+      { toolName: "bash", isError: true, result: { details: "ignored" } },
+      { toolName: "structured-output", result: { details: { answer: 1 } } },
+    ];
+    expect(extractParsedOutput(calls)).toEqual({ answer: 1 });
+  });
+});
+
+// ============================================================
+// describeMissingParsedOutput（F-1 三态归因）
+// ============================================================
+
+describe("describeMissingParsedOutput", () => {
+  it("returns undefined when a valid parsedOutput exists", () => {
+    const calls: ToolCall[] = [
+      { toolName: "structured-output", isError: true, result: { details: {} } },
+      { toolName: "structured-output", result: { details: { ok: 1 } } },
+    ];
+    expect(describeMissingParsedOutput(calls)).toBeUndefined();
+  });
+
+  it("state 1: validation failure — isError calls present, error carries last summary", () => {
+    const calls: ToolCall[] = [
+      { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text: "Schema validation failed: /target is required" }] } },
+    ];
+    const msg = describeMissingParsedOutput(calls);
+    expect(msg).toContain("failed");
+    expect(msg).toContain("1 structured-output call(s) failed");
+    expect(msg).toContain("Schema validation failed: /target is required");
+  });
+
+  it("state 2: structured-output never called — error hints to check extension install (C1 blind spot)", () => {
+    const calls: ToolCall[] = [
+      { toolName: "bash", result: { content: [] } },
+      { toolName: "read", result: { content: [] } },
+    ];
+    const msg = describeMissingParsedOutput(calls);
+    expect(msg).toContain("structured-output tool was never called");
+    expect(msg).toContain("structured-output extension is installed");
+  });
+
+  it("state 3: SO called successfully but no details", () => {
+    const calls: ToolCall[] = [
+      { toolName: "structured-output", result: { content: [] } },
+    ];
+    const msg = describeMissingParsedOutput(calls);
+    expect(msg).toContain("none of the successful calls carried result details");
+  });
+
+  it("empty toolCalls → state 2 (never called)", () => {
+    expect(describeMissingParsedOutput([])).toContain("never called");
+  });
+
+  it("summary truncates long error text (300 chars cap)", () => {
+    const longText = "x".repeat(500);
+    const calls: ToolCall[] = [
+      { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text: longText }] } },
+    ];
+    const msg = describeMissingParsedOutput(calls);
+    expect(msg).toContain("...");
+    expect(msg!.length).toBeLessThan(longText.length);
+  });
+
+  // 文案约束：不得命中 execute-agent-call 的 STALE_CONTEXT_PATTERNS（"aborted" 等），
+  // 否则会被误诊为 stale-context 跳过重试。
+  it("messages avoid STALE_CONTEXT_PATTERNS substrings (no false stale-context triage)", () => {
+    const samples = [
+      describeMissingParsedOutput([])!,
+      describeMissingParsedOutput([{ toolName: "structured-output", isError: true, result: { details: {} } }])!,
+      describeMissingParsedOutput([{ toolName: "structured-output", result: { content: [] } }])!,
+    ];
+    for (const msg of samples) {
+      const lower = msg.toLowerCase();
+      expect(lower).not.toContain("aborted");
+      expect(lower).not.toContain("ctx is stale");
+      expect(lower).not.toContain("context canceled");
+    }
+  });
+
+  // ── [F-R1] 态2（isError 分支）错误摘要拼接段中和 ──
+  //
+  // 动态错误文本（模型/provider 原始错误）可能携带 "aborted"/"ctx is stale" 等
+  // STALE_CONTEXT_PATTERNS 词；不中和则归因 error 经 collectResult → result.error
+  // 流到 execute-agent-call 的 isStaleContextErrorMsg 分诊，被误诊为 stale-context
+  // 跳过重试。固定前缀静态无命中（上一用例锁定），中和只针对动态段。
+  describe("F-R1: 态2 错误摘要 STALE_CONTEXT_PATTERNS 中和", () => {
+    function failedSoCallsWith(text: string): ToolCall[] {
+      return [
+        { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text }] } },
+      ];
+    }
+
+    it("失败 content 含 'aborted'/'ctx is stale' → 摘要被 [redacted]，归因 error 不触发 isStaleContextErrorMsg", () => {
+      const msg = describeMissingParsedOutput(
+        failedSoCallsWith("Request aborted: context canceled — ctx is stale after session replacement"),
+      )!;
+      expect(msg).toContain("[redacted]");
+      const lower = msg.toLowerCase();
+      expect(lower).not.toContain("aborted");
+      expect(lower).not.toContain("ctx is stale");
+      expect(lower).not.toContain("context canceled");
+      // 消费点语义锁定：归因 error 进入 stale-context 分诊必须为 false（可重试）
+      expect(isStaleContextErrorMsg(msg)).toBe(false);
+    });
+
+    it("大小写变体（'ABORTED'）同样被中和（分诊是大小写不敏感子串匹配）", () => {
+      const msg = describeMissingParsedOutput(failedSoCallsWith("ABORTED by provider"))!;
+      expect(msg).toContain("[redacted]");
+      expect(isStaleContextErrorMsg(msg)).toBe(false);
+    });
+
+    it("无动态内容时整条归因也不命中（防御回归锁定）", () => {
+      const msg = describeMissingParsedOutput([
+        { toolName: "structured-output", isError: true, result: { details: {} } },
+      ])!;
+      expect(isStaleContextErrorMsg(msg)).toBe(false);
+    });
+
+    it("neutralizeStalePatterns：多 pattern 同时命中 + 无命中原样透传", () => {
+      expect(neutralizeStalePatterns("aborted CTX IS STALE / context canceled")).toBe(
+        "[redacted] [redacted] / [redacted]",
+      );
+      expect(neutralizeStalePatterns("provider socket hang up")).toBe("provider socket hang up");
+    });
+  });
+
+  // ── [F-R4] 态2 文案按最后错误内容分类，不再硬编码 "(schema validation)" ──
+  describe("F-R4: 态2 失败原因分类", () => {
+    it("最后错误含 'validation failed'（大小写不敏感）→ (schema validation)", () => {
+      const calls: ToolCall[] = [
+        { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text: "Schema validation failed: /target is required" }] } },
+      ];
+      const msg = describeMissingParsedOutput(calls)!;
+      expect(msg).toContain("(schema validation)");
+      expect(msg).not.toContain("(execution failure)");
+    });
+
+    it("最后错误为非校验失败（如 provider 错误）→ (execution failure)", () => {
+      const calls: ToolCall[] = [
+        { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text: "provider socket hang up" }] } },
+      ];
+      const msg = describeMissingParsedOutput(calls)!;
+      expect(msg).toContain("(execution failure)");
+      expect(msg).not.toContain("(schema validation)");
+    });
+  });
+});
+
+// ============================================================
+// MF-1: 三态可重试性矩阵（确定性失败标记）
+// ============================================================
+
+describe("MF-1: 三态可重试性矩阵（确定性失败标记）", () => {
+  // 矩阵（SSOT 注释在 execute-agent-call DETERMINISTIC_SCHEMA_FAILURE_PREFIX 与
+  // describeMissingParsedOutput JSDoc，本 describe 是执行面锁定）：
+  //   态① 从未调用 SO            → 带标记 → 不可重试（环境确定性，C1 安装盲区）
+  //   态② SO isError（gate 终止/不可满足 schema）→ 带标记 → 不可重试（同 schema 重试必同结果）
+  //   态③ 调用过但无 details       → 无标记 → 可重试（可能瞬态，保留既有重试语义）
+
+  it("态① 从未调用 SO → error 以确定性标记开头（不可重试）", () => {
+    const msg = describeMissingParsedOutput([])!;
+    expect(msg.startsWith(DETERMINISTIC_SCHEMA_FAILURE_PREFIX)).toBe(true);
+    expect(isDeterministicSchemaFailureMsg(msg)).toBe(true);
+  });
+
+  it("态② isError/schema validation 子类 → error 以确定性标记开头（不可重试）", () => {
+    const msg = describeMissingParsedOutput([
+      { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text: "Schema validation failed: /target is required" }] } },
+    ])!;
+    expect(msg.startsWith(DETERMINISTIC_SCHEMA_FAILURE_PREFIX)).toBe(true);
+    expect(isDeterministicSchemaFailureMsg(msg)).toBe(true);
+  });
+
+  it("态② execution failure 子类（provider 瞬态）同样带标记（isError 态整体不重试）", () => {
+    const msg = describeMissingParsedOutput([
+      { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text: "provider socket hang up" }] } },
+    ])!;
+    expect(isDeterministicSchemaFailureMsg(msg)).toBe(true);
+  });
+
+  it("态③ 调用过但无 details → 不带标记（可重试语义保留）", () => {
+    const msg = describeMissingParsedOutput([
+      { toolName: "structured-output", result: { content: [] } },
+    ])!;
+    expect(isDeterministicSchemaFailureMsg(msg)).toBe(false);
+  });
+
+  it("有有效 parsedOutput → 无归因无标记（不适用矩阵）", () => {
+    expect(
+      describeMissingParsedOutput([{ toolName: "structured-output", result: { details: { ok: 1 } } }]),
+    ).toBeUndefined();
+  });
+
+  // 验收④：标记词不命中 STALE_CONTEXT_PATTERNS——若命中，isStaleContextErrorMsg
+  // 分诊（判定在前）会抢先归因 stale-context，虽然同样不重试，但归因语义被污染
+  // （TUI/日志把 schema 失败误报为 stale）。
+  it("标记词与全部 STALE_CONTEXT_PATTERNS 零交集，isStaleContextErrorMsg 不抢先", () => {
+    const lower = DETERMINISTIC_SCHEMA_FAILURE_PREFIX.toLowerCase();
+    for (const pattern of STALE_CONTEXT_PATTERNS) {
+      expect(lower.includes(pattern)).toBe(false);
+    }
+    expect(isStaleContextErrorMsg(DETERMINISTIC_SCHEMA_FAILURE_PREFIX)).toBe(false);
+  });
+});
+
+// ============================================================
+// collectResult — F-1 集成行为（schemaExpected → 失败标注）
+// ============================================================
+
+describe("collectResult — F-1 schemaExpected 失败标注", () => {
+  /** 最小 ExecutionRecord stub（collectResult 只读 turns/toolCalls 派生面）。 */
+  function makeRecordWithCalls(calls: ToolCall[]): ExecutionRecord {
+    return {
+      id: "rec-1",
+      turns: [{ toolCalls: calls, text: "done", turnCount: 1, closed: true }],
+      turnCount: 1,
+    } as unknown as ExecutionRecord;
+  }
+
+  const baseArgs = {
+    startTime: Date.now(),
+    sessionId: "s-1",
+    sessionFile: undefined,
+  };
+
+  it("schemaExpected + failed SO call (details:{}) + success=true → success=false + error attributed", () => {
+    const record = makeRecordWithCalls([
+      { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text: "validation boom" }] } },
+    ]);
+    const result = collectResult(record, { ...baseArgs, success: true, error: undefined, schemaExpected: true });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("validation boom");
+    expect(result.parsedOutput).toBeUndefined();
+  });
+
+  it("schemaExpected + never called SO + success=true → error hints extension check", () => {
+    const record = makeRecordWithCalls([{ toolName: "bash", result: { content: [] } }]);
+    const result = collectResult(record, { ...baseArgs, success: true, error: undefined, schemaExpected: true });
+    expect(result.success).toBe(false);
+    expect(result.error).toContain("structured-output extension is installed");
+  });
+
+  it("schemaExpected + valid details → success preserved (S3 e2e semantics no regression)", () => {
+    const record = makeRecordWithCalls([
+      { toolName: "structured-output", result: { details: { answer: 42 } } },
+    ]);
+    const result = collectResult(record, { ...baseArgs, success: true, error: undefined, schemaExpected: true });
+    expect(result.success).toBe(true);
+    expect(result.error).toBeUndefined();
+    expect(result.parsedOutput).toEqual({ answer: 42 });
+  });
+
+  it("no schemaExpected (plain mode) + no SO call → success unchanged", () => {
+    const record = makeRecordWithCalls([{ toolName: "bash", result: { content: [] } }]);
+    const result = collectResult(record, { ...baseArgs, success: true, error: undefined });
+    expect(result.success).toBe(true);
+    expect(result.parsedOutput).toBeUndefined();
+  });
+
+  it("success=false path: existing error not overwritten by F-1 attribution", () => {
+    const record = makeRecordWithCalls([]);
+    const result = collectResult(record, { ...baseArgs, success: false, error: "provider boom", schemaExpected: true });
+    expect(result.success).toBe(false);
+    expect(result.error).toBe("provider boom");
+  });
+
+  it("[MF-1] F-1 标注的 error 携带确定性标记（流到 executeAgentCall 即不可重试）", () => {
+    const record = makeRecordWithCalls([
+      { toolName: "structured-output", isError: true, result: { details: {}, content: [{ type: "text", text: "Schema validation failed: /target is required" }] } },
+    ]);
+    const result = collectResult(record, { ...baseArgs, success: true, error: undefined, schemaExpected: true });
+    expect(result.success).toBe(false);
+    expect(result.error).toBeDefined();
+    expect(isDeterministicSchemaFailureMsg(result.error)).toBe(true);
+  });
+});

package/src/execution/__tests__/path-encoding.test.ts

@@ -0,0 +1,104 @@
+// src/__tests__/path-encoding.test.ts
+//
+// 锁定 encodeCwd 契约：session-runner 与 session-file-gc 共用此编码，
+// 漂移会导致同一 cwd 落到两个不同目录（见 path-encoding.ts 顶部注释）。
+import * as path from "node:path";
+
+import { describe, expect, it } from "vitest";
+
+import { encodeCwd, getSubagentRecordsDir, getSubagentSessionDir } from "../path-encoding.ts";
+
+describe("encodeCwd", () => {
+  it("encodes a normal unix absolute path", () => {
+    expect(encodeCwd("/Users/x/proj")).toBe("--Users-x-proj--");
+  });
+
+  it("strips a single leading backslash", () => {
+    expect(encodeCwd("\\foo")).toBe("--foo--");
+  });
+
+  it("encodes Windows drive letter (colon + backslash)", () => {
+    // C:\proj → 去掉无前导分隔符 → C:\proj → : 和 \ 都替换为 - → C--proj
+    expect(encodeCwd("C:\\proj")).toBe("--C--proj--");
+  });
+
+  it("encodes empty string to bare delimiter pair", () => {
+    expect(encodeCwd("")).toBe("----");
+  });
+
+  it("encodes relative path with no leading separator", () => {
+    expect(encodeCwd("relative/path")).toBe("--relative-path--");
+  });
+
+  it("collapses consecutive separators (forward slash)", () => {
+    expect(encodeCwd("/a//b")).toBe("--a--b--");
+  });
+
+  it("collapses consecutive separators (backslash)", () => {
+    expect(encodeCwd("a\\b\\c")).toBe("--a-b-c--");
+  });
+
+  it("encodes mixed separators and colon", () => {
+    // /x:y\\z → 去前导 / → x:y\z → : \ → - - → x-y-z
+    expect(encodeCwd("/x:y\\z")).toBe("--x-y-z--");
+  });
+});
+
+describe("getSubagentSessionDir", () => {
+  it("returns agentDir/subagents/<encodedCwd>/sessions", () => {
+    // [MF#1] 既有布局：subagents/<enc>/sessions/（不改，避免升级用户既有数据 orphan）
+    const result = getSubagentSessionDir("/home/user/.pi/agent", "/home/user/project");
+    expect(result).toBe(
+      path.join("/home/user/.pi/agent", "subagents", "--home-user-project--", "sessions")
+    );
+  });
+
+  it("uses mainCwd encoding (not effectiveCwd)", () => {
+    // D-004: 用主 cwd 编码，保证同一主 cwd 下所有 subagent 存同一目录
+    const mainCwd = "/Users/zhushanwen/Code/my-project";
+    const result = getSubagentSessionDir("~/.pi/agent", mainCwd);
+    const encoded = encodeCwd(mainCwd);
+    expect(result).toBe(path.join("~/.pi/agent", "subagents", encoded, "sessions"));
+  });
+
+  it("produces consistent path for same inputs", () => {
+    const a = getSubagentSessionDir("/agent", "/cwd");
+    const b = getSubagentSessionDir("/agent", "/cwd");
+    expect(a).toBe(b);
+  });
+
+  it("produces different path for different mainCwd", () => {
+    const a = getSubagentSessionDir("/agent", "/cwd1");
+    const b = getSubagentSessionDir("/agent", "/cwd2");
+    expect(a).not.toBe(b);
+  });
+});
+
+describe("getSubagentRecordsDir", () => {
+  it("returns agentDir/subagents/<encodedCwd>/records", () => {
+    const result = getSubagentRecordsDir("/home/user/.pi/agent", "/Users/x/proj");
+    expect(result).toBe(
+      path.join("/home/user/.pi/agent", "subagents", "--Users-x-proj--", "records")
+    );
+  });
+
+  it("shares the same <enc> segment with getSubagentSessionDir for same cwd", () => {
+    // F1：records 与 sessions 在同一 <enc> 段下，仅尾段不同（records vs sessions）。
+    // worktree 场景三者恒等的前提就靠这个共享 enc。
+    const agentDir = "/home/user/.pi/agent";
+    const cwd = "/Users/x/proj";
+    const sessions = getSubagentSessionDir(agentDir, cwd);
+    const records = getSubagentRecordsDir(agentDir, cwd);
+    // 共享 enc：去掉尾段后剩同一路径前缀
+    expect(path.dirname(sessions)).toBe(path.dirname(records));
+    // 尾段不同
+    expect(path.basename(sessions)).toBe("sessions");
+    expect(path.basename(records)).toBe("records");
+  });
+
+  it("produces different path for different mainCwd", () => {
+    const a = getSubagentRecordsDir("/agent", "/cwd1");
+    const b = getSubagentRecordsDir("/agent", "/cwd2");
+    expect(a).not.toBe(b);
+  });
+});

package/src/execution/__tests__/pi-invocation.test.ts

@@ -0,0 +1,134 @@
+// src/__tests__/pi-invocation.test.ts
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+import { afterEach, describe, expect, it } from "vitest";
+
+import { getPiInvocation } from "../pi-invocation.ts";
+import { RELAY_ENV_NODE, RELAY_ENV_SCRIPT, RELAY_ENV_SOCKET } from "../relay-env.ts";
+
+describe("getPiInvocation", () => {
+  const originalArgv = process.argv;
+  const originalExecPath = process.execPath;
+  let tmpScript: string;
+
+  afterEach(() => {
+    Object.defineProperty(process, "argv", { value: originalArgv, configurable: true });
+    Object.defineProperty(process, "execPath", { value: originalExecPath, configurable: true });
+    if (tmpScript && fs.existsSync(tmpScript)) fs.unlinkSync(tmpScript);
+  });
+
+  it("真实脚本路径存在 → node <script> <userArgs>", () => {
+    // 创建真实临时脚本文件（避免 ESM spy 限制）
+    tmpScript = path.join(os.tmpdir(), `pi-inv-test-${Date.now()}.mjs`);
+    fs.writeFileSync(tmpScript, "// test");
+    Object.defineProperty(process, "argv", { value: ["node", tmpScript], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/bin/node", configurable: true });
+
+    const result = getPiInvocation(["--mode", "json", "Task: x"]);
+    expect(result.command).toBe("/usr/bin/node");
+    expect(result.args).toEqual([tmpScript, "--mode", "json", "Task: x"]);
+  });
+
+  it("bun 虚拟脚本（/$bunfs/root/）→ 退化到 pi-in-PATH", () => {
+    tmpScript = "";
+    const virtualScript = "/$bunfs/root/pi";
+    Object.defineProperty(process, "argv", { value: ["bun", virtualScript], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/bin/bun", configurable: true });
+
+    const result = getPiInvocation(["--mode", "json"]);
+    expect(result.command).toBe("pi");
+    expect(result.args).toEqual(["--mode", "json"]);
+  });
+
+  it("非通用 runtime（pi standalone binary）→ 直接 execPath", () => {
+    tmpScript = "";
+    Object.defineProperty(process, "argv", { value: ["/usr/bin/pi", "/nonexistent"], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/local/bin/pi-binary", configurable: true });
+
+    const result = getPiInvocation(["--mode", "json"]);
+    expect(result.command).toBe("/usr/local/bin/pi-binary");
+    expect(result.args).toEqual(["--mode", "json"]);
+  });
+
+  it("node 通用 runtime + 脚本不存在 → pi-in-PATH", () => {
+    tmpScript = "";
+    Object.defineProperty(process, "argv", { value: ["node", "/nonexistent"], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/bin/node", configurable: true });
+
+    const result = getPiInvocation(["--mode", "json"]);
+    expect(result.command).toBe("pi");
+    expect(result.args).toEqual(["--mode", "json"]);
+  });
+
+  it("空 userArgs 合法（仅 command + 空 args）", () => {
+    tmpScript = "";
+    Object.defineProperty(process, "argv", { value: ["node"], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/bin/node", configurable: true });
+
+    const result = getPiInvocation([]);
+    expect(result.command).toBe("pi");
+    expect(result.args).toEqual([]);
+  });
+});
+
+describe("getPiInvocation relay 分支（E 方案 §5.1）", () => {
+  const originalArgv = process.argv;
+  const originalExecPath = process.execPath;
+  const RELAY_ENVS = [RELAY_ENV_SOCKET, RELAY_ENV_NODE, RELAY_ENV_SCRIPT] as const;
+  /** 三 env 齐备的基准值（改 argv/execPath 隔离直连分支，只测 relay 判定本身）。 */
+  const RELAY_FULL: Record<string, string> = {
+    [RELAY_ENV_SOCKET]: "/tmp/relay-test.sock",
+    [RELAY_ENV_NODE]: "/usr/bin/relay-node",
+    [RELAY_ENV_SCRIPT]: "/opt/relay/relay.mjs",
+  };
+
+  afterEach(() => {
+    Object.defineProperty(process, "argv", { value: originalArgv, configurable: true });
+    Object.defineProperty(process, "execPath", { value: originalExecPath, configurable: true });
+    for (const key of RELAY_ENVS) delete process.env[key];
+  });
+
+  /** 形态 1：三 env 齐备 + 默认 opts → relay invocation（command=NODE、args[0]=SCRIPT）。 */
+  it("三 env 齐备（无 opts）→ 代理形态 <NODE> <SCRIPT> <userArgs>", () => {
+    Object.assign(process.env, RELAY_FULL);
+    const result = getPiInvocation(["--mode", "rpc"]);
+    expect(result.command).toBe(RELAY_FULL[RELAY_ENV_NODE]);
+    expect(result.args).toEqual([RELAY_FULL[RELAY_ENV_SCRIPT], "--mode", "rpc"]);
+  });
+
+  /** 形态 1 变体：opts.relay === true 显式开启，行为与缺省一致。 */
+  it("三 env 齐备 + opts.relay=true → 同缺省（显式开启非必填）", () => {
+    Object.assign(process.env, RELAY_FULL);
+    const result = getPiInvocation(["--mode", "rpc"], { relay: true });
+    expect(result.command).toBe(RELAY_FULL[RELAY_ENV_NODE]);
+    expect(result.args[0]).toBe(RELAY_FULL[RELAY_ENV_SCRIPT]);
+  });
+
+  /** 形态 2：三缺一逐个枚举 → 回落现状直连（全有或全无，E-TUI 零回归）。 */
+  it("三缺一（逐个枚举）→ 现状直连分支", () => {
+    // 直连分支落到「node + 不存在脚本 → pi-in-PATH」可稳定断言（不依赖测试机 execPath 形态）
+    Object.defineProperty(process, "argv", { value: ["node", "/nonexistent"], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/bin/node", configurable: true });
+    for (const missing of RELAY_ENVS) {
+      const partial = { ...RELAY_FULL };
+      delete partial[missing];
+      for (const key of RELAY_ENVS) delete process.env[key];
+      Object.assign(process.env, partial);
+      const result = getPiInvocation(["--mode", "rpc"]);
+      expect(result.command).toBe("pi"); // 分支 3：通用 runtime + 脚本不存在 → PATH
+      expect(result.args).toEqual(["--mode", "rpc"]);
+    }
+  });
+
+  /** 形态 3：probe 排除——显式 relay:false 时即便三 env 齐备也直连。 */
+  it("relay:false 强制直连（probe 语义：探 pi 本体，不探 runtime 健康）", () => {
+    Object.assign(process.env, RELAY_FULL);
+    Object.defineProperty(process, "argv", { value: ["node", "/nonexistent"], configurable: true });
+    Object.defineProperty(process, "execPath", { value: "/usr/bin/node", configurable: true });
+    const result = getPiInvocation(["--version"], { relay: false });
+    expect(result.command).toBe("pi");
+    expect(result.args).toEqual(["--version"]);
+  });
+});