@sema-agent/core 7.63.0 → 7.65.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 (239) hide show
  1. package/CHANGELOG.md +725 -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 +25 -5
  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/auto-promote.d.ts +3 -2
  30. package/dist/core/background-agent-store.d.ts +14 -0
  31. package/dist/core/background-agent-store.js +3 -0
  32. package/dist/core/checkpoint-queries.d.ts +9 -6
  33. package/dist/core/checkpoint-queries.js +8 -3
  34. package/dist/core/checkpoint-store.d.ts +7 -4
  35. package/dist/core/context-settings.d.ts +39 -9
  36. package/dist/core/context-settings.js +32 -10
  37. package/dist/core/engine-attestation.d.ts +26 -6
  38. package/dist/core/engine-attestation.js +5 -1
  39. package/dist/core/engine-notice.d.ts +37 -2
  40. package/dist/core/engine-notice.js +3 -1
  41. package/dist/core/extension-requester.d.ts +9 -0
  42. package/dist/core/extension-requester.js +7 -0
  43. package/dist/core/file-history-store.d.ts +30 -2
  44. package/dist/core/file-history-store.js +48 -9
  45. package/dist/core/fs-write-gate-policy.js +1 -1
  46. package/dist/core/gate-fold.js +5 -1
  47. package/dist/core/gate-lanes.js +2 -0
  48. package/dist/core/gate-outcome.d.ts +39 -2
  49. package/dist/core/gate-outcome.js +20 -1
  50. package/dist/core/governance-codes.d.ts +8 -4
  51. package/dist/core/governance-codes.js +8 -3
  52. package/dist/core/leg-identity.d.ts +35 -1
  53. package/dist/core/leg-identity.js +10 -0
  54. package/dist/core/mailbox-store.d.ts +39 -4
  55. package/dist/core/mailbox-store.js +14 -2
  56. package/dist/core/memory-engine/consolidation.d.ts +13 -6
  57. package/dist/core/memory-engine/consolidation.js +26 -0
  58. package/dist/core/memory-engine/control-objects.d.ts +58 -0
  59. package/dist/core/memory-engine/control-objects.js +273 -0
  60. package/dist/core/memory-engine/control-plane-adoption.d.ts +51 -0
  61. package/dist/core/memory-engine/control-plane-adoption.js +161 -0
  62. package/dist/core/memory-engine/delegation-settlement.d.ts +73 -40
  63. package/dist/core/memory-engine/delegation-settlement.js +271 -107
  64. package/dist/core/memory-engine/dual-root.d.ts +3 -2
  65. package/dist/core/memory-engine/dual-root.js +7 -3
  66. package/dist/core/memory-engine/engine.d.ts +54 -33
  67. package/dist/core/memory-engine/engine.js +150 -157
  68. package/dist/core/memory-engine/file-backend.d.ts +58 -76
  69. package/dist/core/memory-engine/file-backend.js +111 -268
  70. package/dist/core/memory-engine/index.d.ts +3 -2
  71. package/dist/core/memory-engine/index.js +2 -1
  72. package/dist/core/memory-engine/layout.d.ts +135 -50
  73. package/dist/core/memory-engine/layout.js +214 -89
  74. package/dist/core/memory-engine/memory-age.d.ts +12 -0
  75. package/dist/core/memory-engine/memory-age.js +17 -0
  76. package/dist/core/memory-engine/memory-backend-contract.d.ts +10 -3
  77. package/dist/core/memory-engine/memory-backend-contract.js +159 -2
  78. package/dist/core/memory-engine/memory-deployment.d.ts +12 -4
  79. package/dist/core/memory-engine/memory-deployment.js +31 -6
  80. package/dist/core/memory-engine/origin-clearance.d.ts +12 -3
  81. package/dist/core/memory-engine/origin-clearance.js +64 -9
  82. package/dist/core/memory-engine/session-write-home.d.ts +34 -1
  83. package/dist/core/memory-engine/session-write-home.js +37 -10
  84. package/dist/core/memory-engine/tools.d.ts +2 -2
  85. package/dist/core/memory-engine/tools.js +7 -7
  86. package/dist/core/memory-engine/types.d.ts +55 -12
  87. package/dist/core/memory-engine/types.js +2 -1
  88. package/dist/core/memory-vector.d.ts +6 -14
  89. package/dist/core/memory.d.ts +0 -462
  90. package/dist/core/memory.js +0 -333
  91. package/dist/core/mode-policy.js +3 -3
  92. package/dist/core/mods/agent-stations.d.ts +18 -0
  93. package/dist/core/mods/agent-stations.js +8 -6
  94. package/dist/core/mods/extension-call.d.ts +4 -0
  95. package/dist/core/mods/extension-call.js +8 -0
  96. package/dist/core/mods/tool-call.js +3 -4
  97. package/dist/core/parent-spec-seat.d.ts +2 -2
  98. package/dist/core/peer-channel.d.ts +5 -0
  99. package/dist/core/permission-rule-consent.d.ts +64 -22
  100. package/dist/core/permission-rule-consent.js +106 -58
  101. package/dist/core/permission-rule-store.d.ts +56 -21
  102. package/dist/core/permission-rule-store.js +2 -0
  103. package/dist/core/refusal-echo.d.ts +20 -0
  104. package/dist/core/refusal-echo.js +33 -0
  105. package/dist/core/retention.d.ts +175 -10
  106. package/dist/core/retention.js +44 -0
  107. package/dist/core/retired-keys.d.ts +5 -0
  108. package/dist/core/retired-keys.js +3 -0
  109. package/dist/core/rule-offer-read.d.ts +0 -4
  110. package/dist/core/rule-offer-read.js +2 -18
  111. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  112. package/dist/core/runner/classifier-ladder.js +4 -2
  113. package/dist/core/runner/compact-session.js +10 -7
  114. package/dist/core/runner/compaction-call-options.d.ts +7 -7
  115. package/dist/core/runner/compaction-call-options.js +3 -2
  116. package/dist/core/runner/contracts.d.ts +28 -9
  117. package/dist/core/runner/delegation-owner.d.ts +2 -3
  118. package/dist/core/runner/delegation-owner.js +2 -1
  119. package/dist/core/runner/gate-exit.d.ts +6 -0
  120. package/dist/core/runner/gate-exit.js +11 -2
  121. package/dist/core/runner/memory-consolidation-driver.d.ts +4 -2
  122. package/dist/core/runner/memory-consolidation-driver.js +8 -5
  123. package/dist/core/runner/prepare-ask-lane.js +3 -3
  124. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -1
  125. package/dist/core/runner/prepare-caps-and-workflow.js +2 -2
  126. package/dist/core/runner/prepare-config-doors.js +4 -0
  127. package/dist/core/runner/prepare-delegation-surface.d.ts +3 -0
  128. package/dist/core/runner/prepare-delegation-surface.js +2 -2
  129. package/dist/core/runner/prepare-gate-stations.d.ts +8 -0
  130. package/dist/core/runner/prepare-gate-stations.js +15 -7
  131. package/dist/core/runner/prepare-hands-readface.js +1 -1
  132. package/dist/core/runner/prepare-inherited-gate.d.ts +3 -1
  133. package/dist/core/runner/prepare-inherited-gate.js +4 -2
  134. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  135. package/dist/core/runner/prepare-memory.d.ts +4 -0
  136. package/dist/core/runner/prepare-memory.js +22 -28
  137. package/dist/core/runner/prepare-policy-chain.js +18 -10
  138. package/dist/core/runner/prepare-prompt-inputs.js +1 -1
  139. package/dist/core/runner/prepare-task.d.ts +5 -1
  140. package/dist/core/runner/prepare-task.js +16 -11
  141. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -1
  142. package/dist/core/runner/prepare-wiring-manifest.js +3 -2
  143. package/dist/core/runner/resume-admission.d.ts +2 -2
  144. package/dist/core/runner/resume-admission.js +2 -23
  145. package/dist/core/runner/role-resolution-table.d.ts +98 -0
  146. package/dist/core/runner/role-resolution-table.js +62 -0
  147. package/dist/core/runner/run-compaction-machinery.js +2 -2
  148. package/dist/core/runner/run-identity-wiring.js +12 -9
  149. package/dist/core/runner/run-leg.js +8 -4
  150. package/dist/core/runner/run-notification-lane.js +23 -23
  151. package/dist/core/runner/run-recovery-lanes.js +3 -3
  152. package/dist/core/runner/run-terminal-adoption.js +1 -1
  153. package/dist/core/runner/run-turn-boundary.js +14 -15
  154. package/dist/core/runner/runtask.js +1 -1
  155. package/dist/core/runner/sub-agent-deny-lists.d.ts +19 -0
  156. package/dist/core/runner/sub-agent-deny-lists.js +25 -0
  157. package/dist/core/runner/tool-occurrence.d.ts +4 -2
  158. package/dist/core/runner/tool-occurrence.js +2 -2
  159. package/dist/core/runner-deps.d.ts +1 -1
  160. package/dist/core/secret-env.d.ts +2 -2
  161. package/dist/core/secret-env.js +6 -20
  162. package/dist/core/session-checkout.d.ts +63 -3
  163. package/dist/core/session-checkout.js +152 -58
  164. package/dist/core/session-store.d.ts +6 -6
  165. package/dist/core/session-store.js +3 -3
  166. package/dist/core/shell-read-silence.js +8 -0
  167. package/dist/core/store-contracts/background-agent-store-contract.js +13 -0
  168. package/dist/core/store-contracts/peer-directory-contract.js +8 -1
  169. package/dist/core/task-event.d.ts +9 -5
  170. package/dist/core/task-notification.d.ts +137 -31
  171. package/dist/core/task-notification.js +198 -100
  172. package/dist/core/task-registry-agent.d.ts +11 -0
  173. package/dist/core/task-registry-agent.js +12 -3
  174. package/dist/core/task-registry-shared.d.ts +11 -0
  175. package/dist/core/task-registry.d.ts +18 -0
  176. package/dist/core/task-registry.js +27 -8
  177. package/dist/core/task-spec.d.ts +7 -2
  178. package/dist/core/tool-errors.d.ts +17 -9
  179. package/dist/core/tool-errors.js +1 -1
  180. package/dist/core/tool-policy.d.ts +18 -1
  181. package/dist/core/tool-policy.js +16 -7
  182. package/dist/core/tool-result-store.d.ts +20 -0
  183. package/dist/core/tool-spec.d.ts +10 -6
  184. package/dist/core/trace.d.ts +3 -2
  185. package/dist/core/workflow-journal-store.d.ts +11 -0
  186. package/dist/core/workflow-journal-store.js +7 -0
  187. package/dist/core/workflow-run-store.d.ts +9 -0
  188. package/dist/core/workflow-run-store.js +6 -0
  189. package/dist/core/write-protect.d.ts +16 -0
  190. package/dist/core/write-protect.js +10 -0
  191. package/dist/engine/compaction/compaction.d.ts +2 -1
  192. package/dist/engine/harness/types.d.ts +1 -0
  193. package/dist/engine/session/repo-utils.d.ts +14 -4
  194. package/dist/engine/session/repo-utils.js +5 -4
  195. package/dist/engine/session/session.d.ts +7 -1
  196. package/dist/engine/session/session.js +5 -2
  197. package/dist/index.d.ts +13 -11
  198. package/dist/index.js +13 -11
  199. package/dist/orchestration/run-workflow-tool.d.ts +4 -0
  200. package/dist/orchestration/run-workflow-tool.js +7 -0
  201. package/dist/orchestration/workflow-types.d.ts +2 -1
  202. package/dist/orchestration/workflow.d.ts +3 -0
  203. package/dist/orchestration/workflow.js +2 -1
  204. package/dist/prompts/default.d.ts +1 -2
  205. package/dist/scenarios/full-body.d.ts +1 -1
  206. package/dist/stores/file/adoption/adopt.d.ts +1 -1
  207. package/dist/stores/file/checkpoint-store.d.ts +6 -0
  208. package/dist/stores/file/checkpoint-store.js +4 -1
  209. package/dist/stores/file/file-history-store.d.ts +13 -0
  210. package/dist/stores/file/file-history-store.js +75 -13
  211. package/dist/stores/file/index.d.ts +12 -16
  212. package/dist/stores/file/index.js +7 -25
  213. package/dist/stores/file/permission-rule-store.d.ts +34 -0
  214. package/dist/stores/file/permission-rule-store.js +104 -9
  215. package/dist/stores/file/session-store.js +1 -1
  216. package/dist/stores/file/tool-result-store.d.ts +14 -0
  217. package/dist/stores/file/tool-result-store.js +39 -2
  218. package/dist/stores/file/workflow-journal-store.d.ts +4 -0
  219. package/dist/stores/file/workflow-journal-store.js +17 -0
  220. package/dist/stores/file/workflow-run-store.d.ts +3 -0
  221. package/dist/stores/file/workflow-run-store.js +15 -0
  222. package/dist/tools/fs/read-deny.d.ts +15 -2
  223. package/dist/tools/fs/read-deny.js +10 -2
  224. package/dist/tools/fs/shell-read-check.d.ts +8 -2
  225. package/dist/tools/fs/shell-read-check.js +7 -7
  226. package/package.json +2 -2
  227. package/test/export-surface.snapshot.json +71 -73
  228. package/wire-changes/core-stores-sql@7.64.0.json +30 -0
  229. package/wire-changes/core-stores-sql@7.65.0.json +30 -0
  230. package/wire-changes/core@7.64.0.json +2653 -0
  231. package/wire-changes/core@7.65.0.json +1650 -0
  232. package/wire-changes/mods-kernel@7.64.0.json +30 -0
  233. package/wire-changes/mods-kernel@7.65.0.json +30 -0
  234. package/wire-changes/primitives@7.64.0.json +30 -0
  235. package/wire-changes/primitives@7.65.0.json +337 -0
  236. package/dist/core/memory-recall.d.ts +0 -208
  237. package/dist/core/memory-recall.js +0 -136
  238. package/dist/stores/file/memory-store.d.ts +0 -124
  239. package/dist/stores/file/memory-store.js +0 -353
@@ -93,6 +93,7 @@ export function createCcPeerDirectory(opts) {
93
93
  const raw = {
94
94
  schemaVersion: PEER_SESSION_RECORD_SCHEMA_VERSION,
95
95
  sessionId: r["sessionId"],
96
+ occupant: r["occupant"] === undefined ? null : r["occupant"],
96
97
  scope,
97
98
  name,
98
99
  pid,
@@ -97,6 +97,10 @@ export interface CcRegistrationFacts {
97
97
  /** The identity of the mailbox store this session drains (`MailboxStore.identity`). Absent = the store cannot
98
98
  * say, and the row then carries no capability bit: every sender reaches this session over its socket. */
99
99
  storeIdentity?: string;
100
+ /** The occupant of this session's row (`PeerChannelSelf.occupant`; `null` = no token). Carried in the row as this engine's own
101
+ * member (`occupant` — the reference agent ignores members it does not know), so a sender of this engine that reaches the
102
+ * session through its box stamps what it parks for that occupant. */
103
+ occupant: string | null;
100
104
  }
101
105
  /** The registration row this engine writes into the reference agent's registry (`<pid>.json`): the
102
106
  * reference's field names, the protocol word, and the capability broadcast — `peerFeatures` carries the one
@@ -94,5 +94,6 @@ export function ccRegistrationRow(facts) {
94
94
  messagingSocketPath: facts.socketPath,
95
95
  ...(facts.name !== undefined ? { name: facts.name } : {}),
96
96
  updatedAt: facts.updatedAt,
97
+ occupant: facts.occupant,
97
98
  };
98
99
  }
@@ -193,6 +193,9 @@ export function createCcUdsPeerChannel(opts) {
193
193
  throw new CcPeerChannelError("unsupported_platform", "the reference agent's socket lane (its named-pipe arm) is not implemented on this platform — the socket lane was not opened");
194
194
  if (listening !== undefined)
195
195
  throw new CcPeerChannelError("already_listening", `this channel already listens at ${listening.address}`);
196
+ if (self.occupant !== null && (typeof self.occupant !== "string" || self.occupant === "")) {
197
+ throw new TypeError("PeerChannel.listen: self.occupant must be the session row's occupant (its SessionMetadata.incarnation, a non-empty string) or null when the row carries no token");
198
+ }
196
199
  const socketPath = opts.socketPath;
197
200
  if (!isAbsolute(socketPath) || Buffer.byteLength(socketPath) > CC_PEER_SOCKET_PATH_MAX_BYTES) {
198
201
  throw new CcPeerChannelError("socket_path_too_long", `the socket path must be absolute and at most ${CC_PEER_SOCKET_PATH_MAX_BYTES} bytes (got ${Buffer.byteLength(socketPath)})`, socketPath);
@@ -257,6 +260,7 @@ export function createCcUdsPeerChannel(opts) {
257
260
  ...(fields.fromSession !== undefined ? { fromSession: fields.fromSession, senderKey: peerAxisToken(self.scope, "s", fields.fromSession) } : {}),
258
261
  ...(fields.fromMode !== undefined ? { fromMode: fields.fromMode } : {}),
259
262
  kind: "peer_message",
263
+ ...(self.occupant !== null ? { occupant: self.occupant } : {}),
260
264
  };
261
265
  const from = fields.fromName ?? line.from;
262
266
  const seq = await opts.mailbox.append(self.scope, box, { ...(from !== undefined ? { from } : {}), content: body, sentAt: now(), hopChain: fields.hopChain !== undefined ? [...fields.hopChain] : [], peerMeta });
@@ -402,6 +406,7 @@ export function createCcUdsPeerChannel(opts) {
402
406
  ...(reg.entrypoint !== undefined ? { entrypoint: reg.entrypoint } : {}),
403
407
  ...(procStart !== undefined ? { procStart } : {}),
404
408
  ...(typeof opts.mailbox.identity === "string" && opts.mailbox.identity !== "" ? { storeIdentity: opts.mailbox.identity } : {}),
409
+ occupant: self.occupant,
405
410
  })));
406
411
  }
407
412
  catch (e) {
@@ -69,10 +69,12 @@ export declare function principalInboundLayers(layers: CrossSessionInboundSettin
69
69
  * loudly rather than fold into "no class asserted" (which would DELIVER to a prompting recipient).
70
70
  * `cross-principal-default` is the other sema-only arm (CC has no cross-principal lane): a record that
71
71
  * carries the delivery gate's trust anchor (`fromScope`) and meets no explicit setting is held — the
72
- * principal arm has no mode parity to fall back on.
72
+ * principal arm has no mode parity to fall back on. It is a policy hold that no one is asked to answer:
73
+ * which causes a person can answer is `PEER_HELD_REVIEW_CAUSES` alone, and each cause's sentence below agrees with it.
73
74
  */
74
75
  export type CrossSessionHoldCause = "mode-mismatch" | "no-mode-asserted" | "explicit-setting" | "managed-setting" | "repo-setting" | "invalid-setting" | "bypass-default" | "mode-unknown" | "invalid-mode-attestation" | "cross-principal-default";
75
76
  export declare const CROSS_SESSION_HOLD_CAUSES: readonly CrossSessionHoldCause[];
77
+ export declare function isCrossSessionHoldCause(value: unknown): value is CrossSessionHoldCause;
76
78
  /** The reference's wording for the eight inherited causes; the sema arm has its own sentence. */
77
79
  export declare function describeCrossSessionHoldCause(cause: CrossSessionHoldCause): string;
78
80
  export type CrossSessionInboundVerdict = {
@@ -67,6 +67,9 @@ export const CROSS_SESSION_HOLD_CAUSES = Object.freeze([
67
67
  "invalid-mode-attestation",
68
68
  "cross-principal-default",
69
69
  ]);
70
+ export function isCrossSessionHoldCause(value) {
71
+ return typeof value === "string" && CROSS_SESSION_HOLD_CAUSES.includes(value);
72
+ }
70
73
  export function describeCrossSessionHoldCause(cause) {
71
74
  switch (cause) {
72
75
  case "mode-mismatch":
@@ -88,7 +91,7 @@ export function describeCrossSessionHoldCause(cause) {
88
91
  case "invalid-mode-attestation":
89
92
  return "The sender attested an unrecognized permission mode, so the message is held for your review.";
90
93
  case "cross-principal-default":
91
- return `The message came from another user through your organization's delivery gate, and "crossSessionInbound" is not set, so it is held for your review.`;
94
+ return `The message came from another user through your organization's delivery gate, and "crossSessionInbound" is not set, so it is held until that setting says how to treat it (it is not put up for review and has no expiry deadline).`;
92
95
  default: {
93
96
  const _exhaustive = cause;
94
97
  void _exhaustive;
@@ -40,6 +40,14 @@ export interface PeerSessionRecord {
40
40
  schemaVersion: number;
41
41
  /** The session's durable identity: its box address is `session.<sessionId>` ({@link peerSessionBoxHandle}). */
42
42
  sessionId: string;
43
+ /**
44
+ * The occupant of the session's row — its `SessionMetadata.incarnation`, as the session store holds it — or `null` when the row
45
+ * carries no token (a store that mints none). REQUIRED, `null` included: a sender stamps it on what it parks in the session's box
46
+ * (`MailboxPeerMeta.occupant`), and the session's drain hands a record only to the occupant it names, so a row that omitted it
47
+ * would have every message to a token-holding session discarded unseen; a row without the member is refused by the reader
48
+ * (`field_invalid: occupant`). An addressing fact, never rendered by a listing and never a credential.
49
+ */
50
+ occupant: string | null;
43
51
  /** sema axis — the principal scope the row belongs to. A reader filters by the ACCESSOR's scope
44
52
  * before anything else (the mechanical seat of the cross-principal wall). */
45
53
  scope: string;
@@ -78,6 +78,9 @@ export function readPeerSessionRecord(raw) {
78
78
  if (liveness !== "live" && liveness !== "dead" && liveness !== "deleted")
79
79
  return { ok: false, reason: "liveness_invalid" };
80
80
  const bad = (field) => ({ ok: false, reason: "field_invalid", field });
81
+ const occupant = r["occupant"];
82
+ if (occupant !== null && (typeof occupant !== "string" || occupant === ""))
83
+ return bad("occupant");
81
84
  if (!optNumber(r["startedAt"]) || r["startedAt"] === undefined)
82
85
  return bad("startedAt");
83
86
  if (!optNumber(r["updatedAt"]) || r["updatedAt"] === undefined)
@@ -124,6 +127,7 @@ export function readPeerSessionRecord(raw) {
124
127
  const record = {
125
128
  schemaVersion: r["schemaVersion"],
126
129
  sessionId: r["sessionId"],
130
+ occupant,
127
131
  scope: r["scope"],
128
132
  name: r["name"],
129
133
  ...(nameSource !== undefined ? { nameSource } : {}),
@@ -86,7 +86,7 @@ export interface PeerHeldQueueConfig {
86
86
  * lease-holding pass delivers it. */
87
87
  export type PeerHeldSettleOutcome = "gone" | "delivered" | "released_pending" | "dropped" | "dropped_by_policy" | "denied" | "expired" | "decided_elsewhere";
88
88
  /** What {@link PeerHeldQueue.hold} did with a record the judgment holds: `held` — this call held it
89
- * (card + `held` receipt); `adopted` — it was already held (or deliverable) and this queue now shows it
89
+ * (card + hold receipt, `held` / `held_by_policy` by its cause); `adopted` — it was already held (or deliverable) and this queue now shows it
90
90
  * without a receipt; `uncarded` — held, but this queue is full and no card it carries can be settled to
91
91
  * make room (none would tell its sender); a final word — another consumer settled it; `gone` —
92
92
  * no such record any more; `fault` — the store refused the move (reported through `onFault`). */
@@ -102,7 +102,7 @@ export interface PeerHeldQueue {
102
102
  configured(): boolean;
103
103
  /**
104
104
  * Hold a record (CC `v` hold arm). `decision` is the record's decision in the snapshot the caller judged:
105
- * absent ⇒ the move absent → `held` is taken (its winner sends the `held` receipt); `held` / `approved` ⇒
105
+ * absent ⇒ the move absent → `held` is taken (its winner sends the hold receipt its cause reads as); `held` / `approved` ⇒
106
106
  * the record is already held elsewhere and this queue only shows it (an approved card is not announced).
107
107
  * At the cap, settles the oldest held card that tells its sender (it is then a decision); arms the
108
108
  * deadline for a hold cause a person could answer.
@@ -147,11 +147,17 @@ export declare function createPeerHeldQueue(key: string, opts?: {
147
147
  * entries by seq, and seqs are minted per box, so one queue never mixes two boxes. */
148
148
  export declare function peerHeldQueueKey(scope: string, sessionId: string, box?: string): string;
149
149
  /** The held queue of a session (created on first use) — of its own box, or of `box` (the principal inbox it
150
- * also drains). `clock` is honored only at creation. */
150
+ * also drains). `clock` is honored only at creation. `occupant` = the occupant of the session the queue is opened for
151
+ * (`SessionMetadata.incarnation`; absent = the store mints no token): a queue the registry holds for ANOTHER occupant of the id
152
+ * (`sameOccupant` judges, as everywhere) is replaced, and the old one stops in the crash form — its cards leave this process
153
+ * with nothing decided and nothing sent, and the records they showed stay in the box, where the new occupant's drain discards
154
+ * every one addressed to an earlier occupant. So the approval face of a session never shows an earlier occupant's cards, and no
155
+ * deadline of theirs settles a record under this one. */
151
156
  export declare function peerHeldQueueFor(scope: string, sessionId: string, opts?: {
152
157
  cap?: number;
153
158
  clock?: PeerClock;
154
159
  box?: string;
160
+ occupant?: string;
155
161
  }): PeerHeldQueue;
156
162
  /** The held queue of a session if one exists in this process (a host review face reads through this
157
163
  * without creating state for sessions that never held anything); `box` as in {@link peerHeldQueueFor}. */
@@ -1,5 +1,6 @@
1
1
  import { isMailboxDecisionDeliverable, isMailboxDecisionFinal } from "../core/mailbox-store.js";
2
- import { PEER_HELD_QUEUE_CAP, PEER_HELD_REVIEW_CAUSES } from "./peer-notices.js";
2
+ import { sameOccupant } from "../engine/session/repo-utils.js";
3
+ import { PEER_HELD_QUEUE_CAP, PEER_HELD_REVIEW_CAUSES, peerHeldReceiptStateOf } from "./peer-notices.js";
3
4
  import { peerSessionBoxHandle } from "./peer-directory.js";
4
5
  export const realPeerClock = {
5
6
  now: () => Date.now(),
@@ -316,7 +317,7 @@ export function createPeerHeldQueue(key, opts = {}) {
316
317
  return fresh ? "held" : "adopted";
317
318
  if (!(await makeRoom())) {
318
319
  if (fresh)
319
- void sendReceipt(sink, { ...input, heldAt: clock.now(), decision: state }, "held");
320
+ void sendReceipt(sink, { ...input, heldAt: clock.now(), decision: state }, peerHeldReceiptStateOf(input.cause));
320
321
  return "uncarded";
321
322
  }
322
323
  const entry = { ...input, heldAt: clock.now(), decision: state };
@@ -325,7 +326,7 @@ export function createPeerHeldQueue(key, opts = {}) {
325
326
  if (state === "held")
326
327
  safe(() => sink.onHeld?.(entry, entries.length, entry.cause, false));
327
328
  if (fresh)
328
- void sendReceipt(sink, entry, "held");
329
+ void sendReceipt(sink, entry, peerHeldReceiptStateOf(entry.cause));
329
330
  return fresh ? "held" : "adopted";
330
331
  },
331
332
  rejudge,
@@ -432,12 +433,14 @@ export function peerHeldQueueKey(scope, sessionId, box) {
432
433
  }
433
434
  export function peerHeldQueueFor(scope, sessionId, opts = {}) {
434
435
  const seat = peerHeldQueueSeat(scope, sessionId, opts.box);
435
- let row = heldQueues.get(seat.key);
436
- if (row === undefined) {
437
- row = { seat, queue: createPeerHeldQueue(seat.key, opts) };
438
- heldQueues.set(seat.key, row);
439
- }
440
- return row.queue;
436
+ const row = heldQueues.get(seat.key);
437
+ if (row !== undefined && sameOccupant(row.occupant, opts.occupant))
438
+ return row.queue;
439
+ if (row !== undefined)
440
+ crashHandlers.get(row.queue)?.();
441
+ const queue = createPeerHeldQueue(seat.key, opts);
442
+ heldQueues.set(seat.key, { seat, occupant: opts.occupant, queue });
443
+ return queue;
441
444
  }
442
445
  export function peerHeldQueueIfAny(scope, sessionId, box) {
443
446
  return heldQueues.get(peerHeldQueueKey(scope, sessionId, box))?.queue;
@@ -5,6 +5,9 @@ import { type PeerClock } from "./peer-held-queue.js";
5
5
  export interface PeerIdleSubscriber {
6
6
  /** The requester's session id (reply routing). */
7
7
  readonly requester: string;
8
+ /** The occupant the requester's record named as its own (`MailboxPeerMeta.fromOccupant`): the notice is stamped for it, so a
9
+ * later occupant of the requester's id never reads it. Absent = the record stated none. */
10
+ readonly requesterOccupant?: string;
8
11
  /** The requester's display name as its record carried it (display only). */
9
12
  readonly requesterName?: string;
10
13
  /** The requester's self-attested mode class (gates the detail line through the parity judge). */
@@ -100,10 +103,26 @@ export interface PeerIdleMachine {
100
103
  readonly requester: PeerIdleRequester;
101
104
  }
102
105
  export declare function peerIdleMachineKey(scope: string, sessionId: string): string;
103
- /** The idle machine of a session (created on first use; `clock` honored at creation). */
106
+ /**
107
+ * The idle machine of a session's ADDRESS — the session id and its occupant (created on first use; `clock` honored at creation),
108
+ * as the session's admission takes it (a leg's drain mount). The registry keeps one machine per id: a machine opened for another
109
+ * occupant of the id (`sameOccupant` judges, as everywhere) is replaced, and the old one stops as on a process crash — the subscriptions of an earlier occupant are never told this one's
110
+ * idle (nor shown its last turn), and its own asks never answer this one. `occupant` absent = the store mints no token.
111
+ */
104
112
  export declare function peerIdleMachineFor(scope: string, sessionId: string, opts?: {
105
113
  clock?: PeerClock;
114
+ occupant?: string;
106
115
  }): PeerIdleMachine;
116
+ /**
117
+ * The idle machine of this address for a caller that is NOT the session's admission — a tool call of a running leg: the seat
118
+ * when it is this occupant's, opened when the id has none, and `undefined` when another occupant of the id holds it. A seat is
119
+ * replaced only where a leg is admitted as the session's occupant (its drain mount, {@link peerIdleMachineFor}); a leg whose
120
+ * session was deleted and created again after it was admitted is no longer the session's, and its calls never take the seat
121
+ * from the leg admitted after it.
122
+ */
123
+ export declare function peerIdleMachineOfOwnAddress(scope: string, sessionId: string, opts?: {
124
+ occupant?: string;
125
+ }): PeerIdleMachine | undefined;
107
126
  export declare function peerIdleMachineIfAny(scope: string, sessionId: string): PeerIdleMachine | undefined;
108
127
  /** Test seam: forget every machine (timers are NOT settled — the crash form). Never called by production code. */
109
128
  export declare function resetPeerIdleMachinesForTests(): void;
@@ -1,3 +1,4 @@
1
+ import { sameOccupant } from "../engine/session/repo-utils.js";
1
2
  import { PEER_IDLE_FIRE_DEBOUNCE_MS, PEER_IDLE_HELD_BACKOFF_MS, PEER_IDLE_OUTSTANDING_CAP, PEER_IDLE_PRIORS_KEPT, PEER_IDLE_SUBSCRIBER_TABLE_CAP, PEER_IDLE_SUBSCRIPTION_TTL_MS } from "./peer-notices.js";
2
3
  import { realPeerClock } from "./peer-held-queue.js";
3
4
  import { peerSessionBoxHandle } from "./peer-directory.js";
@@ -218,23 +219,33 @@ const machines = new Map();
218
219
  export function peerIdleMachineKey(scope, sessionId) {
219
220
  return JSON.stringify([scope, peerSessionBoxHandle(sessionId)]);
220
221
  }
222
+ function crashIdleMachine(m) {
223
+ m.target.busy();
224
+ for (const o of m.requester.list())
225
+ m.requester.settle(o.target, "idle");
226
+ }
221
227
  export function peerIdleMachineFor(scope, sessionId, opts = {}) {
222
228
  const key = peerIdleMachineKey(scope, sessionId);
223
- let m = machines.get(key);
224
- if (m === undefined) {
225
- m = { key, target: createPeerIdleTarget(opts), requester: createPeerIdleRequester(opts) };
226
- machines.set(key, m);
227
- }
228
- return m;
229
+ const seat = machines.get(key);
230
+ if (seat !== undefined && sameOccupant(seat.occupant, opts.occupant))
231
+ return seat.machine;
232
+ if (seat !== undefined)
233
+ crashIdleMachine(seat.machine);
234
+ const machine = { key, target: createPeerIdleTarget(opts), requester: createPeerIdleRequester(opts) };
235
+ machines.set(key, { occupant: opts.occupant, machine });
236
+ return machine;
237
+ }
238
+ export function peerIdleMachineOfOwnAddress(scope, sessionId, opts = {}) {
239
+ const seat = machines.get(peerIdleMachineKey(scope, sessionId));
240
+ if (seat === undefined)
241
+ return peerIdleMachineFor(scope, sessionId, opts);
242
+ return sameOccupant(seat.occupant, opts.occupant) ? seat.machine : undefined;
229
243
  }
230
244
  export function peerIdleMachineIfAny(scope, sessionId) {
231
- return machines.get(peerIdleMachineKey(scope, sessionId));
245
+ return machines.get(peerIdleMachineKey(scope, sessionId))?.machine;
232
246
  }
233
247
  export function resetPeerIdleMachinesForTests() {
234
- for (const m of machines.values()) {
235
- m.target.busy();
236
- for (const o of m.requester.list())
237
- m.requester.settle(o.target, "idle");
238
- }
248
+ for (const seat of machines.values())
249
+ crashIdleMachine(seat.machine);
239
250
  machines.clear();
240
251
  }
@@ -5,10 +5,12 @@ export interface PeerNoticeRoute {
5
5
  mailbox: MailboxStore;
6
6
  scope: string;
7
7
  /** The notice's author: this session (the recipient of a held message / the target of a subscription /
8
- * the requester answering itself). `name` = its directory row's display name when known. */
8
+ * the requester answering itself). `name` = its directory row's display name when known; `occupant` = the occupant this
9
+ * session's run holds (`SessionMetadata.incarnation`), stamped as the notice's `fromOccupant`; absent = no token. */
9
10
  self: {
10
11
  sessionId: string;
11
12
  name?: string;
13
+ occupant?: string;
12
14
  modeClass?: () => PermissionModeClass | "unknown";
13
15
  };
14
16
  onError?: (error: unknown, ctx: {
@@ -18,14 +20,23 @@ export interface PeerNoticeRoute {
18
20
  }) => void;
19
21
  now?: () => number;
20
22
  }
23
+ /**
24
+ * WHO a notice is for: the addressee session and the occupant the notice answers — the `fromOccupant` of the record it is about,
25
+ * or of the subscription it fulfils; `undefined` = that record stated none. Stamped as the notice record's `occupant`, so the
26
+ * addressee's drain hands it only to that occupant (a notice for an earlier occupant of the id is discarded there).
27
+ */
28
+ export interface PeerNoticeAddressee {
29
+ readonly sessionId: string;
30
+ readonly occupant: string | undefined;
31
+ }
21
32
  /** A delivery RECEIPT to the sender of one message this session judged (held / expired / delivered /
22
33
  * refused / denied). `refSeq` = the seq of the sender's message in THIS session's box. */
23
- export declare function routePeerDeliveryReceipt(route: PeerNoticeRoute, toSession: string, state: Exclude<PeerDeliveryReceiptState, "dropped">, refSeq: number, detail?: string): Promise<boolean>;
34
+ export declare function routePeerDeliveryReceipt(route: PeerNoticeRoute, to: PeerNoticeAddressee, state: Exclude<PeerDeliveryReceiptState, "dropped">, refSeq: number, detail?: string): Promise<boolean>;
24
35
  /** A `dropped` receipt (the ingress guard's arm). */
25
- export declare function routePeerDroppedReceipt(route: PeerNoticeRoute, toSession: string, refSeq: number, dropReason?: PeerDropReason): Promise<boolean>;
36
+ export declare function routePeerDroppedReceipt(route: PeerNoticeRoute, to: PeerNoticeAddressee, refSeq: number, dropReason?: PeerDropReason): Promise<boolean>;
26
37
  /** An idle NOTICE to a requester (`idle` / `exited` / `unavailable` from the target; `expired` from the
27
- * requester's own timer — then `toSession` is the requester itself and the record is self-sent). */
28
- export declare function routePeerIdleNotice(route: PeerNoticeRoute, toSession: string, notice: {
38
+ * requester's own timer — then `to` is the requester itself and the record is self-sent). */
39
+ export declare function routePeerIdleNotice(route: PeerNoticeRoute, to: PeerNoticeAddressee, notice: {
29
40
  kind: PeerIdleNoticeKind;
30
41
  finishedAt?: number;
31
42
  detail?: string;
@@ -1,18 +1,20 @@
1
1
  import { MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../core/mailbox-store.js";
2
2
  import { peerSessionBoxHandle } from "./peer-directory.js";
3
3
  import { peerIdleNoticeLabel, renderCrossSessionDeliveryNotice, renderCrossSessionDroppedNotice, renderCrossSessionIdleNotice } from "./peer-notices.js";
4
- function noticeMeta(route, kind, notice) {
4
+ function noticeMeta(route, to, kind, notice) {
5
5
  const modeClass = route.self.modeClass?.();
6
6
  return {
7
7
  fromSession: route.self.sessionId,
8
+ ...(route.self.occupant !== undefined ? { fromOccupant: route.self.occupant } : {}),
8
9
  ...(modeClass === "bypass" || modeClass === "prompting" ? { fromMode: modeClass } : {}),
9
10
  kind,
10
11
  notice,
12
+ ...(to.occupant !== undefined ? { occupant: to.occupant } : {}),
11
13
  };
12
14
  }
13
- async function appendNotice(route, toSession, content, peerMeta, classification) {
15
+ async function appendNotice(route, to, content, peerMeta, classification) {
14
16
  try {
15
- await route.mailbox.append(route.scope, peerSessionBoxHandle(toSession), {
17
+ await route.mailbox.append(route.scope, peerSessionBoxHandle(to.sessionId), {
16
18
  from: route.self.name ?? peerSessionBoxHandle(route.self.sessionId),
17
19
  content,
18
20
  sentAt: (route.now ?? Date.now)(),
@@ -28,20 +30,20 @@ async function appendNotice(route, toSession, content, peerMeta, classification)
28
30
  return false;
29
31
  }
30
32
  }
31
- export function routePeerDeliveryReceipt(route, toSession, state, refSeq, detail) {
33
+ export function routePeerDeliveryReceipt(route, to, state, refSeq, detail) {
32
34
  const recipient = route.self.name ?? peerSessionBoxHandle(route.self.sessionId);
33
35
  const said = state === "refused" && detail !== undefined ? peerIdleNoticeLabel(detail) : undefined;
34
36
  const notice = { state, refSeq, recipient, ...(said !== undefined ? { detail: said } : {}) };
35
- return appendNotice(route, toSession, renderCrossSessionDeliveryNotice(state, 1, [recipient], said), noticeMeta(route, "delivery_notice", notice), "peer-receipt-route");
37
+ return appendNotice(route, to, renderCrossSessionDeliveryNotice(state, 1, [recipient], said), noticeMeta(route, to, "delivery_notice", notice), "peer-receipt-route");
36
38
  }
37
- export function routePeerDroppedReceipt(route, toSession, refSeq, dropReason) {
39
+ export function routePeerDroppedReceipt(route, to, refSeq, dropReason) {
38
40
  const recipient = route.self.name ?? peerSessionBoxHandle(route.self.sessionId);
39
41
  const notice = { state: "dropped", refSeq, recipient, ...(dropReason !== undefined ? { dropReason } : {}) };
40
- return appendNotice(route, toSession, renderCrossSessionDroppedNotice(1, [recipient], [dropReason]), noticeMeta(route, "delivery_notice", notice), "peer-receipt-route");
42
+ return appendNotice(route, to, renderCrossSessionDroppedNotice(1, [recipient], [dropReason]), noticeMeta(route, to, "delivery_notice", notice), "peer-receipt-route");
41
43
  }
42
- export function routePeerIdleNotice(route, toSession, notice) {
44
+ export function routePeerIdleNotice(route, to, notice) {
43
45
  const detail = notice.detail !== undefined ? peerIdleNoticeLabel(notice.detail) : undefined;
44
46
  const label = notice.label ?? peerIdleNoticeLabel(route.self.name ?? peerSessionBoxHandle(route.self.sessionId)) ?? peerSessionBoxHandle(route.self.sessionId);
45
47
  const meta = { state: notice.kind, ...(notice.finishedAt !== undefined ? { finishedAt: notice.finishedAt } : {}), ...(detail !== undefined ? { detail } : {}), ...(notice.kind === "expired" ? { target: label } : {}) };
46
- return appendNotice(route, toSession, renderCrossSessionIdleNotice({ kind: notice.kind, label, ...(notice.finishedAt !== undefined ? { finishedAt: notice.finishedAt } : {}), ...(detail !== undefined ? { detail } : {}) }), noticeMeta(route, "idle_notice", meta), "peer-idle-route");
48
+ return appendNotice(route, to, renderCrossSessionIdleNotice({ kind: notice.kind, label, ...(notice.finishedAt !== undefined ? { finishedAt: notice.finishedAt } : {}), ...(detail !== undefined ? { detail } : {}) }), noticeMeta(route, to, "idle_notice", meta), "peer-idle-route");
47
49
  }
@@ -36,14 +36,30 @@ export interface ResolvedCrossSessionDialogExpiry {
36
36
  /** Resolve a `dialogExpiry` value. `undefined`/`null`/`"default"` ⇒ the default (not invalid); a member
37
37
  * ⇒ itself; anything else ⇒ the default WITH `invalid: true` so the caller can announce it. */
38
38
  export declare function resolveCrossSessionDialogExpiry(raw: unknown): ResolvedCrossSessionDialogExpiry;
39
- /** The hold causes a human REVIEW can resolve, and therefore the ones the `dialogExpiry` deadline is
40
- * armed for (CC arms its dialog + deadline for exactly `mode-mismatch` / `no-mode-asserted`; the sema
41
- * attestation-garbage arm is a review cause by its own sentence and joins them). Every other cause
42
- * waits for a setting or mode change (CC form: "set it to accept", "once the session finishes
43
- * starting up") and is re-judged at each drain round, never expired by clock. */
39
+ /** The hold causes a human REVIEW can resolve (CC arms its dialog + deadline for exactly `mode-mismatch` /
40
+ * `no-mode-asserted`; the sema attestation-garbage arm is a review cause by its own sentence and joins
41
+ * them). Every other cause is the recipient's own policy holding the message — a setting, or a state
42
+ * such as an undeterminable permission mode — and waits for that to change (CC form: "set it to
43
+ * accept", "once the session finishes starting up"): re-judged at each drain round, no deadline armed
44
+ * for it. This one set answers every question about a hold that turns on "can a person answer it": the
45
+ * `dialogExpiry` deadline is armed only while a card's cause is one of these (a deadline already firing
46
+ * when its re-judgment moves the cause out still ends the card `expired`), the hold receipt its sender
47
+ * gets is read from it ({@link peerHeldReceiptStateOf}), and a host approval face is to present exactly
48
+ * these cards (`PeerHeldQueue.settle` itself does not read the cause). */
44
49
  export declare const PEER_HELD_REVIEW_CAUSES: readonly CrossSessionHoldCause[];
45
- /** The six terminal states a sender can be told about one of its messages (CC receipt states). */
46
- export declare const PEER_DELIVERY_RECEIPT_STATES: readonly ["held", "denied", "expired", "delivered", "refused", "dropped"];
50
+ /**
51
+ * Which hold receipt a held message owes its sender, read from the hold's cause: a cause a person can
52
+ * answer ({@link PEER_HELD_REVIEW_CAUSES}) is `held` — it awaits the recipient user's approval and its deadline
53
+ * runs; any other cause is `held_by_policy` — the recipient's own settings or state hold it, no one there
54
+ * is asked to approve it, and there is no deadline. The receipt is the state at the moment of the hold:
55
+ * a re-judgment that moves the cause re-announces it to the recipient's host, not to the sender.
56
+ */
57
+ export declare function peerHeldReceiptStateOf(cause: CrossSessionHoldCause): Extract<PeerDeliveryReceiptState, "held" | "held_by_policy">;
58
+ /** The states a sender can be told about one of its messages: CC's six receipt states, and
59
+ * `held_by_policy` — a hold no one is asked to approve ({@link peerHeldReceiptStateOf} picks it or
60
+ * `held`). The two hold words are not final: a later receipt follows when the message is delivered,
61
+ * refused, denied, expired or dropped. */
62
+ export declare const PEER_DELIVERY_RECEIPT_STATES: readonly ["held", "denied", "expired", "delivered", "refused", "dropped", "held_by_policy"];
47
63
  export type PeerDeliveryReceiptState = (typeof PEER_DELIVERY_RECEIPT_STATES)[number];
48
64
  export declare function isPeerDeliveryReceiptState(v: unknown): v is PeerDeliveryReceiptState;
49
65
  /**
@@ -62,7 +78,8 @@ export type PeerDropReason = (typeof PEER_DROP_REASONS)[number];
62
78
  /** CC `ule` — the recipient suffix: unique non-empty labels, at most three named. */
63
79
  export declare function peerRecipientSuffix(recipients: readonly string[]): string;
64
80
  /**
65
- * CC `y$e` — the model-face delivery receipt for the five non-drop states. `count` folds several
81
+ * CC `y$e` — the model-face delivery receipt for the non-drop states (`held_by_policy` is sema's: CC
82
+ * renders every hold as awaiting approval, whatever its cause). `count` folds several
66
83
  * receipts of one state into one line (the requester's drain may fold; a single record renders as 1).
67
84
  */
68
85
  export declare function renderCrossSessionDeliveryNotice(state: Exclude<PeerDeliveryReceiptState, "dropped">, count: number, recipients?: readonly string[], detail?: string): string;
@@ -20,7 +20,10 @@ export function resolveCrossSessionDialogExpiry(raw) {
20
20
  return { ms: toMs(CROSS_SESSION_DIALOG_EXPIRY_DEFAULT), value: CROSS_SESSION_DIALOG_EXPIRY_DEFAULT, invalid: true };
21
21
  }
22
22
  export const PEER_HELD_REVIEW_CAUSES = Object.freeze(["mode-mismatch", "no-mode-asserted", "invalid-mode-attestation"]);
23
- export const PEER_DELIVERY_RECEIPT_STATES = Object.freeze(["held", "denied", "expired", "delivered", "refused", "dropped"]);
23
+ export function peerHeldReceiptStateOf(cause) {
24
+ return PEER_HELD_REVIEW_CAUSES.includes(cause) ? "held" : "held_by_policy";
25
+ }
26
+ export const PEER_DELIVERY_RECEIPT_STATES = Object.freeze(["held", "denied", "expired", "delivered", "refused", "dropped", "held_by_policy"]);
24
27
  export function isPeerDeliveryReceiptState(v) {
25
28
  return typeof v === "string" && PEER_DELIVERY_RECEIPT_STATES.includes(v);
26
29
  }
@@ -41,6 +44,8 @@ export function renderCrossSessionDeliveryNotice(state, count, recipients = [],
41
44
  switch (state) {
42
45
  case "held":
43
46
  return `[Cross-session delivery notice] ${P} ${J} held for the recipient user's approval${R}. Not delivered to that session's assistant yet; its user must approve first. Do not wait for a reply; continue, or choose another approach.`;
47
+ case "held_by_policy":
48
+ return `[Cross-session delivery notice] ${P} ${J} held by the recipient session's own settings or state${R}, not for anyone's approval. Not delivered to that session's assistant; no one there is asked to approve it and there is no expiry deadline: it waits for those settings or that state to change. Do not wait for a reply; continue, or choose another approach.`;
44
49
  case "denied":
45
50
  return `[Cross-session delivery notice] ${P} ${J} denied by the recipient user${R}. Not delivered to that session's assistant. Do not wait for a reply; continue, or choose another approach.`;
46
51
  case "expired":
@@ -1,5 +1,6 @@
1
1
  import { type MailboxCrossProcessVerdict, type MailboxStore } from "../core/mailbox-store.js";
2
- import { type FrameReceiver, type SessionBoxBinding, type SystemInjectionPriority, type TaskNotificationPayload } from "../core/task-notification.js";
2
+ import { type FrameReceiver, type SessionAddress, type SessionBoxBinding, type SystemInjectionPriority, type TaskNotificationPayload } from "../core/task-notification.js";
3
+ import type { SessionStore } from "../core/session.js";
3
4
  import { type FrameSettlement } from "../core/frame-settlement.js";
4
5
  import { type EngineNotice, type RunnerDeps } from "../core/types.js";
5
6
  import { type PermissionModeClass } from "./cross-session-envelope.js";
@@ -40,12 +41,14 @@ export type PeerLaneMountVerdict = MailboxCrossProcessVerdict | {
40
41
  * leg's OWN address is judged too: a host-minted session id outside the peer address grammar has no
41
42
  * session box to drain and no address a peer could send to, so the lane refuses by name — the
42
43
  * alternative was `peerSessionBoxHandle` throwing out of prepare and failing the whole run over an
43
- * optional feature.
44
+ * optional feature (`undefined` = no address to judge: the store verdict alone). `sessions` = the Runner's session store: the lane's
45
+ * boxes are session boxes, mounted under the one session-box verdict ({@link sessionBoxMountVerdict} — the store's declaration and
46
+ * the session store's by-id read), the verdict the drain ({@link judgeSessionBoxDrain}) and a direct `SendMessage` mount read too.
44
47
  */
45
48
  export declare function judgePeerLaneMount(deps: {
46
49
  peerDirectory?: PeerDirectory;
47
50
  mailboxStore?: MailboxStore;
48
- }, sessionId?: string): PeerLaneMountVerdict | undefined;
51
+ }, sessionId: string | undefined, sessions: Pick<SessionStore, "headOf"> | undefined): PeerLaneMountVerdict | undefined;
49
52
  /**
50
53
  * May THIS leg drain its own session box, and where is that box? The ONE mount judgment of the
51
54
  * session-box drain, read by two seats: the wiring station binds the drain on it, the notification
@@ -54,12 +57,15 @@ export declare function judgePeerLaneMount(deps: {
54
57
  * discovery faces; the box is also where a child's `SendMessage("main")` waits while its host session
55
58
  * is idle). A DELEGATED CHILD never drains one: its addressable box is its `a*` handle (the tier-3
56
59
  * revival lane), and a drain per child on a box nobody writes would cost a lease claim per turn on
57
- * every background agent. `undefined` on every refusal — silently: no host asked for a box here.
60
+ * every background agent. Nor does a leg whose occupant could not be read (`unread`): its address is nobody's, and a drain
61
+ * would have no occupant to hand a record to. `undefined` on every refusal — silently: no host asked for a box here.
58
62
  */
59
63
  export declare function judgeSessionBoxDrain(deps: Pick<RunnerDeps, "mailboxStore" | "onError" | "sessionBoxEngineFrames">, leg: {
60
64
  sessionId: string;
61
65
  scope: string;
62
66
  isDelegatedChild: boolean;
67
+ unread?: true;
68
+ sessions: Pick<SessionStore, "headOf"> | undefined;
63
69
  }): SessionBoxBinding | undefined;
64
70
  /** What one pull of the box handed back: the records read (already rendered frames), and what is still waiting. */
65
71
  export interface PulledInbox {
@@ -89,6 +95,21 @@ export interface PeerSessionDrainOptions {
89
95
  /** This session (the box owner) and this leg's cycle id (the lease owner). */
90
96
  sessionId: string;
91
97
  runId: string;
98
+ /**
99
+ * The occupant this leg's session holds — its `SessionMetadata.incarnation`, as the leg's acquire read it (absent = the store
100
+ * mints no token). The session box is drained for this ADDRESS: a record is handed to this leg only when `sameOccupant` judges the
101
+ * occupant it names (`MailboxPeerMeta.occupant`) the same; any other is discarded and announced, once this leg has confirmed it
102
+ * still holds the session ({@link sessions}). The receipts and notices this session authors name it as their `fromOccupant`.
103
+ */
104
+ occupant?: string;
105
+ /**
106
+ * The session store's by-id read: before it discards a record addressed to another occupant, the drain reads the session's row
107
+ * once per pass and discards only when the row's occupant is this leg's (the occupant token is minted once per row, so a record
108
+ * for another one is for an earlier occupant). A row of another occupant, no row, a read fault, or no `headOf` at all ⇒ this leg
109
+ * cannot say the record is not for the session's current occupant: it is left exactly as it is — not handed over, not settled,
110
+ * and the ack prefix stops at it. The bound lane always has the read (the session-box mount verdict requires it).
111
+ */
112
+ sessions?: Pick<SessionStore, "headOf">;
92
113
  /** The registry/mailbox scope this run mounts in. */
93
114
  scope: string;
94
115
  /**
@@ -233,13 +254,14 @@ export declare function announcePeerLaneMount(deps: {
233
254
  }, leg: {
234
255
  sessionId: string;
235
256
  runId: string;
257
+ sessions: Pick<SessionStore, "headOf">;
236
258
  }): boolean;
237
259
  /** The SendMessage seats of the lane (design/385 §2): the directory (address arm + last name rung) and
238
260
  * this session's identity/attestation, whose mode class folds LIVE off the manifest's ask derivation. */
239
261
  export declare function peerLaneSendMessageSeats(args: {
240
262
  peerDirectory: PeerDirectory;
241
263
  peerChannel?: PeerChannel;
242
- sessionId: string;
264
+ address: SessionAddress;
243
265
  scope: string;
244
266
  name?: string;
245
267
  refs: PeerLaneRefs;
@@ -314,7 +336,11 @@ export declare function bindPeerSessionDrain(harness: PeerDrainHarness, opts: Pe
314
336
  */
315
337
  export declare function bindPeerLaneDrain(harness: PeerDrainHarness, args: {
316
338
  deps: Pick<RunnerDeps, "mailboxStore" | "peerDirectory" | "peerLane" | "crossSessionInbound" | "crossSessionDialogExpiry" | "principalInboxConsumer" | "onNotice" | "onError">;
317
- sessionId: string;
339
+ /** The leg's own session address ({@link sessionAddressOf}): the box is drained for it. A leg whose occupant could not be read
340
+ * never binds a drain (its session-box mount judgment refused it). */
341
+ address: SessionAddress;
342
+ /** The Runner's session store — the by-id read the drain confirms its occupant through ({@link PeerSessionDrainOptions.sessions}). */
343
+ sessions: Pick<SessionStore, "headOf">;
318
344
  runId: string;
319
345
  scope: string;
320
346
  inject: PeerSessionDrainOptions["inject"];