@zhushanwen/pi-subagent-workflow 7.3.1 → 7.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "7.3.1",
+  "version": "7.3.3",
   "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"));
   }
@@ -735,6 +764,26 @@ export async function runSpawn(
     // abortRunningControllers 跳过它，靠本 Set 兜底）。close/error 后移除（已退出无需再 kill）。
     spawnedChildren.add(child);
 
+    // [worktree-reaper-fix] 同步补全注册表 pid：spawn 返回后 child.pid 立即可得（Node.js
+    // 同步属性），无需等任何 stdout 事件。原补全点挂在 header 分支（下方 stdout handler 内），
+    // 而 RPC mode（buildSpawnArgs 固定 --mode rpc）不输出 header 行——pid 恒为 0，超
+    // SPAWN_GRACE_MS 后被 reaper 当孤儿误删活 worktree（2026-08-11 cw 递归编排整树失活事故）。
+    // header 分支调用保留：json mode 回切时仍能补全，updatePid 同 branch 覆盖写幂等，无副作用。
+    // [S1] 防御：必须放在 spawnedChildren.add 之后（onWorktreePid 抛错时子进程已被跟踪，
+    // dispose 兜底 kill 不会泄漏），且包 try/catch（补全失败不阻断 spawn 主流程——
+    // 注册表写失败最坏后果是条目停留 pid=0，由 reaper 宽限回收兜底）。
+    if (opts.worktree && child.pid) {
+      try {
+        ctx.onWorktreePid?.(opts.worktree.branch, child.pid);
+      } catch (err) {
+        logger.warn("[worktree] worktree pid registration failed (defensive)", {
+          branch: opts.worktree.branch,
+          pid: child.pid,
+          err: err instanceof Error ? err.message : String(err),
+        });
+      }
+    }
+
     // stdout/stderr 用 utf8 编码：stream 自动按字符边界切分，避免多字节
     // UTF-8（CJK/emoji）跨 chunk 时 toString() 产生 U+FFFD 替换符导致 JSON.parse 失败。
     // [m2] 先 setEncoding 再注册 signal listener/watchdog：若 setEncoding 抛错，try/finally
@@ -968,9 +1017,12 @@ export async function runSpawn(
         // [worktree-reaper-fix] 拼 spawnCwd 进错误消息：ENOENT 的 err.message 只含 command 名，
         // 无 cwd 线索（worktree 被 reaper 误删后 cwd 指向虚空）会导致误诊——2026-08-11 事故
         // AI 误判"node 被卸载"的直接原因。
+        // [S3] code 读取带运行时 guard：非 ErrnoException（普通 Error）时 code 为 undefined，
+        // 不加 cwd hint（行为与修复前一致）；仅 ENOENT 才拼 cwd。
         spawnedChildren.delete(child);
         const errno = err as NodeJS.ErrnoException;
-        const cwdHint = errno.code === "ENOENT" ? ` (cwd: ${spawnCwd})` : "";
+        const errCode = "code" in err ? errno.code : undefined;
+        const cwdHint = errCode === "ENOENT" ? ` (cwd: ${spawnCwd})` : "";
         record.lastError = `${err.message}${cwdHint}`;
         resolve(SIGNAL_EXIT_CODE_THRESHOLD); // 非零退出
       });

package/src/index.ts

@@ -14,7 +14,6 @@
  */
 
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 
 import type { ExtensionAPI, ExtensionContext, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
@@ -166,9 +165,10 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   }
 
   function resolveSessionDir(): string {
-    const defaultDir = path.join(os.homedir(), ".pi", "agent");
+    const defaultDir = getAgentDir();
     const sessionSlug = `--${process.cwd().replace(/^\//, "").replace(/\//g, "-")}--`;
-    const sessionScopedDir = path.join(os.homedir(), ".pi", "agent", "sessions", sessionSlug);
+    // F2：根改 getAgentDir() 派生（实例隔离）；保留 sessionScopedDir 存在则用之的探测语义
+    const sessionScopedDir = path.join(getAgentDir(), "sessions", sessionSlug);
     return fs.existsSync(sessionScopedDir) ? sessionScopedDir : defaultDir;
   }
 

package/src/interface/format.ts

@@ -310,6 +310,7 @@ export function formatToolCall(
   theme: ThemeLike,
 ): string {
   const shortenPath = (p: string): string => {
+    // 仅用于显示层路径缩写（~ 替换 home 前缀），不读取 pi 目录（TC9 合法命中）
     const home = os.homedir();
     return p.startsWith(home) ? `~${p.slice(home.length)}` : p;
   };

package/src/interface/views/WorkflowsView.ts

@@ -23,10 +23,10 @@
  */
 
 import { promises as fsPromises } from "node:fs";
-import { homedir } from "node:os";
 import { join as pathJoin } from "node:path";
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { Key, matchesKey } from "@earendil-works/pi-tui";
 
 import {
@@ -858,11 +858,11 @@ const TRACE_ACTIVITY_WIDTH = 80;
 
 /**
  * 导出完整 workflow trace 到 Markdown 文件。
- * 路径：~/.pi/agent/workflow-traces/{runId}.md
+ * 路径：<agentDir>/workflow-traces/{runId}.md（agentDir = getAgentDir()，实例隔离）
  * 对齐 main 的 saveTraceToFile（WorkflowsView.ts:365-396）。
  */
 function saveTraceToFile(run: WorkflowRun, ctx: ExtensionContext): void {
-  const dir = pathJoin(homedir(), ".pi", "agent", "workflow-traces");
+  const dir = pathJoin(getAgentDir(), "workflow-traces");
   const filePath = pathJoin(dir, `${run.runId}.md`);
   const lines: string[] = [];
   lines.push(`# Workflow Trace: ${run.spec.scriptName} (${run.runId})`, "");

package/src/orchestration/skill-discovery.ts

@@ -6,9 +6,10 @@
  */
 
 import * as fs from "node:fs";
-import * as os from "node:os";
 import * as path from "node:path";
 
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
 // ── Skill path resolution (with npm dir cache) ─────────────────────
 
 const skillCandidatesCache = new Map<string, string[]>();
@@ -32,8 +33,9 @@ function getNpmSkillCandidates(npmSkillsDir: string): string[] {
  * Resolve a skill name to its directory or SKILL.md path.
  * Search order:
  * 1. Project-level: .agents/skills/<name>/
- * 2. Global: ~/.pi/agent/skills/<name>/
- * 3. npm packages: ~/.pi/agent/npm/node_modules/<pkg>/skills/<name>/
+ * 2. Global: <agentDir>/skills/<name>/（agentDir = getAgentDir()，实例隔离：
+ *    PI_CODING_AGENT_DIR 场景读隔离目录，不碰 ~/.pi/agent）
+ * 3. npm packages: <agentDir>/npm/node_modules/<pkg>/skills/<name>/
  * Returns the directory path if found, undefined otherwise.
  */
 export function resolveSkillPath(skillName: string): string | undefined {
@@ -41,11 +43,11 @@ export function resolveSkillPath(skillName: string): string | undefined {
  // Project-level
     path.resolve(process.cwd(), ".agents/skills", skillName),
  // Global user skills
-    path.join(os.homedir(), ".pi/agent/skills", skillName),
+    path.join(getAgentDir(), "skills", skillName),
   ];
 
  // npm package skills (cached)
-  const npmSkillsDir = path.join(os.homedir(), ".pi/agent/npm/node_modules");
+  const npmSkillsDir = path.join(getAgentDir(), "npm/node_modules");
   for (const pkgSkillsBase of getNpmSkillCandidates(npmSkillsDir)) {
     candidates.push(path.join(pkgSkillsBase, skillName));
   }