@zhushanwen/pi-subagent-workflow 8.7.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.7.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,7 +19,6 @@
   },
   "files": [
     "index.ts",
-    "agents/",
     "skills/",
     "scripts/",
     "relay/",
@@ -51,24 +50,22 @@
     ],
     "skills": [
       "./skills"
-    ],
-    "agents": [
-      "./agents"
     ]
   },
   "dependencies": {
     "@xyz-agent/session-delivery": "0.3.0",
-    "@zhushanwen/pi-extension-logger": "0.3.0",
-    "@xyz-agent/extension-protocol": "0.7.0",
-    "@zhushanwen/subagent-core": "0.2.0"
+    "@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.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/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

@@ -12,7 +12,9 @@
 // mock 返回 {count: n} 形状直接验证「适配读 .count」；session-delivery mock
 // 验证 createDelivery 透传（参数 + 返回句柄）。
 
-import { join } from "node:path";
+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";
 
@@ -72,17 +74,36 @@ describe("createPiHostServices.discoveryRoots（与现推导逐项一致）", ()
     vi.mocked(getAgentDir).mockReturnValue(AGENT_DIR);
   }
 
-  it("agents 三根：顺序与 source 标签 = user-pi → npm → npm-dev", () => {
+  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;

package/src/host/pi-host.ts

@@ -16,7 +16,9 @@
 //     buildScanTargets、orchestration/skill-discovery.ts resolveSkillPath 的现推导
 //     逐项一致（user-pi / npm / npm-dev 字面即现 ResourceSource 标签）。
 //     project/workspace 根不在壳侧提供——core 消费方按 workspaceRoot 自行推导
-//     （u0-data-discovery 波次接注入消费）。
+//     （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 单元登记给本单元的适配责任。
@@ -25,7 +27,8 @@
 //     是结构超集成员，多不碍兼容）——结构兼容由本注入点 typecheck 守护，上游签名
 //     漂移即红（notify-ports.ts「闭包红线」段）。
 
-import { join } from "node:path";
+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";
@@ -36,12 +39,50 @@ import type { DiscoveryRoot, HostServices } from "@zhushanwen/subagent-core/core
 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();
-  return [
+  const roots: DiscoveryRoot[] = [
     // 1. user .pi/agent/<kind>/
     { dir: join(agentDir, kind), source: "user-pi" },
     // 2. npm global: agentDir/npm/node_modules/*/<pkg>/
@@ -49,6 +90,19 @@ function agentDirKindRoots(kind: "agents" | "workflows"): DiscoveryRoot[] {
     // 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 的两处

package/src/index.ts

@@ -25,6 +25,7 @@ import { configureCore } from "@zhushanwen/subagent-core/core/host-services.ts";
 import { configureNotifyDomain } from "@zhushanwen/subagent-core/core/notify-ports.ts";
 import { createPiHostServices, createPiNotifyDomainPorts } from "./host/pi-host.ts";
 
+import { oncePerProcess } from "@zhushanwen/pi-ext-guards";
 import { bestEffort } from "@zhushanwen/subagent-core/execution/best-effort.ts";
 // ═══ execution/ 层（subagents 核心 + 运行时） ═══
 import { getOrCreateChannelRegistry } from "@zhushanwen/subagent-core/execution/channel-registry-access.ts";
@@ -49,7 +50,7 @@ import {
 } from "@zhushanwen/subagent-core/execution/model-config-service.ts";
 import { bindNotifyLedgerHost, getBoundNotifyLedger, type NotifyLedgerHost } from "@zhushanwen/subagent-core/execution/notify-ledger.ts";
 import { IDENTITY_CUSTOM_TYPE, type SubagentIdentityData } from "@zhushanwen/subagent-core/execution/session-reconstructor.ts";
-import type { ExecutionMode, SubagentRecord } from "@zhushanwen/subagent-core/execution/types.ts";
+import type { ExecutionMode } from "@zhushanwen/subagent-core/execution/types.ts";
 import { maybeCleanupExpiredSessionFiles } from "@zhushanwen/subagent-core/execution/session-file-gc.ts";
 import {
   getSubagentService,
@@ -59,8 +60,10 @@ import {
 import { killAllSpawnedChildren } from "@zhushanwen/subagent-core/execution/session-runner.ts";
 import { SubprocessAgentRunner } from "@zhushanwen/subagent-core/execution/subprocess-agent-runner.ts";
 import { WorktreeManager } from "@zhushanwen/subagent-core/execution/worktree-manager.ts";
-// [engine-awareness U3] per-turn 引擎检测编排（D1/D1b/D2/D3/D5）
-import { normalizeEngineId, runEngineAwarenessTurn } from "./injectors/engine-awareness.ts";
+// [engine-awareness U3] per-turn 引擎检测编排（D1/D1b/D2/D3/D5）；normalizeEngineId
+// 单一权威源在 core registry（原经 engine-awareness 再导出，导入面已折叠直连）
+import { normalizeEngineId } from "@zhushanwen/subagent-core/execution/engine/registry.ts";
+import { runEngineAwarenessTurn } from "./injectors/engine-awareness.ts";
 import { setupModelListInjector } from "./injectors/model-list-injector.ts";
 import { setupSubagentListInjector } from "./injectors/subagent-list-injector.ts";
 import { setupWorkflowListInjector } from "./injectors/workflow-list-injector.ts";
@@ -81,6 +84,7 @@ import { executeNestedWorkflow, runAndWait, type WorkflowRunResult } from "@zhus
 import {
   evictDoneRunsBeyondCap,
   MAX_RETAINED_DONE_RUNS,
+  recoverCrashedRuns,
   scheduleTimeBudget,
   terminateRunningRuns,
 } from "@zhushanwen/subagent-core/orchestration/lifecycle.ts";
@@ -106,42 +110,6 @@ declare module "@earendil-works/pi-coding-agent" {
 // 模块级 logger（setPiHandle 注入后自动走 appendEntry）
 const logger = getLogger("subagents");
 
-// ── subagent 状态快照格式化 ──
-//
-// [v4 A-6] before_agent_start 注入 hook 已删（活跃 subagent 清单改由 agent 按需调
-// action:'list' 拉取，消除每 loop 注入的上下文税与盲点）。本函数保留为纯格式化工具：
-// before-agent-start-injection / parent-child-matrix 测试覆盖其正确性，未来 list
-// 视图或其他注入点可复用。
-
-/** 活跃 subagent 数量上限（超过截断显示）。 */
-const MAX_STATUS_INJECTION = 10;
-
-/**
- * 将活跃 subagent record 格式化为一行一条的快照文本。
- *
- * 格式：
- *   [subagent-status] N active subagents:
- *   - sa-xxx (slug): running, rounds 0
- *   - sa-yyy (slug): idle, rounds 3
- *   +2 more, use action:'list'
- *
- * @param records 已筛选的活跃 record（running + idle）
- */
-export function formatSubagentStatusSnapshot(records: SubagentRecord[]): string {
-  const lines = [`[subagent-status] ${records.length} active subagent${records.length === 1 ? "" : "s"}:`];
-  const shown = records.slice(0, MAX_STATUS_INJECTION);
-  for (const r of shown) {
-    const slug = r.slug || r.agent;
-    const roundPart = r.round !== undefined && r.round > 0 ? `, rounds ${r.round}` : "";
-    lines.push(`- ${r.id} (${slug}): ${r.status}${roundPart}`);
-  }
-  const remaining = records.length - MAX_STATUS_INJECTION;
-  if (remaining > 0) {
-    lines.push(`+${remaining} more, use action:'list'`);
-  }
-  return lines.join("\n");
-}
-
 // ═══ [V2 决策 7 防线 i] process 级 shutdown hook ═══
 //
 // session_shutdown 是 pi 的 async hook，进程被 SIGTERM/SIGINT 强杀或崩溃时来不及
@@ -248,12 +216,10 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     }
   }
 
-  // resources_discover：不再注入额外 skill 目录（ADR-031 废弃 discovery.json）。
-  // pi 核心 auto-discovery 已覆盖 .agents/skills 等标准目录，子 session 的
-  // --skill 由 agent({skill}) 调用方显式传入，无需 extension 额外补充。
-  pi.on("resources_discover", (_event, _ctx: ExtensionContext) => {
-    return {};
-  });
+  // resources_discover：不再注册 handler（v4 决策：不再注入额外 skill 目录，
+  // ADR-031 废弃 discovery.json）。pi 核心 auto-discovery 已覆盖 .agents/skills
+  // 等标准目录，子 session 的 --skill 由 agent({skill}) 调用方显式传入，无需
+  // extension 额外补充。
 
   // ════════════════════════════════════════════════════════════
   //  workflow 域：tools + command + pi.__workflowRun + state
@@ -381,8 +347,9 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     lsRef.lastSessionId = sessionId;
 
     // [U7] 引擎列表同步 engines.json（幂等零写 + fail-safe；组合根注册已在
-    // extension 工厂体完成，此处 registry 已含全部引擎）
-    syncEnginesFile(agentDir);
+    // extension 工厂体完成，此处 registry 已含全部引擎）。写 agentDir 全局文件属
+    // 跨 session 副作用——oncePerProcess 守卫防 factory 二调/handler 累积双跑（u-audit-fix）。
+    oncePerProcess("subagent-workflow:sync-engines-file", () => syncEnginesFile(agentDir));
 
     // skill 路径两级缓存 session 级失效：pi 同进程可能有多个 session（TUI /new、/fork），
     // 运行中安装的 skill 需对新 session 可见（含曾 miss 缓存的 undefined 条目与 npm 新装
@@ -527,21 +494,27 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       setSubagentService(service);
     }
 
-    // S-2: 启动 idle record GC 定时器（30 天 TTL，每小时检查一次）
-    service.startGcTimer();
+    // S-2: 启动 idle record GC 定时器（30 天 TTL，每小时检查一次）。
+    // 注册 setInterval 属进程级副作用——oncePerProcess 守卫防双跑（u-audit-fix）。
+    oncePerProcess("subagent-workflow:start-gc-timer", () => service.startGcTimer());
 
     try {
-      maybeCleanupExpiredSessionFiles(agentDir, cwd);
+      // 递归扫描 <agentDir>/subagents + unlink 超 TTL 跨 session 文件属进程级维护
+      // ——oncePerProcess 守卫防双跑（u-audit-fix）。
+      oncePerProcess("subagent-workflow:cleanup-expired-session-files", () =>
+        maybeCleanupExpiredSessionFiles(agentDir, cwd));
     } catch (err) {
       logger.warn("[subagents] expired session file cleanup failed", {
         reason: err instanceof Error ? err.message : String(err),
       });
     }
 
-    // ADR-035 启动恢复：扫描 manifest tmp 残留（崩溃打断的 writeManifest 留下），
-    // 每次 session_start 都调（与上方 maybeCleanupExpiredSessionFiles 一致）。
+    // ADR-035 启动恢复：扫描 manifest tmp 残留（崩溃打断的 writeManifest 留下，promote/unlink）。
+    // 扫描属进程级维护——oncePerProcess 守卫防双跑（u-audit-fix）；第二派发重放首次
+    // Promise（结果缓存语义），recovered 计数日志可能重打，无文件副作用。
     try {
-      const recovered = await service.recoverManifestTmpFiles();
+      const recovered = await oncePerProcess("subagent-workflow:recover-manifest-tmp-files", () =>
+        service.recoverManifestTmpFiles());
       if (recovered.recovered > 0 || recovered.deleted > 0) {
         logger.warn(`[subagents] manifest tmp recovery: ${recovered.recovered} promoted, ${recovered.deleted} deleted`);
       }
@@ -552,8 +525,9 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     }
 
     try {
-      const wtm = new WorktreeManager(agentDir);
-      await wtm.scan();
+      // 孤儿 worktree 清理（git/rm 进程操作 + 注册表/目录扫描）属进程级维护
+      // ——oncePerProcess 守卫防双跑（u-audit-fix）。
+      await oncePerProcess("subagent-workflow:worktree-scan", () => new WorktreeManager(agentDir).scan());
     } catch (err) {
       logger.warn("[subagents] worktree reaper scan failed", {
         reason: err instanceof Error ? err.message : String(err),
@@ -575,49 +549,30 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     // resolveIdentity），无需经 state 透传——modelService 是唯一 registry 源。
 
     // MF-1: store 健康度跟踪。loadAll 失败 → storeHealthy=false，workflow 域启动时 fail-fast。
+    // 崩溃恢复四步（loadAll → failed → save → evict）收口到 core recoverCrashedRuns（D8：
+    // 宿主各写一遍正是 failure-mode-B）；pending:unregister 经 hooks 外置发射（位置在
+    // transition 后、save 前，对齐原内联实现）；save 走 store 冷路径（done 绕过去抖）——
+    // 冷路径语义在 JsonlRunStore.save 内，不随循环归属转移。loadAll 失败的 fail-fast
+    // （storeHealthy=false 停初始化）是宿主职责，core 原样上抛、这里 catch 兜住。
     let storeHealthy = true;
     try {
-      const loaded = await store.loadAll();
-      for (const run of loaded) {
-        if (run.state.status === "running") {
-          run.state.error = "Process killed (kill-9 or crash recovery)";
-          run.transition("done", "failed");
-          pi.events.emit("pending:unregister", {
-            id: run.runId,
-            reason: "failed",
-          });
-          // 恢复终态必须落盘：save 走冷路径（done 绕过去抖）同步写 state 文件 +
-          // append 终态 workflow-record entry——entry_appended 事件驱动 runtime 派生
-          // 缓存失效重拉（无 triggerTurn 副作用）。不 save 则 entry/state 双双停留
-          // running，侧栏永久卡 running。失败仅记日志不阻断其余 run 的恢复（下次
-          // session_start 重开重试，恢复循环天然幂等）。
-          try {
-            await store.save(run);
-          } catch (err) {
-            logger.error("[subagent-workflow] kill-9 recovery store.save failed", {
-              runId: run.runId,
-              reason: err instanceof Error ? err.message : String(err),
-            });
-          }
-        }
-        runs.set(run.runId, run);
-      }
-      // done run 内存有界性：loadAll 全量重水合后立即裁剪到 K。kill-9 恢复（上方
-      // running → transition("done","failed")）的 run completedAt 为 transition 时刻
-      // （当前时间=全局最新）参与排序且必在保留端；多条恢复 run 同 ms completedAt →
-      // tie 稳定排序。淘汰只 delete runs Map 条目——磁盘 state 文件与
-      // workflow-state-link 指针条目均不动（历史审计保留）；下次 session_start loadAll
-      // 从指针全量重水合后再次裁剪，该循环每次 session 启动重复且可接受：内存峰值只在
-      // 启动期，常驻 O(K + 活跃 run)。消除启动峰值需指针 compaction，属 append+replay
-      // 长期方案问题域，非本范围。
-      const evicted = evictDoneRunsBeyondCap(runs, MAX_RETAINED_DONE_RUNS);
-      if (evicted > 0) {
-        logger.debug("[subagent-workflow] evicted done runs beyond cap after loadAll", {
-          evicted,
-          keep: MAX_RETAINED_DONE_RUNS,
-          sessionId,
-        });
-      }
+      // 崩溃恢复 loadAll 扫 cwd 共享 sessionDir（同 cwd 跨 session 共享）并把 running run
+      // 转 failed 落盘——写非本 session 的 run state 文件属跨 session 副作用，oncePerProcess
+      // 守卫防双跑（u-audit-fix）。第二派发重放首次 Promise：不再落盘、不再 emit。
+      await oncePerProcess(
+        "subagent-workflow:recover-crashed-runs",
+        () =>
+          recoverCrashedRuns(
+            store,
+            runs,
+            "Process killed (kill-9 or crash recovery)",
+            {
+              onRunRecovered: (payload) => {
+                pi.events.emit("pending:unregister", payload);
+              },
+            },
+          ),
+      );
     } catch (err) {
       // QMF-4 fix: store.loadAll 失败是关键路径错误，workflow 域将未初始化
       logger.error("[subagent-workflow] store.loadAll failed, workflow domain uninitialized", {
@@ -997,17 +952,8 @@ function getOrCreateDialogQueue(): DialogGlobalQueue {
   return queue;
 }
 
-// ============================================================
-// Public cross-extension API（channel handler 注册入口）
-// ============================================================
-//
-// 跨扩展消费者（ask-user 等）通过包根 import 注册 channel handler，
-// 让 subagent 子进程的 UI 请求（ask_user 等）透传到主进程渲染。
-// 重新导出 channel-registry-access 的公开 API——稳定 surface，
-// 内部存储实现演进不影响消费者。
-
-export {
-  getOrCreateChannelRegistry,
-  type UiChannelRegistry,
-  type ChannelHandler,
-} from "@zhushanwen/subagent-core/execution/channel-registry-access.ts";
+// 跨扩展 channel handler 注册入口已收口到 core 深路径
+// `@zhushanwen/subagent-core/execution/channel-registry-access.ts`
+// （getOrCreateChannelRegistry / UiChannelRegistry / ChannelHandler）。
+// 历史上的包根 re-export 已删：ask-user 等跨扩展消费者经 globalThis 握手
+// （DIALOG_QUEUE_KEY 同款进程级单例），不再经包根 import 消费本模块。

package/src/injectors/__tests__/engine-awareness.test.ts

@@ -1,7 +1,7 @@
 // engine-awareness 单测（[engine-awareness U3]）
 //
 // 覆盖（设计 docs/design/subagent-engine-awareness-injection.md 验收挂钩 D1/D1b/D2/D3/D5）：
-// 1. normalizeEngineId：缺省/空白归一到 'pi'（单一权威源 registry.ts，经本模块再导出）
+// 1. normalizeEngineId：缺省/空白归一到 'pi'（单一权威源 registry.ts，直连导入）
 // 2. buildEngineChangeNotice：§3.1 文案骨架、pi/非 pi 指路段分界、不含任何模型清单（D4）
 // 3. runEngineAwarenessTurn 编排：
 //    - 变更触发 apply + 通知（D2 顺序硬约束：提交缓存先于通知先于记账）
@@ -18,11 +18,11 @@ import { describe, expect, it } from "vitest";
 import {
 	buildEngineChangeNotice,
 	ENGINE_CHANGE_CUSTOM_TYPE,
-	normalizeEngineId,
 	runEngineAwarenessTurn,
 	type EngineAwarenessDeps,
 	type EngineAwarenessOutcome,
 } from "../engine-awareness";
+import { normalizeEngineId } from "@zhushanwen/subagent-core/execution/engine/registry.ts";
 import type { GlobalConfigReadResult } from "@zhushanwen/subagent-core/execution/config.ts";
 
 // ── 测试数据 ────────────────────────────────────────────

package/src/injectors/__tests__/engine-section-stability.test.ts

@@ -26,7 +26,9 @@ import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { formatModelList, setupModelListInjector, type ModelEntry } from "../model-list-injector.ts";
+// C5①：formatModelList/ModelEntry 下沉 core barrel（setupModelListInjector 留 injector）
+import { formatModelList, type ModelEntry } from "@zhushanwen/subagent-core";
+import { MODEL_LIST_GUIDE, setupModelListInjector } from "../model-list-injector.ts";
 import type { EnginePort } from "@zhushanwen/subagent-core/execution/engine/port.ts";
 import { clearEngines, registerEngine } from "@zhushanwen/subagent-core/execution/engine/registry.ts";
 import {
@@ -80,7 +82,7 @@ const APPEND_SEPARATOR = "\n\n";
 
 /** 合成一个 turn 的 system prompt 尾部：BASE + provider models 段 + engine 追加段。 */
 function composeTurn(defaultEngine: string | undefined): string {
-	const providerSection = formatModelList(PROVIDER_ENTRIES);
+	const providerSection = formatModelList(PROVIDER_ENTRIES, { guide: MODEL_LIST_GUIDE });
 	const afterProvider = providerSection === "" ? BASE : BASE + providerSection;
 	const append = composeEngineAppend(defaultEngine);
 	return append === "" ? afterProvider : `${afterProvider}${APPEND_SEPARATOR}${append}`;
@@ -190,7 +192,7 @@ describe("段渲染确定性（D7：同输入恒同输出）", () => {
  *   - 切换后的引擎追加段恰居 prompt 尾部。
  */
 function expectOnlyTailDiffers(from: string | undefined, to: string | undefined): void {
-	const stableHead = BASE + formatModelList(PROVIDER_ENTRIES);
+	const stableHead = BASE + formatModelList(PROVIDER_ENTRIES, { guide: MODEL_LIST_GUIDE });
 	const before = composeTurn(from);
 	const after = composeTurn(to);
 	const beforeAppend = composeEngineAppend(from);
@@ -279,7 +281,7 @@ describe("段序守护：engine 段恒链尾（D7）", () => {
 		// 恒链尾：engine 追加段是 prompt 的最后内容
 		expect(prompt.endsWith(`${APPEND_SEPARATOR}${composeEngineAppend(defaultEngine)}`)).toBe(true);
 		// model list handler 注入形态锚定（BASE + injection 无分隔，生产 handler 同款）
-		expect(prompt.startsWith(BASE + formatModelList(PROVIDER_ENTRIES))).toBe(true);
+		expect(prompt.startsWith(BASE + formatModelList(PROVIDER_ENTRIES, { guide: MODEL_LIST_GUIDE }))).toBe(true);
 	});
 
 	it("对照：注册序颠倒（engine 先、model list 后）时段序断言必失败——守护有判别力", async () => {