@zhushanwen/subagent-core 0.5.1 → 0.7.0

package/src/execution/engine/common/kill-chain.ts

@@ -1,253 +1,20 @@
 // src/execution/engine/common/kill-chain.ts
 //
-// 超时杀链与 abort 两级中断（P2 公共降级层）。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D1（abort 分级：引擎原生中断 →
-// 公共杀链兜底；CLI-only 引擎直接杀链，杀死后宿主合成终态）+ §3.3.3 engine_timeout /
-// engine_run_failed 行 + 附录 A「CLI 超时」行（6/6 引擎全缺 → 宿主公共层全补）。
-//
-// 为什么放公共层：没有任何引擎有 CLI 级超时（§2.2 表），杀链写一次全引擎复用（D4）。
-
-import { getLogger } from "../../../core/logger.ts";
-
-import { engineTimeoutDetail } from "./errors.ts";
-import type { AgentCallOpts } from "../../../orchestration/models/types.ts";
-import type { AgentOutcome } from "../types.ts";
-import { DEFAULT_ENGINE_ID } from "../registry.ts";
-import { toErrorMessage } from "../../../core/error-message.ts";
-
-const logger = getLogger("subagents");
-
-// ============================================================
-// 杀链（SIGTERM → grace → SIGKILL）
-// ============================================================
-
-/**
- * 可杀子进程的结构形状（Node ChildProcess 的结构子集）。
- * 用结构接口而非 ChildProcess 类型：测试可注入 fake（ChildProcess 全字段构造过重），
- * 且未来 driver host 的常驻进程句柄只要满足此形状即可复用杀链。
- */
-export interface KillableChild {
-  /** 非 null = 进程已退出（自然退出码）。 */
-  readonly exitCode: number | null;
-  /** 非 null = 进程被信号杀死。exitCode/signalCode 任一非 null 即已退出。 */
-  readonly signalCode: string | null;
-  /** 发信号。返回 false = 进程已不存在（kill no-op）。 */
-  kill(signal?: NodeJS.Signals | number): boolean;
-  once(event: "exit", listener: (code: number | null, signal: NodeJS.Signals | null) => void): unknown;
-}
-
-// 毫秒→秒换算（SIGKILL 升级 warn 日志的秒数显示）。文件内私有定义：工程内 MS_PER_SECOND
-// 惯例是各使用文件私有常量（execution-record / lifecycle-manager / session-file-gc /
-// session-runner 四处先例），无共享导出源可 import，保持同惯例不另立导出点。
-const MS_PER_SECOND = 1_000;
-
-/** SIGTERM 优雅窗口默认值（ms）。实测校准点：设计 §5 待验证检查点⑤（zcode 对 SIGTERM 的响应时序）。 */
-export const DEFAULT_KILL_GRACE_MS = 5_000;
-
-/** SIGKILL 发出后的收尸等待上限（ms）——SIGKILL 后进程必死（D 状态罕见），有界等待防挂死。 */
-const SIGKILL_REAP_TIMEOUT_MS = 10_000;
-
-/**
- * 宿主超时 abort 的 signal.reason 标记（对齐点④）。mergeTimeoutSignal（SAR 侧超时
- * 合并链）产出；引擎 abort 合成终态时判别「超时 vs 用户 cancel」——超时统一走
- * synthesizeTimeoutOutcome（engine_timeout），cancel 维持中止标记（engine_run_failed）。
- */
-export const HOST_TIMEOUT_ABORT_REASON = "agent-call-timeout";
-
-/** killChain 的参数形状。 */
-export interface KillChainOptions {
-  /**
-   * SIGTERM 优雅窗口（ms）。grace 窗口按引擎参数化（D3-① 杀链合一）：pi 传 30s
-   * （[race-F4] 现状值）、zcode 传 5s（ZCODE_KILL_GRACE_MS）——两引擎现状逐字节保持。
-   */
-  graceMs: number;
-  /**
-   * [D3-①] 内部 timer unref。pi 路径现状 = 升级 timer unref（不阻止主进程退出，dispose
-   * killAll 兜底）；zcode 现状 = ref'd（timer 挂起时进程等待收尸）——各引擎按现状传。
-   */
-  unrefTimers?: boolean;
-  /**
-   * SIGKILL 升级时的 warn 留痕载体（如 `child sa-xxx (source: spawn watchdog)`）。
-   * 不传则升级静默（zcode 现状）——pi 侧现状有 warn，由调用方组装完整语境。
-   */
-  escalationNote?: string;
-}
-
-/**
- * 杀链：SIGTERM → 等待 graceMs → 仍存活则 SIGKILL。
- *
- * @returns 'terminated' = SIGTERM 优雅退出（或进程已自行退出）；'killed' = 走了 SIGKILL。
- */
-export async function killChain(
-  child: KillableChild,
-  opts: KillChainOptions,
-): Promise<"terminated" | "killed"> {
-  // 已退出（自然/已被杀）→ 无需发信号，按优雅终止口径返回
-  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
-
-  const exited = waitForExit(child);
-  safeKill(child, "SIGTERM");
-
-  const graceful = await raceTimeout(exited, opts.graceMs, opts.unrefTimers === true);
-  if (graceful === "settled") return "terminated";
-  // grace 超时后进程可能恰好在检查前一刻退出——复核退出态，避免误杀已死进程
-  if (child.exitCode !== null || child.signalCode !== null) return "terminated";
-
-  if (opts.escalationNote !== undefined) {
-    logger.warn(
-      `[kill-chain] ${opts.escalationNote} still alive ${opts.graceMs / MS_PER_SECOND}s after SIGTERM, escalating to SIGKILL`,
-    );
-  }
-  safeKill(child, "SIGKILL");
-  // 有界收尸：无论等到与否都返回 'killed'（信号已发出，返回值表达「走了 SIGKILL」）
-  await raceTimeout(exited, SIGKILL_REAP_TIMEOUT_MS, opts.unrefTimers === true);
-  return "killed";
-}
-
-/**
- * 发信号兜底包裹：进程恰在退出态检查与 kill 之间自退时，ChildProcess.kill 可能抛
- * （zsub 实测经验）——幂等吞掉并 debug 留痕，不阻断杀链语义（对已退进程信号本就是
- * no-op）。收口自 zcode launcher 的内联实现（对齐点②：单一权威）。
- */
-function safeKill(child: KillableChild, signal: NodeJS.Signals): void {
-  try {
-    child.kill(signal);
-  } catch (err) {
-    logger.debug(
-      `[kill-chain] ${signal} on exited process: ${toErrorMessage(err)}`,
-    );
-  }
-}
-
-// ============================================================
-// 超时终态合成
-// ============================================================
-
-/**
- * 合成 engine_timeout 终态（宿主超时杀链走完后的 AgentOutcome）。
- * 含 stdout 尾部 2000 字 + 「可用 engine: pi 重跑」建议（§3.3.3 第 6 行）；
- * exitCode: null = 被信号杀死（AgentOutcome 的杀链判据，§3.3.5）。
- */
-export function synthesizeTimeoutOutcome(
-  task: AgentCallOpts,
-  stdoutTail: string,
-  engineId: string = DEFAULT_ENGINE_ID,
-): AgentOutcome {
-  return {
-    content: "",
-    // slug 进错误信息：单看 outcome（record 之外）也能定位是哪个任务超时
-    error: `engine_timeout: [slug=${task.description ?? "unknown"}] ${engineTimeoutDetail(stdoutTail)}`,
-    // 被信号杀死：退出码语义为 null（§3.3.5 AgentOutcome.exitCode 注释）
-    exitCode: null,
-    engineId,
-  };
-}
-
-// ============================================================
-// abort 两级编排
-// ============================================================
-
-/** 原生中断后的宽限窗口默认值（ms）：中断指令送达 → 引擎自行收尾的等待上限。 */
-export const DEFAULT_NATIVE_INTERRUPT_GRACE_MS = 3_000;
-
-/**
- * abort 两级编排 helper（D1 abort 分级的公共实现）：
- * signal abort 时 ①先调引擎原生中断（tryNativeInterrupt，若有）并给宽限窗口，
- * 窗口内未停（或无原生中断——CLI-only 引擎）则 ②走杀链兜底。
- *
- * 进程自然退出时以 'terminated' settle（挂在 exit 事件上，杀链对已退进程是 no-op），
- * 调用方可安全 await；signal 永不 abort 且进程已退时也会 settle，不悬挂。
- */
-export function abortWithFallback(
-  child: KillableChild,
-  signal: AbortSignal,
-  tryNativeInterrupt?: () => Promise<void>,
-  opts?: { graceMs?: number; nativeGraceMs?: number },
-): Promise<"terminated" | "killed"> {
-  const graceMs = opts?.graceMs ?? DEFAULT_KILL_GRACE_MS;
-  const nativeGraceMs = opts?.nativeGraceMs ?? DEFAULT_NATIVE_INTERRUPT_GRACE_MS;
-
-  return new Promise<"terminated" | "killed">((resolve) => {
-    let settled = false;
-    // 三个 handler 互相引用（finish 移除 onAbort / onAbort 触发 runChain / runChain
-    // 兜底 finish），用函数声明 + 提升消解声明环，避免 use-before-define。
-    function finish(result: "terminated" | "killed"): void {
-      if (settled) return;
-      settled = true;
-      signal.removeEventListener("abort", onAbort);
-      resolve(result);
-    }
-
-    function onExit(): void {
-      finish("terminated");
-    }
-
-    function runChain(): void {
-      void (async () => {
-        if (tryNativeInterrupt) {
-          try {
-            await tryNativeInterrupt();
-          } catch (err) {
-            // 原生中断失败（协议错/管道断）→ 直接落杀链，中断失败不阻断兜底。
-            // debug 级留诊断线索：这不是错误终态，只是该引擎优雅中断不可用
-            logger.debug(
-              `[kill-chain] native interrupt failed, falling back to kill chain: ${
-                toErrorMessage(err)
-              }`,
-            );
-          }
-          const stopped = await raceTimeout(waitForExit(child), nativeGraceMs);
-          if (stopped === "settled" || settled) return; // 原生中断生效，进程已停
-        }
-        finish(await killChain(child, { graceMs }));
-      })();
-    }
-
-    function onAbort(): void {
-      runChain();
-    }
-
-    // 进程自然退出（含原生中断生效）→ 优雅终止口径。
-    // once listener 不显式移除：触发时 finish 已幂等，单 child 单 listener 无堆积。
-    child.once("exit", onExit);
-    if (child.exitCode !== null || child.signalCode !== null) {
-      finish("terminated");
-      return;
-    }
-
-    if (signal.aborted) runChain();
-    else signal.addEventListener("abort", onAbort, { once: true });
-  });
-}
-
-// ── 内部工具 ────────────────────────────────────────────────────
-
-/** 等 child 退出（已退出立即 settle；否则挂一次性 exit listener）。 */
-function waitForExit(child: KillableChild): Promise<void> {
-  return new Promise<void>((resolve) => {
-    if (child.exitCode !== null || child.signalCode !== null) {
-      resolve();
-      return;
-    }
-    child.once("exit", () => resolve());
-  });
-}
-
-/** promise vs 超时：超时先到返回 'timeout'（promise 继续但被放弃等待）。unref 见 KillChainOptions。 */
-function raceTimeout(p: Promise<void>, ms: number, unref = false): Promise<"settled" | "timeout"> {
-  return new Promise<"settled" | "timeout">((resolve) => {
-    const timer = setTimeout(() => resolve("timeout"), ms);
-    if (unref) timer.unref();
-    p.then(
-      () => {
-        clearTimeout(timer);
-        resolve("settled");
-      },
-      () => {
-        // 被 await 的 exit promise 不会 reject；防御分支保持语义完整（超时口径胜出前出错按 settled 处理）
-        clearTimeout(timer);
-        resolve("settled");
-      },
-    );
-  });
-}
+// 超时杀链与 abort 两级中断的 re-export shim：实现体单源
+// @zhushanwen/subagent-engine-sdk（自本文件逐字等价移入 SDK，s4-reuse 簇 1；
+// core → SDK 边界正向合法，设计权威源 D1/§3.3.3 注释随实现留在 SDK 侧）。
+// core 内消费方（subprocess-agent-runner 与本目录测试）import 路径保持不变。
+// 唯一签名差异：SDK 版 synthesizeTimeoutOutcome 第 3 参 engineId 必填
+//（core 原缺省 DEFAULT_ENGINE_ID="pi" 的隐式行为随收编删除——core 非测试
+// 代码零调用方，无生产行为影响）。
+
+export {
+  abortWithFallback,
+  DEFAULT_KILL_GRACE_MS,
+  DEFAULT_NATIVE_INTERRUPT_GRACE_MS,
+  HOST_TIMEOUT_ABORT_REASON,
+  killChain,
+  type KillableChild,
+  type KillChainOptions,
+  synthesizeTimeoutOutcome,
+} from "@zhushanwen/subagent-engine-sdk";

package/src/execution/engine/common/nesting-guard.ts

@@ -1,116 +1,20 @@
 // src/execution/engine/common/nesting-guard.ts
 //
-// 嵌套防护（P2 公共降级层）。设计权威源：
-// docs/architecture/subagent-engine-abstraction.md D8（嵌套防护双层）：
-//   统一 XYZ_AGENT_SUBAGENT=1 标记（所有引擎 spawn 都注入，引擎 adapter 检测到即拒绝
-//   递归派发）+ 剥离各引擎原生标记（CC 的 CLAUDECODE / zsub 的 ZSW_NESTED / pi 的
-//   PI_SUBAGENT_*）防继承泄漏——子代理环境的旧标记会让孙代理误判自己已在嵌套层。
-//
-// 为什么 env 标记是唯一跨引擎可靠手段（被否方案见设计）：「隔离目录里不装扩展」
-// 依赖配置洁癖，且 opencode/CC 会吃项目级配置；env 由宿主显式控制，随 spawn 必达。
-//
-// [D3-⑤ 嵌套防护合一] 进程内执行嵌套上下文（原 SubagentService.execCtxAls，pi 路径
-// 私有）并入本文件——「嵌套防护」的两层机制（跨进程 env 标记 / 进程内 ALS 深度计数）
-// 单点于公共层。设计权威源：docs/design/subagent-dual-track-convergence.md §3.3 D3-⑤
-// + 双轨清单 #10。
-
-import { AsyncLocalStorage } from "node:async_hooks";
-
-import { nestedSpawnRejectedError } from "./errors.ts";
-
-/** 统一嵌套标记 env 名（D8）。值恒 '1'。 */
-export const NESTED_SPAWN_ENV = "XYZ_AGENT_SUBAGENT";
-
-/** 需剥离的引擎原生嵌套标记（精确名）。 */
-const NATIVE_NESTED_KEYS: readonly string[] = ["CLAUDECODE", "ZSW_NESTED"];
-
-/** 需剥离的引擎原生嵌套标记前缀（pi 家族）。 */
-const NATIVE_NESTED_PREFIXES: readonly string[] = ["PI_SUBAGENT_"];
-
-/** env 对象形状（NodeJS.ProcessEnv 的结构子集，测试可传普通对象）。 */
-export type SpawnEnv = Record<string, string | undefined>;
-
-/**
- * 构造子代理 spawn env：注入 XYZ_AGENT_SUBAGENT=1 + 剥离引擎原生嵌套标记。
- * 返回新对象，不改入参（spawn env 组装链中的多层 spread 安全）。
- */
-export function buildNestedSpawnEnv(baseEnv: SpawnEnv): SpawnEnv {
-  const env: SpawnEnv = {};
-  for (const [key, value] of Object.entries(baseEnv)) {
-    if (NATIVE_NESTED_KEYS.includes(key)) continue;
-    if (NATIVE_NESTED_PREFIXES.some((prefix) => key.startsWith(prefix))) continue;
-    env[key] = value;
-  }
-  env[NESTED_SPAWN_ENV] = "1";
-  return env;
-}
-
-/**
- * 嵌套 spawn 防护断言：检测到统一标记（本进程已是 subagent）抛
- * EngineError(nested_spawn_rejected)——文案说明防护规则、指向 task 内自行完成。
- * 调用点：subagent 工具入口（进程创建前拒绝，D11 处置三级）。
- */
-export function assertNotNestedSpawn(env: SpawnEnv): void {
-  if (env[NESTED_SPAWN_ENV] === "1") {
-    throw nestedSpawnRejectedError();
-  }
-}
-
-// ============================================================
-// [D3-⑤] 进程内执行嵌套上下文（原 SubagentService.execCtxAls 下沉）
-// ============================================================
-
-/** 执行嵌套状态：当前正在跑的 record 身份 + 递归深度（D-033 通用嵌套深度护栏的计数载体）。 */
-export interface ExecutionNestingState {
-  recordId: string | undefined;
-  depth: number;
-}
-
-/**
- * 进程内执行嵌套上下文（[D3-⑤] 从 SubagentService 的 execCtxAls 私有字段并入公共层）。
- *
- * 机制（原样迁移，行为零变化）：
- *   - ALS 按异步调用链传递当前 record 身份：B run() 期间包 this 上下文，B 内创建 C 时
- *     读到 B → C.parentRecordId=B.id、C.depth=B.depth+1；主 session 链上无 store → 顶层。
- *   - 进程级基线兜底 [ALS 断裂修复]：pi RPC mode 的 stdin JSONL 是事件回调式
- *     （attachJsonlLineReader stream.on("data")），每个命令是独立异步链，enterWith 的
- *     store 不会贯穿到后续 tool 调用事件（实测：递归第二层 parentRecordId/depth 丢失
- *     而 rootSessionId 正确）。基线 = 本进程自己的身份（initSession 从 env 读取）：
- *     读 ALS store 失败时兜底，保证「本进程派发的 subagent 都是本进程记录的孩子」。
- *
- * 实例归属：per-Service（基线随宿主进程身份而异），Service 构造时创建并持有。
- * 深度上限判据（MAX_FORK_DEPTH）留在调用方——上限常量属 execution 层
- * （session-context-resolver），公共层只提供状态存取单点。
- */
-export class ExecutionNestingContext {
-  private readonly als = new AsyncLocalStorage<ExecutionNestingState>();
-  private baselineState: ExecutionNestingState | null = null;
-
-  /** 建立进程级基线（initSession：有 env 自我标记 → env 身份；根进程 → null 顶层）。 */
-  setBaseline(state: ExecutionNestingState | null): void {
-    this.baselineState = state;
-  }
-
-  /** 读当前嵌套状态：ALS store 优先，断裂时基线兜底（顶层 = null）。 */
-  current(): ExecutionNestingState | null {
-    return this.als.getStore() ?? this.baselineState;
-  }
-
-  /**
-   * 读进程级基线（与 current() 的差异：不看 ALS store——直接父归属校验等场景要的是
-   * 「本进程自己的身份」而非「当前异步链正在跑的 record 身份」）。
-   */
-  baseline(): ExecutionNestingState | null {
-    return this.baselineState;
-  }
-
-  /** 包裹执行（B run() 期间挂 B 身份——内层创建 C 时 current() 读到 B）。 */
-  run<T>(state: ExecutionNestingState, fn: () => T): T {
-    return this.als.run(state, fn);
-  }
-
-  /** 顶层 enterWith（initSession 建立基线身份后挂入当前异步链）。 */
-  enterWith(state: ExecutionNestingState): void {
-    this.als.enterWith(state);
-  }
-}
+// 嵌套防护（跨进程 env 标记 + 进程内 ALS 深度计数）的 re-export shim：实现体单源
+// @zhushanwen/subagent-engine-sdk（自本文件逐字等价移入 SDK，s4-reuse 簇 2；
+// 设计权威源 D8 / D3-⑤ 注释随实现留在 SDK 侧）。core 内消费方（subagent-service
+// 与本目录测试）import 路径保持不变。唯一行为差异：assertNotNestedSpawn 抛
+// NestedSpawnRejectedError（SDK 形态，code/recovery 文案逐字一致）而非 core
+// EngineError——该函数在 core 非测试代码零调用方，错误类形态差异无生产影响。
+// 错误类随 shim 一并导出（本目录测试断言消费；core barrel 不转发本模块，无对外
+// 导出面影响）。
+
+export {
+  assertNotNestedSpawn,
+  buildNestedSpawnEnv,
+  ExecutionNestingContext,
+  type ExecutionNestingState,
+  NestedSpawnRejectedError,
+  NESTED_SPAWN_ENV,
+  type SpawnEnv,
+} from "@zhushanwen/subagent-engine-sdk";

package/src/execution/engine/common/pool-manager.ts

@@ -15,6 +15,10 @@
 //   2. journal-*.jsonl 不随池删——生命周期跟随 record，release 只删「该 record 自己的」
 //      journal（record GC 时联动，避免「池删导致仍存 record 的历史从②级静默跌③级」）；
 //   3. 删除失败置 .pool-cleanup-failed 标记文件（可观测不静默），启动期扫描该标记告警。
+//   隔离库边界（2026-09 会话库隔离，设计 docs/design/zcode-session-db-isolation.md D4）：
+//   zcode 隔离会话库不在池目录内，但 TTL 扫描会枚举 session-db/（engines/<id>/ 下每个
+//   子目录都被当池遍历）——db.sqlite* 不匹配任何删除条件（无 refs.json 早退；孤儿 journal
+//   只匹配 journal-*.jsonl），由 A9 守卫测试（公共 API + 枚举断言）钉死。
 //
 // TTL 兜底（cleanupExpiredPoolRefs）：record 主数据的死亡（主 session 文件被 pi 侧
 // 管理）对 core 无触发点，done record 的 journal 因此没有精确回收锚——按 30 天 mtime

package/src/execution/engine/common/session-view-service.ts

@@ -25,23 +25,28 @@
 // pi 分支维持现状（A1 守护）：pi 历史走 runtime 自有 JSONL 直读链
 // （session-service.getSubagentHistory），不经本模块；engineId='pi' 的防御分支
 // 返回空数组，与被收敛前的 runtime 实现一致。
+//
+// [W11/H1] 零静态引擎依赖（设计 §3.8 DoD#3）：①级 native reader 全部经
+// registerNativeSessionReader 注入——core 不再静态 import engines/zcode 的
+// reader/constants/db-path（zcode sqlite 直读迁引擎进程，宿主经协议 read 消费；
+// dbPath 白名单/池锚定判定随 reader 迁 @zhushanwen/zcode-subagent-cli，A plan
+// 证据面由 zcode 包 e2e 接替，原 svs-zcode-dbpath 守护测试随迁删除）。
 
 import { randomUUID } from "node:crypto";
-import { homedir } from "node:os";
 import { isAbsolute, relative, resolve } from "node:path";
 
 // 相对 import 用 .js 形态（本文件是双端复用模块，被 xyz-agent runtime import——对齐
-// engines/zcode/reader.ts 先例：runtime tsconfig 无 allowImportingTsExtensions，.ts
-// 形态在 runtime tsc 下报 TS5097；.js 后缀经 bundler/ESM 解析器 substitution 到 .ts）。
+// 先例：runtime tsconfig 无 allowImportingTsExtensions，.ts 形态在 runtime tsc 下报
+// TS5097；.js 后缀经 bundler/ESM 解析器 substitution 到 .ts）。
+// aggregateUsage 单源 SDK（原 ./session-view-projection.js 逐字等价双活副本已删）。
+// 包名 import 在 runtime 编译图可解析（先例：dialog-queue.ts 同式 import SDK barrel）。
+import { aggregateUsage } from "@zhushanwen/subagent-engine-sdk";
 import { getLogger } from "../../../core/logger.js";
 import { createRecord, updateFromEvent } from "../../execution-record.js";
 import type { Turn } from "../../types.js";
-import { readZcodeSessionView } from "../engines/zcode/reader.js";
-import { ZCODE_ENGINE_ID, ZCODE_HOST_DB_SUFFIX } from "../engines/zcode/constants.js";
-import { resolveEnginesRoot, resolvePoolDir } from "../paths.js";
+import { resolveEnginesRoot } from "../paths.js";
 import type { SessionView } from "../types.js";
 import { replayJournal } from "./event-journal.js";
-import { aggregateUsage } from "./session-view-projection.js";
 import type {
   EngineHandleView,
   EngineToolCallSource,
@@ -50,18 +55,27 @@ import type {
   SubagentRecordSnapshot,
 } from "./session-view-types.js";
 import { parseEngineHandle } from "./session-view-types.js";
-import { toErrorMessage } from "../../../core/error-message.ts";
 
 const logger = getLogger("subagents");
 
 /**
  * 缺省引擎 id（与 registry.ts 的 DEFAULT_ENGINE_ID 同值本地锚定——对齐
- * engines/pi/reader.ts 的 PI_ENGINE_ID 先例：import registry 会连带 port.ts →
+ * inproc reader（已删） 的 PI_ENGINE_ID 先例：import registry 会连带 port.ts →
  * stream-sink.ts 的 .ts 后缀值 import 链进 runtime tsc 编译图，破坏双端复用闭包
  * 约束；锚定漂移由本包 registry.test / 读取链测试双重守护）。
  */
 const DEFAULT_ENGINE_ID = "pi";
 
+/**
+ * ③级 outcome-only 占位 assistant 文案（subagent-nonpi-visibility-followups 设计
+ * §3.3 D6 三端锚点）。core 生产代码不 import shared（双端复用约束，见上方 import
+ * 注释），故本地同值常量 + 锚定注释：权威值 = packages/shared 的
+ * SUBAGENT_OUTCOME_PLACEHOLDER（'(no outcome recorded)'）；同值漂移由 runtime
+ * test/subagent-extractor-engine.test.ts 契约钉子用例的行为断言守护（③级投影占位
+ * content === shared 常量）——core 改文案即该用例翻红。
+ */
+const OUTCOME_PLACEHOLDER_TEXT = "(no outcome recorded)";
+
 // ============================================================
 // 引擎 id 提取（record 路由段）
 // ============================================================
@@ -83,8 +97,12 @@ export function extractEngineId(record: SubagentRecordSnapshot): string {
 /**
  * 引擎原生 reader（①级）：handle + dataDir → SessionView。
  * 返回 undefined = 本级不可达/失败（编排层降②级）；reader 内部自行留 debug 日志。
- * 双端复用约束（设计 §3.3.7，与 zcode/reader.ts 同款）：实现必须无状态纯函数、
- * 不 import 引擎运行时件（launcher/preparer/parser）。
+ * 双端复用约束（设计 §3.3.7）：实现必须无状态纯函数、不 import 引擎运行时件。
+ *
+ * [W11/H1] 本模块零静态引擎依赖：①级 reader 全部经注入面注册——生产调用方 =
+ * runtime 协议客户端（W8 subagent-engine-history 把「协议 read」注册为引擎原生
+ * reader，引擎 id 动态、zcode sqlite 直读在引擎进程内完成）；注册表初始为空，
+ * 未注册引擎直接落②级 journal。
  */
 export type NativeSessionReader = (
   handle: EngineHandleView,
@@ -102,18 +120,15 @@ function getReaderSlot(): Map<string, NativeSessionReader> {
     | undefined;
   if (!slot) {
     slot = new Map();
-    // 内置注册：core 自带 reader 的引擎（当前仅 zcode——pi 的历史读取按 D1 范围声明
-    // 走 runtime 自有 JSONL 直读链，不注册原生 reader）
-    slot.set(ZCODE_ENGINE_ID, readZcodeNativeTier);
     Reflect.set(globalThis, NATIVE_READER_SLOT_KEY, slot);
   }
   return slot;
 }
 
 /**
- * 登记引擎原生 reader（未来引擎 / 测试注入 fake 用）。重复注册同 id = 覆盖
- * （幂等，对齐 registerEngine 惯例）。生产调用方 = core 内新引擎的接入模块；
- * xyz-agent runtime 不需要注册（zcode 内置）。
+ * 登记引擎原生 reader（W11/H1 后的唯①级接入点）。重复注册同 id = 覆盖
+ * （幂等，对齐 registerEngine 惯例）。生产调用方 = 宿主协议客户端接线
+ * （runtime subagent-engine-history 的 ensureProtocolReaderFor）。
  */
 export function registerNativeSessionReader(engineId: string, reader: NativeSessionReader): void {
   getReaderSlot().set(engineId, reader);
@@ -124,65 +139,9 @@ function lookupNativeSessionReader(engineId: string): NativeSessionReader | unde
   return getReaderSlot().get(engineId);
 }
 
-/** 清空注册表并重置为内置集（测试隔离专用，生产禁用——对齐 clearEngines 惯例）。 */
+/** 清空注册表（测试隔离专用，生产禁用——对齐 clearEngines 惯例）。 */
 export function resetNativeSessionReaders(): void {
-  const slot = getReaderSlot();
-  slot.clear();
-  slot.set(ZCODE_ENGINE_ID, readZcodeNativeTier);
-}
-
-// ============================================================
-// ①级：zcode sqlite 原生读取（内置注册的 reader）
-// ============================================================
-
-/**
- * zcode ①级 reader：sessionRef 的 dbPath/sessionId 重定位 + 白名单 +
- * readZcodeSessionView（extension/runtime 双端复用的同一份 reader）。
- * 语义复刻被收敛前的 runtime readZcodeNativeTier（含共享宿主 HOME 形态的绝对
- * dbPath 精确白名单）：绝对 dbPath 只认宿主 zcode 会话 db（ZCODE_HOST_DB_SUFFIX
- * SSOT 推导，防任意读）；相对路径锚池目录 resolve，越界路径（../ 逃逸 / 跨池）
- * 拒绝降②级；读取失败（结构化错误）降②级。
- */
-async function readZcodeNativeTier(
-  handle: EngineHandleView,
-  dataDir: string,
-): Promise<SessionView | undefined> {
-  const dbPathRaw = handle.sessionRef["dbPath"];
-  const sessionId = handle.sessionRef["sessionId"];
-  if (typeof dbPathRaw !== "string" || typeof sessionId !== "string") {
-    logger.debug("[session-view-service] zcode tier1 skipped: handle missing dbPath/sessionId");
-    return undefined;
-  }
-  let dbPath: string;
-  if (dbPathRaw.startsWith("/")) {
-    // 共享宿主 HOME 形态（2026-09 起，写侧 zcode-engine 恒绝对路径）：唯一合法绝对
-    // 路径 = 宿主 zcode 会话 db（record 来自 JSONL 文本不可信，精确匹配 core SSOT
-    // 后缀拼出的路径，防任意读）
-    if (dbPathRaw !== resolve(homedir(), ...ZCODE_HOST_DB_SUFFIX)) {
-      logger.warn(
-        `[session-view-service] zcode absolute dbPath not host db, reject tier1: ${dbPathRaw}`,
-      );
-      return undefined;
-    }
-    dbPath = dbPathRaw;
-  } else {
-    // 旧池时代 records（HOME 池化时期）：相对路径锚池目录重定位，白名单防逃逸
-    const poolDir = resolvePoolDir(dataDir, ZCODE_ENGINE_ID, handle.poolKey);
-    dbPath = resolve(poolDir, dbPathRaw);
-    if (!isStrictlyUnder(poolDir, dbPath)) {
-      logger.warn(`[session-view-service] zcode dbPath escapes pool dir, reject tier1: ${dbPath}`);
-      return undefined;
-    }
-  }
-  try {
-    return await readZcodeSessionView(dbPath, sessionId);
-  } catch (err) {
-    logger.debug(
-      `[session-view-service] zcode tier1 read failed, degrade to journal tier: ` +
-        `${toErrorMessage(err)}`,
-    );
-    return undefined;
-  }
+  getReaderSlot().clear();
 }
 
 // ============================================================
@@ -291,7 +250,7 @@ function replayEventsToHistory(
   return undefined;
 }
 
-function hasTurnContent(turn: Turn): boolean {
+function hasTurnContent(turn: { text: string; thinking: string; toolCalls: unknown[] }): boolean {
   return turn.text !== "" || turn.thinking !== "" || turn.toolCalls.length > 0;
 }
 
@@ -447,7 +406,7 @@ function outcomeOnlyMessages(record: SubagentRecordSnapshot): HistoryMessage[] {
     id: randomUUID(),
     role: "assistant",
     // result 优先（正常轮终文本）；error 次之（失败终态）；双缺占位（运行中被杀等）
-    content: record.result ?? record.error ?? "(no outcome recorded)",
+    content: record.result ?? record.error ?? OUTCOME_PLACEHOLDER_TEXT,
     status: isErrorOutcome ? "error" : "complete",
     timestamp: record.endedAt ?? base,
     ...(isErrorOutcome && record.error !== undefined ? { error: record.error } : {}),
@@ -464,8 +423,8 @@ function outcomeOnlyMessages(record: SubagentRecordSnapshot): HistoryMessage[] {
  *
  * 降级顺序 ①→②→③ 逐级尝试，每级失败留 debug/warn 日志不抛崩溃（GUI 详情页
  * 永不白屏报错，设计 A8）。engineId='pi' 返回 []（pi 的①级 = 调用方现有 JSONL
- * 直读链，A1 守护）。未注册 reader 的引擎（未来）直接落③级——record 字段就够，
- * 详情页至少有摘要卡。
+ * 直读链，A1 守护）。未注册 reader 的引擎（W11 后 = 宿主未接线协议 reader 的
+ * 进程）跳过①级直落②级 journal——record 字段就够，详情页至少有摘要卡。
  *
  * @param record  record 快照（engine/engineHandle 为不可信源，内部守卫消费）
  * @param dataDir xyz-agent 数据根（journal/dbPath 白名单经 paths.ts 布局 SSOT 推导）
@@ -484,16 +443,29 @@ export async function readSubagentHistoryMessages(
     );
     return outcomeOnlyMessages(record);
   }
+  // [W11/H1] ①级 reader 全经注入：未注册（W11 后注册表初始为空——宿主未接线协议
+  // reader 的进程）不可跳过②级——journal 是宿主自有数据，与引擎 reader 无关，
+  // 未注册 reader 的引擎仍走②→③（与「reader 失败降②级」同构）。
   const reader = lookupNativeSessionReader(engineId);
-  if (reader === undefined) {
+  if (reader !== undefined) {
+    const native = await reader(handle, dataDir);
+    if (native !== undefined) {
+      // ①级判空降级（设计 D3）：读成功但 turns 无实质内容（text/thinking/toolCalls
+      // 全空，与②级 replayEventsToHistory 的 contentTurns 判定同语义）= 本级不可用，
+      // 降②级——「仅 task」空壳投影（窗口 B）不再从①级放行。
+      if (native.turns.some(hasTurnContent)) return sessionViewToMessages(native, record);
+      logger.debug(
+        `[session-view-service] tier1 native view has no substantive content ` +
+          `(turns=${native.turns.length}), degrade to journal tier ` +
+          `(subagentId=${record.subagentId})`,
+      );
+    }
+  } else {
     logger.debug(
       `[session-view-service] engine '${engineId}' has no native reader tier, ` +
-        `degrade to outcome-only (subagentId=${record.subagentId})`,
+        `fall through to journal tier (subagentId=${record.subagentId})`,
     );
-    return outcomeOnlyMessages(record);
   }
-  const native = await reader(handle, dataDir);
-  if (native !== undefined) return sessionViewToMessages(native, record);
   const journaled = readJournalTier(record, handle, dataDir);
   if (journaled !== undefined) return journaled;
   return outcomeOnlyMessages(record);