@zhushanwen/pi-subagent-workflow 8.7.0 → 8.8.1

package/src/index.ts

@@ -13,54 +13,30 @@
  * 设计基线：D-004（旧包不动）/ ADR-025（进程内执行）/ D-8（pi.__workflowRun 签名）。
  */
 
-import * as fs from "node:fs";
-import * as path from "node:path";
-
-import type { BeforeAgentStartEvent, ExtensionAPI, ExtensionContext, SessionCompactEvent, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
+import type { ExtensionAPI, ExtensionContext, SessionCompactEvent, SessionShutdownEvent, SessionStartEvent, SessionTreeEvent } from "@earendil-works/pi-coding-agent";
 import { getAgentDir } from "@earendil-works/pi-coding-agent";
 import { getLogger, setPiHandle } from "@zhushanwen/pi-extension-logger";
 
 // ═══ core 宿主端口接线（subagent-core 包抽离 u0-wire；实现见 src/host/pi-host.ts） ═══
-import { configureCore } from "@zhushanwen/subagent-core/core/host-services.ts";
-import { configureNotifyDomain } from "@zhushanwen/subagent-core/core/notify-ports.ts";
+import { configureCore } from "@zhushanwen/subagent-core";
+import { configureNotifyDomain } from "@zhushanwen/subagent-core";
 import { createPiHostServices, createPiNotifyDomainPorts } from "./host/pi-host.ts";
 
-import { bestEffort } from "@zhushanwen/subagent-core/execution/best-effort.ts";
+import { bestEffort } from "@zhushanwen/subagent-core";
 // ═══ execution/ 层（subagents 核心 + 运行时） ═══
-import { getOrCreateChannelRegistry } from "@zhushanwen/subagent-core/execution/channel-registry-access.ts";
-import { DialogGlobalQueue } from "@zhushanwen/subagent-core/execution/dialog-queue.ts";
-// [engine-awareness U3] 全局 config 三态读取（检测 poll 与 session_start 基线共用）
-import { readGlobalConfig } from "@zhushanwen/subagent-core/execution/config.ts";
 // [U7] 引擎列表状态文件（registry → engines.json，GUI 引擎选择器数据源）
-import { syncEnginesFile } from "@zhushanwen/subagent-core/execution/engine/engine-discovery.ts";
-// [U7] 引擎模型段注入（defaultEngine 非 pi 时 system prompt 补 <available_<engine>_models>）
-// [engine-awareness U3] 补恒在状态段 <current_subagent_engine>（D6，pi 引擎也声明）
-import { buildEngineModelsPromptAppend, buildSubagentEngineSection } from "@zhushanwen/subagent-core/execution/engine/model-prompt.ts";
+import { syncEnginesFile } from "@zhushanwen/subagent-core";
 // [P1 引擎接线] 组合根登记 'pi' 引擎进 registry（引擎获取统一经 getEngine，缺省 id 'pi'）
-import { registerPiEngine } from "@zhushanwen/subagent-core/execution/engine/engines/pi/registration.ts";
+import { registerPiEngine } from "@zhushanwen/subagent-core";
 // [P3 引擎接线] 组合根登记 'zcode' 引擎（spawn 单轮模式；engineDataDir 默认走
 // common/data-dir SSOT，见 engines/zcode/registration.ts）
-import { registerZcodeEngine } from "@zhushanwen/subagent-core/execution/engine/engines/zcode/registration.ts";
-import { createUiRequestHandlerForMode } from "@zhushanwen/subagent-core/execution/ui-request-handler-factory.ts";
-import {
-  getModelConfigService,
-  ModelConfigService,
-  setModelConfigService,
-} 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 { maybeCleanupExpiredSessionFiles } from "@zhushanwen/subagent-core/execution/session-file-gc.ts";
-import {
-  getSubagentService,
-  setSubagentService,
-  SubagentService,
-} from "@zhushanwen/subagent-core/execution/subagent-service.ts";
-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";
+import { registerZcodeEngine } from "@zhushanwen/subagent-core";
+import { getModelConfigService } from "@zhushanwen/subagent-core";
+import { getBoundNotifyLedger } from "@zhushanwen/subagent-core";
+import { getSubagentService } from "@zhushanwen/subagent-core";
+import { killAllSpawnedChildren } from "@zhushanwen/subagent-core";
+// [engine-awareness U3/D7-④] per-turn 引擎检测编排 + before_agent_start 链尾接线
+import { setupEngineAwarenessInjector } 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";
@@ -73,20 +49,26 @@ import { registerSubagentTool } from "./interface/subagent-tool.ts";
 import { registerSubagentsCommand } from "./interface/subagents.ts";
 import { registerWorkflowTool } from "./interface/tool-workflow.ts";
 import { registerWorkflowScriptTool } from "./interface/tool-workflow-script.ts";
-import { JsonlRunStore } from "./jsonl-run-store.ts";
-import { clearSkillPathCache } from "@zhushanwen/subagent-core/orchestration/skill-discovery.ts";
 // ═══ orchestration/ 层（workflow engine + infra） ═══
-import type { LauncherDeps } from "@zhushanwen/subagent-core/orchestration/launcher.ts";
-import { executeNestedWorkflow, runAndWait, type WorkflowRunResult } from "@zhushanwen/subagent-core/orchestration/launcher.ts";
+import type { LauncherDeps } from "@zhushanwen/subagent-core";
+import { executeNestedWorkflow, runAndWait, type WorkflowRunResult } from "@zhushanwen/subagent-core";
 import {
   evictDoneRunsBeyondCap,
   MAX_RETAINED_DONE_RUNS,
   scheduleTimeBudget,
   terminateRunningRuns,
-} from "@zhushanwen/subagent-core/orchestration/lifecycle.ts";
-import type { WorkflowRun } from "@zhushanwen/subagent-core/orchestration/models/workflow-run.ts";
-import { WorkerHostImpl } from "@zhushanwen/subagent-core/orchestration/worker-host.ts";
-import { WorkflowScriptRegistryImpl } from "@zhushanwen/subagent-core/orchestration/workflow-script-registry-impl.ts";
+} from "@zhushanwen/subagent-core";
+import type { WorkflowRun } from "@zhushanwen/subagent-core";
+import { WorkerHostImpl } from "@zhushanwen/subagent-core";
+import { WorkflowScriptRegistryImpl } from "@zhushanwen/subagent-core";
+// ═══ session 生命周期装配 seam（bootstrap seam，设计 §3.1/D1） ═══
+import {
+  getOrCreateDialogQueue,
+  setupSessionLifecycle,
+  type SessionLifecycleDeps,
+  type SessionLifecycleResult,
+} from "./session-lifecycle.ts";
+import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
 // ── pi.__workflowRun 类型扩展（D-8 签名） ─────────────────
 
@@ -106,42 +88,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 强杀或崩溃时来不及
@@ -160,7 +106,7 @@ function reapSpawnedChildrenOnShutdown(): void {
     // 不静默吞错，对齐「错误必须可操作」。
     logger.debug(
       "[subagents] process shutdown reap best-effort failed (killAllSpawnedChildren SIGTERM)",
-      { reason: err instanceof Error ? err.message : String(err) },
+      { reason: toErrorMessage(err) },
     );
   }
 }
@@ -224,36 +170,14 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   setupWorkflowListInjector(pi);
   setupModelListInjector(pi);
 
-  // 模块级缓存：主 session 的 sessionFile（fork source 解析用）。
-  let cachedMainSessionFile: string | undefined;
-  function getCachedMainSessionFile(): string | undefined {
-    return cachedMainSessionFile;
-  }
-
-  /**
-   * 按 sessionId 解析主 session 文件路径（文件名约定 `<ISO 时间戳>_<sessionId>.jsonl`）。
-   * [E2E 实测] attach 场景下 ctx.sessionManager.getSessionFile() 会返回前一 session 的
-   * 文件（session_start(root=01a01bf5) 时仍返回刚新建 session 的路径）——恢复逻辑
-   * 读错文件会整段漏判。此处按 id 从 sessions 目录解析为准；新 session 文件未 flush
-   * 时（AGENTS.md 规则 6：首条 assistant 消息前可能不存在）返回 undefined，调用方
-   * （fork 解析 / 孤儿恢复）对该场景本就无 entry 可读。
-   */
-  function resolveMainSessionFileById(sessionId: string): string | undefined {
-    const sessionsDir = path.join(getAgentDir(), "..", "sessions");
-    try {
-      const match = fs.readdirSync(sessionsDir).find((f) => f.endsWith(`_${sessionId}.jsonl`));
-      return match === undefined ? undefined : path.join(sessionsDir, match);
-    } catch {
-      return undefined;
-    }
-  }
+  // [主 session 文件解析随迁] cachedMainSessionFile 缓存与 resolveMainSessionFileById
+  // 随 session_start 装配块整体迁入 session-lifecycle.ts（唯一消费方是随迁块；
+  // SubagentService 的 getMainSessionFile getter 由 createOrReuseServices 提供）。
 
-  // 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
@@ -266,31 +190,13 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   const workerHost = new WorkerHostImpl();
   const registry = new WorkflowScriptRegistryImpl();
 
-  // SAR 改为 per-session 构造（需要 ctxModel 填底 D-008 + subagentService 委托目标）
-  // old: const runner = new SubprocessAgentRunner();
-  // new: per-session session_start 时创建，见下方 makeDeps 前的 runner 创建
-
-  // per-session 状态（session_start 时重建）
-  const sessionState = new Map<
-    string,
-    {
-      store: JsonlRunStore;
-      runs: Map<string, WorkflowRun>;
-      sessionDir: string;
-      /** D-008 per-session SAR（需要 ctxModel + subagentService） */
-      runner: SubprocessAgentRunner;
-      /** session 上下文（notifyDone 需要 GuiContext） */
-      ctx?: ExtensionContext;
-      /** MF-1: store 健康度。session_start 时 store.loadAll 失败则置 false，
-       *  workflow 域启动时 fail-fast，避免后续 store.save 再次失败导致 run 状态不落地。
-       *  subagent 域不依赖 store，不受此标志影响。 */
-      storeHealthy: boolean;
-      /** [engine-awareness D1b] 上一次已知默认引擎（session_start 初始化，per-turn 检测
-       *  diff 基准）。undefined = 初始化时 config 读失败——首 turn 检测遇 undefined
-       *  静默基线化，不算变更、不发通知（防首 turn 伪通知）。 */
-      lastEngine?: string;
-    }
-  >();
+  // SAR 改为 per-session 构造（需要 ctxModel 填底 D-008 + subagentService 委托目标），
+  // 构造点随 session_start 装配块迁入 session-lifecycle.ts，经 SessionLifecycleResult
+  // 传回（见 setupSessionLifecycle）。
+
+  // per-session 状态（session_start 时重建）。value = SessionLifecycleResult
+  // （setupSessionLifecycle 装配结果，ctx 必有）。
+  const sessionState = new Map<string, SessionLifecycleResult>();
 
   function log(
     level: "debug" | "info" | "warn" | "error",
@@ -311,21 +217,20 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     }
   }
 
-  function resolveSessionDir(): string {
-    const defaultDir = getAgentDir();
-    const sessionSlug = `--${process.cwd().replace(/^\//, "").replace(/\//g, "-")}--`;
-    // F2：根改 getAgentDir() 派生（实例隔离）；保留 sessionScopedDir 存在则用之的探测语义
-    const sessionScopedDir = path.join(getAgentDir(), "sessions", sessionSlug);
-    return fs.existsSync(sessionScopedDir) ? sessionScopedDir : defaultDir;
+  // [workflow state 目录解析随迁] resolveSessionDir 随 session_start 装配块整体迁入
+  // session-lifecycle.ts（唯一消费方是随迁块）。
+
+  /** 组合根侧生产 deps 工厂：SessionLifecycleDeps 全部成员有生产默认实现（住
+   *  session-lifecycle.ts——createOrReuseServices 单例语义 / WorktreeManager 每次
+   *  扫描新建 / JsonlRunStore per-session 新建），此处无本地构造可注入；工厂形态
+   *  保留为 index 侧注入点（测试或后续演进可在此覆盖）。
+   *  测试注入路径：不挂载 index.ts，直接调 setupSessionLifecycle(pi, ctx, fakeDeps)。 */
+  function makeLifecycleDeps(): SessionLifecycleDeps {
+    return {};
   }
 
   function makeDeps(
-    state: {
-      store: JsonlRunStore;
-      runs: Map<string, WorkflowRun>;
-      sessionDir: string;
-      runner: SubprocessAgentRunner;
-    },
+    state: Pick<SessionLifecycleResult, "store" | "runs" | "sessionDir" | "runner">,
     sessionCtx?: ExtensionContext,
   ) {
     const deps: LauncherDeps = {
@@ -373,284 +278,16 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
 
   // ════════════════════════════════════════════════════════════
   //  session_start：初始化 subagents + workflow 两域
+  //
+  //  六职责编排（identity 重建 / ledger 装配 / 双 Service 装配 / GC+恢复 / kill-9
+  //  循环 / SAR+engine 基线）已随迁 session-lifecycle.ts（bootstrap seam，设计
+  //  §3.1/D1/D2 原样搬移）。此处仅接线：lastSessionId 先行赋值（时序与原 handler
+  //  开头一致）+ 装配结果写入 per-session sessionState。
   // ════════════════════════════════════════════════════════════
   pi.on("session_start", async (_event: SessionStartEvent, ctx: ExtensionContext) => {
-    const cwd = ctx.cwd;
-    const agentDir = getAgentDir();
-    const sessionId = ctx.sessionManager.getSessionId();
-    lsRef.lastSessionId = sessionId;
-
-    // [U7] 引擎列表同步 engines.json（幂等零写 + fail-safe；组合根注册已在
-    // extension 工厂体完成，此处 registry 已含全部引擎）
-    syncEnginesFile(agentDir);
-
-    // skill 路径两级缓存 session 级失效：pi 同进程可能有多个 session（TUI /new、/fork），
-    // 运行中安装的 skill 需对新 session 可见（含曾 miss 缓存的 undefined 条目与 npm 新装
-    // 包的候选目录）。session 内复用收益不变（IF8/DM3 消重发生在同 session 的重复调用）。
-    clearSkillPathCache();
-
-    // ── [M4] identity 子进程写入（V2 决策 5）──
-    // 子进程经 env（PI_SUBAGENT_*）接收自己的 identity，在 session_start 用 pi.appendEntry
-    // 写 subagent-identity custom entry。pi 自动生成 id/parentId → message tree 连续。
-    // 旧实现父进程 fs.appendFileSync 补写的 custom entry 缺 id/parentId → 污染 _buildIndex
-    // leafId 指针 → message tree 断成两棵 → 多轮对话丢上下文（bug 根因）。
-    // 主/子进程判定：PI_SUBAGENT_SELF_RECORD_ID 仅 session-runner spawn 子进程时注入，
-    // 主进程无此 env → 跳过（identity 只在子进程写一次）。
-    const selfRecordId = process.env.PI_SUBAGENT_SELF_RECORD_ID;
-    if (selfRecordId) {
-      try {
-        const modeEnv = process.env.PI_SUBAGENT_MODE;
-        // ExecutionMode 联合窄化：父进程经 env 注入（record.mode 恒为 "background"），
-        // 运行时校验合法值，非法兜底 background（避免裸 cast，符合 taste/no-unsafe-cast）。
-        const mode: ExecutionMode = modeEnv === "background" ? modeEnv : "background";
-        const identity: SubagentIdentityData = {
-          id: selfRecordId,
-          agent: process.env.PI_SUBAGENT_AGENT ?? "",
-          mode,
-          task: process.env.PI_SUBAGENT_TASK ?? "",
-          slug: process.env.PI_SUBAGENT_SLUG,
-          startedAt: Number(process.env.PI_SUBAGENT_STARTED_AT ?? Date.now()),
-          rootSessionId: process.env.PI_SUBAGENT_ROOT_SESSION_ID,
-          parentRecordId: process.env.PI_SUBAGENT_PARENT_RECORD_ID,
-          depth:
-            process.env.PI_SUBAGENT_DEPTH !== undefined
-              ? Number(process.env.PI_SUBAGENT_DEPTH)
-              : undefined,
-          forkDepth:
-            process.env.PI_SUBAGENT_FORK_DEPTH !== undefined
-              ? Number(process.env.PI_SUBAGENT_FORK_DEPTH)
-              : undefined,
-          chatMode: process.env.PI_SUBAGENT_CHAT_MODE === "true",
-          // [review round2] worktree 隔离标志（session-runner 注入）：跨重启重建路径据此
-          // 拒绝续聊（handle 不可序列化，reattach 不可行）。
-          worktree: process.env.PI_SUBAGENT_WORKTREE === "true",
-        };
-        pi.appendEntry(IDENTITY_CUSTOM_TYPE, identity);
-      } catch (err) {
-        logger.warn("[subagents] identity appendEntry failed in session_start", {
-          reason: err instanceof Error ? err.message : String(err),
-        });
-      }
-    }
-
-    // ── [U2] 通知账本装配 + 重启恢复（设计 D4：存在性 / 可达性分离）──
-    // bind 先于 service.initSession（notifier.revive 在其内——notify() 经
-    // getBoundNotifyLedger 消费账本）。recoverFromSession 扫 ledger/ack 两列 entry
-    // 差集：未销账号重放投递（已销账零重发，notifyId 幂等）；fork 继承未销账
-    // pending 属可接受语义（D4 归属规则——扫描域 = 单 session 文件，幂等键作用域
-    // 随文件域隔离）。compaction 存活情况归 session_compact handler 的条件降级（P-B4
-    // 探针阶段 5 实测，见 notify-ledger.ts compactionCheck）。
-    try {
-      const ledgerHost: NotifyLedgerHost = {
-        appendLedgerEntry: (customType, data) => {
-          pi.appendEntry(customType, data);
-        },
-        readSessionEntries: () => ctx.sessionManager.getEntries(),
-        isIdle: () => ctx.isIdle(),
-        onAgentSettled: (handler) => {
-          pi.on("agent_settled", handler);
-        },
-        sendDelivery: (message) => {
-          // D5 单通道：唯一发送形态 = sendCustomMessage({triggerTurn:true})，
-          // courier 已在发送前二次复查 isIdle，多通道投递选项已删（D5）。
-          pi.sendMessage(message, { triggerTurn: true });
-        },
-      };
-      // U4：重放观测已内聚到 ledger 分桶日志（recoveryReplays 桶经 extensionLogger
-      // 通道落盘），此处不再重复打日志。
-      bindNotifyLedgerHost(ledgerHost).recoverFromSession();
-    } catch (err) {
-      // 账本装配失败不阻断 session_start（通知退回 notifier 的内核路径）
-      logger.warn("[subagents] notify ledger bind failed", {
-        reason: err instanceof Error ? err.message : String(err),
-      });
-    }
-
-    // ── subagents 域：双 Service 装配 ──
-    const existingService = getSubagentService();
-    const existingModelService = getModelConfigService();
-    const modelService = existingModelService ?? new ModelConfigService({ agentDir, cwd });
-    const service = existingService ?? new SubagentService({ cwd, modelService, getMainSessionFile: getCachedMainSessionFile });
-
-    modelService.initModel({
-      modelRegistry: ctx.modelRegistry,
-      sessionId: ctx.sessionManager.getSessionId(),
-      ctxModel: ctx.model ?? undefined,
-    });
-
-    // ── W3: handler 注入链路接通 ──
-    // 进程级单例：channel registry + dialog queue 跨 session 复用
-    //（与 SubagentService 单例模式一致，globalThis Symbol 持有避免 jiti 多实例分裂）。
-    const channelRegistry = getOrCreateChannelRegistry();
-    const dialogQueue = getOrCreateDialogQueue();
-    const uiRequestHandler = createUiRequestHandlerForMode(ctx, channelRegistry, dialogQueue);
-    // SR-3: 无论 new 还是 existing（/resume /fork 复用），session_start 都必须注入 handler
-    service.setUiRequestHandler(uiRequestHandler);
-
-    // 主 session 文件：按 sessionId 解析（getSessionFile() 在 attach 场景会返回前一
-    // session 的文件，E2E 实测），未 flush 的新 session 回退 getSessionFile()。
-    // 值直传 initSession——jiti 多实例分裂下闭包缓存（cachedMainSessionFile）不跨
-    // 实例共享，恢复逻辑经缓存读会拿到滞后一个事件的值（E2E 实测 ENOENT 漏判）；
-    // 缓存本身保留给既有 getter 消费者（fork source 解析）。
-    cachedMainSessionFile =
-      resolveMainSessionFileById(ctx.sessionManager.getSessionId()) ??
-      ctx.sessionManager.getSessionFile() ??
-      undefined;
-
-    service.initSession({
-      pi,
-      sessionId: ctx.sessionManager.getSessionId(),
-      mainSessionFile: cachedMainSessionFile,
-      // 注入 ctx.ui.setWidget 作为 streaming sink（只绑方法，不持有整个 ctx）。
-      // background subagent 执行期间，text_delta 经 SubagentStream 合并后由此通道转发。
-      // [W1 修复] ctx.mode === 'rpc' 守卫：TUI/json/print 下 streamSink = undefined（无 widget 噪音），
-      // rpc mode（GUI/xyz-agent）下保持原行为（ctx.ui.setWidget → sidecar → chatStore）。
-      // streamSink API 不变（SubagentStream.onDelta 仍可调，只是 TUI 下 stream 不会被创建）。
-      streamSink: ctx.mode === "rpc"
-        ? { setWidget: (key, lines) => ctx.ui.setWidget(key, lines) }
-        : undefined,
-      // [#24] uiRequestHandler 单一注入入口：上方 setUiRequestHandler 已注入（SR-3 语义，
-      // new/existing service 均覆盖）。此处不再重复传 initSession.uiRequestHandler，避免
-      // 同一 handler 双路径注入造成的语义混淆与“哪一个是 source of truth”歧义。
-      // mode 仍需 session 级注入（uiObservability.setMode 依赖它，与 handler 无关）。
-      mode: ctx.mode,
-      // SR-4：注入 L2 dialog 队列——session-runner child close 时调 rejectChildDialogs
-      // 清理该 child 在 L2 的 pending dialog，防全局死锁（C1 修复：清理路径接通）。
-      dialogQueue,
-      // [竞态修复] 注入 ctx.isIdle：notifier flush 在主 agent busy 时退避，idle 后再
-      // sendMessage(triggerTurn)，规避 agent_end→finishRun 窗口里走 steer 分支丢失通知。
-      isIdle: () => ctx.isIdle(),
-    });
-
-    if (!existingService) {
-      setModelConfigService(modelService);
-      setSubagentService(service);
-    }
-
-    // S-2: 启动 idle record GC 定时器（30 天 TTL，每小时检查一次）
-    service.startGcTimer();
-
-    try {
-      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 一致）。
-    try {
-      const recovered = await service.recoverManifestTmpFiles();
-      if (recovered.recovered > 0 || recovered.deleted > 0) {
-        logger.warn(`[subagents] manifest tmp recovery: ${recovered.recovered} promoted, ${recovered.deleted} deleted`);
-      }
-    } catch (err) {
-      logger.warn("[subagents] manifest tmp recovery failed", {
-        reason: err instanceof Error ? err.message : String(err),
-      });
-    }
-
-    try {
-      const wtm = new WorktreeManager(agentDir);
-      await wtm.scan();
-    } catch (err) {
-      logger.warn("[subagents] worktree reaper scan failed", {
-        reason: err instanceof Error ? err.message : String(err),
-      });
-    }
-
-    // ── workflow 域：per-session store + runs ──
-    const sessionDir = resolveSessionDir();
-    const store = new JsonlRunStore({
-      sessionDir,
-      pi,
-      ctx,
-    });
-    const runs = new Map<string, WorkflowRun>();
-
-    // F-4/D-003: agent 发现走 shared/resource-discovery（ADR-031），modelService
-    // 自持 AgentRegistry（subagents/workflow 两域共用同一发现结果）。
-    // M2 修正：workflow 域 resolveAgentOpts 不再消费 agentRegistry（agent ref 交
-    // resolveIdentity），无需经 state 透传——modelService 是唯一 registry 源。
-
-    // MF-1: store 健康度跟踪。loadAll 失败 → storeHealthy=false，workflow 域启动时 fail-fast。
-    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,
-        });
-      }
-    } catch (err) {
-      // QMF-4 fix: store.loadAll 失败是关键路径错误，workflow 域将未初始化
-      logger.error("[subagent-workflow] store.loadAll failed, workflow domain uninitialized", {
-        reason: err instanceof Error ? err.message : String(err),
-      });
-      storeHealthy = false;
-    }
-
-    // D-008: per-session SAR（需要 ctxModel 填底 + subagentService 委托目标）。
-    // old: const runner = new SubprocessAgentRunner()（module-level singleton，无 deps）
-    // new: per-session session_start 时创建，通过 sessionState 传给 makeDeps。
-    const runner = new SubprocessAgentRunner({
-      subagentService: service,
-      ctxModel: ctx.model ?? undefined,
-    });
-
-    // [engine-awareness D1b] lastEngine 初始化：构造性同源——单次 reloadGlobalConfig
-    // 读取同时刷新 Service 路由缓存与 lastEngine 基准，消灭 initModel 与本处两次独立
-    // 读取间的分叉窗口（两读值不一致时检测走 unchanged 分支不 reload，状态段/路由
-    // 永停旧值且永不通知）。ok/absent → 归一后的当前引擎；failed → undefined（首 turn
-    // 检测静默基线化兜底，此时缓存亦保持不动）。/resume、/fork 同样走 session_start
-    // （SR-3），基线天然覆盖。
-    const engineRead = modelService.reloadGlobalConfig();
-    sessionState.set(sessionId, {
-      store,
-      runs,
-      sessionDir,
-      runner,
-      ctx,
-      storeHealthy,
-      lastEngine:
-        engineRead.status === "failed" ? undefined : normalizeEngineId(engineRead.config.defaultEngine),
-    });
+    lsRef.lastSessionId = ctx.sessionManager.getSessionId();
+    const result = await setupSessionLifecycle(pi, ctx, makeLifecycleDeps());
+    sessionState.set(result.sessionId, result);
   });
 
   // ════════════════════════════════════════════════════════════
@@ -667,7 +304,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       }
     } catch (err) {
       logger.warn("[subagents] notify ledger compactionCheck failed", {
-        reason: err instanceof Error ? err.message : String(err),
+        reason: toErrorMessage(err),
       });
     }
   });
@@ -675,43 +312,16 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // ════════════════════════════════════════════════════════════
   //  [U7 + engine-awareness U3] before_agent_start：引擎感知注入（链尾注册，D7——
   //  段内容变化只断 system prompt 尾部 cache 前缀）。
-  //  ① per-turn 检测编排（§2.3 数据流）：三态 poll config → lastEngine diff →
-  //     变更时读取结果先行提交缓存（D2，applyGlobalConfig 纯赋值，本 turn 路由生效）
-  //     → sendMessage 通知
-  //     （D3，不设 triggerTurn——P1 探针已证此形态消息进入本 turn LLM 上下文，
-  //     证据：真机 pi rpc payload dump + 0.84.4 dist sendMessage→_appendCustomMessage
-  //     →agent.state.messages.push→createContextSnapshot 调用链）→ 更新 lastEngine。
-  //  ② 恒在状态段 <current_subagent_engine>（D6）+ 引擎清单段 <available_<engine>_models>。
-  //     apply 后 getGlobalConfig() 即新值——通知、状态段、路由三处同 turn 对齐（G2）。
-  //  段序：状态段在前（文案声明 "listed ... below"），清单段在后；provider models 段
-  //  由更早注册的 handler 注入、位于上方。fail-safe 任何异常不注入不阻塞 agent loop。
+  //  D7-④：接线收编于 engine-awareness.ts 的 setupEngineAwarenessInjector（与上方
+  //  三个 setup* 同形，注入链序由调用先后表达）；per-session lastEngine 经
+  //  sessionState 存取器注入。编排/渲染/链尾依据的完整注释随迁至该函数。
   // ════════════════════════════════════════════════════════════
-  pi.on("before_agent_start", (event: BeforeAgentStartEvent, ctx: ExtensionContext) => {
-    try {
-      const service = getModelConfigService();
-      if (service === null || typeof event.systemPrompt !== "string") return undefined;
-      const sid = ctx.sessionManager.getSessionId();
-      runEngineAwarenessTurn({
-        readConfig: () => readGlobalConfig(getAgentDir()),
-        applyRead: (read) => service.applyGlobalConfig(read),
-        sendMessage: (message) => {
-          // D3：不设 triggerTurn——切换是用户主动行为，无需唤醒 AI 立即行动
-          pi.sendMessage(message, {});
-        },
-        getLastEngine: () => sessionState.get(sid)?.lastEngine,
-        setLastEngine: (engine) => {
-          const state = sessionState.get(sid);
-          if (state) state.lastEngine = engine;
-        },
-      });
-      const defaultEngine = service.getGlobalConfig().defaultEngine;
-      const append = [buildSubagentEngineSection(defaultEngine), buildEngineModelsPromptAppend(defaultEngine)]
-        .filter((part) => part !== "")
-        .join("\n\n");
-      return { systemPrompt: `${event.systemPrompt}\n\n${append}` };
-    } catch {
-      return undefined;
-    }
+  setupEngineAwarenessInjector(pi, {
+    getLastEngine: (sid) => sessionState.get(sid)?.lastEngine,
+    setLastEngine: (sid, engine) => {
+      const state = sessionState.get(sid);
+      if (state) state.lastEngine = engine;
+    },
   });
 
   // ════════════════════════════════════════════════════════════
@@ -820,7 +430,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
       await state.store.dispose().catch((err: unknown) => {
         logger.debug(
           `[subagent-workflow] session_shutdown store.dispose failed (sessionId=${sessionId}, sessionDir=${state.sessionDir})`,
-          { reason: err instanceof Error ? err.message : String(err) },
+          { reason: toErrorMessage(err) },
         );
       });
       sessionState.delete(sessionId);
@@ -878,6 +488,32 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   process.on("SIGINT", sigintHandler);
   process.on("beforeExit", reapSpawnedChildrenOnShutdown);
 
+  // ════════════════════════════════════════════════════════════
+  //  workflow deps 守卫（单一出口）
+  //
+  //  [守卫合一] 原 pi.__workflowRun 内联守卫 + getDeps 守卫两份重复（state 缺失 /
+  //  storeHealthy=false），合并为单一 getWorkflowDeps：返回 discriminated union，
+  //  两个消费点各自决定失败形态——pi.__workflowRun（D-8 API）返回错误对象（不
+  //  throw，保住调用方 Promise 契约），getDeps（3 个 tool 的 lazy deps 源）throw
+  //  （pi tool 框架将其转译为 tool 错误结果）。错误消息逐字保留（crash-recovery
+  //  测试锁 "store unavailable" / "loadAll failed" 子串）。
+  // ════════════════════════════════════════════════════════════
+  type WorkflowDepsResolution =
+    | { ok: true; deps: LauncherDeps }
+    | { ok: false; reason: string };
+
+  const getWorkflowDeps = (sessionId: string): WorkflowDepsResolution => {
+    const state = sessionState.get(sessionId);
+    if (!state) {
+      return { ok: false, reason: "Session not initialized" };
+    }
+    // MF-1: store 不健康时 fail-fast，避免 store.save 再次失败导致 run 状态不落地。
+    if (!state.storeHealthy) {
+      return { ok: false, reason: "Workflow store unavailable (loadAll failed in session_start)" };
+    }
+    return { ok: true, deps: makeDeps(state, state.ctx) };
+  };
+
   // ════════════════════════════════════════════════════════════
   //  pi.__workflowRun（D-8 签名）
   // ════════════════════════════════════════════════════════════
@@ -890,28 +526,19 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
     // 注意：lastSessionId 是单值假设——Pi 当前保证单 session 串行（一次只一个活跃 session）。
     // 若未来 Pi 支持多 session 并发，此处需改为从 ctx.sessionManager.getSessionId() 显式传入。
     // M-2 已记录此假设。
-    const state = sessionState.get(lsRef.lastSessionId);
-    if (!state) {
+    const resolved = getWorkflowDeps(lsRef.lastSessionId);
+    if (!resolved.ok) {
       return {
         status: "done",
         reason: "failed",
-        error: "Session not initialized",
-        runId: "",
-      };
-    }
-    // MF-1: store 不健康时 fail-fast，避免 store.save 再次失败导致 run 状态不落地。
-    if (!state.storeHealthy) {
-      return {
-        status: "done",
-        reason: "failed",
-        error: "Workflow store unavailable (loadAll failed in session_start)",
+        error: resolved.reason,
         runId: "",
       };
     }
     return runAndWait(
       workflowName,
       workflowArgs,
-      makeDeps(state, state.ctx),
+      resolved.deps,
       workflowSignal,
       workflowTimeoutMs,
     );
@@ -919,46 +546,65 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
 
   // ════════════════════════════════════════════════════════════
   //  Tools（3 个）—— lazy deps 注入
+  //
+  //  lazyDeps：属性访问触发 getWorkflowDeps 守卫 + makeDeps 求值（每属性独立）。
+  //  守卫合一后 getWorkflowDeps 返回 discriminated union，getter 内消费时 throw
+  //  （与 __workflowRun 的 return 错误对象对齐——同源同消息，session-lifecycle.test.ts 锁定）。
   // ════════════════════════════════════════════════════════════
-  const getDeps = () => {
-    // 注意：lastSessionId 是单值假设——Pi 当前保证单 session 串行（一次只一个活跃 session）。
-    // 若未来 Pi 支持多 session 并发，此处需改为从 ctx.sessionManager.getSessionId() 显式传入。
-    // M-2 已记录此假设。
-    const state = sessionState.get(lsRef.lastSessionId);
-    if (!state) throw new Error("Session not initialized");
-    // MF-1: store 不健康时 fail-fast，避免 store.save 再次失败导致 run 状态不落地。
-    if (!state.storeHealthy) {
-      throw new Error("Workflow store unavailable (loadAll failed in session_start)");
-    }
-    return makeDeps(state, state.ctx);
-  };
-
   const lazyDeps: LauncherDeps = {
     get store() {
-      return getDeps().store;
-    },
-    workerHost,
-    get runner() {
-      return getDeps().runner;
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.store;
     },
     get runs() {
-      return getDeps().runs;
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.runs;
+    },
+    get registry() {
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.registry;
     },
-    registry,
     get onRunDone() {
-      return getDeps().onRunDone;
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.onRunDone;
     },
     get eventBus() {
-      return getDeps().eventBus;
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.eventBus;
+    },
+    get workerHost() {
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.workerHost;
+    },
+    get runner() {
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.runner;
     },
+    // scheduleTimeBudget / onWorkflowCall 不可缺席（ports.ts D-12 regression fix）：
+    // rebuildRuntime 重排 run 级墙钟预算计时器、worker 脚本嵌套 workflow() 调用都经
+    // 这两个成员消费——lazyDeps 缺席会让消费点拿到 undefined（可选属性静默放行），
+    // 带时间预算的 run 命中一次错误重试后计时器静默失效。转发形态与其余成员一致。
     get scheduleTimeBudget() {
-      return getDeps().scheduleTimeBudget;
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.scheduleTimeBudget;
     },
     get onWorkflowCall() {
-      return getDeps().onWorkflowCall;
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.onWorkflowCall;
     },
     get log() {
-      return getDeps().log;
+      const resolved = getWorkflowDeps(lsRef.lastSessionId);
+      if (!resolved.ok) throw new Error(resolved.reason);
+      return resolved.deps.log;
     },
   };
 
@@ -983,31 +629,12 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
 // ============================================================
 
 // channel registry 经 channel-registry-access.ts 公开访问（跨扩展 API）。
-// dialog queue 仍为本模块私有——无外部消费者。
-const DIALOG_QUEUE_KEY = Symbol.for("@zhushanwen/pi-subagents.dialogQueue");
-
-/** 获取或创建进程级 dialog queue 单例。
- *  L2 跨子进程串行队列——所有子进程的 dialog 类请求共享同一队列实例。 */
-function getOrCreateDialogQueue(): DialogGlobalQueue {
-  let queue = Reflect.get(globalThis, DIALOG_QUEUE_KEY) as DialogGlobalQueue | undefined;
-  if (!queue) {
-    queue = new DialogGlobalQueue();
-    Reflect.set(globalThis, DIALOG_QUEUE_KEY, queue);
-  }
-  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";
+// dialog queue 单例随 session_start 装配域迁居 session-lifecycle.ts
+// （getOrCreateDialogQueue；消费方 = 该文件 createOrReuseServices + 本文件
+// session_shutdown），Symbol key 单定义点随迁，避免双份定义漂移。
+
+// 跨扩展 channel handler 注册入口已收口到 core 深路径
+// `@zhushanwen/subagent-core/execution/channel-registry-access.ts`
+// （getOrCreateChannelRegistry / UiChannelRegistry / ChannelHandler）。
+// 历史上的包根 re-export 已删：ask-user 等跨扩展消费者经 globalThis 握手
+// （DIALOG_QUEUE_KEY 同款进程级单例），不再经包根 import 消费本模块。