@zhushanwen/pi-subagent-workflow 0.1.0

package/src/execution/__tests__/alive-store.test.ts

@@ -0,0 +1,147 @@
+// src/__tests__/alive-store.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 {
+  isProcessAlive,
+  readAliveMarker,
+  removeAliveMarker,
+  writeAliveMarker,
+} from "../alive-store.ts";
+import type { AliveMarker } from "../types.ts";
+
+function makeTmpDir(): string {
+  return fs.mkdtempSync(path.join(os.tmpdir(), "alive-store-test-"));
+}
+
+describe("alive-store", () => {
+  let tmpDir: string;
+
+  afterEach(() => {
+    if (tmpDir) {
+      fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+  });
+
+  // ── writeAliveMarker + readAliveMarker 往返 ──
+
+  it("write → read round-trip", () => {
+    tmpDir = makeTmpDir();
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    const marker: AliveMarker = { pid: 12345, id: "bg-1-abc", startedAt: Date.now() };
+
+    writeAliveMarker(sessionFile, marker);
+    const result = readAliveMarker(sessionFile);
+
+    expect(result).toEqual(marker);
+    // 验证 sidecar 文件是单行 JSON
+    const raw = fs.readFileSync(`${sessionFile}.alive`, "utf-8");
+    expect(raw.endsWith("\n")).toBe(true);
+    expect(JSON.parse(raw.trim())).toEqual(marker);
+  });
+
+  // ── readAliveMarker 损坏文件 ──
+
+  it("readAliveMarker returns undefined for corrupted file", () => {
+    tmpDir = makeTmpDir();
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    fs.writeFileSync(`${sessionFile}.alive`, "not-json", "utf-8");
+
+    expect(readAliveMarker(sessionFile)).toBeUndefined();
+  });
+
+  it("readAliveMarker returns undefined for structurally invalid JSON", () => {
+    tmpDir = makeTmpDir();
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    // pid 字段缺失
+    fs.writeFileSync(`${sessionFile}.alive`, '{"id":"x","startedAt":1}\n', "utf-8");
+
+    expect(readAliveMarker(sessionFile)).toBeUndefined();
+  });
+
+  it("readAliveMarker returns undefined when file does not exist", () => {
+    tmpDir = makeTmpDir();
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+
+    expect(readAliveMarker(sessionFile)).toBeUndefined();
+  });
+
+  // ── removeAliveMarker ──
+
+  it("removeAliveMarker removes existing sidecar", () => {
+    tmpDir = makeTmpDir();
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+    const marker: AliveMarker = { pid: 1, id: "x", startedAt: 0 };
+
+    writeAliveMarker(sessionFile, marker);
+    expect(fs.existsSync(`${sessionFile}.alive`)).toBe(true);
+
+    removeAliveMarker(sessionFile);
+    expect(fs.existsSync(`${sessionFile}.alive`)).toBe(false);
+  });
+
+  it("removeAliveMarker does not throw when file does not exist", () => {
+    tmpDir = makeTmpDir();
+    const sessionFile = path.join(tmpDir, "session.jsonl");
+
+    expect(() => removeAliveMarker(sessionFile)).not.toThrow();
+  });
+
+  // ── isProcessAlive ──
+
+  it("isProcessAlive returns true for current process", () => {
+    expect(isProcessAlive(process.pid)).toBe(true);
+  });
+
+  it("isProcessAlive returns false for non-existent pid", () => {
+    // pid 0 不存在于用户空间（kill(0,0) 在某些 OS 有特殊语义，用大数更安全）
+    expect(isProcessAlive(9999999)).toBe(false);
+  });
+
+  it("isProcessAlive returns true for EPERM (process exists but no permission)", () => {
+    // 模拟 EPERM：进程存在但无权限发信号
+    const err = new Error("EPERM") as NodeJS.ErrnoException;
+    err.code = "EPERM";
+    const originalKill = process.kill;
+    process.kill = (_pid: number, _signal?: string | number) => {
+      throw err;
+    };
+    try {
+      expect(isProcessAlive(12345)).toBe(true);
+    } finally {
+      process.kill = originalKill;
+    }
+  });
+
+  it("isProcessAlive returns false for ESRCH (no such process)", () => {
+    // 模拟 ESRCH：进程不存在
+    const err = new Error("ESRCH") as NodeJS.ErrnoException;
+    err.code = "ESRCH";
+    const originalKill = process.kill;
+    process.kill = (_pid: number, _signal?: string | number) => {
+      throw err;
+    };
+    try {
+      expect(isProcessAlive(12345)).toBe(false);
+    } finally {
+      process.kill = originalKill;
+    }
+  });
+
+  it("isProcessAlive returns false for unknown errors", () => {
+    // 模拟未知错误：保守判死
+    const originalKill = process.kill;
+    process.kill = (_pid: number, _signal?: string | number) => {
+      throw new Error("unknown error");
+    };
+    try {
+      expect(isProcessAlive(12345)).toBe(false);
+    } finally {
+      process.kill = originalKill;
+    }
+  });
+});

package/src/execution/__tests__/bg-notify-render.test.ts

@@ -0,0 +1,256 @@
+// src/__tests__/bg-notify-render.test.ts
+//
+// background 完成通知的渲染测试。
+//
+// 核心契约：renderBgNotifyMessage 必须返回带紫色背景 + 圆角边框的组件——
+// Pi 的 CustomMessageComponent 对 customRenderer 返回值是「裸 addChild」，
+// 返回裸 Text 会丢失紫色背景。本测试钉死「施加 customMessageBg + 边框」这一行为。
+//
+// 测试用 mock theme（bg 记录调用色 token），不依赖真实 Pi Theme。
+
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { describe, expect, it } from "vitest";
+
+import { renderBgNotifyMessage } from "../../interface/bg-notify-render.ts";
+
+/**
+ * 构造 mock theme：bg 记录被调用的色 token，fg/bold 透传文本。
+ *
+ * 真实 theme.fg/bg 会包裹 ANSI 码；这里透传纯文本，让断言可读。
+ * 边框/背景 token 通过 bgColors 记录。
+ */
+function makeTheme(): { theme: Theme; bgColors: string[]; fgColors: string[] } {
+  const bgColors: string[] = [];
+  const fgColors: string[] = [];
+  const theme = {
+    fg: (tag: string, text: string) => {
+      fgColors.push(tag);
+      return text;
+    },
+    bold: (text: string) => text,
+    bg: (color: string, text: string) => {
+      bgColors.push(color);
+      return text;
+    },
+  };
+  return { theme: theme as Theme, bgColors, fgColors };
+}
+
+describe("renderBgNotifyMessage", () => {
+  it("单条 done → 施加 customMessageBg 背景 + 边框 + 内容可见", () => {
+    const { theme, bgColors } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      { details: { status: "done", agent: "worker", id: "bg-1", result: "All green" } },
+      { expanded: false },
+      theme,
+    );
+
+    expect(comp).toBeDefined();
+    const lines = comp!.render(80);
+    const joined = lines.join("\n");
+    // 紫色背景施加（内容行 ≥ 1 次）
+    expect(bgColors.filter((c) => c === "customMessageBg").length).toBeGreaterThanOrEqual(1);
+    // 圆角边框
+    expect(lines[0]).toContain("╭");
+    expect(lines[0]).toContain("╮");
+    expect(lines[lines.length - 1]).toContain("╰");
+    expect(lines[lines.length - 1]).toContain("╯");
+    for (let i = 1; i < lines.length - 1; i++) {
+      expect(lines[i]).toContain("│");
+    }
+    // 前景内容仍在
+    expect(joined).toContain("worker");
+    expect(joined).toContain("All green");
+  });
+
+  it("id 用 shortId 截断（bg-tag-seq-ts → bg-tag-seq）", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      { details: { status: "done", agent: "w", id: "bg-f6f731-10-1719500000000", result: "ok" } },
+      { expanded: false },
+      theme,
+    );
+    const joined = comp!.render(80).join("\n");
+    // shortId 对 background id 取前 3 段（bg/tag/seq）
+    expect(joined).toContain("bg-f6f731-10");
+    // 完整时间戳不应出现
+    expect(joined).not.toContain("1719500000000");
+  });
+
+  it("单条 failed → 内容含 Error + agent", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      { details: { status: "failed", agent: "scout", id: "bg-2", error: "boom" } },
+      { expanded: false },
+      theme,
+    );
+    expect(comp).toBeDefined();
+    const joined = comp!.render(80).join("\n");
+    expect(joined).toContain("scout");
+    expect(joined).toContain("Error");
+    expect(joined).toContain("boom");
+  });
+
+  it("批量 → 施加 customMessageBg + 边框，每条 agent 可见", () => {
+    const { theme, bgColors } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      {
+        details: {
+          batch: true,
+          items: [
+            { status: "done", agent: "alpha", id: "1", result: "r1" },
+            { status: "failed", agent: "beta", id: "2", error: "e2" },
+          ],
+        },
+      },
+      { expanded: false },
+      theme,
+    );
+    expect(comp).toBeDefined();
+    const lines = comp!.render(80);
+    const joined = lines.join("\n");
+    expect(bgColors).toContain("customMessageBg");
+    expect(joined).toContain("alpha");
+    expect(joined).toContain("beta");
+    // 边框
+    expect(lines[0]).toContain("╭");
+    expect(lines[lines.length - 1]).toContain("╰");
+  });
+
+  it("cancelled → 内容含 cancelled", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      { details: { status: "cancelled", agent: "w", id: "bg-3" } },
+      { expanded: false },
+      theme,
+    );
+    expect(comp).toBeDefined();
+    expect(comp!.render(80).join("\n")).toContain("cancelled");
+  });
+
+  it("details 缺失/结构不全 → undefined（走 Pi 默认渲染兜底）", () => {
+    const { theme } = makeTheme();
+    expect(renderBgNotifyMessage({ details: undefined }, { expanded: false }, theme)).toBeUndefined();
+    expect(renderBgNotifyMessage({ details: { foo: 1 } }, { expanded: false }, theme)).toBeUndefined();
+    // 缺 status / agent
+    expect(
+      renderBgNotifyMessage({ details: { id: "x", agent: "w" } }, { expanded: false }, theme),
+    ).toBeUndefined();
+    expect(
+      renderBgNotifyMessage({ details: { status: "done", id: "x" } }, { expanded: false }, theme),
+    ).toBeUndefined();
+  });
+
+  it("details 无效时不施加任何背景（兜底路径不应泄漏背景色）", () => {
+    const { theme, bgColors } = makeTheme();
+    renderBgNotifyMessage({ details: undefined }, { expanded: false }, theme);
+    expect(bgColors).not.toContain("customMessageBg");
+  });
+
+  // ── model 显示 ──
+
+  it("record 带 model → 内容含 model 字符串（agent 后、状态描述前）", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      { details: { status: "done", agent: "general-purpose", model: "anthropic/sonnet-4-5", id: "bg-1", result: "ok" } },
+      { expanded: false },
+      theme,
+    );
+    const joined = comp!.render(80).join("\n");
+    expect(joined).toContain("anthropic/sonnet-4-5");
+    // agent 和状态仍在
+    expect(joined).toContain("general-purpose");
+    expect(joined).toContain("finished");
+  });
+
+  it("record 无 model → 向后兼容，不渲染 model 段不崩", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      { details: { status: "done", agent: "worker", id: "bg-2", result: "r" } },
+      { expanded: false },
+      theme,
+    );
+    const joined = comp!.render(80).join("\n");
+    expect(joined).toContain("worker");
+    expect(joined).toContain("finished");
+  });
+
+  // ── ANSI 背景 safety ──
+
+  it("着色行截断的 \\x1b[0m 被替换为精确 reset（不破坏背景）", () => {
+    // mock theme 产生真实 ANSI（fg 用 italic \x1b[3m..\x1b[23m，bold 用 \x1b[1m..\x1b[22m）
+    const theme = {
+      fg: (_tag: string, text: string) => `\x1b[3m${text}\x1b[23m`,
+      bold: (text: string) => `\x1b[1m${text}\x1b[22m`,
+      bg: (_color: string, text: string) => `\x1b[48;5;95m${text}\x1b[49m`,
+    } as Theme;
+    // 关键：用窄 width + 长 agent 名，让 head 行在 truncLine 内被真正截断
+    // head 行含 ANSI（fg 包裹），截断时 activeStyles 非空 → 会产生 \x1b[0m
+    const longAgent = "a".repeat(60);
+    const comp = renderBgNotifyMessage(
+      { details: { status: "done", agent: longAgent, id: "bg-1", result: "ok" } },
+      { expanded: false },
+      theme,
+    );
+    const lines = comp!.render(30);
+    // 内容行（非边框）不应含 \x1b[0m（会破坏背景）
+    const contentLines = lines.slice(1, -1);
+    expect(contentLines.length).toBeGreaterThan(0);
+    for (const line of contentLines) {
+      expect(line).not.toContain("\x1b[0m");
+    }
+    // 正向验证：sanitizeAnsiForBg 把 \x1b[0m 替换成了精确 reset（\x1b[39m）
+    // 如果截断真的发生了，内容行应含 \x1b[39m（sanitize 的替换产物）
+    const hasSanitized = contentLines.some((l) => l.includes("\x1b[39m"));
+    expect(hasSanitized).toBe(true);
+  });
+
+  // ── 窄宽度退化 ──
+
+  it("极窄宽度（width < 5）退化：无边框，不崩溃，有背景", () => {
+    const { theme, bgColors } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      { details: { status: "done", agent: "w", id: "bg-1", result: "ok" } },
+      { expanded: false },
+      theme,
+    );
+    // width=3 < MIN_BORDER_WIDTH(5)，应退化为无边框模式
+    const lines = comp!.render(3);
+    expect(lines.length).toBeGreaterThan(0);
+    // 不应有边框字符（退化模式）
+    for (const line of lines) {
+      expect(line).not.toContain("╭");
+      expect(line).not.toContain("│");
+    }
+    // 仍施加背景
+    expect(bgColors).toContain("customMessageBg");
+  });
+
+  it("批量场景边框完整：所有中间行含 │", () => {
+    const { theme } = makeTheme();
+    const comp = renderBgNotifyMessage(
+      {
+        details: {
+          batch: true,
+          items: [
+            { status: "done", agent: "alpha", id: "1", result: "r1" },
+            { status: "failed", agent: "beta", id: "2", error: "e2" },
+            { status: "cancelled", agent: "gamma", id: "3" },
+          ],
+        },
+      },
+      { expanded: false },
+      theme,
+    );
+    const lines = comp!.render(80);
+    // 顶底边框
+    expect(lines[0]).toContain("╭");
+    expect(lines[0]).toContain("╮");
+    expect(lines[lines.length - 1]).toContain("╰");
+    expect(lines[lines.length - 1]).toContain("╯");
+    // 所有中间行都应有左右 │
+    for (let i = 1; i < lines.length - 1; i++) {
+      expect(lines[i]).toContain("│");
+    }
+  });
+});

package/src/execution/__tests__/concurrency-pool.test.ts

@@ -0,0 +1,217 @@
+// src/__tests__/concurrency-pool.test.ts
+import { describe, expect, it } from "vitest";
+
+import { DefaultConcurrencyPool } from "../concurrency-pool.ts";
+
+describe("DefaultConcurrencyPool", () => {
+  it("allows up to maxConcurrent concurrent tasks", async () => {
+    const pool = new DefaultConcurrencyPool(2);
+    await pool.acquire(0);
+    await pool.acquire(0);
+    // 第三个 acquire 应阻塞
+    let thirdAcquired = false;
+    const third = pool.acquire(0).then(() => { thirdAcquired = true; });
+    await new Promise((r) => setTimeout(r, 5));
+    expect(thirdAcquired).toBe(false);
+    expect(pool.active).toBe(2);
+
+    pool.release();
+    await third;
+    expect(thirdAcquired).toBe(true);
+    expect(pool.active).toBe(2);
+
+    pool.release();
+    pool.release();
+    await new Promise((r) => setTimeout(r, 5));
+    expect(pool.active).toBe(0);
+  });
+
+  it("higher priority acquires the pool first", async () => {
+    const pool = new DefaultConcurrencyPool(1);
+    await pool.acquire(0); // 占满
+
+    let lowAcquired = false;
+    let highAcquired = false;
+    const low = pool.acquire(10).then(() => { lowAcquired = true; });
+    const high = pool.acquire(0).then(() => { highAcquired = true; });
+
+    await new Promise((r) => setTimeout(r, 5));
+    pool.release();
+    await Promise.race([low, high, new Promise((r) => setTimeout(r, 20))]);
+
+    expect(highAcquired).toBe(true);
+    expect(lowAcquired).toBe(false);
+    pool.release();
+  });
+
+  it("same-priority tasks wake in FIFO (seq) order", async () => {
+    const pool = new DefaultConcurrencyPool(1);
+    await pool.acquire(0); // fill slot
+
+    const order: number[] = [];
+    // Enqueue 3 tasks with same priority — they should resolve in enqueue order
+    const p1 = pool.acquire(0).then(() => { order.push(1); pool.release(); });
+    const p2 = pool.acquire(0).then(() => { order.push(2); pool.release(); });
+    const p3 = pool.acquire(0).then(() => { order.push(3); pool.release(); });
+
+    pool.release(); // kick off the chain
+    await Promise.allSettled([p1, p2, p3]);
+
+    expect(order).toEqual([1, 2, 3]);
+  });
+
+  it("extra release() does not make active negative", () => {
+    const pool = new DefaultConcurrencyPool(2);
+    pool.release(); // no acquires yet
+    pool.release();
+    pool.release();
+    expect(pool.active).toBe(0);
+  });
+
+  it("active never exceeds maxConcurrent", async () => {
+    const pool = new DefaultConcurrencyPool(2);
+    const acquires: Array<Promise<void>> = [];
+    let peak = 0;
+    for (let i = 0; i < 6; i++) {
+      acquires.push(pool.acquire(0).then(() => {
+        peak = Math.max(peak, pool.active);
+      }));
+    }
+    // Drain: release one at a time so we can observe peak
+    for (let i = 0; i < 6; i++) {
+      pool.release();
+      await new Promise((r) => setTimeout(r, 2));
+    }
+    await Promise.allSettled(acquires);
+    expect(peak).toBeLessThanOrEqual(2);
+  });
+
+  it("clamps maxConcurrent=0 to 1 (no deadlock, C3 fix)", async () => {
+    const pool = new DefaultConcurrencyPool(0);
+    // 不会死锁——clamp 到 1，acquire 立即返回
+    await pool.acquire(0);
+    expect(pool.active).toBe(1);
+    pool.release();
+    expect(pool.active).toBe(0);
+  });
+
+  it("clamps negative maxConcurrent to 1", async () => {
+    const pool = new DefaultConcurrencyPool(-5);
+    await pool.acquire(0);
+    expect(pool.active).toBe(1);
+  });
+
+  it("priority 0 (sync) preempts priority 1000 (background)", async () => {
+    const pool = new DefaultConcurrencyPool(1);
+    await pool.acquire(1000); // background 占满
+
+    let bgAcquired = false;
+    let syncAcquired = false;
+    const bg = pool.acquire(1000).then(() => { bgAcquired = true; });
+    const sync = pool.acquire(0).then(() => { syncAcquired = true; });
+
+    await new Promise((r) => setTimeout(r, 5));
+    pool.release();
+    await Promise.race([bg, sync, new Promise((r) => setTimeout(r, 20))]);
+
+    expect(syncAcquired).toBe(true);
+    expect(bgAcquired).toBe(false);
+    pool.release();
+  });
+
+  // ============================================================
+  // 分层配额：effectiveMaxConcurrent 参数控制放行上限 (T-A1~T-A4)
+  // ============================================================
+  //
+  // [背景] T2 Wave 0 给 acquire 增加可选 effectiveMaxConcurrent 参数，让调用方
+  // 传 max(1, maxConcurrent - depth) 实现分层配额（嵌套越深有效并发越小）。
+  // 该参数覆盖实例级 maxConcurrent 的本次调用上限，不改实例状态。
+  // 这组测试锁定该参数的语义。
+
+  describe("分层配额 effectiveMaxConcurrent (T-A1~T-A4)", () => {
+    it("T-A1: effectiveMaxConcurrent 限制本次调用放行数（小于实例级 maxConcurrent）", async () => {
+      // 实例配额 5，但本次调用 effective=2 → 第 3 个应阻塞
+      const pool = new DefaultConcurrencyPool(5);
+      await pool.acquire(0, 2);
+      await pool.acquire(0, 2);
+      expect(pool.active).toBe(2);
+
+      let thirdAcquired = false;
+      const third = pool.acquire(0, 2).then(() => { thirdAcquired = true; });
+      await new Promise((r) => setTimeout(r, 5));
+
+      expect(thirdAcquired).toBe(false);
+      expect(pool.active).toBe(2);
+
+      pool.release();
+      await third;
+      expect(thirdAcquired).toBe(true);
+      pool.release();
+      pool.release();
+    });
+
+    it("T-A2: 同一 pool 实例不同 effectiveMaxConcurrent 控制不同调用放行数", async () => {
+      // 同一 pool（实例级 maxConcurrent=5）
+      const pool = new DefaultConcurrencyPool(5);
+      // 前 3 个用 effective=3，全放行（active 0→1→2→3，每次 < 3）
+      await pool.acquire(0, 3);
+      await pool.acquire(0, 3);
+      await pool.acquire(0, 3);
+      expect(pool.active).toBe(3);
+
+      // 第 4 个用 effective=3 → 阻塞（active 3 >= 3）
+      let blockedAcquired = false;
+      const blocked = pool.acquire(0, 3).then(() => { blockedAcquired = true; });
+      await new Promise((r) => setTimeout(r, 5));
+      expect(blockedAcquired).toBe(false);
+
+      // 换 effective=5 放行（active 3 < 5）
+      let wideAcquired = false;
+      const wide = pool.acquire(0, 5).then(() => { wideAcquired = true; });
+      await new Promise((r) => setTimeout(r, 5));
+      expect(wideAcquired).toBe(true);
+      expect(pool.active).toBe(4);
+
+      // wide release 后 blocked 仍等（active 3 >= 3 不变直到再 release）
+      pool.release(); // wide 释放
+      await new Promise((r) => setTimeout(r, 5));
+      expect(blockedAcquired).toBe(true);
+
+      // 清理
+      pool.release();
+      pool.release();
+      pool.release();
+      pool.release();
+      await Promise.allSettled([blocked, wide]);
+    });
+
+    it("T-A3: effectiveMaxConcurrent=1 只放行 1 个（保底）", async () => {
+      const pool = new DefaultConcurrencyPool(5);
+      await pool.acquire(0, 1);
+      expect(pool.active).toBe(1);
+
+      let secondAcquired = false;
+      const second = pool.acquire(0, 1).then(() => { secondAcquired = true; });
+      await new Promise((r) => setTimeout(r, 5));
+      expect(secondAcquired).toBe(false);
+      expect(pool.active).toBe(1);
+
+      pool.release();
+      await second;
+      expect(secondAcquired).toBe(true);
+      pool.release();
+    });
+
+    it("T-A4: maxConcurrent readonly 属性可读且等于构造值", () => {
+      const pool = new DefaultConcurrencyPool(4);
+      expect(pool.maxConcurrent).toBe(4);
+
+      // clamp 路径也通过该属性暴露
+      const clamped = new DefaultConcurrencyPool(0);
+      expect(clamped.maxConcurrent).toBe(1);
+
+      const negative = new DefaultConcurrencyPool(-3);
+      expect(negative.maxConcurrent).toBe(1);
+    });
+  });
+});