@sema-agent/core 7.57.0 → 7.59.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 (399) hide show
  1. package/CHANGELOG.md +1161 -0
  2. package/README.md +6 -4
  3. package/dist/agents/cc-peer-directory.js +8 -8
  4. package/dist/agents/child-model-seat.d.ts +4 -2
  5. package/dist/agents/child-model-seat.js +5 -3
  6. package/dist/agents/peer-directory.d.ts +9 -0
  7. package/dist/agents/peer-directory.js +6 -2
  8. package/dist/agents/send-message-tool.js +21 -12
  9. package/dist/agents/subagent-steps.js +2 -4
  10. package/dist/agents/subagent.js +33 -34
  11. package/dist/brain/anthropic.js +161 -45
  12. package/dist/brain/errors.d.ts +9 -3
  13. package/dist/brain/errors.js +7 -1
  14. package/dist/brain/failover.js +2 -1
  15. package/dist/brain/open-responses.js +3 -3
  16. package/dist/brain/openai.js +103 -53
  17. package/dist/brain/provider-dialect.d.ts +11 -0
  18. package/dist/brain/provider-dialect.js +5 -2
  19. package/dist/brain/reasoning-request.js +5 -4
  20. package/dist/brain/reasoning.d.ts +19 -0
  21. package/dist/brain/reasoning.js +17 -2
  22. package/dist/brain/request-route.d.ts +4 -1
  23. package/dist/brain/request-route.js +4 -1
  24. package/dist/brain/route-adjudicator.d.ts +84 -18
  25. package/dist/brain/route-adjudicator.js +89 -22
  26. package/dist/brain/route-conformance.js +1 -1
  27. package/dist/brain/stream-engine.js +84 -49
  28. package/dist/brain/stream-shared.d.ts +30 -0
  29. package/dist/brain/stream-shared.js +34 -1
  30. package/dist/brain/timeout.d.ts +62 -5
  31. package/dist/brain/timeout.js +93 -6
  32. package/dist/core/a2a.d.ts +2 -1
  33. package/dist/core/a2a.js +23 -10
  34. package/dist/core/account-row.d.ts +61 -0
  35. package/dist/core/account-row.js +51 -0
  36. package/dist/core/advisor-verdict.d.ts +2 -1
  37. package/dist/core/advisor-verdict.js +1 -1
  38. package/dist/core/allow-entry.d.ts +20 -7
  39. package/dist/core/allow-entry.js +18 -9
  40. package/dist/core/approval-object.d.ts +29 -15
  41. package/dist/core/approval-object.js +47 -19
  42. package/dist/core/ask-origin.d.ts +21 -2
  43. package/dist/core/ask-origin.js +5 -1
  44. package/dist/core/auto-compaction.d.ts +4 -0
  45. package/dist/core/auto-compaction.js +2 -2
  46. package/dist/core/auto-mode-directive.d.ts +29 -5
  47. package/dist/core/auto-mode-directive.js +38 -8
  48. package/dist/core/background-agent-store.d.ts +16 -3
  49. package/dist/core/checkpoint-requirements.d.ts +19 -1
  50. package/dist/core/checkpoint-requirements.js +5 -1
  51. package/dist/core/checkpoint-store.d.ts +85 -23
  52. package/dist/core/checkpoint-store.js +31 -9
  53. package/dist/core/child-clamp-seats.d.ts +29 -0
  54. package/dist/core/child-clamp-seats.js +56 -1
  55. package/dist/core/compliance.d.ts +2 -2
  56. package/dist/core/compliance.js +1 -1
  57. package/dist/core/effective-path-target.d.ts +8 -2
  58. package/dist/core/effective-path-target.js +8 -3
  59. package/dist/core/engine-notice.d.ts +99 -9
  60. package/dist/core/engine-notice.js +19 -5
  61. package/dist/core/fs-write-gate-policy.d.ts +4 -2
  62. package/dist/core/fs-write-gate-policy.js +7 -3
  63. package/dist/core/gate-fold.js +7 -4
  64. package/dist/core/gate-lanes.js +19 -6
  65. package/dist/core/gate-outcome.d.ts +32 -3
  66. package/dist/core/gate-outcome.js +19 -1
  67. package/dist/core/git-worktree-env.d.ts +53 -11
  68. package/dist/core/git-worktree-env.js +96 -12
  69. package/dist/core/governance-codes.d.ts +9 -1
  70. package/dist/core/governance-codes.js +13 -0
  71. package/dist/core/hooks.d.ts +35 -4
  72. package/dist/core/hooks.js +17 -11
  73. package/dist/core/human-input-projection.d.ts +1 -0
  74. package/dist/core/human-input-projection.js +3 -0
  75. package/dist/core/image-admission.d.ts +6 -5
  76. package/dist/core/image-admission.js +18 -14
  77. package/dist/core/locked-config.d.ts +20 -3
  78. package/dist/core/locked-config.js +40 -3
  79. package/dist/core/mailbox-store.d.ts +45 -1
  80. package/dist/core/mailbox-store.js +53 -9
  81. package/dist/core/mcp-call-meta.d.ts +66 -0
  82. package/dist/core/mcp-call-meta.js +103 -0
  83. package/dist/core/mcp-connection-pool.d.ts +3 -1
  84. package/dist/core/mcp-connection-pool.js +3 -1
  85. package/dist/core/mcp-failure.d.ts +117 -15
  86. package/dist/core/mcp-failure.js +71 -3
  87. package/dist/core/mcp-probe.d.ts +4 -0
  88. package/dist/core/mcp-probe.js +1 -1
  89. package/dist/core/mcp-server-link.d.ts +27 -3
  90. package/dist/core/mcp-server-link.js +25 -1
  91. package/dist/core/mcp-server-spec.d.ts +46 -18
  92. package/dist/core/mcp-server-spec.js +1 -18
  93. package/dist/core/mcp.d.ts +16 -20
  94. package/dist/core/mcp.js +112 -55
  95. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  96. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  97. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  98. package/dist/core/memory-engine/consolidation.js +1 -0
  99. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  100. package/dist/core/memory-engine/distiller.js +2 -2
  101. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  102. package/dist/core/memory-engine/dual-root.js +44 -1
  103. package/dist/core/memory-engine/engine.d.ts +67 -14
  104. package/dist/core/memory-engine/engine.js +384 -212
  105. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  106. package/dist/core/memory-engine/export-bundle.js +23 -4
  107. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  108. package/dist/core/memory-engine/file-backend.js +290 -117
  109. package/dist/core/memory-engine/index.d.ts +1 -1
  110. package/dist/core/memory-engine/layout.d.ts +59 -11
  111. package/dist/core/memory-engine/layout.js +190 -40
  112. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  113. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  114. package/dist/core/memory-engine/scope-contract.d.ts +45 -4
  115. package/dist/core/memory-engine/scope-contract.js +80 -11
  116. package/dist/core/memory-engine/sync-client.d.ts +9 -1
  117. package/dist/core/memory-engine/sync-client.js +31 -8
  118. package/dist/core/memory-engine/sync.d.ts +5 -0
  119. package/dist/core/memory-engine/types.d.ts +6 -0
  120. package/dist/core/mode-policy.d.ts +8 -5
  121. package/dist/core/mode-policy.js +5 -4
  122. package/dist/core/mods/classic-events.d.ts +5 -1
  123. package/dist/core/mods/host.js +1 -1
  124. package/dist/core/mods/kernel/dispatch.d.ts +3 -0
  125. package/dist/core/mods/kernel/dispatch.js +12 -9
  126. package/dist/core/mods/kernel/events.d.ts +6 -1
  127. package/dist/core/mods/kernel/events.js +2 -2
  128. package/dist/core/mods/kernel/registration.d.ts +9 -1
  129. package/dist/core/mods/kernel/registration.js +3 -0
  130. package/dist/core/mods/kernel/site-rules.d.ts +3 -0
  131. package/dist/core/mods/kernel/site-rules.js +10 -0
  132. package/dist/core/mods/package.d.ts +23 -0
  133. package/dist/core/mods/package.js +118 -0
  134. package/dist/core/mods/stations.d.ts +33 -12
  135. package/dist/core/mods/stations.js +45 -11
  136. package/dist/core/mods/tool-call.d.ts +5 -1
  137. package/dist/core/mods/tool-call.js +13 -4
  138. package/dist/core/parent-spec-seat.d.ts +8 -3
  139. package/dist/core/parent-spec-seat.js +2 -0
  140. package/dist/core/park-selfcheck.js +6 -0
  141. package/dist/core/path-guard-rows.d.ts +20 -0
  142. package/dist/core/path-guard-rows.js +11 -0
  143. package/dist/core/peer-seat.d.ts +248 -0
  144. package/dist/core/peer-seat.js +439 -0
  145. package/dist/core/permission-rule-consent.js +10 -4
  146. package/dist/core/permission-rule-model.d.ts +16 -0
  147. package/dist/core/permission-rule-model.js +1 -1
  148. package/dist/core/present-plan-tool.d.ts +20 -3
  149. package/dist/core/present-plan-tool.js +48 -4
  150. package/dist/core/protocol-http-auth.d.ts +40 -29
  151. package/dist/core/protocol-http-auth.js +30 -32
  152. package/dist/core/redaction-marks.d.ts +16 -0
  153. package/dist/core/redaction-marks.js +16 -0
  154. package/dist/core/redaction-passes.js +8 -9
  155. package/dist/core/resume-startup-cause.js +1 -0
  156. package/dist/core/retention.d.ts +41 -15
  157. package/dist/core/retention.js +59 -12
  158. package/dist/core/rewrite-rejudge.d.ts +38 -0
  159. package/dist/core/rewrite-rejudge.js +42 -2
  160. package/dist/core/roles.d.ts +34 -2
  161. package/dist/core/roles.js +43 -4
  162. package/dist/core/run-origin.d.ts +40 -0
  163. package/dist/core/run-origin.js +37 -0
  164. package/dist/core/runner/advertised-writable-dirs.d.ts +57 -38
  165. package/dist/core/runner/advertised-writable-dirs.js +126 -0
  166. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  167. package/dist/core/runner/announce-once-ledger.js +4 -2
  168. package/dist/core/runner/call-hook-stations.js +2 -2
  169. package/dist/core/runner/compaction-restate.d.ts +15 -6
  170. package/dist/core/runner/compaction-restate.js +28 -2
  171. package/dist/core/runner/contracts.d.ts +33 -21
  172. package/dist/core/runner/credential-origin-seat.js +4 -3
  173. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  174. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  175. package/dist/core/runner/decide-continuation.d.ts +2 -2
  176. package/dist/core/runner/gate-exit.d.ts +30 -8
  177. package/dist/core/runner/gate-exit.js +15 -8
  178. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  179. package/dist/core/runner/image-removed-seat.js +19 -0
  180. package/dist/core/runner/inline-image.js +1 -1
  181. package/dist/core/runner/memory-consolidation-driver.js +3 -3
  182. package/dist/core/runner/park-commit.d.ts +1 -1
  183. package/dist/core/runner/park-commit.js +3 -0
  184. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  185. package/dist/core/runner/prepare-ask-lane.js +2 -1
  186. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  187. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -5
  188. package/dist/core/runner/prepare-caps-and-workflow.js +3 -1
  189. package/dist/core/runner/prepare-config-doors.d.ts +8 -5
  190. package/dist/core/runner/prepare-config-doors.js +14 -10
  191. package/dist/core/runner/prepare-context-lane.js +2 -0
  192. package/dist/core/runner/prepare-delegation-surface.d.ts +8 -0
  193. package/dist/core/runner/prepare-delegation-surface.js +16 -18
  194. package/dist/core/runner/prepare-gate-stations.js +1 -1
  195. package/dist/core/runner/prepare-hands-readface.d.ts +11 -3
  196. package/dist/core/runner/prepare-hands-readface.js +9 -1
  197. package/dist/core/runner/prepare-inherited-gate.d.ts +1 -3
  198. package/dist/core/runner/prepare-inherited-gate.js +14 -27
  199. package/dist/core/runner/prepare-memory.d.ts +3 -0
  200. package/dist/core/runner/prepare-memory.js +26 -37
  201. package/dist/core/runner/prepare-park-ask.d.ts +1 -1
  202. package/dist/core/runner/prepare-park-ask.js +2 -1
  203. package/dist/core/runner/prepare-policy-chain.d.ts +7 -7
  204. package/dist/core/runner/prepare-policy-chain.js +18 -15
  205. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  206. package/dist/core/runner/prepare-project-context.js +2 -2
  207. package/dist/core/runner/prepare-prompt-inputs.d.ts +1 -1
  208. package/dist/core/runner/prepare-prompt-inputs.js +8 -19
  209. package/dist/core/runner/prepare-protocol-tools.d.ts +4 -2
  210. package/dist/core/runner/prepare-protocol-tools.js +11 -3
  211. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  212. package/dist/core/runner/prepare-run-refs.js +4 -1
  213. package/dist/core/runner/prepare-suspend-saga.d.ts +2 -0
  214. package/dist/core/runner/prepare-suspend-saga.js +2 -1
  215. package/dist/core/runner/prepare-task.js +28 -13
  216. package/dist/core/runner/prepare-wiring-manifest.d.ts +2 -1
  217. package/dist/core/runner/prepare-wiring-manifest.js +4 -3
  218. package/dist/core/runner/prepare-workspace-restore.d.ts +3 -0
  219. package/dist/core/runner/prepare-workspace-restore.js +4 -4
  220. package/dist/core/runner/reply-pricing.d.ts +30 -0
  221. package/dist/core/runner/reply-pricing.js +19 -0
  222. package/dist/core/runner/resume-admission.js +5 -3
  223. package/dist/core/runner/resume-apply.js +6 -1
  224. package/dist/core/runner/resume-checkpoint-screen.js +2 -0
  225. package/dist/core/runner/resume-policy-outcome.js +5 -5
  226. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  227. package/dist/core/runner/role-seat-defaulted.js +40 -0
  228. package/dist/core/runner/run-brain-sinks.js +2 -0
  229. package/dist/core/runner/run-harness-handlers.d.ts +3 -4
  230. package/dist/core/runner/run-harness-handlers.js +1 -8
  231. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  232. package/dist/core/runner/run-identity-wiring.js +6 -4
  233. package/dist/core/runner/run-leg.d.ts +2 -0
  234. package/dist/core/runner/run-leg.js +42 -29
  235. package/dist/core/runner/run-notification-lane.js +3 -0
  236. package/dist/core/runner/run-stop-and-final-verify.js +2 -2
  237. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  238. package/dist/core/runner/run-terminal-adoption.js +9 -3
  239. package/dist/core/runner/run-turn-boundary.js +77 -70
  240. package/dist/core/runner/runtask.d.ts +1 -1
  241. package/dist/core/runner/runtask.js +2 -2
  242. package/dist/core/runner/side-call-account.d.ts +1 -1
  243. package/dist/core/runner/side-call-account.js +3 -18
  244. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  245. package/dist/core/runner/sub-agent-deny-lists.js +10 -0
  246. package/dist/core/runner/terminal-account.js +3 -3
  247. package/dist/core/runner/tool-end-body.js +2 -1
  248. package/dist/core/runner/tool-occurrence.d.ts +5 -2
  249. package/dist/core/runner/tool-occurrence.js +4 -3
  250. package/dist/core/runner/turn-attachments.d.ts +26 -22
  251. package/dist/core/runner/turn-attachments.js +24 -26
  252. package/dist/core/runner/write-protection-station.d.ts +8 -2
  253. package/dist/core/runner/write-protection-station.js +2 -0
  254. package/dist/core/runner-deps.d.ts +3 -3
  255. package/dist/core/secret-env.d.ts +32 -2
  256. package/dist/core/secret-env.js +65 -3
  257. package/dist/core/sensitive-path-policy.js +9 -10
  258. package/dist/core/session-log-transfer.d.ts +24 -0
  259. package/dist/core/session-log-transfer.js +166 -0
  260. package/dist/core/session-policy-store.d.ts +3 -1
  261. package/dist/core/session-policy-store.js +13 -9
  262. package/dist/core/session-store.d.ts +86 -24
  263. package/dist/core/session-store.js +162 -24
  264. package/dist/core/session.d.ts +92 -1
  265. package/dist/core/shell-read-silence.js +1 -0
  266. package/dist/core/side-query.d.ts +11 -1
  267. package/dist/core/side-query.js +9 -0
  268. package/dist/core/skill-grant-binding.d.ts +31 -2
  269. package/dist/core/skill-grant-binding.js +31 -1
  270. package/dist/core/skill-grant.d.ts +8 -5
  271. package/dist/core/skill-grant.js +6 -6
  272. package/dist/core/steer-replay.d.ts +4 -2
  273. package/dist/core/steer-replay.js +2 -1
  274. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  275. package/dist/core/store-contracts/checkpoint-store-contract.js +20 -2
  276. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  277. package/dist/core/store-contracts/session-repo-contract.js +112 -5
  278. package/dist/core/store-contracts/session-store-contract.d.ts +4 -1
  279. package/dist/core/store-contracts/session-store-contract.js +236 -2
  280. package/dist/core/synthetic-read-verdict.js +2 -1
  281. package/dist/core/task-event.d.ts +92 -8
  282. package/dist/core/task-notification.js +16 -10
  283. package/dist/core/task-registry-agent.js +1 -0
  284. package/dist/core/task-registry-shared.d.ts +7 -1
  285. package/dist/core/task-spec.d.ts +49 -1
  286. package/dist/core/task-stream.d.ts +2 -1
  287. package/dist/core/terminal-cause.d.ts +11 -1
  288. package/dist/core/tool-catalog-entries.js +1 -0
  289. package/dist/core/tool-check-reading.d.ts +1 -0
  290. package/dist/core/tool-check-reading.js +3 -3
  291. package/dist/core/tool-policy.d.ts +16 -0
  292. package/dist/core/tool-result-store.d.ts +17 -10
  293. package/dist/core/tool-result-store.js +3 -1
  294. package/dist/core/tool-roster.d.ts +112 -5
  295. package/dist/core/tool-roster.js +42 -1
  296. package/dist/core/tool-spec.d.ts +3 -1
  297. package/dist/core/types.d.ts +3 -3
  298. package/dist/core/types.js +1 -1
  299. package/dist/core/untrusted-egress.d.ts +0 -2
  300. package/dist/core/untrusted-egress.js +10 -14
  301. package/dist/core/user-attachment.js +1 -1
  302. package/dist/core/wiring-manifest.d.ts +18 -6
  303. package/dist/core/wiring-manifest.js +4 -3
  304. package/dist/core/workspace-snapshot.d.ts +44 -0
  305. package/dist/core/workspace-snapshot.js +34 -0
  306. package/dist/core/write-protect.d.ts +43 -3
  307. package/dist/core/write-protect.js +43 -16
  308. package/dist/engine/compaction/compaction.js +29 -3
  309. package/dist/engine/execution-env/node-execution-env.d.ts +4 -3
  310. package/dist/engine/execution-env/node-execution-env.js +24 -23
  311. package/dist/engine/execution-env/symlink-chain.d.ts +7 -5
  312. package/dist/engine/harness/agent-harness.d.ts +30 -2
  313. package/dist/engine/harness/agent-harness.js +43 -12
  314. package/dist/engine/harness/messages.d.ts +3 -1
  315. package/dist/engine/harness/messages.js +3 -2
  316. package/dist/engine/harness/types.d.ts +56 -7
  317. package/dist/engine/harness/types.js +5 -1
  318. package/dist/engine/llm/rejected-images.d.ts +46 -0
  319. package/dist/engine/llm/rejected-images.js +54 -0
  320. package/dist/engine/llm/tool-turns.d.ts +2 -1
  321. package/dist/engine/llm/types.d.ts +30 -10
  322. package/dist/engine/llm/types.js +1 -1
  323. package/dist/engine/loop/agent-loop.d.ts +8 -0
  324. package/dist/engine/loop/agent-loop.js +52 -15
  325. package/dist/engine/loop/types.d.ts +3 -1
  326. package/dist/engine/session/import-validate.js +3 -0
  327. package/dist/engine/session/memory-repo.d.ts +17 -9
  328. package/dist/engine/session/memory-repo.js +44 -34
  329. package/dist/engine/session/path-to-root.d.ts +38 -0
  330. package/dist/engine/session/path-to-root.js +39 -0
  331. package/dist/engine/session/repo-utils.d.ts +22 -4
  332. package/dist/engine/session/repo-utils.js +49 -1
  333. package/dist/engine/session/storage-base.d.ts +10 -1
  334. package/dist/engine/session/storage-base.js +11 -22
  335. package/dist/index.d.ts +29 -16
  336. package/dist/index.js +21 -11
  337. package/dist/internal/harness-types.d.ts +2 -2
  338. package/dist/internal/harness.d.ts +3 -2
  339. package/dist/internal/harness.js +2 -2
  340. package/dist/internal/llm.d.ts +1 -0
  341. package/dist/orchestration/workflow-observe.d.ts +17 -1
  342. package/dist/orchestration/workflow-observe.js +20 -0
  343. package/dist/orchestration/workflow-types.d.ts +32 -7
  344. package/dist/orchestration/workflow.js +739 -489
  345. package/dist/shell/counting-pass.d.ts +50 -0
  346. package/dist/shell/counting-pass.js +502 -0
  347. package/dist/shell/lex.d.ts +4 -2
  348. package/dist/shell/lex.js +93 -34
  349. package/dist/shell/shell-words.d.ts +1 -1
  350. package/dist/shell/shell-words.js +7 -6
  351. package/dist/stores/file/index.d.ts +4 -1
  352. package/dist/stores/file/index.js +4 -1
  353. package/dist/stores/file/mailbox-store.js +6 -10
  354. package/dist/stores/file/session-store.d.ts +15 -8
  355. package/dist/stores/file/session-store.js +28 -13
  356. package/dist/tools/fs/fs-bash.d.ts +6 -0
  357. package/dist/tools/fs/fs-bash.js +6 -3
  358. package/dist/tools/fs/fs-write.d.ts +6 -3
  359. package/dist/tools/fs/fs-write.js +8 -7
  360. package/dist/tools/fs/index.d.ts +3 -0
  361. package/dist/tools/fs/index.js +7 -3
  362. package/dist/tools/fs/program-read-model.d.ts +13 -0
  363. package/dist/tools/fs/program-read-model.js +15 -0
  364. package/dist/tools/fs/program-read-model.rows.js +1 -1
  365. package/dist/tools/fs/read-deny.d.ts +13 -10
  366. package/dist/tools/fs/read-deny.js +25 -5
  367. package/dist/tools/fs/read-floor.d.ts +19 -0
  368. package/dist/tools/fs/read-floor.js +23 -0
  369. package/dist/tools/fs/safety.js +40 -8
  370. package/dist/tools/fs/search.js +6 -24
  371. package/dist/tools/fs/shell-read-check.d.ts +9 -2
  372. package/dist/tools/fs/shell-read-check.js +61 -16
  373. package/dist/tools/fs/shell-read-establish.js +2 -1
  374. package/dist/tools/fs/shell-read-identity.js +1 -1
  375. package/dist/tools/fs/shell-read-judge.d.ts +26 -9
  376. package/dist/tools/fs/shell-read-judge.js +10 -6
  377. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  378. package/dist/tools/fs/shell-read-plan.js +22 -15
  379. package/dist/tools/fs/shell-read-start.js +1 -0
  380. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  381. package/dist/tools/fs/shell-reentry-text.js +25 -3
  382. package/dist/tools/monitor.d.ts +4 -0
  383. package/dist/tools/monitor.js +2 -0
  384. package/dist/tools/worktree.d.ts +42 -15
  385. package/dist/tools/worktree.js +60 -32
  386. package/package.json +5 -2
  387. package/test/export-surface.snapshot.json +149 -1
  388. package/wire-changes/core-stores-sql@7.58.0.json +29 -0
  389. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  390. package/wire-changes/core@7.58.0.json +2188 -0
  391. package/wire-changes/core@7.59.0.json +2459 -0
  392. package/wire-changes/mods-kernel@7.58.0.json +81 -0
  393. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  394. package/wire-changes/primitives@7.58.0.json +29 -0
  395. package/wire-changes/primitives@7.59.0.json +29 -0
  396. package/dist/primitives/credential-ref.d.ts +0 -89
  397. package/dist/primitives/credential-ref.js +0 -125
  398. package/dist/primitives/index.d.ts +0 -2
  399. package/dist/primitives/index.js +0 -1
@@ -197,10 +197,13 @@ function runtimeSuppliedHolderOf(value) {
197
197
  }
198
198
  const PLACEHOLDER_KEY_WORDS = new Set([...FLAG_WORDS, "undefined", "placeholder", "lm-studio", "not-needed", "sk-no-key-required"]);
199
199
  const ONE_REPEATED_CHARACTER_RE = /^(\S)\1{2,}$/u;
200
+ export function isBlankCredential(value) {
201
+ return value.trim() === "";
202
+ }
200
203
  function notACredentialReason(value) {
201
- const text = value.trim();
202
- if (text === "")
204
+ if (isBlankCredential(value))
203
205
  return "white space only, which every blank variable equals";
206
+ const text = value.trim();
204
207
  if (text.length < CREDENTIAL_MIN_CHARS)
205
208
  return `a string of fewer than ${CREDENTIAL_MIN_CHARS} characters, which names no secret`;
206
209
  if (PLACEHOLDER_KEY_WORDS.has(text.toLowerCase()))
@@ -267,7 +270,7 @@ export function declareWithheldEnv(table) {
267
270
  Reflect.set(globalThis, WITHHELD_ENV, { names: names, declared, held: withheldEnvOf().held });
268
271
  }
269
272
  export function holdOwnCredentialValues(values, onNotice) {
270
- const given = [...values].filter((v) => typeof v === "string" && v.length > 0);
273
+ const given = [...values].filter((v) => typeof v === "string" && !isBlankCredential(v));
271
274
  const taken = given.filter((v) => {
272
275
  const why = notACredentialReason(v);
273
276
  if (why !== undefined)
@@ -364,6 +367,65 @@ export function inheritedHostEnv(policy, findings) {
364
367
  throw new Error(problem);
365
368
  return withholdOwnCredentials(policyArm(policy, findings), findings);
366
369
  }
370
+ const unkeptCharacter = (text) => (text.includes("\0") ? "a NUL" : UNPAIRED_SURROGATE_RE.test(text) ? "an unpaired surrogate" : undefined);
371
+ function readGrant(grant, n) {
372
+ try {
373
+ if (typeof grant !== "object" || grant === null || Array.isArray(grant))
374
+ return `env grant ${n} must be an object of variable names to strings (got ${kindOf(grant)})`;
375
+ const entries = Object.entries(grant);
376
+ for (const [name, value] of entries) {
377
+ const unkept = name.includes("=") ? "\"=\"" : unkeptCharacter(name);
378
+ const badName = name === "" ? "an empty string" : unkept && `one holding ${unkept}`;
379
+ if (badName)
380
+ return `env grant ${n} holds a key that is not a variable name (${badName})`;
381
+ if (value !== undefined && typeof value !== "string")
382
+ return `env grant ${n}: ${name} must be a string (got ${kindOf(value)})`;
383
+ const badValue = value === undefined ? undefined : unkeptCharacter(value);
384
+ if (badValue !== undefined)
385
+ return `env grant ${n}: the value of ${name} holds ${badValue}`;
386
+ }
387
+ return entries;
388
+ }
389
+ catch {
390
+ return `env grant ${n} threw while it was read — refused`;
391
+ }
392
+ }
393
+ function composeHostChildEnv(policy, grants) {
394
+ let problem;
395
+ try {
396
+ problem = inheritEnvPolicyProblem(policy);
397
+ }
398
+ catch {
399
+ problem = "inheritEnv threw while it was read — refused";
400
+ }
401
+ if (problem !== undefined)
402
+ return problem;
403
+ const findings = [];
404
+ const entries = new Map();
405
+ for (const entry of Object.entries(inheritedHostEnv(policy, findings)))
406
+ entries.set(envNameKey(entry[0]), entry);
407
+ for (let i = 0; i < grants.length; i++) {
408
+ if (grants[i] === undefined)
409
+ continue;
410
+ const read = readGrant(grants[i], i + 1);
411
+ if (typeof read === "string")
412
+ return read;
413
+ for (const [name, value] of read)
414
+ entries.set(envNameKey(name), [entries.get(envNameKey(name))?.[0] ?? name, value]);
415
+ }
416
+ const env = Object.fromEntries(entries.values());
417
+ return { env, withheld: findings.filter((f) => entries.get(envNameKey(f.key))?.[1] === undefined) };
418
+ }
419
+ export function hostChildEnvProblem(policy, ...grants) {
420
+ const composed = composeHostChildEnv(policy, grants);
421
+ return typeof composed === "string" ? composed : undefined;
422
+ }
423
+ export function hostChildEnv(policy, ...grants) {
424
+ const composed = composeHostChildEnv(policy, grants);
425
+ if (typeof composed === "string")
426
+ throw new Error(composed);
427
+ return composed;
428
+ }
367
429
  function policyArm(policy, findings) {
368
430
  if (policy === "all")
369
431
  return { ...process.env };
@@ -2,8 +2,8 @@ import { homedir } from "node:os";
2
2
  import { isAbsolute, join, resolve } from "node:path";
3
3
  import { anchorSpelling, canonicalizeTarget, expandHomeTilde, isAbsoluteForFamily, isWinFormPath, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
4
4
  import { spelledExemptionOf } from "./write-protect.js";
5
- import { compileSegmentPattern, READ_FACE_BUILTIN_DENY_TABLE, readDenyPatternRun, segmentGuardRow } from "../tools/fs/read-deny.js";
6
- import { judgePathRows } from "./path-guard-rows.js";
5
+ import { compileSegmentPattern, READ_FACE_BUILTIN_DENY_TABLE, readDenyPatternRun, SEGMENT_FOLDS, segmentGuardRow } from "../tools/fs/read-deny.js";
6
+ import { guardHitReachClause, guardHitVia, judgePathRows } from "./path-guard-rows.js";
7
7
  import { agentConfigDirSegments, agentConfigDirTail, checkedAgentConfigDir } from "./agent-config-dir.js";
8
8
  import { isProtectedWrite, protectivePathTargetOf } from "./tool-registry.js";
9
9
  import { pathTargetBaseOf } from "./effective-path-target.js";
@@ -132,8 +132,8 @@ export function createSensitivePathPolicy(opts) {
132
132
  if (configRoot === undefined || configRows.length === 0)
133
133
  return [];
134
134
  const fold = CASE_INSENSITIVE_FS ? "ascii" : "none";
135
- const lower = (segs) => (CASE_INSENSITIVE_FS ? segs.map((seg) => seg.replace(/[A-Z]/g, (c) => c.toLowerCase())) : segs);
136
- const anchors = [configRoot, ...(env === undefined ? [] : await canonicalDataRootKeys(env, [configRoot], signal))].map((root) => lower(agentConfigDirSegments(root)));
135
+ const folded = (segs) => segs.map((seg) => SEGMENT_FOLDS[fold](seg));
136
+ const anchors = [configRoot, ...(env === undefined ? [] : await canonicalDataRootKeys(env, [configRoot], signal))].map((root) => folded(agentConfigDirSegments(root)));
137
137
  return configRows.map(({ raw, tail }) => ({ ...(compileSegmentPattern(tail, fold) ?? { raw, segments: [], fold }), raw, anchors, rootedOnly: true }));
138
138
  };
139
139
  const rowsOf = async (env, signal) => [...guardRows, ...(await configTwins(env, signal)).map(rowOf)];
@@ -182,7 +182,7 @@ export function createSensitivePathPolicy(opts) {
182
182
  return { kind: "clear" };
183
183
  if (hit.unreadable !== undefined)
184
184
  return { kind: "unresolved", cause: hit.unreadable };
185
- return { kind: "hit", pattern: hit.row.name, via: hit.viewKind === "hop" ? "chain" : hit.viewKind === "canonical" ? "target" : "spelling" };
185
+ return { kind: "hit", pattern: hit.row.name, via: guardHitVia(hit.viewKind) };
186
186
  };
187
187
  return {
188
188
  ...(compiled.length > 0 ? { writeGuardRows: (at) => rowsOf(at.env, at.signal) } : {}),
@@ -200,13 +200,12 @@ export function createSensitivePathPolicy(opts) {
200
200
  return { action: "deny", message: `write to "${path}" is refused (target_unresolved): where it leads on disk could not be determined, so the sensitive-path list cannot tell whether it is a guarded path — ${judged.cause}`, decisionReason: "safety" };
201
201
  }
202
202
  if (judged.kind === "hit") {
203
+ const reach = guardHitReachClause(judged.via);
203
204
  return {
204
205
  action: "deny",
205
- message: judged.via === "target"
206
- ? `write to "${path}" is blocked: its real target resolves onto the guarded sensitive path "${judged.pattern}"`
207
- : judged.via === "chain"
208
- ? `write to "${path}" is blocked: its symlink chain passes through the guarded sensitive path "${judged.pattern}"`
209
- : `write to "${path}" is blocked: its path names the guarded sensitive path "${judged.pattern}"`,
206
+ message: reach === undefined
207
+ ? `write to "${path}" is blocked: its path names the guarded sensitive path "${judged.pattern}"`
208
+ : `write to "${path}" is blocked: the guarded sensitive path "${judged.pattern}" — ${reach}`,
210
209
  decisionReason: "safety",
211
210
  };
212
211
  }
@@ -0,0 +1,24 @@
1
+ import { type SessionHead, type SessionRowExpectation, type SessionRowRead, type SessionTreeEntry } from "../internal/harness.js";
2
+ import type { SessionLogTransfer } from "./session.js";
3
+ /**
4
+ * What a store's {@link SessionLogTransfer} reads and writes through: the repo's one read of a row (metadata, head and log of one
5
+ * generation) and its conditional import (judged against the row as that read answered it, in the import's own step, answering the head
6
+ * it wrote), and the store's own hold of an id — the one gate its other row writers (acquire, register, release) wait on, which also drops
7
+ * the store's cached view of the id so the view a commit replaces is not served again. Writers the hold does not see (another instance,
8
+ * a write straight through the repo) are met by the import's expectation instead.
9
+ */
10
+ export interface LogTransferSeat {
11
+ readRow(sessionId: string): Promise<SessionRowRead | undefined>;
12
+ importEntries(sessionId: string, owner: string | undefined, entries: SessionTreeEntry[], options: {
13
+ preserveActorAssertions?: boolean;
14
+ expect: SessionRowExpectation;
15
+ }): Promise<SessionHead>;
16
+ holding<T>(sessionId: string, work: () => Promise<T>): Promise<T>;
17
+ }
18
+ /**
19
+ * The {@link SessionLogTransfer} of a store over a repo that holds each log whole: reads are the repo's row read, a staging lives in this
20
+ * process until its commit, and a commit is the repo's conditional import under the store's hold of the id — the import itself judging,
21
+ * in the step that replaces the log, the write law (`importRowCells`: an existing row must already be the committer's; a placed row is
22
+ * refused) and that the row is still the one the commit read (its head, log included), and answering the head it wrote.
23
+ */
24
+ export declare function repoLogTransfer(seat: LogTransferSeat): SessionLogTransfer;
@@ -0,0 +1,166 @@
1
+ import { SessionError, StreamingImportValidator, importRowCells, ownerCell, sessionLogMarkOf, uuidv7 } from "../internal/harness.js";
2
+ import { receiptRefusal, receiveOwnProperties } from "./own-property-receipt.js";
3
+ import { thrownText } from "./thrown-value.js";
4
+ const EXPORT_WORDS = { subject: "SessionLogExportOptions", unit: "member", moment: "at SessionLogTransfer.exportStream" };
5
+ const BEGIN_WORDS = { subject: "SessionLogTransfer.beginReplace options", unit: "member", moment: "at SessionLogTransfer.beginReplace" };
6
+ const COMMIT_WORDS = { subject: "SessionLogCommit", unit: "member", moment: "at SessionLogReplace.commit" };
7
+ async function logOrNull(seat, sessionId) {
8
+ return (await seat.readRow(sessionId))?.entries ?? null;
9
+ }
10
+ function committedHead(sessionId, answer) {
11
+ if (typeof answer === "object" && answer !== null) {
12
+ const { owner, incarnation, leafId } = answer;
13
+ if ((owner === null || typeof owner === "string") && (incarnation === undefined || typeof incarnation === "string") && (leafId === null || typeof leafId === "string"))
14
+ return { owner, incarnation, leafId };
15
+ }
16
+ throw new SessionError("storage", `the repo's importEntries wrote session ${sessionId}'s log but answered no head (got ${answer === null ? "null" : typeof answer}) — a repo behind SessionStore.logTransfer answers the head its write committed; read the row again`);
17
+ }
18
+ function readRecord(raw, words, names) {
19
+ if (typeof raw !== "object" || raw === null)
20
+ throw receiptRefusal(`${words.subject} must be an object, got ${raw === null ? "null" : typeof raw}`);
21
+ const got = receiveOwnProperties(raw, words);
22
+ for (const name of Object.keys(got))
23
+ if (!names.includes(name))
24
+ throw receiptRefusal(`${words.subject} carries "${name}" — not a member this face reads`);
25
+ return got;
26
+ }
27
+ function isIntegerFrom(value, floor) {
28
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= floor;
29
+ }
30
+ function readExportOptions(raw) {
31
+ if (raw === undefined)
32
+ return { afterSeq: -1 };
33
+ const got = readRecord(raw, EXPORT_WORDS, ["afterSeq", "batchSize"]);
34
+ const afterSeq = got["afterSeq"];
35
+ if (afterSeq !== undefined && !isIntegerFrom(afterSeq, -1))
36
+ throw receiptRefusal("SessionLogExportOptions.afterSeq must be an integer ≥ -1 when present");
37
+ if (got["batchSize"] !== undefined && !isIntegerFrom(got["batchSize"], 1))
38
+ throw receiptRefusal("SessionLogExportOptions.batchSize must be an integer ≥ 1 when present");
39
+ return { afterSeq: isIntegerFrom(afterSeq, -1) ? afterSeq : -1 };
40
+ }
41
+ function readBeginOptions(raw) {
42
+ if (raw === undefined)
43
+ return {};
44
+ const preserveActorAssertions = readRecord(raw, BEGIN_WORDS, ["preserveActorAssertions"])["preserveActorAssertions"];
45
+ if (preserveActorAssertions === undefined)
46
+ return {};
47
+ if (typeof preserveActorAssertions !== "boolean")
48
+ throw receiptRefusal("beginReplace options.preserveActorAssertions must be a boolean when present");
49
+ return { preserveActorAssertions };
50
+ }
51
+ function readCommit(raw) {
52
+ const { owner, decide } = readRecord(raw, COMMIT_WORDS, ["owner", "decide"]);
53
+ if (owner === undefined)
54
+ throw receiptRefusal("SessionLogCommit.owner must be a principal name or null (anonymous), got undefined");
55
+ try {
56
+ ownerCell(owner);
57
+ }
58
+ catch (err) {
59
+ throw receiptRefusal(`SessionLogCommit.owner: ${thrownText(err)}`);
60
+ }
61
+ if (typeof decide !== "function")
62
+ throw receiptRefusal(`SessionLogCommit.decide must be a function, got ${typeof decide}`);
63
+ return { owner: owner, decide: decide };
64
+ }
65
+ function detachedCopy(entry) {
66
+ try {
67
+ return structuredClone(entry);
68
+ }
69
+ catch (err) {
70
+ throw new SessionError("invalid_session", `a staged entry is not plain data: ${thrownText(err)}`);
71
+ }
72
+ }
73
+ function pick(log, ids, side) {
74
+ const byId = new Map(log.map((e) => [e.id, e]));
75
+ return ids.map((id) => {
76
+ const entry = byId.get(id);
77
+ if (entry === undefined)
78
+ throw new SessionError("not_found", `the ${side} log holds no entry ${id}`);
79
+ return entry;
80
+ });
81
+ }
82
+ export function repoLogTransfer(seat) {
83
+ return {
84
+ async listEntryIds(sessionId) {
85
+ const log = await logOrNull(seat, sessionId);
86
+ return log === null ? null : log.map((e) => e.id);
87
+ },
88
+ async exportStream(sessionId, opts) {
89
+ const { afterSeq } = readExportOptions(opts);
90
+ const log = await logOrNull(seat, sessionId);
91
+ if (log === null)
92
+ return null;
93
+ const tail = log.slice(afterSeq + 1);
94
+ return (async function* () {
95
+ yield* tail;
96
+ })();
97
+ },
98
+ beginReplace(sessionId, opts) {
99
+ return stagedReplace(seat, sessionId, readBeginOptions(opts));
100
+ },
101
+ };
102
+ }
103
+ function stagedReplace(seat, sessionId, gate) {
104
+ const validator = new StreamingImportValidator(gate);
105
+ let staged = [];
106
+ let ended;
107
+ const refuseEnded = () => {
108
+ if (ended !== undefined)
109
+ throw new SessionError("invalid_session", `the staging of session ${sessionId} has ended (${ended}) — it takes nothing more`);
110
+ };
111
+ return {
112
+ stagingId: `${sessionId}#stg-${uuidv7()}`,
113
+ async append(entries) {
114
+ refuseEnded();
115
+ try {
116
+ if (!Array.isArray(entries))
117
+ throw receiptRefusal(`SessionLogReplace.append takes an array of entries, got ${entries === null ? "null" : typeof entries}`);
118
+ for (const entry of entries) {
119
+ const copy = detachedCopy(entry);
120
+ validator.step(copy);
121
+ staged.push(copy);
122
+ }
123
+ }
124
+ catch (err) {
125
+ ended = "a batch was refused";
126
+ staged = [];
127
+ throw err;
128
+ }
129
+ },
130
+ async commit(input) {
131
+ refuseEnded();
132
+ ended = "committed";
133
+ const entries = staged;
134
+ staged = [];
135
+ const { owner, decide } = readCommit(input);
136
+ validator.finish();
137
+ const stagedIds = entries.map((e) => e.id);
138
+ return seat.holding(sessionId, async () => {
139
+ const row = await seat.readRow(sessionId);
140
+ if (row !== undefined)
141
+ importRowCells(sessionId, owner, row.metadata, row.metadata.createdAt);
142
+ const current = row === undefined ? null : row.entries;
143
+ const view = {
144
+ current: current === null ? null : current.map((e) => e.id),
145
+ staged: stagedIds,
146
+ read: async (side, ids) => structuredClone(side === "current" ? pick(current ?? [], ids, "current") : pick(entries, ids, "staged")),
147
+ };
148
+ const verdict = await decide(view);
149
+ if (verdict !== "replace" && verdict !== "keep")
150
+ throw receiptRefusal(`SessionLogCommit.decide must answer "replace" or "keep", got ${typeof verdict === "string" ? `"${verdict}"` : typeof verdict}`);
151
+ if (verdict === "keep") {
152
+ if (row === undefined)
153
+ throw new SessionError("invalid_session", `decide answered "keep" for session ${sessionId}, which has no row — there is no log to keep`);
154
+ return { outcome: "kept", head: row.head };
155
+ }
156
+ const expect = row === undefined ? { row: null } : { row: row.head, log: sessionLogMarkOf(row.entries) };
157
+ const answer = await seat.importEntries(sessionId, owner ?? undefined, entries, { ...gate, expect });
158
+ return { outcome: "replaced", head: committedHead(sessionId, answer) };
159
+ });
160
+ },
161
+ async abort() {
162
+ ended ??= "aborted";
163
+ staged = [];
164
+ },
165
+ };
166
+ }
@@ -370,7 +370,9 @@ export declare function judgeSessionRulesWrite(prior: StoredSessionRules | null,
370
370
  * nothing is in no effect, so writing it in this engine's grammar widens). Both sides are read through
371
371
  * {@link readSessionRulesShape} first: a side it cannot read (a key that is no bucket — a retired one included) throws
372
372
  * `invalid_shape` rather than compare without it. `mountedToolNames` = the store's declaration
373
- * ({@link SessionPolicyStoreOptions.mountedToolNames}; empty when it has none) — the write judge's too.
373
+ * ({@link SessionPolicyStoreOptions.mountedToolNames}; empty when it has none), read with the engine's catalog as the one
374
+ * {@link storeRoster} the write judge reads: a case twin of an engine tool (`BASH`) is no entry on either side, so its owner can
375
+ * take a stored one out (and adding one widens nothing).
374
376
  */
375
377
  export declare function loosenReasons(priorValue: SessionPermissionRules, nextValue: SessionPermissionRules, mountedToolNames?: ReadonlySet<string>): string[];
376
378
  /**
@@ -392,11 +392,14 @@ export function earlierGrammarAnnouncer(sink) {
392
392
  }
393
393
  };
394
394
  }
395
- function effectiveEntries(rules, field, mountedToolNames) {
396
- return compileSessionRuleBucket(rules, field, mountedToolNames).rows.map((r) => r.entry);
395
+ function storeRoster(declared) {
396
+ return rootFacingToolNames(declared);
397
+ }
398
+ function effectiveEntries(rules, field, roster) {
399
+ return compileSessionRuleBucket(rules, field, roster).rows.map((r) => r.entry);
397
400
  }
398
401
  function assertEntriesRead(rules, mountedToolNames) {
399
- const known = rootFacingToolNames(mountedToolNames);
402
+ const known = storeRoster(mountedToolNames);
400
403
  for (const field of ENTRY_FIELDS) {
401
404
  for (const { entry, reading: read, reader } of bucketReadings(rules, field, known)) {
402
405
  if (read.kind === "row")
@@ -467,23 +470,24 @@ export function loosenReasons(priorValue, nextValue, mountedToolNames = NO_DECLA
467
470
  };
468
471
  const prior = shapeOf("prior", priorValue);
469
472
  const next = shapeOf("next", nextValue);
470
- if (unreadableDenyEntries(next, mountedToolNames).length > 0)
473
+ const roster = storeRoster(mountedToolNames);
474
+ if (unreadableDenyEntries(next, roster).length > 0)
471
475
  return [];
472
- const unreadPrior = unreadableDenyEntries(prior, mountedToolNames);
476
+ const unreadPrior = unreadableDenyEntries(prior, roster);
473
477
  if (unreadPrior.length > 0) {
474
478
  return [`the prior rules refuse every call — their toolDeny holds ${shownEntries(unreadPrior.map((i) => i.entry), (entry) => inertEntryPhrase({ entry, reason: "grammar" }))}, which no grammar reads`];
475
479
  }
476
480
  const reasons = [];
477
- const keptDeny = new Set(effectiveEntries(next, "toolDeny", mountedToolNames));
478
- for (const x of effectiveEntries(prior, "toolDeny", mountedToolNames))
481
+ const keptDeny = new Set(effectiveEntries(next, "toolDeny", roster));
482
+ for (const x of effectiveEntries(prior, "toolDeny", roster))
479
483
  if (!keptDeny.has(x))
480
484
  reasons.push(`removed toolDeny ${renderListEntry(x)}`);
481
485
  if (prior.toolAllow !== undefined) {
482
486
  if (next.toolAllow === undefined)
483
487
  reasons.push("removed toolAllow allowlist (all allowed)");
484
488
  else {
485
- const had = new Set(effectiveEntries(prior, "toolAllow", mountedToolNames));
486
- for (const x of effectiveEntries(next, "toolAllow", mountedToolNames))
489
+ const had = new Set(effectiveEntries(prior, "toolAllow", roster));
490
+ for (const x of effectiveEntries(next, "toolAllow", roster))
487
491
  if (!had.has(x))
488
492
  reasons.push(`widened toolAllow with ${renderListEntry(x)}`);
489
493
  }
@@ -1,6 +1,7 @@
1
- import { type Session, type SessionHead, type SessionPlacementRecord, type SessionRepo } from "../internal/harness.js";
2
- import { type AcquiredSession, type PlacedSessionRow, type SessionListQuery, type SessionPlacement, type SessionStore, type SessionStoreSummary } from "./session.js";
1
+ import { type ForkPoint, type Session, type SessionHead, type SessionPlacementRecord, type SessionRepo } from "../internal/harness.js";
2
+ import { type AcquiredSession, type PlacedSessionRow, type SessionListQuery, type SessionLogTransfer, type SessionPlacement, type SessionStore, type SessionStoreHooks, type SessionStoreSummary } from "./session.js";
3
3
  import type { StoreDurability } from "./checkpoint-store.js";
4
+ import { type RetentionDeclaration } from "./retention.js";
4
5
  import { SESSION_DEFAULT_TTL_DAYS } from "../config/defaults.js";
5
6
  export { SESSION_DEFAULT_TTL_DAYS };
6
7
  /** What idle-eviction and `release` do to the underlying repo. */
@@ -51,6 +52,17 @@ export interface TtlSessionStoreOptions {
51
52
  durability: StoreDurability;
52
53
  };
53
54
  };
55
+ /**
56
+ * The store's managed-retention declaration ({@link RetentionDeclaration}): `"managed"` says this store's rows are deleted
57
+ * on schedule by the deployment. Same declaration rule as {@link durability}: this cache layer runs no sweep and cannot see
58
+ * one, so the party that runs the sweep over the repo's rows states it. Default `"none"`. A word other than the two is refused
59
+ * at construction (`config.retention_capability`).
60
+ */
61
+ retention?: RetentionDeclaration;
62
+ /** The deployment's hooks on this store's row deletions ({@link SessionStoreHooks}): `beforeSessionDelete` runs, awaited, before
63
+ * every row this store deletes — an owner's `delete`, a placed `release`, an `evict: "delete"` release or idle sweep. A hook that is
64
+ * not a function, or a member this store does not run, is refused at construction. */
65
+ hooks?: SessionStoreHooks;
54
66
  }
55
67
  /**
56
68
  * The one placement admission of a session store's `acquire` — every backend that declares the placement partition
@@ -97,12 +109,12 @@ export declare function admitSessionPlacement(sessionId: string, persisted: Sess
97
109
  * See `design/10-会话持久化与会话中心.md` for the durable-backend (TiDB) contract.
98
110
  */
99
111
  export declare class TtlSessionStore implements SessionStore {
100
- /** Managed-retention declaration (ruled 2026-08-05, retention.ts): with a custom repo the default
101
- * evict policy is `forget` — cache eviction only, the durable rows live on — and there is no
102
- * tenant-scoped scheduled-deletion contract on any arm. Honestly `"none"`: a deployment with a
103
- * LOCKED retention policy refuses to start over this store. (The `SessionStore` interface itself
104
- * is declaration-agnostic; the retention face is the structural `RetentionDeclaring` shape.) */
105
- readonly retention: "none";
112
+ /** Managed-retention declaration (retention.ts): whether this store's rows are deleted on schedule by the deployment — given
113
+ * by the party that runs the sweep ({@link TtlSessionStoreOptions.retention}), `"none"` when none is given. This layer deletes
114
+ * nothing on schedule itself: with a custom repo the default evict policy is `forget` (cache eviction only, the durable rows
115
+ * live on), so a locked retention policy refuses this store at the default. (The `SessionStore` interface
116
+ * itself is declaration-agnostic; the retention face is the structural `RetentionDeclaring` shape.) */
117
+ readonly retention: RetentionDeclaration;
106
118
  /** design/173 §2.3 — see {@link TtlSessionStoreOptions.durability} for the declaration rules. */
107
119
  readonly durability?: StoreDurability;
108
120
  /** Subagent transcript persistence — see {@link TtlSessionStoreOptions.placements}. */
@@ -124,6 +136,20 @@ export declare class TtlSessionStore implements SessionStore {
124
136
  /** The repo's head read as this store's own decisions read the row through it (the cache check, the existence check), held
125
137
  * privately so the store's reading of its rows is the repo's whatever a host does with the face. */
126
138
  private readonly repoHead?;
139
+ /** The storage half of a cross-backend move ({@link SessionStore.logTransfer}), over the repo's row read and its conditional import:
140
+ * present only when the repo has both and a head read. A staging lives in this process; a commit holds the id as a release does, and
141
+ * the import it ends with is conditional on the row the commit read. */
142
+ readonly logTransfer?: SessionLogTransfer;
143
+ /** The owner-guarded delete ({@link SessionStore.delete}): present only when the repo has a head read (the owner it guards on) and
144
+ * the row read (so its removal is conditional on the row it judged). */
145
+ readonly delete?: (sessionId: string, guard: {
146
+ owner: string | null;
147
+ }) => Promise<boolean>;
148
+ /** Whether the repo judges the expectation of the writes this store hands it (`SessionRepo.delete` / `importEntries` with `expect`):
149
+ * a repo with a head read and the row read ({@link SessionRepo.readRow}). Over any other repo a deletion is of the id it judged. */
150
+ private readonly judgesRows;
151
+ /** {@link TtlSessionStoreOptions.hooks}' deletion hook, read once at construction. */
152
+ private readonly beforeRowDelete?;
127
153
  private repo;
128
154
  private entries;
129
155
  /** In-flight acquisitions keyed by id, so concurrent acquire(sameId) share one session. */
@@ -138,6 +164,8 @@ export declare class TtlSessionStore implements SessionStore {
138
164
  * and then lose) an authority the delete is about to close, and the caller would hold a session whose first append answers
139
165
  * log_closed while the file still exists. The gate is per-id and bounded by the release's own settlement (both outcomes release it). */
140
166
  private releasing;
167
+ /** Resolutions of an id in flight (`openOrCreate`), each marked when a hold of the id starts while it reads the row. */
168
+ private readonly resolutions;
141
169
  /** Sessions pinned by a design/45 checkpoint — skipped by idle sweep until unpinned (B6/§5). */
142
170
  private pinned;
143
171
  private defaultTtlMs;
@@ -157,16 +185,24 @@ export declare class TtlSessionStore implements SessionStore {
157
185
  * view without positive proof is dropped and the id resolved from the row; over one with no head read (it mints no occupant token)
158
186
  * the cached view is the only evidence of the occupant, and it stands. */
159
187
  private viewStandsFor;
160
- /** Whether a cached view is still the occupant the row holds ({@link viewStandsFor}, over the row's head read in one read). Over a repo
161
- * with no head read there is no row to read: the judge's answer for no row there is "stands", given without reading the view. */
162
- private cachedViewStands;
188
+ /** Whether a cached view is still the occupant the row holds ({@link viewStandsFor}, over the row's head read in one read) and still
189
+ * the log it holds — the row's leaf is the view's: a log replaced under the same occupant (a cross-backend move's commit, through
190
+ * another instance or the repo) is another log, and its view is dropped and the id resolved from the row. Answers the head that read
191
+ * gave when the view stands — the row a deletion through the view expects (`SessionRepo.delete`'s expectation) — and `undefined` when
192
+ * it does not. Over a repo with no head read there is no row to read: the judge's answer for no row there is "stands" (`null`: no head
193
+ * to expect), given without reading the view. */
194
+ private standingRow;
163
195
  /** The placement admission ({@link admitSessionPlacement}) for this store, judged on every resolution path. The
164
196
  * partition declaration is a getter over this store's live field, so it is read where the admission judges the
165
197
  * mirror direction (after the request's own members, and only then) — never captured at construction. */
166
198
  private assertPlacementAdmission;
167
199
  /** Resume an existing session from the repo, or create it if the backend has no such id (unless
168
- * `requireExisting`, in which case a genuinely-missing id fails loud instead — design/114 Phase3). */
200
+ * `requireExisting`, in which case a genuinely-missing id fails loud instead — design/114 Phase3). A resolution that a hold of the id
201
+ * (a commit, a delete, a release) overtook while it read the row is withdrawn and made again after the hold: the view it read may be of
202
+ * a log the hold replaced, and it is never left published. */
169
203
  private openOrCreate;
204
+ /** One resolution of {@link openOrCreate}: open the row, or create it on a miss. */
205
+ private resolveRow;
170
206
  private createAndStore;
171
207
  /** Refresh the idle timer for a session, and record the activity on its row through the repo ({@link SessionRepo.touch}, where the repo
172
208
  * has it) — the time {@link list} orders by. A fault recording it rejects. */
@@ -208,17 +244,46 @@ export declare class TtlSessionStore implements SessionStore {
208
244
  /** Run a release that may delete the row while it holds the id: the gate is set before the first await, after any release already in
209
245
  * flight for the id, and `acquire` / `register` answer after it settles — no caller captures an authority the delete is about to tear
210
246
  * down (the repo closes the shared authority before its removal can fail), or writes the row mid-decision. */
247
+ /** Resolves once the hold of the id in flight when the caller arrived settles (either outcome). A hold queued behind it is the next
248
+ * resolution's concern: `openOrCreate` resolves again after any hold that overtakes it. */
249
+ private settledHolds;
211
250
  private holdingId;
212
251
  /** The deciding half of {@link release}, under its gate. A delete goes through the cached view only while the row still stands for it
213
- * (`cachedViewStands`); with no view, or a view of an occupant the row no longer holds (another writer deleted the row, or deleted and
214
- * created it again), the row decides — its placement read cold ({@link rowIsPlaced}) — and an unplaced row nobody here holds is left
215
- * as it is. Placement obligation 4: a placed row's release is a REAL deletion whatever the evict policy (the joint reap deletes the
216
- * agent row first and then calls this to end the transcript; a forget would strand it). A delete runs only on a read that answered
217
- * — the head read with the view still standing, or the row's own placement: a read that faults deletes nothing, and the release
218
- * rejects with it. A placed release that fails (a read or the delete) leaves the tombstone, so the retry reads the row again —
219
- * never a retained cache entry, which could serve a closed log; an unplaced view's release under `evict: "delete"` leaves nothing,
220
- * so its retry after a failed read resolves and deletes nothing. */
252
+ * (`standingRow`); with no view, or a view of an occupant the row no longer holds (another writer deleted the row, or deleted and
253
+ * created it again), the row decides — its head read first, then its placement read cold ({@link rowIsPlaced}) — and an unplaced row
254
+ * nobody here holds is left as it is. Placement obligation 4: a placed row's release is a REAL deletion whatever the evict policy (the
255
+ * joint reap deletes the agent row first and then calls this to end the transcript; a forget would strand it). A delete runs only on a
256
+ * read that answered — the head read with the view still standing, or the row's own placement: a read that faults deletes nothing, and
257
+ * the release rejects with it. A placed release that fails (a read or the delete) leaves the tombstone, so the retry reads the row
258
+ * again — never a retained cache entry, which could serve a closed log; an unplaced view's release under `evict: "delete"` leaves
259
+ * nothing, so its retry after a failed read resolves and deletes nothing. What the deletion expects of the row is what was judged:
260
+ * a placed transcript's deletion is owed to its occupant, so it expects the occupant only; an unplaced view's eviction judged its log
261
+ * idle, so it expects the view's occupant and the view's log as it stands after the hook ({@link idleViewExpectation}). A cold release
262
+ * expects the head it read before the placement (no row read ⇒ it expects no row, and so deletes none): the deletion lands only on
263
+ * that generation, and a row once replaced never comes back, so the placement read after it was of that same row. */
221
264
  private releaseRow;
265
+ /** What the deletion of a view judged idle (an `evict: "delete"` release or sweep) expects of the row, read after the hook: the occupant
266
+ * the view stood for and the view's log as it stands then — an append through the view itself while the hook ran is still the view's
267
+ * log; a write through anyone else is not, and the row is not deleted. Over a repo that does not judge rows, none (the id judged). */
268
+ private idleViewExpectation;
269
+ /** Every row deletion this store makes, after its caller judged the row: the deployment's {@link TtlSessionStoreOptions.hooks} deletion
270
+ * hook first, awaited — when it rejects the row is not deleted and the deletion rejects with it — then the repo's delete, conditional
271
+ * on the row the caller judged (`expect`, read after the hook and judged by the repo in the step that removes the row: the hook ran in
272
+ * another writer's time, which may have deleted the row, created another under the id, or written it). Answers whether it deleted: a
273
+ * missed expectation (`conflict`) deletes nothing and answers `false`. With no expectation (a repo that does not judge rows) the
274
+ * deletion is of the id judged. */
275
+ private deleteRow;
276
+ /**
277
+ * The owner-guarded delete ({@link SessionStore.delete}), holding the id as a release does: the row's head decides — no row, or an
278
+ * owner other than `guard.owner` (null-safe), deletes nothing — and a placed row is left to `release` (the joint reap). A deleted row
279
+ * leaves no cached view and no pin: the id answers nothing afterwards, and a later create under it is a new occupant.
280
+ */
281
+ private deleteOwned;
282
+ /** The row's metadata as the repo holds it, its placement included; `undefined` = no row. A read fault rejects. */
283
+ private rowMetadata;
284
+ /** The row's placement: the repo's placement probe where it has one, else the row's own metadata; `undefined` = no row or an unplaced
285
+ * one. A read fault rejects. */
286
+ private readPlacement;
222
287
  /** The repo's placement probe, where it has one. */
223
288
  private placementProbe;
224
289
  /** Whether an uncached id's row is worth reading for its placement: through the probe on a store that declares placements, and by
@@ -274,7 +339,4 @@ export declare class TtlSessionStore implements SessionStore {
274
339
  * and owner it mints. Forking the whole log instead copies the in-flight turn. The walk is one of the parent-chain walks, so it takes the
275
340
  * shared guard: a leaf on a loop of tool-result messages is refused `invalid_session` (the sentence of `getPathToRoot`) instead of followed.
276
341
  */
277
- export declare function settledForkOptions(source: Session): Promise<{
278
- entryId?: string;
279
- position?: "at";
280
- }>;
342
+ export declare function settledForkOptions(source: Session): Promise<ForkPoint>;