@zhushanwen/subagent-core 0.6.0 → 0.7.0

package/src/execution/engine/host/host-bridge.ts

@@ -0,0 +1,150 @@
+// src/execution/engine/host/host-bridge.ts
+//
+// HostBridge 契约 + core 侧实现（W6，impl-plan §2.6 / 设计 §3.8 D2 表 + 最小示例）。
+//
+// 归属裁定（设计 §3.8 D2 表逐条）：PiEngineService 的 9 成员中——executeAndAwait /
+// getRecordForAction / collectRecords / closeSubagent / cancel / ChatRoundTicket /
+// record 状态回写 / idle+activate lock 定时器——都是「宿主执行链 / 数据所有权在宿主」，
+// 归 HostBridge（core）；pi 包（W7）经 host/* 反向请求消费本面。spawnedChildren 归
+// 引擎进程（core 镜像见同目录 spawned-children.ts）；sendPromptCommand / EPIPE 兜底 /
+// 冷续轮 resume（stdin-writer）归 pi 包（W7 迁移物）。
+//
+// 本文件只依赖 core 公共类型（types.ts / record-store / stream-sink /
+// lifecycle-manager / orchestration 类型），不 import inproc pi 引擎目录 内部——它是 pi 包
+// 反向请求消费面的契约落点（协议无关，类型闭包经 HostBridgeServiceFace 泛型参数化）。
+// [F-3] cancel 收敛等待面已删（无生产装配点）；D3 core 侧收敛语义由引擎面
+// chat-session.cancel 等价承接，偏差登记见 chat-domain impl-plan §5。
+
+import { armIdleTimer, disarmIdleTimer } from "../../lifecycle-manager.ts";
+import type { AgentResult as WorkflowAgentResult } from "../../../orchestration/models/types.ts";
+import type { StatusFilter } from "../../record-store.ts";
+import type { SubagentStream } from "../../stream-sink.ts";
+import type {
+  AgentEvent,
+  AgentResult,
+  ExecuteOptions,
+  ExecutionRecord,
+  SubagentRecord,
+} from "../../types.ts";
+
+/**
+ * chat 域轮次交接包的 core 契约基座（设计 §3.8 D2「ChatRoundTicket → HostBridge」）。
+ * pi 专有扩展（identity / SessionRunnerContext / SpawnResumeOpts resume）在
+ * pi-engine.ChatRoundTicket extends 本接口（W7 随包迁移；过渡期 record/opts/signal/
+ * priority/stream 五字段的宿主编排语义在此单一权威）。
+ */
+export interface HostChatRoundTicket {
+  record: ExecutionRecord;
+  opts: ExecuteOptions;
+  signal: AbortSignal | undefined;
+  priority: number;
+  stream?: SubagentStream;
+}
+
+/**
+ * HostBridge 的服务实现面（SubagentService 的结构子集，鸭子类型——与原 pi-engine 的
+ * PiEngineService 同一形态的协议化泛化：chat 域轮次面泛型参数化，pi 绑定 =
+ * HostBridgeServiceFace<ChatRoundTicket>，见 pi-host-binding.ts 的 re-export）。
+ * 为什么用结构接口而非 import SubagentService 类型：防 Service 内部演进连锁影响
+ * 契约面 + 测试可注入 fake（PiEngineService 的既有先例，语义照搬）。
+ */
+export interface HostBridgeServiceFace<TTicket extends HostChatRoundTicket = HostChatRoundTicket> {
+  executeAndAwait(
+    opts: ExecuteOptions,
+    signal?: AbortSignal,
+    onEvent?: (event: AgentEvent) => void,
+    stream?: SubagentStream,
+  ): Promise<WorkflowAgentResult>;
+  getRecordForAction(id: string): ExecutionRecord;
+  closeSubagent(record: ExecutionRecord, force: boolean): Promise<void>;
+  cancel(id: string): boolean;
+  collectRecords(limit: number, statusFilter?: StatusFilter): SubagentRecord[];
+  /** chat 域轮次交接（run 的 chat 分支入口）：按 taskId 取走预备包（一次性消费）。 */
+  takeChatRound?(taskId: string): TTicket | undefined;
+  /** 执行预备的 chat 轮次（编排归 Service：pool 槽 + runSpawn + 终态迁移）。 */
+  runChatRound?(ticket: TTicket): Promise<AgentResult>;
+  /** 冷路径续轮（interact message 分支的编排回调：守卫 + record 迁移 + kick-off）。 */
+  resumeChatRound?(record: ExecutionRecord, text: string): void;
+  /** record 状态迁移上报（热路径投递后让 runtime 派生缓存失效 / GUI 回流）。 */
+  reportRecordTransition?(record: ExecutionRecord): void;
+}
+
+/**
+ * HostBridge 接口（设计 §3.8 最小示例，9 方法）。core 侧实现；pi 包经 host/* 反向
+ * 请求消费。签名与最小示例的两处实现级偏差（均按现状语义落地）：
+ *   - getRecordForAction 返回 ExecutionRecord | null（现状实现面的活 record 形态；
+ *     不存在 / 不可达 → null，引擎侧 resolveRecord 的 try/catch 语义内聚到本面）；
+ *   - reportRecordTransition 收 record 对象（现状状态回写以 record 为单位整体上报，
+ *     无 patch 增量形态——造 patch 形态属凭空造词，W7 反向通道载荷再议）。
+ */
+export interface HostBridge {
+  executeAndAwait(
+    opts: ExecuteOptions,
+    signal?: AbortSignal,
+    onEvent?: (event: AgentEvent) => void,
+    stream?: SubagentStream,
+  ): Promise<WorkflowAgentResult>;
+  getRecordForAction(id: string): ExecutionRecord | null;
+  collectRecords(limit: number, filter?: StatusFilter): SubagentRecord[];
+  closeSubagent(record: ExecutionRecord, force: boolean): Promise<void>;
+  cancel(id: string): Promise<void>;
+  takeChatRound(taskId: string): HostChatRoundTicket | null;
+  reportRecordTransition(record: ExecutionRecord): void;
+  armIdleTimer(id: string, ms: number): void;
+  disarmIdleTimer(id: string): void;
+}
+
+/** createHostBridge 依赖（服务面 + idle 超时处置）。 */
+export interface HostBridgeDeps {
+  /** HostBridge 服务实现面（生产 = SubagentService 的结构子集）。 */
+  service: HostBridgeServiceFace;
+  /**
+   * idle timer 超时处置（回收层兜底）：宿主在 arm 时注入杀链回调（现状语义 =
+   * killRecordChildWithEscalation 升级杀，pi-engine.rearmIdleTimerAfterHotPathFailure
+   * 同款）。不注入则 arm 时 throw（无处置的 idle timer = 永不回收的泄漏源，宁可显式）。
+   */
+  onIdleTimeout: (recordId: string) => void;
+  // [F-3 删除登记] 曾有的 waitForRoundTerminal / escalateKill 可选注入（W3 D3 cancel
+  // 终态等待面）已删：createHostBridge 全仓无生产调用点，且该面与生产 cancel 链结构
+  // 冲突（cancelBackground 同步 unregisterChatRoundRoute 后，waitForRoundTerminal 再
+  // race 轮终相位恒等满 3s 超时）。D3 core 侧收敛语义由引擎面等价承接 =
+  // chat-session.cancel（waiter 先于 kill 注册 + killChain 有界升级），偏差登记见
+  // chat-domain-v1x-liveness-governance.impl-plan.md §5。
+}
+
+/** HostBridge core 实现（SubagentService 编排面的协议化视图）。 */
+export function createHostBridge(deps: HostBridgeDeps): HostBridge {
+  const { service } = deps;
+  return {
+    executeAndAwait: (opts, signal, onEvent, stream) =>
+      service.executeAndAwait(opts, signal, onEvent, stream),
+    getRecordForAction: (id) => {
+      try {
+        return service.getRecordForAction(id);
+      } catch {
+        return null;
+      }
+    },
+    collectRecords: (limit, filter) => service.collectRecords(limit, filter),
+    closeSubagent: (record, force) => service.closeSubagent(record, force),
+    /**
+     * cancel 语义 = 受理即返回（service.cancel 同步布尔 → 契约 void）。
+     * [F-3 删除登记] 终态等待/杀链升级面已删（无生产装配点 + 与 cancelBackground 的
+     * 路由注销冲突，见 HostBridgeDeps 尾注）；生产收敛语义由引擎面承接 =
+     * chat-session.cancel（waiter 先于 kill 注册 → 等 roundLifecycle 终态相位 →
+     * CANCEL_SETTLE_GRACE_MS 未收敛走 killChain 有界升级）。resolve 语义归引擎侧
+     * 判 notResumable（契约注释，W6 起如此）。
+     */
+    cancel: async (id) => {
+      service.cancel(id);
+    },
+    takeChatRound: (taskId) => service.takeChatRound?.(taskId) ?? null,
+    reportRecordTransition: (record) => service.reportRecordTransition?.(record),
+    armIdleTimer: (id, ms) => {
+      armIdleTimer(id, () => deps.onIdleTimeout(id), ms);
+    },
+    disarmIdleTimer: (id) => {
+      disarmIdleTimer(id);
+    },
+  };
+}

package/src/execution/engine/host/host-ui-endpoint.ts

@@ -0,0 +1,47 @@
+// src/execution/engine/host/host-ui-endpoint.ts
+//
+// core 壳侧 host/askUser 应答端登记处（W6，R3 MF-A / impl-plan §2.6 末条）。
+//
+// 接线链路：引擎进程经协议帧④ host/askUser 反向请求 → EngineClient reverse-router
+// （W2 已交付，ack 两阶段 R9-2 语义）→ EngineClientOptions.uiRequestHandler 注入点 →
+// 本登记处的 getter（discovery portFactory 构造 EngineClient 时读取）→ SubagentService
+// init/initSession.uiRequestHandler（[D4-④] 唯一注入入口，应答处理复用
+// ui-request-handler-factory / dialog-queue 应答链路；[W3] inproc inproc UI 请求队列（已删）
+// 随 inproc pi 引擎目录 删除消亡——chat 域 UI 请求同样经本通道，关联键 = spawn 轮 runId）。
+//
+// 为什么是登记处而非直接传参：EngineClient 在 discovery portFactory 内构造（惰性，
+// 首次 getEngine），构造点拿不到 Service 实例——进程级 endpoint 槽位把「handler 何时
+// 注册」（session_start）与「EngineClient 何时构造」（首次引擎使用，晚于 session_start）
+// 解耦。globalThis[Symbol.for] 持有防 jiti 双路径加载分裂（registry.ts 同款惯例）。
+
+import type { UiRequestHandler } from "@zhushanwen/subagent-engine-sdk";
+
+const ENDPOINT_SLOT_KEY = Symbol.for(
+  "@zhushanwen/pi-subagent-workflow.hostUiRequestEndpoint",
+);
+
+function endpointSlot(): { handler: UiRequestHandler | undefined } {
+  let slot = Reflect.get(globalThis, ENDPOINT_SLOT_KEY) as
+    | { handler: UiRequestHandler | undefined }
+    | undefined;
+  if (!slot) {
+    slot = { handler: undefined };
+    Reflect.set(globalThis, ENDPOINT_SLOT_KEY, slot);
+  }
+  return slot;
+}
+
+/** 登记壳侧应答端（SubagentService 在 uiRequestHandler 三态写点同步调用：init / initSession / dispose）。 */
+export function setHostUiRequestEndpoint(handler: UiRequestHandler | undefined): void {
+  endpointSlot().handler = handler;
+}
+
+/** 读壳侧应答端（discovery portFactory 构造 EngineClient 时取值；undefined → 引擎收 {unsupported:true} 自行降级）。 */
+export function getHostUiRequestEndpoint(): UiRequestHandler | undefined {
+  return endpointSlot().handler;
+}
+
+/** 测试隔离：清空登记。 */
+export function _resetHostUiRequestEndpointForTest(): void {
+  endpointSlot().handler = undefined;
+}

package/src/execution/engine/host/pi-host-binding.ts

@@ -0,0 +1,91 @@
+// src/execution/engine/host/pi-host-binding.ts
+//
+// pi 引擎的宿主侧绑定点（W6 建立；[W3 chat 域收口] 重写为纯协议形态）。
+// 职责 = pi 引擎的 EnginePort 解析与公共常量的宿主侧单一出口——chat 域 inproc 引擎
+// （inproc pi 引擎目录）已随 chat-domain-v1x-liveness-governance W3 删除，chat 轮次与 run
+// 域同样经协议客户端（RemoteEngine，registry 'pi' 由三级发现装载 cli descriptor）
+// 发往 pi-subagent-cli 引擎进程（G1：pi 引擎单一 CLI 形态，core 壳侧零内建引擎）。
+//
+// 两个出口：
+//   - PI_POOL_KEY 常量：pi 无隔离池（PI_CODING_AGENT_DIR 全局一份）→ poolKey 恒
+//     'shared'。原 inproc pi-engine（已删） 定义随删件收敛到本公共面（字面量不变，
+//     引擎包内侧等价物在 pi-subagent-cli constants.ts——跨包字面量一致性由协议
+//     handle.poolKey 往返锚定）；
+//   - resolveHostPiEnginePort：宿主侧（SAR / chat 域路由）pi EnginePort 解析——
+//     registry 'pi' 返回发现器装载的 cli 形态 port（RemoteEngine）；未注册（引擎包
+//     未装/发现失败）→ 不可用 stub：路由层对 pi 恒同步短路（本地 pi 恒可用口径），
+//     真正的拒绝发生在首次 engine.run——stub 抛 EngineNotFoundError（含安装指引），
+//     由 SAR「不 reject」契约收口进 result.error。
+//
+// maxTurnsToWatchdogMs：maxTurns→watchdog 毫秒换算的 barrel 公共出口（U3/U4 / D7，
+// 两宿主预算一致性 S2 的函数级锚点）。原 inproc session-runner（已删） 定义随删件
+// 收敛到本文件——算法（floor 30min + 每轮 5min，均 floor 语义）与运行时真实消费方
+// （pi-subagent-cli spawn-runner 的 spawn watchdog）保持同源常量，漂移由 conformance
+// chat golden（spawn-args 断言）在引擎包侧守护。
+
+import type { EnginePort } from "../port.ts";
+import { EngineNotFoundError, getEngine, hasEngine, listEngines } from "../registry.ts";
+
+/** pi 无隔离池（PI_CODING_AGENT_DIR 全局一份，协议化设计 §3.3.9），poolKey 恒 'shared'。 */
+export const PI_POOL_KEY = "shared";
+
+/** watchdog 换算下限（分钟）：与引擎包 spawn-runner 的 floor 同源（30min）。 */
+const WATCHDOG_FLOOR_MINUTES = 30;
+/** watchdog 每轮预算（分钟/turn）：同源常量（5min/turn）。 */
+const WATCHDOG_MINUTES_PER_TURN = 5;
+
+const MS_PER_SECOND = 1000;
+const SECONDS_PER_MINUTE = 60;
+
+/** maxTurns → spawn watchdog 毫秒估算（floor 语义：maxTurns 小时取下限）。 */
+export function maxTurnsToWatchdogMs(maxTurns: number): number {
+  return Math.max(
+    WATCHDOG_FLOOR_MINUTES * SECONDS_PER_MINUTE * MS_PER_SECOND,
+    maxTurns * WATCHDOG_MINUTES_PER_TURN * SECONDS_PER_MINUTE * MS_PER_SECOND,
+  );
+}
+
+/**
+ * 宿主侧 pi EnginePort 解析（SAR / chat 域路由）：registry 的 'pi'（发现器装载的
+ * cli descriptor → RemoteEngine）直接返回——chat 轮次与 run 域同路（协议 run(interact)
+ * 发往 pi-subagent-cli 引擎进程）。
+ * [U-2 一致性修复] pi **未注册**（引擎包未装/发现失败）时返回不可用 stub，不静默
+ * 直构任何本地实例——保留设计 D4「全不可用 → 派发期 engine_not_found + 安装指引」
+ * 错误契约（zcode 侧 d8-compat 同语义，两引擎对称）。
+ *
+ * @param getService 未消费（历史签名兼容位——inproc per-session DI 重绑形态随
+ *   inproc pi 引擎目录 删除消亡；保留形参使 SAR 调用点零改动，W8 收口时随调用面一并清理）。
+ */
+export function resolveHostPiEnginePort(_getService?: () => unknown): EnginePort {
+  if (hasEngine("pi")) return getEngine("pi");
+  return piUnavailableEnginePort();
+}
+
+/** pi 不可用 stub（D4）：一切执行面抛 engine_not_found；capabilities 全放行（拒绝点唯一化在 run）。 */
+function piUnavailableEnginePort(): EnginePort {
+  const fail = (): never => {
+    throw new EngineNotFoundError("pi", listEngines());
+  };
+  return {
+    id: "pi",
+    // 与 pi-subagent-cli manifest capabilities 逐位一致（快照权威；stub 的能力位
+    // 只被 gate 同步面在 run 前读取，真正的拒绝发生在 stub.run 抛 engine_not_found）。
+    capabilities: () => ({
+      schemaEnforcement: "native",
+      steer: "unsupported",
+      conversation: "native",
+      personaInjection: "flag",
+      eventGranularity: "stream",
+      sandbox: "emulated",
+      sessionRead: "full",
+      resume: "native",
+      interrupt: "kill-only",
+      permissionMode: "native",
+      maxTurns: true,
+    }),
+    probe: () => fail(),
+    run: () => fail(),
+    interact: () => fail(),
+    read: () => fail(),
+  };
+}

package/src/execution/engine/host/spawned-children.ts

@@ -0,0 +1,139 @@
+// src/execution/engine/host/spawned-children.ts
+//
+// core 侧 spawnedChildren 状态镜像（W6 建立；[W3 chat 域收口] 去除 inproc 过渡桥，
+// 纯镜像形态——设计 §3.8 D2 归属裁定的终态：spawnedChildren Map + 子进程收割的
+// 持有方 = 引擎进程，core 只持状态投影）。
+//
+// 本文件是 core 侧的公共消费面：
+//   - subagent-service / subprocess-agent-runner 的注册与镜像记账调用改经本模块，
+//     不深路径 import 引擎内部（R3 S-C / R1 MF-5 改线落点）；
+//   - lifecycle-predicates（hasLiveProcessHandle / isResumable）读本模块读点。
+//
+// [W3] 数据源两路（协议化形态）：① cli 引擎经 host/childSpawned / childStateChanged
+// 反向通道上报（client/mirror.ts 落本镜像——失效语义同构）；② 历史调用点
+// （cancel/close/idle timer/watchdog 的 killRecordChildWithEscalation）写镜像置死位。
+// 实际进程终止**不经本模块**——子进程活在引擎进程内，终止经协议 interact
+// cancel/close / run 域 cancel 帧承载（宿主侧杀链 = EngineClient killAll 进程组收割，
+// 见 remote-engine abort 分级）。inproc 委托（session-runner Map 并读/委托杀）随
+// inproc pi 引擎目录 删除消亡。
+
+import type { ChildProcess } from "node:child_process";
+
+// 镜像项（recordId 键 + killed 判据，与 client/mirror.ts 载荷契约同构）。
+export interface SpawnedChildMirrorEntry {
+  /** 引擎侧一次性子进程 pid（诊断面；recordId 才是镜像 key）。 */
+  pid?: number;
+  /** 必含判据（`child !== undefined && !child.killed` 同构）：true = 已被杀/已终止。 */
+  killed: boolean;
+  /** 最近一次状态变更的墙钟时间戳（诊断面）。 */
+  updatedAt: number;
+}
+
+/**
+ * core 侧 spawnedChildren 状态镜像（进程级单例，globalThis[Symbol.for] 持有防 jiti
+ * 双路径加载分裂——registry.ts 同款惯例）。镜像只是状态投影：不发信号、不杀进程
+ * （收割 = 引擎进程组级，见文件头）。
+ */
+class CoreSpawnedChildrenMirror {
+  private readonly entries = new Map<string, SpawnedChildMirrorEntry>();
+
+  /** 落项 / 覆盖（同 recordId 重 spawn = 覆盖旧句柄，与引擎侧 Map 同语义）。 */
+  register(recordId: string, child: { pid?: number; killed: boolean }): void {
+    this.entries.set(recordId, {
+      pid: child.pid,
+      killed: child.killed,
+      updatedAt: Date.now(),
+    });
+  }
+
+  /** 单项置死（杀链入口：killRecordChildWithEscalation 途经）。 */
+  markKilled(recordId: string): void {
+    const entry = this.entries.get(recordId);
+    if (entry !== undefined) {
+      entry.killed = true;
+      entry.updatedAt = Date.now();
+    }
+  }
+
+  /** 整体置死 + 清空（失效语义 2+3：引擎 exit / 重建 / dispose / killAll）。 */
+  killAll(): void {
+    this.entries.clear();
+  }
+
+  getChildByRecord(recordId: string): SpawnedChildMirrorEntry | undefined {
+    return this.entries.get(recordId);
+  }
+
+  /** 句柄存活谓词（镜像面；判据与引擎侧 `!child.killed` 同构）。 */
+  hasLiveProcessHandle(recordId: string): boolean {
+    const entry = this.entries.get(recordId);
+    return entry !== undefined && !entry.killed;
+  }
+
+  /** 快照（诊断/测试）。 */
+  snapshot(): SpawnedChildMirrorEntry[] {
+    return [...this.entries.entries()].map(([recordId, entry]) => ({ recordId, ...entry }));
+  }
+
+  /** 测试隔离专用（生产禁用——进程级全局状态）。 */
+  clear(): void {
+    this.entries.clear();
+  }
+}
+
+const MIRROR_SLOT_KEY = Symbol.for(
+  "@zhushanwen/pi-subagent-workflow.coreSpawnedChildrenMirror",
+);
+
+function coreMirrorSlot(): CoreSpawnedChildrenMirror {
+  let slot = Reflect.get(globalThis, MIRROR_SLOT_KEY) as CoreSpawnedChildrenMirror | undefined;
+  if (!slot) {
+    slot = new CoreSpawnedChildrenMirror();
+    Reflect.set(globalThis, MIRROR_SLOT_KEY, slot);
+  }
+  return slot;
+}
+
+/** core 侧镜像访问点（诊断/测试；生产读点走下方公共 API）。 */
+export function coreSpawnedChildrenMirror(): CoreSpawnedChildrenMirror {
+  return coreMirrorSlot();
+}
+
+// ── 公共面 API（subagent-service / SAR 消费）─────────────────────────
+
+/**
+ * 子进程注册（宿主记账回调 RunContext.onChildSpawned 的落点）：写镜像。
+ * 引擎经 host/childSpawned 上报的形态经 client/mirror 落同一张镜像（单源）。
+ */
+export function registerSpawnedChildForRecord(recordId: string, child: ChildProcess): void {
+  coreMirrorSlot().register(recordId, { pid: child.pid, killed: child.killed });
+}
+
+/**
+ * 单 record 终止记账（镜像置死位）：实际终止在引擎进程内（协议 interact cancel /
+ * close 或 run 域 cancel 帧承载）；宿主侧调用点是终止意图的记账面，宿主进程组级
+ * 收割兜底 = EngineClient killAll（EnginePort.dispose / abort 杀链，见 remote-engine）。
+ */
+export function killRecordChildWithEscalation(recordId: string, _source: string): void {
+  coreMirrorSlot().markKilled(recordId);
+}
+
+/** 全量收割记账（dispose / parent-shutdown）：镜像整体置死。 */
+export function killAllSpawnedChildren(_signal: NodeJS.Signals = "SIGTERM"): number {
+  const before = coreMirrorSlot().snapshot().length;
+  coreMirrorSlot().killAll();
+  return before;
+}
+
+/**
+ * 句柄存活读点（lifecycle-predicates 的 hasLiveProcessHandle / isResumable 消费）。
+ * 镜像是唯一数据源（host/childSpawned 上报 + 终止意图置死位）。
+ */
+export function hasLiveProcessHandleCore(recordId: string): boolean {
+  return coreMirrorSlot().hasLiveProcessHandle(recordId);
+}
+
+/** 测试隔离：清镜像。 */
+export function _resetCoreSpawnedChildrenMirrorForTest(): void {
+  coreMirrorSlot().clear();
+}

package/src/execution/engine/host-task-spec.ts

@@ -15,7 +15,9 @@
 //
 // conversation/fork 在调用本 mapper 前已被 capability-gate 预检拒绝（[D3-④]
 // capabilities 驱动的调用前拒绝，非 pi 引擎 unsupported），透传仅保持映射完整性——
-// 未来引擎支持时无需改本函数。
+// 未来引擎支持时无需改本函数。forkFromSessionFile 同属预检面（fork 通道族同判据），
+// 透传语义相同：pi 引擎经协议 task.forkSource 消费（--fork 载体，fork-from 断联恢复），
+// zcode 引擎被 gate 拒绝不会到达。
 
 import type { AgentCallOpts } from "../../orchestration/models/types.ts";
 import type { ExecuteOptions } from "../types.ts";
@@ -24,20 +26,45 @@ import type { ExecuteOptions } from "../types.ts";
 export function executeOptionsToEngineTaskSpec(opts: ExecuteOptions): AgentCallOpts {
   return {
     prompt: opts.task,
+    ...identityFields(opts),
+    ...budgetFields(opts),
+    ...deliveryFields(opts),
+    // 运行期字段（signal/ctxModel）不入声明——归 RunContext（port.ts 删字段去向）。
+  };
+}
+
+/** 声明面基础字段（slug/agent/model/thinkingLevel/skillPath/appendSystemPrompt 同名透传）。 */
+function identityFields(opts: ExecuteOptions): Partial<AgentCallOpts> {
+  return {
     ...(opts.slug !== undefined ? { description: opts.slug } : {}),
     ...(opts.agent !== undefined ? { agent: opts.agent } : {}),
     ...(opts.model !== undefined ? { model: opts.model } : {}),
     ...(opts.thinkingLevel !== undefined ? { thinkingLevel: opts.thinkingLevel } : {}),
     ...(opts.skillPath !== undefined ? { skillPath: opts.skillPath } : {}),
     ...(opts.appendSystemPrompt !== undefined ? { appendSystemPrompt: opts.appendSystemPrompt } : {}),
+  };
+}
+
+/** 约束面字段（schema/maxTurns/graceTurns 同名透传）。 */
+function budgetFields(opts: ExecuteOptions): Partial<AgentCallOpts> {
+  return {
     ...(opts.schema !== undefined ? { schema: opts.schema } : {}),
     ...(opts.maxTurns !== undefined ? { maxTurns: opts.maxTurns } : {}),
     ...(opts.graceTurns !== undefined ? { graceTurns: opts.graceTurns } : {}),
+  };
+}
+
+/** 运行载体字段（fork 族 / worktree / cwd / conversation / idleTimeoutMs 同名透传）。 */
+function deliveryFields(opts: ExecuteOptions): Partial<AgentCallOpts> {
+  return {
     ...(opts.fork !== undefined ? { fork: opts.fork } : {}),
+    // fork-from 源 session 文件（W3 断链修复：协议化后唯一 lossless 载体回到本映射）。
+    // 唯一改名点：ExecuteOptions.forkFromSessionFile → 中立任务形状 forkSource
+    // （与 SDK 协议字段、引擎侧 SpawnRunParams.forkSource 三层同名）。
+    ...(opts.forkFromSessionFile !== undefined ? { forkSource: opts.forkFromSessionFile } : {}),
     ...(opts.worktree !== undefined ? { worktree: opts.worktree } : {}),
     ...(opts.cwd !== undefined ? { cwd: opts.cwd } : {}),
     ...(opts.conversation !== undefined ? { conversation: opts.conversation } : {}),
     ...(opts.idleTimeoutMs !== undefined ? { idleTimeoutMs: opts.idleTimeoutMs } : {}),
-    // 运行期字段（signal/ctxModel）不入声明——归 RunContext（port.ts 删字段去向）。
   };
 }

package/src/execution/engine/model-validation.ts

@@ -9,6 +9,12 @@
 // 修复定案：校验源 = 目标引擎 registry（EnginePort.validateModel 可选面），时机 =
 // 路由之后的派发同步期（record 创建前，不产生孤儿 record）。
 //
+// [W3 契约变更②放宽（协议化）] 「record 创建前拒绝」不再绝对：manifest `modelCatalog`
+// 声明 `dynamic:true` 时，未命中 ref 放行（运行期以引擎为权威，失败 = engine_model_mismatch
+// + record 标 failed）；仅 `dynamic:false` 的静态目录保持同步拒（engine_model_unknown）。
+// 成员形态映射（cli 形态）：manifest 省略 modelCatalog → validateModel 成员不实现
+// （本入口 :63 `typeof !== "function"` 分支 → 跳过校验恒放行）。
+//
 // 两个调用点共享本入口与错误文案（D2-2 调用点双路径覆盖）：
 //   ① chat 路径 subagent-service.executeViaEngine（非 pi 分支）；
 //   ② workflow 路径 subprocess-agent-runner.run（route.engine.run 之前，非 pi 分支）。
@@ -21,6 +27,51 @@ import { toErrorMessage } from "../../core/error-message.ts";
 /** 错误消息中列出的目标引擎可用清单上限（防超长错误信息；与 shared/model-ref 同量级口径）。 */
 const ENGINE_MODEL_LIST_LIMIT = 20;
 
+// ============================================================
+// canonical ref 拆分（契约变更④：无斜杠 ref 的 core 侧处理）
+// ============================================================
+
+/** canonical ref 拆分结果（ModelInfo 构造子集；name = 整串原样）。 */
+export interface SplitModelRef {
+  /** provider 段：有斜杠 = 斜杠前段；无斜杠 = ""（契约④——不落 "<ref>/" 畸形）。 */
+  provider: string;
+  /** id 段：有斜杠 = 斜杠后段；无斜杠 = 整串。 */
+  id: string;
+  /** 整串原样（留痕/显示名）。 */
+  name: string;
+}
+
+/**
+ * canonical ref → {provider, id, name} 拆分（单一权威源）。
+ *
+ * 契约变更④（协议化后）：引擎 validateModel 的 canonicalRef 允许**无斜杠**形态
+ * （引擎原样返回的 ref）——拆分时按 `provider=""`、`id=ref`、整串进 `name` 处理。
+ * 旧实现把无斜杠 ref 整串塞进 provider（id=""），经 record.model "provider/id" 拼接
+ * 落成 `"<ref>/"` 畸形、续聊回读还原出错误 provider——本函数消解该畸形。
+ *
+ * 消费方：resolveIdentityForEngine（chat 域留痕）与续聊回读（record.model → ModelInfo
+ * 重建），两处必须同源拆分，否则写入/回读两侧对同一 ref 给出不同 provider/id。
+ *
+ * 斜杠位置判定用 `> 0`（与既有口径一致）：开头斜杠（"/x"）视为无有效 provider 段，
+ * 走无斜杠分支（防御异常形态，不 crash）。
+ */
+export function splitEngineModelRef(modelStr: string): SplitModelRef {
+  const slashIdx = modelStr.indexOf("/");
+  if (slashIdx > 0) {
+    return { provider: modelStr.slice(0, slashIdx), id: modelStr.slice(slashIdx + 1), name: modelStr };
+  }
+  return { provider: "", id: modelStr, name: modelStr };
+}
+
+/**
+ * record.model 留痕词形（SplitModelRef 的写入侧配对函数）：provider 为空串时只写 id
+ * （不拼斜杠——"/ref" 头斜杠与 "ref/" 尾斜杠同属畸形留痕）。续聊回读侧
+ * splitEngineModelRef 对无斜杠串给出 provider=""/id=ref，往返自洽。
+ */
+export function joinEngineModelRef(ref: SplitModelRef): string {
+  return ref.provider === "" ? ref.id : `${ref.provider}/${ref.id}`;
+}
+
 // ============================================================
 // 场景 2：engine+model 不配套的结构化错误（D2-3）
 // ============================================================
@@ -45,14 +96,16 @@ class EngineModelMismatchError extends Error {
  * 非 pi 引擎的派发同步期 model 校验（两路径统一入口）。
  *
  * - 引擎实现 validateModel：同步裁决（含 undefined = 查引擎缺省模型），返回 canonical
- *   全名供 record.model 留痕；失败包装为 EngineModelMismatchError（场景 2 文案：
+ *   ref 供 record.model 留痕；失败包装为 EngineModelMismatchError（场景 2 文案：
  *   点破 registry 独立 + 目标引擎可用清单 + 按引擎区分的省略语义修正动作）。
+ *   canonical ref 允许**无斜杠**形态（引擎原样返回的 ref，契约变更④）——留痕拆分
+ *   归 splitEngineModelRef（provider=""/id=ref/整串进 name），不在本入口裁词形。
  * - 引擎未实现 validateModel：返回 modelRef 原样（透传给其 prepare 期校验兜底——
  *   现状语义，未来引擎零强制接入）。
  *
  * @param engine   路由解析出的目标引擎
  * @param modelRef 显式 model（调用参数或 agent .md frontmatter；undefined = 引擎缺省语义）
- * @returns canonical ref（引擎裁决后全名）；未实现校验面时 = modelRef 原样
+ * @returns canonical ref（引擎裁决后）；未实现校验面时 = modelRef 原样
  */
 export function validateModelForEngine(
   engine: EnginePort,

package/src/execution/engine/paths.ts

@@ -1,42 +1,17 @@
-import { join } from 'node:path';
+// src/execution/engine/paths.ts
+//
+// 引擎数据目录布局的 re-export shim：实现体单源 @zhushanwen/subagent-engine-sdk
+// （自本文件逐字等价移入 SDK，迁移处置 impl-plan §2.1 登记的「core 侧引用切换」收口）。
+// 设计权威源：subagent-engine-abstraction.md D5/D6（C-ext-15 同源推导要求单源）。
+//
+// 本文件路径是 core package.json exports `./engine/paths` 子入口的解析目标，
+// 不可移动/删除（semver 面无损）；core 内消费方（pool-manager / journal-wiring /
+// session-view-service / routing 测试）import 路径保持不变。
 
-/**
- * 引擎数据目录布局 SSOT（设计文档 D5/D6）。
- *
- * 为什么独立成模块：extension 写侧（journal 落盘 / preparer 池目录）与
- * runtime 校验侧（subagent-extractor 前缀白名单）必须同源推导——
- * 双方 import 同一份纯函数，禁止各自拼字符串漂移。
- *
- * 布局：`<dataDir>/engines/<engineId>/<pool-key>/journal-<taskId>.jsonl`
- * 隔离池跨任务保留复用；journal 生命周期跟随 record，不随池删除（D5）。
- */
-
-/** 路径段安全编码后的最大字符数（防超长段击穿文件名长度上限；runtime 校验侧同源）。 */
-const MAX_SEG_CHARS = 80;
-
-/** 路径段进入文件系统前的安全编码：路径穿越、分隔符、空白、超长全部归一。 */
-export function sanitizeSeg(input: string): string {
-  const s = input.replace(/[^A-Za-z0-9-]+/g, '-').replace(/^-+|-+$/g, '');
-  return s.length > 0 ? s.slice(0, MAX_SEG_CHARS) : 'default';
-}
-
-export function resolveEnginesRoot(dataDir: string): string {
-  return join(dataDir, 'engines');
-}
-
-export function resolveEngineDir(dataDir: string, engineId: string): string {
-  return join(resolveEnginesRoot(dataDir), sanitizeSeg(engineId));
-}
-
-export function resolvePoolDir(dataDir: string, engineId: string, poolKey: string): string {
-  return join(resolveEngineDir(dataDir, sanitizeSeg(engineId)), sanitizeSeg(poolKey));
-}
-
-export function resolveJournalPath(
-  dataDir: string,
-  engineId: string,
-  poolKey: string,
-  taskId: string,
-): string {
-  return join(resolvePoolDir(dataDir, engineId, poolKey), `journal-${sanitizeSeg(taskId)}.jsonl`);
-}
+export {
+  sanitizeSeg,
+  resolveEnginesRoot,
+  resolveEngineDir,
+  resolvePoolDir,
+  resolveJournalPath,
+} from "@zhushanwen/subagent-engine-sdk";