dsh-expert-group 0.1.1 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -439,6 +439,34 @@ export function createFanoutRuntimeModule({
439
439
  if (closed || typeof parentTaskId !== "string" || parentTaskId.length === 0) return null;
440
440
  return resolvedOwner(parentTaskId);
441
441
  },
442
+ /**
443
+ * 「该 exact live root 能否证明自己拥有这个父任务」的只读判定。
444
+ *
445
+ * 为什么需要它:root turn 等待只能由**任务真正归属的那一代 root**建立,
446
+ * 否则同 id 的 replacement 或已销毁 root 就能替别人登记等待工作,让一个不会再产生
447
+ * task_settled 的任务把 root 永久钉在等待中。
448
+ *
449
+ * 授权条件与 continuation 写路径**同一套硬条件**(activeBindingReplayEvidence),
450
+ * 绝不接受单纯的字符串 parent id,也不使用 settledParentSessions 兜底:
451
+ * 1. 活动绑定存在且 ownerId 精确等于调用方 id;
452
+ * 2. 绑定的 exact parent Agent 就是调用方对象(同 id replacement 不是该对象);
453
+ * 3. 绑定当时的 generation token 仍是调用方的 live generation;
454
+ * 4. 任务非终态 —— 终态任务不会再产生 task_settled,登记原因等于永久 paused。
455
+ *
456
+ * 只读:不改变任何状态、不注册任何凭据,返回 false 表示无法证明归属(fail-closed)。
457
+ *
458
+ * @param {object} parent - 调用方 exact root Agent。
459
+ * @param {string} parentTaskId - fan-out 父任务 id。
460
+ * @returns {boolean} 是否可证明归属。
461
+ */
462
+ ownsTask(parent, parentTaskId) {
463
+ if (closed) return false;
464
+ if (parent === null || typeof parent !== "object" || typeof parent.id !== "string") return false;
465
+ if (typeof parentTaskId !== "string" || parentTaskId.length === 0) return false;
466
+ const task = runtime.manager.getTask(parentTaskId);
467
+ if (task === null || managerTaskIsTerminal(task)) return false;
468
+ return activeBindingReplayEvidence(parent, parentTaskId) !== null;
469
+ },
442
470
  getEvents: (options) => (closed
443
471
  ? { events: [], nextSequence: Number.isSafeInteger(options?.after) && options.after >= 0 ? options.after : 0 }
444
472
  : runtime.getEvents(options)),
@@ -489,7 +517,7 @@ export function createFanoutRuntimeModule({
489
517
  const currentTask = runtime.manager.getTask(parentTaskId);
490
518
  const recorded = currentTask?.continuationRequests?.[replayRequestId];
491
519
  if (recorded !== undefined && recorded !== null && typeof recorded.result === "object") {
492
- // 重放不触发任何 goal handoff 重新登记(index.js 按 duplicate 标记跳过)。
520
+ // 重放不触发任何等待工作重新登记(index.js 按 duplicate 标记跳过)。
493
521
  return { ...recorded.result, duplicate: true, ...(currentTask === null ? {} : { task: currentTask }) };
494
522
  }
495
523
  }
@@ -733,13 +761,12 @@ export function createFanoutRuntimeModule({
733
761
  ...(typeof runtime?.manager?.budget === "function" ? { budget: runtime.manager.budget() } : {}),
734
762
  }),
735
763
  /**
736
- * 显式落盘一次当前快照(C7 归属证据变化后由宿主调用)。
764
+ * 显式落盘一次当前快照(由宿主在需要立刻持久化时调用)。
737
765
  *
738
- * 为什么需要显式入口:goal handoff 归属证据(插件自己暂停过哪个 goal、暂停时的
739
- * exact revision、覆盖哪些父任务)不在 manager 的状态机里,manager 的状态变化
740
- * 不会触发它落盘。证据只在两个时刻变化(pause 建立 / release 完成),因此这里的
741
- * 显式 flush 不会被高频调用;它复用既有 persist 旁路(合并、退避、健康记录、
742
- * generation 校验都不复制)。
766
+ * 为什么需要显式入口:manager 的状态机只覆盖任务本身,宿主侧的登记(例如 fan-out
767
+ * 等待代次)变化不会触发它落盘。这类变化频率与任务数量同阶,因此这里的显式 flush
768
+ * 不会被高频调用;它复用既有 persist 旁路(合并、退避、健康记录、generation 校验
769
+ * 都不复制)。
743
770
  *
744
771
  * 关闭后返回 false:卸载路径不得再发起新的 domain 写入。
745
772
  * @returns {Promise<boolean>} 是否成功落盘。
@@ -192,7 +192,7 @@ export function buildToastXml({ title, taskName, body } = {}) {
192
192
  /**
193
193
  * 默认提示音路径:以本模块文件位置解析包内 assets/notification-whoosh.wav。
194
194
  *
195
- * 用 import.meta.url 而不是 __dirname/cwd:模块被 install.ps1 复制到
195
+ * 用 import.meta.url 而不是 __dirname/cwd:模块被 web-install.ps1 复制到
196
196
  * profiles\packages\dsh-expert-group 后依然指向同一份随包发布的资源。
197
197
  * 返回值只用于 stdin JSON,绝不进入命令行、日志、诊断或脚本文本。
198
198
  */
@@ -0,0 +1,465 @@
1
+ /**
2
+ * Host 关注点模块:root turn 等待登记表(wait ledger / 单状态机)。
3
+ *
4
+ * 背景(用户确认的改造 A):子代理派发后 root 必须**保持当前 turn 打开**,直到精确
5
+ * 关联的工作真正结束。DSH 会完整 await 工具 execute 的返回,期间 root 的
6
+ * `agent.status` 保持 `running`,而 goal round driver 只在 root `idle` 时才推进
7
+ * 下一轮——因此「保持 turn」本身就等价于旧实现里「pause durable goal」想要达到的
8
+ * 效果,却不需要调用任何 goal API。
9
+ *
10
+ * 本模块是**唯一**的等待账本与状态机:`dsh_expert_group_finalize` 与
11
+ * `agent/turn-stopping` 兜底共用同一份实现,绝不维护两套。
12
+ *
13
+ * ## 释放条件(缺一不可,全部为「明确成立」而非「无法证明」)
14
+ * 1. 该 root 名下没有任何未结算的登记工作(role admission / fan-out attempt);
15
+ * 2. root-scoped 的后代查询**明确**返回「没有 running 后代」
16
+ * (`snapshotDescendants` 返回 `known:true` 且 `running` 为空)。
17
+ *
18
+ * 查询失败、返回结构非法、`known !== true`、后代状态未知时一律**继续等待**:
19
+ * unknown 绝不能被当成「无人运行」。本模块**不提供也不接受任何超时**。
20
+ *
21
+ * ## 竞态保护
22
+ * 每次登记/结算/外部活动都会推进 `version`。一次静止判定只有在「异步查询期间
23
+ * version 未变、且登记集仍为空」时才成立;判定成立后仍会在同一同步临界区里
24
+ * 复查一次 version,因此「判定通过」与「真正释放」之间不可能插入新的 dispatch、
25
+ * child 创建或 fanout retry。
26
+ *
27
+ * ## 记录生命周期(单次静止 = 记录销毁)
28
+ * 一条记录在一次**静止收口**后立即被销毁(从登记表移除、监听解除、等待者收口、
29
+ * 对 exact Agent 的强引用清空)。同一 root 之后再次 engage/track/wait 时会建立
30
+ * **全新记录**并重新订阅监听、重新查询——因此第二轮(尤其是
31
+ * `continue_parent_turn` 建立第二个 child)不会因为「旧记录已 released」而永久
32
+ * 悬挂。销毁是不可逆的:在途查询的落地回调看到 `destroyed` 后只做丢弃,绝不会把
33
+ * 已退休记录重新挂回登记表。
34
+ *
35
+ * ## 代际与生命周期
36
+ * 记录以 **exact root Agent 对象**为键(同 id 的 replacement root 无法继承),并
37
+ * 绑定创建时的 generation token。root dispose、代际替换或插件卸载时调用
38
+ * `retire()`:该 root 的等待者立即以 `released:false` 收口、监听器移除、记录删除、
39
+ * Agent 强引用清空;旧代际的迟到事件不会释放新 waiter(记录已不存在,事件只会命中
40
+ * 新对象的新记录)。
41
+ *
42
+ * @module dsh-expert-group/host/turn-wait
43
+ */
44
+
45
+ /** 工作键的稳定编码:同一逻辑工作重复登记是幂等的。 */
46
+ export function turnWaitWorkKey(work) {
47
+ if (work === null || typeof work !== "object") return void 0;
48
+ if (work.kind === "admission") {
49
+ return typeof work.token === "string" && work.token.length > 0 ? "admission:" + work.token : void 0;
50
+ }
51
+ if (work.kind === "fanout") {
52
+ if (typeof work.parentTaskId !== "string" || work.parentTaskId.length === 0) return void 0;
53
+ const attempt = work.attempt;
54
+ return Number.isSafeInteger(attempt) && attempt > 0
55
+ ? "fanout:" + work.parentTaskId + ":" + attempt
56
+ : "fanout:" + work.parentTaskId;
57
+ }
58
+ return void 0;
59
+ }
60
+
61
+ /** 可外部驱动的 promise;只在本模块内部使用。 */
62
+ function createDeferred() {
63
+ let resolve;
64
+ const promise = new Promise((settle) => { resolve = settle; });
65
+ return { promise, resolve };
66
+ }
67
+
68
+ /**
69
+ * 创建 root turn 等待登记表。
70
+ *
71
+ * @param {object} options
72
+ * @param {(agent:object)=>boolean} options.isLiveRoot - exact root Agent 是否仍是当前
73
+ * live root(对象身份 + generation 双重校验由调用方提供)。
74
+ * @param {(rootId:string)=>Promise<{known:boolean,running?:unknown[],runningIds?:Set<string>,reason?:string}>} options.snapshotDescendants
75
+ * root-scoped 后代查询。**必须**是「明确回答」语义:查询失败/结构非法返回
76
+ * `known:false`,绝不能返回「空的 running 列表」来冒充已知。
77
+ * @param {(agent:object, snapshot:object)=>void} [options.onKnownSnapshot]
78
+ * 拿到**明确**快照后的可选回调(`known === true` 时)。调用方用它做「完成通知缺失」
79
+ * 的回退结算:只有在明确知道「某个 admission 的 exact child 已不在 running 列表里」
80
+ * 时才允许结算,因此绝不会凭未知状态放行。回调只能**减少**未结算工作;它在
81
+ * version 复查之后、同一同步临界区内被调用,因此不会与新的登记交错。
82
+ * @param {(agent:object, invalidate:()=>void)=>()=>void} options.subscribe
83
+ * 安装本 root 的活动监听(child 创建 / 状态转 running / dispose),返回移除函数。
84
+ * 调用方必须在**首次状态查询之前**同步安装(本模块保证 subscribe 在第一次
85
+ * `scheduleCheck` 之前完成)。记录销毁后本模块必定调用返回的移除函数,因此监听
86
+ * 不会跨记录泄漏。
87
+ * @param {(error:unknown)=>void} [options.onError] - 异常记录回调;不得抛出。
88
+ * @returns {object} 登记表 API。
89
+ */
90
+ export function createRootTurnWaitRegistry(options = {}) {
91
+ const isLiveRoot = typeof options.isLiveRoot === "function" ? options.isLiveRoot : () => false;
92
+ const snapshotDescendants = typeof options.snapshotDescendants === "function"
93
+ ? options.snapshotDescendants
94
+ : async () => ({ known: false, running: [], reason: "descendant-query-unavailable" });
95
+ const subscribe = typeof options.subscribe === "function" ? options.subscribe : () => () => {};
96
+ const onKnownSnapshot = typeof options.onKnownSnapshot === "function" ? options.onKnownSnapshot : () => {};
97
+ const onError = typeof options.onError === "function" ? options.onError : () => {};
98
+
99
+ /** exact root Agent -> record。Map 会强引用 root,因此 destroy 必须显式删除。 */
100
+ const records = new Map();
101
+ let disposed = false;
102
+
103
+ function report(error) {
104
+ try { onError(error); } catch { /* 记录回调自身异常不得改变等待语义 */ }
105
+ }
106
+
107
+ /** 释放一条记录的监听器;幂等。 */
108
+ function releaseListeners(record) {
109
+ if (typeof record.unlisten !== "function") return;
110
+ const unlisten = record.unlisten;
111
+ record.unlisten = void 0;
112
+ try { unlisten(); } catch (error) { report(error); }
113
+ }
114
+
115
+ /** 以指定结论收口所有等待者;不会重复收口。 */
116
+ function settleWaiters(record, released, reason) {
117
+ const waiters = [...record.waiters];
118
+ record.waiters.clear();
119
+ for (const waiter of waiters) {
120
+ try {
121
+ waiter.cleanup?.();
122
+ waiter.resolve({ released, reason });
123
+ } catch (error) { report(error); }
124
+ }
125
+ }
126
+
127
+ /**
128
+ * **唯一**的记录销毁路径:等待者收口、监听解除、登记表移除、exact Agent 强引用清空。
129
+ *
130
+ * 为什么必须清空引用(问题 4):`retireRecord` 之后在途的 snapshot Promise 仍持有
131
+ * 这条 record;只要 record 还指向 exact Agent,已退休的 root 就无法被回收。清空
132
+ * `owner`/`agent` 后,任何迟到回调最多只能看到 `destroyed` 并丢弃。
133
+ *
134
+ * 为什么必须从登记表移除(问题 2):保留「已 released」的记录会让同一 root 的第二轮
135
+ * 等待复用一条监听已解除、且 `scheduleCheck` 会直接早退的记录,从而永久 pending。
136
+ * 销毁后再次 engage/track/wait 会建立全新记录并重新订阅。
137
+ *
138
+ * @param {object} record - 目标记录。
139
+ * @param {boolean} released - 等待结论:静止成立为 true,被取消为 false。
140
+ * @param {string} reason - 稳定原因码(诊断用)。
141
+ */
142
+ function destroyRecord(record, released, reason) {
143
+ if (record.destroyed === true) return;
144
+ record.destroyed = true;
145
+ record.cancelled = released !== true;
146
+ record.released = released === true;
147
+ record.releaseReason = reason;
148
+ record.checking = false;
149
+ record.recheck = false;
150
+ record.inSnapshot = false;
151
+ releaseListeners(record);
152
+ settleWaiters(record, released === true, reason);
153
+ record.works.clear();
154
+ // 先按 owner 摘除,再清空引用:清空后 record 不再能让 Map 保留已退休 Agent。
155
+ const owner = record.owner;
156
+ record.owner = void 0;
157
+ record.agent = void 0;
158
+ if (owner !== void 0 && records.get(owner) === record) records.delete(owner);
159
+ }
160
+
161
+ /**
162
+ * 判定一次静止。任何一步不成立都保持等待;查询失败/未知一律不释放。
163
+ *
164
+ * @param {object} record - 目标记录。
165
+ */
166
+ function scheduleCheck(record) {
167
+ if (disposed || record.destroyed === true || record.released === true) return;
168
+ // 正在 onKnownSnapshot 的同步回调里:本次结算由外层判定统一收口,不再嵌套发起查询。
169
+ if (record.inSnapshot === true) return;
170
+ if (record.checking) {
171
+ // 已有判定在飞:它的结论对本轮已陈旧,落地后必须重跑(见 handleQuerySettled)。
172
+ record.recheck = true;
173
+ return;
174
+ }
175
+ record.checking = true;
176
+ const queryId = ++record.querySequence;
177
+ record.activeQueryId = queryId;
178
+ const version = record.version;
179
+ const rootId = record.rootId;
180
+ let outcome;
181
+ try {
182
+ outcome = Promise.resolve(snapshotDescendants(rootId));
183
+ } catch (error) {
184
+ // 同步抛错同样归入「查询失败」的异步收口路径,避免递归重入。
185
+ outcome = Promise.reject(error);
186
+ }
187
+ outcome.then(
188
+ (result) => handleQuerySettled(record, queryId, version, result, void 0),
189
+ (error) => handleQuerySettled(record, queryId, version, void 0, error),
190
+ );
191
+ }
192
+
193
+ /**
194
+ * 查询落地后的**唯一**收口点(成功与失败共用),保证 `checking` 一定被复位、
195
+ * 且 `recheck` 一定被消费。
196
+ *
197
+ * 问题 3:查询在飞期间发生的事件会把 `recheck` 置 true;若 rejection 分支只记错
198
+ * 不消费该标志,那次「有新活动,请复查」的意图就被吞掉,等待可能永久悬挂。因此
199
+ * 两条分支都必须消费 `recheck` 并重跑一次查询。
200
+ *
201
+ * 不自旋的保证:`recheck` 只在**已有查询在飞**时被置位,而置位者只能是事件
202
+ * (track/settle/invalidate 都会推进 version)或新到达的 waiter。每次 rejection
203
+ * 最多消费一个 `recheck`,因此「连续 reject 且没有新事件」时第二轮之后不再重跑。
204
+ */
205
+ function handleQuerySettled(record, queryId, version, result, error) {
206
+ if (record.activeQueryId !== queryId) return;
207
+ record.activeQueryId = 0;
208
+ record.checking = false;
209
+ if (disposed || record.destroyed === true) return;
210
+
211
+ if (error !== void 0) {
212
+ report(error);
213
+ // unknown:继续等待。仅当在飞期间确有复查意图时才重跑,绝不无条件自旋。
214
+ if (record.recheck === true) {
215
+ record.recheck = false;
216
+ scheduleCheck(record);
217
+ }
218
+ return;
219
+ }
220
+
221
+ // 查询期间出现新活动(新登记 / child 创建 / 状态变化):本轮结论作废,重新判定。
222
+ // 注意:`works.size > 0` **不是**陈旧信号——它就是「仍在等待」的正常状态,
223
+ // 在这里重跑只会造成无休止的重新查询。
224
+ if (record.version !== version) {
225
+ record.recheck = false;
226
+ scheduleCheck(record);
227
+ return;
228
+ }
229
+ const known = result?.known === true;
230
+ const running = known && Array.isArray(result.running) ? result.running : [];
231
+ if (!known) {
232
+ // 未知(查询失败 / 结构非法 / 状态无法确定):继续等待,**绝不**当成无人运行。
233
+ if (record.recheck === true) { record.recheck = false; scheduleCheck(record); }
234
+ return;
235
+ }
236
+ // 明确快照:先给调用方一次「完成通知缺失」的回退结算机会。回调只减少未结算工作,
237
+ // 且此刻处于同一同步临界区(不可能与新的登记交错);inSnapshot 阻止回调内的
238
+ // settle 触发嵌套查询,由本回调统一收口。
239
+ record.inSnapshot = true;
240
+ try { onKnownSnapshot(record.agent, result); } catch (callbackError) { report(callbackError); } finally {
241
+ record.inSnapshot = false;
242
+ }
243
+ if (record.destroyed === true) return;
244
+ // 从「快照落地」到「判定静止」之间没有任何 await / 回调边界,因此这里的判定
245
+ // 与释放处于同一同步临界区:「通过」与「释放」之间不可能插入新的 dispatch、
246
+ // child 创建或 fanout retry。
247
+ if (record.works.size > 0 || running.length > 0) {
248
+ // 仍有未结算工作,或确有 running 后代:继续等待。
249
+ if (record.recheck === true) { record.recheck = false; scheduleCheck(record); }
250
+ return;
251
+ }
252
+ if (!isLiveRoot(record.agent)) {
253
+ // root 已不再是 live:由 retire() 负责收口;这里保持等待避免误报静止。
254
+ return;
255
+ }
256
+ record.recheck = false;
257
+ destroyRecord(record, true, "quiescent");
258
+ }
259
+
260
+ /**
261
+ * 取得(必要时创建)一个 root 的记录;首次创建时**先**安装监听器,再返回,
262
+ * 因此调用方的第一次状态查询一定发生在监听安装之后。
263
+ *
264
+ * 已销毁的记录不在登记表里,因此这里会为同一 root 建立**全新**记录并重新订阅
265
+ * (问题 2 的第二轮等待就靠这一点)。
266
+ */
267
+ function ensureRecord(agent) {
268
+ if (disposed) return void 0;
269
+ if (agent === null || (typeof agent !== "object" && typeof agent !== "function")) return void 0;
270
+ const existing = records.get(agent);
271
+ if (existing !== void 0) return existing;
272
+ const record = {
273
+ owner: agent,
274
+ agent,
275
+ rootId: typeof agent.id === "string" ? agent.id : void 0,
276
+ works: new Map(),
277
+ waiters: new Set(),
278
+ version: 0,
279
+ querySequence: 0,
280
+ activeQueryId: 0,
281
+ checking: false,
282
+ recheck: false,
283
+ inSnapshot: false,
284
+ released: false,
285
+ cancelled: false,
286
+ destroyed: false,
287
+ releaseReason: void 0,
288
+ unlisten: void 0,
289
+ };
290
+ if (typeof record.rootId !== "string" || record.rootId.length === 0) return void 0;
291
+ records.set(agent, record);
292
+ // 监听必须先于任何状态查询/快照安装。
293
+ try {
294
+ record.unlisten = subscribe(agent, () => invalidate(agent));
295
+ } catch (error) {
296
+ report(error);
297
+ record.unlisten = void 0;
298
+ }
299
+ return record;
300
+ }
301
+
302
+ /**
303
+ * 登记一项未结算工作。重复登记同一键幂等。
304
+ *
305
+ * @param {object} agent - exact root Agent。
306
+ * @param {{kind:"admission",token:string}|{kind:"fanout",parentTaskId:string,attempt?:number}} work - 工作描述。
307
+ * @returns {string|undefined} 工作键;非法输入或已卸载时 undefined。
308
+ */
309
+ function track(agent, work) {
310
+ const key = turnWaitWorkKey(work);
311
+ if (key === void 0) return void 0;
312
+ const record = ensureRecord(agent);
313
+ if (record === void 0 || record.destroyed === true) return void 0;
314
+ const existing = record.works.get(key);
315
+ if (existing !== void 0 && existing.settled !== true) return key;
316
+ record.works.set(key, { key, ...work, settled: false });
317
+ record.version += 1;
318
+ scheduleCheck(record);
319
+ return key;
320
+ }
321
+
322
+ /**
323
+ * 精确结算一项工作。只有确实命中未结算项时才算结算(幂等)。
324
+ *
325
+ * @returns {boolean} 是否结算成功。
326
+ */
327
+ function settle(agent, work) {
328
+ const key = turnWaitWorkKey(work);
329
+ if (key === void 0) return false;
330
+ const record = records.get(agent);
331
+ if (record === void 0 || record.destroyed === true) return false;
332
+ const entry = record.works.get(key);
333
+ if (entry === void 0 || entry.settled === true) return false;
334
+ record.works.delete(key);
335
+ record.version += 1;
336
+ scheduleCheck(record);
337
+ return true;
338
+ }
339
+
340
+ /**
341
+ * 外部活动(child 创建 / 状态转 running / fanout retry)让当前静止结论作废。
342
+ * 只推进 version 并重跑判定,不改变登记集。
343
+ */
344
+ function invalidate(agent) {
345
+ const record = records.get(agent);
346
+ if (record === void 0 || record.destroyed === true) return;
347
+ record.version += 1;
348
+ scheduleCheck(record);
349
+ }
350
+
351
+ /**
352
+ * 等待该 root 静止。**永不超时**:只有精确结算 + root-scoped 明确空闲、
353
+ * 或 retire/dispose 才会收口。
354
+ *
355
+ * @param {object} agent - exact root Agent。
356
+ * @param {AbortSignal} [signal] - 只取消本次 waiter,不改变等待记录或工作项。
357
+ * @returns {Promise<{released:boolean,reason:string}>} 释放结论;`released:false`
358
+ * 表示 root 已销毁/代际被替换/插件卸载,或本次 waiter 被取消。
359
+ */
360
+ function wait(agent, signal) {
361
+ if (signal?.aborted === true) return Promise.resolve({ released: false, reason: "signal-aborted" });
362
+ const record = ensureRecord(agent);
363
+ if (record === void 0) return Promise.resolve({ released: false, reason: "root-unknown" });
364
+ if (record.destroyed === true) return Promise.resolve({ released: false, reason: record.releaseReason ?? "cancelled" });
365
+ const deferred = createDeferred();
366
+ const waiter = { resolve: deferred.resolve, cleanup: void 0 };
367
+ record.waiters.add(waiter);
368
+ if (typeof signal?.addEventListener === "function") {
369
+ const onAbort = () => {
370
+ if (!record.waiters.delete(waiter)) return;
371
+ waiter.cleanup?.();
372
+ waiter.cleanup = void 0;
373
+ waiter.resolve({ released: false, reason: "signal-aborted" });
374
+ // 最后一个 waiter 取消后,忽略它启动的在途快照并释放 checking。
375
+ if (record.waiters.size === 0 && record.checking) {
376
+ record.activeQueryId = ++record.querySequence;
377
+ record.checking = false;
378
+ record.recheck = false;
379
+ }
380
+ };
381
+ const cleanup = () => signal.removeEventListener?.("abort", onAbort);
382
+ waiter.cleanup = cleanup;
383
+ signal.addEventListener("abort", onAbort, { once: true });
384
+ if (signal.aborted === true) onAbort();
385
+ }
386
+ scheduleCheck(record);
387
+ return deferred.promise;
388
+ }
389
+
390
+ /**
391
+ * 建立(或复用)该 root 的等待记录但**不登记任何工作**。
392
+ *
393
+ * 用途:`continue_parent_turn` 之类的路径不会产生"未结算工作",但它确实会留下
394
+ * 正在运行的子代理;只要该 root 曾经委派过专家,`agent/turn-stopping` 兜底就必须
395
+ * 参与判定。engage 只保证记录与监听存在,是否等待仍由静止判定决定。
396
+ *
397
+ * @returns {boolean} 记录是否可用(已卸载/非法 root 为 false)。
398
+ */
399
+ function engage(agent) {
400
+ const record = ensureRecord(agent);
401
+ return record !== void 0 && record.destroyed !== true;
402
+ }
403
+
404
+ /** 该 root 是否已有(存活的)等待记录——turn-stopping 兜底的介入条件。 */
405
+ function isEngaged(agent) {
406
+ const record = records.get(agent);
407
+ return record !== void 0 && record.destroyed !== true;
408
+ }
409
+
410
+ /** 是否存在未结算工作(turn-stopping 兜底据此决定是否介入)。 */
411
+ function hasOutstanding(agent) {
412
+ const record = records.get(agent);
413
+ return record !== void 0 && record.destroyed !== true && record.works.size > 0;
414
+ }
415
+
416
+ /** 未结算工作数。 */
417
+ function outstandingCount(agent) {
418
+ const record = records.get(agent);
419
+ return record === void 0 || record.destroyed === true ? 0 : record.works.size;
420
+ }
421
+
422
+ /** 只读诊断投影(不含任何工作负载,也不暴露 Agent 引用)。 */
423
+ function describe(agent) {
424
+ const record = records.get(agent);
425
+ if (record === void 0) return void 0;
426
+ return {
427
+ outstanding: record.works.size,
428
+ waiters: record.waiters.size,
429
+ version: record.version,
430
+ released: record.released,
431
+ cancelled: record.cancelled,
432
+ reason: record.releaseReason,
433
+ };
434
+ }
435
+
436
+ /** root dispose / 代际替换:取消该 root 的等待并移除监听与引用。 */
437
+ function retire(agent, reason = "root-retired") {
438
+ const record = records.get(agent);
439
+ if (record === void 0) return false;
440
+ destroyRecord(record, false, reason);
441
+ return true;
442
+ }
443
+
444
+ /** 插件卸载:所有 root 一起收口,绝不留下悬空等待或监听。 */
445
+ function dispose() {
446
+ disposed = true;
447
+ for (const record of [...records.values()]) destroyRecord(record, false, "plugin-unloaded");
448
+ records.clear();
449
+ }
450
+
451
+ return Object.freeze({
452
+ track,
453
+ settle,
454
+ invalidate,
455
+ engage,
456
+ isEngaged,
457
+ wait,
458
+ hasOutstanding,
459
+ outstandingCount,
460
+ describe,
461
+ retire,
462
+ dispose,
463
+ get size() { return records.size; },
464
+ });
465
+ }