@zhushanwen/pi-subagent-workflow 9.2.1 → 9.4.0

package/src/host/inflight-reporter.ts

@@ -26,15 +26,14 @@
 // （session_start 是 pi 启动序列里最早带 ctx 的钩子 = 「session 就绪」，即设计所指
 // 加载完成时点；不挂任何懒触发（无 subagent 的 session 也必上报）。
 //
-// 失败语义（D5 缺席语义②）：select 失败（超时/通道异常/非确认回包）折叠后延迟重试，
-// **累计 MAX_REPORT_ATTEMPTS（3）次放弃**。上限刻意取小（增强面降级）：GUI live
-// 在途镜像短暂滞后可接受，重试 3 次封顶后放弃，不做长尾可达保证——子任务完成通知
-// 另有账本必达通道，不依赖此镜像。session_start 首帧早于 runtime adapter attach 的
-// 竞态（R2 实证）在 3×2s=6s 窗口内自愈，错过窗口即放弃。送达判据 = runtime resolve
-// 的确认回包
-// （INFLIGHT_REPORT_ACK）——fire-and-forget 下 resolve(undefined) 与超时不可区分，
-// 靠显式 ack 区分「已送达」与「无路由」；放弃后镜像按 absent-report 走 errs 推迟
-// （30min 有界），不丢 errs-safe 兜底。
+// 失败语义（ADR-0122 收紧，原 D5 缺席语义②的 timer 重试已删）：select 失败
+// （超时/通道异常/非确认回包）→ 首败 warn 显式留痕 + 置脏——**不设 setTimeout
+// 自动重试**，等下一个 onInFlightChanged 事件驱动重推（绝对计数语义下任何一帧
+// 成功即整镜恢复）。session_start 首帧早于 runtime adapter attach 的竞态（R2 实证）
+// 由此由后续 in-flight 变化事件自然补推；无后续事件的 session 镜像按 absent-report
+// 走 errs 推迟（30min 有界），完成通知另有账本必达通道，不依赖此镜像。
+// 送达判据 = runtime resolve 的确认回包（INFLIGHT_REPORT_ACK）——fire-and-forget 下
+// resolve(undefined) 与超时不可区分，靠显式 ack 区分「已送达」与「无路由」。
 
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { SUBAGENT_INFLIGHT_MARKER, callMarkerRpc, isInFlightReportAck } from "@zhushanwen/extension-protocol";
@@ -42,21 +41,10 @@ import { getInFlightSnapshot } from "@zhushanwen/subagent-core";
 import { getLogger } from "@zhushanwen/pi-extension-logger";
 import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
 
-/** select 通道级超时（控制面单请求，秒级校准——超时默认原则规则 19）。取值对齐
- *  plugin-bridge 启动 sync 的 2s 自愈闸：session_start 首帧可能早于 runtime adapter
- *  attach（R2 实证），超时折叠后靠有限次重试覆盖 attach 竞态窗口（约 6s，见
- *  MAX_REPORT_ATTEMPTS）；fire-and-forget 帧不留 pending 挂死面。 */
+/** select 通道级超时（控制面单请求，秒级校准——超时默认原则规则 19）；fire-and-forget
+ *  帧不留 pending 挂死面。失败不重试（ADR-0122），置脏等下一个事件。 */
 const SELECT_TIMEOUT_MS = 2_000;
 
-/** 失败重试退避（对齐 plugin-bridge SYNC_RETRY_MS 控制面节奏）。 */
-const RETRY_DELAY_MS = 2_000;
-
-/** 累计失败放弃上限（刻意取小——增强面降级）：GUI live 在途镜像短暂滞后可接受，
- *  3 次封顶（约 6s）后放弃，不做长尾可达保证；完成通知另有账本必达通道，不依赖
- *  此镜像。重试窗口同时覆盖 session_start 首帧早于 runtime adapter attach 的竞态
- *  （R2 实证），并有界防 rpc-but-非-taiji orchestrator 场景的永久空转。 */
-const MAX_REPORT_ATTEMPTS = 3;
-
 /** 在途上报器（组合根 index.ts 持有；per-factory 实例，session_start/shutdown 驱动）。 */
 export interface InFlightReporter {
   /**
@@ -65,7 +53,7 @@ export interface InFlightReporter {
    * （ctx.mode !== 'rpc'）下为 no-op：无 runtime 拦截方，上报通道不该启动。
    */
   attachSession(ctx: ExtensionContext): void;
-  /** session_shutdown 摘除 ctx 并停止重试（session 已死，上报通道随之终结）。 */
+  /** session_shutdown 摘除 ctx（session 已死，上报通道随之终结）。 */
   detachSession(): void;
   /** core 出口回调（notifyInFlightChanged 直连）：同步返回，内部合并 + void 推送。 */
   onInFlightChanged(): void;
@@ -74,16 +62,12 @@ export interface InFlightReporter {
 export interface InFlightReporterOpts {
   /** 测试注入：select 超时（ms）。缺省 SELECT_TIMEOUT_MS。 */
   selectTimeoutMs?: number;
-  /** 测试注入：重试退避（ms）。缺省 RETRY_DELAY_MS。 */
-  retryDelayMs?: number;
-  /** 测试注入：累计失败放弃上限。缺省 MAX_REPORT_ATTEMPTS。 */
-  maxAttempts?: number;
 }
 
 /**
- * sessionId 从 ctx 取（plugin-bridge getSessionId 同款防御）：pi session 文件延迟写入
- * 窗口内取失败不阻断上报——sessionId 缺席时 runtime 按无法归属丢弃整帧（契约
- * SubagentInFlightReport.sessionId 可选语义），不视为协议错误。
+ * sessionId 从 ctx 取：pi session 文件延迟写入窗口内取失败不阻断上报——sessionId
+ * 缺席时 runtime 按无法归属丢弃整帧（契约 SubagentInFlightReport.sessionId 可选语义），
+ * 不视为协议错误。
  */
 function getSessionId(ctx: ExtensionContext): string | undefined {
   try {
@@ -95,35 +79,20 @@ function getSessionId(ctx: ExtensionContext): string | undefined {
 
 export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFlightReporter {
   const selectTimeoutMs = opts.selectTimeoutMs ?? SELECT_TIMEOUT_MS;
-  const retryDelayMs = opts.retryDelayMs ?? RETRY_DELAY_MS;
-  const maxAttempts = opts.maxAttempts ?? MAX_REPORT_ATTEMPTS;
   const logger = getLogger("subagents");
 
   // 闭包状态（per-factory 实例；禁模块级 let——同进程多 factory 实例会串台）。
   let ctx: ExtensionContext | null = null;
   /** 一次推送尝试在途（串行化——绝对计数语义下中间值可安全合并丢弃）。 */
   let attemptInFlight = false;
-  /** 有待推帧（onInFlightChanged 在推送在途期间置位，成功后立即补推最新值）。 */
+  /** 有待推帧（推送在途或上次失败期间置位，下次 onInFlightChanged 事件驱动重推）。 */
   let dirty = false;
-  /** 重试定时器句柄（单飞；成功/dispose 即清）。 */
-  let retryTimer: ReturnType<typeof setTimeout> | null = null;
-  /** 累计失败次数（成功清零；达 maxAttempts 放弃——本 session 不再重试）。 */
-  let failureCount = 0;
-  /** 已放弃（累计到顶；session 内终态，成功路径永不触及）。 */
-  let givenUp = false;
-  /** 首次失败已 warn 留痕（重试循环不刷屏）。 */
+  /** 首次失败已 warn 留痕（后续失败不刷屏）。 */
   let firstFailureLogged = false;
 
-  function clearRetryTimer(): void {
-    if (retryTimer !== null) {
-      clearTimeout(retryTimer);
-      retryTimer = null;
-    }
-  }
-
-  /** 推送在途、已放弃或无 ctx 时仅置脏；否则发起一次尝试（void，不阻塞调用方）。 */
+  /** 推送在途或无 ctx 时仅置脏；否则发起一次尝试（void，不阻塞调用方）。 */
   function kick(): void {
-    if (attemptInFlight || givenUp || ctx === null) {
+    if (attemptInFlight || ctx === null) {
       dirty = true;
       return;
     }
@@ -148,7 +117,7 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
     });
     // 发送+折叠半边走 protocol 的 callMarkerRpc 原语（D8，fire-and-forget：void 发起
     // 不变）：ok:false 四态（cancelled/timeout/channel-error/non-json）统一折叠进下方
-    // 延迟重试路径；送达判据 = ack 全等匹配（不是 JSON 消费），留在本侧。原语的失败
+    // 失败留痕路径；送达判据 = ack 全等匹配（不是 JSON 消费），留在本侧。原语的失败
     // 留痕经注入的 log 承载本侧「首败 warn / 后续 debug」防刷屏策略。
     // guiCtx = ExtensionContext 的 GuiContext 最小子集（ask-user runRpcInteraction 同款
     // 先例：ui.custom 泛型签名静态不兼容，callMarkerRpc 只读 ui.select）。
@@ -163,37 +132,19 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
     });
     attemptInFlight = false;
     if (result.ok && isInFlightReportAck(result.value)) {
-      // 送达确认：清重试与失败计数，补推积压脏帧。
-      failureCount = 0;
-      clearRetryTimer();
+      // 送达确认：补推积压脏帧。
       if (dirty && ctx !== null) kick();
       return;
     }
-    // 失败折叠（resolve undefined = 超时/取消/无路由 / 回包非 ack / 通道异常）→ 延迟
-    // 重试，累计到顶放弃（放弃后镜像按 absent-report 走 errs 推迟，30min 有界，
-    // errs-safe 兜底不丢）。
+    // 失败折叠（resolve undefined = 超时/取消/无路由 / 回包非 ack / 通道异常）：
+    // 显式留痕 + 置脏（ADR-0122：无 timer 自动重试）——等下一个 onInFlightChanged
+    // 事件驱动重推；attach 竞态丢失的首帧由后续事件自然补推，无后续事件的 session
+    // 镜像按 absent-report 走 errs 推迟（30min 有界，errs-safe 兜底不丢）。
     logFailure(
       result.ok ? "no ack (non-ack response)" : `no ack (${result.reason})`,
       result.ok ? result.value : undefined,
     );
-    failureCount += 1;
-    if (failureCount >= maxAttempts) {
-      givenUp = true;
-      clearRetryTimer();
-      logger.warn(
-        `[subagent-inflight] in-flight report gave up after ${failureCount} attempts; ` +
-          `mirror will treat this session as absent-report (errs-deferred, bounded)`,
-      );
-      return;
-    }
-    if (ctx !== null && retryTimer === null) {
-      retryTimer = setTimeout(() => {
-        retryTimer = null;
-        kick();
-      }, retryDelayMs);
-      // unref：不阻塞进程退出（退出收割由既有 process hook 负责，与 plugin-bridge 同款）。
-      retryTimer.unref?.();
-    }
+    dirty = true;
   }
 
   /** 原语留痕注入（D8）：msg/detail 由 callMarkerRpc 产出；防刷屏策略（首败 warn /
@@ -205,12 +156,12 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
   function logFailure(reason: string, detail: unknown): void {
     if (!firstFailureLogged) {
       firstFailureLogged = true;
-      logger.warn(`[subagent-inflight] in-flight report failed (${reason}); retrying every ${retryDelayMs}ms (bounded at ${maxAttempts} attempts)`, {
+      logger.warn(`[subagent-inflight] in-flight report failed (${reason}); will retry on next in-flight change (event-driven, no timer)`, {
         detail: toErrorMessage(detail),
       });
       return;
     }
-    logger.debug(`[subagent-inflight] in-flight report retry failed (${reason})`);
+    logger.debug(`[subagent-inflight] in-flight report failed again (${reason})`);
   }
 
   return {
@@ -219,13 +170,10 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
       // select 会弹真框（2026-09-12 裸 TUI 无限闪框事故根因）——不设 ctx，本 session
       // 全程 no-op。ask-user 的 ctx.mode === "rpc" 二值判定同款先例。
       if (target.mode !== "rpc") return;
-      // attach = 新 reporting epoch（新 session / respawn 后重载）：放弃态与失败计数
-      // 随旧 session 终结，重置重试资格（同一 session 内放弃不恢复——absent-report 兜底）。
-      givenUp = false;
-      failureCount = 0;
+      // attach = 新 reporting epoch（新 session / respawn 后重载）：首败留痕标记随旧
+      // session 终结重置（新 session 的首败仍 warn 显式上报）。
       firstFailureLogged = false;
       ctx = target;
-      clearRetryTimer();
       // 初始上报（count=当下绝对计数；session 就绪时点恒为 0——子进程只会在后续
       // subagent 调用里出现）。fire-and-forget：不阻塞 session_start 装配链。
       kick();
@@ -234,7 +182,6 @@ export function createInFlightReporter(opts: InFlightReporterOpts = {}): InFligh
     detachSession(): void {
       ctx = null;
       dirty = false;
-      clearRetryTimer();
     },
 
     onInFlightChanged(): void {

package/src/host/journal-reporter.ts

@@ -0,0 +1,204 @@
+// src/host/journal-reporter.ts
+//
+// 壳层 journal 事件推送出口（event-push-channel W-P1，设计权威源
+// .tmp/tech-design/event-push-channel.md §3.1/§3.3/§3.4）。本文件属壳侧（shell），
+// 对 pi SDK（ExtensionContext 的 ctx.ui.select 通道）的消费收敛在 host/ 层——
+// core 闭包红线只约束 core（出口回调由 core 的 journal-notify 注入，见组合根
+// workflow-events.ts 的 setJournalAppendListener 接线）。
+//
+// 链路：core journal 落盘提交点（run 域 terminal-actions / record 域 record-store
+// 族）→ notifyJournalAppended（同步回调）→ 本 reporter（事件按 (domain, fileKey)
+// 分组合并 → select 通道帧，title = SUBAGENT_JOURNAL_MARKER）→ runtime event-adapter
+// marker 路由 → session-records 派生视图（applyJournalReport）。
+//
+// 语义（设计 §3.3）：单帧报告覆盖一个文件（fileKey 单数）；事件 = 刚落盘的行对象
+// （seq 已分配），不做水位协商——去重与缺口判定归消费方（fold seq 单调守卫构造性
+// 幂等）。串行化合并：一次推送尝试在途时，后续事件并入待推缓冲；尝试成功后缓冲
+// 剩余组继续逐组推送（事件驱动，无 timer）。
+//
+// 失败语义（设计 D5，与 inflight reporter 的 dirty 重推刻意分叉）：select 失败
+// （超时/通道异常/非确认回包）→ 首败 warn 留证 + 待推缓冲整体丢弃——**不重试**
+// （本通道消费方有 seq 水位可判缺口，丢失由缺口补读收敛，缓冲重推是重复保险）。
+// 无后续事件的丢失场景由终局条目补读触发兜底（设计 §3.3 终局一致性）。
+// 送达判据 = runtime resolve 的确认回包（JOURNAL_REPORT_ACK）——回执 = 「已应用」
+// （runtime 同步完成 fold 后 resolve）。
+//
+// 环境门控：上报的消费方是 taiji runtime 的 event-adapter marker 路由，runtime
+// spawn pi 恒为 --mode rpc——ctx.mode !== 'rpc' 即无拦截方（裸 pi TUI 下 marker
+// select 会弹真框），此时不启动推送（inflight-reporter 环境门控同款）。
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import {
+  SUBAGENT_JOURNAL_MARKER,
+  callMarkerRpc,
+  isJournalReportAck,
+  type SubagentJournalDomain,
+  type SubagentJournalEvent,
+} from "@zhushanwen/extension-protocol";
+import { getLogger } from "@zhushanwen/pi-extension-logger";
+
+/** select 通道级超时（控制面单请求，秒级校准——超时默认原则规则 19；与 inflight
+ *  reporter 同量级。失败不重试，缺口归消费方补读收敛）。 */
+const SELECT_TIMEOUT_MS = 2_000;
+
+/** 单帧报告字节数的观测阈值（设计 W-P4 ④：只观测不拦截——超限 warn 留痕，供
+ *  worker-log 高频行合并量级评估；不设硬上限，截断会破坏报告内 seq 连续性判定）。 */
+const REPORT_BYTES_WARN_THRESHOLD = 100_000;
+
+/** 单文件待推事件组（报告的逐文件分组形态）。 */
+type PendingFileGroup = {
+  domain: SubagentJournalDomain;
+  fileKey: string;
+  events: SubagentJournalEvent[];
+};
+
+/** journal 事件推送器（workflow-events 装配点持有；per-factory 实例，session_start/shutdown 驱动）。 */
+export interface JournalReporter { // oe-exempt:20261003:framework:host 层对装配点的 reporter 端口契约（attach/detach/onJournalAppended 消费缝先立）
+  /**
+   * session_start 注入当前 ctx（非 rpc 模式下为 no-op：无 runtime 拦截方，推送
+   * 通道不该启动）。journal 推送是纯事件驱动（落盘提交点触发），无初始帧——
+   * 与 inflight 的「加载完成初始上报」刻意不同：报告语义是增量事件，空 session
+   * 无事件可报，缺席语义归消费方冷读。
+   */
+  attachSession(ctx: ExtensionContext): void;
+  /** session_shutdown 摘除 ctx 并丢弃待推缓冲（session 已死，推送通道随之终结；
+   *  未推事件由消费方冷读/缺口补读收敛）。 */
+  detachSession(): void;
+  /** core 出口回调（notifyJournalAppended 直连）：同步返回，内部分组合并 + void 推送。 */
+  onJournalAppended(domain: SubagentJournalDomain, fileKey: string, events: readonly unknown[]): void;
+}
+
+export interface JournalReporterOpts { // oe-exempt:20261003:framework:工厂参数契约（测试注入缝，消费方 workflow-events 以不同 opts 实例化）
+  /** 测试注入：select 超时（ms）。缺省 SELECT_TIMEOUT_MS。 */
+  selectTimeoutMs?: number;
+  /** 测试注入：报告字节数观测阈值。缺省 REPORT_BYTES_WARN_THRESHOLD。 */
+  reportBytesWarnThreshold?: number;
+}
+
+/**
+ * sessionId 从 ctx 取：pi session 文件延迟写入窗口内取失败不阻断推送——sessionId
+ * 缺席时 runtime 按无法归属丢弃整帧（契约 SubagentJournalReport.sessionId 可选语义），
+ * 不视为协议错误。
+ */
+function getSessionId(ctx: ExtensionContext): string | undefined {
+  try {
+    return ctx.sessionManager.getSessionId();
+  } catch {
+    return undefined;
+  }
+}
+
+export function createJournalReporter(opts: JournalReporterOpts = {}): JournalReporter {
+  const selectTimeoutMs = opts.selectTimeoutMs ?? SELECT_TIMEOUT_MS;
+  const reportBytesWarnThreshold = opts.reportBytesWarnThreshold ?? REPORT_BYTES_WARN_THRESHOLD;
+  const logger = getLogger("subagents");
+
+  // 闭包状态（per-factory 实例；禁模块级 let——同进程多 factory 实例会串台）。
+  let ctx: ExtensionContext | null = null;
+  /** 待推缓冲（(domain,fileKey) → 事件组；推送在途期间新事件并入，尝试启动时取走）。 */
+  const pending = new Map<string, PendingFileGroup>();
+  /** 一次推送尝试在途（串行化——组间逐帧发送，避免并发 select 帧交叉）。 */
+  let attemptInFlight = false;
+  /** 首次失败已 warn 留痕（后续失败不刷屏；随 attach 重置——新 session 的首败仍显式上报）。 */
+  let firstFailureLogged = false;
+
+  function groupKeyOf(domain: SubagentJournalDomain, fileKey: string): string {
+    return `${domain}:${fileKey}`;
+  }
+
+  /** core 出口回调直连：事件并入待推缓冲 + 事件驱动 kick（同步返回，不阻塞落盘主链）。 */
+  function onJournalAppended(
+    domain: SubagentJournalDomain,
+    fileKey: string,
+    events: readonly unknown[],
+  ): void {
+    if (ctx === null || events.length === 0) return;
+    const key = groupKeyOf(domain, fileKey);
+    const group = pending.get(key);
+    if (group !== undefined) {
+      group.events.push(...(events as SubagentJournalEvent[]));
+    } else {
+      pending.set(key, { domain, fileKey, events: [...(events as SubagentJournalEvent[])] });
+    }
+    kick();
+  }
+
+  /** 推送在途时不重入（缓冲已承接）；否则逐组发起推送（void，不阻塞调用方）。 */
+  function kick(): void {
+    if (attemptInFlight || ctx === null) return;
+    attemptInFlight = true;
+    void attempt();
+  }
+
+  async function attempt(): Promise<void> {
+    try {
+      let active = ctx;
+      while (active !== null && pending.size > 0) {
+        // 取首组发送（FIFO——Map 插入序 = 事件到达序）；组在发送前移出缓冲：
+        // 失败时该组与其余待推组一起丢弃（D5 缓冲即弃），成功时继续下一组。
+        const [key, group] = pending.entries().next().value as [string, PendingFileGroup];
+        pending.delete(key);
+        const payload = JSON.stringify({
+          domain: group.domain,
+          fileKey: group.fileKey,
+          events: group.events,
+          sessionId: getSessionId(active),
+          emittedAt: Date.now(),
+        });
+        if (payload.length > reportBytesWarnThreshold) {
+          logger.warn(`[subagent-journal] report size exceeds observation threshold (${payload.length} bytes, file=${group.fileKey}, events=${group.events.length}) — observation only, no rejection`);
+        }
+        const guiCtx = {
+          mode: active.mode,
+          hasUI: active.hasUI,
+          ui: { select: active.ui.select.bind(active.ui) },
+        };
+        const result = await callMarkerRpc(guiCtx, SUBAGENT_JOURNAL_MARKER, payload, {
+          timeout: selectTimeoutMs,
+          log: primitiveLog,
+        });
+        if (!(result.ok && isJournalReportAck(result.value))) {
+          logFailure(result.ok ? "no ack (non-ack response)" : `no ack (${result.reason})`);
+          pending.clear(); // D5：失败即弃缓冲（不重推）——完整性归消费方 seq 缺口补读
+          return;
+        }
+        active = ctx; // 尝试期间可能 detach/attach——每轮现读
+      }
+    } finally {
+      attemptInFlight = false;
+    }
+    // 成功路径：detach 后 ctx 为 null（while 退出）——缓冲随 detach 清空，无残留。
+  }
+
+  /** 原语留痕注入：msg/detail 由 callMarkerRpc 产出；防刷屏策略留本侧 logFailure。 */
+  function primitiveLog(msg: string, detail?: object): void {
+    logFailure(detail === undefined ? msg : `${msg} ${JSON.stringify(detail)}`);
+  }
+
+  function logFailure(reason: string): void {
+    if (!firstFailureLogged) {
+      firstFailureLogged = true;
+      logger.warn(`[subagent-journal] journal report failed (${reason}); buffer dropped, convergence via consumer seq-gap backfill (no retry)`);
+      return;
+    }
+    logger.debug(`[subagent-journal] journal report failed again (${reason})`);
+  }
+
+  return {
+    attachSession(target: ExtensionContext): void {
+      // 环境门控：非 rpc 模式（裸 pi TUI / json / print）无 runtime 拦截方，marker
+      // select 会弹真框——不设 ctx，本 session 全程 no-op（inflight 同款先例）。
+      if (target.mode !== "rpc") return;
+      // attach = 新 reporting epoch：首败留痕标记随旧 session 终结重置。
+      firstFailureLogged = false;
+      ctx = target;
+    },
+
+    detachSession(): void {
+      ctx = null;
+      pending.clear();
+    },
+
+    onJournalAppended,
+  };
+}

package/src/index.ts

@@ -2,7 +2,7 @@
  * subagent-workflow Extension — Factory（extension 装配点）
  *
  * 合并 @zhushanwen/pi-subagents + @zhushanwen/pi-workflow 为统一包。
- * 注册项：4 tool（subagent + subagents + workflow + workflow-script）+ 2 command（subagents + workflows）
+ * 注册项：4 tool（subagent + subagents + workflow + workflow-script）+ 3 command（subagents + workflows + subagent-model）
  * + messageRenderer（subagent-bg-notify）+ session 事件。
  *
  * 包内结构（执行运行时已迁 packages/subagent-core，本包只留注册面与宿主适配）：
@@ -52,6 +52,8 @@ import { registerWorkflowsCommand } from "./interface/command/commands.ts";
 import { registerSubagentTool } from "./interface/tool/subagent-tool.ts";
 // ═══ interface/ 层（tools/commands/tui 合并） ═══
 import { registerSubagentsCommand } from "./interface/command/subagents.ts";
+// [subagent-model-switch U6] 模型切换 RPC 通道消费端（§7.1.1，runtime 出站点 prompt 触达）
+import { registerSubagentModelCommand } from "./interface/command/subagent-model.ts";
 import { registerSubagentsTool } from "./interface/tool/tool-subagents.ts";
 import { registerWorkflowTool } from "./interface/tool/tool-workflow.ts";
 import { registerWorkflowScriptTool } from "./interface/tool/tool-workflow-script.ts";
@@ -143,6 +145,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   // ════════════════════════════════════════════════════════════
   registerSubagentTool(pi);
   registerSubagentsCommand(pi);
+  registerSubagentModelCommand(pi);
   pi.registerMessageRenderer(SUBAGENT_BG_NOTIFY_CUSTOM_TYPE, renderBgNotifyMessage);
 
   // ════════════════════════════════════════════════════════════
@@ -226,7 +229,7 @@ export default function subagentsWorkflowExtension(pi: ExtensionAPI): void {
   process.on("beforeExit", reapSpawnedChildrenOnShutdown);
 
   // ════════════════════════════════════════════════════════════
-  //  Tools（3 个）+ Commands（2 个）—— 注册面
+  //  Tools（3 个）+ Commands（3 个）—— 注册面
   //
   //  lazyDeps / isScriptRunning / registry 由 workflow-events.ts 装配结果提供。
   //  guard：workflow tool 与 subagents（批量派发入口）共用同一 guard——两者是同一条

package/src/interface/command/__tests__/commands-resume.test.ts

@@ -1,13 +1,13 @@
 /**
- * /workflows 命令的 resume 通道契约（workflow-run-resume-revision U3）。
+ * /workflows 命令的 resume 通道契约（workflow-run-resume-revision U3 + F1-26 后续项）。
  *
- * 覆盖面（TUI 模式）：/workflows resume <runId> → 执行断点续跑后 notify，不打开
- * 面板；缺 runId → Usage 提示；resumeRun 拒绝 → warning notify 透出恢复指引文案。
+ * 覆盖面（TUI 模式）：/workflows resume <runId> [model] → 执行断点续跑后 notify，
+ * 不打开面板；缺 runId → Usage 提示（含可选 [model]）；resumeRun 拒绝 → warning
+ * notify 透出恢复指引文案；显式 model 的 handler 透传（第三参 { model } / 无 model
+ * 不落键）与目录预检拒单（与 tool 通道同款 D8 语义）。
  *
- * RPC 模式（taiji GUI）的 resume verb 接线未随 U3 落地：解析词表在
- * command-actions.ts（领地外，resume verb 现仍解析为 lifecycle-removed），其
- * dispatch 断言由 src/__tests__/rpc-command-handling.test.ts 原样锁定——词表
- * 适配归编排层（见 commands.ts handleRpcMode 注释）。workflow tool 通道
+ * RPC 模式（taiji GUI）的 resume verb 接线与 model 透传由
+ * src/__tests__/rpc-command-handling.test.ts 覆盖；workflow tool 通道
  * （action:"resume"，含 D14 args 校验）由 tool-workflow-resume.test.ts 覆盖。
  *
  * mock 策略：resume-run 深路径 stub（对齐 tool-workflow-resume.test.ts）；命令
@@ -19,6 +19,7 @@ import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
 
 // 被 mock 的模块——import 路径与被测源文件的等值实例（对齐 tool-workflow-resume.test.ts）
 import { resumeRun } from "@zhushanwen/subagent-core/orchestration/resume-run.ts";
+import { setModelConfigService, GLOBAL_SLOT_KEYS } from "@zhushanwen/subagent-core";
 
 import { registerWorkflowsCommand } from "../commands.ts";
 
@@ -66,9 +67,26 @@ function makeCtx(mode: "rpc" | "tui"): { ctx: ExtensionCommandContext; notifies:
   return { ctx: ctx as never, notifies };
 }
 
+/** 重置进程级 ModelConfigService 单例槽（model catalog 预检用例的注入/清理，
+ *  Symbol 直写——key 与生产 getModelServiceSlot 的 MODEL_SERVICE_SLOT_KEY 一致）。 */
+function resetModelServiceSlot(): void {
+  const slot = Reflect.get(globalThis, Symbol.for(GLOBAL_SLOT_KEYS.modelService)) as
+    | { current: unknown }
+    | undefined;
+  if (slot) slot.current = null;
+}
+
+/** 注入目录为 entries 的最小 ModelConfigService fake（duck-typed getAvailable）。 */
+function injectModelServiceWith(entries: Array<{ provider: string; id: string }>): void {
+  setModelConfigService({
+    getModelRegistry: () => ({ getAvailable: () => entries }),
+  } as never);
+}
+
 beforeEach(() => {
   vi.mocked(resumeRun).mockReset();
   vi.mocked(resumeRun).mockResolvedValue("wf-x");
+  resetModelServiceSlot();
 });
 
 // ── TUI 模式 ─────────────────────────────────────────────────
@@ -79,17 +97,44 @@ describe("/workflows TUI resume", () => {
     const { ctx, notifies } = makeCtx("tui");
     await cmd.handler("resume wf-x", ctx);
     expect(vi.mocked(resumeRun)).toHaveBeenCalledWith("wf-x", expect.anything());
+    // 无 model 不落键：调用恰为 (runId, deps) 两参（spread 条件反写不会静默通过）
+    expect(vi.mocked(resumeRun).mock.calls[0]).toHaveLength(2);
     expect(notifies).toHaveLength(1);
     expect(notifies[0]!.msg).toContain("resuming");
     expect(notifies[0]!.level).toBe("info");
   });
 
+  it("resume <runId> <model> → resumeRun 第三参 { model } 透传 + notify 带模型", async () => {
+    injectModelServiceWith([{ provider: "p2", id: "m2" }]);
+    const cmd = captureCommand();
+    const { ctx, notifies } = makeCtx("tui");
+    await cmd.handler("resume wf-x p2/m2:high", ctx);
+    expect(vi.mocked(resumeRun)).toHaveBeenCalledWith("wf-x", expect.anything(), {
+      model: "p2/m2:high",
+    });
+    expect(notifies[0]!.msg).toContain("resuming with model p2/m2:high");
+    expect(notifies[0]!.level).toBe("info");
+  });
+
+  it("resume 显式 model 目录查无 → 同步拒单 warning（tool 通道同款 D8 语义，不落覆盖记账）", async () => {
+    injectModelServiceWith([{ provider: "p1", id: "m1" }]);
+    const cmd = captureCommand();
+    const { ctx, notifies } = makeCtx("tui");
+    await cmd.handler("resume wf-x pX/nope", ctx);
+    // 目录查无在 resumeRun 之前拒绝——不产生假成功 notify
+    expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
+    expect(notifies).toHaveLength(1);
+    expect(notifies[0]!.msg).toContain("Failed to resume workflow wf-x:");
+    expect(notifies[0]!.msg).toContain("pX/nope");
+    expect(notifies[0]!.level).toBe("warning");
+  });
+
   it("resume 缺 runId → Usage warning", async () => {
     const cmd = captureCommand();
     const { ctx, notifies } = makeCtx("tui");
     await cmd.handler("resume", ctx);
     expect(vi.mocked(resumeRun)).not.toHaveBeenCalled();
-    expect(notifies[0]).toMatchObject({ msg: "Usage: /workflows resume <runId>", level: "warning" });
+    expect(notifies[0]).toMatchObject({ msg: "Usage: /workflows resume <runId> [model]", level: "warning" });
   });
 
   it("resumeRun 拒绝 → warning notify（TUI 同款透出）", async () => {