@zhushanwen/subagent-core 0.4.0 → 0.6.0

package/src/index.ts

@@ -1,5 +1,5 @@
 /**
- * @zhushanwen/subagent-core — 公共 API barrel（D5 定稿）
+ * @zhushanwen/subagent-core — 公共 API barrel（D5 定稿 + post-convergence B-2 扩面）
  *
  * 公共 API 面 = 本文件导出 + package.json exports 的语义子入口
  * （./engines/zcode/reader、./engines/zcode/constants、./engine/paths、./relay-env）
@@ -7,25 +7,34 @@
  * 新增导出走 minor，本文件刻意不使用 `export *`，逐名列出以使 diff 可审。
  * 内部实现细节（error-recovery / execute-agent-call / worker-script-builder 等
  * engine 编排件）不经 barrel 导出；host-surface 扩面（zsw 回接 U0，2026-08-30）
- * 后 port 的 Infra 实现与宿主组装件已列入公共面，仓内壳侧深路径消费
- * （`./*` -> src 通配）不受本文件约束。
+ * 后 port 的 Infra 实现与宿主组装件已列入公共面。
+ *
+ * 扩面判定标准（post-convergence D3）：壳非测试代码实际消费 ≥1 处即进 barrel——
+ * 契约面 = 壳的实际消费面，core 内部移动/重命名文件不再是对壳的隐性 breaking。
+ * 未进 barrel 的内部实现细节仍不经此导出；`./*` -> src 开发态通配已随 u-2a/u-2b
+ * 从 package.json 删除，深路径归一由消费侧单元（u-2b/u-2c）收口，barrel 是公共
+ * 消费终点。
  *
  * 设计权威源：docs/design/subagent-core-package-extraction.md §3.3 D5；
+ * docs/design/subagent-post-convergence-architecture.md §3.2 B-2 / §3.6 D3/D8/D9；
+ * docs/design/subagent-core-sink-design.md（sink 下沉收口扩面，2026-08-31）；
  * 宿主接入示例见包 README（§3.4 core_host_not_configured 恢复指引的落点）。
  */
 
 // 0.4.0 = 首个公开发布的收敛收口面（0.3.0 为 2026-08-30 裁决的跳号占位，永不单独
 // 发布；+ minor changeset 收口面落本号）；与 package.json version 的一致性由
 // src/__tests__/smoke.test.ts 动态守护，改版本须两处同步。
-export const CORE_PACKAGE_VERSION = "0.4.0";
+export const CORE_PACKAGE_VERSION = "0.6.0";
 
 // ── 宿主端口接线面（core/）────────────────────────────────────
 // HostServices：dataRoot / log / discoveryRoots 端口 + configureCore 注入；
 // 未 configureCore 即消费 dataRoot 抛 core_host_not_configured（§3.4 错误规格，
 // 恢复指引指向 README 接入示例）。DEFAULT_DATA_ROOT 显式导出供宿主选用——
-// 消除「缺省静默漂目录」。
+// 消除「缺省静默漂目录」。getHostServices：core 内统一取用点，宿主 injector
+// 消费（resource-list-injector）。
 export {
   configureCore,
+  getHostServices,
   DEFAULT_DATA_ROOT,
   type DiscoveryRoot,
   type HostServices,
@@ -54,13 +63,11 @@ export type {
 export type {
   AgentEvent,
   AgentOutcome,
-  AgentTaskSpec,
   EngineCapabilities,
   EngineHandle,
   EngineHandleData,
   InteractAction,
   InteractResult,
-  PersonaSpec,
   ProbeReport,
   ReplayedTurn,
   SessionView,
@@ -82,107 +89,373 @@ export {
   type EngineRoutingSource,
 } from "./execution/engine/routing.ts";
 
-// ── 资源发现面（shared/resource-discovery，W2③）──────────────
-// discoverResources：agent .md / workflow .js 的多源统一发现（ADR-031）——多源扫描
-// + stem last-writer-wins 合并 + realpath 去重。宿主（zsw 回接）经 ScanConfig.hostRoots
-// 注入发现根（source 标签即 ResourceSource 槽位键，含 project-host 项目级槽）；
-// 深路径消费在 npm/vendored 发布形态不可达（exports 无深路径通配），故出 barrel。
-export { discoverResources } from "./shared/resource-discovery.ts";
-export type {
-  DiscoveredResource,
-  ResourceKind,
-  ResourceSource,
-  ScanConfig,
-} from "./shared/resource-discovery.ts";
-// 发现链辅助（C5b）：discoverResources 之外被发现消费方逐文件消费的三个原语——
-// findWorkspaceRoot（project 源根定位）、getCachedParsed/getCachedFileContent
-// （mtime 缓存读取）。发现链消费方（pi-sw injector 等宿主接线）逐条解析
-// DiscoveredResource 的 frontmatter/meta 需要它们，深路径在 npm/vendored 发布
-// 形态不可达，故随发现面出 barrel。
+// ── 引擎注册 / 发现与进程面（execution/engine）────────────────
+// 组合根 index.ts 接线消费（registerXxx 引擎注册、syncEnginesFile engines 文件
+// 同步、killAllSpawnedChildren session 派生进程兜底清理）。
+export { syncEnginesFile } from "./execution/engine/engine-discovery.ts";
+export { registerPiEngine } from "./execution/engine/engines/pi/registration.ts";
+export { killAllSpawnedChildren } from "./execution/engine/engines/pi/session-runner.ts";
+export { registerZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
+
+// pi session-runner 内核件（merge 裁决：dev 侧旧深路径 execution/session-runner.ts
+// 终态已不存在，符号随 u-2a 迁移至 engine/engines/pi/session-runner.ts）：
+// maxTurnsToWatchdogMs 为 maxTurns→watchdog 毫秒换算（U3/U4 / D7，floor 语义
+// 文档化——两宿主预算一致性 S2 的函数级锚点）；killRecordChildWithEscalation 为
+// 单 record 子进程升级回收（session 派生进程清理的细粒度入口）。
 export {
-  findWorkspaceRoot,
-  getCachedFileContent,
-  getCachedParsed,
-} from "./shared/resource-discovery.ts";
-// parseResourceMeta：.md frontmatter / workflow @pi-meta 的统一 meta 解析
-// （fail-safe null）——发现链消费方从 DiscoveredResource 提取 name/description
-// 的解析入口，与上面发现链辅助同属一个消费面，深路径同样不可达。
-export { parseResourceMeta } from "./shared/meta-parser.ts";
+  killRecordChildWithEscalation,
+  maxTurnsToWatchdogMs,
+} from "./execution/engine/engines/pi/session-runner.ts";
+
+// zcode 引擎注册面：registerZcodeEngine 把 'zcode' 引擎登记进 registry（组合根
+// 职责，幂等，上方已导出）；createZcodeEngine 为 DI 工厂（测试/宿主注入 deps）。
+// ZcodeEngineDeps 经 registration.ts 的 re-export 导出（避免与 zcode-engine.ts 双源）。
+export { createZcodeEngine } from "./execution/engine/engines/zcode/registration.ts";
+export type { ZcodeEngineDeps } from "./execution/engine/engines/zcode/registration.ts";
 
-// ── 注入渲染面（shared/injection-render + shared/xml-injection，W3）──
-// 三段 XML（<available_subagents>/<available_workflows>/<available_provider_models>）
-// 的 format 纯函数 + Entry 接口从 pi-sw 插件层下沉（D-3）：ModelEntry 并集口径
-// （除 id/name 外全字段 optional，红线 5 守卫不抛不渲垃圾）、分段条目预算
-// （码点序排 + 截尾 + 宿主注入兜底指引；models 段无预算永不截，红线 7）、
-// guide 文案宿主注入（core 不内嵌平台文案）。summarizeDescription 随
-// WorkflowEntry 链导出（zsw 侧同口径消费）。escapeXml/renderXmlSection 渲染
-// 原语随面出 barrel——深路径消费在 npm/vendored 发布形态不可达。
+// ZcodeTaskShapeError：zcode 任务形状错误类（instanceof 分流用）——
+// execution-runtime-face.test.ts:29 消费，barrel 保留导出（engines 域 A1 裁决）。
+export { ZcodeTaskShapeError } from "./execution/engine/engines/zcode/zcode-engine.ts";
+
+// 引擎注册表原语 + 引擎感知提示面：engine-awareness injector 消费。
 export {
-  formatAgentList,
-  formatModelList,
-  formatWorkflowList,
-  sortByCodepoint,
-  summarizeDescription,
-} from "./shared/injection-render.ts";
+  DEFAULT_ENGINE_ID,
+  normalizeEngineId,
+} from "./execution/engine/registry.ts";
+export {
+  buildEngineModelsPromptAppend,
+  buildSubagentEngineSection,
+} from "./execution/engine/model-prompt.ts";
+
+// session-view 归一符号（post-convergence D3）：runtime 读取侧 2 处深路径
+// （subagent-extractor / subagent-engine-history）归一 barrel 的前置——不新增
+// 子入口（D9：每条子入口 bundle 多一份 host-services 副本）。
+export { parseEngineHandle } from "./execution/engine/common/session-view-types.ts";
+export { readSubagentHistoryMessages } from "./execution/engine/common/session-view-service.ts";
+
+// ── 执行域（execution/）──────────────────────────────────────
+// types.ts 领域类型族：record / 响应 / 列表项等 subagent 域公共契约（壳消费最高频面，
+// tool 面 / interface 渲染层 / bg-notify 共同消费）。CLOSED_REASONS / DEFAULT_AGENT_NAME
+// 为值常量，ResurrectDeniedError 为错误类（值 + 类型双形态）。
+export {
+  CLOSED_REASONS,
+  DEFAULT_AGENT_NAME,
+  ResurrectDeniedError,
+} from "./execution/types.ts";
 export type {
-  AgentEntry,
-  ListFormatOptions,
-  ModelEntry,
-  ModelListFormatOptions,
-  ModelReasoningInfo,
-  WorkflowEntry,
-} from "./shared/injection-render.ts";
-export { escapeXml, renderXmlSection } from "./shared/xml-injection.ts";
+  AgentEventLogEntry,
+  BgResponse,
+  CancelResponse,
+  CloseResponse,
+  ClosedReason,
+  DisplayItem,
+  ExecutionMode,
+  ExecutionOutcome,
+  ExecutionRecord,
+  ExecutionStatus,
+  ExternalState,
+  ForkFromResponse,
+  ListResponse,
+  MessageResponse,
+  SubagentListItem,
+  SubagentRecord,
+  SubagentToolResult,
+} from "./execution/types.ts";
+
+// execution-record 投影函数族：record → 渲染态投影（outcome / elapsed / tool calls /
+// live progress），interface 渲染层唯一消费入口。
+export {
+  computeElapsedSeconds,
+  countAllToolCalls,
+  deriveOutcome,
+  getAllToolCalls,
+  projectLiveProgress,
+  projectOutcome,
+} from "./execution/execution-record.ts";
+
+// SubagentService 聚合面 + 进程单例访问器（post-convergence D8）：访问器经
+// globalThis[Symbol.for] slot 防 jiti 多实例分裂，/resume /fork 复用既有实例
+// （SR-3/SR-4 语义）。createSubagentService / SubagentServiceInit 为构造依赖参数
+// 注入形态（modelService 等，无全局查找，@experimental U10 / D6）。
+export {
+  SubagentService,
+  getSubagentService,
+  setSubagentService,
+  createSubagentService,
+  type SubagentServiceInit,
+} from "./execution/subagent-service.ts";
+// notifyGateAllowsDelivery：closedReason → 投递许可判定（通知门）——
+// 投递内核与壳侧 notify 链的共同语义锚点（execution 生产域消费，A2a）。
+export { notifyGateAllowsDelivery } from "./execution/subagent-service.ts";
+
+// ModelConfigService 聚合面 + 单例访问器四件中的 model 侧两件（D8）；
+// ModelConfigServiceInit 为 SubagentServiceInit.modelService 的构造依赖
+// （MF-4：jsdoc 示例 `new ModelConfigService({cwd, agentDir})` 可构造）。
+export {
+  ModelConfigService,
+  getModelConfigService,
+  setModelConfigService,
+  type ModelConfigServiceInit,
+} from "./execution/model-config-service.ts";
+
+// notify ledger：宿主通知账本端口（bind / getBound）——组合根装配 + workflow 域消费。
+export {
+  bindNotifyLedgerHost,
+  getBoundNotifyLedger,
+  type NotifyLedgerHost,
+} from "./execution/notify-ledger.ts";
+
+// identity 重建常量与类型：session_start identity custom entry 的写入侧契约。
+export {
+  IDENTITY_CUSTOM_TYPE,
+  type SubagentIdentityData,
+} from "./execution/session-reconstructor.ts";
+
+// 执行域外围件（组合根 / interface 层直接消费的独立单点件）。
+export { bestEffort } from "./execution/best-effort.ts";
+// channel-registry 类型闭包（UiChannelRegistry / ChannelHandler）随值符号进 barrel
+// （u-2b 主 agent 裁决 2026-09-03）：壳 index.ts 跨扩展 re-export surface 的非测试
+// 生产消费，满足 D3 判定标准；type-only，零运行时面变化。
+export {
+  getOrCreateChannelRegistry,
+  type UiChannelRegistry,
+  type ChannelHandler,
+} from "./execution/channel-registry-access.ts";
+export { DialogGlobalQueue } from "./execution/dialog-queue.ts";
+export {
+  readGlobalConfig,
+  type GlobalConfigReadResult,
+} from "./execution/config.ts";
+export { isResumable } from "./execution/lifecycle-predicates.ts";
+export { maybeCleanupExpiredSessionFiles } from "./execution/session-file-gc.ts";
+export { createUiRequestHandlerForMode } from "./execution/ui-request-handler-factory.ts";
+export { WorktreeManager } from "./execution/worktree-manager.ts";
+export { SubprocessAgentRunner } from "./execution/subprocess-agent-runner.ts";
+
+// record 存储面：RecordStore 类 + 索引文件名常量（bench 扫描基准消费）；
+// ChangeListener / RecordStorePi / StatusFilter 为状态查询面的类型闭包
+//（@experimental U10 / D6：lookupRecordAnyState 全态查询等签名直接引用）。
+export {
+  RecordStore,
+  type ChangeListener,
+  type RecordStorePi,
+  type StatusFilter,
+} from "./execution/record-store.ts";
+export { INDEX_FILENAME } from "./execution/sessions-index.ts";
+
+// record 落盘 entry 契约：custom entry 写入侧（@experimental U10 / D6）。
+export {
+  SUBAGENT_RECORD_CUSTOM_TYPE,
+  toSubagentRecordEntry,
+  type SubagentRecordEntryData,
+} from "./execution/record-entry.ts";
+
+// agent-registry 执行消费面：loadByPath 直接加载（@experimental U10 / D6）+
+// parseAgentProfile 宽容解析（无 frontmatter 不拒、name 缺省 stem、返回 body 与
+// 执行字段全量）——执行消费面单点；与严格注入投影（parseResourceMeta）双轨分离
+// 的执行侧统一入口（U2 / D3）。
+export { AgentRegistry } from "./execution/agent-registry.ts";
+export {
+  parseAgentProfile,
+  type AgentProfile,
+} from "./execution/agent-registry.ts";
+
+// 错误类型族（error-recovery.ts 计划路径实测不存在，实测散布于下列源文件）：
+// resurrect/fork-depth/dirty-worktree 为动作层守卫抛出点（types.ts），
+// GitRunError 见 worktree 内核组裁决，ZcodeTaskShapeError 见引擎注册面。
+export {
+  DirtyWorktreeError,
+  ForkDepthExceededError,
+} from "./execution/types.ts";
+
+// 动作层领域内核（@experimental U10 / D6）：六 handler 的校验/守卫链/归属判定/
+// 终态映射，产出领域对象，宿主 adapter 负责包装渲染。
+export {
+  BG_MESSAGE,
+  cancelHandler,
+  closeHandler,
+  DEFAULT_LIST_LIMIT,
+  endedMessageGuard,
+  FORK_FROM_DEFAULT_PROMPT,
+  forkFromHandler,
+  listHandler,
+  mapExternalState,
+  MAX_LIST_LIMIT,
+  messageHandler,
+  NOTIFY_CONTRACT,
+  recordToListItem,
+  startHandler,
+  wrapForkFromPrompt,
+  type CancelHandlerInput,
+  type CancelHandlerResult,
+  type CloseHandlerInput,
+  type CloseHandlerResult,
+  type ForkFromHandlerInput,
+  type ForkFromHandlerResult,
+  type ListHandlerInput,
+  type ListHandlerResult,
+  type MessageHandlerInput,
+  type MessageHandlerResult,
+  type StartHandlerInput,
+  type StartHandlerResult,
+} from "./execution/subagent-actions-core.ts";
+
+// 进程活性探针（watchdog/孤儿判定共用，agent-ref 契约原语组 U1）。
+export { isProcessAlive } from "./execution/alive-store.ts";
+
+// 并发池工厂（U3/U4 / D7）：queuePolicy 缺省 priority 保 pi 行为，zsw 消费
+// strict-fifo——策略差异显式化而非双实现。
+export {
+  createConcurrencyPool,
+  type ConcurrencyPool,
+  type CreateConcurrencyPoolOptions,
+  type QueuePolicy,
+} from "./execution/concurrency-pool.ts";
+
+// 模型引用切分原语（U1 契约面批件）：provider/model 引用切分与缺省值（两宿主
+// maxTurns/model 换算同源）；实现体内聚 zcode preparer/constants 不挪文件，
+// barrel re-export（§5.3）。
+export {
+  DEFAULT_PROVIDER_ID,
+  hasApiKey,
+  splitZcodeModelRef,
+} from "./execution/engine/engines/zcode/preparer.ts";
+export { ZCODE_FALLBACK_DEFAULT_MODEL } from "./execution/engine/engines/zcode/constants.ts";
+
+// ── worktree git 内核（U5 / D5）───────────────────────────────
+// git 语义纯函数单源：保真读（gitRun）、SafeId 校验、dirty 谓词、
+// collectWorktreePatch（统一 add+diff 基线机制，返回结构即 patchIncomplete
+// 留痕载体）、三步容错清理、listWorktreePorcelain（原始输出供宿主 realpath
+// 对账）。锚点缺失/损坏与 add 失败两条降级路径 warn + 留痕（⛔3）。
+//
+// GitRunError 同名双类裁决（u-core-exec-export 交接）：worktree-manager.ts 与
+// worktree-git-ops.ts 各有一个 GitRunError（文案同但类独立）——barrel 只导出
+// 本组 worktree-git-ops 版（git 语义新单源）；worktree-manager 版不进 barrel，
+// 将来 manager 收缩到 git-ops 内核时随之消除。
+export {
+  assertSafeId,
+  cleanupWorktree,
+  collectWorktreePatch,
+  GitRunError,
+  gitRun,
+  isSafeId,
+  isTreeDirty,
+  listWorktreePorcelain,
+  SAFE_ID_RE,
+  type CleanupWorktreeOptions,
+  type CollectWorktreePatchOptions,
+  type ListWorktreePorcelainOptions,
+  type PatchBaselineAnchor,
+  type WorktreePatchResult,
+} from "./execution/worktree-git-ops.ts";
+
+// 组装层（U2 装配）：discoverAgents 发现→宽容解析→去重→码点序（workflow 侧
+// discoverWorkflows 对称面，第三宿主「列 agents」入口）。
+export { discoverAgents } from "./execution/agents-assembly.ts";
 
 // ── workflow 编排入口（orchestration）────────────────────────
 // runWorkflow / abortRun：run 生命周期 free functions（D-12）——orchestration 的
-// 最小宿主入口。以下 host-surface 扩面（zsw 回接 U0）出 Barrel：宿主壳组装
-// LifecycleDeps 需要亲手构造三个 port 实现与消费细粒度编排函数，深路径消费
+// 最小宿主入口。更细粒度编排（terminateRunningRuns / evictDoneRunsBeyondCap /
+// scheduleTimeBudget / 上限常量）为组合根实际消费面，随 B-2 扩面进 barrel
+// （D3 判定标准首次执行）。host-surface 扩面（zsw 回接 U0）同出 barrel：宿主壳
+// 组装 LifecycleDeps 需要亲手构造三个 port 实现与消费细粒度编排函数，深路径消费
 // 在 npm 形态不可达（发布面无 `./*` 通配）——宿主触点证据即 zsw 回接设计 D2。
 export { abortRun, runWorkflow } from "./orchestration/lifecycle.ts";
-export type { RunSpec } from "./orchestration/models/run-spec.ts";
-export type { LifecycleDeps } from "./orchestration/models/ports.ts";
-
-// lifecycle 细粒度编排：session 切换/关闭批量终止、done run 内存淘汰（窗口常量
-// MAX_RETAINED_DONE_RUNS）、run 级墙钟预算计时器（宿主 rebuildRuntime 重排用）。
 export {
+  terminateRunningRuns,
   evictDoneRunsBeyondCap,
-  MAX_RETAINED_DONE_RUNS,
   scheduleTimeBudget,
-  terminateRunningRuns,
+  MAX_RETAINED_DONE_RUNS,
 } from "./orchestration/lifecycle.ts";
 
-// launcher 层：runAndWait（阻塞至 done）与 executeNestedWorkflow（嵌套 workflow()，
-// 宿主 onWorkflowCall 注入的实现体）——宿主 tool/action 面的直接消费入口。
-export { executeNestedWorkflow, runAndWait } from "./orchestration/launcher.ts";
-export type { LauncherDeps, WorkflowRunResult } from "./orchestration/launcher.ts";
-
-// WorkerHost port 的 Infra 实现（worker_threads 启动 worker 脚本）——宿主组装
-// LifecycleDeps.workerHost 的默认实现；WorkerHandlers 是 start 的回调 bag 类型。
-export { WorkerHostImpl } from "./orchestration/worker-host.ts";
+// recoverCrashedRuns：崩溃恢复四步装配（宿主事件经 hooks 外置，U7 生命周期 / D8）。
+export {
+  recoverCrashedRuns,
+  type RecoverCrashedRunsHooks,
+  type RecoverCrashedRunsResult,
+} from "./orchestration/lifecycle.ts";
 
-// 脚本注册表 Infra 实现（config-loader 之上的 WorkflowScript 实体工厂）——
-// launcher 层 registry 依赖的默认实现。
+// launcher 层：runAndWait / executeNestedWorkflow（workflow 域嵌套编排入口）
+// + deps / 结果类型。
+export {
+  runAndWait,
+  executeNestedWorkflow,
+  type LauncherDeps,
+  type WorkflowRunResult,
+} from "./orchestration/launcher.ts";
+
+// worker-message-pump 内核件（execution 生产域消费，A2a）：finalizeRun run 终态
+// 收口 + FinalizeRunOptions 契约、closeOutInFlightCalls 在飞 call 批量清算、
+// makeSerializeFailedResult 序列化失败结果构造、postBudgetUpdate 预算播报、
+// resetRebuildFailureInjectionForTest 重建失败注入复位（测试面）。
+export {
+  finalizeRun,
+  closeOutInFlightCalls,
+  makeSerializeFailedResult,
+  postBudgetUpdate,
+  resetRebuildFailureInjectionForTest,
+  type FinalizeRunOptions,
+} from "./orchestration/worker-message-pump.ts";
+
+// workflow 领域模型族：run / call / trace / budget / 状态与规格（壳 store 与
+// interface 渲染层共同消费）。
+export type { RunSpec } from "./orchestration/models/run-spec.ts";
+export type { LifecycleDeps } from "./orchestration/models/ports.ts";
+export type { RunStore } from "./orchestration/models/ports.ts";
+// RunStore / AgentRunner / WorkerHost port 契约类型：宿主自写 Infra 实现（如 zsw
+// 的 RunnerPort 桥接）需要契约面；WorkerHandlers 已随 WorkerHost 注释。
+export type {
+  AgentRunner,
+  WorkerHandlers,
+  WorkerHost,
+} from "./orchestration/models/ports.ts";
+export type { RunState } from "./orchestration/models/run-state.ts";
+export { Trace } from "./orchestration/models/trace.ts";
+export { AgentCall } from "./orchestration/models/agent-call.ts";
+export { Budget } from "./orchestration/models/budget.ts";
+export { WorkflowRun, type WorkflowRunMeta } from "./orchestration/models/workflow-run.ts";
+export type {
+  AgentCallOpts,
+  AgentResult,
+  DoneReason,
+  ExecutionTraceNode,
+  RunStatus,
+  ToolCallEntry,
+  WorkerLogEntry,
+} from "./orchestration/models/types.ts";
+// SLUG_MAX_LENGTH 单源（merge 收敛完成）：唯一定义在 orchestration/models/types.ts；
+// 原 execution/execute-options-mapper.ts 重复定义已删（改 import 消费，深路径消费者
+// subagent-actions-core 同步切到 models/types 单源）。
+export { SLUG_MAX_LENGTH } from "./orchestration/models/types.ts";
+
+// workflow 脚本资产面：registry 契约 + 实现 / 脚本 lint / 文件落盘（save / delete）
+// + skill 路径缓存清理——组合根装配与 workflow 工具面消费。
+export type { WorkflowScriptRegistry } from "./orchestration/models/workflow-script-registry.ts";
 export { WorkflowScriptRegistryImpl } from "./orchestration/workflow-script-registry-impl.ts";
-
+// WorkflowScript 实体与按路径加载工厂（第三宿主零复刻脚本加载，G3/S5）。
+export {
+  loadWorkflowScriptByPath,
+  WorkflowScript,
+} from "./orchestration/workflow-script-registry-impl.ts";
 // lintScript：workflow 脚本静态检查（执行前 fail-fast，宿主 list/validate 面消费）。
 export { lintScript } from "./orchestration/script-lint.ts";
 export type { LintFinding, LintResult } from "./orchestration/script-lint.ts";
+export { saveWorkflow, deleteWorkflow } from "./orchestration/workflow-files.ts";
+export { clearSkillPathCache } from "./orchestration/skill-discovery.ts";
+export { WorkerHostImpl } from "./orchestration/worker-host.ts";
 
 // ── workflow 创作闭环面（orchestration/script-generate + workflow-files，W4）──
 // generateWorkflowScript：generate 校验管线（五道闸 + @pi-meta round-trip + tmp
 // 写盘）从 pi-sw 插件层下沉（D-6）——纯函数返回结构化结果（不 throw，pi 的
 // isError 契约转换由宿主负责），报错文案逐字对齐 pi 现版（CA2 前提）。
-// saveWorkflow/deleteWorkflow 首次出 barrel：宿主（zsw）generate→save→delete
-// 创作闭环的完整入口；目录经 WorkflowDirOptions 注入（缺省 pi 布局
-// DEFAULT_WORKFLOW_TMP_DIR / DEFAULT_WORKFLOW_SAVED_DIR，向后兼容——pi 现深路径
-// 调用形态行为不变，改接在 C5）。
+// saveWorkflow/deleteWorkflow（上方已导出）+ 目录经 WorkflowDirOptions 注入
+// （缺省 pi 布局 DEFAULT_WORKFLOW_TMP_DIR / DEFAULT_WORKFLOW_SAVED_DIR，向后兼容
+// ——pi 现深路径调用形态行为不变，改接在 C5）。
 export { generateWorkflowScript } from "./orchestration/script-generate.ts";
 export type {
   GenerateWorkflowScriptOptions,
   GenerateWorkflowScriptResult,
 } from "./orchestration/script-generate.ts";
-export { deleteWorkflow, saveWorkflow } from "./orchestration/workflow-files.ts";
 export type { WorkflowDirOptions } from "./orchestration/workflow-files.ts";
 // 缺省目录常量随面导出：宿主显式注入 pi 缺省布局时引用常量，避免字面硬编码回流。
 export {
@@ -209,61 +482,92 @@ export type {
 // FileRunStore：RunStore port 的宿主无关文件实现（D2 设计件）——落盘
 // <dataRoot>/workflow-state/<runId>.jsonl，zsw 等无 pi session 设施的宿主装配
 // LifecycleDeps.store 用；pi 壳继续用 session 锚定的 JsonlRunStore。
-export { FileRunStore } from "./orchestration/file-run-store.ts";
+// DEFAULT_* 两常量：壳 jsonl-run-store.ts 生产消费（D3 判定进 barrel），
+// u-2c 删 ./* 通配后深路径仅测试侧 vitest alias 可解析，生产消费必须走 barrel。
+export {
+  DEFAULT_SAVE_MIN_INTERVAL_MS,
+  DEFAULT_STATE_MAX_RUNS,
+  FileRunStore,
+} from "./orchestration/file-run-store.ts";
 
-// RunStore / AgentRunner / WorkerHost port 契约类型：宿主自写 Infra 实现
-// （如 zsw 的 RunnerPort 桥接）需要契约面；WorkerHandlers 已随 WorkerHost 注释。
-export type {
-  AgentRunner,
-  RunStore,
-  WorkerHandlers,
-  WorkerHost,
-} from "./orchestration/models/ports.ts";
+// ── 快照 codec（U8 / D4）──────────────────────────────────────
+// WorkflowRun ↔ 落盘快照的单一投影：版本常量沿用 pi "wf-run-v2"（存量逐字节
+// 可读）、live 字段 strip、更高版本跳过（宿主侧 warn 可见性自决）。
+export {
+  fromRunSnapshot,
+  SNAPSHOT_VERSION,
+  toRunSnapshot,
+  type RunSnapshot,
+} from "./orchestration/run-snapshot.ts";
 
-// ── zcode 引擎注册面（execution/engine）──────────────────────
-// registerZcodeEngine：把 'zcode' 引擎登记进 registry（组合根职责，幂等）；
-// createZcodeEngine：DI 工厂（测试/宿主注入 deps）。ZcodeEngineDeps 经
-// registration.ts 的 re-export 导出（避免与 zcode-engine.ts 双源）。
+// run 投影（U7 / D8）：isScriptRunning / runSummary 以 core WorkflowRun 为准的
+// 投影（runSummary 双投影分叉收口）。
 export {
-  createZcodeEngine,
-  registerZcodeEngine,
-} from "./execution/engine/engines/zcode/registration.ts";
-export type { ZcodeEngineDeps } from "./execution/engine/engines/zcode/registration.ts";
+  isScriptRunning,
+  runSummary,
+  type WorkflowRunSummary,
+} from "./orchestration/workflow-run-summary.ts";
 
-// killAllSpawnedChildren：session 关闭时批量回收 agent 子进程（宿主 shutdown
-// 钩子消费；子进程注册表在 session-runner 模块内）。
-export { killAllSpawnedChildren } from "./execution/session-runner.ts";
+// ── schema 助手（U9 / D9）─────────────────────────────────────
+// workflow 资产 @pi-meta parameters 的 schema→已知键集、平铺参数检测与
+// 归一化（pi tool-workflow 消费面下沉；宿主白名单退役入口）。
+export {
+  argKeysFromMeta,
+  findFlattenedArgKeys,
+  normalizeArgsByMeta,
+  type ArgKeySet,
+  type ArgMetaOptions,
+  type ArgMetaWarning,
+  type NormalizedArgs,
+} from "./orchestration/args-meta.ts";
 
-// ═══════════════════════════════════════════════════════════════════
-// sink 下沉收口扩面（docs/design/subagent-core-sink-design.md，2026-08-31）
-//
-// D2 裁决：本分隔线以下全部为纯新增导出——上方既有导出符号与路径零变更
-//（pi 24 处深路径 import 与 zsw vendor sha256 manifest 双不受波及）。
-// 按域分组逐名列出（不使用 `export *`，沿用本文件既有纪律使 diff 可审）。
-//
-// semver 分档：运行时面一组标注 @experimental（一个 minor 周期内允许签名
-// 微调，D6）；其余各组为常规 semver 稳定面。
-// ═══════════════════════════════════════════════════════════════════
+// ── 共享原语（shared/）───────────────────────────────────────
+// agent 展示名归一（渲染层 7 处消费的 SSOT）+ meta 解析 / XML 注入 / 资源发现 /
+// thinking 档位序（THINKING_ORDER 定义源 shared/model-ref，model-resolver 为转发）。
+export { displayAgentName } from "./shared/agent-ref.ts";
+export {
+  parseResourceMeta,
+  parseResourceMetaDetailed,
+} from "./shared/meta-parser.ts";
+export { THINKING_ORDER } from "./shared/model-ref.ts";
+// 定时器上限（壳 tool-workflow.ts OR-1 消费，D3 判定进 barrel）
+export { MAX_TIMER_DELAY_MS } from "./shared/timer-delay.ts";
+// 资源发现面（W2③）：discoverResources——agent .md / workflow .js 的多源统一发现
+// （ADR-031）——多源扫描 + stem last-writer-wins 合并 + realpath 去重。宿主（zsw
+// 回接）经 ScanConfig.hostRoots 注入发现根（source 标签即 ResourceSource 槽位键，
+// 含 project-host 项目级槽）；深路径消费在 npm/vendored 发布形态不可达（exports 无
+// 深路径通配），故出 barrel。发现链辅助（C5b）：findWorkspaceRoot（project 源根
+// 定位）、getCachedParsed/getCachedFileContent（mtime 缓存读取）——发现链消费方
+// （pi-sw injector 等宿主接线）逐条解析 DiscoveredResource 的 frontmatter/meta
+// 需要它们，深路径同样不可达。
+export {
+  discoverResources,
+  findWorkspaceRoot,
+  getCachedFileContent,
+  getCachedParsed,
+} from "./shared/resource-discovery.ts";
+export type {
+  DiscoveredResource,
+  ResourceKind,
+  ResourceSource,
+  ScanConfig,
+} from "./shared/resource-discovery.ts";
+export { escapeXml, renderXmlSection } from "./shared/xml-injection.ts";
 
 // ── agent-ref 面（契约原语，U1）────────────────────────────────
 // agent 引用规范化（normalizeRef 含 `..` 段拒绝——G4 声明的唯一行为收紧，
-// ⛔2 样本集验证）+ 引用扩展名常量 + 显示名投影 + 报错文案工厂 +
-// slug 长度上限 + 进程活性探针（watchdog/孤儿判定共用）。
+// ⛔2 样本集验证）+ 引用扩展名常量 + 报错文案工厂。
 export {
   AGENT_REF_EXT,
-  displayAgentName,
   invalidAgentRefMessage,
   normalizeRef,
   type InvalidAgentRefMessageOptions,
   WORKFLOW_REF_EXT,
 } from "./shared/agent-ref.ts";
-export { SLUG_MAX_LENGTH } from "./execution/execute-options-mapper.ts";
-export { isProcessAlive } from "./execution/alive-store.ts";
 
 // ── workflow 契约面（U1）──────────────────────────────────────
-// workflow 引用规范化（名/路径二分 + 保留字裁决，knownNames 宿主注入——
-// 内置 workflow 名不 core 硬编码）+ WorkflowScript 实体与按路径加载工厂
-//（第三宿主零复刻脚本加载，G3/S5）。
+// workflow 引用规范化（名/路径二分 + 保留字裁决，knownNames 宿主注入——内置
+// workflow 名不 core 硬编码）。
 export {
   normalizeWorkflowRef,
   WORKFLOW_REF_RESERVED_NAMES,
@@ -271,169 +575,35 @@ export {
   type NormalizedWorkflowRef,
   type WorkflowRefInvalidReason,
 } from "./shared/agent-ref.ts";
-export {
-  loadWorkflowScriptByPath,
-  WorkflowScript,
-} from "./orchestration/workflow-script-registry-impl.ts";
-
-// ── 执行预算原语（U3/U4 / D7）─────────────────────────────────
-// maxTurns→watchdog 毫秒换算（floor 语义文档化——两宿主预算一致性 S2 的函数级
-// 锚点）+ 并发池工厂（queuePolicy 缺省 priority 保 pi 行为，zsw 消费 strict-fifo
-// ——策略差异显式化而非双实现）。
-export { maxTurnsToWatchdogMs } from "./execution/session-runner.ts";
-export {
-  createConcurrencyPool,
-  type ConcurrencyPool,
-  type CreateConcurrencyPoolOptions,
-  type QueuePolicy,
-} from "./execution/concurrency-pool.ts";
 
-// ── 模型引用切分原语（U1 契约面批件）─────────────────────────
-// provider/model 引用切分与缺省值（两宿主 maxTurns/model 换算同源）；
-// 实现体内聚 zcode preparer/constants 不挪文件，barrel re-export（§5.3）。
-export {
-  DEFAULT_PROVIDER_ID,
-  hasApiKey,
-  splitZcodeModelRef,
-} from "./execution/engine/engines/zcode/preparer.ts";
-export { ZCODE_FALLBACK_DEFAULT_MODEL } from "./execution/engine/engines/zcode/constants.ts";
-
-// ── worktree git 内核（U5 / D5）───────────────────────────────
-// git 语义纯函数单源：保真读（gitRun）、SafeId 校验、dirty 谓词、
-// collectWorktreePatch（统一 add+diff 基线机制，返回结构即 patchIncomplete
-// 留痕载体）、三步容错清理、listWorktreePorcelain（原始输出供宿主 realpath
-// 对账）。锚点缺失/损坏与 add 失败两条降级路径 warn + 留痕（⛔3）。
-//
-// GitRunError 同名双类裁决（u-core-exec-export 交接）：worktree-manager.ts 与
-// worktree-git-ops.ts 各有一个 GitRunError（文案同但类独立）——barrel 只导出
-// 本组 worktree-git-ops 版（git 语义新单源）；worktree-manager 版不进 barrel，
-// 将来 manager 收缩到 git-ops 内核时随之消除。
-export {
-  assertSafeId,
-  cleanupWorktree,
-  collectWorktreePatch,
-  GitRunError,
-  gitRun,
-  isSafeId,
-  isTreeDirty,
-  listWorktreePorcelain,
-  SAFE_ID_RE,
-  type CleanupWorktreeOptions,
-  type CollectWorktreePatchOptions,
-  type ListWorktreePorcelainOptions,
-  type PatchBaselineAnchor,
-  type WorktreePatchResult,
-} from "./execution/worktree-git-ops.ts";
-
-// ── 运行时面（@experimental，U10 / D6）────────────────────────
-// SubagentService 构造依赖参数注入（modelService 等，无全局查找）+
-// record 状态查询面（RecordStore 按状态枚举/按 id；lookupRecordAnyState
-// 全态查询）+ record 落盘 entry 契约 + agent-registry 执行消费面
-//（loadByPath 直接加载）+ 动作层领域内核（六 handler 的校验/守卫链/
-// 归属判定/终态映射，产出领域对象，宿主 adapter 负责包装渲染）+
-// 错误类型族（instanceof 分流用）。
-//
-// @experimental：本组全部导出在一个 minor 周期内允许签名微调，稳定后转
-// 常规 semver 承诺（D6 语义，各源文件符号注释同款声明）。
-//
-// SubagentServiceSessionInit 刻意不出 barrel：pi session_start 注入专属
-//（引用未导出的 PiLike 签面），第三宿主不经该流程。
-//
-// ModelConfigService：SubagentServiceInit.modelService 的构造依赖（MF-4：jsdoc
-// 示例 `new ModelConfigService({cwd, agentDir})` 的类此前不在导出面——第三宿主
-// 按文档用法不可构造）。getModelConfigService 同为 SubagentService 类 jsdoc
-// session_start 示例的引用符号，随之可达；setModelConfigService 是 pi 壳
-// session_start 专属的进程单例写入点，第三宿主参数注入构造不需要，刻意不出 barrel。
-export {
-  getModelConfigService,
-  ModelConfigService,
-  type ModelConfigServiceInit,
-} from "./execution/model-config-service.ts";
-export {
-  createSubagentService,
-  SubagentService,
-  type SubagentServiceInit,
-} from "./execution/subagent-service.ts";
-export {
-  RecordStore,
-  type ChangeListener,
-  type RecordStorePi,
-  type StatusFilter,
-} from "./execution/record-store.ts";
-export {
-  SUBAGENT_RECORD_CUSTOM_TYPE,
-  toSubagentRecordEntry,
-  type SubagentRecordEntryData,
-} from "./execution/record-entry.ts";
-export { AgentRegistry } from "./execution/agent-registry.ts";
-// 错误类型族（error-recovery.ts 计划路径实测不存在，实测散布于下列源文件）：
-// resurrect/fork-depth/dirty-worktree 为动作层守卫抛出点（types.ts），
-// GitRunError 见 worktree 内核组裁决。
-export {
-  DirtyWorktreeError,
-  ForkDepthExceededError,
-  ResurrectDeniedError,
-} from "./execution/types.ts";
+// ── 注入渲染面（shared/injection-render，W3）───────────────────
+// 三段 XML（<available_subagents>/<available_workflows>/<available_provider_models>）
+// 的 format 纯函数 + Entry 接口从 pi-sw 插件层下沉（D-3）：ModelEntry 并集口径
+// （除 id/name 外全字段 optional，红线 5 守卫不抛不渲垃圾）、分段条目预算
+// （码点序排 + 截尾 + 宿主注入兜底指引；models 段无预算永不截，红线 7）、
+// guide 文案宿主注入（core 不内嵌平台文案）。summarizeDescription 随
+// WorkflowEntry 链导出（zsw 侧同口径消费）。
 export {
-  BG_MESSAGE,
-  cancelHandler,
-  closeHandler,
-  DEFAULT_LIST_LIMIT,
-  endedMessageGuard,
-  FORK_FROM_DEFAULT_PROMPT,
-  forkFromHandler,
-  listHandler,
-  mapExternalState,
-  MAX_LIST_LIMIT,
-  messageHandler,
-  NOTIFY_CONTRACT,
-  recordToListItem,
-  startHandler,
-  wrapForkFromPrompt,
-  type CancelHandlerInput,
-  type CancelHandlerResult,
-  type CloseHandlerInput,
-  type CloseHandlerResult,
-  type ForkFromHandlerInput,
-  type ForkFromHandlerResult,
-  type ListHandlerInput,
-  type ListHandlerResult,
-  type MessageHandlerInput,
-  type MessageHandlerResult,
-  type StartHandlerInput,
-  type StartHandlerResult,
-} from "./execution/subagent-actions-core.ts";
-// 运行时面类型闭包（先例同 ModelInfo/SubagentStream：签名直接引用的具名类型
-// 显式导出，免宿主深路径兜圈；二阶成员类型不强制——结构化类型下实例可用）。
+  formatAgentList,
+  formatModelList,
+  formatWorkflowList,
+  sortByCodepoint,
+  summarizeDescription,
+} from "./shared/injection-render.ts";
 export type {
-  BgResponse,
-  CancelResponse,
-  CloseResponse,
-  ExecutionRecord,
-  ExecutionStatus,
-  ExternalState,
-  ForkFromResponse,
-  ListResponse,
-  MessageResponse,
-  SubagentListItem,
-  SubagentRecord,
-} from "./execution/types.ts";
-
-// ── 快照 codec（U8 / D4）──────────────────────────────────────
-// WorkflowRun ↔ 落盘快照的单一投影：版本常量沿用 pi "wf-run-v2"（存量逐字节
-// 可读）、live 字段 strip、更高版本跳过（宿主侧 warn 可见性自决）。
-export {
-  fromRunSnapshot,
-  SNAPSHOT_VERSION,
-  toRunSnapshot,
-  type RunSnapshot,
-} from "./orchestration/run-snapshot.ts";
+  AgentEntry,
+  ListFormatOptions,
+  ModelEntry,
+  ModelListFormatOptions,
+  ModelReasoningInfo,
+  WorkflowEntry,
+} from "./shared/injection-render.ts";
 
 // ── 原语（U6a）────────────────────────────────────────────────
 // atomic-write：tmp+rename 原子写单一实现（统一 tmp 命名 `.tmp.<pid>.<seq>-<rand>`、
 // 失败清理、崩溃残留扫描/清理入口）——core 内部全部写点已收敛于此（U6b）；
 // sync/async 两档耐久语义见模块头。bounded-serialize：预算内 JSON 序列化
-//（自 pi-sw helpers 平移，输出逐字节一致）。
+// （自 pi-sw helpers 平移，输出逐字节一致）。
 export {
   atomicTmpPathFor,
   cleanupStaleTmpFiles,
@@ -448,47 +618,3 @@ export {
   type CleanupStaleTmpResult,
 } from "./shared/atomic-write.ts";
 export { boundedPrettySerialize } from "./shared/bounded-serialize.ts";
-
-// ── 组装层（U2 装配 + U7 生命周期 / D8）───────────────────────
-// discoverAgents：发现→宽容解析→去重→码点序（workflow 侧 discoverWorkflows
-// 对称面，第三宿主「列 agents」入口）；recoverCrashedRuns：崩溃恢复四步装配
-//（宿主事件经 hooks 外置）；runSummary/isScriptRunning：以 core WorkflowRun
-// 为准的投影（runSummary 双投影分叉收口）；WorkflowRun 聚合根随闭包出 barrel。
-export { discoverAgents } from "./execution/agents-assembly.ts";
-export {
-  recoverCrashedRuns,
-  type RecoverCrashedRunsHooks,
-  type RecoverCrashedRunsResult,
-} from "./orchestration/lifecycle.ts";
-export {
-  isScriptRunning,
-  runSummary,
-  type WorkflowRunSummary,
-} from "./orchestration/workflow-run-summary.ts";
-export {
-  WorkflowRun,
-  type WorkflowRunMeta,
-} from "./orchestration/models/workflow-run.ts";
-export type { DoneReason, RunStatus } from "./orchestration/models/types.ts";
-
-// ── schema 助手（U9 / D9）─────────────────────────────────────
-// workflow 资产 @pi-meta parameters 的 schema→已知键集、平铺参数检测与
-// 归一化（pi tool-workflow 消费面下沉；宿主白名单退役入口）。
-export {
-  argKeysFromMeta,
-  findFlattenedArgKeys,
-  normalizeArgsByMeta,
-  type ArgKeySet,
-  type ArgMetaOptions,
-  type ArgMetaWarning,
-  type NormalizedArgs,
-} from "./orchestration/args-meta.ts";
-
-// ── 解析面（U2 / D3）──────────────────────────────────────────
-// parseAgentProfile：宽容解析（无 frontmatter 不拒、name 缺省 stem、返回
-// body 与执行字段全量）——执行消费面单点；与严格注入投影（parseResourceMeta）
-// 双轨分离的执行侧统一入口。
-export {
-  parseAgentProfile,
-  type AgentProfile,
-} from "./execution/agent-registry.ts";