@zhushanwen/subagent-core 0.2.0

package/src/core/__tests__/host-services.test.ts

@@ -0,0 +1,144 @@
+// host-services.test.ts —— HostServices 配置态 / NULL_HOST 降级 / DEFAULT_DATA_ROOT。
+//
+// 三视角：①构建者——configureCore 覆盖语义与 getHostServices 解析；②使用者——
+// 未配置消费 dataRoot 得到可操作错误（core_host_not_configured + 恢复指引关键词，
+// 设计 §3.4 错误规格）；③观察者——NULL_HOST 日志落缺省 console（warn/error），
+// discoveryRoots 可选端口缺席为 undefined，DiscoveryRoot.source 标签原样透传。
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  configureCore,
+  DEFAULT_DATA_ROOT,
+  getHostServices,
+  resetCoreForTests,
+  type DiscoveryRoot,
+  type HostServices,
+} from "../host-services.ts";
+
+beforeEach(() => {
+  resetCoreForTests();
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  resetCoreForTests();
+});
+
+function makeHost(overrides: Partial<HostServices> = {}): HostServices {
+  return {
+    dataRoot: () => "/data/root",
+    log: () => {},
+    ...overrides,
+  };
+}
+
+describe("getHostServices（未配置 → NULL_HOST）", () => {
+  it("消费 dataRoot 抛错，message 含 core_host_not_configured", () => {
+    expect(() => getHostServices().dataRoot()).toThrowError("core_host_not_configured");
+  });
+
+  it("错误文案含恢复指引：configureCore 调用时机 + pi 壳 / zsw 壳接入示例落点", () => {
+    try {
+      getHostServices().dataRoot();
+      expect.unreachable("dataRoot must throw before configureCore");
+    } catch (err) {
+      expect(err).toBeInstanceOf(Error);
+      const msg = (err as Error).message;
+      expect(msg).toContain("core_host_not_configured");
+      expect(msg).toContain("configureCore");
+      expect(msg).toContain("pi-host.ts");
+      expect(msg).toContain("README");
+    }
+  });
+
+  it("log warn → console.warn，error → console.error，带 [component] 前缀", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const host = getHostServices();
+
+    host.log("warn", "comp-a", "w-message", { k: 1 });
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toBe("[comp-a] w-message");
+    expect(warnSpy.mock.calls[0][1]).toEqual({ k: 1 });
+    expect(errorSpy).not.toHaveBeenCalled();
+
+    host.log("error", "comp-a", "e-message");
+    expect(errorSpy).toHaveBeenCalledTimes(1);
+    expect(errorSpy.mock.calls[0][0]).toBe("[comp-a] e-message");
+  });
+
+  it("data 缺省时省略第二参数（node console 会把显式 undefined 打成尾巴）", () => {
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    getHostServices().log("warn", "comp-a", "bare");
+    expect(warnSpy.mock.calls[0].length).toBe(1);
+  });
+
+  it("debug 缺省 no-op（对齐 pi-extension-logger debug 默认 no-op 语义）", () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    getHostServices().log("debug", "comp-a", "d-message");
+    expect(logSpy).not.toHaveBeenCalled();
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("discoveryRoots 为 undefined（可选端口缺席）", () => {
+    expect(getHostServices().discoveryRoots).toBeUndefined();
+  });
+});
+
+describe("configureCore", () => {
+  it("配置后 dataRoot / log 路由到宿主实现", () => {
+    const logSpy = vi.fn<HostServices["log"]>();
+    configureCore(makeHost({ dataRoot: () => "/host/root", log: logSpy }));
+
+    const host = getHostServices();
+    expect(host.dataRoot()).toBe("/host/root");
+    host.log("warn", "comp", "msg", { x: 2 });
+    expect(logSpy).toHaveBeenCalledWith("warn", "comp", "msg", { x: 2 });
+  });
+
+  it("DiscoveryRoot.source 标签由宿主提供、core 原样透传（不枚举封闭集）", () => {
+    const roots: DiscoveryRoot[] = [
+      { dir: "/roots/npm", source: "npm" },
+      { dir: "/roots/user-pi", source: "user-pi" },
+      { dir: "/roots/custom-tag", source: "host-defined-anything" },
+    ];
+    configureCore(
+      makeHost({
+        discoveryRoots: () => ({ agents: roots }),
+      }),
+    );
+
+    const resolved = getHostServices().discoveryRoots?.();
+    expect(resolved?.agents).toEqual(roots);
+    expect(resolved?.agents?.[2].source).toBe("host-defined-anything");
+  });
+
+  it("重复调用以后者覆盖（测试切宿主依赖此语义）", () => {
+    const firstLog = vi.fn<HostServices["log"]>();
+    const secondLog = vi.fn<HostServices["log"]>();
+    configureCore(makeHost({ log: firstLog }));
+    configureCore(makeHost({ log: secondLog }));
+
+    getHostServices().log("error", "comp", "msg");
+    expect(firstLog).not.toHaveBeenCalled();
+    expect(secondLog).toHaveBeenCalledTimes(1);
+  });
+
+  it("resetCoreForTests 后回到未配置态（dataRoot 抛错）", () => {
+    configureCore(makeHost());
+    resetCoreForTests();
+    expect(() => getHostServices().dataRoot()).toThrowError("core_host_not_configured");
+  });
+});
+
+describe("DEFAULT_DATA_ROOT", () => {
+  it("等于 ~/.subagent-core（homedir 推导，不写死绝对路径）", () => {
+    expect(DEFAULT_DATA_ROOT).toBe(join(homedir(), ".subagent-core"));
+    expect(DEFAULT_DATA_ROOT.startsWith(homedir())).toBe(true);
+  });
+});

package/src/core/__tests__/logger.test.ts

@@ -0,0 +1,78 @@
+// logger.test.ts —— core log facade 的时序契约（D2「解析时机契约」的直接守护）。
+//
+// 核心场景：模块顶层 `const logger = getLogger(...)` 缓存惯例（切面内 30 处既有形态）
+// 下，configureCore 前后透明切换——facade 每次方法调用动态解析宿主实现，无模块加载
+// 顺序依赖。另覆盖：缺省 console 行为、singleton 缓存惯例、level 逐字透传。
+
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { configureCore, resetCoreForTests, type HostServices } from "../host-services.ts";
+import { getLogger } from "../logger.ts";
+
+// 模块顶层缓存 facade——复刻既有惯例的加载形态：加载期 getLogger，此时宿主必然未
+// 配置。下面的时序契约用例证明：配置后该引用无需重建即路由到宿主实现。
+const topLevelLogger = getLogger("top-level-comp");
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  resetCoreForTests();
+});
+
+describe("facade 顶层缓存惯例 + configureCore 前后透明切换（时序契约）", () => {
+  it("顶层缓存的 logger：配置前落缺省 console，配置后同一引用路由到宿主实现", () => {
+    // 1) configureCore 前：facade 调用落缺省 console（warn 通道）。
+    const warnSpy = vi.spyOn(console, "warn").mockImplementation(() => {});
+    topLevelLogger.warn("before-configure", { stage: 1 });
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    expect(warnSpy.mock.calls[0][0]).toBe("[top-level-comp] before-configure");
+    expect(warnSpy.mock.calls[0][1]).toEqual({ stage: 1 });
+
+    // 2) configureCore：宿主 log 接线（模拟宿主壳初始化时点，晚于本模块加载）。
+    const hostLog = vi.fn<HostServices["log"]>();
+    configureCore({ dataRoot: () => "/host/root", log: hostLog });
+
+    // 3) 同一引用（未重建、未重新 getLogger）调用即刻路由到宿主实现——无模块加载
+    //    顺序依赖；console 缺省出口不再被消费。
+    topLevelLogger.warn("after-configure");
+    topLevelLogger.error("fatal-after-configure", { code: 7 });
+    expect(hostLog).toHaveBeenCalledWith("warn", "top-level-comp", "after-configure", undefined);
+    expect(hostLog).toHaveBeenCalledWith("error", "top-level-comp", "fatal-after-configure", {
+      code: 7,
+    });
+    expect(warnSpy).toHaveBeenCalledTimes(1); // 配置后不再增长
+  });
+
+  it("debug 也经同一动态解析链路（配置前 no-op、配置后路由宿主）", () => {
+    const logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+    topLevelLogger.debug("dbg-before");
+    expect(logSpy).not.toHaveBeenCalled(); // 缺省 no-op
+
+    const hostLog = vi.fn<HostServices["log"]>();
+    configureCore({ dataRoot: () => "/host/root", log: hostLog });
+    topLevelLogger.debug("dbg-after");
+    expect(hostLog).toHaveBeenCalledWith("debug", "top-level-comp", "dbg-after", undefined);
+  });
+});
+
+describe("getLogger", () => {
+  it("同 component 返回同一引用（singleton 缓存惯例，对齐 pi-extension-logger）", () => {
+    expect(getLogger("same-comp")).toBe(getLogger("same-comp"));
+  });
+
+  it("不同 component 返回不同 facade", () => {
+    expect(getLogger("comp-a")).not.toBe(getLogger("comp-b"));
+  });
+
+  it("level/component/message/data 四参逐字透传宿主（调用面等价替换的前提）", () => {
+    const hostLog = vi.fn<HostServices["log"]>();
+    configureCore({ dataRoot: () => "/host/root", log: hostLog });
+
+    const logger = getLogger("pass-through-comp");
+    logger.debug("m1", { a: 1 });
+    logger.warn("m2");
+    logger.error("m3", null);
+    expect(hostLog).toHaveBeenNthCalledWith(1, "debug", "pass-through-comp", "m1", { a: 1 });
+    expect(hostLog).toHaveBeenNthCalledWith(2, "warn", "pass-through-comp", "m2", undefined);
+    expect(hostLog).toHaveBeenNthCalledWith(3, "error", "pass-through-comp", "m3", null);
+  });
+});

package/src/core/__tests__/notify-ports.test.ts

@@ -0,0 +1,104 @@
+// notify-ports.test.ts —— NotifyDomainPorts 配置态 / 缺省降级语义 / 重置隔离。
+//
+// 缺席语义（设计 D2 + §3.4 core_port_missing「可选端口缺席是合法形态」）：
+//   - 计数器缺席 → 恒 0（零活跃，pending 门全开）——缺省内聚在端口层；
+//   - 投递工厂缺席 → createDelivery 为 undefined，由消费方降级直发（后续单元接线）。
+
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import {
+  configureNotifyDomain,
+  getNotifyDomainPorts,
+  resetNotifyDomainForTests,
+  type DeliveryConfig,
+  type DeliveryHandle,
+  type DeliveryPort,
+} from "../notify-ports.ts";
+
+beforeEach(() => {
+  resetNotifyDomainForTests();
+});
+
+afterEach(() => {
+  resetNotifyDomainForTests();
+});
+
+/** 形态对齐 pi 会话 JSONL 的 pending register/unregister custom entry（unknown[] 注入）。 */
+function pendingEntries(): unknown[] {
+  return [
+    { customType: "pending:register", data: { id: "sa-1" } },
+    { customType: "other:entry" },
+    { customType: "pending:unregister", data: { id: "sa-1" } },
+  ];
+}
+
+function makePort(): DeliveryPort {
+  return {
+    supportedPayloads: ["custom"],
+    isIdle: () => true,
+    hasPendingMessages: () => false,
+    send: () => {},
+  };
+}
+
+describe("getNotifyDomainPorts（未注入 → 缺省降级）", () => {
+  it("计数器缺省恒 0（即便 entries 含 pending 形态内容也不消费）", () => {
+    const ports = getNotifyDomainPorts();
+    expect(ports.countActiveFromEntries?.([])).toBe(0);
+    expect(ports.countActiveFromEntries?.(pendingEntries())).toBe(0);
+  });
+
+  it("投递工厂缺席为 undefined（消费方降级直发的判据）", () => {
+    expect(getNotifyDomainPorts().createDelivery).toBeUndefined();
+  });
+});
+
+describe("configureNotifyDomain", () => {
+  it("注入计数器后按实现计数，entries 原样透传", () => {
+    const counter = vi.fn<(entries: unknown[]) => number>((entries) => entries.length);
+    configureNotifyDomain({ countActiveFromEntries: counter });
+
+    const entries = pendingEntries();
+    expect(getNotifyDomainPorts().countActiveFromEntries?.(entries)).toBe(3);
+    expect(counter).toHaveBeenCalledWith(entries);
+  });
+
+  it("注入投递工厂后可调用，port/options 透传、handle 原样返回", () => {
+    const port = makePort();
+    const options: DeliveryConfig = { intent: "interrupt-at-turn-boundary", mergeWindowMs: 60_000 };
+    const handle: DeliveryHandle = {
+      send: () => {},
+      flush: () => {},
+      dispose: () => {},
+    };
+    const factory = vi.fn((receivedPort: DeliveryPort, receivedOptions?: DeliveryConfig): DeliveryHandle => {
+      expect(receivedPort).toBe(port);
+      expect(receivedOptions).toBe(options);
+      return handle;
+    });
+    configureNotifyDomain({ createDelivery: factory });
+
+    const ports = getNotifyDomainPorts();
+    expect(ports.createDelivery?.(port, options)).toBe(handle);
+    expect(factory).toHaveBeenCalledTimes(1);
+  });
+
+  it("重复注入以后者覆盖", () => {
+    const first = vi.fn<(entries: unknown[]) => number>(() => 1);
+    const second = vi.fn<(entries: unknown[]) => number>(() => 2);
+    configureNotifyDomain({ countActiveFromEntries: first });
+    configureNotifyDomain({ countActiveFromEntries: second });
+
+    expect(getNotifyDomainPorts().countActiveFromEntries?.([])).toBe(2);
+    expect(first).not.toHaveBeenCalled();
+  });
+
+  it("resetNotifyDomainForTests 后回到缺省降级（计数 0 / 工厂缺席）", () => {
+    configureNotifyDomain({ countActiveFromEntries: () => 99 });
+    resetNotifyDomainForTests();
+
+    const ports = getNotifyDomainPorts();
+    expect(ports.countActiveFromEntries?.(pendingEntries())).toBe(0);
+    expect(ports.createDelivery).toBeUndefined();
+  });
+});

package/src/core/host-services.ts

@@ -0,0 +1,97 @@
+// src/core/host-services.ts
+//
+// HostServices 宿主端口（P0 依赖闭包 port 化）。设计权威源：
+// docs/design/subagent-core-package-extraction.md §3.3 D2 + §3.4 错误规格。
+//
+// core 与宿主（pi 壳 / zsw 壳）的唯一环境服务契约：数据根 / 结构化日志 / 资源发现根。
+// 注入时机：宿主壳初始化最早期 configureCore(host)，core 内模块统一经
+// getHostServices() 取用——解析发生在每次调用时，宿主后续覆盖配置即刻生效。
+//
+// dataRoot 分段归属（计划期细化 2026-08-29）：本端口只返回宿主数据根本身——env
+// 覆盖段（XYZ_AGENT_DATA_DIR 优先）与 warn-once 语义留在 core data-dir.ts，壳不
+// 重复实现。未 configureCore 即消费 dataRoot 抛 core_host_not_configured（§3.4）：
+// 「缺省静默漂目录」被显式报错取代，DEFAULT_DATA_ROOT 供宿主显式采用而非 core 内部
+// 静默兜底。
+
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+import type { LogLevel } from "./logger.ts";
+
+/** 发现根条目：dir 为扫描根路径；source 是宿主提供的语义标签（遮蔽报告透传用）。
+ *  source 不枚举封闭集——core 只透传不解释（宿主如 pi 壳用 user-pi/npm/npm-dev）。 */
+export interface DiscoveryRoot {
+  dir: string;
+  source: string;
+}
+
+export interface HostServices {
+  /** 数据根目录：引擎隔离池 / journal / record 派生存放的锚点。
+   *  pi 壳返回 getAgentDir()（独立 pi 用户 journal 不漂目录）；zsw 壳返回 zsw 数据根。 */
+  dataRoot(): string;
+  /** 结构化日志：对齐现 getLogger 调用面（level/component/message/data）。缺省 sink 按级分化：
+   *  warn/error 走 console、debug no-op（对齐 pi-extension-logger 语义，见 NULL_HOST.log）。 */
+  log(level: LogLevel, component: string, message: string, data?: unknown): void;
+  /** agent/skill/workflow 资源发现根（可选端口，缺席 = 调用方降级）。宿主只提供根列表
+   *  （按优先级低→高）；扫描 / 同名遮蔽（last-writer-wins）/ 遮蔽报告语义归 core 统一。 */
+  discoveryRoots?(): {
+    agents?: DiscoveryRoot[];
+    skills?: DiscoveryRoot[];
+    workflows?: DiscoveryRoot[];
+  };
+}
+
+/** core 缺省数据根（~/.subagent-core，homedir 推导——禁止写死绝对路径，排查规则）。
+ *  供无自有数据根的轻宿主显式采用；core 自身不静默兜底到该值。 */
+export const DEFAULT_DATA_ROOT: string = join(homedir(), ".subagent-core");
+
+// 模块级配置态：configureCore 覆盖式写入（重复调用以后者覆盖——测试切宿主依赖此语义）。
+let configuredHost: HostServices | undefined;
+
+export function configureCore(host: HostServices): void {
+  configuredHost = host;
+}
+
+/** 测试隔离专用：清空配置态（生产禁用——生产宿主配置一次后生命周期与进程一致）。 */
+export function resetCoreForTests(): void {
+  configuredHost = undefined;
+}
+
+const NULL_HOST: HostServices = {
+  dataRoot() {
+    // §3.4 core_host_not_configured：错误必须可操作——指出缺失动作（configureCore
+    // 的调用时机）+ 双宿主接入示例落点。pi 壳接入文件由后续接线单元（u0-wire）创建。
+    throw new Error(
+      "[subagent-core] core_host_not_configured: HostServices is not configured — " +
+        "the host shell must call configureCore(host) during initialization, before any " +
+        "core API that needs host services is consumed. " +
+        "Recovery: pi shell wires HostServices in src/host/pi-host.ts of " +
+        "@zhushanwen/pi-subagent-workflow; zsw shell: see the wiring example in the " +
+        "@zhushanwen/subagent-core package README.",
+    );
+  },
+  log(level, component, message, data) {
+    // 缺省 console 出口（configureCore 前的日志不丢）。格式对齐 pi-extension-logger
+    // 的 `[extName] msg` 前缀，便于 session 日志逆向检索时两形态互通。
+    const line = `[${component}] ${message}`;
+    // data 作第二参数；缺省时必须省略——node console 会把显式 undefined 格式化成
+    // " undefined" 尾巴污染每行输出。
+    if (level === "error") {
+      if (data === undefined) console.error(line);
+      else console.error(line, data);
+      return;
+    }
+    if (level === "warn") {
+      if (data === undefined) console.warn(line);
+      else console.warn(line, data);
+      return;
+    }
+    // debug 缺省 no-op：对齐 pi-extension-logger 的 debug 默认 no-op 语义（未配置期
+    // 多为模块加载窗口，刷屏无诊断价值）；warn/error 不可静默。
+  },
+  // discoveryRoots 刻意不实现：可选端口缺席 = undefined，由调用方走缺省发现语义。
+};
+
+export function getHostServices(): HostServices {
+  return configuredHost ?? NULL_HOST;
+}

package/src/core/logger.ts

@@ -0,0 +1,47 @@
+// src/core/logger.ts
+//
+// core log facade（替代 @zhushanwen/pi-extension-logger 的 core 内统一入口）。
+// 设计权威源：docs/design/subagent-core-package-extraction.md §3.3 D2「解析时机契约」。
+//
+// 为什么是 facade 代理而不是绑死实现：切面内 30 处既有惯例是模块顶层
+// `const logger = getLogger(...)`（模块加载期创建并缓存实例，彼时宿主必然尚未
+// configureCore）。若 getLogger 在创建时就绑定当时配置态，先加载的模块会永远落
+// 缺省 console——典型时序陷阱。facade 在每次方法调用时经 host-services 配置态
+// 动态解析当前宿主实现：configureCore 前落缺省 console，配置后已缓存的顶层
+// logger 透明切换到宿主实现，无模块加载顺序依赖（该时序契约由 logger.test.ts
+// 顶层缓存用例直接守护）。
+
+import { getHostServices } from "./host-services.ts";
+
+/** 日志级别。对齐 @zhushanwen/pi-extension-logger 的 LogLevel（三值，无 info）。 */
+export type LogLevel = "debug" | "warn" | "error";
+
+/** core logger 接口。与 pi-extension-logger 的 ExtensionLogger 结构兼容——
+ *  u0-log 批次替换是纯 import 源替换，调用面（方法名/参数序）逐文件等价。 */
+export interface CoreLogger {
+  debug(msg: string, data?: unknown): void;
+  warn(msg: string, data?: unknown): void;
+  error(msg: string, data?: unknown): void;
+}
+
+// 与 pi-extension-logger 的 getLogger singleton 惯例对齐（同 component 同引用）。
+// facade 自身无状态（解析发生在方法内），缓存只为引用稳定，不影响透明切换。
+const facadeCache = new Map<string, CoreLogger>();
+
+export function getLogger(component: string): CoreLogger {
+  const existing = facadeCache.get(component);
+  if (existing) return existing;
+  const facade: CoreLogger = {
+    debug(msg, data) {
+      getHostServices().log("debug", component, msg, data);
+    },
+    warn(msg, data) {
+      getHostServices().log("warn", component, msg, data);
+    },
+    error(msg, data) {
+      getHostServices().log("error", component, msg, data);
+    },
+  };
+  facadeCache.set(component, facade);
+  return facade;
+}

package/src/core/notify-ports.ts

@@ -0,0 +1,126 @@
+// src/core/notify-ports.ts
+//
+// 通知域窄端口（D2 计划期细化②）。pi 侧完成通知的两机制——@xyz-agent/session-delivery
+// 投递内核工厂 / @zhushanwen/pi-pending-notifications 活跃计数——经本端口结构化注入；
+// HostServices.notify 事件推送按演进纪律②（禁止无真实触点的推测性预留）推迟到 P2
+// zsw 壳首个真实触点（task-notification）再落。
+//
+// 闭包红线：本文件是 core 对上述两包的唯一替代面——下方 Delivery* 结构化类型为手工
+// 转写（与 packages/session-delivery/src/types.ts 逐字段结构兼容），禁止 import 两包
+// （D9 闭包守卫扫描对象）。结构兼容由注入点 typecheck 守护：pi 壳直传真实
+// createDelivery、拆 CountActiveResult.count 时，上游签名漂移即 typecheck 红。
+//
+// 缺席语义（设计 §3.4 core_port_missing 精神：可选端口缺席是合法形态，不报错）：
+//   - 计数器缺席 → 恒 0（零活跃）：pending 门全开，缺省内聚在本端口层。
+//   - 投递工厂缺席 → 消费方降级直发：直发是消费方行为，端口层无法代为执行，
+//     故 createDelivery 刻意保持缺席（undefined），由消费方判缺席降级。
+
+/** 投递意图（与 session-delivery 的 DeliveryIntent 字面量一致）。 */
+export type DeliveryIntent = "interrupt-at-turn-boundary" | "after-run";
+
+/** 文本 payload。 */
+export interface DeliveryTextPayload {
+  kind: "text";
+  content: string;
+}
+
+/** custom message payload（extension 通路）。 */
+export interface DeliveryCustomPayload {
+  kind: "custom";
+  customType: string;
+  content: string;
+  display: boolean;
+  details?: unknown;
+}
+
+/** 判别联合 payload（envelope / payload 分离）。 */
+export type DeliveryPayload = DeliveryTextPayload | DeliveryCustomPayload;
+
+/** 投递消息 envelope。 */
+export interface DeliveryMessage {
+  payload: DeliveryPayload;
+  /** 缺省回落工厂 options.intent。 */
+  intent?: DeliveryIntent;
+  /** 去重 key（工厂开 dedupe 时必填）。 */
+  dedupeKey?: string;
+}
+
+/** port.send 的受理回执（U2 扩展位；void = 受理未知，按成功处理）。 */
+export interface DeliverySendReceipt {
+  accepted: boolean;
+  reason?: string;
+}
+
+/** 投递端口：内核与外部世界的唯一接口（notifier 装配，intent→宿主参数翻译在适配器内）。 */
+export interface DeliveryPort {
+  /** 本通路支持的 payload kind（不支持的 kind 由工厂 fail-fast）。 */
+  supportedPayloads: readonly DeliveryPayload["kind"][];
+  /** 主 agent 是否空闲（gate 投递时机）。 */
+  isIdle(): boolean;
+  /** 是否有排队中的消息。 */
+  hasPendingMessages(): boolean;
+  /** 投递消息。返回受理回执或 void（扩展位——旧实现返回 void 兼容）。 */
+  send(
+    msg: DeliveryMessage,
+    intent: DeliveryIntent,
+  ): void | DeliverySendReceipt | Promise<void | DeliverySendReceipt>;
+  /** agent_settled 边沿订阅。缺省时工厂退化退避轮询；返回退订函数。 */
+  subscribeSettled?(cb: () => void): () => void;
+}
+
+/** 投递工厂 options（notifier 实际消费的字段集；其余策略字段未入端口面）。 */
+export interface DeliveryConfig {
+  intent?: DeliveryIntent;
+  busyPolicy?: "retry-force" | "park";
+  /** 合批窗口（ms）：0 = 关；>0 = 滑动窗口合批。 */
+  mergeWindowMs?: number;
+  /** 合批依赖谓词（禁止用 isIdle 代替——D4 must-fix 语义）。 */
+  mergeHoldActive?: () => boolean;
+  backoff?: { ms: number; max: number };
+  dedupe?: { maxKeys: number };
+  /** 投递失败警告出口（U4：装配方接 logger 使警告落日志盘而非 stderr）。 */
+  warn?: (msg: string, err?: unknown) => void;
+}
+
+/** 投递句柄（notifier 消费面：send / flush / dispose——诊断面 depth 等不入端口）。 */
+export interface DeliveryHandle {
+  /** 唯一常规入口（合批窗口 + 空闲零延迟立即投）。 */
+  send(msg: DeliveryMessage, opts?: { merge?: boolean }): void;
+  /** 强制投递尝试（shutdown flush 等）。 */
+  flush(): void;
+  /** 销毁（清队列 + 清 timer + 退订）。 */
+  dispose(): void;
+}
+
+export interface NotifyDomainPorts {
+  /** pending 活跃计数（pi 会话 entries 中 register − unregister 差集的数值）。
+   *  契约为 number 而非 pi 侧 CountActiveResult：core 消费面只读 count，契约面最窄；
+   *  pi 壳注入时拆 `countActiveFromEntries(entries).count`。 */
+  countActiveFromEntries?(entries: unknown[]): number;
+  /** 投递内核工厂。签名与 @xyz-agent/session-delivery 的 createDelivery 结构兼容，
+   *  pi 壳直传其本体即可。缺席 = 消费方降级直发。 */
+  createDelivery?(port: DeliveryPort, options?: DeliveryConfig): DeliveryHandle;
+}
+
+// 模块级配置态（与 host-services 同款覆盖式语义——重复注入以后者覆盖）。
+let configuredPorts: NotifyDomainPorts | undefined;
+
+export function configureNotifyDomain(ports: NotifyDomainPorts): void {
+  configuredPorts = ports;
+}
+
+/** 测试隔离专用：清空注入态（生产禁用——注入点在宿主壳初始化，生命周期与进程一致）。 */
+export function resetNotifyDomainForTests(): void {
+  configuredPorts = undefined;
+}
+
+const DEFAULT_NOTIFY_PORTS: NotifyDomainPorts = {
+  // 计数缺省恒 0：零活跃是安全侧语义（pending 门全开），且把「缺席按零处理」从
+  // 消费方约定收敛为端口层的机器事实。
+  countActiveFromEntries: () => 0,
+  // createDelivery 刻意缺席（见文件头「缺席语义」）。
+};
+
+export function getNotifyDomainPorts(): NotifyDomainPorts {
+  return configuredPorts ?? DEFAULT_NOTIFY_PORTS;
+}

package/src/execution/__tests__/__fixtures__/notifier-golden-snapshots.json

@@ -0,0 +1,53 @@
+{
+  "_meta": "Golden snapshots for BgNotifier.buildLlmContent — captured pre-migration (commit HEAD at time of capture). Used by migration verification to ensure zero behavioral regression.",
+  "single_closed_success": {
+    "input": { "id": "sa-ptr-7", "status": "closed", "agent": "worker", "result": "done", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"worker\" (sa-ptr-7) completed. Result:\ndone"
+  },
+  "single_closed_with_sessionfile": {
+    "input": { "id": "sa-ptr-2", "status": "closed", "agent": "w", "result": "final result", "sessionFile": "/tmp/sessions/child-2.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-2) completed. Result:\nfinal result\n\nFull transcript: /tmp/sessions/child-2.jsonl"
+  },
+  "single_running_round": {
+    "input": { "id": "sa-ptr-4", "status": "running", "agent": "w", "round": 2, "result": "round2 text", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-4) finished a round. Reply:\nround2 text"
+  },
+  "single_running_round_with_sessionfile": {
+    "input": { "id": "sa-ptr-1", "status": "running", "agent": "w", "round": 1, "result": "round1 text", "sessionFile": "/tmp/sessions/child-1.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-1) finished a round. Reply:\nround1 text\n\nFull transcript: /tmp/sessions/child-1.jsonl"
+  },
+  "single_cancelled": {
+    "input": { "id": "sa-ptr-5", "status": "closed", "closedReason": "cancelled", "agent": "w", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-5) cancelled."
+  },
+  "single_gc_failed": {
+    "input": { "id": "sa-ptr-6", "status": "closed", "closedReason": "gc", "agent": "w", "error": "spawn EPIPE", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-6) failed: spawn EPIPE"
+  },
+  "single_gc_failed_with_patchfile": {
+    "input": { "id": "sa-ptr-8", "status": "closed", "closedReason": "gc", "agent": "w", "error": "spawn EPIPE", "patchFile": "/tmp/patches/sa-ptr-8.patch", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-ptr-8) failed: spawn EPIPE"
+  },
+  "single_closed_with_patchfile_and_sessionfile": {
+    "input": { "id": "sa-ptr-3", "status": "closed", "agent": "w", "result": "did work", "patchFile": "/tmp/patches/sa-ptr-3.patch", "sessionFile": "/tmp/sessions/child-3.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output_contains": "git apply /tmp/patches/sa-ptr-3.patch",
+    "output_ends_with": "\n\nFull transcript: /tmp/sessions/child-3.jsonl"
+  },
+  "single_closed_totalrounds": {
+    "input": { "id": "sa-rounds-1", "status": "closed", "agent": "w", "totalRounds": 3, "result": "", "sessionFile": "/tmp/sessions/child-rounds.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-rounds-1) completed after 3 rounds. Result:\n\n\nFull transcript: /tmp/sessions/child-rounds.jsonl"
+  },
+  "single_closed_no_totalrounds": {
+    "input": { "id": "sa-rounds-2", "status": "closed", "agent": "w", "result": "done", "sessionFile": "/tmp/sessions/child-oneshot.jsonl", "startedAt": 1, "endedAt": 2 },
+    "output": "Subagent \"w\" (sa-rounds-2) completed. Result:\ndone\n\nFull transcript: /tmp/sessions/child-oneshot.jsonl"
+  },
+  "batch_two_closed": {
+    "description": "Two closed records merged in one message (simulating 60s merge window)",
+    "records": [
+      { "id": "batch-1", "status": "closed", "agent": "w1", "result": "result1", "startedAt": 1, "endedAt": 2 },
+      { "id": "batch-2", "status": "closed", "agent": "w2", "result": "result2", "startedAt": 3, "endedAt": 4 }
+    ],
+    "separator": "\n\n---\n\n",
+    "details_shape": { "batch": true, "items": "array-of-records" }
+  }
+}