@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
@@ -1,3 +1,6 @@
1
+ import type { EngineStorageBackend } from "./engine-storage-backend.js";
2
+ import type { MemoryStore } from "./memory.js";
3
+ import type { WorkflowRunStore } from "./workflow-run-store.js";
1
4
  /** A store's retention declaration: `"managed"` = this store's rows are deleted on schedule by the
2
5
  * deployment; `"none"` = nothing deletes them on schedule. Absent ⇒ read fail-closed as `"none"`. */
3
6
  export type RetentionDeclaration = "managed" | "none";
@@ -30,7 +33,7 @@ export interface RetentionPolicy {
30
33
  /**
31
34
  * The executor that deletes the rows of the stores declaring `retention: "managed"` — a backend's
32
35
  * `retention` member (contract TYPE — core ships no implementation; the server half consumes this.
33
- * Reference implementation of the cascade: the server's session-purge order contract). A deployment
36
+ * The legs it calls, store by store and in order, are {@link RETENTION_CASCADE}). A deployment
34
37
  * that declares a store managed runs one over that store's rows. Every method is expected to be:
35
38
  * - **tenant-domain scoped**: work is enumerated and executed per retention domain (tenant/scope),
36
39
  * never as one global sweep;
@@ -45,7 +48,10 @@ export interface RetentionPolicy {
45
48
  * therefore the CALL's three counts, deliberately not an audit row. Where the deletion and the
46
49
  * sweep's context live on two sides — a SQL backend writes the deletion, the deployment holds the op —
47
50
  * the deployment writes the audit row through the backend's `audit` transaction hook, inside the
48
- * deleting transaction, from the receipt it is handed there.
51
+ * deleting transaction, from the receipt it is handed there;
52
+ * - **bounded by its call**: each call carries its own `cutoffMs`, computed by the party that runs the
53
+ * sweep (from its own horizon, e.g. a host's cleanup period in days) — an executor never reads
54
+ * {@link RetentionPolicy.maxAgeDays}, which is the startup check's to judge.
49
55
  */
50
56
  export interface ManagedRetentionCapability {
51
57
  /** Enumerate the retention domains (tenant/scope keys) this store holds data for. */
@@ -60,7 +66,8 @@ export interface ManagedRetentionCapability {
60
66
  /** Lineage-aware transcript/session deletion: a session tree is deleted only when no live
61
67
  * reference (fork child, background child, workflow run, pending checkpoint) still points into
62
68
  * it — references are re-checked inside the deletion transaction, never assumed from a prior
63
- * scan; {@link RETENTION_CASCADE_EXEMPT} is never deleted with one. */
69
+ * scan; {@link RETENTION_CASCADE_EXEMPT} is never deleted with one. What one session's deletion
70
+ * erases, and in which order, is {@link RETENTION_CASCADE}'s session-tree legs. */
64
71
  deleteExpiredSessions(input: {
65
72
  domain: string;
66
73
  cutoffMs: number;
@@ -72,6 +79,176 @@ export interface ManagedRetentionCapability {
72
79
  cutoffMs: number;
73
80
  }): Promise<RetentionReceipt>;
74
81
  }
82
+ /** @contract retention.cascade_domains — the executor's three destructive operations, one domain each: checkpoint expiry
83
+ * (`expireCheckpoints`), session-tree deletion (`deleteExpiredSessions`) and orphan tool-result deletion
84
+ * (`deleteOrphanToolResults`). Every leg of {@link RETENTION_CASCADE} belongs to exactly one of them, and each has a leg. */
85
+ export declare const RETENTION_CASCADE_DOMAINS: readonly ["checkpoints", "session-trees", "orphan-tool-results"];
86
+ /** One of {@link RETENTION_CASCADE_DOMAINS}. */
87
+ export type RetentionCascadeDomain = (typeof RETENTION_CASCADE_DOMAINS)[number];
88
+ /** @contract retention.governance_records_outlive_the_purge — the pollution marker dir, the capture
89
+ * opt-out record dir and the lineage ledger are governance FACTS about content that exists, not
90
+ * session data: deleting them makes a one-way privacy record revocable. */
91
+ export declare const RETENTION_CASCADE_EXEMPT: readonly ["session-pollution", "session-capture-optout", "lineage.json"];
92
+ /** The stores {@link RETENTION_CASCADE} covers, by seat name: every store member of {@link EngineStorageBackend}, the memory
93
+ * store the bundled file backend carries beside them, and the workflow-run store a deployment constructs itself. */
94
+ export type RetentionCascadeStores = Omit<EngineStorageBackend, "retention" | "dispose"> & {
95
+ readonly memoryStore: MemoryStore;
96
+ readonly workflowRunStore: WorkflowRunStore;
97
+ };
98
+ /** One leg of a store's row: the store method a domain's operation calls on it. */
99
+ export interface RetentionCascadeLeg<S = {
100
+ readonly [verb: string]: unknown;
101
+ }> {
102
+ readonly domain: RetentionCascadeDomain;
103
+ /** The store's method — a member of its interface (checked by the table's type). */
104
+ readonly verb: Extract<keyof S, string>;
105
+ /** What the call is given and what it removes. */
106
+ readonly selects: string;
107
+ /** A session-tree leg's place in one session's erasure (ascending; unique across the table). Present on a
108
+ * `"session-trees"` leg, absent on the other two domains' legs, whose operations each call one leg. */
109
+ readonly step?: number;
110
+ /** A fence the leg's store runs before the session's first step, where the store carries it (absent there ⇒ no fence). */
111
+ readonly fence?: Extract<keyof S, string>;
112
+ }
113
+ /** A store's one row: the legs that erase its rows, or why none do. */
114
+ export type RetentionCascadeRow<S = {
115
+ readonly [verb: string]: unknown;
116
+ }> = {
117
+ readonly legs: readonly RetentionCascadeLeg<S>[];
118
+ } | {
119
+ readonly exempt: string;
120
+ };
121
+ /**
122
+ * @contract retention.cascade_table — what deleting a session erases, as one table: every store the engine persists in has exactly one
123
+ * row (typed complete against {@link RetentionCascadeStores}), either the legs that erase its rows (domain, verb, what the verb selects,
124
+ * and for a session-tree leg its step) or an exemption naming why its rows are not session data. A session tree is erased child
125
+ * sessions first; within one session every leg's fence runs before the first step, then the steps ascend and the session row's leg
126
+ * is last — a leg that fails leaves the row, so a retry runs the cascade again from its first step and converges. A leg that finds
127
+ * what it erases through another store's rows runs before that store's leg (the journals before the runs, the background agents'
128
+ * boxes before their rows), so a retry still finds them. A workflow run
129
+ * started in a deleted session goes with it, journal included: a later resume of that run from another session is refused
130
+ * `workflow.park_truth_unreadable` with `detail.reason: "record_missing"`, the word an absent prior record already answers. The run
131
+ * store is what indexes runs by session, so a deployment that wires a journal store without one leaves its journals out of reach.
132
+ */
133
+ export declare const RETENTION_CASCADE: {
134
+ workflowJournalStore: {
135
+ legs: {
136
+ domain: "session-trees";
137
+ step: number;
138
+ verb: "deleteRun";
139
+ selects: string;
140
+ }[];
141
+ };
142
+ workflowRunStore: {
143
+ legs: {
144
+ domain: "session-trees";
145
+ step: number;
146
+ verb: "deleteBySession";
147
+ selects: string;
148
+ }[];
149
+ };
150
+ backgroundAgentStore: {
151
+ legs: {
152
+ domain: "session-trees";
153
+ step: number;
154
+ verb: "delete";
155
+ selects: string;
156
+ }[];
157
+ };
158
+ rosterStore: {
159
+ legs: {
160
+ domain: "session-trees";
161
+ step: number;
162
+ verb: "releaseAgent";
163
+ selects: string;
164
+ }[];
165
+ };
166
+ checkpointStore: {
167
+ legs: ({
168
+ domain: "session-trees";
169
+ step: number;
170
+ verb: "deleteSessionCheckpoints";
171
+ selects: string;
172
+ } | {
173
+ domain: "checkpoints";
174
+ verb: "reap";
175
+ selects: string;
176
+ step?: undefined;
177
+ })[];
178
+ };
179
+ toolResultStore: {
180
+ legs: ({
181
+ domain: "session-trees";
182
+ step: number;
183
+ verb: "deleteBySession";
184
+ selects: string;
185
+ } | {
186
+ domain: "orphan-tool-results";
187
+ verb: "deleteUnattributable";
188
+ selects: string;
189
+ step?: undefined;
190
+ })[];
191
+ };
192
+ sessionPolicyStore: {
193
+ legs: {
194
+ domain: "session-trees";
195
+ step: number;
196
+ verb: "deleteBySession";
197
+ selects: string;
198
+ }[];
199
+ };
200
+ fileHistoryStore: {
201
+ legs: {
202
+ domain: "session-trees";
203
+ step: number;
204
+ verb: "deleteBySession";
205
+ selects: string;
206
+ }[];
207
+ };
208
+ mailboxStore: {
209
+ legs: ({
210
+ domain: "session-trees";
211
+ step: number;
212
+ verb: "drop";
213
+ selects: string;
214
+ fence?: undefined;
215
+ } | {
216
+ domain: "session-trees";
217
+ step: number;
218
+ verb: "drop";
219
+ fence: "retireRecipient";
220
+ selects: string;
221
+ })[];
222
+ };
223
+ /**
224
+ * @contract retention.image_bytes_live_in_the_session_store — a transcript's image bytes have one holder, the engine's session store:
225
+ * they ride the session's log entries, so the session row's leg deletes them. A host that keeps a transcript of its own keeps a
226
+ * reference to them (session id, entry id, block index), never a second copy.
227
+ */
228
+ sessionStore: {
229
+ legs: ({
230
+ domain: "session-trees";
231
+ step: number;
232
+ verb: "delete";
233
+ selects: string;
234
+ } | {
235
+ domain: "checkpoints";
236
+ verb: "unpin";
237
+ selects: string;
238
+ step?: undefined;
239
+ })[];
240
+ };
241
+ usageWindowStore: {
242
+ exempt: string;
243
+ };
244
+ memoryStore: {
245
+ exempt: string;
246
+ };
247
+ };
248
+ /** One session's erasure in order — {@link RETENTION_CASCADE}'s session-tree legs, ascending by step (the one reading of the order). */
249
+ export declare const RETENTION_SESSION_TREE_STEPS: readonly (RetentionCascadeLeg & {
250
+ readonly store: keyof RetentionCascadeStores;
251
+ })[];
75
252
  /**
76
253
  * The three counts one destructive retention call produced. NOT an audit row and deliberately
77
254
  * identity-free (see the capability's `audited` clause): a scheduler that needs to tell two
@@ -79,13 +256,6 @@ export interface ManagedRetentionCapability {
79
256
  * own occurrence id, operation, and timestamp inside the deleting transaction. Adding those here
80
257
  * would ask a return value to know its own call context.
81
258
  */
82
- /** @contract retention.cascade_domains — a managed-retention cascade deletes checkpoint rows,
83
- * session trees (transcripts and lineage) and orphan tool results; nothing else is session data. */
84
- export declare const RETENTION_CASCADE_DOMAINS: readonly ["checkpoints", "session-trees", "orphan-tool-results"];
85
- /** @contract retention.governance_records_outlive_the_purge — the pollution marker dir, the capture
86
- * opt-out record dir and the lineage ledger are governance FACTS about content that exists, not
87
- * session data: deleting them makes a one-way privacy record revocable. */
88
- export declare const RETENTION_CASCADE_EXEMPT: readonly ["session-pollution", "session-capture-optout", "lineage.json"];
89
259
  export interface RetentionReceipt {
90
260
  domain: string;
91
261
  /** Rows destroyed by THIS call (idempotent retries count already-gone rows as 0, not errors). */
@@ -11,6 +11,51 @@ export function readRetentionDeclaration(name, value) {
11
11
  }
12
12
  export const RETENTION_CASCADE_DOMAINS = Object.freeze(["checkpoints", "session-trees", "orphan-tool-results"]);
13
13
  export const RETENTION_CASCADE_EXEMPT = Object.freeze(["session-pollution", "session-capture-optout", "lineage.json"]);
14
+ function deepFreeze(value) {
15
+ if (typeof value === "object" && value !== null) {
16
+ for (const member of Object.values(value))
17
+ deepFreeze(member);
18
+ Object.freeze(value);
19
+ }
20
+ return value;
21
+ }
22
+ export const RETENTION_CASCADE = deepFreeze({
23
+ workflowJournalStore: { legs: [{ domain: "session-trees", step: 1, verb: "deleteRun", selects: "the journal of each terminal workflow run the session started, found through the run store's listByScope session filter while the run rows still exist (a running run is a live reference, so the tree is not deleted)" }] },
24
+ workflowRunStore: { legs: [{ domain: "session-trees", step: 2, verb: "deleteBySession", selects: "the session's terminal workflow runs in its scope; answers the run ids it deleted" }] },
25
+ backgroundAgentStore: { legs: [{ domain: "session-trees", step: 4, verb: "delete", selects: "each terminal row listBySession names for the session (a running or parked row is a live reference)" }] },
26
+ rosterStore: { legs: [{ domain: "session-trees", step: 5, verb: "releaseAgent", selects: "every agent whose roster entry names the session as its session" }] },
27
+ checkpointStore: {
28
+ legs: [
29
+ { domain: "session-trees", step: 6, verb: "deleteSessionCheckpoints", selects: "the session's checkpoint rows in any status, guarded by the session row's owner (so it runs while the row exists)" },
30
+ { domain: "checkpoints", verb: "reap", selects: "the scope's pending rows whose deadline is before the call's cutoff, flipped to expired (no row is deleted)" },
31
+ ],
32
+ },
33
+ toolResultStore: {
34
+ legs: [
35
+ { domain: "session-trees", step: 7, verb: "deleteBySession", selects: "the entries whose owner record names the session" },
36
+ { domain: "orphan-tool-results", verb: "deleteUnattributable", selects: "the entries stored with no owner record, older than the call's cutoff" },
37
+ ],
38
+ },
39
+ sessionPolicyStore: { legs: [{ domain: "session-trees", step: 8, verb: "deleteBySession", selects: "the session's permission rules" }] },
40
+ fileHistoryStore: { legs: [{ domain: "session-trees", step: 9, verb: "deleteBySession", selects: "the session's whole history scope (the scope is the session id): boundaries, version records, pristine baselines, and the blobs no other scope references" }] },
41
+ mailboxStore: {
42
+ legs: [
43
+ { domain: "session-trees", step: 3, verb: "drop", selects: "the box of each terminal background-agent row backgroundAgentStore.listBySession names for the session (the row's scope and handle), found through those rows while they still exist" },
44
+ { domain: "session-trees", step: 10, verb: "drop", fence: "retireRecipient", selects: "the session's box (its peer session handle) in the session owner's scope; the fence is the optional retireRecipient pair's — run first, it refuses deliveries from then on, and a store without the pair (the bundled two) keeps no recipient lifecycle and has its box dropped" },
45
+ ],
46
+ },
47
+ sessionStore: {
48
+ legs: [
49
+ { domain: "session-trees", step: 11, verb: "delete", selects: "the session's row and its whole log (a placed subagent row is its agent row's joint reap: release after a winning delete)" },
50
+ { domain: "checkpoints", verb: "unpin", selects: "the session each expired checkpoint pinned" },
51
+ ],
52
+ },
53
+ usageWindowStore: { exempt: "a usage-governance ledger keyed by principal: token and cost counts, no session content, bounded by the deployment's live window set" },
54
+ memoryStore: { exempt: "memory is not session data: entries outlive the session that wrote them, and the governance records about them are RETENTION_CASCADE_EXEMPT" },
55
+ });
56
+ export const RETENTION_SESSION_TREE_STEPS = deepFreeze(Object.entries(RETENTION_CASCADE)
57
+ .flatMap(([store, row]) => ("legs" in row ? row.legs.filter((leg) => leg.domain === "session-trees").map((leg) => ({ store, ...leg })) : []))
58
+ .sort((a, b) => (a.step ?? 0) - (b.step ?? 0)));
14
59
  function codedError(code, message) {
15
60
  const e = new Error(message);
16
61
  e.code = code;
@@ -42,6 +42,11 @@ export declare const RETIRED_TASK_SPEC_KEYS: Readonly<Record<string, string>>;
42
42
  * the seat, owner `TaskSpec` (same code, same `TaskSpec.skills[].…` sentence). Kept out of {@link RETIRED_TASK_SPEC_KEYS}:
43
43
  * the spec's read judging these rows would read into the caller's `skills` entries before the seat's reader does. */
44
44
  export declare const RETIRED_SKILLS_SEAT_KEYS: Readonly<Record<string, string>>;
45
+ /** The RETIRED member of every bag that carries the compaction seats — a task's `compaction`, a `Runner.compactSession`
46
+ * request's `compaction`, a deployment's `contextSettings` overlay — keyed relative to the bag. The table the seats' one
47
+ * judgment reads (`compactionSeatsDefect`, `context-settings.ts`), each door with its own owner and code. Kept out of
48
+ * {@link RETIRED_TASK_SPEC_KEYS} for the reason the skills rows are: the seats have their own reader. */
49
+ export declare const RETIRED_COMPACTION_SEAT_KEYS: Readonly<Record<string, string>>;
45
50
  /** The RETIRED `ToolSpec` members — a spec still carrying one is refused by name (`config.deps_retired_key`) where the
46
51
  * factory reads the spec, never dropped unseen: a description the author wrote for one prompt shape would silently
47
52
  * never be shown. */
@@ -39,6 +39,9 @@ export const RETIRED_TASK_SPEC_KEYS = Object.freeze({
39
39
  export const RETIRED_SKILLS_SEAT_KEYS = Object.freeze({
40
40
  "skills[].manifest": "a skill's tools are its `allowedTools` / `disallowedTools` now — an allow-rule and a deny-rule source for the run the skill is activated in, never a fence; move `manifest.allowTools` to `allowedTools`. To fence tools write deny rules (or a delegated agent definition's `allowTools`); to fence write paths use session `allowDirs`",
41
41
  });
42
+ export const RETIRED_COMPACTION_SEAT_KEYS = Object.freeze({
43
+ enabled: "compaction is switched by two seats now — `autoCompact` (the passes the engine starts by itself: the turn-boundary pass at the window threshold, a prompt-too-long or guard recovery pass, the end-of-task summary) and `manualCompact` (the passes a caller asks for: `TaskStream.compact`, `Runner.compactSession`, `$.session.compact`). Write the seat you mean; `enabled: false` switched off both",
44
+ });
42
45
  export const RETIRED_TOOL_SPEC_KEYS = Object.freeze({
43
46
  descriptionClassic: 'a description\'s other forms are `descriptionVariants` now — the long form is `{ id: "classic", traits: { noneOf: ["lean_prompt"] }, text }`, chosen at mount by the run\'s prompt traits',
44
47
  });
@@ -24,10 +24,6 @@ export interface RuleOfferRead {
24
24
  /** Present when the batch's `uncoveredDetail` seat was not one well-formed row per counted segment and was left out
25
25
  * (the count is the truth source and an absent seat claims nothing); the caller owes that loss a disclosure. */
26
26
  readonly uncoveredDetailDropped?: true;
27
- /** Present when at least one batch member was read through the kind-less stored form (no `kind`, the four command
28
- * text members). A backend counts these to know whether its rows still carry the form that retirement line
29
- * RL-2164-kindless-batch-member waits on. */
30
- readonly kindlessForm?: true;
31
27
  }
32
28
  /** One element not read, and why. The rest of the list is read regardless. */
33
29
  export interface RuleOfferDropped {
@@ -62,29 +62,23 @@ function readBatch(value) {
62
62
  if (length === 0)
63
63
  return MALFORMED;
64
64
  const members = [];
65
- let kindless = false;
66
65
  for (let i = 0; i < length; i++) {
67
66
  const verdict = readBatchMember(rules[i]);
68
67
  if ("problem" in verdict)
69
68
  return verdict;
70
69
  members.push(verdict.member);
71
- if (verdict.kindlessForm === true)
72
- kindless = true;
73
70
  }
74
71
  if (typeof count !== "number" || !Number.isSafeInteger(count) || count < 0)
75
72
  return MALFORMED;
76
73
  const offer = { kind: "batch", rules: members, uncoveredSegments: count };
77
- const marks = kindless ? { kindlessForm: true } : {};
78
74
  if (detail === undefined)
79
- return { offer, ...marks };
75
+ return { offer };
80
76
  const rows = detailRowsOf(detail, count);
81
- return rows !== undefined ? { offer: { ...offer, uncoveredDetail: rows }, ...marks } : { offer, uncoveredDetailDropped: true, ...marks };
77
+ return rows !== undefined ? { offer: { ...offer, uncoveredDetail: rows } } : { offer, uncoveredDetailDropped: true };
82
78
  }
83
79
  function readBatchMember(value) {
84
80
  if (!isPlainRecord(value))
85
81
  return MALFORMED;
86
- if (!("kind" in value))
87
- return readKindlessBatchMember(value);
88
82
  const kind = wordOf(value.kind, RULE_OFFER_BATCH_MEMBER_KINDS);
89
83
  if (typeof kind !== "string")
90
84
  return kind;
@@ -105,16 +99,6 @@ function readBatchMember(value) {
105
99
  }
106
100
  }
107
101
  }
108
- function readKindlessBatchMember(value) {
109
- const rule = value.rule;
110
- const match = value.match;
111
- const command = value.command;
112
- const segment = value.segment;
113
- if (typeof rule !== "string" || typeof match !== "string" || typeof command !== "string" || typeof segment !== "string")
114
- return MALFORMED;
115
- const verdict = commandMember(rule, match, command, segment);
116
- return "problem" in verdict ? verdict : { ...verdict, kindlessForm: true };
117
- }
118
102
  function commandMember(rule, rawMatch, command, segment) {
119
103
  if (typeof rule !== "string")
120
104
  return MALFORMED;
@@ -152,7 +152,9 @@ export declare function announceClassifierRoleDefaulted(args: {
152
152
  * itself is never the count: the unavailable form is never counted; a reply with no verdict refused for want of a seat is
153
153
  * counted by the station's ruling path, not by this line.
154
154
  *
155
- * `detail: { toolName, toolCallId, cause, disposition, sessionId?, runId? }` — `cause` is why the classification did not rule,
155
+ * `detail: { toolName, toolCallId, cause, disposition, sessionId?, sourceSessionId?, agentId?, runId? }` — the session triple is the
156
+ * station's notice address (`noticeAddressOf`, leg-identity.ts: a delegated leg's notice goes to the tree's root and names its
157
+ * source leg); `cause` is why the classification did not rule,
156
158
  * an `AutoModeFallbackCause` word (`timeout` / `error`, or `parse_error` for a reply with no verdict). The sentence names the seat the station forked on — `leg` (this
157
159
  * run's own approval seat) or `ancestor` (the frozen approver of the ancestor layer whose classifier it was) — and, on a
158
160
  * timeout, the budget the classifier actually held (`budgetMs`, the decider's {@link AutoModeDecider.timeoutMs}; a
@@ -160,6 +162,8 @@ export declare function announceClassifierRoleDefaulted(args: {
160
162
  */
161
163
  export declare function classifierUnavailableNotice(args: ClassifierUnavailableInfo & ClassifierUnavailableStation & {
162
164
  sessionId?: string;
165
+ sourceSessionId?: string;
166
+ agentId?: string;
163
167
  runId?: string;
164
168
  }): EngineNotice;
165
169
  /** A classifier station's fork facts, wired once per leg: the route an ask the station hands on takes, and the
@@ -168,6 +172,8 @@ export declare function classifierUnavailableSeat(args: ClassifierUnavailableSta
168
172
  route: ApprovalRoute;
169
173
  onNotice: RunnerDeps["onNotice"];
170
174
  sessionId?: string;
175
+ sourceSessionId?: string;
176
+ agentId?: string;
171
177
  runId?: string;
172
178
  }): ClassifierUnavailableSeat;
173
179
  /** Which station forked (`leg` — the leg's gate, on its own approval seat; `ancestor` — an ancestor's frozen classifier in
@@ -129,13 +129,15 @@ export function classifierUnavailableNotice(args) {
129
129
  cause: args.cause,
130
130
  disposition: classifierUnavailableDispositionOf(args.route),
131
131
  ...(args.sessionId !== undefined ? { sessionId: args.sessionId } : {}),
132
+ ...(args.sourceSessionId !== undefined ? { sourceSessionId: args.sourceSessionId } : {}),
133
+ ...(args.agentId !== undefined ? { agentId: args.agentId } : {}),
132
134
  ...(args.runId !== undefined ? { runId: args.runId } : {}),
133
135
  },
134
136
  };
135
137
  }
136
138
  export function classifierUnavailableSeat(args) {
137
- const { route, onNotice, sessionId, runId, station, budgetMs } = args;
138
- return { route, onUnavailable: (info) => deliverEngineNotice(onNotice, classifierUnavailableNotice({ ...info, station, ...(budgetMs !== undefined ? { budgetMs } : {}), ...(sessionId !== undefined ? { sessionId } : {}), ...(runId !== undefined ? { runId } : {}) })) };
139
+ const { route, onNotice, sessionId, sourceSessionId, agentId, runId, station, budgetMs } = args;
140
+ return { route, onUnavailable: (info) => deliverEngineNotice(onNotice, classifierUnavailableNotice({ ...info, station, ...(budgetMs !== undefined ? { budgetMs } : {}), ...(sessionId !== undefined ? { sessionId } : {}), ...(sourceSessionId !== undefined ? { sourceSessionId } : {}), ...(agentId !== undefined ? { agentId } : {}), ...(runId !== undefined ? { runId } : {}) })) };
139
141
  }
140
142
  function classifierFallbackAnnouncer(args) {
141
143
  const announced = new Set();
@@ -1,6 +1,7 @@
1
1
  import { convertToLlm, uuidv7 } from "../../internal/harness.js";
2
2
  import { compactionFailureReason, compactionPassReport, DEFAULT_COMPACTION_INSTRUCTIONS, isCompactionManualCancel, manualCompactOutcomeOf, maybeCompact, mintCompactedEvent } from "../auto-compaction.js";
3
- import { contextOverlayFor } from "../context-settings.js";
3
+ import { compactionSeatsDefect, contextOverlayFor } from "../context-settings.js";
4
+ import { RETIRED_COMPACTION_SEAT_KEYS } from "../retired-keys.js";
4
5
  import { createRowSeat, promptCountOf } from "../mods/session-append.js";
5
6
  import { createCompactStation } from "../mods/session-compact.js";
6
7
  import { admitLegMods, legFacadeSeats } from "../mods/stations.js";
@@ -18,7 +19,7 @@ import { derivedLegBrain, sideCallBookOf } from "./side-call-account.js";
18
19
  import { acquireExistingSession, claimIdleSession, readPlainRequest, shownValue } from "./session-verb-doors.js";
19
20
  const VERB = "Runner.compactSession";
20
21
  const REQUEST_KEYS = new Set(["sessionId", "model", "instructions", "compaction", "compactionModel", "getApiKeyAndHeaders", "signal"]);
21
- const SETTINGS_KEYS = new Set(["enabled", "reserveTokens", "keepRecentTokens", "instructions", "clampTolerance"]);
22
+ const SETTINGS_KEYS = new Set(["manualCompact", "reserveTokens", "keepRecentTokens", "instructions", "clampTolerance", ...Object.keys(RETIRED_COMPACTION_SEAT_KEYS)]);
22
23
  export async function compactIdleSession(seats, request) {
23
24
  const req = screenCompactSessionRequest(request);
24
25
  const { deps } = seats;
@@ -90,7 +91,7 @@ async function compactOnSession(req, deps, session, resolved, named, legMods) {
90
91
  brain: derivedLegBrain(() => deps.brain, "compaction", book),
91
92
  ...(req.getApiKeyAndHeaders !== undefined ? { getApiKeyAndHeaders: req.getApiKeyAndHeaders } : {}),
92
93
  ...(thinking !== undefined ? { thinking } : {}),
93
- settings: legCompactionSettings(req.compaction !== undefined ? { compaction: req.compaction } : {}, overlay),
94
+ settings: legCompactionSettings(req.compaction !== undefined ? { compaction: req.compaction } : {}, overlay, "manualCompact"),
94
95
  customInstructions: req.instructions ?? req.compaction?.instructions ?? DEFAULT_COMPACTION_INSTRUCTIONS,
95
96
  ...(req.signal !== undefined ? { signal: req.signal, manualCancelSignal: req.signal } : {}),
96
97
  minTokens: 0,
@@ -193,9 +194,11 @@ function screenCompactSessionRequest(request) {
193
194
  };
194
195
  }
195
196
  function screenSettings(raw, bad) {
196
- const { enabled, reserveTokens, keepRecentTokens, instructions, clampTolerance } = readPlainRequest(raw, SETTINGS_KEYS, (what) => bad(`compaction: ${what}`));
197
- if (enabled !== undefined && typeof enabled !== "boolean")
198
- return bad(`compaction.enabled must be a boolean when given, got ${shownValue(enabled)}`);
197
+ const read = readPlainRequest(raw, SETTINGS_KEYS, (what) => bad(`compaction: ${what}`));
198
+ const seats = compactionSeatsDefect(read, "compaction");
199
+ if (seats !== undefined)
200
+ return bad(seats.sentence);
201
+ const { manualCompact, reserveTokens, keepRecentTokens, instructions, clampTolerance } = read;
199
202
  for (const [name, v] of [["reserveTokens", reserveTokens], ["keepRecentTokens", keepRecentTokens], ["clampTolerance", clampTolerance]]) {
200
203
  if (v !== undefined && typeof v !== "number")
201
204
  return bad(`compaction.${name} must be a number when given, got ${shownValue(v)}`);
@@ -203,7 +206,7 @@ function screenSettings(raw, bad) {
203
206
  if (instructions !== undefined && typeof instructions !== "string")
204
207
  return bad(`compaction.instructions must be a string when given, got ${shownValue(instructions)}`);
205
208
  return {
206
- ...(enabled !== undefined ? { enabled: enabled } : {}),
209
+ ...(manualCompact !== undefined ? { manualCompact: manualCompact } : {}),
207
210
  ...(reserveTokens !== undefined ? { reserveTokens: reserveTokens } : {}),
208
211
  ...(keepRecentTokens !== undefined ? { keepRecentTokens: keepRecentTokens } : {}),
209
212
  ...(instructions !== undefined ? { instructions: instructions } : {}),
@@ -4,7 +4,7 @@ import type { StaleToolResultOffloadOptions, TaskSpec } from "../types.js";
4
4
  import type { Context } from "../../internal/llm.js";
5
5
  import { type ToolResultStore } from "../tool-result-store.js";
6
6
  import type { Prepared, RunnerDepsSeat } from "./contracts.js";
7
- import { type ContextWindowOverlay } from "../context-settings.js";
7
+ import { type CompactionSeat, type ContextWindowOverlay } from "../context-settings.js";
8
8
  import { type CompactionSettings } from "../../internal/harness.js";
9
9
  /**
10
10
  * The maybeCompact call arguments that MUST be assembled identically on all three
@@ -159,10 +159,10 @@ export declare function legContextOverlayOption(prepared: Prepared, runner: Runn
159
159
  * The compaction SETTINGS a pass runs under — the assembly all three lanes and the out-of-run `Runner.compactSession` share.
160
160
  *
161
161
  * `{ ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction }` was hand-copied at each lane, and it is where the
162
- * deployment's live `enabled` declaration belongs: `maybeCompact` has exactly one enablement gate (it reads
163
- * `settings.enabled`), so folding the overlay in HERE makes the deployment's switch reach the boundary pass,
164
- * the recovery pass and the end-of-task summary by one edit instead of three, and keeps "who decides whether
165
- * compaction runs" a single expression ({@link compactionEnabled}: the request authored it > the deployment
166
- * declared it > on).
162
+ * deployment's live seat declarations belong: `maybeCompact` has exactly one enablement gate (it reads
163
+ * `settings.enabled`, the pass's own), so resolving it HERE from the seat of the pass the lane runs — `autoCompact`
164
+ * for the boundary's own pass, the recovery pass and the end-of-task summary, `manualCompact` for a requested one —
165
+ * keeps "who decides whether this pass runs" a single expression ({@link compactionEnabled}: the request authored the
166
+ * seat > the deployment declared it > on). The two seats themselves do not ride the settings: the pass reads its gate.
167
167
  */
168
- export declare function legCompactionSettings(spec: Pick<TaskSpec, "compaction">, overlay: ContextWindowOverlay | undefined): CompactionSettings;
168
+ export declare function legCompactionSettings(spec: Pick<TaskSpec, "compaction">, overlay: ContextWindowOverlay | undefined, seat: CompactionSeat): CompactionSettings;
@@ -121,6 +121,7 @@ export function legContextOverlayOption(prepared, runner) {
121
121
  const overlay = contextOverlayFor(runner.deps.contextSettings, prepared.harness.getModelRef(), runner.deps);
122
122
  return overlay !== undefined ? { contextOverlay: overlay } : {};
123
123
  }
124
- export function legCompactionSettings(spec, overlay) {
125
- return { ...DEFAULT_COMPACTION_SETTINGS, ...spec.compaction, enabled: compactionEnabled(spec.compaction?.enabled, overlay) };
124
+ export function legCompactionSettings(spec, overlay, seat) {
125
+ const { autoCompact: _auto, manualCompact: _manual, ...members } = spec.compaction ?? {};
126
+ return { ...DEFAULT_COMPACTION_SETTINGS, ...members, enabled: compactionEnabled(seat, spec.compaction, overlay) };
126
127
  }
@@ -271,6 +271,14 @@ export interface Prepared {
271
271
  * the `Session` contract instead. */
272
272
  session: StoredSession;
273
273
  sessionId: string;
274
+ /** The occupant of the session row this leg acquired (`SessionMetadata.incarnation`, read once from {@link session} at
275
+ * prepare); absent = no token (a row written before occupants were minted, or that read failed). With {@link sessionId} it
276
+ * is the leg's session ADDRESS (`task-notification.ts` `SessionAddress`): what its notification lane parks under, drains
277
+ * and registers as. */
278
+ sessionIncarnation?: string;
279
+ /** `true` = that read threw: the leg names no occupant it knows, so the notification store takes it as no admission and drains
280
+ * it nothing (`SessionAddress.unread`); what is kept for the session waits for a leg that reads its occupant. */
281
+ sessionIncarnationUnread?: true;
274
282
  /** This leg's task id, minted ONCE at prepare ({@link import("../leg-identity.js").legTaskIdOf}): its identity, frames, events'
275
283
  * `sourceTaskId`, trace frames and `TaskResult.taskId` read it here; none re-spells it. */
276
284
  taskId: string;
@@ -573,7 +581,7 @@ export interface Prepared {
573
581
  /**
574
582
  * This session's DURABLE box, present iff this leg mounted the session-box drain (a top-level leg
575
583
  * over a cross-process-safe mailbox with a grammatical session id). The notification lane binds it
576
- * to the park seat ({@link import("../task-notification.js").PendingSessionNotifications.bindSessionBox})
584
+ * to the park seat ({@link import("../task-notification.js").PendingSessionNotifications.admit})
577
585
  * so a child's uplink frame parked for this session while it is idle lands in the box the next run
578
586
  * drains — one mount judgment, the drain and the park read it alike. Absent ⇒ in-process parking.
579
587
  */
@@ -1051,6 +1059,10 @@ export interface Prepared {
1051
1059
  lastSentRequest: () => CompactionForkContext | undefined;
1052
1060
  /** The leg's advisor-instructions seat (advisor-instructions.ts); absent when the leg neither mounts the advisor nor has told the model of it. */
1053
1061
  advisorInstruction?: import("./advisor-instructions.js").AdvisorInstructionSeat;
1062
+ /** #1123 — the memory notices this prepare drained (whole engine reminders, model lane only, no echo): the leg's first
1063
+ * request carries them once, ahead of the user's message — a fresh leg's first user message, a resumed leg's
1064
+ * continuation. Never the system prompt (an event there breaks the cached prefix twice). Absent when nothing drained. */
1065
+ memoryNoticesFrame?: string;
1054
1066
  /** The post-compaction restore (`MaybeCompactOptions.workingFileAttachments.restore`): re-reads the candidates through
1055
1067
  * the leg's one file reader under the run's synthetic-Read judge — the user attachment's own path read — deduplicated
1056
1068
  * against the read state the summary leaves, and mints their attachment frames (`readCompactionRestore`); a file it
@@ -2063,6 +2075,12 @@ export interface RunInternals {
2063
2075
  * after a restart those intermediate sessions are dead ends, and a recovery face enumerating
2064
2076
  * "everything under this host session" needs the root anchor, not an alias walk. */
2065
2077
  rootSessionId?: string;
2078
+ /** The occupant of {@link rootSessionId}'s row (`SessionMetadata.incarnation`) as the tree's root run acquired it — the
2079
+ * other half of the root anchor's ADDRESS, carried beside it by the same fixed point (the spawner passes its own
2080
+ * `ctx.rootSessionIncarnation`). Absent = unknown: a revival, a resume or a wake (the row records no root occupant) and a
2081
+ * row written before occupants were minted; a frame the notification lane escalates to the root anchor is then addressed
2082
+ * to an unknown occupant, which a root holding a token is not. TRUSTED run-scoped channel (never a TaskSpec field). */
2083
+ rootSessionIncarnation?: string;
2066
2084
  /** The delegation tree's owner seat ({@link import("./delegation-owner.js").DelegationOwnerSeat}): a fixed point like
2067
2085
  * {@link rootSessionId} — the spawning run hands its own seat down by reference (the delegation and workflow lanes), so the tree
2068
2086
  * reads its root row's owner once. Absent ⇒ this run is nobody's child here (a top-level run, a revival, a resumed park) and its
@@ -3095,7 +3113,8 @@ export type EndOfTaskCompaction = {
3095
3113
  */
3096
3114
  export interface NotificationLaneBindings {
3097
3115
  harness: AgentHarness | undefined;
3098
- sessionId: string | undefined;
3116
+ /** The leg's session address (its session id and the occupant it acquired), bound by the identity lane once prepared. */
3117
+ address: import("../task-notification.js").SessionAddress | undefined;
3099
3118
  ident: () => {
3100
3119
  eventId?: string;
3101
3120
  parentToolCallId?: string;
@@ -22,11 +22,18 @@ export type DelegationOwnerReading = {
22
22
  export interface DelegationOwnerSeat {
23
23
  read(): Promise<DelegationOwnerReading>;
24
24
  }
25
+ /**
26
+ * Whether two readings of one session id's occupant cell (`SessionMetadata.incarnation`, `undefined` = no token) name the occupant a
27
+ * run holds: the same token, or no token on either side (a row written before occupants were minted, taken as it reads — a row
28
+ * created again under the id is minted a token, so it never reads as the one before it). A token on one side only is another
29
+ * occupant. The one reading of this question for a run's own seats: the tree owner below and the session address a frame is
30
+ * delivered to (`task-notification.ts`).
31
+ */
32
+ export declare function sameOccupant(held: string | undefined, current: string | undefined): boolean;
25
33
  /**
26
34
  * The seat of a run nobody spawned: the owner of the row it acquired, read by id through its own store's {@link SessionStore.headOf}
27
- * and taken only while the row's occupant is the one acquired — the head's `incarnation` equals the acquired session's metadata's
28
- * (both absent = a row written before occupants were minted, taken as it reads). A store without a by-id read has no owner to read:
29
- * the reading is `null`.
35
+ * and taken only while the row's occupant is the one acquired ({@link sameOccupant} of the head's `incarnation` and the acquired
36
+ * session's metadata's). A store without a by-id read has no owner to read: the reading is `null`.
30
37
  */
31
38
  export declare function ownRowDelegationOwner(sessions: Pick<SessionStore, "headOf">, sessionId: string, acquiredIncarnation: () => Promise<string | undefined>): DelegationOwnerSeat;
32
39
  /** The refusal of a delegation whose tree owner does not bind ({@link DelegationOwnerReading}): the child is not started and no row is
@@ -4,6 +4,9 @@ function ownerCellReading(sessionId, head) {
4
4
  return { bound: true, owner };
5
5
  return { bound: false, reason: `the session ${sessionId}'s row answers an owner that is neither a name nor anonymous (${owner === undefined ? "none" : typeof owner})` };
6
6
  }
7
+ export function sameOccupant(held, current) {
8
+ return held === current;
9
+ }
7
10
  export function ownRowDelegationOwner(sessions, sessionId, acquiredIncarnation) {
8
11
  let settled;
9
12
  let inFlight;
@@ -14,7 +17,7 @@ export function ownRowDelegationOwner(sessions, sessionId, acquiredIncarnation)
14
17
  const [head, acquired] = await Promise.all([headOf.call(sessions, sessionId), acquiredIncarnation()]);
15
18
  if (head === undefined)
16
19
  return { bound: false, reason: `the session ${sessionId} this run acquired has no row any more` };
17
- if (head.incarnation !== acquired)
20
+ if (!sameOccupant(head.incarnation, acquired))
18
21
  return { bound: false, reason: `the session ${sessionId} this run acquired now holds another occupant` };
19
22
  return ownerCellReading(sessionId, head);
20
23
  };
@@ -21,6 +21,7 @@
21
21
  * the reminder envelope and the text helpers. Its `import type` edges up to `hooks.ts` name the gate's public
22
22
  * contract (`ToolGateInput`, `ToolGateResult`, the observer payload), which stays declared there.
23
23
  */
24
+ import type { RefusalEcho } from "../refusal-echo.js";
24
25
  import { type ClassifierDenyCause, type DeniedBy, type GateOutcome, type ModeRefusal, type ModeRelease, type Settlement } from "../gate-outcome.js";
25
26
  import type { AllowRuleClearance } from "../allow-rule-shadow.js";
26
27
  import type { AutoModeClassifierRound } from "../auto-mode.js";
@@ -58,6 +59,8 @@ export interface GateExitFacts {
58
59
  /** The registration whose handler ended the call at the hook layer (its deny answer or its failure) — only beside `deniedBy: "hook"`.
59
60
  * As the bus names it: the engine's own origin word is read as no extension at the mint, once. */
60
61
  extension?: string;
62
+ /** The literals the refusal's sentence quotes, minted with it — only beside a layer word {@link DENIED_BY_MAY_ECHO} admits. */
63
+ echoed?: readonly RefusalEcho[];
61
64
  }
62
65
  /**
63
66
  * Mint the outcome. A defect here is an ENGINE defect (a refusing site that did not say who refused, a
@@ -344,6 +347,9 @@ export interface GatePass {
344
347
  * beside `deniedBy` by that station alone; the exit puts it on the gate result for the loop's error result.
345
348
  * OPTIONAL (the `probeUnanswered` form): the dispatch that builds the pass has nothing to declare here. */
346
349
  denyDetails?: unknown;
350
+ /** borrowed-mutable — the literals the shell read station's deny sentence quotes, written beside `deniedBy: "read_boundary"` by
351
+ * the sites that apply a refusing verdict; the exit mints `GateDisposition.echoed` from it ({@link DENIED_BY_MAY_ECHO}). */
352
+ denyEchoed?: readonly RefusalEcho[];
347
353
  /** borrowed-mutable — the shell read station's containment card behind a standing MANDATED ask (an out-of-root
348
354
  * or unestablishable read): when that ask ends as a refusal (a person's no, nobody to ask), the exit puts the
349
355
  * card on the gate result, so the refusal's `tool_end` still says WHAT was found (`readonly_out_of_root`) beside