@zhushanwen/pi-subagent-workflow 8.6.0 → 8.8.0

package/README.md

@@ -4,7 +4,7 @@ Pi 的 subagent + workflow 合并包：任务委派 + 多 agent 编排（chain /
 
 ## 内置 Agents
 
-按「读/写 × 视角」正交切分，9 个角色零重叠：
+按「读/写 × 视角」正交切分，10 个角色零重叠（C1 起随 `@zhushanwen/subagent-core` 的 `agents/` 资产分发，`<available_subagents>` 的 `<location>` 指向 core 包目录）：
 
 | Agent | 角色 | 读/写 |
 |-------|------|-------|
@@ -12,6 +12,7 @@ Pi 的 subagent + workflow 合并包：任务委派 + 多 agent 编排（chain /
 | `planner` | 复杂任务拆解为有序实施计划（合并需求澄清） | 只读产文档 |
 | `coder` | 代码实现、修改、测试（唯一改代码的角色） | 可改 |
 | `reviewer` | 代码审查与需求验收（含 git diff） | 只读 |
+| `doc-reviewer` | 文档审查（四遍方法论，事实锚点核实；spec / 设计文档） | 只读 |
 | `debugger` | 运行时故障诊断，钉根因 | 只读* |
 | `analyst` | 深度项目分析，产出给人读的报告 | 只读 |
 | `researcher` | 外部资料调研（依赖 tavily skill） | 只读 |
@@ -30,19 +31,12 @@ Pi 的 subagent + workflow 合并包：任务委派 + 多 agent 编排（chain /
 
 ## Orchestrator 协调器模式
 
-主 agent 禁用 bash / read / write / edit 等执行工具，只保留协调类工具，被迫作为纯协调器：拆解任务 → 委派 subagent → 汇总结果。orchestrator agent 自身也可递归委派子 orchestrator，实现分层任务拆解（深度受 `Depth: N/10` 护栏保护）。
+orchestrator 是纯协调器角色：拆解任务 → 委派 subagent → 汇总结果，自身不做执行类工作。orchestrator agent 自身也可递归委派子 orchestrator，实现分层任务拆解（深度受 `Depth: N/10` 护栏保护）。
 
-可用工具 5 个：`todo`、`goal_control`、`workflow`、`subagent`、`ask_user`（`ask_user` 由 `@zhushanwen/pi-ask-user` 提供，未安装时 orchestrator 遇歧义会明示停止而非猜测）。
-
-### 启动命令
+**工具约束变化（C1/D-5）**：内置模板不再携带 `tools:` frontmatter 白名单，subagent 不再以 `--tools` 白名单启动——工具约束回归宿主默认工具面，orchestrator 靠角色职责（职责边界段）约束自身只做协调。想要白名单的用户在 `<workspace>/.agents/agents/` 放同名 `.md` 覆写（project 级源稳定遮蔽内置，是唯一逃生门），或沿用 pi CLI 的 `--tools` 白名单（临时验证）：
 
 ```bash
-# 方式一：CLI 工具白名单（临时验证最快）
 pi --tools todo,goal_control,workflow,subagent,ask_user
-
-# 方式二：白名单 + 注入 orchestrator 的 system prompt（推荐，主进程也具备协调器视角）
-pi --tools todo,goal_control,workflow,subagent,ask_user \
-   --append-system-prompt "$(cat ~/.pi/agent/npm/node_modules/@zhushanwen/pi-subagent-workflow/agents/orchestrator.md)"
 ```
 
 > **依赖**：需先安装本包及相关扩展
@@ -59,7 +53,7 @@ pi --tools todo,goal_control,workflow,subagent,ask_user \
 
 ## Workflow 生命周期（one-shot）
 
-Workflow run 是一次性执行，状态机两态：`running → done`（`done` 唯一终态，reason 区分 completed / aborted / failed / budget_limited / time_limited）。`workflow` tool 仅 3 个 action：`run` / `status` / `abort`。
+Workflow run 是一次性执行，状态机两态：`running → done`（`done` 唯一终态，reason 区分 completed / aborted / failed / budget_limited / time_limited）。`workflow` tool 仅 3 个 action：`run` / `status` / `abort`。run 的 `name` 接受 `<available_workflows>` 列出的 workflow 名（内置 chain / parallel / map-reduce / scatter-gather / review-fix-loop 或已保存脚本）或 `.js` 绝对路径。
 
 Runs are one-shot: there is no pause/resume — to stop a run early use abort; for a fresh result start a new run.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhushanwen/pi-subagent-workflow",
-  "version": "8.6.0",
+  "version": "8.8.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.",
@@ -19,17 +19,14 @@
   },
   "files": [
     "index.ts",
-    "agents/",
     "skills/",
-    "workflows/",
     "scripts/",
     "relay/",
     "src/index.ts",
-    "src/execution/",
+    "src/jsonl-run-store.ts",
+    "src/host/",
     "src/injectors/",
-    "src/orchestration/",
-    "src/interface/",
-    "src/shared/"
+    "src/interface/"
   ],
   "xyz-agent": {
     "role": "universal",
@@ -53,26 +50,22 @@
     ],
     "skills": [
       "./skills"
-    ],
-    "agents": [
-      "./agents"
     ]
   },
   "dependencies": {
-    "ajv": "^8.20.0",
-    "yaml": "^2.9.0",
-    "@xyz-agent/extension-protocol": "0.7.0",
     "@xyz-agent/session-delivery": "0.3.0",
-    "@zhushanwen/pi-extension-logger": "0.3.0",
-    "@zhushanwen/pi-file-lock": "0.1.2"
+    "@zhushanwen/pi-ext-guards": "0.2.0",
+    "@zhushanwen/pi-extension-logger": "0.4.0",
+    "@xyz-agent/extension-protocol": "0.8.0",
+    "@zhushanwen/subagent-core": "0.4.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "^0.84.1",
-    "@earendil-works/pi-coding-agent": "^0.84.1",
-    "@earendil-works/pi-tui": "^0.84.1",
+    "@earendil-works/pi-ai": "^0.84.4",
+    "@earendil-works/pi-coding-agent": "^0.84.4",
+    "@earendil-works/pi-tui": "^0.84.4",
     "typebox": "*",
-    "@zhushanwen/pi-pending-notifications": "0.5.0",
-    "@zhushanwen/pi-structured-output": "5.1.0"
+    "@zhushanwen/pi-structured-output": "5.1.2",
+    "@zhushanwen/pi-pending-notifications": "0.5.2"
   },
   "peerDependenciesMeta": {
     "@earendil-works/pi-coding-agent": {

package/relay/relay.mjs

@@ -8,7 +8,7 @@
  * 通道，payload 一律 base64 封装保字节精确。
  *
  * ============================ 镜像常量表 ============================
- * SSOT = src/execution/relay-env.ts（零依赖脚本不能 import workspace 包，只能内嵌镜像；
+ * SSOT = packages/subagent-core/src/execution/relay-env.ts（零依赖脚本不能 import workspace 包，只能内嵌镜像；
  * 改名/改值必须双侧同步，一致性由 E-3 conformance relay 变体断言锁定——设计 §10-5）：
  *
  *   | relay-env.ts 常量         | 本文件常量                | 值                          |

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

@@ -39,13 +39,22 @@ This is enforced by `lintScript`:
 
 ## Required: Meta Declaration
 
-Every script MUST declare `meta` at the top level:
+Every script MUST declare its metadata as a `/* @pi-meta */` YAML block comment at the top level — NOT a `const meta` variable:
 
 ```javascript
-const meta = { name: 'workflow-name', description: '...', phases: ['phase1', 'phase2'] };
+/* @pi-meta
+name: workflow-name
+description: One-line description of what the workflow does
+phases: ['phase1', 'phase2']
+*/
 ```
 
-`name` must match the filename stem. `phases` is for display only.
+- `name` must match the filename stem. `phases` is for display only.
+- Optional fields: `parameters` (JSON Schema for `$ARGS`) and `usage` (markdown).
+- The YAML body starts on the line after `/* @pi-meta`; the closing `*/` must sit alone at column 0.
+- `generate` round-trip-validates the YAML and reports line/col on error (common pitfall: patternProperties regex must use double backslash `\\d`, not `\d`).
+
+> **Legacy `const meta = { ... }` (transition only):** `generate` still accepts a legacy top-level `const meta` during the transition window, but the core discovery chain does NOT recognize it (no legacy fallback) — such scripts stay invisible to discovery and get no metadata injection. Always use `/* @pi-meta */` for new scripts.
 
 ## [MANDATORY] Display: description + phase
 
@@ -59,11 +68,11 @@ TUI `/workflows` 视图按**运行时 `phase()` 调用**分组（非 `meta.phase
 ### Minimal 示例（三者齐备）
 
 ```javascript
-const meta = {
-  name: 'review-fix',
-  description: 'review then fix',
-  phases: ['review', 'fix'],
-};
+/* @pi-meta
+name: review-fix
+description: review then fix
+phases: ['review', 'fix']
+*/
 
 phase('review');
 const r = await agent({ prompt: 'review diff', description: 'review-diff' });
@@ -79,11 +88,17 @@ return { done: true };
 // ❌ agent() 无 description → TUI 显示 unnamed agent
 await agent({ prompt: 'review diff' });
 
-// ❌ meta.phases 用对象数组 → 引擎忽略，全部归入 (unnamed)
-const meta = { name: 'x', phases: [{ title: 'review' }, { title: 'fix' }] };
+// ❌ phases 用对象数组 → 引擎忽略，全部归入 (unnamed)
+/* @pi-meta
+name: x
+phases: [{ title: 'review' }, { title: 'fix' }]
+*/
 
 // ❌ 声明了 phases 但从不 phase() 调用 → 运行时分组失效
-const meta = { name: 'x', phases: ['review', 'fix'] };
+/* @pi-meta
+name: x
+phases: ['review', 'fix']
+*/
 // ... 直接 await agent(...) 从不调 phase('review') / phase('fix')
 ```
 
@@ -201,7 +216,7 @@ const results = await parallel(
 );
 ```
 
-> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/universal/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
+> 内置通用编排 workflow（chain / parallel / scatter-gather / map-reduce / review-fix-loop，可直接 `workflow run`，用 `agent()` 自包含实现）见 `extensions/universal/subagent-workflow/workflows/`。本段教 `workflow()` 嵌套 API，workflows 目录是开箱即用的通用编排工具（用 `agent()` 而非 `workflow()` 嵌套）。
 
 ### Other globals
 
@@ -249,7 +264,11 @@ agent({ prompt: '...', description: 'review-business-logic' });
 ## Complete Example
 
 ```javascript
-const meta = { name: 'review-fix-loop', description: 'Loop: review → fix → commit until clean', phases: ['review-fix'] };
+/* @pi-meta
+name: review-fix-loop
+description: "Loop: review → fix → commit until clean"
+phases: ['review-fix']
+*/
 
 const MAX_ROUNDS = 10;
 let round = 0;

package/src/host/__tests__/pi-host.test.ts

@@ -0,0 +1,235 @@
+// pi-host.test.ts —— pi 壳宿主实现与现行为等价（u0-wire 验收①）。
+//
+// 三视角：①使用者——discoveryRoots 各 kind 的根清单/顺序/source 标签与
+// resource-discovery.ts buildScanTargets（user-pi/npm/npm-dev 段）、
+// skill-discovery.ts resolveSkillPath（skills 两根）现推导逐项一致；
+// ②构建者——dataRoot/log/countActiveFromEntries/createDelivery 四端口桥接形态；
+// ③观察者——getAgentDir 每次现取（PI_CODING_AGENT_DIR 实例隔离切换后重取生效，
+// 无模块级缓存）。
+//
+// mock 策略：pi SDK / pi 宿主协作件全部 vi.mock 工厂覆盖（vitest alias 的
+// mocks/ 桩只供其他测试族用，本文件需要可控返回值）。pending-notifications
+// mock 返回 {count: n} 形状直接验证「适配读 .count」；session-delivery mock
+// 验证 createDelivery 透传（参数 + 返回句柄）。
+
+import { join, dirname } from "node:path";
+import { createRequire } from "node:module";
+import { existsSync } from "node:fs";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+// ── hoisted mocks（vi.mock 工厂 hoisting 不能引用外部 let/const） ──
+
+const piCodingAgentMock = vi.hoisted(() => ({
+  // 与实装版 getAgentDir 的 env 契约一致（PI_CODING_AGENT_DIR 实例隔离优先），
+  // 使「env 切换后重取生效」可直接断言；缺省值仅作 fallback。
+  getAgentDir: vi.fn(() => process.env.PI_CODING_AGENT_DIR ?? "/mock/default/agent-dir"),
+}));
+
+const extensionLoggerMock = vi.hoisted(() => ({
+  getLogger: vi.fn(),
+}));
+
+const pendingNotificationsMock = vi.hoisted(() => ({
+  countActiveFromEntries: vi.fn(),
+}));
+
+const sessionDeliveryMock = vi.hoisted(() => ({
+  createDelivery: vi.fn(),
+}));
+
+vi.mock("@earendil-works/pi-coding-agent", () => piCodingAgentMock);
+vi.mock("@zhushanwen/pi-extension-logger", () => extensionLoggerMock);
+vi.mock("@zhushanwen/pi-pending-notifications", () => pendingNotificationsMock);
+vi.mock("@xyz-agent/session-delivery", () => sessionDeliveryMock);
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
+import { createDelivery } from "@xyz-agent/session-delivery";
+
+import { createPiHostServices, createPiNotifyDomainPorts } from "../pi-host.ts";
+
+beforeEach(() => {
+  vi.mocked(getAgentDir).mockClear();
+  vi.mocked(getLogger).mockReset();
+  vi.mocked(countActiveFromEntries).mockReset();
+  vi.mocked(createDelivery).mockReset();
+  delete process.env.PI_CODING_AGENT_DIR;
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  delete process.env.PI_CODING_AGENT_DIR;
+});
+
+describe("createPiHostServices.discoveryRoots（与现推导逐项一致）", () => {
+  // 基线锚点：resource-discovery.ts buildScanTargets（join(agentDir, kind) /
+  // join(agentDir, "npm", "node_modules") / join(agentDir, "extensions")）与
+  // skill-discovery.ts resolveSkillPath（join(getAgentDir(), "skills") +
+  // join(getAgentDir(), "npm/node_modules")）。根列表按优先级低→高排列（D2）。
+  const AGENT_DIR = "/fake/agent-dir";
+
+  function stubAgentDir(): void {
+    vi.mocked(getAgentDir).mockReturnValue(AGENT_DIR);
+  }
+
+  it("agents 四根：user-pi → npm → npm-dev → core 包父目录（C5⑥，source npm 追加末位）", () => {
+    stubAgentDir();
+    const roots = createPiHostServices().discoveryRoots?.().agents;
+
+    // 期望的 core 注入根用与 pi-host.ts 相同的锚点解析（./workflows/* 子入口在
+    // workspace 与 npm dist 双形态同径；探针证据见 probe-c5.md P1/P3）
+    const require = createRequire(import.meta.url);
+    const anchor = require.resolve("@zhushanwen/subagent-core/workflows/README.md");
+    const coreParent = dirname(dirname(dirname(anchor)));
+
+    expect(roots).toEqual([
+      { dir: join(AGENT_DIR, "agents"), source: "user-pi" },
+      { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
+      { dir: join(AGENT_DIR, "extensions"), source: "npm-dev" },
+      // C5⑥：core 包一级父目录（npm 槽语义：一级子项 = 包目录，无 pi manifest 扫
+      // agents/ 约定目录）；追加在既有 npm 根之后——同标签靠后者胜（新版遮蔽旧残留）
+      { dir: coreParent, source: "npm" },
+    ]);
+  });
+
+  it("agents 第 4 根指向 core 包的父目录（其下 subagent-core/agents/ 存在 10 内置角色）", () => {
+    stubAgentDir();
+    const roots = createPiHostServices().discoveryRoots?.().agents;
+    const coreRoot = roots?.[3];
+
+    expect(coreRoot?.source).toBe("npm");
+    // 便捷断言：core 包根（注入 dir 的子目录）下 agents/ 真实存在
+    expect(existsSync(join(coreRoot!.dir, "subagent-core", "agents"))).toBe(true);
+  });
+
+  it("workflows 三根：与 agents 同构，末级目录名切换为 workflows", () => {
+    stubAgentDir();
+    const roots = createPiHostServices().discoveryRoots?.().workflows;
+
+    expect(roots).toEqual([
+      { dir: join(AGENT_DIR, "workflows"), source: "user-pi" },
+      { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
+      { dir: join(AGENT_DIR, "extensions"), source: "npm-dev" },
+    ]);
+  });
+
+  it("skills 两根：user-pi + npm，无 npm-dev（对齐 skill-discovery 现状）", () => {
+    stubAgentDir();
+    const roots = createPiHostServices().discoveryRoots?.().skills;
+
+    expect(roots).toEqual([
+      { dir: join(AGENT_DIR, "skills"), source: "user-pi" },
+      { dir: join(AGENT_DIR, "npm", "node_modules"), source: "npm" },
+    ]);
+  });
+
+  it("每次调用现取 getAgentDir（agentDir 变更后根列表跟随，不缓存）", () => {
+    stubAgentDir();
+    const first = createPiHostServices().discoveryRoots?.().agents;
+    const secondCallDir = "/another/agent-dir";
+    vi.mocked(getAgentDir).mockReturnValue(secondCallDir);
+    const second = createPiHostServices().discoveryRoots?.().agents;
+
+    expect(second?.[0].dir).toBe(join(secondCallDir, "agents"));
+    expect(first?.[0].dir).not.toBe(second?.[0].dir);
+  });
+});
+
+describe("createPiHostServices.dataRoot（每次现取 getAgentDir）", () => {
+  it("返回 getAgentDir() 本身（env 覆盖段与 warn-once 留 core data-dir）", () => {
+    vi.mocked(getAgentDir).mockReturnValue("/data/root");
+    expect(createPiHostServices().dataRoot()).toBe("/data/root");
+  });
+
+  it("PI_CODING_AGENT_DIR 切换后重取生效（实例隔离，无模块级缓存）", () => {
+    // 恢复 mock 工厂的 env 语义实现（其他用例的 mockReturnValue 会覆盖它）
+    vi.mocked(getAgentDir).mockImplementation(
+      () => process.env.PI_CODING_AGENT_DIR ?? "/mock/default/agent-dir",
+    );
+    process.env.PI_CODING_AGENT_DIR = "/instance-a";
+    const host = createPiHostServices();
+    expect(host.dataRoot()).toBe("/instance-a");
+
+    process.env.PI_CODING_AGENT_DIR = "/instance-b";
+    expect(host.dataRoot()).toBe("/instance-b");
+  });
+
+  it("透传 getAgentDir 调用（不缓存结果、不吞调用）", () => {
+    vi.mocked(getAgentDir).mockReturnValue("/d1");
+    const host = createPiHostServices();
+    host.dataRoot();
+    host.dataRoot();
+    expect(vi.mocked(getAgentDir)).toHaveBeenCalledTimes(2);
+  });
+});
+
+describe("createPiHostServices.log（桥接 pi-extension-logger）", () => {
+  function stubLogger(): { debug: ReturnType<typeof vi.fn>; warn: ReturnType<typeof vi.fn>; error: ReturnType<typeof vi.fn> } {
+    const fake = { debug: vi.fn(), warn: vi.fn(), error: vi.fn() };
+    vi.mocked(getLogger).mockReturnValue(fake);
+    return fake;
+  }
+
+  it("debug level → logger.debug，(message, data) 透传", () => {
+    const fake = stubLogger();
+    createPiHostServices().log("debug", "subagents", "d-msg", { k: 1 });
+
+    expect(vi.mocked(getLogger)).toHaveBeenCalledWith("subagents");
+    expect(fake.debug).toHaveBeenCalledWith("d-msg", { k: 1 });
+    expect(fake.warn).not.toHaveBeenCalled();
+    expect(fake.error).not.toHaveBeenCalled();
+  });
+
+  it("warn level → logger.warn；error level → logger.error", () => {
+    const fake = stubLogger();
+    const host = createPiHostServices();
+
+    host.log("warn", "comp-a", "w-msg");
+    host.log("error", "comp-b", "e-msg", { reason: "x" });
+
+    expect(fake.warn).toHaveBeenCalledWith("w-msg", undefined);
+    expect(fake.error).toHaveBeenCalledWith("e-msg", { reason: "x" });
+    expect(vi.mocked(getLogger)).toHaveBeenNthCalledWith(1, "comp-a");
+    expect(vi.mocked(getLogger)).toHaveBeenNthCalledWith(2, "comp-b");
+  });
+});
+
+describe("createPiNotifyDomainPorts.countActiveFromEntries（适配读 .count）", () => {
+  it("拆 CountActiveResult.count 为 number（core 端口契约），entries 透传", () => {
+    const entries: unknown[] = [{ customType: "pending:register" }];
+    vi.mocked(countActiveFromEntries).mockReturnValue({ count: 3, ids: ["a", "b", "c"], entries: [] });
+
+    const result = createPiNotifyDomainPorts().countActiveFromEntries?.(entries);
+
+    expect(result).toBe(3);
+    expect(vi.mocked(countActiveFromEntries)).toHaveBeenCalledWith(entries);
+  });
+
+  it("零活跃返回 0（{count: 0} 形状）", () => {
+    vi.mocked(countActiveFromEntries).mockReturnValue({ count: 0, ids: [], entries: [] });
+    expect(createPiNotifyDomainPorts().countActiveFromEntries?.([])).toBe(0);
+  });
+});
+
+describe("createPiNotifyDomainPorts.createDelivery（透传 session-delivery）", () => {
+  it("参数透传 + 返回句柄透传（不经包装）", () => {
+    const fakePort = {
+      supportedPayloads: ["text"] as const,
+      isIdle: () => true,
+      hasPendingMessages: () => false,
+      send: () => undefined,
+    };
+    const fakeConfig = { intent: "after-run" as const };
+    const fakeHandle = { send: () => {}, flush: () => {}, dispose: () => {} };
+    vi.mocked(createDelivery).mockReturnValue(fakeHandle);
+
+    const result = createPiNotifyDomainPorts().createDelivery?.(fakePort, fakeConfig);
+
+    expect(vi.mocked(createDelivery)).toHaveBeenCalledTimes(1);
+    expect(vi.mocked(createDelivery).mock.calls[0][0]).toBe(fakePort);
+    expect(vi.mocked(createDelivery).mock.calls[0][1]).toBe(fakeConfig);
+    expect(result).toBe(fakeHandle);
+  });
+});

package/src/host/pi-host.ts

@@ -0,0 +1,163 @@
+// src/host/pi-host.ts
+//
+// pi 壳宿主实现（subagent-core 包抽离 u0-wire）。设计权威源：
+// docs/design/subagent-core-package-extraction.md §3.3 D2（含计划期契约细化 3 条）。
+//
+// 本文件属壳侧（shell），不进 core 切面——对 pi SDK 与 pi 宿主协作件
+// （@earendil-works/pi-coding-agent / @zhushanwen/pi-extension-logger /
+// @zhushanwen/pi-pending-notifications / @xyz-agent/session-delivery）的运行时
+// import 收敛在此层，core 闭包（D9 守卫对象）不得出现这些包。
+//
+// 端口语义：
+//   - dataRoot / discoveryRoots 每次调用现取 getAgentDir()，禁止模块级缓存：
+//     getAgentDir 尊重 PI_CODING_AGENT_DIR 实例隔离（xyz-agent 按 session dir
+//     隔离 pi 实例），缓存会把后续切换实例的进程钉死在首个 agentDir。
+//   - discoveryRoots 的根清单/顺序/source 标签与 shared/resource-discovery.ts
+//     buildScanTargets、orchestration/skill-discovery.ts resolveSkillPath 的现推导
+//     逐项一致（user-pi / npm / npm-dev 字面即现 ResourceSource 标签）。
+//     project/workspace 根不在壳侧提供——core 消费方按 workspaceRoot 自行推导
+//     （u0-data-discovery 波次接注入消费）。C5⑥ 起 agents kind 追加第 4 根：
+//     core 包一级父目录（source "npm"）——core agents/ 资产进 pi 发现面，见
+//     corePackageNpmRoot 注释。
+//   - countActiveFromEntries 适配：pi 侧真函数返回 CountActiveResult 对象，core
+//     端口契约是 number（core 消费面只读 .count，notify-ports.ts 契约注释）——
+//     foundation 单元登记给本单元的适配责任。
+//   - createDelivery 透传：@xyz-agent/session-delivery 的 createDelivery 与 core
+//     的 Delivery* 结构化类型逐字段结构兼容（DeliveryHandle 的 sendChecked/depth
+//     是结构超集成员，多不碍兼容）——结构兼容由本注入点 typecheck 守护，上游签名
+//     漂移即红（notify-ports.ts「闭包红线」段）。
+
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+import { countActiveFromEntries } from "@zhushanwen/pi-pending-notifications";
+import { createDelivery } from "@xyz-agent/session-delivery";
+
+import type { DiscoveryRoot, HostServices } from "@zhushanwen/subagent-core/core/host-services.ts";
+import type { LogLevel } from "@zhushanwen/subagent-core/core/logger.ts";
+import type { NotifyDomainPorts } from "@zhushanwen/subagent-core/core/notify-ports.ts";
+
+/**
+ * core 包（@zhushanwen/subagent-core）agents/ 资产进 pi 发现面的注入根（C5⑥，
+ * convergence §5.4 检查点 2；探针证据 docs/design/subagent-core-convergence.probe-c5.md）。
+ *
+ * 解析锚点 = `@zhushanwen/subagent-core/workflows/README.md`：`./workflows/*` 子入口
+ * 在 workspace TS 直引与 npm dist 两种发布形态下同径（publishConfig 保留该子入口），
+ * README.md 是两形态都必在的资产文件。core 包根 = 锚点上两级；npm 槽注入其一级
+ * 父目录——npm 槽语义：dir 下一级子项 = 包目录，core 无 pi manifest → 扫 agents/
+ * 约定目录命中 10 内置角色。
+ *
+ * 布局覆盖（探针 P2-P5 实测）：dev workspace（core 在仓库 packages/ 下）与发布态
+ * 嵌套布局（core 在本包 node_modules 内）下这是唯一命中通路；发布态平铺布局
+ * （core 与本包同层）下既有 npm 根已命中，本注入是幂等兜底（重复发现被 core
+ * realpath 去重吸收）。
+ *
+ * 每次调用现解析（不 memo）：发现调用点稀疏（session_start + 缓存 miss），解析
+ * 成本可忽略；失败（异常布局/解析器不可用）降级为不注入并 warn——绝不因资产
+ * 接线失败阻断发现主链。
+ */
+function corePackageNpmRoot(): string | undefined {
+  try {
+    // createRequire 锚定本模块（jiti 加载器下 import.meta.url 可用；不可用则随
+    // catch 降级）。require.resolve 沿 pi-sw 自身的依赖解析链——workspace 与发布态
+    // 都从本包出发命中 core。
+    const require = createRequire(import.meta.url);
+    const anchor = require.resolve("@zhushanwen/subagent-core/workflows/README.md");
+    return dirname(dirname(dirname(anchor)));
+  } catch (err) {
+    // getLogger 惰性调用（catch 是冷路径——测试环境对 pi-extension-logger 的
+    // module-level mock 可能返回 undefined，模块级持有会在 import 期踩 undefined）
+    getLogger("pi-host").warn(
+      "[pi-host] core 包 agents/ 注入根解析失败——10 内置角色可能不可发现",
+      { reason: err instanceof Error ? err.message : String(err) },
+    );
+    return undefined;
+  }
+}
+
+/** agents/workflows 共享的 agentDir 派生根（末级目录名由 kind 决定）。
+ *  顺序与 source 标签逐项对齐 resource-discovery.ts buildScanTargets 的
+ *  user-pi → npm → npm-dev 段（根列表按优先级低→高排列，D2 语义边界）。 */
+function agentDirKindRoots(kind: "agents" | "workflows"): DiscoveryRoot[] {
+  const agentDir = getAgentDir();
+  const roots: DiscoveryRoot[] = [
+    // 1. user .pi/agent/<kind>/
+    { dir: join(agentDir, kind), source: "user-pi" },
+    // 2. npm global: agentDir/npm/node_modules/*/<pkg>/
+    { dir: join(agentDir, "npm", "node_modules"), source: "npm" },
+    // 3. npm dev symlink: agentDir/extensions/*/<pkg>/
+    { dir: join(agentDir, "extensions"), source: "npm-dev" },
+  ];
+  // 4. core 包根（C5⑥，仅 agents kind）：追加在既有 npm 根之后——同标签多根依注入
+  //    序扫描 + last-writer-wins，core（随本包依赖分发的新模板）遮蔽同 agentDir 内
+  //    旧版残留副本；序位仍在 user 级之上、npm-dev/project 级之下（红线 1）。
+  //    workflows kind 刻意不注入：<available_workflows> 的 <location> 是 CA2 快照
+  //    不豁免面（红线 8 豁免仅限 10 内置 agent 角色路径前缀），注入会翻转内置
+  //    workflow 的胜出路径。
+  if (kind === "agents") {
+    const coreNpmRoot = corePackageNpmRoot();
+    if (coreNpmRoot !== undefined) {
+      roots.push({ dir: coreNpmRoot, source: "npm" });
+    }
+  }
+  return roots;
+}
+
+/** skills 的 agentDir 派生根。对齐 skill-discovery.ts resolveSkillPath 的两处
+ *  推导（<agentDir>/skills + <agentDir>/npm/node_modules）——现状无 npm-dev 根，
+ *  刻意不补（避免静默引入新发现源）。 */
+function skillRoots(): DiscoveryRoot[] {
+  const agentDir = getAgentDir();
+  return [
+    { dir: join(agentDir, "skills"), source: "user-pi" },
+    { dir: join(agentDir, "npm", "node_modules"), source: "npm" },
+  ];
+}
+
+/** pi 宿主 HostServices 实现（扩展初始化最早处经 configureCore 注入）。 */
+export function createPiHostServices(): HostServices {
+  return {
+    // 每次现取 getAgentDir（实例隔离，见文件头）；env 覆盖段与 warn-once 留 core
+    // data-dir.ts，壳只返回数据根本身（D2 计划期细化③分段归属）。
+    dataRoot(): string {
+      return getAgentDir();
+    },
+
+    // 桥接到 pi-extension-logger：component 即 extName（复用其 loggerCache 单例
+    // 与 appendEntry/文件日志通路），按 level 分派方法，(message, data) 透传。
+    log(level: LogLevel, component: string, message: string, data?: unknown): void {
+      const logger = getLogger(component);
+      if (level === "error") logger.error(message, data);
+      else if (level === "warn") logger.warn(message, data);
+      else logger.debug(message, data);
+    },
+
+    discoveryRoots(): {
+      agents?: DiscoveryRoot[];
+      skills?: DiscoveryRoot[];
+      workflows?: DiscoveryRoot[];
+    } {
+      return {
+        agents: agentDirKindRoots("agents"),
+        skills: skillRoots(),
+        workflows: agentDirKindRoots("workflows"),
+      };
+    },
+  };
+}
+
+/** pi 侧通知域窄端口实现（configureNotifyDomain 注入）。zsw 壳不注入本端口
+ *  （其完成通知走 HostServices.notify，P2 落地）。 */
+export function createPiNotifyDomainPorts(): NotifyDomainPorts {
+  return {
+    // pi 真函数返回 CountActiveResult，core 契约只读 .count——壳侧拆数值。
+    countActiveFromEntries(entries: unknown[]): number {
+      return countActiveFromEntries(entries).count;
+    },
+
+    // 投递内核工厂直传本体（结构兼容论证见文件头）；不经包装避免多一层间接面。
+    createDelivery,
+  };
+}