@zhushanwen/subagent-core 0.2.0

package/src/__tests__/derive-closed-display-parity.test.ts

@@ -0,0 +1,93 @@
+// derive-closed-display-parity — 成败推导单一权威守卫（core 侧）
+//
+// 同构成败推导收敛到 execution-record.ts 的 deriveOutcome/projectOutcome（单一权威）。
+// 本文件锚定：① 权威函数行为；② core 侧消费方（execution/notifier.ts buildLlmContent）
+// 源码不得写回手写同构 switch。
+// [u1-move 拆分] 壳侧消费方（interface/bg-notify-render.ts renderRecordLines）的守卫段
+// 随壳件留守 pi extension 包：src/__tests__/derive-closed-display-parity-interface.test.ts。
+
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+import { deriveOutcome, projectOutcome } from "../execution/execution-record.ts";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** core 侧消费方源码（同构成败推导已收敛删除）。 */
+const CONSUMER_SOURCES = {
+  notifier: join(here, "..", "execution", "notifier.ts"),
+} as const;
+
+/**
+ * 手写同构 switch 的源码特征 token：出现即说明有人把收敛删除的成败推导又写了回去。
+ * （"gc" 是 ClosedReason 专属字面量——outcome 三态不含它，消费方合法代码不会出现
+ * `?? "gc"` / `=== "gc"`；cancelled 比较不列入——outcome === "cancelled" 是合法消费。）
+ */
+const LEGACY_DERIVATION_TOKENS = [/\?\?\s*["']gc["']/, /===\s*["']gc["']/] as const;
+
+describe("deriveOutcome — 单一权威终态派生（行为锚定）", () => {
+  it("completed：closed + 无 error（gc / user-close 正常完成）", () => {
+    expect(deriveOutcome("gc", undefined)).toBe("completed");
+    expect(deriveOutcome("user-close", undefined)).toBe("completed");
+  });
+
+  it("failed：closed + error 非空（gc 失败）", () => {
+    expect(deriveOutcome("gc", "spawn EPIPE")).toBe("failed");
+  });
+
+  it("[D6 显式取舍] parent-shutdown/parent-fork/parent-new 合成关闭 → failed（勿改 cancelled）", () => {
+    // disposeAllRecords 合成 result 恒写 error:"closed due to ${reason}"——
+    // 「父进程关闭时子 agent 未完成即失败」为选定行为而非疏漏。
+    expect(deriveOutcome("parent-shutdown", "closed due to parent-shutdown")).toBe("failed");
+    expect(deriveOutcome("parent-fork", "closed due to parent-fork")).toBe("failed");
+    expect(deriveOutcome("parent-new", "closed due to parent-new")).toBe("failed");
+  });
+
+  it("cancelled：取消优先于 error（abort 合成 result 可能带 error）", () => {
+    expect(deriveOutcome("cancelled", undefined)).toBe("cancelled");
+    expect(deriveOutcome("cancelled", "aborted by user")).toBe("cancelled");
+  });
+
+  it("空串 error 不构成 failed（与旧同构 `record.error &&` truthy 判定逐字对齐）", () => {
+    expect(deriveOutcome("gc", "")).toBe("completed");
+  });
+});
+
+describe("projectOutcome — 投影唯一出口（行为锚定）", () => {
+  it("running → undefined；closed 一等 outcome 直读；存量 record 兜底派生", () => {
+    expect(projectOutcome({ status: "running" })).toBeUndefined();
+    expect(projectOutcome({ status: "closed", outcome: "failed" })).toBe("failed");
+    expect(projectOutcome({ status: "closed", closedReason: "gc", error: "boom" })).toBe("failed");
+    expect(projectOutcome({ status: "closed" })).toBe("completed");
+  });
+});
+
+describe("同构 switch 残留守卫（收敛删除后不得写回）— core 消费方", () => {
+  it("消费方源码可读（fail-loud 前置）", () => {
+    for (const [key, p] of Object.entries(CONSUMER_SOURCES)) {
+      expect(() => readFileSync(p, "utf-8"), `源文件不可读：${key} ${p}`).not.toThrow();
+    }
+  });
+
+  it("notifier buildLlmContent 无 closedReason 成败推导特征", () => {
+    for (const [key, p] of Object.entries(CONSUMER_SOURCES)) {
+      const src = readFileSync(p, "utf-8");
+      for (const token of LEGACY_DERIVATION_TOKENS) {
+        expect(
+          token.test(src),
+          `[${key}] 检出旧同构推导特征 /${token.source}/——成败判定应只读 outcome 或调用 ` +
+            `execution-record.ts 的 deriveOutcome/projectOutcome（单一权威），禁止手写 switch 写回。` +
+            `若确属新增合法用法，请同步更新本护栏的特征提取。`,
+        ).toBe(false);
+      }
+      // 消费方必须经由单一权威实现
+      expect(
+        src.includes("deriveOutcome"),
+        `[${key}] 未引用 deriveOutcome——outcome 兜底派生必须复用单一权威函数。`,
+      ).toBe(true);
+    }
+  });
+});

package/src/__tests__/fr4-get-state-handshake.test.ts

@@ -0,0 +1,125 @@
+import { describe, expect,it } from "vitest";
+
+import { parseSpawnLine } from "../execution/spawn-event-adapter";
+import { sendGetStateCommand } from "../execution/stdin-writer";
+
+describe("FR-4: get_state RPC handshake", () => {
+  describe("sendGetStateCommand", () => {
+    it("should write get_state command to stdin", () => {
+      const written: string[] = [];
+      const child = {
+        stdin: {
+          destroyed: false,
+          write: (data: string) => {
+            written.push(data);
+            return true;
+          },
+        },
+      } as unknown as Parameters<typeof sendGetStateCommand>[0];
+
+      const id = sendGetStateCommand(child);
+
+      expect(written).toHaveLength(1);
+      const parsed = JSON.parse(written[0]);
+      expect(parsed.type).toBe("get_state");
+      expect(parsed.id).toBe(id);
+      expect(typeof parsed.id).toBe("string");
+    });
+
+    it("should not write if stdin is destroyed", () => {
+      const written: string[] = [];
+      const child = {
+        stdin: {
+          destroyed: true,
+          write: (data: string) => {
+            written.push(data);
+            return true;
+          },
+        },
+      } as unknown as Parameters<typeof sendGetStateCommand>[0];
+
+      sendGetStateCommand(child);
+
+      expect(written).toHaveLength(0);
+    });
+
+    it("should not write if stdin is null", () => {
+      const child = {
+        stdin: null,
+      } as unknown as Parameters<typeof sendGetStateCommand>[0];
+
+      // Should not throw
+      sendGetStateCommand(child);
+    });
+  });
+
+  describe("parseSpawnLine: get_state response", () => {
+    it("should parse get_state response correctly", () => {
+      const line = JSON.stringify({
+        type: "response",
+        command: "get_state",
+        success: true,
+        id: "test-req-id",
+        data: {
+          sessionFile: "/path/to/session.jsonl",
+          sessionId: "session-123",
+        },
+      });
+
+      const parsed = parseSpawnLine(line);
+      expect(parsed).not.toBeNull();
+      expect(parsed!.kind).toBe("response");
+      if (parsed!.kind === "response") {
+        expect(parsed!.command).toBe("get_state");
+        expect(parsed!.success).toBe(true);
+        expect(parsed!.id).toBe("test-req-id");
+        expect(parsed!.data).toEqual({
+          sessionFile: "/path/to/session.jsonl",
+          sessionId: "session-123",
+        });
+      }
+    });
+
+    it("should parse get_state error response", () => {
+      const line = JSON.stringify({
+        type: "response",
+        command: "get_state",
+        success: false,
+        id: "test-req-id",
+        error: "session not initialized",
+      });
+
+      const parsed = parseSpawnLine(line);
+      expect(parsed).not.toBeNull();
+      expect(parsed!.kind).toBe("response");
+      if (parsed!.kind === "response") {
+        expect(parsed!.command).toBe("get_state");
+        expect(parsed!.success).toBe(false);
+        expect(parsed!.error).toBe("session not initialized");
+      }
+    });
+
+    it("should parse get_state response without id (notification)", () => {
+      const line = JSON.stringify({
+        type: "response",
+        command: "get_state",
+        success: true,
+        data: { sessionId: "session-456" },
+      });
+
+      const parsed = parseSpawnLine(line);
+      expect(parsed).not.toBeNull();
+      expect(parsed!.kind).toBe("response");
+      if (parsed!.kind === "response") {
+        expect(parsed!.command).toBe("get_state");
+        expect(parsed!.id).toBeUndefined();
+      }
+    });
+  });
+
+  // [B8] 删除原 "get_state response matching in stdout pump" describe 块（3 case）：
+  // 该块在测试内重写了 session-runner 的 response matching 逻辑（Map<id,resolver> +
+  //  delete + resolver(data)），断言的是测试自己复制的逻辑而非生产代码——tautological
+  // （同义反复），无法捕获生产 matching 的真实回归。真实覆盖已在 run-spawn-rpc-mode.test.ts
+  // （端到端跑 session-runner 的 stdout pump + get_state 握手）中存在，此处删除不减覆盖。
+});

package/src/__tests__/fr8-orphan-recovery.test.ts

@@ -0,0 +1,259 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { afterEach,beforeEach, describe, expect, it } from "vitest";
+
+import { ManifestStore } from "../execution/manifest-store";
+import { RecordStore } from "../execution/record-store";
+
+describe("FR-8: Orphan Recovery from Manifest", () => {
+  let rootDir: string;
+  let sessionsDir: string;
+  let recordsDir: string;
+  let manifestStore: ManifestStore;
+
+  beforeEach(() => {
+    // [DS3] 两层布局：sessions/records 平级落同一 rootDir（对齐生产 <enc> 段结构），
+    // sessions-index.json 落 dirname(sessionsDir)=rootDir 内随 afterEach 清理，
+    // 不写 os.tmpdir() 本身（并行 worker 共写会跨文件污染）。
+    rootDir = fs.mkdtempSync(path.join(os.tmpdir(), "fr8-"));
+    sessionsDir = path.join(rootDir, "sessions");
+    fs.mkdirSync(sessionsDir);
+    recordsDir = path.join(rootDir, "records");
+    manifestStore = new ManifestStore(recordsDir);
+  });
+
+  afterEach(() => {
+    // maxRetries：fire-and-forget 的 sessions-index 写可能与删除并发（ENOTEMPTY 竞态）
+    fs.rmSync(rootDir, { recursive: true, force: true, maxRetries: 5, retryDelay: 20 });
+  });
+
+  it("should recover orphan records from manifest when session.jsonl is missing", async () => {
+    const store = new RecordStore(sessionsDir, manifestStore);
+
+    // Write a manifest record (simulating a subagent that crashed before writing session.jsonl)
+    await manifestStore.writeManifest({
+      id: "orphan-1",
+      rootSessionId: "session-main",
+      agentName: "worker",
+      status: "closed",
+      createdAt: 1000,
+      completedAt: 2000,
+      sessionFile: "/path/to/session.jsonl",
+    });
+
+    const records = store.collectRecords(100, "all", "session-main");
+    expect(records).toHaveLength(1);
+    expect(records[0].id).toBe("orphan-1");
+    expect(records[0].agent).toBe("worker");
+    expect(records[0].status).toBe("closed");
+    expect(records[0].startedAt).toBe(1000);
+    expect(records[0].endedAt).toBe(2000);
+  });
+
+  it("should not duplicate records already recovered from session.jsonl", async () => {
+    // Create a session.jsonl with an identity entry (simulating successful reconstruction)
+    const sessionId = "existing-session";
+    const timestamp = "2026-07-18T12-00-00-000Z";
+    const sessionFile = path.join(sessionsDir, `${timestamp.replace(/[:.]/g, "-")}_${sessionId}.jsonl`);
+    fs.writeFileSync(sessionFile, JSON.stringify({
+      type: "custom",
+      customType: "subagent-identity",
+      data: {
+        id: "existing-1",
+        agent: "explorer",
+        mode: "background",
+        task: "explore codebase",
+        slug: "explore",
+        startedAt: 1000,
+        rootSessionId: "session-main",
+        depth: 0,
+      },
+    }) + "\n");
+
+    // Also write a manifest for the same record
+    await manifestStore.writeManifest({
+      id: "existing-1",
+      rootSessionId: "session-main",
+      agentName: "explorer",
+      status: "closed",
+      createdAt: 1000,
+      completedAt: 2000,
+      sessionFile,
+    });
+
+    const store = new RecordStore(sessionsDir, manifestStore);
+    const records = store.collectRecords(100, "all", "session-main");
+
+    // Should have exactly 1 record (no duplication)
+    const matching = records.filter((r) => r.id === "existing-1");
+    expect(matching).toHaveLength(1);
+  });
+
+  it("should filter manifest records by rootSessionId", async () => {
+    const store = new RecordStore(sessionsDir, manifestStore);
+
+    await manifestStore.writeManifest({
+      id: "orphan-session-a",
+      rootSessionId: "session-a",
+      agentName: "worker",
+      status: "closed",
+      createdAt: 1000,
+    });
+
+    await manifestStore.writeManifest({
+      id: "orphan-session-b",
+      rootSessionId: "session-b",
+      agentName: "worker",
+      status: "closed",
+      createdAt: 2000,
+    });
+
+    const recordsA = store.collectRecords(100, "all", "session-a");
+    expect(recordsA).toHaveLength(1);
+    expect(recordsA[0].id).toBe("orphan-session-a");
+
+    const recordsB = store.collectRecords(100, "all", "session-b");
+    expect(recordsB).toHaveLength(1);
+    expect(recordsB[0].id).toBe("orphan-session-b");
+  });
+
+  it("should map manifest status correctly (4-state)", async () => {
+    const store = new RecordStore(sessionsDir, manifestStore);
+
+    await manifestStore.writeManifest({
+      id: "status-completed",
+      rootSessionId: "session-main",
+      agentName: "worker",
+      status: "closed",
+      createdAt: 1000,
+    });
+
+    await manifestStore.writeManifest({
+      id: "status-failed",
+      rootSessionId: "session-main",
+      agentName: "worker",
+      status: "closed",
+      createdAt: 2000,
+    });
+
+    await manifestStore.writeManifest({
+      id: "status-cancelled",
+      rootSessionId: "session-main",
+      agentName: "worker",
+      status: "cancelled",
+      createdAt: 3000,
+    });
+
+    // M3: ManifestRecord.status 4 态（running/completed/failed/cancelled）。
+    // v4 B-1：cancelled 不再是独立 ExecutionStatus——mapManifestStatus 映射为 closed
+    //（closedReason='cancelled' 由重建路径 sidecar 推断）。crashed 不进 manifest
+    //（crashed 是重启重建时靠 sidecar 四分支推断的派生态,见 record-store.ts reconstructAll）。
+    const records = store.collectRecords(100, "all", "session-main");
+    expect(records).toHaveLength(3);
+
+    expect(records.find((r) => r.id === "status-completed")?.status).toBe("closed");
+    expect(records.find((r) => r.id === "status-failed")?.status).toBe("closed");
+    expect(records.find((r) => r.id === "status-cancelled")?.status).toBe("closed");
+  });
+
+  it("mapManifestStatus 越界值返回 null：collectRecords 跳过损坏 record（不降级 failed）", async () => {
+    const store = new RecordStore(sessionsDir, manifestStore);
+
+    // 合法 record（对照组）
+    await manifestStore.writeManifest({
+      id: "good",
+      rootSessionId: "session-main",
+      agentName: "worker",
+      status: "closed",
+      createdAt: 1000,
+    });
+
+    // 直接写磁盘注入非法 status（绕过 writeManifest 的 TS 类型守卫）。
+    // crashed 不在 4 态枚举——它是重建派生态,意外出现在 manifest 应被跳过而非降级 failed。
+    fs.writeFileSync(path.join(recordsDir, "bad-crashed.json"), JSON.stringify({
+      id: "bad-crashed", rootSessionId: "session-main", agentName: "worker",
+      status: "crashed", createdAt: 2000,
+    }));
+    // 未知值同样跳过
+    fs.writeFileSync(path.join(recordsDir, "bad-unknown.json"), JSON.stringify({
+      id: "bad-unknown", rootSessionId: "session-main", agentName: "worker",
+      status: "totally-unknown", createdAt: 3000,
+    }));
+
+    const records = store.collectRecords(100, "all", "session-main");
+    // 只剩 good——损坏 record 被跳过 + console.warn,不误显示为 failed
+    expect(records).toHaveLength(1);
+    expect(records[0].id).toBe("good");
+    expect(records[0].status).toBe("closed");
+  });
+
+  it("in-memory records should take priority over manifest records", async () => {
+    const store = new RecordStore(sessionsDir, manifestStore);
+
+    // Register a running record in memory
+    store.register({
+      id: "memory-record",
+      agent: "worker",
+      model: "test/model",
+      thinkingLevel: undefined,
+      mode: "background",
+      task: "test task",
+      slug: "test",
+      startedAt: 1000,
+      rootSessionId: "session-main",
+      parentRecordId: undefined,
+      depth: 0,
+      status: "running",
+      turns: [],
+      turnCount: 0,
+      totalTokens: 0,
+      lastError: undefined,
+      endedAt: undefined,
+      result: undefined,
+      error: undefined,
+      agentResult: undefined,
+      sessionFile: undefined,
+      controller: undefined,
+    });
+
+    // Also write a manifest with the same id but different status
+    await manifestStore.writeManifest({
+      id: "memory-record",
+      rootSessionId: "session-main",
+      agentName: "different-agent",
+      status: "closed",
+      createdAt: 500,
+    });
+
+    const records = store.collectRecords(100, "all", "session-main");
+    expect(records).toHaveLength(1);
+    // Memory record should win
+    expect(records[0].status).toBe("running");
+    expect(records[0].agent).toBe("worker");
+  });
+
+  it("should work without manifestStore (backward compatible)", () => {
+    const store = new RecordStore(sessionsDir); // No manifestStore
+
+    // Should not throw
+    const records = store.collectRecords(100, "all", "session-main");
+    expect(records).toHaveLength(0);
+  });
+
+  it("should handle manifest with status=running as running", async () => {
+    const store = new RecordStore(sessionsDir, manifestStore);
+
+    await manifestStore.writeManifest({
+      id: "still-running",
+      rootSessionId: "session-main",
+      agentName: "worker",
+      status: "running",
+      createdAt: Date.now(),
+    });
+
+    const records = store.collectRecords(100, "all", "session-main");
+    expect(records).toHaveLength(1);
+    expect(records[0].status).toBe("running");
+  });
+});

package/src/__tests__/m2-append-content-probe.test.ts

@@ -0,0 +1,73 @@
+// M2 修复回归探针（design.json TC1）。
+//
+// M2 bug：旧实现把 schema SO 指令写成临时文件，push 文件路径（而非内容）给下游，
+// 下游 mapper/session-runner 把路径当文本拼进最终 append 文件，子进程收到
+// "/var/folders/.../xxx.md" 路径垃圾，schema 指令从未进入子进程。
+//
+// 修复后：schema 指令内容直传 appendSystemPrompt（不写盘、无临时文件）。
+// 本探针锁死：appendSystemPrompt 只含 SO 指令内容，不含 agent 正文，无路径，无临时文件。
+
+import { describe, expect, it } from "vitest";
+
+import type { AgentCallOpts } from "../orchestration/models/types.ts";
+import { resolveAgentOpts } from "../orchestration/agent-opts-resolver.ts";
+
+describe("M2 append-content probe (design.json TC1)", () => {
+  it("schema + agent 时 appendSystemPrompt 只含 SO 指令内容（非路径、非 agent 正文）", () => {
+    const opts: AgentCallOpts = {
+      prompt: "run task",
+      schema: { type: "object", properties: { ok: { type: "boolean" } } },
+      agent: "/fake/agents/worker.md",
+      description: "m2-probe",
+      slug: "m2-probe",
+    };
+
+    const result = resolveAgentOpts(opts);
+
+    expect(result.error).toBeUndefined();
+    // 只含 SO 指令（length === 1）
+    expect(result.opts.appendSystemPrompt).toBeDefined();
+    expect(result.opts.appendSystemPrompt!.length).toBe(1);
+
+    const item = result.opts.appendSystemPrompt![0];
+
+    // 内容语义：含 structured-output 关键词
+    expect(item).toContain("structured-output");
+    // 非路径：不匹配 /tmp 或 var/folders（M2 bug 旧实现 push 路径字符串）
+    expect(item).not.toMatch(/\/tmp\/|\/var\/folders\//);
+    // 不以 .md 结尾（路径特征）
+    expect(item).not.toMatch(/\.md$/);
+    // 不含 agent 正文/路径标识词（agent 正文不经 appendSystemPrompt，防双重注入回归）
+    expect(item).not.toContain("/fake/agents/worker.md");
+    // agent ref 原样保留（resolveAgentOpts 不消费 agent，交 resolveIdentity）
+    expect(result.opts.agent).toBe("/fake/agents/worker.md");
+    // model/thinkingLevel 未被修改（agent 处理移交，不在此提升层级）
+    expect(result.opts.model).toBeUndefined();
+    expect(result.opts.thinkingLevel).toBeUndefined();
+    // schemaEnv 设置（PI_WORKFLOW_SCHEMA 契约）
+    expect(result.opts.schemaEnv).toBe(JSON.stringify(opts.schema));
+  });
+
+  it("agent 存在不影响 appendSystemPrompt 内容（agent 正文结构性不泄漏）", () => {
+    const schema = { type: "object" } as Record<string, unknown>;
+    const withAgent = resolveAgentOpts({ prompt: "x", schema, agent: "/fake/a.md" });
+    const withoutAgent = resolveAgentOpts({ prompt: "x", schema });
+
+    // 加不加 agent，appendSystemPrompt 完全相同——证明 agent 不被消费、正文不注入
+    expect(withAgent.opts.appendSystemPrompt).toEqual(withoutAgent.opts.appendSystemPrompt);
+  });
+
+  it("无 schema 时 appendSystemPrompt undefined", () => {
+    const result = resolveAgentOpts({ prompt: "x", agent: "/fake/a.md" });
+    expect(result.opts.appendSystemPrompt).toBeUndefined();
+  });
+
+  it("resolveAgentOpts 无文件副作用——同 schema 多次调用结果字节相同（无随机路径）", () => {
+    const schema = { type: "object" } as Record<string, unknown>;
+    const a = resolveAgentOpts({ prompt: "x", schema });
+    const b = resolveAgentOpts({ prompt: "x", schema });
+
+    // 旧实现每次写入随机 UUID 文件名路径，结果不同；内容直传后结果确定性相同
+    expect(a.opts.appendSystemPrompt).toEqual(b.opts.appendSystemPrompt);
+  });
+});