@zhushanwen/pi-subagent-workflow 2.0.1 → 4.0.0

package/agents/reviewer.md

@@ -2,7 +2,7 @@
 name: reviewer
 description: 代码审查 agent（diff 分析、问题发现）
 color: "#ef4444"
-tools: read
+tools: read, structured-output
 ---
 
 You are a code reviewer. Your role is to find bugs, logic errors, and security issues.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "2.0.1",
+  "version": "4.0.0",
   "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.",
@@ -40,7 +40,8 @@
     ]
   },
   "dependencies": {
-    "@xyz-agent/extension-protocol": "^0.2.0"
+    "@xyz-agent/extension-protocol": "^0.3.0",
+    "@zhushanwen/pi-extension-logger": "0.2.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",

package/skills/workflow-script-format/SKILL.md

@@ -54,7 +54,8 @@ const meta = { name: 'workflow-name', description: '...', phases: ['phase1', 'ph
 支持三种签名：
 - `agent(promptString)` — 最简，prompt 字符串，返回 content 字符串
 - `agent(promptString, { label?, schema?, ... })` — 字符串 + opts（`label` 是 `description` 的别名）
-- `agent({ prompt, schema?, description?, agent?, skill?, timeoutMs?, model?, scene? })` — 完整 opts 对象
+- `agent({ prompt, schema?, description?, agent?, skill?, timeoutMs?, model?, scene?, thinkingLevel? })` — 完整 opts 对象
+  - `thinkingLevel?` (`string`) — 思考强度，合法值 `off | minimal | low | medium | high | xhigh`，透传至 pi CLI 拼接为 `--model provider/modelId:thinkingLevel`（与 `model?` 同效，影响子 agent 推理预算）
 
 Returns `parsedOutput` (structured data when schema provided) or `content` (string).
 

package/src/execution/__tests__/agent-registry.test.ts

@@ -173,7 +173,7 @@ describe("createPackageBuiltinRegistry", () => {
     expect(builtin.get("orchestrator")?.tools).toEqual([
       "todo", "goal_control", "workflow", "subagent", "ask_user",
     ]);
-    expect(builtin.get("reviewer")?.tools).toEqual(["read"]);
+    expect(builtin.get("reviewer")?.tools).toEqual(["read", "structured-output"]);
     expect(builtin.get("planner")?.tools).toEqual(["read"]);
     expect(builtin.get("oracle")?.tools).toEqual(["read"]);
     expect(builtin.get("context-builder")?.tools).toEqual(["read"]);

package/src/execution/__tests__/channel-registry-handshake.test.ts

@@ -17,6 +17,19 @@
 
 import { afterEach, describe, expect, it, vi } from "vitest";
 
+// Mock 共享 logger，让 logger.warn 可被 spy（源码已从 console.warn 改为 logger.warn）
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+  },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => loggerMock,
+}));
+
 import {
   CHANNEL_HANDSHAKE_KEY,
   getOrCreateChannelRegistry,
@@ -31,6 +44,7 @@ function clearSlot(): void {
 
 afterEach(() => {
   clearSlot();
+  loggerMock.warn.mockClear();
 });
 
 /** 读取当前 slot（绕过本模块的 readHandshakeSlot，测试断言用）。 */
@@ -193,7 +207,7 @@ describe("getOrCreateChannelRegistry — 多条 pending flush 顺序与覆盖",
 describe("getOrCreateChannelRegistry — version 校验（向前兼容）", () => {
   it("version !== 1（如塞 {version:2,...}）→ warn + 重建为新 slot，旧 pending 数据丢弃", () => {
     clearSlot();
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    loggerMock.warn.mockClear();
     // 塞一个 version:2 的 slot，含旧数据
     const staleHandler = vi.fn();
     injectSlot({
@@ -205,7 +219,7 @@ describe("getOrCreateChannelRegistry — version 校验（向前兼容）", () =
     const registry = getOrCreateChannelRegistry();
 
     // warn 被调用
-    expect(warnSpy).toHaveBeenCalled();
+    expect(loggerMock.warn).toHaveBeenCalled();
     // 旧 pending 数据被丢弃（staleHandler 没被注册）
     expect(registry.resolve("ask_user")).toBeUndefined();
     // slot 被重建为 version:1，pending 为空
@@ -213,21 +227,17 @@ describe("getOrCreateChannelRegistry — version 校验（向前兼容）", () =
     expect(slot!.version).toBe(1);
     expect(slot!.pending).toEqual([]);
     expect(slot!.registry).toBe(registry);
-
-    warnSpy.mockRestore();
   });
 
   it("version !== 1 时 warn 消息包含 got/expected 字样", () => {
     clearSlot();
-    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    loggerMock.warn.mockClear();
     injectSlot({ version: 99 as unknown as 1, pending: [] });
 
     getOrCreateChannelRegistry();
 
-    const msg = warnSpy.mock.calls[0]?.[0] ?? "";
+    const msg = loggerMock.warn.mock.calls[0]?.[0] ?? "";
     expect(String(msg)).toMatch(/got/);
     expect(String(msg)).toMatch(/expected/);
-
-    warnSpy.mockRestore();
   });
 });

package/src/execution/__tests__/execute-and-await-worktree.test.ts

@@ -0,0 +1,219 @@
+// src/__tests__/execute-and-await-worktree.test.ts
+//
+// executeAndAwait 的 worktree 前置守卫 + 失败收尾测试（W1 code review 修复回归锁）。
+//
+// 覆盖两点：
+//   1. [MF#7] worktree:true && !fork 在任何副作用之前 fail-fast 抛错
+//   2. worktreeManager.create 抛错时 record 被 finalizeFailed（status→failed）且原错外抛
+//
+// ── mock 策略 ──
+//
+// 复用 execute-nesting.test.ts 的 spawn / node:fs / manifest-store / temp-prompt / alive-store
+// / finalized-marker mock 范式（见该文件头部详细注释）。本文件 **不驱动 FakeChild 完成**——
+// 被测的两个分支都在 runSpawn 之前抛/收尾（worktree create 在步骤 2.5，runSpawn 在步骤 5），
+// 因此 spawn 即使被调也无人驱动，测试在抛错后立即断言即可结束。
+//
+// worktreeManager 是 SubagentService 构造时 new 出的私有字段（WorktreeManager 实例，非模块）。
+// 测试 2 用 vi.spyOn(Reflect.get(service, "worktreeManager"), "create") 注入抛错，无需模块级 mock。
+
+import { PassThrough } from "node:stream";
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+// ── mock modules（与 execute-nesting.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", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("../alive-store.ts")>();
+  return {
+    ...actual,
+    writeAliveMarker: vi.fn(),
+    removeAliveMarker: vi.fn(),
+  };
+});
+
+vi.mock("../finalized-marker.ts", () => ({
+  writeFinalized: vi.fn(),
+  readFinalized: vi.fn(() => false),
+}));
+
+vi.mock("../manifest-store.ts", () => {
+  class FakeManifestStore {
+    writeManifest = vi.fn(async () => {});
+    readManifest = vi.fn(async () => null);
+    listAllSync = vi.fn(() => []);
+    recoverTmpFiles = vi.fn(async () => []);
+  }
+  return { ManifestStore: FakeManifestStore };
+});
+
+vi.mock("../temp-prompt.ts", () => ({
+  writePromptToTempFile: vi.fn(async (agent: string) => {
+    const safeName = agent.replace(/[^\w.-]+/g, "_");
+    return { dir: `/tmp/fake-${safeName}`, filePath: `/tmp/fake-${safeName}/prompt-${safeName}.md` };
+  }),
+  cleanupTempPrompt: vi.fn(async () => {}),
+}));
+
+import { ModelConfigService } from "../model-config-service.ts";
+import type { ModelInfo, ModelRegistryLike } from "../model-resolver.ts";
+import type { RecordStore } from "../record-store.ts";
+import type { WorktreeManager } from "../worktree-manager.ts";
+import { SubagentService } from "../subagent-service.ts";
+
+// ── 辅助：service 构造（与 execute-nesting.test.ts setup 等价）──
+
+function makeEmptyRegistry(): ModelRegistryLike {
+  return { getAvailable: () => [], find: () => undefined, hasConfiguredAuth: () => true };
+}
+
+function makePi() {
+  return { sendMessage: vi.fn(), appendEntry: vi.fn(), events: { emit: vi.fn() } };
+}
+
+interface SetupResult {
+  service: SubagentService;
+  worktreeManager: WorktreeManager;
+}
+
+function setup(): SetupResult {
+  const agentDir = "/tmp/exec-await-worktree-it"; // fs 已 mock，路径不需真实存在
+  const modelService = new ModelConfigService({ agentDir });
+  modelService.initModel({
+    modelRegistry: makeEmptyRegistry(),
+    sessionId: "exec-await-worktree-it",
+    ctxModel: { id: "m", name: "M", provider: "p", reasoning: false },
+  });
+  const service = new SubagentService({
+    cwd: agentDir,
+    modelService,
+    getMainSessionFile: () => "/mock/main-session.jsonl",
+  });
+  service.initSession({ pi: makePi(), sessionId: "exec-await-worktree-it" });
+  // worktreeManager 是 SubagentService 构造时 new 的 private 字段（无外部注入入口），
+  // 测试经 Reflect.get 访问后 cast 到生产导出类型 WorktreeManager（已在文件顶部 import），
+  // 让字段/方法签名与生产类型契约绑定。
+  const worktreeManager = Reflect.get(service, "worktreeManager") as WorktreeManager;
+  return { service, worktreeManager };
+}
+
+const ctxModel: ModelInfo = { id: "m", name: "M", provider: "p", reasoning: false };
+
+/**
+ * 从 service 取出 private store（断言 record 终态用）。
+ *
+ * worktreeManager 与 store 都是 SubagentService 构造时 new 出的 private 字段——
+ * 无外部注入入口，测试只能经 Reflect.get 访问。这里 cast 到生产导出类型
+ * （RecordStore / WorktreeManager）而非内联匿名 shape，让测试与生产类型契约绑定：
+ * 字段改名/签名变更时 tsc 立即报错（而非静默漂移）。
+ */
+function getStore(service: SubagentService): RecordStore {
+  return Reflect.get(service, "store") as RecordStore;
+}
+
+describe("executeAndAwait worktree 前置守卫 + 失败收尾", () => {
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  // ============================================================
+  // [MF#7] worktree:true && !fork → fail-fast 抛错（任何副作用之前）
+  // ============================================================
+  it("[MF#7] worktree:true 且 fork 未设时抛 'worktree:true requires fork:true'", async () => {
+    const { service } = setup();
+
+    // guard 在 BC-12 深度检查之后、步骤 1 之前——无需 fork:true，worktree:true 即触发。
+    // 传入完整 ExecuteOptions（补全 slug 必填字段），不再用 `as` 掩盖缺失字段——让缺字段在类型层可见。
+    await expect(
+      service.executeAndAwait({
+        task: "needs worktree without fork",
+        slug: "mf7-worktree-without-fork",
+        worktree: true,
+        fork: undefined,
+        ctxModel,
+      }),
+    ).rejects.toThrow(/worktree:true requires fork:true/);
+
+    // 无副作用：guard 在 createRecordForMode 之前 → store 无 running record。
+    expect(getStore(service).listRunning()).toHaveLength(0);
+  });
+
+  // ============================================================
+  // worktreeManager.create 抛错 → record 收尾为 failed + 原错外抛
+  // ============================================================
+  it("worktreeManager.create 失败时 finalizeFailed 收尾 record 并抛原错", async () => {
+    const { service, worktreeManager } = setup();
+
+    const createErr = new Error("worktree create boom");
+    vi.spyOn(worktreeManager, "create").mockImplementation(() => {
+      throw createErr;
+    });
+
+    // spy store.archive：finalizeFailed 真实收尾链（CAS→completeRecord→archive）的最末一步。
+    // 捕获传入 archive 的 record，断言其 status 已被推向 "failed"（证明 finalizeFailed 完整执行，
+    // 而非仅 tryTransition 中途返回）。archive 真实执行（不 mockImplementation）以保留移出 running map 的语义。
+    const store = getStore(service);
+    const archiveSpy = vi.spyOn(store, "archive");
+
+    await expect(
+      service.executeAndAwait({
+        task: "worktree create will fail",
+        slug: "worktree-create-fail",
+        worktree: true,
+        fork: true,
+        ctxModel,
+      }),
+    ).rejects.toBe(createErr);
+
+    // finalizeFailed 完整执行：record 经 CAS→completeRecord 推到 failed 终态后 archive。
+    expect(archiveSpy).toHaveBeenCalledTimes(1);
+    // store 现已强类型为 RecordStore → archive 入参为 ExecutionRecord，无需 `as` 断言。
+    const archivedRecord = archiveSpy.mock.calls[0]![0];
+    expect(archivedRecord.status).toBe("failed");
+    // archive 后 record 已移出 running map → listRunning 空、getMutable 取不到。
+    expect(store.listRunning()).toHaveLength(0);
+    expect(store.getMutable(archivedRecord.id)).toBeUndefined();
+  });
+});

package/src/execution/__tests__/finalize-record.test.ts

@@ -12,6 +12,19 @@ import * as os from "node:os";
 import * as path from "node:path";
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+// Mock 共享 logger，让 logger.error 可被 spy（源码已从 console.error 改为 logger.error）
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+  },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => loggerMock,
+}));
+
 import { doFinalizeRecord } from "../finalize-record.ts";
 import { ManifestStore } from "../manifest-store.ts";
 import type { AgentResult, ExecutionRecord } from "../types.ts";
@@ -129,7 +142,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
       finalizedBeforeManifestWrite.value = fs.existsSync(`${sessionFile}.finalized`);
       throw new Error("disk full");
     });
-    const consoleErrorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    loggerMock.error.mockClear();
 
     const deps = makeDeps();
 
@@ -147,9 +160,9 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     // ── 核心 claim 4：pending-notifications 注销仍触发（emitUnregister）──
     expect(deps.emitUnregister).toHaveBeenCalledWith("rec-cleanup-first", "done");
 
-    // ── 核心 claim 5：manifest 写失败被 console.error 记录（含 record id + error）──
-    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining("manifest 写入失败"));
-    const errMsg = consoleErrorSpy.mock.calls[0]?.[0];
+    // ── 核心 claim 5：manifest 写失败被 logger.error 记录（含 record id + error）──
+    expect(loggerMock.error).toHaveBeenCalledWith(expect.stringContaining("manifest 写入失败"));
+    const errMsg = loggerMock.error.mock.calls[0]?.[0];
     expect(errMsg).toContain("rec-cleanup-first");
     expect(errMsg).toContain("disk full");
 
@@ -167,7 +180,7 @@ describe("doFinalizeRecord — manifest status 透传 (M3 4 态)", () => {
     // .finalized 尚未被 Step 3 写入），保护 Critical #1 时序不变量。
     expect(finalizedBeforeManifestWrite.value).toBe(true);
 
-    // 清理 spy 防止污染其他测试
-    consoleErrorSpy.mockRestore();
+    // 清理 mock 调用记录防污染
+    loggerMock.error.mockClear();
   });
 });

package/src/execution/__tests__/stdin-writer.test.ts

@@ -21,6 +21,19 @@ import { PassThrough } from "node:stream";
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+// Mock 共享 logger，让 logger.warn 可被 spy（源码已从 console.warn 改为 logger.warn）
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+  },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => loggerMock,
+}));
+
 import { respond, sendGetStateCommand, sendPromptCommand } from "../stdin-writer.ts";
 
 // ── helpers ──
@@ -55,13 +68,13 @@ function readStdinLines(child: ChildProcess): unknown[] {
     .map((l) => JSON.parse(l));
 }
 
-let warnSpy: ReturnType<typeof vi.spyOn>;
+// vi.fn() 的返回类型原生含 .mock.calls——无需双重断言（ReturnType<typeof vi.fn> 已是强类型）。
+let warnSpy: ReturnType<typeof vi.fn>;
 
 beforeEach(() => {
-  // stdin-writer 在背压 / 序列化失败时 console.warn；测试 stub 避免 noise，且可断言调用。
-  // console.error（manifest 写失败路径）也 stub 静音，但测试不断言其调用。
-  warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
-  vi.spyOn(console, "error").mockImplementation(() => {});
+  // stdin-writer 在背压 / 序列化失败时 logger.warn；测试 mock logger 避免噪声，且可断言调用。
+  loggerMock.warn.mockClear();
+  warnSpy = loggerMock.warn;
 });
 
 afterEach(() => {

package/src/execution/__tests__/ui-request-observability.test.ts

@@ -14,12 +14,25 @@
 
 import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
+// Mock 共享 logger，让 logger.warn 可被 spy（源码已从 console.warn 改为 logger.warn）
+const { loggerMock } = vi.hoisted(() => ({
+  loggerMock: {
+    debug: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    info: vi.fn(),
+  },
+}));
+vi.mock("@zhushanwen/pi-extension-logger", () => ({
+  getLogger: () => loggerMock,
+}));
+
 import { UiRequestObservability } from "../ui-request-observability.ts";
 
 // ── 公共 fixture ──────────────────────────────────────────────
 
 beforeEach(() => {
-  vi.spyOn(console, "warn").mockImplementation(() => {});
+  loggerMock.warn.mockClear();
 });
 
 afterEach(() => {
@@ -57,17 +70,17 @@ describe("UiRequestObservability — notifyMissingHandler per-session 去重", (
     const obs = new UiRequestObservability();
     obs.notifyMissingHandler("s1");
     obs.notifyMissingHandler("s1");
-    expect(console.warn).toHaveBeenCalledTimes(1);
+    expect(loggerMock.warn).toHaveBeenCalledTimes(1);
   });
 
   it("warn 内容含 sessionId 和 mode（可观测性）", () => {
     const obs = new UiRequestObservability();
     obs.setMode("tui");
     obs.notifyMissingHandler("s1");
-    expect(console.warn).toHaveBeenCalledWith(
+    expect(loggerMock.warn).toHaveBeenCalledWith(
       expect.stringContaining("session=s1"),
     );
-    expect(console.warn).toHaveBeenCalledWith(
+    expect(loggerMock.warn).toHaveBeenCalledWith(
       expect.stringContaining("mode=tui"),
     );
   });
@@ -77,12 +90,12 @@ describe("UiRequestObservability — resetMissingHandlerWarnings 后可重新 wa
   it("notify(s1) → reset → notify(s1) → warn 被调 2 次", () => {
     const obs = new UiRequestObservability();
     obs.notifyMissingHandler("s1");
-    expect(console.warn).toHaveBeenCalledTimes(1);
+    expect(loggerMock.warn).toHaveBeenCalledTimes(1);
 
     obs.resetMissingHandlerWarnings();
 
     obs.notifyMissingHandler("s1");
-    expect(console.warn).toHaveBeenCalledTimes(2);
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
   });
 });
 
@@ -91,11 +104,11 @@ describe("UiRequestObservability — 不同 session 各自首次 warn", () => {
     const obs = new UiRequestObservability();
     obs.notifyMissingHandler("s1");
     obs.notifyMissingHandler("s2");
-    expect(console.warn).toHaveBeenCalledTimes(2);
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
 
     // 再次各自调用，已被去重，不再 warn
     obs.notifyMissingHandler("s1");
     obs.notifyMissingHandler("s2");
-    expect(console.warn).toHaveBeenCalledTimes(2);
+    expect(loggerMock.warn).toHaveBeenCalledTimes(2);
   });
 });

package/src/execution/agent-registry.ts

@@ -11,6 +11,8 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import {
   type DiscoveredResource,
   discoverResourcesSync,
@@ -18,6 +20,8 @@ import {
 } from "../shared/resource-discovery.ts";
 import type { AgentConfig } from "./model-resolver.ts";
 
+const logger = getLogger("subagents");
+
 /** 内置 agent（代码硬编码，如 default worker）。 */
 export interface BuiltinAgentRegistry {
   get(name: string): AgentConfig | undefined;
@@ -52,13 +56,17 @@ export function createPackageBuiltinRegistry(): BuiltinAgentRegistry {
       } catch (err) {
         // 单个 builtin agent 文件损坏不影响其他——降级跳过该文件。
         void err;
-        console.warn(`[subagents] skip malformed builtin agent: ${resource.path}`, err);
+        logger.warn(`[subagents] skip malformed builtin agent: ${resource.path}`, {
+          detail: err instanceof Error ? err.message : String(err),
+        });
       }
     }
   } catch (err) {
     // agents/ 目录不存在（打包遗漏）→ 空 builtin，不崩。
     void err;
-    console.warn("[subagents] builtin agents/ directory unreadable, falling back to empty set:", err);
+    logger.warn("[subagents] builtin agents/ directory unreadable, falling back to empty set", {
+      detail: err instanceof Error ? err.message : String(err),
+    });
   }
   return {
     get: (name) => cache.get(name),

package/src/execution/best-effort.ts

@@ -9,22 +9,30 @@
 //
 // 规则绕过原理：taste/no-silent-catch 仅检查 CatchClause 直接 body 是否为空或仅
 // console 调用。本 helper 是普通函数调用（ExpressionStatement），既非空也非仅
-// console，故合规。helper 函数体内部的 console 不被该规则检查。
+// console，故合规。helper 函数体内部经共享 logger 路由（不裸 console）。
+
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+const logger = getLogger("subagents");
 
 /** 错误日志级别。debug = 次要清理（默认）；error = 关键步骤但需继续后续清理。 */
 export type BestEffortLevel = "debug" | "error";
 
 /**
- * 吞咽 best-effort IO 的错误，按 level 记录到 console。
+ * 吞咽 best-effort IO 的错误，按 level 经共享 logger 记录。
  *
  *   - debug（默认）：次要清理（sidecar/worktree/alive marker），失败属预期路径
  *   - error：关键步骤抛错但需继续后续清理（如 finalizeRecord 的 B9 链：completeRecord
  *     抛错后仍要执行 finalized/cleanup，错误需可见但不阻断）
  *
- * 错误对象优先取 message（避免打印巨大堆栈/对象），其他类型原样打印。
+ * 错误对象优先取 message（避免打印巨大堆栈/对象），其他类型原样传入。
  */
 export function bestEffort(err: unknown, context: string, level: BestEffortLevel = "debug"): void {
   const detail = err instanceof Error ? err.message : err;
-  const fn = level === "error" ? console.error : console.debug;
-  fn(`[subagents] best-effort ${context} failed:`, detail);
+  const msg = `[subagents] best-effort ${context} failed`;
+  if (level === "error") {
+    logger.error(msg, { detail });
+  } else {
+    logger.debug(msg, { detail });
+  }
 }

package/src/execution/channel-registry-access.ts

@@ -24,8 +24,12 @@
 // handshake 形状： ChannelRegistryHandshake（version=1）
 // version 守卫：    slot.version !== 1 时 console.warn + 丢弃重建（向前兼容未来升级）
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import { createUiChannelRegistry, type UiChannelRegistry, type ChannelHandler } from "./ui-channels.ts";
 
+const logger = getLogger("subagents");
+
 /** 进程级 channel 握手的 globalThis key（Symbol.for 跨模块共享）。
  *
  *  **协议契约**：字面量 `"@zhushanwen/pi-subagents.channelHandshake"` 必须与
@@ -67,14 +71,14 @@ function readHandshakeSlot(): ChannelRegistryHandshake | undefined {
   if (slot === undefined) return undefined;
   // 形状校验：必须是对象且 version===1，否则视为不兼容
   if (typeof slot !== "object" || slot === null) {
-    console.warn(
+    logger.warn(
       "[pi-subagent-workflow] channel handshake slot is not an object; discarding and recreating.",
     );
     return undefined;
   }
   const version = (slot as { version?: unknown }).version;
   if (version !== HANDSHAKE_VERSION) {
-    console.warn(
+    logger.warn(
       `[pi-subagent-workflow] channel handshake version mismatch (got ${String(
         version,
       )}, expected ${HANDSHAKE_VERSION}); discarding and recreating.`,
@@ -84,7 +88,7 @@ function readHandshakeSlot(): ChannelRegistryHandshake | undefined {
   // version 正确，但 pending 可能被恶意/错误地塞了非数组；防御性处理
   const candidate = slot as ChannelRegistryHandshake;
   if (!Array.isArray(candidate.pending)) {
-    console.warn(
+    logger.warn(
       "[pi-subagent-workflow] channel handshake pending is not an array; discarding and recreating.",
     );
     return undefined;

package/src/execution/execute-options-mapper.ts

@@ -55,6 +55,8 @@ export function mapToExecuteOptions(
     schema: opts.schema,
     schemaEnv: opts.schemaEnv,
     cwd: opts.cwd,
+    fork: opts.fork,
+    worktree: opts.worktree,
     model: opts.model,
     ctxModel,
     skillPath: opts.skillPath,

package/src/execution/finalize-record.ts

@@ -16,6 +16,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
 import { removeAliveMarker } from "./alive-store.ts";
 import { bestEffort } from "./best-effort.ts";
 import { completeRecord } from "./execution-record.ts";
@@ -28,6 +30,8 @@ import { writeCancelledTombstone } from "./tombstone-store.ts";
 import type { AgentResult, ExecutionRecord } from "./types.ts";
 import type { WorktreeManager } from "./worktree-manager.ts";
 
+const logger = getLogger("subagents");
+
 /** doFinalizeRecord 的依赖（从 SubagentService 注入，避免 this 绑定 + 解耦可测试）。 */
 export interface FinalizeDeps {
   manifestStore: ManifestStore;
@@ -151,7 +155,7 @@ export async function doFinalizeRecord(
     });
   } catch (err) {
     const msg = err instanceof Error ? err.message : String(err);
-    console.error(`[subagent] manifest 写入失败 (record=${record.id}): ${msg}`);
+    logger.error(`[subagent] manifest 写入失败 (record=${record.id}): ${msg}`);
     deps.pi?.appendEntry?.("subagent:manifest-write-failed", {
       id: record.id,
       error: msg,