@sema-agent/core 7.60.0 → 7.61.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 (482) hide show
  1. package/CHANGELOG.md +605 -0
  2. package/README.md +2 -2
  3. package/dist/agents/agent-transcript-tool.d.ts +2 -2
  4. package/dist/agents/agent-transcript-tool.js +1 -1
  5. package/dist/agents/cascade.d.ts +61 -10
  6. package/dist/agents/cascade.js +60 -20
  7. package/dist/agents/composition-allowance.d.ts +53 -0
  8. package/dist/agents/composition-allowance.js +49 -0
  9. package/dist/agents/composition-placement.d.ts +29 -0
  10. package/dist/agents/composition-placement.js +24 -0
  11. package/dist/agents/cumulative-stats.d.ts +4 -0
  12. package/dist/agents/cumulative-stats.js +3 -0
  13. package/dist/agents/inherited-tool-pool.d.ts +5 -3
  14. package/dist/agents/inherited-tool-pool.js +2 -2
  15. package/dist/agents/list-agents-tool.d.ts +1 -1
  16. package/dist/agents/peer-notice-route.d.ts +1 -1
  17. package/dist/agents/peer-notice-route.js +4 -3
  18. package/dist/agents/peer-notices.d.ts +4 -4
  19. package/dist/agents/peer-notices.js +8 -4
  20. package/dist/agents/peer-session-drain.d.ts +8 -1
  21. package/dist/agents/peer-session-drain.js +36 -7
  22. package/dist/agents/repair-loop.js +16 -6
  23. package/dist/agents/retain-ledger.js +3 -1
  24. package/dist/agents/roster-store.d.ts +1 -1
  25. package/dist/agents/roster-store.js +7 -4
  26. package/dist/agents/send-message-tool.d.ts +8 -10
  27. package/dist/agents/send-message-tool.js +43 -23
  28. package/dist/agents/subagent-completion-gate.d.ts +35 -0
  29. package/dist/agents/subagent-completion-gate.js +62 -0
  30. package/dist/agents/subagent-steps.d.ts +7 -6
  31. package/dist/agents/subagent.d.ts +30 -40
  32. package/dist/agents/subagent.js +187 -196
  33. package/dist/agents/suspend-guard.d.ts +9 -0
  34. package/dist/agents/suspend-guard.js +4 -0
  35. package/dist/agents/verify.d.ts +41 -14
  36. package/dist/agents/verify.js +37 -27
  37. package/dist/brain/anthropic.js +1 -0
  38. package/dist/brain/errors.d.ts +7 -1
  39. package/dist/brain/errors.js +6 -0
  40. package/dist/brain/failover.js +2 -1
  41. package/dist/brain/open-responses.js +1 -0
  42. package/dist/brain/openai.js +1 -0
  43. package/dist/brain/provider-dialect.d.ts +10 -0
  44. package/dist/brain/provider-dialect.js +13 -2
  45. package/dist/brain/stream-engine.d.ts +3 -0
  46. package/dist/brain/stream-engine.js +4 -0
  47. package/dist/core/agent-state.d.ts +1 -1
  48. package/dist/core/allow-entry.d.ts +59 -23
  49. package/dist/core/allow-entry.js +131 -38
  50. package/dist/core/ask-origin.d.ts +79 -0
  51. package/dist/core/ask-origin.js +76 -0
  52. package/dist/core/ask-question.d.ts +19 -13
  53. package/dist/core/ask-question.js +8 -2
  54. package/dist/core/auto-compaction.d.ts +2 -0
  55. package/dist/core/auto-compaction.js +2 -1
  56. package/dist/core/auto-mode.js +3 -5
  57. package/dist/core/background-agent-store.d.ts +7 -5
  58. package/dist/core/background-agent-store.js +12 -11
  59. package/dist/core/checkpoint-requirements.d.ts +24 -3
  60. package/dist/core/checkpoint-requirements.js +9 -1
  61. package/dist/core/checkpoint-store.d.ts +78 -19
  62. package/dist/core/checkpoint-store.js +8 -4
  63. package/dist/core/child-clamp-seats.d.ts +3 -2
  64. package/dist/core/child-clamp-seats.js +4 -3
  65. package/dist/core/closest-name.d.ts +13 -0
  66. package/dist/core/closest-name.js +35 -0
  67. package/dist/core/context-settings.js +3 -5
  68. package/dist/core/cross-boundary-taint.d.ts +1 -1
  69. package/dist/core/decision-receipt.d.ts +14 -1
  70. package/dist/core/decision-receipt.js +6 -3
  71. package/dist/core/delegation-frames.d.ts +13 -9
  72. package/dist/core/effective-path-target.js +2 -3
  73. package/dist/core/engine-attestation.d.ts +11 -1
  74. package/dist/core/engine-attestation.js +2 -0
  75. package/dist/core/engine-notice.d.ts +49 -18
  76. package/dist/core/file-history-retention.d.ts +8 -0
  77. package/dist/core/file-history-retention.js +14 -11
  78. package/dist/core/file-history-store.d.ts +31 -1
  79. package/dist/core/file-history-store.js +31 -2
  80. package/dist/core/frame-settlement.d.ts +10 -0
  81. package/dist/core/frame-settlement.js +6 -1
  82. package/dist/core/fs-write-gate-policy.d.ts +3 -3
  83. package/dist/core/fs-write-gate-policy.js +8 -7
  84. package/dist/core/gate-fold.js +2 -1
  85. package/dist/core/gate-lanes.js +7 -4
  86. package/dist/core/gate-outcome.d.ts +40 -1
  87. package/dist/core/gate-outcome.js +10 -0
  88. package/dist/core/git-worktree-env.d.ts +7 -3
  89. package/dist/core/git-worktree-env.js +16 -13
  90. package/dist/core/governance-codes.d.ts +12 -4
  91. package/dist/core/governance-codes.js +16 -4
  92. package/dist/core/hooks.d.ts +12 -4
  93. package/dist/core/hooks.js +11 -4
  94. package/dist/core/host-floor.js +3 -5
  95. package/dist/core/image-admission.d.ts +48 -8
  96. package/dist/core/image-admission.js +35 -4
  97. package/dist/core/input-author.d.ts +36 -0
  98. package/dist/core/input-author.js +39 -0
  99. package/dist/core/leg-identity.d.ts +62 -0
  100. package/dist/core/leg-identity.js +18 -0
  101. package/dist/core/locked-config.d.ts +2 -1
  102. package/dist/core/locked-config.js +5 -3
  103. package/dist/core/lsp.d.ts +5 -3
  104. package/dist/core/lsp.js +3 -2
  105. package/dist/core/mailbox-store.d.ts +85 -10
  106. package/dist/core/mailbox-store.js +31 -10
  107. package/dist/core/mcp-connection-pool.d.ts +6 -20
  108. package/dist/core/mcp-connection-pool.js +10 -28
  109. package/dist/core/mcp-failure.d.ts +76 -15
  110. package/dist/core/mcp-failure.js +60 -33
  111. package/dist/core/mcp-host-seat.d.ts +92 -53
  112. package/dist/core/mcp-host-seat.js +220 -46
  113. package/dist/core/mcp-probe.js +2 -2
  114. package/dist/core/mcp-server-link.d.ts +18 -6
  115. package/dist/core/mcp-server-link.js +19 -4
  116. package/dist/core/mcp-server-spec.d.ts +2 -1
  117. package/dist/core/mcp-session-end.d.ts +1 -2
  118. package/dist/core/mcp-session-end.js +1 -1
  119. package/dist/core/mcp.d.ts +6 -49
  120. package/dist/core/mcp.js +115 -111
  121. package/dist/core/media-byte-cap.d.ts +21 -46
  122. package/dist/core/media-byte-cap.js +55 -55
  123. package/dist/core/member-group.d.ts +7 -0
  124. package/dist/core/member-group.js +35 -0
  125. package/dist/core/memory-engine/consolidation.d.ts +1 -1
  126. package/dist/core/memory-engine/consolidation.js +7 -1
  127. package/dist/core/memory-engine/dual-root.d.ts +31 -0
  128. package/dist/core/memory-engine/dual-root.js +59 -11
  129. package/dist/core/memory-engine/engine.js +27 -24
  130. package/dist/core/memory-engine/file-backend.d.ts +13 -0
  131. package/dist/core/memory-engine/file-backend.js +35 -15
  132. package/dist/core/memory-engine/layout.d.ts +3 -0
  133. package/dist/core/memory-engine/layout.js +13 -3
  134. package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
  135. package/dist/core/memory-engine/memory-deployment.js +182 -0
  136. package/dist/core/memory-engine/sync-client.d.ts +39 -18
  137. package/dist/core/memory-engine/sync-client.js +72 -14
  138. package/dist/core/memory-engine/sync-report.d.ts +7 -4
  139. package/dist/core/memory-engine/sync.d.ts +9 -1
  140. package/dist/core/mode-policy.d.ts +8 -8
  141. package/dist/core/mode-policy.js +7 -5
  142. package/dist/core/mods/agent-stations.d.ts +39 -4
  143. package/dist/core/mods/agent-stations.js +59 -10
  144. package/dist/core/mods/dollar.d.ts +62 -0
  145. package/dist/core/mods/extension-call.d.ts +15 -1
  146. package/dist/core/mods/extension-call.js +7 -2
  147. package/dist/core/mods/kernel/dispatch.d.ts +4 -3
  148. package/dist/core/mods/kernel/dispatch.js +4 -4
  149. package/dist/core/mods/kernel/events.d.ts +4 -1
  150. package/dist/core/mods/kernel/events.js +6 -6
  151. package/dist/core/mods/kernel/registration.d.ts +3 -0
  152. package/dist/core/mods/kernel/registration.js +5 -0
  153. package/dist/core/mods/kernel/site-rules.d.ts +6 -3
  154. package/dist/core/mods/kernel/site-rules.js +10 -2
  155. package/dist/core/mods/session-append.d.ts +115 -0
  156. package/dist/core/mods/session-append.js +311 -0
  157. package/dist/core/mods/session-compact.d.ts +48 -0
  158. package/dist/core/mods/session-compact.js +194 -0
  159. package/dist/core/mods/session-receive.d.ts +93 -0
  160. package/dist/core/mods/session-receive.js +141 -0
  161. package/dist/core/mods/session-send.d.ts +72 -0
  162. package/dist/core/mods/session-send.js +88 -0
  163. package/dist/core/mods/stations.d.ts +38 -16
  164. package/dist/core/mods/stations.js +25 -11
  165. package/dist/core/mods/tool-call.d.ts +2 -0
  166. package/dist/core/mods/tool-call.js +4 -4
  167. package/dist/core/output-style.js +3 -4
  168. package/dist/core/own-property-receipt.d.ts +61 -2
  169. package/dist/core/own-property-receipt.js +42 -2
  170. package/dist/core/park-selfcheck.js +4 -2
  171. package/dist/core/path-identity.d.ts +11 -0
  172. package/dist/core/path-identity.js +4 -0
  173. package/dist/core/path-rule-binding.d.ts +3 -1
  174. package/dist/core/path-rule-binding.js +3 -1
  175. package/dist/core/peer-seat.d.ts +3 -3
  176. package/dist/core/peer-seat.js +20 -8
  177. package/dist/core/permission-rule-consent.d.ts +21 -5
  178. package/dist/core/permission-rule-consent.js +21 -1
  179. package/dist/core/permission-rule-model.d.ts +34 -11
  180. package/dist/core/permission-rule-model.js +47 -10
  181. package/dist/core/permission-rule-org.d.ts +1 -1
  182. package/dist/core/permission-rule-provider.js +4 -1
  183. package/dist/core/permission-rules.d.ts +4 -0
  184. package/dist/core/permission-rules.js +11 -16
  185. package/dist/core/remote-env.d.ts +74 -26
  186. package/dist/core/remote-env.js +20 -0
  187. package/dist/core/retention-policy.d.ts +24 -23
  188. package/dist/core/retention-policy.js +36 -2
  189. package/dist/core/retention.d.ts +4 -1
  190. package/dist/core/retired-keys.d.ts +4 -4
  191. package/dist/core/row-admission.d.ts +10 -0
  192. package/dist/core/row-admission.js +5 -0
  193. package/dist/core/runner/advisor-instructions.d.ts +2 -1
  194. package/dist/core/runner/advisor-instructions.js +2 -1
  195. package/dist/core/runner/announce-once-ledger.d.ts +4 -4
  196. package/dist/core/runner/assemble-result.d.ts +13 -3
  197. package/dist/core/runner/assemble-result.js +12 -7
  198. package/dist/core/runner/caller-roster.d.ts +12 -9
  199. package/dist/core/runner/caller-roster.js +5 -2
  200. package/dist/core/runner/checkpoint-scope.d.ts +16 -1
  201. package/dist/core/runner/checkpoint-scope.js +21 -0
  202. package/dist/core/runner/compact-session.js +14 -2
  203. package/dist/core/runner/compaction-call-options.d.ts +1 -1
  204. package/dist/core/runner/compaction-restate.d.ts +2 -2
  205. package/dist/core/runner/compaction-restate.js +4 -3
  206. package/dist/core/runner/construction-doors.d.ts +2 -2
  207. package/dist/core/runner/construction-doors.js +2 -2
  208. package/dist/core/runner/contracts.d.ts +98 -26
  209. package/dist/core/runner/cross-boundary-lane.d.ts +1 -1
  210. package/dist/core/runner/decide-continuation.d.ts +4 -2
  211. package/dist/core/runner/decide-continuation.js +7 -4
  212. package/dist/core/runner/denial-limit-arms.d.ts +15 -21
  213. package/dist/core/runner/denial-limit-arms.js +17 -10
  214. package/dist/core/runner/expire-settle.d.ts +44 -0
  215. package/dist/core/runner/expire-settle.js +55 -0
  216. package/dist/core/runner/git-status-frame.d.ts +3 -3
  217. package/dist/core/runner/git-status-frame.js +2 -1
  218. package/dist/core/runner/halt-attribution.d.ts +2 -1
  219. package/dist/core/runner/halt-attribution.js +2 -1
  220. package/dist/core/runner/local-claims.d.ts +17 -0
  221. package/dist/core/runner/local-claims.js +18 -0
  222. package/dist/core/runner/media-removed-seat.d.ts +46 -0
  223. package/dist/core/runner/media-removed-seat.js +88 -0
  224. package/dist/core/runner/park-commit.d.ts +2 -2
  225. package/dist/core/runner/permission-rule-lanes.d.ts +5 -1
  226. package/dist/core/runner/permission-rule-lanes.js +28 -9
  227. package/dist/core/runner/person-path-rows.js +1 -1
  228. package/dist/core/runner/placement-fence.d.ts +26 -0
  229. package/dist/core/runner/placement-fence.js +38 -0
  230. package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
  231. package/dist/core/runner/prepare-ask-lane.js +4 -4
  232. package/dist/core/runner/prepare-boundary-parks.d.ts +4 -1
  233. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  234. package/dist/core/runner/prepare-caps-and-workflow.d.ts +2 -0
  235. package/dist/core/runner/prepare-caps-and-workflow.js +1 -0
  236. package/dist/core/runner/prepare-config-doors.js +16 -17
  237. package/dist/core/runner/prepare-context-lane.d.ts +6 -2
  238. package/dist/core/runner/prepare-context-lane.js +13 -13
  239. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -9
  240. package/dist/core/runner/prepare-delegation-surface.js +4 -5
  241. package/dist/core/runner/prepare-execution-env.d.ts +5 -2
  242. package/dist/core/runner/prepare-execution-env.js +7 -4
  243. package/dist/core/runner/prepare-gate-stations.d.ts +19 -14
  244. package/dist/core/runner/prepare-gate-stations.js +6 -4
  245. package/dist/core/runner/prepare-hands-readface.d.ts +5 -5
  246. package/dist/core/runner/prepare-hands-readface.js +4 -4
  247. package/dist/core/runner/prepare-inherited-gate.d.ts +6 -0
  248. package/dist/core/runner/prepare-inherited-gate.js +3 -0
  249. package/dist/core/runner/prepare-lsp.d.ts +3 -0
  250. package/dist/core/runner/prepare-lsp.js +2 -2
  251. package/dist/core/runner/prepare-park-ask.d.ts +5 -2
  252. package/dist/core/runner/prepare-park-ask.js +4 -5
  253. package/dist/core/runner/prepare-policy-chain.d.ts +10 -21
  254. package/dist/core/runner/prepare-policy-chain.js +16 -25
  255. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  256. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -4
  257. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  258. package/dist/core/runner/prepare-question-face.d.ts +6 -4
  259. package/dist/core/runner/prepare-question-face.js +2 -2
  260. package/dist/core/runner/prepare-run-refs.d.ts +3 -0
  261. package/dist/core/runner/prepare-run-refs.js +2 -2
  262. package/dist/core/runner/prepare-suspend-saga.d.ts +11 -7
  263. package/dist/core/runner/prepare-suspend-saga.js +17 -7
  264. package/dist/core/runner/prepare-task.d.ts +1 -1
  265. package/dist/core/runner/prepare-task.js +56 -28
  266. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
  267. package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
  268. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -0
  269. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  270. package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
  271. package/dist/core/runner/prepare-workspace-restore.js +10 -6
  272. package/dist/core/runner/read-root-grant.d.ts +1 -1
  273. package/dist/core/runner/read-root-grant.js +2 -1
  274. package/dist/core/runner/resume-admission.d.ts +5 -3
  275. package/dist/core/runner/resume-admission.js +17 -3
  276. package/dist/core/runner/resume-apply.js +3 -1
  277. package/dist/core/runner/resume-claim.d.ts +8 -3
  278. package/dist/core/runner/resume-claim.js +28 -12
  279. package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
  280. package/dist/core/runner/resume-internals-and-config.js +10 -1
  281. package/dist/core/runner/resume-preflight.d.ts +3 -2
  282. package/dist/core/runner/resume-preflight.js +13 -26
  283. package/dist/core/runner/retired-runner-deps.js +2 -0
  284. package/dist/core/runner/run-git-lane.js +2 -1
  285. package/dist/core/runner/run-harness-handlers.js +2 -2
  286. package/dist/core/runner/run-identity-wiring.d.ts +2 -2
  287. package/dist/core/runner/run-identity-wiring.js +14 -5
  288. package/dist/core/runner/run-leg.d.ts +3 -3
  289. package/dist/core/runner/run-leg.js +40 -29
  290. package/dist/core/runner/run-notification-lane.js +20 -2
  291. package/dist/core/runner/run-recovery-lanes.js +3 -2
  292. package/dist/core/runner/run-settle-and-teardown.js +9 -7
  293. package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
  294. package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
  295. package/dist/core/runner/run-terminal-adoption.js +26 -17
  296. package/dist/core/runner/run-turn-boundary.js +27 -14
  297. package/dist/core/runner/runtask.d.ts +18 -3
  298. package/dist/core/runner/runtask.js +27 -11
  299. package/dist/core/runner/session-rule-policy.d.ts +1 -1
  300. package/dist/core/runner/session-rule-policy.js +6 -1
  301. package/dist/core/runner/shell-env-withheld.d.ts +1 -1
  302. package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
  303. package/dist/core/runner/stream-halt-verbs.js +4 -3
  304. package/dist/core/runner/stream-reap.d.ts +7 -6
  305. package/dist/core/runner/stream-reap.js +13 -16
  306. package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
  307. package/dist/core/runner/stream-settle-backstop.js +5 -3
  308. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  309. package/dist/core/runner/stream-steer-verb.js +8 -7
  310. package/dist/core/runner/terminal-account.d.ts +11 -1
  311. package/dist/core/runner/terminal-account.js +20 -0
  312. package/dist/core/runner/terminal-projection.d.ts +8 -2
  313. package/dist/core/runner/terminal-projection.js +2 -2
  314. package/dist/core/runner/tool-disclosure.d.ts +3 -0
  315. package/dist/core/runner/tool-disclosure.js +5 -2
  316. package/dist/core/runner/tool-end-body.d.ts +3 -3
  317. package/dist/core/runner/tool-end-body.js +1 -1
  318. package/dist/core/runner/tool-output-projection.d.ts +3 -3
  319. package/dist/core/runner/tool-output-projection.js +7 -6
  320. package/dist/core/runner/tool-table-view.d.ts +56 -0
  321. package/dist/core/runner/tool-table-view.js +51 -0
  322. package/dist/core/runner/turn-attachments.d.ts +3 -2
  323. package/dist/core/runner/turn-attachments.js +1 -1
  324. package/dist/core/runner/void-verifier-pause.d.ts +33 -0
  325. package/dist/core/runner/void-verifier-pause.js +41 -0
  326. package/dist/core/runner-deps.d.ts +24 -25
  327. package/dist/core/secret-env.d.ts +11 -11
  328. package/dist/core/secret-env.js +8 -9
  329. package/dist/core/session-log-transfer.js +9 -10
  330. package/dist/core/session-policy-store.d.ts +1 -1
  331. package/dist/core/session-policy-store.js +5 -2
  332. package/dist/core/session-reconcile.d.ts +3 -2
  333. package/dist/core/session-reconcile.js +7 -4
  334. package/dist/core/session-store.d.ts +2 -0
  335. package/dist/core/session-store.js +5 -7
  336. package/dist/core/session.d.ts +2 -1
  337. package/dist/core/shell-confinement.d.ts +37 -0
  338. package/dist/core/shell-confinement.js +56 -0
  339. package/dist/core/skill-grant.js +1 -1
  340. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +2 -2
  341. package/dist/core/store-contracts/checkpoint-store-contract.js +15 -2
  342. package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
  343. package/dist/core/store-contracts/file-history-store-contract.js +25 -1
  344. package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
  345. package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
  346. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  347. package/dist/core/store-contracts/tool-result-store-contract.js +30 -0
  348. package/dist/core/task-event.d.ts +17 -8
  349. package/dist/core/task-limits.d.ts +5 -0
  350. package/dist/core/task-notification.d.ts +89 -12
  351. package/dist/core/task-notification.js +87 -13
  352. package/dist/core/task-registry-agent.d.ts +5 -43
  353. package/dist/core/task-registry-agent.js +24 -51
  354. package/dist/core/task-registry-monitor.d.ts +1 -1
  355. package/dist/core/task-registry-monitor.js +15 -60
  356. package/dist/core/task-registry-shared.d.ts +15 -112
  357. package/dist/core/task-registry-shared.js +3 -41
  358. package/dist/core/task-registry-workflow.js +4 -21
  359. package/dist/core/task-registry.d.ts +19 -60
  360. package/dist/core/task-registry.js +19 -106
  361. package/dist/core/task-result.d.ts +24 -7
  362. package/dist/core/task-spec-members.d.ts +39 -0
  363. package/dist/core/task-spec-members.js +92 -0
  364. package/dist/core/task-spec.d.ts +10 -10
  365. package/dist/core/task-tool-shape.d.ts +7 -57
  366. package/dist/core/task-tool-shape.js +7 -66
  367. package/dist/core/terminal-cause.d.ts +30 -0
  368. package/dist/core/terminal-cause.js +1 -0
  369. package/dist/core/tool-catalog-entries.js +2 -5
  370. package/dist/core/tool-check-reading.js +16 -10
  371. package/dist/core/tool-conformance.js +1 -2
  372. package/dist/core/tool-errors.d.ts +6 -3
  373. package/dist/core/tool-errors.js +2 -0
  374. package/dist/core/tool-face-reader.js +3 -2
  375. package/dist/core/tool-face.d.ts +2 -3
  376. package/dist/core/tool-name-aliases.d.ts +5 -29
  377. package/dist/core/tool-name-aliases.js +9 -5
  378. package/dist/core/tool-name-readings.d.ts +14 -3
  379. package/dist/core/tool-name-readings.js +2 -0
  380. package/dist/core/tool-policy.d.ts +108 -18
  381. package/dist/core/tool-policy.js +84 -14
  382. package/dist/core/tool-result-store.d.ts +23 -0
  383. package/dist/core/tool-result-store.js +3 -2
  384. package/dist/core/tool-spec.d.ts +19 -6
  385. package/dist/core/trace.d.ts +18 -1
  386. package/dist/core/user-attachment.js +26 -21
  387. package/dist/core/workflow-journal-store.d.ts +1 -1
  388. package/dist/core/workflow-run-store.d.ts +2 -0
  389. package/dist/core/workflow-run-store.js +6 -5
  390. package/dist/core/workflow-settled-run.d.ts +5 -0
  391. package/dist/core/workflow-settled-run.js +7 -0
  392. package/dist/engine/execution-env/node-execution-env.d.ts +34 -9
  393. package/dist/engine/execution-env/node-execution-env.js +213 -21
  394. package/dist/engine/harness/agent-harness.d.ts +65 -18
  395. package/dist/engine/harness/agent-harness.js +90 -23
  396. package/dist/engine/harness/messages.d.ts +4 -3
  397. package/dist/engine/harness/messages.js +2 -2
  398. package/dist/engine/harness/types.d.ts +41 -7
  399. package/dist/engine/llm/media-removed.d.ts +14 -0
  400. package/dist/engine/llm/media-removed.js +9 -0
  401. package/dist/engine/llm/rejected-images.d.ts +35 -25
  402. package/dist/engine/llm/rejected-images.js +59 -10
  403. package/dist/engine/llm/types.d.ts +24 -3
  404. package/dist/engine/llm/types.js +7 -3
  405. package/dist/engine/loop/agent-loop.d.ts +6 -1
  406. package/dist/engine/loop/agent-loop.js +20 -11
  407. package/dist/engine/loop/types.d.ts +12 -3
  408. package/dist/engine/session/import-validate.js +7 -0
  409. package/dist/fixtures/index.d.ts +7 -5
  410. package/dist/fixtures/index.js +5 -3
  411. package/dist/index.d.ts +21 -11
  412. package/dist/index.js +15 -7
  413. package/dist/internal/harness-types.d.ts +2 -0
  414. package/dist/internal/llm.d.ts +2 -1
  415. package/dist/internal/llm.js +1 -0
  416. package/dist/orchestration/goal.d.ts +6 -2
  417. package/dist/orchestration/goal.js +6 -3
  418. package/dist/orchestration/run-workflow-tool.d.ts +11 -17
  419. package/dist/orchestration/run-workflow-tool.js +19 -42
  420. package/dist/orchestration/workflow-governance.d.ts +1 -1
  421. package/dist/orchestration/workflow-types.d.ts +2 -2
  422. package/dist/orchestration/workflow.d.ts +4 -0
  423. package/dist/orchestration/workflow.js +8 -5
  424. package/dist/stores/file/background-agent-store.js +18 -15
  425. package/dist/stores/file/checkpoint-store.js +7 -4
  426. package/dist/stores/file/file-history-store.js +3 -2
  427. package/dist/stores/file/index.d.ts +5 -3
  428. package/dist/stores/file/index.js +23 -8
  429. package/dist/stores/file/ledger-tuning.d.ts +23 -0
  430. package/dist/stores/file/ledger-tuning.js +21 -0
  431. package/dist/stores/file/mailbox-store.js +42 -22
  432. package/dist/stores/file/memory-store.js +3 -2
  433. package/dist/stores/file/permission-rule-adopt.js +24 -21
  434. package/dist/stores/file/permission-rule-store.js +6 -3
  435. package/dist/stores/file/session-policy-store.js +3 -2
  436. package/dist/stores/file/session-store.d.ts +16 -3
  437. package/dist/stores/file/session-store.js +21 -20
  438. package/dist/stores/file/tool-result-store.d.ts +11 -0
  439. package/dist/stores/file/tool-result-store.js +57 -3
  440. package/dist/stores/file/usage-window-store.js +3 -2
  441. package/dist/stores/file/workflow-journal-store.d.ts +0 -2
  442. package/dist/stores/file/workflow-journal-store.js +3 -18
  443. package/dist/stores/file/workflow-run-store.d.ts +1 -1
  444. package/dist/stores/file/workflow-run-store.js +15 -10
  445. package/dist/tools/fs/dead-cwd.d.ts +5 -5
  446. package/dist/tools/fs/dead-cwd.js +4 -11
  447. package/dist/tools/fs/fs-bash-background-text.d.ts +6 -0
  448. package/dist/tools/fs/fs-bash-background-text.js +6 -0
  449. package/dist/tools/fs/fs-bash.d.ts +3 -18
  450. package/dist/tools/fs/fs-bash.js +37 -124
  451. package/dist/tools/fs/fs-pdf.js +8 -6
  452. package/dist/tools/fs/fs-read.js +2 -2
  453. package/dist/tools/fs/fs-shared.d.ts +28 -3
  454. package/dist/tools/fs/fs-shared.js +15 -0
  455. package/dist/tools/fs/index.d.ts +1 -1
  456. package/dist/tools/fs/index.js +4 -14
  457. package/dist/tools/fs/pdf.d.ts +4 -4
  458. package/dist/tools/fs/pdf.js +6 -6
  459. package/dist/tools/fs/read-deny-home.js +8 -1
  460. package/dist/tools/fs/read-deny.d.ts +26 -2
  461. package/dist/tools/fs/read-deny.js +9 -2
  462. package/dist/tools/fs/read-floor.d.ts +13 -5
  463. package/dist/tools/fs/read-floor.js +206 -2
  464. package/dist/tools/fs/search.d.ts +3 -2
  465. package/dist/tools/fs/search.js +6 -6
  466. package/dist/tools/fs/shell-read-establish.js +3 -1
  467. package/dist/tools/fs/shell-read-identity.d.ts +3 -1
  468. package/dist/tools/fs/shell-read-identity.js +4 -2
  469. package/dist/tools/fs/shell-read-judge.d.ts +7 -1
  470. package/dist/tools/fs/shell-read-judge.js +1 -1
  471. package/dist/tools/monitor.d.ts +8 -7
  472. package/dist/tools/monitor.js +12 -10
  473. package/dist/tools/worktree.d.ts +5 -1
  474. package/dist/tools/worktree.js +20 -17
  475. package/package.json +6 -3
  476. package/test/export-surface.snapshot.json +92 -10
  477. package/wire-changes/core-stores-sql@7.61.0.json +480 -0
  478. package/wire-changes/core@7.61.0.json +4405 -0
  479. package/wire-changes/mods-kernel@7.61.0.json +65 -0
  480. package/wire-changes/primitives@7.61.0.json +30 -0
  481. package/dist/core/runner/image-removed-seat.d.ts +0 -12
  482. package/dist/core/runner/image-removed-seat.js +0 -19
@@ -96,7 +96,8 @@ export type TraceEvent = {
96
96
  version: 1;
97
97
  taskId: string;
98
98
  /** The ENGINE-minted identity of THIS run (`TaskResult.runId`). `taskId` is
99
- * `spec.taskId ?? sessionId`, so two runs of one session that declare no host task id emit two
99
+ * the leg's task id (a background row's id, else the declared one, else the session id), so two
100
+ * runs of one session that declare no host task id emit two
100
101
  * task.start frames under ONE id and a consumer pairing start↔end has no way to say which end
101
102
  * closes which start. Present on every `task.start` (the frame is emitted after prepare, which
102
103
  * is where the id is minted).
@@ -924,6 +925,22 @@ export type TraceEvent = {
924
925
  /** True = store.put failed (or no store): the model lost read-back for this result. */
925
926
  storeFallback: boolean;
926
927
  ts: number;
928
+ } | {
929
+ /** A request's media trim (`media-byte-cap.ts`) left blocks out of a request that was sent: one frame per such
930
+ * request (the person hears each block once per session, `context.media_removed`). `items` / `base64Chars` are the
931
+ * request's media before the trim; `budgetBase64Chars` is absent when the deployment set no budget. */
932
+ kind: "context.media_removed";
933
+ version: 1;
934
+ taskId: string;
935
+ reason: "media_budget";
936
+ images: number;
937
+ documents: number;
938
+ removedBase64Chars: number;
939
+ items: number;
940
+ base64Chars: number;
941
+ maxItems: number;
942
+ budgetBase64Chars?: number;
943
+ ts: number;
927
944
  } | {
928
945
  /** C4 — image blocks were replaced with text placeholders because the served model declares no
929
946
  * vision input (`ModelSpec.input` without "image"). Silent quality loss without this. */
@@ -10,8 +10,10 @@ import { MARKED_BLOCK_AFTER_DATA, mintSystemReminder } from "./reminder-mint.js"
10
10
  import { commitReminderDisclosureEffects, planReminderDisclosure } from "./reminder-disclosure.js";
11
11
  import { DEFAULT_CHARS_PER_TOKEN, estimateTokens, uuidv7 } from "../internal/harness.js";
12
12
  import { thrownText } from "./thrown-value.js";
13
+ import { optionKeys, receiveMembers } from "./own-property-receipt.js";
13
14
  import { guardBudget } from "./context-guard.js";
14
- import { agentIdOf, failedHandlerClause } from "./mods/stations.js";
15
+ import { failedHandlerClause } from "./mods/stations.js";
16
+ import { agentIdOf } from "./leg-identity.js";
15
17
  import { extensionWords } from "./untrusted-egress.js";
16
18
  export const USER_ATTACHMENTS_MAX = 20;
17
19
  export const USER_ATTACHMENT_LABEL_MAX = 4096;
@@ -75,10 +77,13 @@ function screenPositiveInt(v, at) {
75
77
  throw userAttachmentRefusal(at, "must be an integer of at least 1.");
76
78
  return v;
77
79
  }
78
- function onlyMembers(o, allowed, at) {
79
- for (const k of Object.keys(o))
80
- if (!allowed.includes(k))
81
- throw userAttachmentRefusal(memberRef(at, k), `is not a member of this attachment (allowed: ${allowed.join(", ")}).`);
80
+ const PATH_KEYS = optionKeys()({ path: 0, lines: 0 });
81
+ const LINES_KEYS = optionKeys()({ start: 0, end: 0 });
82
+ const TEXT_KEYS = optionKeys()({ name: 0, text: 0, startLine: 0 });
83
+ const IMAGE_KEYS = optionKeys()({ name: 0, image: 0 });
84
+ const IMAGE_BYTES_KEYS = optionKeys()({ data: 0, mimeType: 0 });
85
+ function onlyMembers(o, keys, at) {
86
+ return receiveMembers(o, { subject: at.path, unit: "member", moment: "when the attachment is screened" }, keys, (_, [k]) => userAttachmentRefusal(memberRef(at, String(k)), `is not a member of this attachment (allowed: ${keys.join(", ")}).`));
82
87
  }
83
88
  function screenEntry(raw, at) {
84
89
  if (!isPlainObject(raw))
@@ -90,17 +95,17 @@ function screenEntry(raw, at) {
90
95
  }
91
96
  switch (arm) {
92
97
  case "path": {
93
- onlyMembers(raw, ["path", "lines"], at);
94
- const path = screenLabel(raw.path, memberRef(at, "path"));
95
- const linesRaw = raw.lines;
98
+ const entry = onlyMembers(raw, PATH_KEYS, at);
99
+ const path = screenLabel(entry.path, memberRef(at, "path"));
100
+ const linesRaw = entry.lines;
96
101
  if (linesRaw === undefined)
97
102
  return { supply: "path", path };
98
103
  const linesAt = memberRef(at, "lines");
99
104
  if (!isPlainObject(linesRaw))
100
105
  throw userAttachmentRefusal(linesAt, "must be { start, end? }.");
101
- onlyMembers(linesRaw, ["start", "end"], linesAt);
102
- const start = screenPositiveInt(linesRaw.start, memberRef(linesAt, "start"));
103
- const endRaw = linesRaw.end;
106
+ const lines = onlyMembers(linesRaw, LINES_KEYS, linesAt);
107
+ const start = screenPositiveInt(lines.start, memberRef(linesAt, "start"));
108
+ const endRaw = lines.end;
104
109
  if (endRaw === undefined)
105
110
  return { supply: "path", path, lines: { start } };
106
111
  const end = screenPositiveInt(endRaw, memberRef(linesAt, "end"));
@@ -109,27 +114,27 @@ function screenEntry(raw, at) {
109
114
  return { supply: "path", path, lines: { start, end } };
110
115
  }
111
116
  case "text": {
112
- onlyMembers(raw, ["name", "text", "startLine"], at);
113
- const name = screenLabel(raw.name, memberRef(at, "name"));
114
- const text = raw.text;
117
+ const entry = onlyMembers(raw, TEXT_KEYS, at);
118
+ const name = screenLabel(entry.name, memberRef(at, "name"));
119
+ const text = entry.text;
115
120
  if (typeof text !== "string" || text.length === 0)
116
121
  throw userAttachmentRefusal(memberRef(at, "text"), "must be a non-empty string.");
117
- const startLine = raw.startLine === undefined ? 1 : screenPositiveInt(raw.startLine, memberRef(at, "startLine"));
122
+ const startLine = entry.startLine === undefined ? 1 : screenPositiveInt(entry.startLine, memberRef(at, "startLine"));
118
123
  const rendered = renderNumbered(text, startLine);
119
124
  if (rendered.length > MAX_READ_OUTPUT_CHARS)
120
125
  throw userAttachmentRefusal(memberRef(at, "text"), `renders to ${rendered.length} characters with line numbers, over the ${MAX_READ_OUTPUT_CHARS}-character limit a read may deliver — send a part of it.`);
121
126
  return { supply: "content_text", name, text, startLine, rendered };
122
127
  }
123
128
  case "image": {
124
- onlyMembers(raw, ["name", "image"], at);
125
- const name = screenLabel(raw.name, memberRef(at, "name"));
126
- const img = raw.image;
129
+ const entry = onlyMembers(raw, IMAGE_KEYS, at);
130
+ const name = screenLabel(entry.name, memberRef(at, "name"));
131
+ const img = entry.image;
127
132
  const imageAt = memberRef(at, "image");
128
133
  if (!isPlainObject(img))
129
134
  throw userAttachmentRefusal(imageAt, "must be { data, mimeType } (base64 bytes and the image's type).");
130
- onlyMembers(img, ["data", "mimeType"], imageAt);
131
- const data = img.data;
132
- const mimeType = img.mimeType;
135
+ const bytes = onlyMembers(img, IMAGE_BYTES_KEYS, imageAt);
136
+ const data = bytes.data;
137
+ const mimeType = bytes.mimeType;
133
138
  if (typeof data !== "string" || data.length === 0)
134
139
  throw userAttachmentRefusal(memberRef(imageAt, "data"), "must be a non-empty base64 string.");
135
140
  if (typeof mimeType !== "string" || !ADMITTED_IMAGE_MIME_TYPES.includes(mimeType)) {
@@ -135,7 +135,7 @@ export interface WorkflowJournalStore {
135
135
  /** (CC diagnostics parity, additive): a HUMAN/MODEL-readable coordinate for this run's journal —
136
136
  * the file store returns the on-disk jsonl path (CC "Read journal.jsonl" local form); a service store
137
137
  * returns its API route (cloud form). `undefined`/absent ⇒ the completion notification's diagnostics
138
- * line teaches only the TaskOutput route (which is always live). Engine-facing string, never parsed. */
138
+ * line names no journal (the record behind its ref still carries every agent's row). Engine-facing string, never parsed. */
139
139
  locator?(runId: string, scope: string): string | undefined;
140
140
  /**
141
141
  * ADMISSION for a resume, so two concurrent
@@ -222,6 +222,8 @@ export declare function queryWorkflowRuns(runs: Iterable<WorkflowRun>, scope: st
222
222
  * `WorkflowRun` the workflow keeps mutating — must not corrupt the stored row, and a returned run must not
223
223
  * be a live reference the caller can mutate back into the store).
224
224
  */
225
+ /** The retention knobs a workflow-run `reap` takes: an age bound and a keep-newest-N bound over the terminal runs. */
226
+ export declare const WORKFLOW_RUN_REAP_KNOBS: readonly ["maxAgeMs", "keep"];
225
227
  export declare class InMemoryWorkflowRunStore implements WorkflowRunStore {
226
228
  private runs;
227
229
  put(id: string, run: WorkflowRun): Promise<void>;
@@ -1,5 +1,5 @@
1
1
  import { runParkedOf } from "../orchestration/workflow-types.js";
2
- import { assertRetentionPolicy } from "./retention-policy.js";
2
+ import { receiveRetentionPolicy } from "./retention-policy.js";
3
3
  export function summarizeWorkflowRun(run) {
4
4
  const latestPhase = run.phases.at(-1);
5
5
  return {
@@ -53,6 +53,7 @@ export function queryWorkflowRuns(runs, scope, opts) {
53
53
  const limited = opts?.limit !== undefined ? rows.slice(0, Math.max(0, opts.limit)) : rows;
54
54
  return limited.map(summarizeWorkflowRun);
55
55
  }
56
+ export const WORKFLOW_RUN_REAP_KNOBS = Object.freeze(["maxAgeMs", "keep"]);
56
57
  export class InMemoryWorkflowRunStore {
57
58
  runs = new Map();
58
59
  async put(id, run) {
@@ -79,16 +80,16 @@ export class InMemoryWorkflowRunStore {
79
80
  return queryWorkflowRuns(this.runs.values(), scope, opts);
80
81
  }
81
82
  async reap(scope, now, opts) {
82
- assertRetentionPolicy("WorkflowRunStore.reap", opts);
83
- if (opts?.maxAgeMs === undefined && opts?.keep === undefined)
83
+ const policy = receiveRetentionPolicy("WorkflowRunStore.reap", opts, WORKFLOW_RUN_REAP_KNOBS);
84
+ if (policy.maxAgeMs === undefined && policy.keep === undefined)
84
85
  return 0;
85
86
  const terminal = [...this.runs.values()].filter((r) => r.scope === scope && isTerminalWorkflowStatus(r.status));
86
87
  terminal.sort((a, b) => b.createdAt - a.createdAt);
87
88
  const doomed = new Set();
88
89
  for (let i = 0; i < terminal.length; i++) {
89
90
  const r = terminal[i];
90
- const tooOld = opts.maxAgeMs !== undefined && (r.endedAt ?? r.createdAt) < now - opts.maxAgeMs;
91
- const overKeep = opts.keep !== undefined && i >= opts.keep;
91
+ const tooOld = policy.maxAgeMs !== undefined && (r.endedAt ?? r.createdAt) < now - policy.maxAgeMs;
92
+ const overKeep = policy.keep !== undefined && i >= policy.keep;
92
93
  if (tooOld || overKeep)
93
94
  doomed.add(r.id);
94
95
  }
@@ -0,0 +1,5 @@
1
+ import type { WorkflowRun } from "../orchestration/workflow-types.js";
2
+ /** Bind `run` to the `done` promise that settles for it — the run's starter, once, before the promise is handed out. */
3
+ export declare function bindSettledRun(done: Promise<unknown>, run: WorkflowRun): void;
4
+ /** The run `done` settles for; `undefined` for a promise no run was bound to (a handle its caller assembled itself). */
5
+ export declare function settledRunOf(done: Promise<unknown>): WorkflowRun | undefined;
@@ -0,0 +1,7 @@
1
+ const runOfDone = new WeakMap();
2
+ export function bindSettledRun(done, run) {
3
+ runOfDone.set(done, run);
4
+ }
5
+ export function settledRunOf(done) {
6
+ return runOfDone.get(done);
7
+ }
@@ -1,7 +1,7 @@
1
1
  import { type FileHandle } from "node:fs/promises";
2
2
  import { type BoundFileObject, type ExecResult, type ExecutionEnv, ExecutionError, type ExecutionEnvExecOptions, FileError, type FileInfo, type Result } from "../harness/types.js";
3
3
  import { type SecretEnvFinding } from "../../core/secret-env.js";
4
- import type { EngineNotice } from "../../core/engine-notice.js";
4
+ import { type EngineNotice } from "../../core/engine-notice.js";
5
5
  import type { ExecutionEnvCapabilities, SymlinkChain } from "../harness/types.js";
6
6
  import type { BackgroundHardKillOutcome, BackgroundShellCapability, BackgroundShellId, BackgroundPoll, BackgroundSpawnOptions } from "../../core/background-shell.js";
7
7
  import { BackgroundShellError } from "../../core/background-shell.js";
@@ -83,8 +83,13 @@ export declare function openSpoolPair(base: string): {
83
83
  export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCapability, SchedulerCapability {
84
84
  cwd: string;
85
85
  /** `ExecutionEnv.capabilities`: the engine's own host — commands are this process's children on its own disk, not
86
- * contained, not snapshotable; its resolver always answers; it does not keep the byte floor (no process confinement). */
86
+ * contained, not snapshotable; its resolver always answers; it keeps the byte floor exactly when its starts are confined
87
+ * (`readFloorConfinement: "os"` on a host where the probe applied), and otherwise does not. */
87
88
  readonly capabilities: ExecutionEnvCapabilities;
89
+ /** Every start carrying a floor runs under that floor's seatbelt profile (the probe applied at construction). */
90
+ private readonly confined;
91
+ /** Each profile's apply, once per text: `undefined` applied, else the launcher's reason. */
92
+ private readonly profileApplies;
88
93
  /** `ExecutionEnv.homeDir` = the `HOME` the shell child receives (its `~`/`$HOME`/`${HOME}` all expand to it), read LIVE off the same `shellEnv`-over-`inheritEnv` merge each exec gets; ABSENT when the
89
94
  * child gets none (an allowlist that withholds it: `~` then falls back to passwd while `$HOME` is empty — two values, no single home, home-relative operands stay fail-closed). Residual: a per-exec `env.HOME` override. */
90
95
  get homeDir(): string | undefined;
@@ -154,6 +159,13 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
154
159
  * `code: "config.secret_env_scrubbed"`, `detail.names`); independent of `onSecretEnvScrub` (a raw
155
160
  * findings collector) except: that seat wired alone stays console-silent, as before this existed. */
156
161
  onNotice?: (notice: EngineNotice) => void;
162
+ /** Confine every start that carries a byte floor (`ExecutionEnvExecOptions.readFloor`) at the OS: `"os"` = on macOS,
163
+ * when the seatbelt base applies here (probed once, now), each such start runs under `sandbox-exec -p <the floor's
164
+ * profile>` and the environment declares `keepsReadFloor: true`; a floor the profile cannot express, or a profile that
165
+ * does not apply, refuses that start (`spawn_error` / `spawn_failed`, naming why) — it never runs unconfined. On any
166
+ * other host, or when the probe does not apply, the environment declares `false` and says so once on `onNotice`
167
+ * (`config.read_floor_confinement_unavailable`). Absent = no confinement (`false`). Any other value throws. */
168
+ readFloorConfinement?: "os";
157
169
  });
158
170
  get schedulerCapabilities(): SchedulerCapability["schedulerCapabilities"];
159
171
  schedule(intent: ScheduledIntent, ctx: SchedulerContext): Promise<Result<{
@@ -163,6 +175,10 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
163
175
  list(ctx: SchedulerContext): Promise<Result<ScheduledTaskSummary[], SchedulerError>>;
164
176
  absolutePath(path: string): Promise<Result<string, FileError>>;
165
177
  joinPath(parts: string[]): Promise<Result<string, FileError>>;
178
+ /** The program and arguments ONE shell start spawns: the shell as it is, or — on a confined environment, for a start
179
+ * carrying a floor — the shell under that floor's seatbelt profile; a floor the profile cannot express, or a profile the
180
+ * host does not apply, is the reason the start is refused (the command never runs, confined or not). */
181
+ private startOf;
166
182
  exec(command: string, options?: ExecutionEnvExecOptions): Promise<Result<ExecResult, ExecutionError>>;
167
183
  readTextFile(path: string, abortSignal?: AbortSignal): Promise<Result<string, FileError>>;
168
184
  readTextLines(path: string, options?: {
@@ -174,20 +190,29 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
174
190
  * The former single-step `writeFile` was an in-place O_TRUNC: an abort mid-write
175
191
  * (Esc during a large Write — ctx.signal reaches here directly), ENOSPC, or a crash left the target as
176
192
  * a torn prefix of the NEW content with the original unrecoverable. Post-fix contract: the target is
177
- * either fully old or fully new; `aborted` means it was never touched. Known semantic change (same as
178
- * CC): rename breaks a hard link — the other link keeps the old content. The replacement is a new inode made
179
- * by the writing process: its owner is the writer and its group follows the new-file rule, so the target's
180
- * group bits can land on another group; no fchown (KL-3120-b). */
193
+ * either fully old or fully new; `aborted` means it was never touched — the in-place fallback legs
194
+ * judge the signal once, before their first byte, so they answer `aborted` (untouched), `ok` or their own
195
+ * error, never `aborted` after a truncation. Known semantic change (same as CC): rename breaks a hard link —
196
+ * the other link keeps the old content. The replacement is a new inode made by the writing process: its owner
197
+ * is the writer and its group follows the new-file rule, so the target's group bits can land on another group;
198
+ * no fchown (KL-3120-b). */
181
199
  writeFile(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
182
200
  /** RB-221: the historical single-step in-place overwrite — kept for targets where
183
201
  * staging+rename would change node identity (symlink chains, non-regular files) and as the
184
- * CC-parity fallback for filesystems where the rename cannot work. NOT atomic by design. */
202
+ * CC-parity fallback for filesystems where the rename cannot work. NOT atomic by design, and
203
+ * deliberately not cancellable: the signal is judged once, here, before the first byte, and not again —
204
+ * so `aborted` never describes a target this write has truncated. */
185
205
  private writeFileInPlace;
186
206
  /** Atomic exclusive create ({@link FileSystem.writeFileExclusive}): Node `wx` flag = one
187
207
  * `open(O_CREAT|O_EXCL)` syscall — an existing file returns FileError `"already_exists"` and is left
188
208
  * untouched. The EEXIST→already_exists mapping lives HERE, on the exclusive-open step only — a parent
189
209
  * `mkdir` can also throw EEXIST (parent path component is a regular file) and that is NOT "the target
190
- * already exists" (fable review). Parent directories are created like writeFile. */
210
+ * already exists" (fable review). Parent directories are created like writeFile.
211
+ *
212
+ * The signal is judged before the first byte — at entry and after the parent `mkdir` — and is not handed to the write: the
213
+ * exclusive open creates the target itself, so a write cancelled after it would leave a new file holding a prefix of the
214
+ * content under an `aborted` answer. `aborted` therefore means no file was created; a write whose open has begun runs to its
215
+ * end and answers `ok` or its own error (the same rule as the in-place legs of {@link NodeExecutionEnv.writeFile}). */
191
216
  writeFileExclusive(path: string, content: string | Uint8Array, abortSignal?: AbortSignal): Promise<Result<void, FileError>>;
192
217
  appendFile(path: string, content: string | Uint8Array): Promise<Result<void, FileError>>;
193
218
  fileInfo(path: string): Promise<Result<FileInfo, FileError>>;
@@ -241,7 +266,7 @@ export declare class NodeExecutionEnv implements ExecutionEnv, BackgroundShellCa
241
266
  suffix?: string;
242
267
  }): Promise<Result<string, FileError>>;
243
268
  /** design/116 detach: adopt a RUNNING foreground child as a background shell. Pre-fills the bg tails with
244
- * the output captured so far (so TaskOutput's first read has the full history), attaches fresh data/close
269
+ * the output captured so far (so the first background read has the full history), attaches fresh data/close
245
270
  * handlers, and arms the default bg timeout. Returns undefined when the live-shell limit is hit (detach
246
271
  * refused; the exec keeps running in the foreground). */
247
272
  private adoptRunningChild;