@zhushanwen/pi-subagent-workflow 7.3.1 → 7.3.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "7.3.1",
+  "version": "7.3.2",
   "type": "module",
   "main": "index.ts",
   "description": "Unified subagent execution and multi-agent workflow orchestration for Pi — spawned-process agent runtime with sync/background modes, stateful workflow management with persistence, state machine, and execution tracing.",

package/src/execution/__tests__/spawn-worktree-guidance.test.ts

@@ -0,0 +1,206 @@
+// src/execution/__tests__/spawn-worktree-guidance.test.ts
+//
+// worktree 模式认知纠正提示注入测试。
+//
+// 背景：worktree checkout 放 os.tmpdir()（路径形似临时沙箱），子 agent 无 worktree 语义
+// 提示时误判 cwd 为"空隔离目录"，主动 cd 别处放弃隔离（wave-agent 事故 session 019ff64c）。
+// 修复在 runSpawn 的 appendParts 注入 WORKTREE_GUIDANCE_PROMPT。
+//
+// 验证：
+//   - worktree 模式（opts.worktree 传入）→ appendSystemPrompt content 含 WORKTREE_GUIDANCE_PROMPT
+//   - 非 worktree 模式 → content 不含 worktree 提示
+//
+// 测试策略：mock writePromptToTempFile 捕获拼接后的 appendParts content（vi.hoisted 防
+// vi.mock hoisting 引用未初始化变量），断言含/不含 worktree 提示标识。
+
+import type { PassThrough } from "node:stream";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// 捕获 writePromptToTempFile 的 content 参数（appendParts.join("\n\n")）。
+// vi.hoisted 保证变量在 vi.mock factory hoisting 前已声明可用。
+const captured = vi.hoisted(() => ({ content: "" }));
+
+// ── mock modules（与 session-runner-schema-env.test.ts 同模式）──
+
+vi.mock("node:child_process", async () => {
+  const { EventEmitter } = await import("node:events");
+  const { PassThrough } = await import("node:stream");
+
+  class FakeChild extends EventEmitter {
+    pid = 12345;
+    stdout = new PassThrough();
+    stderr = new PassThrough();
+    killed = false;
+    killSignal: string | undefined;
+    kill(sig?: string): boolean {
+      this.killed = true;
+      this.killSignal = sig;
+      return true;
+    }
+  }
+
+  return {
+    spawn: vi.fn(() => new FakeChild()),
+    execFileSync: vi.fn(() => ""),
+  };
+});
+
+vi.mock("node:fs", async () => {
+  const actual = await import("node:fs");
+  return {
+    default: {
+      ...actual,
+      mkdirSync: vi.fn(),
+      existsSync: vi.fn(() => false),
+      appendFileSync: vi.fn(),
+      writeFileSync: vi.fn(),
+      readdirSync: vi.fn(() => []),
+    },
+    mkdirSync: vi.fn(),
+    existsSync: vi.fn(() => false),
+    appendFileSync: vi.fn(),
+    writeFileSync: vi.fn(),
+    readdirSync: vi.fn(() => []),
+    promises: actual.promises,
+  };
+});
+
+vi.mock("../alive-store.ts", () => ({
+  writeAliveMarker: vi.fn(),
+}));
+
+vi.mock("../temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string, content: string) => {
+    captured.content = content;
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { spawn } from "node:child_process";
+
+import { createRecord } from "../execution-record.ts";
+import { runSpawn, type RunOptions, type SessionRunnerContext } from "../session-runner.ts";
+
+const mockSpawn = vi.mocked(spawn);
+
+interface FakeChild {
+  pid: number;
+  stdout: PassThrough;
+  stderr: PassThrough;
+  killed: boolean;
+  killSignal: string | undefined;
+  kill(sig?: string): boolean;
+  emit(event: string, ...args: unknown[]): boolean;
+}
+
+function getLastSpawnedChild(): FakeChild {
+  const result = mockSpawn.mock.results.at(-1);
+  if (!result) throw new Error("spawn was not called yet");
+  return result.value as FakeChild;
+}
+
+async function waitForSpawn(timeoutMs = 1000): Promise<void> {
+  const start = Date.now();
+  while (mockSpawn.mock.results.length === 0) {
+    if (Date.now() - start > timeoutMs) {
+      throw new Error(`spawn was not called within ${timeoutMs}ms`);
+    }
+    await new Promise((r) => setTimeout(r, 5));
+  }
+}
+
+function makeRecord() {
+  return createRecord("wt-guidance-1", {
+    agent: "general-purpose",
+    model: "test/model",
+    mode: "sync",
+    task: "test task",
+    startedAt: Date.now(),
+    rootSessionId: "s1",
+    parentRecordId: undefined,
+    depth: 0,
+  });
+}
+
+function makeRunOpts(overrides: Partial<RunOptions> = {}): RunOptions {
+  return {
+    resolved: { model: { provider: "test", id: "model" }, thinkingLevel: undefined },
+    agentConfig: undefined,
+    appendSystemPrompt: undefined,
+    skillPath: undefined,
+    schema: undefined,
+    maxTurns: undefined,
+    graceTurns: undefined,
+    signal: undefined,
+    onEvent: undefined,
+    ...overrides,
+  };
+}
+
+function makeCtx(overrides: Partial<SessionRunnerContext> = {}): SessionRunnerContext {
+  return {
+    cwd: "/fake/cwd",
+    agentDir: "/fake/agent",
+    skillDirs: [],
+    mainCwd: "/fake/cwd",
+    sessionRootId: "root-session-test",
+    rootCwd: "/fake/cwd",
+    ...overrides,
+  };
+}
+
+describe("worktree guidance prompt injection", () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    captured.content = "";
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("worktree 模式 → appendSystemPrompt content 含 worktree 认知纠正提示", async () => {
+    const record = makeRecord();
+    const opts = makeRunOpts({
+      worktree: {
+        path: "/tmp/pi-subagents/--fake--/pi-sub-sa-wt-guidance-1",
+        branch: "pi-sub-sa-wt-guidance-1",
+        baseCommit: "abc123",
+        mainCwd: "/fake/cwd",
+      },
+    });
+    const ctx = makeCtx();
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+
+    // content 含 WORKTREE_GUIDANCE_PROMPT 的标题
+    expect(captured.content).toContain("Git Worktree");
+    // 含关键纠正信息：cwd 含完整项目代码（非临时沙箱）
+    expect(captured.content).toContain("complete project source code");
+    // 含防 cd 别处的行为指引
+    expect(captured.content).toContain("Do NOT");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+
+  it("非 worktree 模式 → content 不含 worktree 认知提示", async () => {
+    const record = makeRecord();
+    const opts = makeRunOpts(); // 不传 worktree
+    const ctx = makeCtx();
+
+    const resultPromise = runSpawn(record, "test task", opts, ctx);
+    await waitForSpawn();
+
+    expect(captured.content).not.toContain("Git Worktree");
+
+    const child = getLastSpawnedChild();
+    child.emit("close", 0);
+    await resultPromise;
+  });
+});

package/src/execution/session-runner.ts

@@ -174,6 +174,30 @@ The \`ask_user\` tool is available in this session. When you call \`ask_user\`,
 - Use ask_user only when you genuinely cannot resolve ambiguity yourself (see tool description for guidelines)
 `.trim();
 
+/**
+ * worktree 模式注入子 agent 的认知纠正提示。
+ *
+ * 背景：worktree checkout 放在 os.tmpdir()（如 `/private/var/folders/.../pi-subagents/.../pi-sub-<id>`），
+ * 路径形似临时沙箱。子 agent system prompt 无任何 worktree 语义说明时，会误判 cwd 为
+ * "空隔离目录"，主动 cd 别处（如主 worktree）放弃隔离——实测见 wave-agent 事故
+ *（session 019ff64c T001 自述 cwd 是 pi 隔离目录，实际是合法 worktree checkout）。
+ *
+ * 此提示在 worktree 模式下注入，明确告知子 agent：cwd 是含完整项目代码的 git worktree，
+ * 直接在此工作即可，不要 cd 别处找"真正的项目"。
+ */
+export const WORKTREE_GUIDANCE_PROMPT = `
+## Working Directory Is a Git Worktree
+
+Your working directory (the "Working directory" in the environment block above) is a **dedicated git worktree** — an isolated checkout of the repository at HEAD, NOT a temporary sandbox. It contains the **complete project source code**.
+
+**You should:**
+- Work directly in your current cwd — it already has the full project (every file). Read project files via relative paths as usual.
+- To locate the shared repository root: \`git rev-parse --git-common-dir\`.
+- Your file changes are automatically captured as a patch when you finish — just do the work; no need to commit, push, or merge.
+
+**Do NOT** \`cd\` to another directory looking for "the real project" — your cwd IS the project. A path like \`/private/var/folders/.../pi-subagents/.../pi-sub-<id>\` is your worktree checkout, not an empty sandbox.
+`.trim();
+
 // ============================================================
 // 孤儿进程兜底（C1）
 // ============================================================
@@ -662,6 +686,11 @@ export async function runSpawn(
   if (opts.agentConfig?.tools?.includes("ask_user") && willRespondToAskUser(ctx.mode)) {
     appendParts.push(ASK_USER_RPC_PROMPT);
   }
+  // worktree 认知纠正：告知子 agent cwd 是 git worktree（非临时沙箱），含完整项目代码，
+  // 直接在此工作。防 wave-agent 类误判 cwd 为空隔离目录后 cd 主 worktree 放弃隔离。
+  if (opts.worktree) {
+    appendParts.push(WORKTREE_GUIDANCE_PROMPT);
+  }
   if (appendParts.length > 0) {
     tempPromptFile = await writePromptToTempFile(record.agent, appendParts.join("\n\n"));
   }