@zhushanwen/pi-subagent-workflow 9.2.0 → 9.3.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/host/pi-host.ts

@@ -62,20 +62,34 @@ import { toErrorMessage } from "@zhushanwen/pi-ext-guards";
  * realpath 去重吸收）。
  *
  * 每次调用现解析（不 memo）：发现调用点稀疏（session_start + 缓存 miss），解析
- * 成本可忽略；失败（异常布局/解析器不可用）降级为不注入并 warn——绝不因资产
- * 接线失败阻断发现主链。
+ * 成本可忽略；两种形态各有通路，都不阻断发现主链：
+ *   - **dev / npm 形态**：`require.resolve` 沿本包依赖解析链命中 core 包；
+ *   - **bundle / staged 打包形态**（2026-10-03 B′ 修复）：esbuild 自包含 bundle 把
+ *     core inline、staged 布局无 node_modules ⇒ resolve 必败（实证：pi-host 日志全天
+ *     202 条 'Cannot find module … workflows/README.md'，内置 6 workflow + 10 agent
+ *     整体不可发现、`subagents` 批量工具报 'Built-in workflow fan-out is not available'）。
+ *     此时回退到 staged scope 根（见 stagedScopeRootFromModuleUrl）——仅当回退也不
+ *     成立（异常布局/解析器不可用）才降级为不注入并 warn。
  */
-function corePackageNpmRoot(): string | undefined {
+export function corePackageNpmRoot(moduleUrl: string = import.meta.url): string | undefined {
   try {
     // createRequire 锚定本模块（jiti 加载器下 import.meta.url 可用；不可用则随
     // catch 降级）。require.resolve 沿 pi-sw 自身的依赖解析链——workspace 与发布态
     // 都从本包出发命中 core。
-    const require = createRequire(import.meta.url);
+    const require = createRequire(moduleUrl);
     const anchor = require.resolve("@zhushanwen/subagent-core/workflows/README.md");
     return dirname(dirname(dirname(anchor)));
   } catch (err) {
-    // getLogger 惰性调用（catch 是冷路径——测试环境对 pi-extension-logger 的
-    // module-level mock 可能返回 undefined，模块级持有会在 import 期踩 undefined）
+    const stagedRoot = stagedScopeRootFromModuleUrl(moduleUrl);
+    if (stagedRoot !== undefined) {
+      // getLogger 惰性调用（冷路径：测试环境对 pi-extension-logger 的 module-level
+      // mock 可能返回 undefined，模块级持有会在 import 期踩 undefined）
+      getLogger("pi-host").debug(
+        "[pi-host] core 包经 staged scope 根注入（bundle 形态，无 node_modules 解析面）",
+        { root: stagedRoot },
+      );
+      return stagedRoot;
+    }
     getLogger("pi-host").warn(
       "[pi-host] core 包 agents/ 注入根解析失败——10 内置角色可能不可发现",
       { reason: toErrorMessage(err) },
@@ -84,6 +98,40 @@ function corePackageNpmRoot(): string | undefined {
   }
 }
 
+/**
+ * bundle / staged 形态的 core 资产注入根（2026-10-03 B′）。
+ *
+ * 打包态扩展被 esbuild 打成**自包含 index.js**（core 被 inline），staged 布局内无
+ * node_modules ⇒ `require.resolve` 锚点必败。但此时模块位置是
+ * `<stagedScope>/<pkg>/index.js`（如
+ * `<Resources>/extensions/@zhushanwen/pi-subagent-workflow/index.js`），其**父目录**
+ * 正是 `@zhushanwen` scope 目录——npm 槽语义（"一级子项 = 包目录"）恰好成立，
+ * 于是可直接当 npm 槽根用：约定目录扫描即命中
+ * `pi-subagent-workflow/{workflows,agents}`（两目录由 `scripts/bundle-extensions.mjs`
+ * 随包拷贝；`pi.agents`/`pi.workflows` manifest 约定及其"声明路径不存在 → 整包失败
+ * 占位"语义是 subagent-core resource-discovery 的 taiji 自建规则，权威源 =
+ * resource-discovery.ts processPackage——pi 上游 manifest 只有
+ * extensions/skills/prompts/themes 四字段，无 agents/workflows 概念。已核仓内无任何
+ * 包声明该字段，故扫描面内所有包都走约定目录分支，不进 manifest 失败分支）。
+ *
+ * 与 dev/npm 形态的既有语义一致：npm 槽根扫的就是 scope 下全部包目录（因此本包自带
+ * 的 workflows/agents 在 dev/npm 形态同样入发现面），非新增语义。
+ *
+ * 形态判据 = 父目录名以 `@` 开头：dev（模块在 `extensions/universal/...`）与 npm
+ * 安装形态都先走 resolve 成功分支，本回退不可达；仅 bundle/staged 形态命中。
+ */
+export function stagedScopeRootFromModuleUrl(moduleUrl: string): string | undefined {
+  try {
+    const pkgDir = dirname(fileURLToPath(moduleUrl));
+    const scopeDir = dirname(pkgDir);
+    if (scopeDir === pkgDir) return undefined;
+    const scopeName = scopeDir.split(/[\\/]/).pop() ?? "";
+    return scopeName.startsWith("@") ? scopeDir : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 /** agents/workflows 共享的 agentDir 派生根（末级目录名由 kind 决定）。
  *  顺序与 source 标签逐项对齐 resource-discovery.ts buildScanTargets 的
  *  user-pi → npm → npm-dev 段（根列表按优先级低→高排列，D2 语义边界）。

package/src/interface/command/subagents.ts

@@ -36,8 +36,8 @@ export interface SubagentDirectiveDetails {
 /**
  * 定向消息留痕：向主 session 落 subagent-directive custom_message entry。
  *
- * 按主 agent streaming 状态分流 sendMessage options。pi 0.84.4 sendCustomMessage
- * 实装（agent-session.js）：isStreaming 且无 deliverAs 时默认 agent.steer()——会把
+ * 按主 agent streaming 状态分流 sendMessage options。pi sendCustomMessage
+ * 实装（agent-session.js，1.0.0 复核同构）：isStreaming 且无 deliverAs 时默认 agent.steer()——会把
  * 定向消息注入正在运行的主 agent LLM turn，违反「不经主 agent LLM 直达 subagent」。
  * 故按调用时刻的权威 streaming 状态（ctx.isIdle()，与 sendCustomMessage 内部
  * isStreaming 判据精确互补，含 agent_end 后 retry/continuation 窗口）分流：

package/src/interface/tool/subagent-tool.ts

@@ -92,11 +92,12 @@ function isModelOverrideObj(a: unknown): a is { model?: unknown; thinkingLevel?:
 /**
  * start 路径类参数（skillPath / cwd）运行时守卫：绝对路径 + 禁 `..` 穿越。
  *
- * 校验链事实（pi 0.84.4 实装，登记 PS-20）：pi agent-loop 对注册 typebox schema
- * 有运行时强校验——agent-loop.js:403-404 在 beforeToolCall / execute 之前调
- * validateToolArguments（pi-ai validation.js:247：Value.Convert :249 + Compile :210
- * + Check :265，失败 throw `Validation failed for tool` :272-273）→ catch 走
- * immediate error（agent-loop.js:445-451），execute 不被调用。schema 的
+ * 校验链事实（语义登记 PS-20，verifiedWith 以 pi-semantics.json 为准，逐 claim 行号见该条目
+ * piAnchor）：pi agent-loop 对注册 typebox schema
+ * 有运行时强校验——在 beforeToolCall / execute 之前调
+ * validateToolArguments（pi-ai validation.js：Value.Convert + Compile
+ * + Check，失败 throw `Validation failed for tool`）→ catch 走
+ * immediate error，execute 不被调用。schema 的
  * pattern（skillPath/cwd `^/`）/ maxLength（slug 35）是运行时强制而非仅模型可见
  * 契约；tool-definition-wrapper.js:11 只原样透传 params，校验发生在上游 agent-loop 层。
  *

package/src/interface/tool/tool-workflow-script.ts

@@ -13,8 +13,9 @@
  * C5②（convergence D-6）：generate 五道闸校验管线 + tmp 写盘下沉 core
  * generateWorkflowScript（报错文案逐字平移，CA2 前提）；save/delete 改调 core
  * barrel（第三可选目录参数缺省即 pi 布局 .pi/workflows——pi 现两参调用形态零变化）。
- * 结构化 {ok}|{error} → pi 的 execute-throw 契约转换在本层（pi 只对 execute throw
- * 置 isError:true）；AbortSignal 的 aborted 检查在 execute 入口统一拦截（与
+ * 结构化 {ok}|{error} → pi 的 execute-throw 契约转换在本层（pi 1.0.0：execute 抛出经
+ * pi-agent-core agent-loop.js executePreparedToolCall 外层 catch 统一转 isError:true）；
+ * AbortSignal 的 aborted 检查在 execute 入口统一拦截（与
  * workflow / subagents 两 tool 同源，tool-shared assertNotAborted；C4 偏差 #4）。
  *
  * 层归属：Interface。依赖 Pi SDK + engine script-lint + infra workflow-files。
@@ -183,7 +184,8 @@ export function registerWorkflowScriptTool(
     ): Promise<WorkflowScriptExecuteResult> {
       // P1-2 abort 前置（三 tool 对称）：5 个 action 统一在 execute 入口拦截——
       // 原先只在 generate 内检查，lint/save/delete/list 四路径漏拦。throw（W4b）：
-      // pi 只对 execute throw 置 isError:true，返回值里的 isError 被 agent-loop 丢弃。
+      // 错误路径统一 throw（单一错误路径纪律；pi 1.0.0 agent-loop 对抛出统一转
+      // isError:true error result）。
       assertNotAborted(signal);
       let result: WorkflowScriptExecuteResult;
       switch (params.action) {
@@ -203,8 +205,9 @@ export function registerWorkflowScriptTool(
           result = await actionList(registry);
           break;
         default:
-          // 防御性（schema StringEnum 先拦）：throw（W4b）——pi 只对 execute throw 置
-          // isError:true，返回值里的 isError 被 agent-loop 丢弃（agent-loop.js:453-483）。
+          // 防御性（schema StringEnum 先拦）：throw（W4b）——错误路径统一 throw
+          // （pi 1.0.0 pi-agent-core agent-loop.js executePreparedToolCall :579-588：
+          // 抛出经外层 catch 转 isError:true error result）。
           throw new Error(`Unknown action: ${String(params.action)}`);
       }
       // GUI 协议：RPC 模式下附加 __gui__ 到 details（attach 单点在 tool-shared）
@@ -229,7 +232,8 @@ export function registerWorkflowScriptTool(
 // ── generate action ──────────────────────────────────────────
 
 export function actionGenerate(params: ScriptParams): WorkflowScriptExecuteResult {
-  // throw（W4b）：pi 只对 execute throw 置 isError:true（返回值 isError 被丢弃）。
+  // throw（W4b）：错误路径统一 throw（单一错误路径纪律；pi 1.0.0 agent-loop 对抛出
+  // 统一转 isError:true error result）。
   // abort 前置在 execute 入口统一拦截（三 tool 同源，tool-shared assertNotAborted），
   // 本函数不再自带 signal 检查。
   const name = params.name ?? "";
@@ -386,9 +390,9 @@ async function actionList(registry: WorkflowScriptRegistry): Promise<WorkflowScr
 // ── helper ───────────────────────────────────────────────────
 
 /**
- * 构造纯文本非错误结果（W4b：isError 参数已删除——pi 只对 execute throw 置
- * isError:true，返回值里的 isError 被 agent-loop 丢弃（agent-loop.js:453-483），
- * 错误一律 throw，编译器兜底防回潮）。
+ * 构造纯文本非错误结果（W4b：isError 参数已删除——异常错误路径一律 throw（单一
+ * 错误路径纪律；pi 1.0.0 pi-agent-core agent-loop.js :579-588 对抛出统一转
+ * isError:true error result），编译器兜底防回潮）。
  */
 function textResult(text: string): WorkflowScriptExecuteResult {
   return {

package/src/session-lifecycle.ts

@@ -523,19 +523,17 @@ function appendSubagentIdentityEntry(pi: ExtensionAPI): void {
  * 返回 undefined。
  */
 export function bindLedgerHostAndRecover(pi: ExtensionAPI, ctx: ExtensionContext): NotifyLedgerHost | undefined {
-  // host 五端口接线 + 送达 stale 防御（D5 单通道 {triggerTurn:true} / stale 静默降级 /
-  // abandon 补显形 T4③）收敛在 @zhushanwen/pi-notify-ledger-host 工厂，权威注释随迁
-  // 工厂内；component/logger 参数保持本包 label 前缀与 warn 通道归因不变，
-  // sendDisplayMessage = 生产 bind 恒实现（NotifyLedgerHost 可选端口的本侧既有语义）。
+  // host 五端口接线 + 送达 stale 防御（D5 单通道 {triggerTurn:true} / stale 静默降级）
+  // 收敛在 @zhushanwen/pi-notify-ledger-host 工厂，权威注释随迁工厂内；
+  // component/logger 参数保持本包 label 前缀与 warn 通道归因不变。
   const ledgerHost = createPiNotifyLedgerHost(pi, ctx, {
     component: "subagent-workflow",
     logger,
-    sendDisplayMessage: true,
   });
   // bind 与 recover 拆独立 try（失败归因不同）：
   // - bind 失败：槽上无 ledger，消费方（getBoundNotifyLedger）退回内核直发路径；
   // - recover 失败：bind 已成功、槽上 ledger 仍在，消费方照常走账本路径（重启重放
-  //   缺席，边沿/看门狗仍投新通知）——不得共用 "bind failed" 文案误报。
+  //   缺席，settled 边沿仍投新通知）——不得共用 "bind failed" 文案误报。
   let ledger: ReturnType<typeof bindNotifyLedgerHost>;
   try {
     ledger = bindNotifyLedgerHost(ledgerHost);