dsh-expert-group 0.1.1

package/host/handoff.js

@@ -0,0 +1,80 @@
+/**
+ * Host 关注点模块：pending handoff admission 注册表。
+ *
+ * 接管原先 index.js 里的 pendingHandoffAdmissions 数组与其增删查操作；
+ * admission 的编排（cohort/token/暂停/释放）仍留在 index.js，任务 06 再收缩。
+ *
+ * @module dsh-expert-group/host/handoff
+ */
+export function createHandoffRegistryModule() {
+  const entries = [];
+  let disposed = false;
+
+  return Object.freeze({
+    /**
+     * 登记一个 admission entry（调用方负责构造 entry 字段）。
+     *
+     * 已销毁后静默丢弃并返回 undefined，不再抛错：注册路径可能落在迟到的 promise
+     * 回调里（admission 的 await 期间插件被卸载，微任务/后续 await 恢复后才回到
+     * 这里），此时抛出的异常没有任何调用方接收，只会变成 unhandled rejection。
+     * 与 host/recovery.js 的 queueRebuild 保持同一迟到语义：先判销毁、再做形状校验，
+     * 因此销毁后的畸形 entry 也一并丢弃，而不是半途抛错。
+     *
+     * 参数形状校验仍然保留：未销毁时的调用方缺陷（null/非对象）照旧抛 TypeError，
+     * 只有"已销毁"这一竞态态才降级为丢弃。
+     *
+     * @param {unknown} entry - 待登记的 admission entry。
+     * @returns {object|undefined} 登记成功时返回原 entry；已销毁时返回 undefined（丢弃指示）。
+     */
+    add(entry) {
+      if (disposed) return void 0;
+      if (entry === null || typeof entry !== "object") throw new TypeError("handoff admission 必须是对象");
+      entries.push(entry);
+      return entry;
+    },
+    contains: (entry) => entry !== undefined && entries.includes(entry),
+    remove(entry) {
+      if (entry === undefined) return false;
+      const index = entries.indexOf(entry);
+      if (index === -1) return false;
+      entries.splice(index, 1);
+      return true;
+    },
+    /** 只读快照；调用方不得依赖其身份。 */
+    entries: () => [...entries],
+    find(predicate) {
+      if (typeof predicate !== "function") throw new TypeError("find 需要谓词");
+      return entries.find(predicate);
+    },
+    filter(predicate) {
+      if (typeof predicate !== "function") throw new TypeError("filter 需要谓词");
+      return entries.filter(predicate);
+    },
+    some(predicate) {
+      if (typeof predicate !== "function") throw new TypeError("some 需要谓词");
+      return entries.some(predicate);
+    },
+    /** 按父 Agent 清理；返回被移除的 entry 数。 */
+    removeForParent(parent) {
+      let removed = 0;
+      for (let index = entries.length - 1; index >= 0; index -= 1) {
+        if (entries[index]?.parent === parent) {
+          entries.splice(index, 1);
+          removed += 1;
+        }
+      }
+      return removed;
+    },
+    clear() {
+      const removed = entries.length;
+      entries.length = 0;
+      return removed;
+    },
+    get size() { return entries.length; },
+    describe: () => ({ pending: entries.length, disposed }),
+    dispose() {
+      disposed = true;
+      entries.length = 0;
+    },
+  });
+}

package/host/lineage.js

@@ -0,0 +1,274 @@
+/**
+ * Host 关注点模块：root/child 血缘与 fan-out 父任务 ownership。
+ *
+ * 接管原先散落在 apply 里的 root 代际表（current/known/generation token）、
+ * fan-out 父任务 -> 父会话/父 Agent 映射、deferred 任务索引与父任务 id 分配。
+ * 这些索引只保存寻址关系，不复制 task/result 数据；完整状态仍由 fan-out manager 持有。
+ *
+ * 依赖全部注入，模块不读取 index.js 的闭包变量，也不创建 DSH 服务。
+ *
+ * @module dsh-expert-group/host/lineage
+ */
+
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * @param {object} options
+ * @param {WeakSet} [options.disposedRoots] - 已销毁 root 的 exact 对象集合（由组合根持有）。
+ * @param {Function} options.isRootAgent - 判断对象是否是根 Agent 身份。
+ * @param {Function} options.getAgent - agents.get(id)。
+ * @param {Function} [options.getTask] - fan-out manager.getTask(id)（用于 id 冲突检测）。
+ * @param {Function} [options.listTasks] - fan-out manager.listTasks()。
+ * @param {Function} [options.now] - 时钟，默认 Date.now。
+ */
+export function createLineageModule({
+  disposedRoots,
+  isRootAgent,
+  getAgent,
+  getTask = () => null,
+  listTasks = () => [],
+  now = Date.now,
+  isGenerationBlocked = () => false,
+} = {}) {
+  if (typeof isRootAgent !== "function") throw new TypeError("createLineageModule 需要 isRootAgent");
+  if (typeof getAgent !== "function") throw new TypeError("createLineageModule 需要 getAgent");
+  if (typeof now !== "function") throw new TypeError("createLineageModule 需要 now");
+
+  const knownRoots = new WeakSet();
+  const currentRoots = new Map();
+  const generationTokens = new WeakMap();
+  const parentSessions = new Map();
+  const parentAgents = new Map();
+  /**
+   * parentTaskId -> 绑定时父 Agent 的 generation token（exact 对象 + 活跃代际证据）。
+   *
+   * 为什么需要它：`parentSessions/parentAgents` 只回答「这个任务属于哪个会话/哪个对象」，
+   * 无法区分「绑定时的那一代 root」与「同 id 的 replacement」。续作（continuation）是**写**
+   * 权限，只能在「当前调用者就是绑定时那一代 live root」时才授予：
+   * - 同一 root 存活：token.agent === 调用者 且 isLiveGeneration(token) 为真；
+   * - root 被销毁/替换：token.active 被置 false 或 isLiveRoot 失败 → 拒绝；
+   * - 冷恢复后只从持久化 parentSessions 重建（restoreParentSessions）时不铸 token →
+   *   没有 exact 代际证据 → 续作 fail-closed（只允许寻址/读取）。
+   */
+  const parentTokens = new Map();
+  const deferredTasks = new Map();
+  const deferredParents = new Map();
+  let sequence = 0;
+  let disposed = false;
+
+  const isDisposed = (agent) => disposedRoots !== undefined && disposedRoots !== null && disposedRoots.has(agent);
+
+  const api = {
+    // ── root 代际 ──────────────────────────────────────────────────────────
+    /** 登记 root 为当前代际，并分配（或复用）其 generation token。 */
+    activateRoot(agent) {
+      if (!isRootAgent(agent) || !isNonEmptyString(agent?.id)) return void 0;
+      knownRoots.add(agent);
+      currentRoots.set(agent.id, agent);
+      return api.tokenFor(agent);
+    },
+    /** 当前代际的 exact root 对象。 */
+    activeRoot(id) {
+      return isNonEmptyString(id) ? currentRoots.get(id) : void 0;
+    },
+    /** 该对象是否是当前代际 root（同 id 的新 root 会取代旧对象）。 */
+    isCurrentRoot(agent) {
+      return isRootAgent(agent) && isNonEmptyString(agent?.id) && currentRoots.get(agent.id) === agent;
+    },
+    /** root replacement/dispose 时移除当前代际映射。 */
+    releaseRoot(agent) {
+      if (!isNonEmptyString(agent?.id)) return false;
+      if (currentRoots.get(agent.id) !== agent) return false;
+      currentRoots.delete(agent.id);
+      return true;
+    },
+    /** 是否曾经是本插件的 root（用于 dispose 判定）。 */
+    isKnownRoot: (agent) => knownRoots.has(agent),
+    /** exact root 对象的 generation token；非 root 返回 undefined。 */
+    tokenFor(agent) {
+      if (!isRootAgent(agent)) return void 0;
+      let token = generationTokens.get(agent);
+      if (token === void 0) {
+        token = { agent, active: true };
+        generationTokens.set(agent, token);
+      }
+      return token;
+    },
+    /** 只读查询：不创建 token。 */
+    tokenOf(agent) {
+      return generationTokens.get(agent);
+    },
+    /** token 仍是该 exact root 的活跃代际。 */
+    isLiveGeneration(agent, token) {
+      // 组合根可注入阻塞谓词（卸载/handoff 停止）；一旦阻塞，旧 token 立即失效。
+      if (isGenerationBlocked()) return false;
+      return token !== void 0 && token.agent === agent && token.active === true
+        && generationTokens.get(agent) === token && api.isLiveRoot(agent);
+    },
+    /** root 仍在当前代际且未被销毁（与 index.js 旧 isLiveRootAgent 等价）。 */
+    isLiveRoot(agent) {
+      return isRootAgent(agent)
+        && !isDisposed(agent)
+        && isNonEmptyString(agent?.id)
+        && currentRoots.get(agent.id) === agent
+        && getAgent(agent.id) === agent;
+    },
+    isDisposed,
+    /** 标记 exact 对象已销毁；token 同时失活。 */
+    markDisposed(agent) {
+      if (agent === null || typeof agent !== "object") return false;
+      disposedRoots?.add?.(agent);
+      const token = generationTokens.get(agent);
+      if (token !== void 0) token.active = false;
+      return true;
+    },
+    knownRootCount: () => currentRoots.size,
+
+    // ── fan-out 父任务 ownership ────────────────────────────────────────────
+    /**
+     * 绑定父任务到父会话/父 Agent，并记录绑定时的 generation token。
+     *
+     * token 只在**绑定当时**由该 exact parentAgent 铸造（或外部显式传入），之后不再刷新：
+     * 只有它仍然 `isLiveGeneration` 时，这个任务的可写权限（续作）才成立。这样同 id 的
+     * replacement 即使让 `getAgent(id)` 指向新对象，也拿不到旧任务的可写权限。
+     */
+    bindParentTask({ parentTaskId, parentId, parentAgent, token } = {}) {
+      if (!isNonEmptyString(parentTaskId) || !isNonEmptyString(parentId)) return false;
+      parentSessions.set(parentTaskId, parentId);
+      if (parentAgent !== undefined && parentAgent !== null) {
+        parentAgents.set(parentTaskId, parentAgent);
+        const recorded = token !== undefined && token !== null ? token : api.tokenFor(parentAgent);
+        if (recorded !== undefined && recorded !== null) parentTokens.set(parentTaskId, recorded);
+        else parentTokens.delete(parentTaskId);
+      }
+      deferredTasks.delete(parentTaskId);
+      deferredParents.delete(parentTaskId);
+      return true;
+    },
+    /** 绑定时的 exact generation token；无证据（未绑定/只从快照恢复寻址）返回 undefined。 */
+    parentTokenOf: (parentTaskId) => (isNonEmptyString(parentTaskId) ? parentTokens.get(parentTaskId) : void 0),
+    /** 父 Agent：缓存失效（被替换）时按 parentId 重新解析。 */
+    parentAgentOf(parentTaskId) {
+      const cached = parentAgents.get(parentTaskId);
+      if (cached !== undefined && getAgent(cached.id) === cached) return cached;
+      const parentId = parentSessions.get(parentTaskId);
+      if (!isNonEmptyString(parentId)) return void 0;
+      const parent = getAgent(parentId);
+      if (parent !== void 0) parentAgents.set(parentTaskId, parent);
+      return parent;
+    },
+    /** 为父任务分配稳定、单调、与既有任务不冲突的 id。 */
+    allocateParentTaskId(parent) {
+      if (!isNonEmptyString(parent?.id)) throw new TypeError("allocateParentTaskId 需要带 id 的父 Agent");
+      let candidate;
+      do {
+        sequence += 1;
+        candidate = "fanout-" + parent.id + "-" + now().toString(36) + "-" + sequence.toString(36);
+      } while (getTask(candidate) !== null);
+      return candidate;
+    },
+    /** 释放单个父任务的全部寻址关系（历史仍由 manager 保留）。 */
+    releaseParentTask(parentTaskId) {
+      const removed = parentSessions.delete(parentTaskId);
+      parentAgents.delete(parentTaskId);
+      parentTokens.delete(parentTaskId);
+      deferredTasks.delete(parentTaskId);
+      deferredParents.delete(parentTaskId);
+      return removed;
+    },
+    /** root replacement/dispose 后摘除该 Agent 的 fan-out ownership。 */
+    releaseAgent(agent) {
+      if (agent === undefined || agent === null || !isNonEmptyString(agent.id)) return 0;
+      let removed = 0;
+      for (const [parentTaskId, recordedAgent] of [...parentAgents]) {
+        if (recordedAgent === agent) {
+          api.releaseParentTask(parentTaskId);
+          removed += 1;
+        }
+      }
+      for (const [parentTaskId, parentId] of [...parentSessions]) {
+        if (parentId === agent.id && !parentAgents.has(parentTaskId)) {
+          api.releaseParentTask(parentTaskId);
+          removed += 1;
+        }
+      }
+      for (const [parentTaskId, parentId] of [...deferredParents]) {
+        if (parentId === agent.id) {
+          api.releaseParentTask(parentTaskId);
+          removed += 1;
+        }
+      }
+      return removed;
+    },
+    /**
+     * 从持久化快照恢复 parentSessions 索引（只接受非空字符串对）。
+     *
+     * 这里**只恢复寻址**（读路径/RPC 归属过滤），不铸造 generation token：冷恢复后的
+     * 任务是否可写（续作）必须由后续的真实绑定（`bindParentTask`，带 live root 的 exact
+     * token）决定，否则同 id replacement 会继承旧任务的可写权限。
+     */
+    restoreParentSessions(snapshot) {
+      const source = snapshot?.parentSessions;
+      if (source === null || typeof source !== "object" || Array.isArray(source)) return 0;
+      let restored = 0;
+      for (const [parentTaskId, parentId] of Object.entries(source)) {
+        if (!isNonEmptyString(parentTaskId) || !isNonEmptyString(parentId)) continue;
+        parentSessions.set(parentTaskId, parentId);
+        const parent = getAgent(parentId);
+        if (parent !== void 0) parentAgents.set(parentTaskId, parent);
+        // 不设置 parentTokens：没有绑定当时的 exact 代际证据 → 续作 fail-closed。
+        parentTokens.delete(parentTaskId);
+        restored += 1;
+      }
+      return restored;
+    },
+    /** 快照投影：parentTaskId -> parentSessionId。 */
+    parentSessionsSnapshot() {
+      const result = {};
+      for (const [parentTaskId, parentId] of parentSessions) {
+        if (isNonEmptyString(parentTaskId) && isNonEmptyString(parentId)) result[parentTaskId] = parentId;
+      }
+      return result;
+    },
+    parentSessionOf: (parentTaskId) => parentSessions.get(parentTaskId),
+    /** 缺失 root 的 queued 任务：独立保留，不阻塞其它任务。 */
+    deferTask({ parentTaskId, parentId, task } = {}) {
+      if (!isNonEmptyString(parentTaskId)) return false;
+      deferredTasks.set(parentTaskId, task);
+      if (isNonEmptyString(parentId)) deferredParents.set(parentTaskId, parentId);
+      return true;
+    },
+    deferredTaskOf: (parentTaskId) => deferredTasks.get(parentTaskId),
+    deferredTasks: () => [...deferredTasks.values()],
+    deferredParentOf: (parentTaskId) => deferredParents.get(parentTaskId),
+    /** RPC/反馈使用的 ownership 查询：只有当前代际映射才算归属。 */
+    resolveOwner(parentTaskId) {
+      return isNonEmptyString(parentTaskId) ? parentSessions.get(parentTaskId) : void 0;
+    },
+    tasksOwnedBy(sessionId) {
+      if (!isNonEmptyString(sessionId)) return [];
+      return listTasks().filter((task) => api.resolveOwner(task?.parentTaskId) === sessionId);
+    },
+    describe() {
+      return {
+        currentRoots: currentRoots.size,
+        parentTasks: parentSessions.size,
+        deferredTasks: deferredTasks.size,
+        disposed,
+      };
+    },
+    dispose() {
+      disposed = true;
+      currentRoots.clear();
+      parentSessions.clear();
+      parentAgents.clear();
+      parentTokens.clear();
+      deferredTasks.clear();
+      deferredParents.clear();
+      sequence = 0;
+    },
+  };
+  return Object.freeze(api);
+}

package/host/notifications.js

@@ -0,0 +1,189 @@
+/**
+ * Host 关注点模块：root run 终止快照注册表。
+ *
+ * 旧实现同时持有"事件队列 registry"和"root completion 去重状态机"，客户端必须靠
+ * 短时轮询按游标消费事件批次，投递正确性因此依赖轮询时机与队列 TTL。新实现只保留
+ * 生命周期权威真正需要的那一份状态：**每个 root run 的当前终止快照**。
+ *
+ * 快照只在 root 主代理 turn 已终止、且该 root 的全部递归后代专家都不在运行时写入
+ * （递归判定 fail closed，见 shared.snapshotRunningRootDescendants），并一直保留到
+ * 下一次真实用户输入开启新 run 或 root 被 dispose。客户端任何时刻读取同一份权威结果，
+ * 因此不需要"短时事件轮询"就能拿到正确状态。
+ *
+ * 终止原因不再被过滤成"只有成功才通知"：completed / blocked / error / aborted /
+ * interrupted / max-tokens 都会成为快照原因，由客户端按原因显示不同文案。
+ *
+ * @module dsh-expert-group/host/notifications
+ */
+import { snapshotRunningRootDescendants } from "../shared.js";
+
+/**
+ * DSH turn/end 的已知终止原因。TurnEndReason 是 merge-extensible 联合类型，
+ * 表外的 kind 一律归一为 unknown，绝不能被当作"completed"。
+ */
+export const ROOT_TERMINATION_REASONS = Object.freeze([
+  "completed",
+  "blocked",
+  "error",
+  "aborted",
+  "interrupted",
+  "max-tokens",
+]);
+
+/** 归一化终止原因：缺失或未知 kind 都返回 unknown。 */
+export function normalizeRootTerminationReason(reason) {
+  const kind = typeof reason?.kind === "string" ? reason.kind.trim() : "";
+  if (kind.length === 0) return "unknown";
+  return ROOT_TERMINATION_REASONS.includes(kind) ? kind : "unknown";
+}
+
+const EMPTY_VIEW = Object.freeze({ rootId: null, generation: null, runSeq: 0, snapshot: null });
+
+/**
+ * 创建 root run 终止快照模块。
+ *
+ * @param {object} [options]
+ * @param {() => unknown} [options.listAgents] - 读取全部 live Agent 的查询；缺失即未知。
+ * @param {() => number} [options.now] - 可注入时钟，测试用它固定快照时间戳。
+ */
+export function createNotificationModule({ listAgents, now = () => Date.now() } = {}) {
+  /** rootId -> { generation, runSeq, publishedRunSeq, snapshot } */
+  const roots = new Map();
+  // 发布序号单调递增：客户端用 generation+runSeq+seq 去重，因此撤销后又真正终止的
+  // 同一次 run 仍然可以被提示，而同一次发布永远只提示一次。
+  let publishSeq = 0;
+  let disposed = false;
+
+  const timestamp = () => {
+    const value = Number(now());
+    return Number.isFinite(value) ? Math.trunc(value) : Date.now();
+  };
+  const validIdentity = (rootId, generation) => typeof rootId === "string" && rootId.length > 0
+    && Number.isSafeInteger(generation) && generation > 0;
+
+  /**
+   * 读取（可选创建）某个 exact root generation 的状态。generation 单调：迟到的旧代际
+   * 不能读取或覆盖新代际的状态，同 id 的 replacement 因此不会继承旧 root 的快照。
+   */
+  function stateOf(rootId, generation, create) {
+    if (!validIdentity(rootId, generation)) return void 0;
+    const existing = roots.get(rootId);
+    if (existing !== void 0 && generation < existing.generation) return void 0;
+    if (existing !== void 0 && existing.generation === generation) return existing;
+    if (create !== true) return void 0;
+    const created = { generation, runSeq: 0, publishedRunSeq: null, snapshot: null };
+    roots.set(rootId, created);
+    return created;
+  }
+
+  const api = {
+    /** 插件启动/恢复时为已存在的 root 建立空状态：不能继承同 id 旧 root 的终止快照。 */
+    activateRoot({ rootId, generation } = {}) {
+      if (disposed) return false;
+      const state = stateOf(rootId, generation, true);
+      if (state === void 0) return false;
+      state.snapshot = null;
+      state.publishedRunSeq = null;
+      return true;
+    },
+    /**
+     * 真实用户输入开启新 run：runSeq 单调递增并清空上一 run 的快照与发布资格。
+     * 这是"同一 root 再次提示"的唯一入口——宿主注入的 subagent feedback 不经过这里。
+     */
+    beginRootRun({ rootId, generation } = {}) {
+      if (disposed) return false;
+      const state = stateOf(rootId, generation, true);
+      if (state === void 0) return false;
+      state.runSeq += 1;
+      state.publishedRunSeq = null;
+      state.snapshot = null;
+      return true;
+    },
+    /**
+     * root turn 已终止：只有递归后代门控确认"没有任何专家在运行"时才写入快照。
+     * 门控未知（agents.list 缺失/抛错/身份或状态不完整）与仍有后代在运行时都拒绝发布，
+     * 并且不消耗本 run 的发布资格——专家真正结束的那一轮仍然可以通知。
+     * @returns {{published: boolean, reason?: string, snapshot?: object}}
+     */
+    recordTermination({ rootId, generation, reason, turn } = {}) {
+      if (disposed) return { published: false, reason: "disposed" };
+      const state = stateOf(rootId, generation, false);
+      if (state === void 0) return { published: false, reason: "identity" };
+      // 每个 root run 至多一次：同 run 的后续 turn（例如子代理结算回唤出的续接 turn）
+      // 一律拒绝，直到 beginRootRun 开启新 run。
+      if (state.publishedRunSeq === state.runSeq) return { published: false, reason: "already-published" };
+      const gate = snapshotRunningRootDescendants(listAgents, rootId);
+      if (gate.known !== true) return { published: false, reason: gate.reason ?? "runtime-child-query-unknown" };
+      if (gate.blocked === true) return { published: false, reason: gate.reason ?? "runtime-running-descendant" };
+      const snapshot = Object.freeze({
+        seq: ++publishSeq,
+        runSeq: state.runSeq,
+        generation: state.generation,
+        reason: normalizeRootTerminationReason(reason),
+        turn: Number.isSafeInteger(turn) ? turn : null,
+        at: timestamp(),
+      });
+      state.snapshot = snapshot;
+      state.publishedRunSeq = state.runSeq;
+      return { published: true, snapshot };
+    },
+    /**
+     * 同一 turn 在 turn/end 之后又开始新 step，说明 listener 通过 steer 续接了本次运行，
+     * 刚写入的"终止"并不成立：撤销快照并归还本 run 的发布资格，让真正的终止仍能通知。
+     * 只有 turn 完全一致的撤销才生效，后续新 turn 不会被误撤销。
+     *
+     * 代际校验（fail-closed）：撤销面只拿得到 rootId，无法自己区分调用方属于哪一代，
+     * 而 replacement 之后同一 rootId 的下一代际**可以重用同一个 turn 号**——旧代际 root
+     * 的迟到 step/start 因此能撤销新代际刚发布的终止快照。调用方声明 generation 时
+     * 必须与当前状态代际严格一致（缺失、非法或不等都拒绝）。
+     *
+     * 兼容边界：未声明 generation 的历史调用方（index.js 的 session/event 路由）保留
+     * 原来的同 turn 语义——上游用 exact root Agent + Session 身份守卫拦住了跨代际事件；
+     * 新增调用方一律应带上 generation，才能获得完整的跨代际保护。
+     *
+     * @param {object} [input]
+     * @param {string} [input.rootId]
+     * @param {number} [input.turn] - 可省略；省略时不校验 turn 号（历史语义）。
+     * @param {number} [input.generation] - 调用方所属的 root 代际；声明即强校验。
+     * @returns {boolean} 真正撤销返回 true。
+     */
+    revokeTermination({ rootId, turn, generation } = {}) {
+      if (disposed) return false;
+      const state = roots.get(rootId);
+      if (state === void 0 || state.snapshot === null) return false;
+      if (generation !== undefined && generation !== state.generation) return false;
+      if (Number.isSafeInteger(turn) && state.snapshot.turn !== turn) return false;
+      state.snapshot = null;
+      state.publishedRunSeq = null;
+      return true;
+    },
+    /** 只读视图：RPC 与测试共用的权威读取面；未知 root 返回空视图而不是报错。 */
+    snapshotOf(rootId) {
+      if (disposed || typeof rootId !== "string" || rootId.length === 0) return EMPTY_VIEW;
+      const state = roots.get(rootId);
+      if (state === void 0) return Object.freeze({ rootId, generation: null, runSeq: 0, snapshot: null });
+      return Object.freeze({ rootId, generation: state.generation, runSeq: state.runSeq, snapshot: state.snapshot });
+    },
+    /** root replacement/dispose：删除该 root 的全部状态；旧代际的迟到退休无效。 */
+    retireRoot(rootId, generation) {
+      if (disposed) return false;
+      const state = roots.get(rootId);
+      if (state === void 0 || state.generation !== generation) return false;
+      roots.delete(rootId);
+      return true;
+    },
+    describe: () => Object.freeze({
+      roots: roots.size,
+      hasAgentQuery: typeof listAgents === "function",
+      reasons: [...ROOT_TERMINATION_REASONS],
+      disposed,
+    }),
+    /** 幂等清理：丢弃全部 root 状态；之后不接受新工作也不返回旧快照。 */
+    dispose() {
+      if (disposed) return;
+      disposed = true;
+      roots.clear();
+    },
+  };
+  return Object.freeze(api);
+}