@sema-agent/core 7.63.0 → 7.64.0

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.
Files changed (204) hide show
  1. package/CHANGELOG.md +408 -0
  2. package/dist/agents/cc-peer-directory.js +1 -0
  3. package/dist/agents/cc-peer-wire.d.ts +4 -0
  4. package/dist/agents/cc-peer-wire.js +1 -0
  5. package/dist/agents/cc-uds-peer-channel.js +5 -0
  6. package/dist/agents/cross-session-judge.d.ts +3 -1
  7. package/dist/agents/cross-session-judge.js +4 -1
  8. package/dist/agents/peer-directory.d.ts +8 -0
  9. package/dist/agents/peer-directory.js +4 -0
  10. package/dist/agents/peer-held-queue.d.ts +9 -3
  11. package/dist/agents/peer-held-queue.js +12 -9
  12. package/dist/agents/peer-idle.d.ts +20 -1
  13. package/dist/agents/peer-idle.js +23 -12
  14. package/dist/agents/peer-notice-route.d.ts +16 -5
  15. package/dist/agents/peer-notice-route.js +11 -9
  16. package/dist/agents/peer-notices.d.ts +25 -8
  17. package/dist/agents/peer-notices.js +6 -1
  18. package/dist/agents/peer-session-drain.d.ts +32 -6
  19. package/dist/agents/peer-session-drain.js +100 -26
  20. package/dist/agents/send-message-tool.d.ts +7 -0
  21. package/dist/agents/send-message-tool.js +18 -6
  22. package/dist/agents/subagent.js +20 -3
  23. package/dist/core/allow-entry.d.ts +4 -0
  24. package/dist/core/ask-origin.d.ts +1 -1
  25. package/dist/core/ask-origin.js +2 -2
  26. package/dist/core/ask-unresolvable-notice.d.ts +13 -4
  27. package/dist/core/ask-unresolvable-notice.js +10 -3
  28. package/dist/core/auto-compaction.d.ts +7 -5
  29. package/dist/core/background-agent-store.d.ts +7 -0
  30. package/dist/core/background-agent-store.js +3 -0
  31. package/dist/core/checkpoint-queries.d.ts +9 -6
  32. package/dist/core/checkpoint-queries.js +8 -3
  33. package/dist/core/checkpoint-store.d.ts +5 -1
  34. package/dist/core/context-settings.d.ts +40 -9
  35. package/dist/core/context-settings.js +32 -10
  36. package/dist/core/engine-attestation.d.ts +26 -6
  37. package/dist/core/engine-attestation.js +5 -1
  38. package/dist/core/engine-notice.d.ts +24 -1
  39. package/dist/core/extension-requester.d.ts +9 -0
  40. package/dist/core/extension-requester.js +7 -0
  41. package/dist/core/file-history-store.d.ts +28 -0
  42. package/dist/core/file-history-store.js +48 -5
  43. package/dist/core/fs-write-gate-policy.js +1 -1
  44. package/dist/core/gate-fold.js +2 -0
  45. package/dist/core/gate-lanes.js +2 -0
  46. package/dist/core/gate-outcome.d.ts +39 -2
  47. package/dist/core/gate-outcome.js +20 -1
  48. package/dist/core/governance-codes.d.ts +3 -1
  49. package/dist/core/governance-codes.js +4 -0
  50. package/dist/core/leg-identity.d.ts +19 -1
  51. package/dist/core/leg-identity.js +12 -0
  52. package/dist/core/mailbox-store.d.ts +39 -4
  53. package/dist/core/mailbox-store.js +14 -2
  54. package/dist/core/memory-engine/consolidation.d.ts +3 -2
  55. package/dist/core/memory-engine/consolidation.js +16 -0
  56. package/dist/core/memory-engine/control-objects.d.ts +25 -0
  57. package/dist/core/memory-engine/control-objects.js +151 -0
  58. package/dist/core/memory-engine/control-plane-adoption.d.ts +48 -0
  59. package/dist/core/memory-engine/control-plane-adoption.js +159 -0
  60. package/dist/core/memory-engine/delegation-settlement.d.ts +21 -5
  61. package/dist/core/memory-engine/delegation-settlement.js +217 -26
  62. package/dist/core/memory-engine/dual-root.js +2 -2
  63. package/dist/core/memory-engine/engine.d.ts +38 -23
  64. package/dist/core/memory-engine/engine.js +14 -14
  65. package/dist/core/memory-engine/file-backend.d.ts +41 -65
  66. package/dist/core/memory-engine/file-backend.js +59 -166
  67. package/dist/core/memory-engine/index.d.ts +3 -2
  68. package/dist/core/memory-engine/index.js +2 -1
  69. package/dist/core/memory-engine/layout.d.ts +6 -1
  70. package/dist/core/memory-engine/layout.js +12 -7
  71. package/dist/core/memory-engine/memory-backend-contract.d.ts +10 -3
  72. package/dist/core/memory-engine/memory-backend-contract.js +158 -2
  73. package/dist/core/memory-engine/memory-deployment.d.ts +11 -3
  74. package/dist/core/memory-engine/memory-deployment.js +31 -6
  75. package/dist/core/memory-engine/origin-clearance.d.ts +12 -3
  76. package/dist/core/memory-engine/origin-clearance.js +68 -9
  77. package/dist/core/memory-engine/session-write-home.d.ts +34 -1
  78. package/dist/core/memory-engine/session-write-home.js +37 -10
  79. package/dist/core/memory-engine/types.d.ts +44 -7
  80. package/dist/core/memory-engine/types.js +2 -1
  81. package/dist/core/mode-policy.js +3 -3
  82. package/dist/core/mods/agent-stations.d.ts +18 -0
  83. package/dist/core/mods/agent-stations.js +8 -6
  84. package/dist/core/mods/extension-call.d.ts +4 -0
  85. package/dist/core/mods/extension-call.js +8 -0
  86. package/dist/core/mods/tool-call.js +3 -4
  87. package/dist/core/parent-spec-seat.d.ts +2 -2
  88. package/dist/core/peer-channel.d.ts +5 -0
  89. package/dist/core/permission-rule-consent.d.ts +21 -10
  90. package/dist/core/permission-rule-consent.js +50 -23
  91. package/dist/core/permission-rule-store.d.ts +41 -16
  92. package/dist/core/permission-rule-store.js +2 -0
  93. package/dist/core/refusal-echo.d.ts +20 -0
  94. package/dist/core/refusal-echo.js +33 -0
  95. package/dist/core/retention.d.ts +180 -10
  96. package/dist/core/retention.js +45 -0
  97. package/dist/core/retired-keys.d.ts +5 -0
  98. package/dist/core/retired-keys.js +3 -0
  99. package/dist/core/rule-offer-read.d.ts +0 -4
  100. package/dist/core/rule-offer-read.js +2 -18
  101. package/dist/core/runner/classifier-ladder.d.ts +7 -1
  102. package/dist/core/runner/classifier-ladder.js +4 -2
  103. package/dist/core/runner/compact-session.js +10 -7
  104. package/dist/core/runner/compaction-call-options.d.ts +7 -7
  105. package/dist/core/runner/compaction-call-options.js +3 -2
  106. package/dist/core/runner/contracts.d.ts +21 -2
  107. package/dist/core/runner/delegation-owner.d.ts +10 -3
  108. package/dist/core/runner/delegation-owner.js +4 -1
  109. package/dist/core/runner/gate-exit.d.ts +6 -0
  110. package/dist/core/runner/gate-exit.js +11 -2
  111. package/dist/core/runner/memory-consolidation-driver.d.ts +4 -2
  112. package/dist/core/runner/memory-consolidation-driver.js +8 -5
  113. package/dist/core/runner/prepare-ask-lane.js +3 -3
  114. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -1
  115. package/dist/core/runner/prepare-caps-and-workflow.js +2 -2
  116. package/dist/core/runner/prepare-config-doors.js +4 -0
  117. package/dist/core/runner/prepare-delegation-surface.d.ts +3 -0
  118. package/dist/core/runner/prepare-delegation-surface.js +2 -2
  119. package/dist/core/runner/prepare-gate-stations.d.ts +5 -0
  120. package/dist/core/runner/prepare-gate-stations.js +5 -5
  121. package/dist/core/runner/prepare-hands-readface.js +1 -1
  122. package/dist/core/runner/prepare-inherited-gate.d.ts +3 -1
  123. package/dist/core/runner/prepare-inherited-gate.js +4 -2
  124. package/dist/core/runner/prepare-memory.d.ts +4 -0
  125. package/dist/core/runner/prepare-memory.js +14 -20
  126. package/dist/core/runner/prepare-policy-chain.js +7 -7
  127. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  128. package/dist/core/runner/prepare-task.js +15 -10
  129. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -1
  130. package/dist/core/runner/prepare-wiring-manifest.js +3 -2
  131. package/dist/core/runner/resume-admission.d.ts +2 -2
  132. package/dist/core/runner/resume-admission.js +2 -23
  133. package/dist/core/runner/role-resolution-table.d.ts +98 -0
  134. package/dist/core/runner/role-resolution-table.js +62 -0
  135. package/dist/core/runner/run-compaction-machinery.js +2 -2
  136. package/dist/core/runner/run-identity-wiring.js +12 -9
  137. package/dist/core/runner/run-leg.js +8 -4
  138. package/dist/core/runner/run-notification-lane.js +22 -22
  139. package/dist/core/runner/run-recovery-lanes.js +3 -3
  140. package/dist/core/runner/run-terminal-adoption.js +1 -1
  141. package/dist/core/runner/run-turn-boundary.js +14 -15
  142. package/dist/core/runner/runtask.js +1 -1
  143. package/dist/core/runner/tool-occurrence.d.ts +4 -2
  144. package/dist/core/runner/tool-occurrence.js +2 -2
  145. package/dist/core/runner-deps.d.ts +1 -1
  146. package/dist/core/session-checkout.d.ts +63 -3
  147. package/dist/core/session-checkout.js +152 -58
  148. package/dist/core/shell-read-silence.js +8 -0
  149. package/dist/core/store-contracts/peer-directory-contract.js +8 -1
  150. package/dist/core/task-event.d.ts +9 -5
  151. package/dist/core/task-notification.d.ts +110 -31
  152. package/dist/core/task-notification.js +180 -100
  153. package/dist/core/task-registry-agent.d.ts +11 -0
  154. package/dist/core/task-registry-agent.js +11 -3
  155. package/dist/core/task-registry-shared.d.ts +7 -0
  156. package/dist/core/task-registry.d.ts +18 -0
  157. package/dist/core/task-registry.js +27 -8
  158. package/dist/core/task-spec.d.ts +7 -2
  159. package/dist/core/tool-errors.d.ts +14 -6
  160. package/dist/core/tool-errors.js +1 -1
  161. package/dist/core/tool-policy.d.ts +18 -1
  162. package/dist/core/tool-policy.js +16 -7
  163. package/dist/core/tool-result-store.d.ts +20 -0
  164. package/dist/core/tool-spec.d.ts +4 -0
  165. package/dist/core/trace.d.ts +3 -2
  166. package/dist/core/workflow-journal-store.d.ts +11 -0
  167. package/dist/core/workflow-journal-store.js +7 -0
  168. package/dist/core/workflow-run-store.d.ts +9 -0
  169. package/dist/core/workflow-run-store.js +6 -0
  170. package/dist/engine/compaction/compaction.d.ts +2 -1
  171. package/dist/engine/harness/types.d.ts +1 -0
  172. package/dist/engine/session/session.d.ts +7 -1
  173. package/dist/engine/session/session.js +5 -2
  174. package/dist/index.d.ts +7 -5
  175. package/dist/index.js +7 -5
  176. package/dist/orchestration/run-workflow-tool.d.ts +4 -0
  177. package/dist/orchestration/run-workflow-tool.js +7 -0
  178. package/dist/orchestration/workflow-types.d.ts +2 -1
  179. package/dist/orchestration/workflow.d.ts +3 -0
  180. package/dist/orchestration/workflow.js +2 -1
  181. package/dist/stores/file/checkpoint-store.d.ts +6 -0
  182. package/dist/stores/file/checkpoint-store.js +4 -1
  183. package/dist/stores/file/file-history-store.d.ts +13 -0
  184. package/dist/stores/file/file-history-store.js +75 -13
  185. package/dist/stores/file/index.d.ts +11 -1
  186. package/dist/stores/file/index.js +7 -11
  187. package/dist/stores/file/permission-rule-store.d.ts +23 -0
  188. package/dist/stores/file/permission-rule-store.js +75 -7
  189. package/dist/stores/file/tool-result-store.d.ts +14 -0
  190. package/dist/stores/file/tool-result-store.js +39 -2
  191. package/dist/stores/file/workflow-journal-store.d.ts +4 -0
  192. package/dist/stores/file/workflow-journal-store.js +17 -0
  193. package/dist/stores/file/workflow-run-store.d.ts +3 -0
  194. package/dist/stores/file/workflow-run-store.js +15 -0
  195. package/dist/tools/fs/read-deny.d.ts +15 -2
  196. package/dist/tools/fs/read-deny.js +10 -2
  197. package/dist/tools/fs/shell-read-check.d.ts +8 -2
  198. package/dist/tools/fs/shell-read-check.js +7 -7
  199. package/package.json +2 -2
  200. package/test/export-surface.snapshot.json +63 -1
  201. package/wire-changes/core-stores-sql@7.64.0.json +30 -0
  202. package/wire-changes/core@7.64.0.json +2653 -0
  203. package/wire-changes/mods-kernel@7.64.0.json +30 -0
  204. package/wire-changes/primitives@7.64.0.json +30 -0
@@ -4,6 +4,8 @@ import { egressText } from "./untrusted-egress.js";
4
4
  import { redactThenCut } from "../agents/subagent-steps.js";
5
5
  import { PEER_MESSAGE_NOTICE } from "../agents/peer-admission.js";
6
6
  import { buildCrossSessionEnvelope, CROSS_PRINCIPAL_MESSAGE_NOTICE, CROSS_SESSION_MESSAGE_NOTICE, neutralizePeerBody } from "../agents/cross-session-envelope.js";
7
+ import { deliverEngineNotice } from "./engine-notice.js";
8
+ import { sameOccupant } from "./runner/delegation-owner.js";
7
9
  export const TASK_NOTIFICATION_TERMINAL_STATUSES = Object.freeze(["completed", "failed", "killed", "cancelled"]);
8
10
  export const NOTIFICATION_INJECTION_OUTCOMES = Object.freeze(["queued", "parked", "parked_durably", "dropped_duplicate", "refused"]);
9
11
  export function isNotificationInjectionOutcome(value) {
@@ -163,6 +165,23 @@ export const MAX_PENDING_EVENTS_PER_TASK = 50;
163
165
  export const MAX_PENDING_EVENTS_PER_SESSION = 200;
164
166
  export const MAX_PENDING_SESSIONS = 100;
165
167
  export const MAX_SESSION_BOX_BINDINGS = 4096;
168
+ export function sessionAddressOf(leg) {
169
+ return { sessionId: leg.sessionId, occupant: leg.sessionIncarnation, ...(leg.sessionIncarnationUnread === true ? { unread: true } : {}) };
170
+ }
171
+ export function deliveryDiscardedNotice(address, current, payload, path) {
172
+ return {
173
+ code: "delegation.delivery_discarded",
174
+ message: `a ${inlineUntrusted(String(payload.task_type), 40)} frame of task ${inlineUntrusted(String(payload.task_id), 120)} was addressed to session ${inlineUntrusted(address.sessionId, 120)} under an occupant the session does not hold now (the id was deleted and created again, or the address carried no occupant), so it was discarded, not delivered`,
175
+ detail: {
176
+ taskId: payload.task_id,
177
+ taskType: payload.task_type,
178
+ sessionId: address.sessionId,
179
+ path,
180
+ addressed: address.occupant !== undefined ? "known" : "unknown",
181
+ current: current !== undefined ? "known" : "unknown",
182
+ },
183
+ };
184
+ }
166
185
  export const HANDBACK_STATES = Object.freeze(["send", "flagged", "withheld"]);
167
186
  export function handbackStateOf(facts) {
168
187
  if (facts.warning !== undefined)
@@ -285,12 +304,12 @@ function malformedFacet(f) {
285
304
  }
286
305
  return undefined;
287
306
  }
288
- export function engineFrameRecordOf(payload, priority, box) {
307
+ export function engineFrameRecordOf(payload, priority, to) {
289
308
  return {
290
309
  id: taskNotificationDedupKey(payload),
291
310
  content: encodeEngineFrame(payload, priority),
292
311
  sentAt: Date.now(),
293
- peerMeta: { fromRoot: box.sessionId, kind: "engine_frame" },
312
+ peerMeta: { fromRoot: to.sessionId, kind: "engine_frame", ...(to.occupant !== undefined ? { occupant: to.occupant } : {}) },
294
313
  };
295
314
  }
296
315
  const MAX_TOMBSTONES = 5_000;
@@ -426,62 +445,134 @@ export function createLiveNotificationLane(seat) {
426
445
  }
427
446
  export class SessionLiveNotificationLanes {
428
447
  lanes = new Map();
429
- register(sessionId, lane) {
430
- const existing = this.lanes.get(sessionId);
448
+ register(address, lane) {
449
+ if (address.unread === true)
450
+ return;
451
+ const existing = this.lanes.get(address.sessionId);
452
+ const seat = { occupant: address.occupant, lane };
431
453
  if (existing === undefined)
432
- this.lanes.set(sessionId, [lane]);
433
- else if (!existing.includes(lane))
434
- existing.push(lane);
454
+ this.lanes.set(address.sessionId, [seat]);
455
+ else if (!existing.some((s) => s.lane === lane))
456
+ existing.push(seat);
435
457
  }
436
- unregister(sessionId, lane) {
437
- const existing = this.lanes.get(sessionId);
458
+ unregister(address, lane) {
459
+ const existing = this.lanes.get(address.sessionId);
438
460
  if (existing === undefined)
439
461
  return;
440
- const at = existing.indexOf(lane);
462
+ const at = existing.findIndex((s) => s.lane === lane);
441
463
  if (at !== -1)
442
464
  existing.splice(at, 1);
443
465
  if (existing.length === 0)
444
- this.lanes.delete(sessionId);
466
+ this.lanes.delete(address.sessionId);
445
467
  }
446
- deliver(sessionId, payload, priority, opts) {
447
- const existing = this.lanes.get(sessionId);
468
+ deliver(address, payload, priority, opts) {
469
+ const existing = this.lanes.get(address.sessionId);
448
470
  if (existing === undefined)
449
471
  return "unavailable";
450
472
  for (let i = existing.length - 1; i >= 0; i -= 1) {
451
- const outcome = existing[i](payload, priority, opts?.onDisposition);
473
+ const seat = existing[i];
474
+ if (!sameOccupant(seat.occupant, address.occupant))
475
+ continue;
476
+ const outcome = seat.lane(payload, priority, opts?.onDisposition);
452
477
  if (outcome !== "unavailable")
453
478
  return outcome;
454
479
  }
455
480
  return "unavailable";
456
481
  }
482
+ holds(address) {
483
+ return this.lanes.get(address.sessionId)?.some((s) => sameOccupant(s.occupant, address.occupant)) === true;
484
+ }
457
485
  get size() {
458
486
  return this.lanes.size;
459
487
  }
460
488
  }
489
+ function parksDurably(payload, box) {
490
+ return payload.agentMessage !== undefined || (box.engineFrames === true && isEngineFrameParkable(payload));
491
+ }
492
+ function keysOf(held, address) {
493
+ const entry = held.get(address.sessionId);
494
+ return entry !== undefined && sameOccupant(entry.occupant, address.occupant) ? entry.keys : undefined;
495
+ }
496
+ function addOccupantKey(held, address, dedupKey) {
497
+ let mine = keysOf(held, address);
498
+ if (mine === undefined) {
499
+ held.delete(address.sessionId);
500
+ if (held.size >= MAX_PENDING_SESSIONS) {
501
+ const oldest = held.keys().next().value;
502
+ if (oldest !== undefined)
503
+ held.delete(oldest);
504
+ }
505
+ mine = new Set();
506
+ held.set(address.sessionId, { occupant: address.occupant, keys: mine });
507
+ }
508
+ mine.add(dedupKey);
509
+ if (mine.size > MAX_PENDING_EVENTS_PER_SESSION) {
510
+ for (const k of mine) {
511
+ mine.delete(k);
512
+ if (mine.size <= MAX_PENDING_EVENTS_PER_SESSION)
513
+ break;
514
+ }
515
+ }
516
+ }
461
517
  export class PendingSessionNotifications {
462
518
  sessions = new Map();
519
+ noticeSeat;
520
+ constructor(seats) {
521
+ this.noticeSeat = seats?.onNotice ?? (() => undefined);
522
+ }
463
523
  liveLanes = new SessionLiveNotificationLanes();
464
524
  droppedSessions = 0;
465
525
  evictedSessions = new Map();
466
526
  unattributedDrops = 0;
467
- sessionBoxes = new Map();
468
- bindSessionBox(sessionId, box) {
469
- this.sessionBoxes.delete(sessionId);
470
- if (box === undefined)
527
+ seats = new Map();
528
+ admit(address, box) {
529
+ if (address.unread === true)
471
530
  return;
472
- this.sessionBoxes.set(sessionId, box);
473
- while (this.sessionBoxes.size > MAX_SESSION_BOX_BINDINGS) {
474
- const oldest = this.sessionBoxes.keys().next().value;
475
- if (oldest === undefined)
531
+ this.seats.delete(address.sessionId);
532
+ this.seats.set(address.sessionId, { occupant: address.occupant, ...(box !== undefined ? { box } : {}) });
533
+ for (const id of this.seats.keys()) {
534
+ if (this.seats.size <= MAX_SESSION_BOX_BINDINGS)
476
535
  break;
477
- this.sessionBoxes.delete(oldest);
536
+ if (!this.sessions.has(id))
537
+ this.seats.delete(id);
538
+ }
539
+ const parked = this.sessions.get(address.sessionId);
540
+ if (parked !== undefined && !sameOccupant(parked.occupant, address.occupant))
541
+ this.discardRecord(address.sessionId, parked, address.occupant);
542
+ for (const held of [this.evictedSessions, this.routed, this.durable]) {
543
+ const entry = held.get(address.sessionId);
544
+ if (entry !== undefined && !sameOccupant(entry.occupant, address.occupant))
545
+ held.delete(address.sessionId);
478
546
  }
479
547
  }
480
- sessionBoxFor(sessionId) {
481
- return this.sessionBoxes.get(sessionId);
548
+ sessionBoxFor(address) {
549
+ const seat = this.seats.get(address.sessionId);
550
+ return seat !== undefined && sameOccupant(seat.occupant, address.occupant) ? seat.box : undefined;
551
+ }
552
+ discardsStale(address, payload) {
553
+ const seat = this.seats.get(address.sessionId);
554
+ if (address.unread !== true && (seat === undefined || sameOccupant(address.occupant, seat.occupant)))
555
+ return false;
556
+ const current = { sessionId: address.sessionId, occupant: seat?.occupant };
557
+ const path = seat !== undefined && this.liveLanes.holds(current) ? "live" : seat?.box !== undefined && parksDurably(payload, seat.box) ? "box" : "drain";
558
+ this.announceDiscard(address, seat?.occupant, payload, path);
559
+ return true;
560
+ }
561
+ announceDiscard(address, current, payload, path) {
562
+ deliverEngineNotice(this.noticeSeat(), deliveryDiscardedNotice(address, current, payload, path));
563
+ }
564
+ discardRecord(sessionId, record, current) {
565
+ if (this.sessions.get(sessionId) === record)
566
+ this.sessions.delete(sessionId);
567
+ for (const n of record.items)
568
+ this.announceDiscard({ sessionId, occupant: record.occupant }, current, n, "drain");
482
569
  }
483
- settleBoxDebts(sessionId, signal) {
484
- const owed = this.sessions.get(sessionId)?.boxDebts;
570
+ recordOf(address) {
571
+ const s = this.sessions.get(address.sessionId);
572
+ return s !== undefined && sameOccupant(s.occupant, address.occupant) ? s : undefined;
573
+ }
574
+ settleBoxDebts(address, signal) {
575
+ const owed = this.recordOf(address)?.boxDebts;
485
576
  if (owed === undefined || owed.size === 0)
486
577
  return undefined;
487
578
  const debts = [...owed];
@@ -489,7 +580,7 @@ export class PendingSessionNotifications {
489
580
  for (const [copy, debt] of debts) {
490
581
  if (signal?.aborted === true)
491
582
  return;
492
- await this.settleBoxDebt(sessionId, copy, debt);
583
+ await this.settleBoxDebt(address, copy, debt);
493
584
  }
494
585
  })();
495
586
  }
@@ -504,11 +595,12 @@ export class PendingSessionNotifications {
504
595
  if (p !== undefined)
505
596
  tiers.set(n, p);
506
597
  }
507
- this.sessions.set(sessionId, { items: owing, dropped: new Map(), keys: new Set(owing.map((n) => taskNotificationDedupKey(n))), priorities: tiers, boxDebts: debts });
598
+ this.sessions.set(sessionId, { occupant: s.occupant, items: owing, dropped: new Map(), keys: new Set(owing.map((n) => taskNotificationDedupKey(n))), priorities: tiers, boxDebts: debts });
508
599
  const rest = s.items.filter((n) => !debts.has(n));
509
600
  return rest.length === 0 && s.dropped.size === 0 ? undefined : { ...s, items: rest };
510
601
  }
511
- async settleBoxDebt(sessionId, copy, debt) {
602
+ async settleBoxDebt(address, copy, debt) {
603
+ const sessionId = address.sessionId;
512
604
  let answered = false;
513
605
  try {
514
606
  await debt.box.mailbox.append(debt.box.scope, debt.box.handle, debt.record);
@@ -521,7 +613,7 @@ export class PendingSessionNotifications {
521
613
  catch {
522
614
  }
523
615
  }
524
- const s = this.sessions.get(sessionId);
616
+ const s = this.recordOf(address);
525
617
  if (s?.boxDebts?.get(copy) !== debt)
526
618
  return;
527
619
  s.boxDebts.delete(copy);
@@ -532,12 +624,19 @@ export class PendingSessionNotifications {
532
624
  const key = taskNotificationDedupKey(copy);
533
625
  s.keys.delete(key);
534
626
  s.priorities?.delete(copy);
535
- this.noteDurablePark(sessionId, key);
627
+ this.noteDurablePark(address, key);
536
628
  if (s.items.length === 0 && s.dropped.size === 0)
537
629
  this.sessions.delete(sessionId);
538
630
  }
539
- pend(sessionId, n, priority, debt) {
631
+ pend(address, n, priority, debt) {
632
+ if (this.discardsStale(address, n))
633
+ return false;
634
+ const sessionId = address.sessionId;
540
635
  let s = this.sessions.get(sessionId);
636
+ if (s !== undefined && !sameOccupant(s.occupant, address.occupant)) {
637
+ this.discardRecord(sessionId, s, address.occupant);
638
+ s = undefined;
639
+ }
541
640
  if (s === undefined) {
542
641
  if (this.sessions.size >= MAX_PENDING_SESSIONS) {
543
642
  const oldest = this.sessions.keys().next().value;
@@ -550,20 +649,22 @@ export class PendingSessionNotifications {
550
649
  if (!this.evictedSessions.has(oldest) && this.evictedSessions.size >= MAX_TOMBSTONES) {
551
650
  const oldestTomb = this.evictedSessions.keys().next().value;
552
651
  if (oldestTomb !== undefined) {
553
- this.unattributedDrops += this.evictedSessions.get(oldestTomb) ?? 0;
652
+ this.unattributedDrops += this.evictedSessions.get(oldestTomb)?.count ?? 0;
554
653
  this.evictedSessions.delete(oldestTomb);
555
654
  }
556
655
  }
557
- this.evictedSessions.set(oldest, (this.evictedSessions.get(oldest) ?? 0) + lost);
656
+ const tomb = this.evictedSessions.get(oldest);
657
+ const occupant = victim?.occupant;
658
+ this.evictedSessions.set(oldest, { occupant, count: (tomb !== undefined && sameOccupant(tomb.occupant, occupant) ? tomb.count : 0) + lost });
558
659
  }
559
660
  }
560
661
  }
561
- s = { items: [], dropped: new Map(), keys: new Set(), priorities: new Map() };
662
+ s = { occupant: address.occupant, items: [], dropped: new Map(), keys: new Set(), priorities: new Map() };
562
663
  this.sessions.set(sessionId, s);
563
664
  }
564
665
  const key = taskNotificationDedupKey(n);
565
666
  if (s.keys.has(key))
566
- return;
667
+ return true;
567
668
  s.keys.add(key);
568
669
  s.items.push(n);
569
670
  if (priority !== undefined)
@@ -579,10 +680,17 @@ export class PendingSessionNotifications {
579
680
  evictOldest(s, (i) => taskNotificationLaneKey(i) === lane);
580
681
  if (s.items.length > MAX_PENDING_EVENTS_PER_SESSION)
581
682
  evictOldest(s, () => true);
683
+ return true;
582
684
  }
583
- drain(sessionId) {
685
+ drain(address) {
686
+ if (address.unread === true)
687
+ return undefined;
688
+ const sessionId = address.sessionId;
584
689
  this.routed.delete(sessionId);
585
- const parked = this.sessions.get(sessionId);
690
+ const held = this.sessions.get(sessionId);
691
+ if (held !== undefined && !sameOccupant(held.occupant, address.occupant))
692
+ this.discardRecord(sessionId, held, address.occupant);
693
+ const parked = this.recordOf(address);
586
694
  if (parked !== undefined)
587
695
  this.sessions.delete(sessionId);
588
696
  const s = parked !== undefined ? this.keepBackOwing(sessionId, parked) : undefined;
@@ -593,10 +701,12 @@ export class PendingSessionNotifications {
593
701
  };
594
702
  s.items = [...s.items].sort((a, b) => rank(a) - rank(b));
595
703
  }
596
- const tomb = this.evictedSessions.get(sessionId);
704
+ const tombstone = this.evictedSessions.get(sessionId);
705
+ const tomb = tombstone !== undefined && sameOccupant(tombstone.occupant, address.occupant) ? tombstone.count : undefined;
706
+ if (tombstone !== undefined)
707
+ this.evictedSessions.delete(sessionId);
597
708
  if (tomb === undefined && this.unattributedDrops === 0)
598
709
  return s;
599
- this.evictedSessions.delete(sessionId);
600
710
  const carried = this.unattributedDrops;
601
711
  this.unattributedDrops = 0;
602
712
  const out = s ?? { items: [], dropped: new Map() };
@@ -604,57 +714,23 @@ export class PendingSessionNotifications {
604
714
  return out;
605
715
  }
606
716
  routed = new Map();
607
- holdsKey(sessionId, dedupKey) {
608
- return this.sessions.get(sessionId)?.keys.has(dedupKey) === true || this.routed.get(sessionId)?.has(dedupKey) === true || this.durable.get(sessionId)?.has(dedupKey) === true;
717
+ holdsKey(address, dedupKey) {
718
+ return this.recordOf(address)?.keys.has(dedupKey) === true || keysOf(this.routed, address)?.has(dedupKey) === true || keysOf(this.durable, address)?.has(dedupKey) === true;
609
719
  }
610
720
  durable = new Map();
611
- noteDurablePark(sessionId, dedupKey) {
612
- let mine = this.durable.get(sessionId);
613
- if (mine === undefined) {
614
- if (this.durable.size >= MAX_PENDING_SESSIONS) {
615
- const oldest = this.durable.keys().next().value;
616
- if (oldest !== undefined)
617
- this.durable.delete(oldest);
618
- }
619
- mine = new Set();
620
- this.durable.set(sessionId, mine);
621
- }
622
- mine.add(dedupKey);
623
- if (mine.size > MAX_PENDING_EVENTS_PER_SESSION) {
624
- for (const k of mine) {
625
- mine.delete(k);
626
- if (mine.size <= MAX_PENDING_EVENTS_PER_SESSION)
627
- break;
628
- }
629
- }
721
+ noteDurablePark(address, dedupKey) {
722
+ addOccupantKey(this.durable, address, dedupKey);
630
723
  }
631
- forgetDurablePark(sessionId, dedupKey) {
632
- const mine = this.durable.get(sessionId);
724
+ forgetDurablePark(address, dedupKey) {
725
+ const mine = keysOf(this.durable, address);
633
726
  if (mine === undefined)
634
727
  return;
635
728
  mine.delete(dedupKey);
636
729
  if (mine.size === 0)
637
- this.durable.delete(sessionId);
638
- }
639
- markDelivered(sessionId, dedupKey) {
640
- let mine = this.routed.get(sessionId);
641
- if (mine === undefined) {
642
- if (this.routed.size >= MAX_PENDING_SESSIONS) {
643
- const oldest = this.routed.keys().next().value;
644
- if (oldest !== undefined)
645
- this.routed.delete(oldest);
646
- }
647
- mine = new Set();
648
- this.routed.set(sessionId, mine);
649
- }
650
- mine.add(dedupKey);
651
- if (mine.size > MAX_PENDING_EVENTS_PER_SESSION) {
652
- for (const k of mine) {
653
- mine.delete(k);
654
- if (mine.size <= MAX_PENDING_EVENTS_PER_SESSION)
655
- break;
656
- }
657
- }
730
+ this.durable.delete(address.sessionId);
731
+ }
732
+ markDelivered(address, dedupKey) {
733
+ addOccupantKey(this.routed, address, dedupKey);
658
734
  }
659
735
  get size() {
660
736
  return this.sessions.size;
@@ -678,20 +754,23 @@ export class DurableAppendObligations {
678
754
  await Promise.allSettled([...this.inFlight]);
679
755
  }
680
756
  }
681
- export function routeOrParkNotification(store, sessionId, payload, priority, onDisposition) {
757
+ export function routeOrParkNotification(store, address, payload, priority, onDisposition) {
758
+ if (store.discardsStale(address, payload)) {
759
+ onDisposition?.("refused");
760
+ return;
761
+ }
682
762
  const dedupKey = taskNotificationDedupKey(payload);
683
- if (store.holdsKey(sessionId, dedupKey)) {
763
+ if (store.holdsKey(address, dedupKey)) {
684
764
  onDisposition?.("parked");
685
765
  return;
686
766
  }
687
- const routed = store.liveLanes.deliver(sessionId, payload, priority, { ...(onDisposition !== undefined ? { onDisposition } : {}) });
767
+ const routed = store.liveLanes.deliver(address, payload, priority, { ...(onDisposition !== undefined ? { onDisposition } : {}) });
688
768
  if (routed === "unavailable") {
689
- const box = store.sessionBoxFor(sessionId);
769
+ const box = store.sessionBoxFor(address);
690
770
  const carrier = payload.agentMessage;
691
- const durable = box !== undefined && (carrier !== undefined || (box.engineFrames === true && isEngineFrameParkable(payload)));
692
- if (box !== undefined && durable) {
693
- store.noteDurablePark(sessionId, dedupKey);
694
- const record = carrier !== undefined ? sessionBoxRecordOf({ ...payload, agentMessage: carrier }, box) : engineFrameRecordOf(payload, priority, box);
771
+ if (box !== undefined && parksDurably(payload, box)) {
772
+ store.noteDurablePark(address, dedupKey);
773
+ const record = carrier !== undefined ? sessionBoxRecordOf({ ...payload, agentMessage: carrier }, address) : engineFrameRecordOf(payload, priority, address);
695
774
  const ask = () => {
696
775
  try {
697
776
  return Promise.resolve(box.mailbox.append(box.scope, box.handle, record));
@@ -709,21 +788,21 @@ export function routeOrParkNotification(store, sessionId, payload, priority, onD
709
788
  return ask();
710
789
  });
711
790
  const settled = appended.then(() => onDisposition?.("parked_durably"), () => {
712
- store.forgetDurablePark(sessionId, dedupKey);
713
- store.pend(sessionId, payload, priority, { box, record });
714
- onDisposition?.("parked");
791
+ store.forgetDurablePark(address, dedupKey);
792
+ const parked = store.pend(address, payload, priority, { box, record });
793
+ onDisposition?.(parked ? "parked" : "refused");
715
794
  });
716
795
  DurableAppendObligations.current()?.track(settled);
717
796
  return;
718
797
  }
719
- store.pend(sessionId, payload, priority);
720
- onDisposition?.("parked");
798
+ const parked = store.pend(address, payload, priority);
799
+ onDisposition?.(parked ? "parked" : "refused");
721
800
  }
722
801
  else if (routed !== "taken") {
723
802
  onDisposition?.("queued");
724
803
  }
725
804
  }
726
- export function sessionBoxRecordOf(payload, box) {
805
+ export function sessionBoxRecordOf(payload, to) {
727
806
  const peer = payload.peer;
728
807
  return {
729
808
  id: taskNotificationDedupKey(payload),
@@ -734,8 +813,9 @@ export function sessionBoxRecordOf(payload, box) {
734
813
  peerMeta: {
735
814
  ...(peer?.fromSession !== undefined ? { fromSession: peer.fromSession } : {}),
736
815
  ...(peer?.senderKey !== undefined ? { senderKey: peer.senderKey } : {}),
737
- fromRoot: box.sessionId,
816
+ fromRoot: to.sessionId,
738
817
  kind: "peer_message",
818
+ ...(to.occupant !== undefined ? { occupant: to.occupant } : {}),
739
819
  },
740
820
  };
741
821
  }
@@ -1,5 +1,6 @@
1
1
  import { type BackgroundAgentRecord, type BackgroundAgentStore } from "./background-agent-store.js";
2
2
  import { type StopSource, type TaskAccess, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type BackgroundAgentTaskHandle, type ChildSessionStore, type RegisteredTaskHandle, type DurableAgentCore, type ParkedClaimTicket, type RegisterBackgroundAgentInput, type LandedAgentTerminal } from "./task-registry-shared.js";
3
+ import type { ExtensionRequester } from "./task-event.js";
3
4
  import { type AgentState } from "./agent-state.js";
4
5
  import type { CheckpointSeat } from "./checkpoint-seat.js";
5
6
  /**
@@ -19,6 +20,8 @@ export declare function activeDelegationHandlesLane(core: DurableAgentCore, scop
19
20
  export interface DelegationOccupant {
20
21
  readonly id: string;
21
22
  readonly name: string;
23
+ /** The extension that started the row, when one did (the row's `requestedBy`); absent for every other row. */
24
+ readonly requestedBy?: ExtensionRequester;
22
25
  readonly reachable: boolean;
23
26
  }
24
27
  /** The rows {@link activeDelegationHandlesLane} counts, with the name each is addressed by — the one selection, read in the same
@@ -545,6 +548,14 @@ export interface AgentPollDetailsInput {
545
548
  * `agentState` when given; the poll arms always give it, a serving layer may omit it. */
546
549
  agentState?: AgentState;
547
550
  }
551
+ /**
552
+ * The ONE reading of a delegation outcome's tool-result error bit: a delegation whose child FAILED produced no usable result,
553
+ * so the tool result that reports it is an error (`isError: true`) — on the synchronous card, the fork card, the live poll
554
+ * and the durable poll alike, so a hook or a host reading the bit never sees `false` beside `status: failed`. Every other
555
+ * outcome word answers `false` here: a completed, killed or still-running delegation is data, and the refusals that never
556
+ * start a child (a refused call, a held park, an unavailable isolation) are their own constructors, not outcomes.
557
+ */
558
+ export declare function agentOutcomeIsError(status: string): boolean;
548
559
  /** PUBLIC (see the doc above): a serving layer that renders its own protocol projection of a row
549
560
  * builds the structured facts HERE, so the status gates and the untrusted-text fencing apply to it
550
561
  * too — a third literal is exactly the drift this builder exists to prevent. Input only; it reads no
@@ -7,6 +7,7 @@ import { delimitUntrusted } from "./untrusted-text.js";
7
7
  import { boundedRedactedSummary } from "./untrusted-egress.js";
8
8
  import { mintCompletionId, commitCompletionIdIfEmpty, clipTaskOutput, assertOwnership, sleepPollStep, alreadyTerminalStopNote, canAccess, normalizeAgentName, engineAgentName, chosenAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, } from "./task-registry-shared.js";
9
9
  import { thrownLabel } from "./thrown-value.js";
10
+ import { readExtensionRequester } from "./extension-requester.js";
10
11
  import { closestName } from "./closest-name.js";
11
12
  import { agentStateSourceOfHandle, agentStateSummary, readAgentState } from "./agent-state.js";
12
13
  export function activeDelegationHandlesLane(core, scope, rootSessionId) {
@@ -25,7 +26,8 @@ export function activeDelegationOccupantsLane(core, scope, rootSessionId, caller
25
26
  const root = bh.rootSessionId ?? bh.parentSessionId ?? (bh.sessionScoped ? bh.owner : undefined);
26
27
  if (root !== rootSessionId)
27
28
  continue;
28
- out.push({ id: h.id, name: bh.name, reachable: caller !== undefined && canAccess(h, { ...caller, scope }) });
29
+ const requestedBy = readExtensionRequester(bh.requestedBy);
30
+ out.push({ id: h.id, name: bh.name, ...(requestedBy !== undefined ? { requestedBy } : {}), reachable: caller !== undefined && canAccess(h, { ...caller, scope }) });
29
31
  }
30
32
  return out;
31
33
  }
@@ -395,6 +397,7 @@ export function registerBackgroundAgentLane(core, input) {
395
397
  throw new Error(`TaskRegistry: background-agent name must be a non-empty string (got ${JSON.stringify(input.name)}); omit it to take the derived one`);
396
398
  }
397
399
  const name = input.name ?? engineAgentName(id);
400
+ const requestedBy = readExtensionRequester(input.requestedBy);
398
401
  core.handles.set(id, {
399
402
  id,
400
403
  type: "background_agent",
@@ -406,6 +409,7 @@ export function registerBackgroundAgentLane(core, input) {
406
409
  ...(input.description !== undefined ? { description: input.description } : {}),
407
410
  name,
408
411
  ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
412
+ ...(requestedBy !== undefined ? { requestedBy } : {}),
409
413
  ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
410
414
  ...(input.parentSessionId !== undefined ? { parentSessionId: input.parentSessionId } : {}),
411
415
  ...(input.rootSessionId !== undefined ? { rootSessionId: input.rootSessionId } : {}),
@@ -449,6 +453,7 @@ export function registerBackgroundAgentLane(core, input) {
449
453
  ...(input.parentTaskId !== undefined ? { parentTaskId: input.parentTaskId } : {}),
450
454
  name,
451
455
  ...(input.agentType !== undefined ? { agentType: input.agentType } : {}),
456
+ ...(requestedBy !== undefined ? { requestedBy } : {}),
452
457
  ...(input.description !== undefined ? { description: input.description } : {}),
453
458
  ...(input.model !== undefined ? { model: input.model } : {}),
454
459
  ...(input.policyFloor !== undefined ? { policyFloor: input.policyFloor } : {}),
@@ -1331,6 +1336,9 @@ export function notFoundRunningAgentsTail(footer) {
1331
1336
  return ((footer.named.length > 0 ? `. Running named agents: ${footer.named.join(", ")}` : "") +
1332
1337
  (footer.background.length > 0 ? `. Running background agents: ${footer.background.join(", ")}` : ""));
1333
1338
  }
1339
+ export function agentOutcomeIsError(status) {
1340
+ return status === "failed";
1341
+ }
1334
1342
  export function buildAgentPollDetails(input) {
1335
1343
  const failed = input.status === "failed";
1336
1344
  return {
@@ -1387,7 +1395,7 @@ ${clipTaskOutput(row.finalOutputFull ?? row.finalOutput)}` : "(no result text)"}
1387
1395
  ...(row.completionId !== undefined ? { completionId: row.completionId } : {}),
1388
1396
  ...(agentState !== undefined ? { agentState } : {}),
1389
1397
  }),
1390
- ...(row.status === "failed" ? { isError: true } : {}),
1398
+ ...(agentOutcomeIsError(row.status) ? { isError: true } : {}),
1391
1399
  };
1392
1400
  }
1393
1401
  export async function pollBackgroundAgentLane(handle, deadline, signal, checkpointSeat) {
@@ -1458,7 +1466,7 @@ ${resultText}` : "(no result text)"}`;
1458
1466
  ...(snap.completionId !== undefined ? { completionId: snap.completionId } : {}),
1459
1467
  agentState,
1460
1468
  }),
1461
- ...(snap.status === "failed" ? { isError: true } : {}),
1469
+ ...(agentOutcomeIsError(snap.status) ? { isError: true } : {}),
1462
1470
  };
1463
1471
  }
1464
1472
  export async function stopBackgroundAgentLane(core, handle) {
@@ -4,6 +4,7 @@ import { type WorkflowRunStore } from "./workflow-run-store.js";
4
4
  import type { BackgroundAgentRecord, BackgroundAgentStore } from "./background-agent-store.js";
5
5
  import type { WorkflowHandle, WorkflowRun } from "../orchestration/workflow.js";
6
6
  import type { TaskNotificationPayload } from "./task-notification.js";
7
+ import type { ExtensionRequester } from "./task-event.js";
7
8
  import type { TaskArtifactSeat } from "./tool-result-store.js";
8
9
  import type { AssertAllKeysHandled } from "./ask-origin.js";
9
10
  export type SemaTaskType = "background_bash" | "workflow" | "background_agent" | "monitor";
@@ -271,6 +272,8 @@ export interface BackgroundAgentTaskHandle extends SemaTaskHandle {
271
272
  parentTaskId?: string;
272
273
  parentSessionId?: string;
273
274
  rootSessionId?: string;
275
+ /** Who started the agent when an extension did ({@link RegisterBackgroundAgentInput.requestedBy}); absent otherwise. */
276
+ requestedBy?: ExtensionRequester;
274
277
  /** design/151 S1a — the child's store session id (transcript/resume anchor), bound once the child
275
278
  * session is minted ({@link TaskRegistry.bindBackgroundAgentSession}) and removed — together with the
276
279
  * durable record's copy — by the successful release of that session
@@ -932,6 +935,10 @@ export interface RegisterBackgroundAgentInput extends TaskAccess {
932
935
  /** the RESOLVED subagent type ("general-purpose"/"fork"/a roster name), persisted
933
936
  * so a REVIVE cycle's observer frames can reproduce the row's TYPE column (never the description). */
934
937
  agentType?: string;
938
+ /** Who started this agent when an extension did: the extension, by its registration name (`$.agent.spawn`) — persisted on the row,
939
+ * so a revival keeps the row's origin. ABSENT = not an extension's spawn (the model's own, the host's): the one reading, with no
940
+ * word for either of those. A display and audit fact only — it decides nothing. */
941
+ requestedBy?: ExtensionRequester;
935
942
  /** the spawn frame's parent linkage, persisted so a REVIVE cycle's spawn frame nests the
936
943
  * revived row exactly like the first spawn did. The caller passes the SAME values it emitted on the
937
944
  * original frame (parentTaskId already-clamped there; parentSessionId always-on). */
@@ -5,6 +5,7 @@ import type { BoundaryLegsGiven } from "./cross-boundary-taint.js";
5
5
  import type { WorkflowRunStore } from "./workflow-run-store.js";
6
6
  import { type BackgroundAgentStore } from "./background-agent-store.js";
7
7
  import type { TaskNotificationPayload } from "./task-notification.js";
8
+ import type { ExtensionRequester } from "./task-event.js";
8
9
  import { type TaskArtifactSeat } from "./tool-result-store.js";
9
10
  import { type SemaTaskType, type StopSource, type SemaTaskStatus, type TaskRetrievalStatus, type UnifiedTaskOutput, type UnifiedTaskResult, type SemaTaskHandle, type TaskAccess, type BackgroundAgentTaskHandle, type MonitorTimers, type RegisterMonitorInput, type RegisterWorkflowInput, canAccessWorkflowRun, clipTaskOutput, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE } from "./task-registry-shared.js";
10
11
  export { normalizeAgentName, DURABLE_AGENT_HEARTBEAT_MS, DURABLE_AGENT_HANDLE_RE, BG_AGENT_REAP_STOP_ERROR, engineAgentName, chosenAgentName } from "./task-registry-shared.js";
@@ -116,6 +117,10 @@ export interface TaskListRow {
116
117
  * session store still holds the session" — the session store answers that. Only this process's
117
118
  * handles are listed: a row known only to the durable store of another process is not here. */
118
119
  sessionId?: string;
120
+ /** The extension that started a `background_agent` row, when one did — its registration name, from the extension's own
121
+ * `$.agent.spawn` (`ExtensionRequester`); ABSENT on every other row (the model's own spawn, the host's, and every row an earlier
122
+ * release registered): the one reading, with no word for either. A display and audit fact only. */
123
+ requestedBy?: ExtensionRequester;
119
124
  createdAt: number;
120
125
  updatedAt: number;
121
126
  }
@@ -588,6 +593,19 @@ export declare class TaskRegistry {
588
593
  sessionId: string;
589
594
  scope: string;
590
595
  })): BackgroundShellHardKillReceipt[];
596
+ /** How many shell-lane rows (`background_bash` + `monitor`) the exit-boundary hard face would take down if it ran now: the
597
+ * registry's `running` shell rows, over the WHOLE registry — no owner, session, scope or env narrowing — with a retained row
598
+ * counted only under `includeRetained: true` (no default, as on {@link killAllBackgroundShellsNow}). The rows are chosen
599
+ * by the hard face's own reading ({@link hardFaceVisitOf}), so the count and the walk cannot drift. SYNCHRONOUS and READ-ONLY:
600
+ * the count calls no seat and changes no row; like the hard face it reads each row's env declaration of retention (host-provided
601
+ * data), so a host whose env makes that read throw makes the count throw. It counts registry rows, not process truth: a row whose seat later answers `already_gone`
602
+ * or `no_pgid` stays `running` and is counted until its watcher settles it. A row an earlier stop settled `killed` or
603
+ * `failed` is visited by the hard face but is not running, so it is not counted; `completed` rows are not visited.
604
+ * Not {@link list}'s length: `list(access)` is the caller's own reach, capped at `limit`, every task type and status;
605
+ * {@link countRunningBackgroundForOwner} is one owner key's running tasks, agents included. */
606
+ countRunningBackgroundShells(opts: {
607
+ includeRetained: boolean;
608
+ }): number;
591
609
  /** subscribe to `reapSessionBackground` (the design/129 session terminal anchor).
592
610
  * Returns an unsubscribe. Hooks are best-effort observers; a throwing hook is swallowed. */
593
611
  onSessionReap(hook: (sessionId: string, scope?: string) => void): () => void;