@sema-agent/core 7.58.0 → 7.60.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 (519) hide show
  1. package/CHANGELOG.md +1340 -0
  2. package/README.md +6 -4
  3. package/dist/agents/agent-definition.d.ts +7 -0
  4. package/dist/agents/agent-definition.js +12 -0
  5. package/dist/agents/agent-transcript-tool.d.ts +2 -1
  6. package/dist/agents/agent-transcript-tool.js +3 -1
  7. package/dist/agents/cc-peer-directory.js +8 -8
  8. package/dist/agents/child-model-seat.d.ts +4 -2
  9. package/dist/agents/child-model-seat.js +9 -4
  10. package/dist/agents/cumulative-stats.js +0 -1
  11. package/dist/agents/inherited-tool-pool.d.ts +26 -1
  12. package/dist/agents/inherited-tool-pool.js +22 -0
  13. package/dist/agents/peer-directory.d.ts +9 -0
  14. package/dist/agents/peer-directory.js +6 -2
  15. package/dist/agents/retain-ledger.d.ts +11 -1
  16. package/dist/agents/retain-ledger.js +13 -2
  17. package/dist/agents/roster-store.d.ts +1 -1
  18. package/dist/agents/roster-store.js +3 -1
  19. package/dist/agents/send-message-tool.d.ts +8 -19
  20. package/dist/agents/send-message-tool.js +32 -50
  21. package/dist/agents/subagent.d.ts +51 -17
  22. package/dist/agents/subagent.js +150 -112
  23. package/dist/agents/tool-filter.d.ts +1 -3
  24. package/dist/agents/tool-filter.js +4 -12
  25. package/dist/bench/metrics.d.ts +3 -5
  26. package/dist/bench/metrics.js +0 -1
  27. package/dist/brain/anthropic.js +161 -45
  28. package/dist/brain/degrading.js +3 -1
  29. package/dist/brain/errors.d.ts +9 -3
  30. package/dist/brain/errors.js +7 -1
  31. package/dist/brain/failover.js +2 -1
  32. package/dist/brain/open-responses.js +3 -3
  33. package/dist/brain/openai.js +103 -53
  34. package/dist/brain/provider-dialect.d.ts +11 -0
  35. package/dist/brain/provider-dialect.js +5 -2
  36. package/dist/brain/reasoning-request.js +5 -4
  37. package/dist/brain/reasoning.d.ts +19 -0
  38. package/dist/brain/reasoning.js +17 -2
  39. package/dist/brain/request-route.d.ts +4 -1
  40. package/dist/brain/request-route.js +4 -1
  41. package/dist/brain/route-adjudicator.d.ts +84 -18
  42. package/dist/brain/route-adjudicator.js +90 -22
  43. package/dist/brain/route-conformance.js +1 -1
  44. package/dist/brain/status-sink.d.ts +7 -1
  45. package/dist/brain/status-sink.js +6 -0
  46. package/dist/brain/stream-engine.js +84 -49
  47. package/dist/brain/stream-shared.d.ts +30 -0
  48. package/dist/brain/stream-shared.js +34 -1
  49. package/dist/brain/timeout.d.ts +65 -6
  50. package/dist/brain/timeout.js +111 -11
  51. package/dist/core/a2a.d.ts +15 -5
  52. package/dist/core/a2a.js +34 -19
  53. package/dist/core/account-row.d.ts +61 -0
  54. package/dist/core/account-row.js +51 -0
  55. package/dist/core/advisor-verdict.d.ts +2 -1
  56. package/dist/core/advisor-verdict.js +1 -1
  57. package/dist/core/agent-definition.d.ts +20 -0
  58. package/dist/core/allow-entry.d.ts +20 -6
  59. package/dist/core/allow-entry.js +17 -7
  60. package/dist/core/approval-object.d.ts +29 -15
  61. package/dist/core/approval-object.js +47 -19
  62. package/dist/core/artifact-host.d.ts +0 -2
  63. package/dist/core/artifact-host.js +0 -1
  64. package/dist/core/auto-compaction.js +1 -1
  65. package/dist/core/auto-mode-defaults.d.ts +8 -0
  66. package/dist/core/auto-mode-defaults.js +1 -0
  67. package/dist/core/auto-mode-rebuild.d.ts +2 -1
  68. package/dist/core/auto-mode.d.ts +39 -4
  69. package/dist/core/auto-mode.js +63 -12
  70. package/dist/core/background-agent-store.d.ts +26 -4
  71. package/dist/core/background-agent-store.js +3 -2
  72. package/dist/core/background-shell.d.ts +12 -1
  73. package/dist/core/background-shell.js +12 -0
  74. package/dist/core/checkpoint-requirements.d.ts +13 -1
  75. package/dist/core/checkpoint-requirements.js +3 -1
  76. package/dist/core/checkpoint-store.d.ts +66 -25
  77. package/dist/core/checkpoint-store.js +22 -9
  78. package/dist/core/child-clamp-seats.d.ts +29 -0
  79. package/dist/core/child-clamp-seats.js +56 -1
  80. package/dist/core/compliance.d.ts +3 -3
  81. package/dist/core/compliance.js +1 -1
  82. package/dist/core/credential-echo.d.ts +52 -0
  83. package/dist/core/credential-echo.js +65 -0
  84. package/dist/core/credential-vocabulary.d.ts +13 -3
  85. package/dist/core/credential-vocabulary.js +12 -4
  86. package/dist/core/cross-boundary-taint.d.ts +4 -5
  87. package/dist/core/effective-path-target.d.ts +8 -2
  88. package/dist/core/effective-path-target.js +8 -3
  89. package/dist/core/engine-notice.d.ts +156 -23
  90. package/dist/core/engine-notice.js +19 -5
  91. package/dist/core/frame-settlement.d.ts +5 -0
  92. package/dist/core/frame-settlement.js +4 -0
  93. package/dist/core/gate-fold.js +8 -6
  94. package/dist/core/gate-lanes.js +47 -12
  95. package/dist/core/gate-outcome.d.ts +32 -3
  96. package/dist/core/gate-outcome.js +19 -1
  97. package/dist/core/governance-codes.d.ts +17 -1
  98. package/dist/core/governance-codes.js +25 -0
  99. package/dist/core/hands-band-screen.js +0 -1
  100. package/dist/core/hands-band.d.ts +0 -3
  101. package/dist/core/hooks.d.ts +70 -59
  102. package/dist/core/hooks.js +125 -80
  103. package/dist/core/image-admission.d.ts +106 -52
  104. package/dist/core/image-admission.js +184 -56
  105. package/dist/core/image-downsample.d.ts +36 -69
  106. package/dist/core/image-downsample.js +111 -73
  107. package/dist/core/integer-option.d.ts +21 -0
  108. package/dist/core/integer-option.js +13 -0
  109. package/dist/core/locked-config.d.ts +59 -5
  110. package/dist/core/locked-config.js +82 -50
  111. package/dist/core/mailbox-store.d.ts +45 -1
  112. package/dist/core/mailbox-store.js +53 -9
  113. package/dist/core/mcp-call-meta.d.ts +2 -2
  114. package/dist/core/mcp-call-meta.js +9 -10
  115. package/dist/core/mcp-failure.d.ts +122 -20
  116. package/dist/core/mcp-failure.js +73 -5
  117. package/dist/core/mcp-host-seat.d.ts +92 -0
  118. package/dist/core/mcp-host-seat.js +131 -0
  119. package/dist/core/mcp-probe.d.ts +7 -2
  120. package/dist/core/mcp-probe.js +7 -2
  121. package/dist/core/mcp-server-link.d.ts +22 -1
  122. package/dist/core/mcp-server-link.js +25 -1
  123. package/dist/core/mcp-server-spec.d.ts +38 -9
  124. package/dist/core/mcp-server-spec.js +55 -21
  125. package/dist/core/mcp.d.ts +27 -12
  126. package/dist/core/mcp.js +105 -76
  127. package/dist/core/memory-admission.d.ts +23 -6
  128. package/dist/core/memory-admission.js +19 -9
  129. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  130. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  131. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  132. package/dist/core/memory-engine/consolidation.js +1 -0
  133. package/dist/core/memory-engine/content-origin.d.ts +13 -0
  134. package/dist/core/memory-engine/content-origin.js +21 -3
  135. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  136. package/dist/core/memory-engine/distiller.js +2 -2
  137. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  138. package/dist/core/memory-engine/dual-root.js +44 -1
  139. package/dist/core/memory-engine/engine.d.ts +67 -14
  140. package/dist/core/memory-engine/engine.js +384 -212
  141. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  142. package/dist/core/memory-engine/export-bundle.js +23 -4
  143. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  144. package/dist/core/memory-engine/file-backend.js +290 -117
  145. package/dist/core/memory-engine/index.d.ts +3 -2
  146. package/dist/core/memory-engine/index.js +2 -1
  147. package/dist/core/memory-engine/layout.d.ts +59 -11
  148. package/dist/core/memory-engine/layout.js +190 -40
  149. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  150. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  151. package/dist/core/memory-engine/scope-contract.d.ts +13 -3
  152. package/dist/core/memory-engine/scope-contract.js +2 -2
  153. package/dist/core/memory-engine/sync-client.d.ts +51 -9
  154. package/dist/core/memory-engine/sync-client.js +107 -13
  155. package/dist/core/memory-engine/sync-report.d.ts +103 -0
  156. package/dist/core/memory-engine/sync-report.js +119 -0
  157. package/dist/core/memory-engine/sync.d.ts +8 -1
  158. package/dist/core/memory-engine/types.d.ts +6 -0
  159. package/dist/core/mode-policy.d.ts +9 -1
  160. package/dist/core/mode-policy.js +11 -1
  161. package/dist/core/model-receipt.d.ts +39 -0
  162. package/dist/core/model-receipt.js +139 -0
  163. package/dist/core/mods/agent-stations.d.ts +65 -0
  164. package/dist/core/mods/agent-stations.js +105 -0
  165. package/dist/core/mods/classic-events.d.ts +5 -1
  166. package/dist/core/mods/kernel/dispatch.d.ts +5 -1
  167. package/dist/core/mods/kernel/dispatch.js +6 -5
  168. package/dist/core/mods/kernel/events.d.ts +11 -4
  169. package/dist/core/mods/kernel/events.js +11 -7
  170. package/dist/core/mods/kernel/receive.d.ts +5 -0
  171. package/dist/core/mods/kernel/receive.js +10 -0
  172. package/dist/core/mods/kernel/registration.d.ts +4 -0
  173. package/dist/core/mods/kernel/registration.js +3 -0
  174. package/dist/core/mods/lifecycle-stations.d.ts +41 -0
  175. package/dist/core/mods/lifecycle-stations.js +35 -0
  176. package/dist/core/mods/stations.d.ts +73 -60
  177. package/dist/core/mods/stations.js +64 -40
  178. package/dist/core/mods/tool-call.d.ts +10 -4
  179. package/dist/core/mods/tool-call.js +28 -12
  180. package/dist/core/mounted-mcp.d.ts +5 -0
  181. package/dist/core/mounted-mcp.js +2 -2
  182. package/dist/core/namespaced-rule-name.d.ts +7 -1
  183. package/dist/core/namespaced-rule-name.js +13 -2
  184. package/dist/core/oracle-isolation.js +1 -1
  185. package/dist/core/own-property-receipt.d.ts +3 -0
  186. package/dist/core/own-property-receipt.js +3 -0
  187. package/dist/core/parent-spec-seat.d.ts +8 -3
  188. package/dist/core/parent-spec-seat.js +2 -0
  189. package/dist/core/park-selfcheck.js +14 -8
  190. package/dist/core/peer-seat.d.ts +133 -16
  191. package/dist/core/peer-seat.js +319 -42
  192. package/dist/core/permission-rule-consent.d.ts +0 -21
  193. package/dist/core/permission-rule-consent.js +11 -6
  194. package/dist/core/permission-rule-model.d.ts +20 -2
  195. package/dist/core/permission-rule-model.js +8 -7
  196. package/dist/core/present-plan-tool.d.ts +11 -3
  197. package/dist/core/present-plan-tool.js +2 -2
  198. package/dist/core/protocol-http-auth.d.ts +14 -2
  199. package/dist/core/protocol-http-auth.js +16 -7
  200. package/dist/core/read-face-seats.d.ts +7 -5
  201. package/dist/core/read-face-seats.js +4 -1
  202. package/dist/core/redaction-marks.d.ts +4 -3
  203. package/dist/core/redaction-marks.js +2 -2
  204. package/dist/core/remote-env.d.ts +146 -98
  205. package/dist/core/remote-env.js +113 -14
  206. package/dist/core/resume-startup-cause.js +1 -0
  207. package/dist/core/retention.js +37 -12
  208. package/dist/core/retired-keys.d.ts +6 -1
  209. package/dist/core/retired-keys.js +4 -1
  210. package/dist/core/rewrite-rejudge.d.ts +13 -5
  211. package/dist/core/rewrite-rejudge.js +9 -5
  212. package/dist/core/roles.d.ts +69 -3
  213. package/dist/core/roles.js +167 -80
  214. package/dist/core/rule-owner.d.ts +3 -0
  215. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  216. package/dist/core/runner/announce-once-ledger.js +4 -2
  217. package/dist/core/runner/assemble-result.d.ts +0 -5
  218. package/dist/core/runner/assemble-result.js +0 -1
  219. package/dist/core/runner/call-hook-stations.d.ts +17 -10
  220. package/dist/core/runner/call-hook-stations.js +23 -12
  221. package/dist/core/runner/child-tree.d.ts +7 -8
  222. package/dist/core/runner/child-tree.js +6 -6
  223. package/dist/core/runner/classifier-ladder.d.ts +10 -2
  224. package/dist/core/runner/classifier-ladder.js +39 -8
  225. package/dist/core/runner/construction-doors.js +5 -0
  226. package/dist/core/runner/contracts.d.ts +82 -57
  227. package/dist/core/runner/credential-origin-seat.js +4 -3
  228. package/dist/core/runner/cross-boundary-lane.d.ts +3 -5
  229. package/dist/core/runner/cross-boundary-lane.js +11 -2
  230. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  231. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  232. package/dist/core/runner/decide-continuation.d.ts +2 -2
  233. package/dist/core/runner/env-capability-census.d.ts +15 -20
  234. package/dist/core/runner/env-capability-census.js +25 -34
  235. package/dist/core/runner/file-history-request.d.ts +2 -2
  236. package/dist/core/runner/file-history-request.js +0 -8
  237. package/dist/core/runner/gate-exit.d.ts +87 -11
  238. package/dist/core/runner/gate-exit.js +30 -8
  239. package/dist/core/runner/git-status-frame.d.ts +5 -2
  240. package/dist/core/runner/git-status-frame.js +3 -4
  241. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  242. package/dist/core/runner/image-removed-seat.js +19 -0
  243. package/dist/core/runner/image.d.ts +7 -2
  244. package/dist/core/runner/image.js +14 -8
  245. package/dist/core/runner/inline-image.d.ts +10 -8
  246. package/dist/core/runner/inline-image.js +11 -9
  247. package/dist/core/runner/memory-consolidation-driver.js +5 -5
  248. package/dist/core/runner/park-commit.d.ts +1 -1
  249. package/dist/core/runner/park-commit.js +3 -0
  250. package/dist/core/runner/permission-rule-lanes.js +1 -1
  251. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  252. package/dist/core/runner/prepare-ask-lane.js +2 -1
  253. package/dist/core/runner/prepare-boundary-parks.d.ts +2 -2
  254. package/dist/core/runner/prepare-boundary-parks.js +5 -5
  255. package/dist/core/runner/prepare-caps-and-workflow.d.ts +7 -5
  256. package/dist/core/runner/prepare-caps-and-workflow.js +6 -3
  257. package/dist/core/runner/prepare-config-doors.d.ts +6 -1
  258. package/dist/core/runner/prepare-config-doors.js +16 -9
  259. package/dist/core/runner/prepare-context-lane.js +2 -0
  260. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -3
  261. package/dist/core/runner/prepare-delegation-surface.js +5 -4
  262. package/dist/core/runner/prepare-file-history.d.ts +10 -12
  263. package/dist/core/runner/prepare-file-history.js +3 -12
  264. package/dist/core/runner/prepare-gate-stations.d.ts +4 -3
  265. package/dist/core/runner/prepare-gate-stations.js +4 -3
  266. package/dist/core/runner/prepare-hands-readface.d.ts +7 -1
  267. package/dist/core/runner/prepare-hands-readface.js +19 -6
  268. package/dist/core/runner/prepare-inherited-gate.d.ts +6 -7
  269. package/dist/core/runner/prepare-inherited-gate.js +22 -31
  270. package/dist/core/runner/prepare-memory-engine-session.js +1 -1
  271. package/dist/core/runner/prepare-memory.d.ts +2 -2
  272. package/dist/core/runner/prepare-memory.js +12 -19
  273. package/dist/core/runner/prepare-park-ask.d.ts +4 -6
  274. package/dist/core/runner/prepare-park-ask.js +5 -9
  275. package/dist/core/runner/prepare-policy-chain.d.ts +8 -7
  276. package/dist/core/runner/prepare-policy-chain.js +136 -121
  277. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  278. package/dist/core/runner/prepare-project-context.js +10 -7
  279. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -2
  280. package/dist/core/runner/prepare-prompt-inputs.js +10 -20
  281. package/dist/core/runner/prepare-protocol-tools.d.ts +5 -3
  282. package/dist/core/runner/prepare-protocol-tools.js +17 -2
  283. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  284. package/dist/core/runner/prepare-run-refs.js +4 -1
  285. package/dist/core/runner/prepare-suspend-saga.d.ts +0 -2
  286. package/dist/core/runner/prepare-suspend-saga.js +5 -7
  287. package/dist/core/runner/prepare-task.js +44 -28
  288. package/dist/core/runner/prepare-turn-wiring.d.ts +2 -0
  289. package/dist/core/runner/prepare-turn-wiring.js +7 -2
  290. package/dist/core/runner/prepare-wiring-manifest.d.ts +5 -4
  291. package/dist/core/runner/prepare-wiring-manifest.js +34 -19
  292. package/dist/core/runner/prepare-workspace-restore.js +3 -3
  293. package/dist/core/runner/reply-pricing.d.ts +30 -0
  294. package/dist/core/runner/reply-pricing.js +19 -0
  295. package/dist/core/runner/resume-admission.js +4 -2
  296. package/dist/core/runner/resume-apply.js +6 -1
  297. package/dist/core/runner/resume-checkpoint-screen.js +4 -4
  298. package/dist/core/runner/resume-policy-outcome.js +5 -5
  299. package/dist/core/runner/retired-runner-deps.js +4 -1
  300. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  301. package/dist/core/runner/role-seat-defaulted.js +40 -0
  302. package/dist/core/runner/run-attachment-seats.js +3 -3
  303. package/dist/core/runner/run-brain-sinks.js +3 -0
  304. package/dist/core/runner/run-git-lane.d.ts +3 -1
  305. package/dist/core/runner/run-git-lane.js +1 -1
  306. package/dist/core/runner/run-harness-handlers.d.ts +3 -1
  307. package/dist/core/runner/run-harness-handlers.js +3 -1
  308. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  309. package/dist/core/runner/run-identity-wiring.js +6 -5
  310. package/dist/core/runner/run-leg.d.ts +2 -0
  311. package/dist/core/runner/run-leg.js +63 -56
  312. package/dist/core/runner/run-notification-lane.d.ts +3 -1
  313. package/dist/core/runner/run-notification-lane.js +16 -10
  314. package/dist/core/runner/run-settle-and-teardown.js +5 -1
  315. package/dist/core/runner/run-stop-and-final-verify.d.ts +4 -0
  316. package/dist/core/runner/run-stop-and-final-verify.js +14 -6
  317. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  318. package/dist/core/runner/run-terminal-adoption.js +9 -3
  319. package/dist/core/runner/run-turn-boundary.js +89 -77
  320. package/dist/core/runner/runtask.d.ts +8 -5
  321. package/dist/core/runner/runtask.js +21 -13
  322. package/dist/core/runner/side-call-account.d.ts +1 -1
  323. package/dist/core/runner/side-call-account.js +3 -18
  324. package/dist/core/runner/skills-seat.js +2 -2
  325. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  326. package/dist/core/runner/sub-agent-deny-lists.js +20 -7
  327. package/dist/core/runner/synthetic-tools.js +2 -2
  328. package/dist/core/runner/tool-disclosure.js +0 -2
  329. package/dist/core/runner/tool-end-body.js +2 -2
  330. package/dist/core/runner/tool-face-overlay.d.ts +1 -1
  331. package/dist/core/runner/tool-face-overlay.js +26 -19
  332. package/dist/core/runner/tool-occurrence.d.ts +1 -1
  333. package/dist/core/runner/tool-occurrence.js +2 -2
  334. package/dist/core/runner/tool-result-media-seat.d.ts +9 -1
  335. package/dist/core/runner/tool-result-media-seat.js +17 -1
  336. package/dist/core/runner/turn-attachments.d.ts +29 -27
  337. package/dist/core/runner/turn-attachments.js +27 -42
  338. package/dist/core/runner-deps.d.ts +32 -19
  339. package/dist/core/secret-env.d.ts +35 -4
  340. package/dist/core/secret-env.js +65 -3
  341. package/dist/core/sensitive-path-policy.js +3 -3
  342. package/dist/core/session-policy-store.d.ts +12 -3
  343. package/dist/core/session-policy-store.js +29 -10
  344. package/dist/core/session-store.d.ts +5 -7
  345. package/dist/core/session-store.js +50 -11
  346. package/dist/core/side-query.d.ts +11 -1
  347. package/dist/core/side-query.js +9 -0
  348. package/dist/core/skill-grant-binding.d.ts +31 -2
  349. package/dist/core/skill-grant-binding.js +31 -1
  350. package/dist/core/skill-grant.d.ts +17 -5
  351. package/dist/core/skill-grant.js +24 -6
  352. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  353. package/dist/core/store-contracts/checkpoint-store-contract.js +3 -2
  354. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  355. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  356. package/dist/core/store-contracts/tool-result-store-contract.js +37 -0
  357. package/dist/core/stub-env.d.ts +5 -5
  358. package/dist/core/stub-env.js +11 -1
  359. package/dist/core/swappable-deps.d.ts +17 -43
  360. package/dist/core/swappable-deps.js +15 -5
  361. package/dist/core/synthetic-read-verdict.d.ts +1 -1
  362. package/dist/core/synthetic-read-verdict.js +2 -1
  363. package/dist/core/task-event.d.ts +50 -10
  364. package/dist/core/task-notification.d.ts +88 -5
  365. package/dist/core/task-notification.js +146 -17
  366. package/dist/core/task-registry-agent.d.ts +18 -12
  367. package/dist/core/task-registry-agent.js +19 -6
  368. package/dist/core/task-registry-monitor.d.ts +7 -0
  369. package/dist/core/task-registry-monitor.js +28 -1
  370. package/dist/core/task-registry-shared.d.ts +43 -3
  371. package/dist/core/task-registry-shared.js +21 -7
  372. package/dist/core/task-registry-workflow.js +1 -1
  373. package/dist/core/task-registry.d.ts +50 -35
  374. package/dist/core/task-registry.js +64 -23
  375. package/dist/core/task-result.d.ts +3 -12
  376. package/dist/core/task-spec.d.ts +15 -7
  377. package/dist/core/task-stream.d.ts +1 -1
  378. package/dist/core/terminal-cause.d.ts +10 -0
  379. package/dist/core/tool-catalog-entries.js +1 -1
  380. package/dist/core/tool-check-reading.d.ts +1 -0
  381. package/dist/core/tool-check-reading.js +3 -3
  382. package/dist/core/tool-face-reader.d.ts +7 -6
  383. package/dist/core/tool-face-reader.js +4 -3
  384. package/dist/core/tool-name-aliases.d.ts +19 -0
  385. package/dist/core/tool-name-aliases.js +54 -2
  386. package/dist/core/tool-policy.d.ts +21 -4
  387. package/dist/core/tool-policy.js +1 -1
  388. package/dist/core/tool-registry.d.ts +5 -5
  389. package/dist/core/tool-registry.js +2 -2
  390. package/dist/core/tool-result-store.d.ts +88 -5
  391. package/dist/core/tool-result-store.js +51 -12
  392. package/dist/core/tool-roster.d.ts +112 -5
  393. package/dist/core/tool-roster.js +42 -1
  394. package/dist/core/tool-spec.d.ts +23 -5
  395. package/dist/core/trace.d.ts +0 -1
  396. package/dist/core/types.d.ts +5 -5
  397. package/dist/core/types.js +2 -2
  398. package/dist/core/untrusted-text.js +1 -1
  399. package/dist/core/user-attachment.d.ts +10 -5
  400. package/dist/core/user-attachment.js +15 -7
  401. package/dist/core/wiring-manifest.d.ts +6 -3
  402. package/dist/engine/compaction/compaction.js +29 -3
  403. package/dist/engine/execution-env/node-execution-env.d.ts +11 -5
  404. package/dist/engine/execution-env/node-execution-env.js +21 -13
  405. package/dist/engine/harness/agent-harness.d.ts +26 -3
  406. package/dist/engine/harness/agent-harness.js +49 -16
  407. package/dist/engine/harness/messages.d.ts +3 -1
  408. package/dist/engine/harness/messages.js +3 -2
  409. package/dist/engine/harness/types.d.ts +119 -28
  410. package/dist/engine/llm/rejected-images.d.ts +46 -0
  411. package/dist/engine/llm/rejected-images.js +54 -0
  412. package/dist/engine/llm/tool-turns.d.ts +2 -1
  413. package/dist/engine/llm/types.d.ts +18 -7
  414. package/dist/engine/loop/agent-loop.d.ts +20 -12
  415. package/dist/engine/loop/agent-loop.js +205 -36
  416. package/dist/engine/loop/types.d.ts +12 -3
  417. package/dist/engine/lsp/node-lsp-manager.d.ts +3 -3
  418. package/dist/engine/lsp/node-lsp-manager.js +32 -13
  419. package/dist/engine/session/path-to-root.d.ts +38 -0
  420. package/dist/engine/session/path-to-root.js +39 -0
  421. package/dist/engine/session/storage-base.js +4 -21
  422. package/dist/index.d.ts +35 -21
  423. package/dist/index.js +26 -17
  424. package/dist/internal/harness-types.d.ts +1 -1
  425. package/dist/internal/harness.d.ts +1 -0
  426. package/dist/internal/llm.d.ts +1 -0
  427. package/dist/orchestration/run-workflow-tool.d.ts +9 -3
  428. package/dist/orchestration/run-workflow-tool.js +59 -29
  429. package/dist/orchestration/workflow-governance.d.ts +1 -1
  430. package/dist/orchestration/workflow-governance.js +2 -1
  431. package/dist/orchestration/workflow-observe.d.ts +17 -1
  432. package/dist/orchestration/workflow-observe.js +20 -0
  433. package/dist/orchestration/workflow-types.d.ts +32 -7
  434. package/dist/orchestration/workflow.d.ts +4 -0
  435. package/dist/orchestration/workflow.js +762 -491
  436. package/dist/prompts/default.d.ts +1 -10
  437. package/dist/prompts/default.js +0 -2
  438. package/dist/shell/counting-pass.d.ts +50 -0
  439. package/dist/shell/counting-pass.js +502 -0
  440. package/dist/shell/lex.d.ts +4 -2
  441. package/dist/shell/lex.js +93 -34
  442. package/dist/shell/shell-words.d.ts +1 -1
  443. package/dist/shell/shell-words.js +7 -6
  444. package/dist/stores/file/background-agent-store.d.ts +1 -1
  445. package/dist/stores/file/background-agent-store.js +3 -1
  446. package/dist/stores/file/checkpoint-store.d.ts +127 -2
  447. package/dist/stores/file/checkpoint-store.js +19 -14
  448. package/dist/stores/file/file-history-store.d.ts +1 -1
  449. package/dist/stores/file/file-history-store.js +3 -1
  450. package/dist/stores/file/index.d.ts +4 -3
  451. package/dist/stores/file/index.js +17 -8
  452. package/dist/stores/file/mailbox-store.d.ts +1 -1
  453. package/dist/stores/file/mailbox-store.js +9 -11
  454. package/dist/stores/file/memory-store.d.ts +1 -1
  455. package/dist/stores/file/memory-store.js +3 -1
  456. package/dist/stores/file/session-policy-store.d.ts +1 -1
  457. package/dist/stores/file/session-policy-store.js +3 -1
  458. package/dist/stores/file/session-store.d.ts +1 -1
  459. package/dist/stores/file/session-store.js +3 -1
  460. package/dist/stores/file/shared-ledger.d.ts +26 -0
  461. package/dist/stores/file/shared-ledger.js +38 -9
  462. package/dist/stores/file/tool-result-store.d.ts +20 -2
  463. package/dist/stores/file/tool-result-store.js +74 -6
  464. package/dist/stores/file/usage-window-store.d.ts +1 -1
  465. package/dist/stores/file/usage-window-store.js +3 -1
  466. package/dist/stores/file/workflow-journal-store.d.ts +1 -11
  467. package/dist/stores/file/workflow-journal-store.js +3 -2
  468. package/dist/tools/fs/containment-face.d.ts +5 -0
  469. package/dist/tools/fs/encoding.d.ts +13 -4
  470. package/dist/tools/fs/encoding.js +17 -2
  471. package/dist/tools/fs/fs-bash-background-text.d.ts +7 -0
  472. package/dist/tools/fs/fs-bash-background-text.js +1 -0
  473. package/dist/tools/fs/fs-bash.d.ts +14 -4
  474. package/dist/tools/fs/fs-bash.js +29 -35
  475. package/dist/tools/fs/fs-pdf.d.ts +2 -2
  476. package/dist/tools/fs/fs-pdf.js +26 -21
  477. package/dist/tools/fs/fs-read.d.ts +5 -4
  478. package/dist/tools/fs/fs-read.js +35 -18
  479. package/dist/tools/fs/fs-search-tools.js +4 -1
  480. package/dist/tools/fs/fs-shared.d.ts +11 -13
  481. package/dist/tools/fs/fs-shared.js +11 -7
  482. package/dist/tools/fs/fs-write.js +5 -5
  483. package/dist/tools/fs/index.d.ts +14 -8
  484. package/dist/tools/fs/index.js +13 -5
  485. package/dist/tools/fs/program-read-model.d.ts +13 -0
  486. package/dist/tools/fs/program-read-model.js +15 -0
  487. package/dist/tools/fs/program-read-model.rows.js +1 -1
  488. package/dist/tools/fs/read-deny.d.ts +13 -10
  489. package/dist/tools/fs/read-deny.js +25 -5
  490. package/dist/tools/fs/read-floor.d.ts +62 -0
  491. package/dist/tools/fs/read-floor.js +58 -0
  492. package/dist/tools/fs/removal-targets.d.ts +9 -4
  493. package/dist/tools/fs/removal-targets.js +17 -9
  494. package/dist/tools/fs/search.d.ts +3 -3
  495. package/dist/tools/fs/search.js +4 -4
  496. package/dist/tools/fs/shell-read-check.d.ts +1 -1
  497. package/dist/tools/fs/shell-read-check.js +2 -1
  498. package/dist/tools/fs/shell-read-judge.d.ts +16 -8
  499. package/dist/tools/fs/shell-read-judge.js +10 -6
  500. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  501. package/dist/tools/fs/shell-read-plan.js +22 -15
  502. package/dist/tools/fs/shell-read-start.js +1 -0
  503. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  504. package/dist/tools/fs/shell-reentry-text.js +25 -3
  505. package/dist/tools/monitor.d.ts +9 -4
  506. package/dist/tools/monitor.js +17 -8
  507. package/dist/tools/scheduler-tools.js +42 -4
  508. package/dist/tools/web.d.ts +0 -10
  509. package/dist/tools/web.js +1 -4
  510. package/package.json +5 -2
  511. package/test/export-surface.snapshot.json +161 -21
  512. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  513. package/wire-changes/core-stores-sql@7.60.0.json +30 -0
  514. package/wire-changes/core@7.59.0.json +2459 -0
  515. package/wire-changes/core@7.60.0.json +3274 -0
  516. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  517. package/wire-changes/mods-kernel@7.60.0.json +62 -0
  518. package/wire-changes/primitives@7.59.0.json +29 -0
  519. package/wire-changes/primitives@7.60.0.json +30 -0
@@ -1,4 +1,4 @@
1
- import type { ExecutionEnv } from "../../internal/harness-types.js";
1
+ import type { ExecutionEnv, ReadFloor } from "../../internal/harness-types.js";
2
2
  import { type HomeViewsCarrier } from "./read-deny-home.js";
3
3
  import { type FsGlob } from "./fs-glob.js";
4
4
  /** The JS scanner's own output ceiling, in bytes of emitted content rows. Pinned to the
@@ -312,10 +312,10 @@ export declare function rgOutputDenyTripwire(stdout: string, mode: GrepOutputMod
312
312
  * re-scan — partial results ship with a caveat; only a zero-output failure degrades to
313
313
  * {@link jsGrep}, and that degradation is declared in both text and structure. An external abort
314
314
  * propagates as the interruption it is (no fallback rerun). */
315
- export declare function rgGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, deny?: ReadDenyJudge): Promise<GrepRunResult>;
315
+ export declare function rgGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, deny?: ReadDenyJudge, readFloor?: ReadFloor): Promise<GrepRunResult>;
316
316
  /** grep dispatch: ripgrep when the env has it, else the hardened JS fallback.
317
317
  * Returns the degradation facts alongside the text so the tool layer can surface them structurally. */
318
- export declare function runGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, deny?: ReadDenyJudge): Promise<GrepRunResult>;
318
+ export declare function runGrepDetailed(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal, deny?: ReadDenyJudge, readFloor?: ReadFloor): Promise<GrepRunResult>;
319
319
  /** Text-only wrapper of {@link runGrepDetailed}. */
320
320
  export declare function runGrep(env: ExecutionEnv, root: string, p: GrepParams, signal?: AbortSignal): Promise<string>;
321
321
  /** glob: find files by name pattern, with optional sub-path scoping; returns RELATIVE paths. */
@@ -1174,7 +1174,7 @@ async function jsGrepFallback(env, root, p, signal, reason, deny) {
1174
1174
  ...(denyOut.withheld !== undefined ? { withheld: denyOut.withheld } : {}),
1175
1175
  };
1176
1176
  }
1177
- export async function rgGrepDetailed(env, root, p, signal, deny) {
1177
+ export async function rgGrepDetailed(env, root, p, signal, deny, readFloor) {
1178
1178
  const mode = p.output_mode ?? "files_with_matches";
1179
1179
  const flags = ["--null", "-H", "--no-messages", "--no-require-git", "--hidden"];
1180
1180
  for (const d of VCS_DIRS)
@@ -1209,7 +1209,7 @@ export async function rgGrepDetailed(env, root, p, signal, deny) {
1209
1209
  flags.push(g.flag, shellQuote(g.glob));
1210
1210
  const target = p.path ? shellQuote(p.path) : ".";
1211
1211
  const cmd = `rg ${flags.join(" ")} -e ${shellQuote(p.pattern)} -- ${target}`;
1212
- const res = await env.exec(cmd, { cwd: root, timeout: 60, abortSignal: signal });
1212
+ const res = await env.exec(cmd, { cwd: root, timeout: 60, abortSignal: signal, ...(readFloor !== undefined ? { readFloor } : {}) });
1213
1213
  if (!res.ok) {
1214
1214
  const err = res.error;
1215
1215
  if (err.code === "aborted" || signal?.aborted === true)
@@ -1313,7 +1313,7 @@ async function rgDenyExistenceProbe(env, root, deny, target, signal) {
1313
1313
  return { kind: "probe_failed" };
1314
1314
  }
1315
1315
  }
1316
- export async function runGrepDetailed(env, root, p, signal, deny) {
1316
+ export async function runGrepDetailed(env, root, p, signal, deny, readFloor) {
1317
1317
  const scope = p.path ? anchorSpelling(pathFamilyOf({ root }), root, p.path) : root;
1318
1318
  const unexcludableUnder = async () => {
1319
1319
  if (deny === undefined)
@@ -1326,7 +1326,7 @@ export async function runGrepDetailed(env, root, p, signal, deny) {
1326
1326
  return deny.unexcludableUnder(scope) || (home.view !== undefined && deny.unexcludableUnder(home.view));
1327
1327
  };
1328
1328
  if (!(await unexcludableUnder()) && (await detectRipgrep(env)))
1329
- return rgGrepDetailed(env, root, p, signal, deny);
1329
+ return rgGrepDetailed(env, root, p, signal, deny, readFloor);
1330
1330
  const denyOut = {};
1331
1331
  const { text, rows } = await jsGrepDetailed(env, root, p, signal, undefined, deny, denyOut);
1332
1332
  return { text, ...(rows !== undefined ? { rows } : {}), ...(denyOut.withheld !== undefined ? { withheld: denyOut.withheld } : {}) };
@@ -261,7 +261,7 @@ export interface ShellReadJudgment {
261
261
  * holding a command, an environment and a boundary gets the decision the gate would reach for them.
262
262
  *
263
263
  * An ENVIRONMENT question, not a text question: a symlink that leaves the roots, a pattern that expands
264
- * onto a deny row, a traversal root that cannot be enumerated are answered by `env`, not guessed from the
264
+ * onto a deny row, a traversal root that lands elsewhere than it is spelled are answered by `env`, not guessed from the
265
265
  * spelling. {@link judgeShellReadLexically} is the no-environment reading and not a substitute — it is
266
266
  * LAXER where only a filesystem sees the escape (an in-root symlink pointing out vouches) and answers a
267
267
  * pattern on its spelling alone, so the two diverge in both directions.
@@ -350,7 +350,7 @@ function judgePlan(plan, established, boundary) {
350
350
  return judgeEstablishedPlan(plan, established.reads, boundary, (n) => {
351
351
  const nested = established.nested.get(n);
352
352
  return nested === undefined ? { plan: n, segments: [], guards: stationGuards(boundary), writeGuards: writeFaceGuards(boundary) } : judgePlan(n, nested, boundary);
353
- });
353
+ }, (n) => judgePlan(n, establishShellReadsLexically(n, boundary), boundary));
354
354
  }
355
355
  async function applyAlsoInside(judged, boundary) {
356
356
  const alsoInside = boundary.alsoInside;
@@ -375,6 +375,7 @@ async function applyAlsoInside(judged, boundary) {
375
375
  segment: s.segment,
376
376
  findings: s.findings.map((f) => (outsideRead(f) && rescued.has(f.read.target) ? { ...f, kind: "none", containment: "inside" } : f)),
377
377
  nested: s.nested.map(rewrite),
378
+ printed: s.printed,
378
379
  })),
379
380
  });
380
381
  return rewrite(judged);
@@ -231,7 +231,7 @@ export interface ShellReadBoundary extends BashReadonlyRootBoundary {
231
231
  }
232
232
  /** How far one candidate got before it was judged. `lexical` = the folded spelling is the judged target
233
233
  * (an isolated sandbox, or a resolver that declares no authority and did not answer); `canonical` = the
234
- * environment resolved it; `expansion` = one path a pattern expanded to or a traversal enumerated;
234
+ * environment resolved it; `expansion` = one path a pattern expanded to (a traversal root is never listed below);
235
235
  * `unestablishable` = the floor could not say where it lands (`cause` says why). */
236
236
  export type ReadEstablishment = "lexical" | "canonical" | "expansion" | "unestablishable";
237
237
  export interface EstablishedRead {
@@ -293,11 +293,14 @@ export interface ReadFinding {
293
293
  * @contract shell.read_boundary.friction_floor — what this judge answers is a question about TEXT and the
294
294
  * FILESYSTEM the command will run in: which files the words of a command may name, resolved against the
295
295
  * declared roots, the declared home and the observed working directory, and — where the environment can
296
- * answer — where those spellings really land (symlinks resolved, patterns expanded, traversal roots
297
- * enumerated, each within a bound). It is not a question about what the process will open. A deployment's
298
- * containment for what a shell may reach is the `ExecutionEnv` the command runs in (a sandbox, a
299
- * container, a remote adapter); everything here is the friction floor under that containment. Under an
300
- * isolated sandbox the floor is lexical (the sandbox is the boundary and its filesystem is not this
296
+ * answer — where those spellings really land (symlinks resolved, patterns expanded within a bound). A
297
+ * recursive read's root is one of those words: it is judged by what the command NAMES (the root itself and the
298
+ * placed rows the root contains), never by a tree walked below it. It is not a question about what the
299
+ * process will open. A deployment's containment for what a shell may reach is the `ExecutionEnv` the
300
+ * command runs in (a sandbox, a container, a remote adapter); everything here is the friction floor under
301
+ * that containment, and the read-deny table this station judges with travels to that environment on every
302
+ * command start as `readFloor` (an environment that confines processes keeps it or refuses the start). Under
303
+ * an isolated sandbox the floor is lexical (the sandbox is the boundary and its filesystem is not this
301
304
  * process's to resolve). A deny-listed read is REFUSED on every seat; an out-of-root read asks where a
302
305
  * person can be asked and is refused where none can; a read the floor cannot establish (an expansion it
303
306
  * cannot finish, a spelling the shell rewrites, a working directory it cannot place) is asked or refused
@@ -330,6 +333,10 @@ export interface JudgedSegment {
330
333
  readonly segment: ShellReadSegment;
331
334
  readonly findings: readonly ReadFinding[];
332
335
  readonly nested: readonly JudgedPlan[];
336
+ /** What a literal printer says the segment's shell is fed ({@link ShellReadSegment.printed}), judged on its spelling alone
337
+ * (no environment is asked about a text that may not run): the fold reads its deny hits and nothing else; no other reader
338
+ * of a judged plan reads it. */
339
+ readonly printed: readonly JudgedPlan[];
333
340
  }
334
341
  export interface JudgedPlan {
335
342
  readonly plan: ShellReadPlan;
@@ -393,11 +400,12 @@ export interface ShellReadFold {
393
400
  * only RAISE that: the nested text's deny-relation answers count — a deny hit (a refusal is a refusal whatever
394
401
  * runs it) and a root that may hold a row no home places — its containment and its other silence do not (an inner
395
402
  * `cat inside.txt` vouches nothing about the outer text). A substitution body (`$(…)`, a backtick, `<(…)`) is nested
396
- * WITHOUT re-entry and folds in full.
403
+ * WITHOUT re-entry and folds in full. What a literal printer says the shell is fed ({@link JudgedSegment.printed}) is a
404
+ * text that may not run at all: its deny HITS count, and nothing else it finds or fails to find does.
397
405
  */
398
406
  export declare function foldShellReadFindings(judged: JudgedPlan): ShellReadFold;
399
407
  /** Judge every established read of a plan, in place. `establish` runs per segment so a caller can bound it. */
400
- export declare function judgeEstablishedPlan(plan: ShellReadPlan, established: ReadonlyMap<ShellReadSegment, readonly EstablishedRead[]>, boundary: ShellReadBoundary, nestedOf: (plan: ShellReadPlan) => JudgedPlan): JudgedPlan;
408
+ export declare function judgeEstablishedPlan(plan: ShellReadPlan, established: ReadonlyMap<ShellReadSegment, readonly EstablishedRead[]>, boundary: ShellReadBoundary, nestedOf: (plan: ShellReadPlan) => JudgedPlan, printedOf: (plan: ShellReadPlan) => JudgedPlan): JudgedPlan;
401
409
  /** Every finding of a judged plan, flattened (segments and nested plans alike). */
402
410
  export declare function allFindings(judged: JudgedPlan): ReadFinding[];
403
411
  /** One lexical step up, family-aware. A family ROOT is its own parent — the fixpoint the climb below ends
@@ -146,12 +146,13 @@ export function foldShellReadFindings(judged) {
146
146
  if (rank > 0 || (rank === 0 && next.witness?.read.candidate.face === "write" && best.witness?.read.candidate.face !== "write"))
147
147
  best = next;
148
148
  };
149
- const walk = (j, denyOnly) => {
149
+ const walk = (j, reading) => {
150
+ const denyOnly = reading !== "full";
150
151
  if (j.plan.unreadable !== undefined && !denyOnly)
151
152
  raise({ finding: "unestablishable" });
152
153
  for (const s of j.segments) {
153
154
  for (const f of s.findings) {
154
- if (denyOnly && f.kind !== "deny_hit" && f.kind !== "unanswered")
155
+ if (denyOnly && f.kind !== "deny_hit" && (reading === "deny-hit" || f.kind !== "unanswered"))
155
156
  continue;
156
157
  if (f.kind !== "none")
157
158
  raise({ finding: f.kind, witness: f });
@@ -169,12 +170,13 @@ export function foldShellReadFindings(judged) {
169
170
  if (move !== undefined && (typeof move.target === "string" || move.target.expands !== false))
170
171
  raise({ finding: "unestablishable", declined: s.segment });
171
172
  }
172
- const nestedDenyOnly = denyOnly || s.segment.reentry === "shell";
173
173
  for (const n of s.nested)
174
- walk(n, nestedDenyOnly);
174
+ walk(n, reading === "full" && s.segment.reentry !== "shell" ? "full" : reading === "deny-hit" ? "deny-hit" : "deny-relation");
175
+ for (const n of s.printed)
176
+ walk(n, "deny-hit");
175
177
  }
176
178
  };
177
- walk(judged, false);
179
+ walk(judged, "full");
178
180
  const unfinished = judged.incomplete?.[0];
179
181
  if (unfinished !== undefined && (judged.guards || judged.writeGuards) && SHELL_READ_FINDING_RANK.unanswered > SHELL_READ_FINDING_RANK[best.finding]) {
180
182
  unestablished = true;
@@ -182,13 +184,14 @@ export function foldShellReadFindings(judged) {
182
184
  }
183
185
  return { ...best, ...(unestablished ? { unestablished: true } : {}), ...(unplacedRead ? { unplacedRead: true } : {}), ...(unestablished && reentered.length > 0 ? { reentered } : {}) };
184
186
  }
185
- export function judgeEstablishedPlan(plan, established, boundary, nestedOf) {
187
+ export function judgeEstablishedPlan(plan, established, boundary, nestedOf, printedOf) {
186
188
  return {
187
189
  plan,
188
190
  segments: plan.segments.map((segment) => ({
189
191
  segment,
190
192
  findings: (established.get(segment) ?? []).map((r) => judgeRead(r, boundary)),
191
193
  nested: segment.nested.map(nestedOf),
194
+ printed: (segment.printed ?? []).map(printedOf),
192
195
  })),
193
196
  guards: stationGuards(boundary),
194
197
  writeGuards: writeFaceGuards(boundary),
@@ -273,6 +276,7 @@ export function rejudge(judged, boundary) {
273
276
  segment: s.segment,
274
277
  findings: s.findings.map((f) => judgeRead(f.read, boundary)),
275
278
  nested: s.nested.map((n) => rejudge(n, boundary)),
279
+ printed: s.printed.map((n) => rejudge(n, boundary)),
276
280
  })),
277
281
  guards: stationGuards(boundary),
278
282
  writeGuards: writeFaceGuards(boundary),
@@ -22,7 +22,8 @@
22
22
  * · an INTERPRETER's inline program is a shape fact (`reentry:"interpreter"`), never parsed, never a finding;
23
23
  * · `<` targets are read candidates, `>`-family targets are write targets (tagged, not read), here-documents
24
24
  * and here-strings are data (an UNQUOTED here-document body's substitutions are nested plans) — except to a shell
25
- * whose argv names no script: what arrives on its standard input is its script, a nested plan where the text spells it;
25
+ * whose argv names no script: what arrives on its standard input is its script, a nested plan where the text spells it,
26
+ * a `printed` plan where a literal printer producing it does (`printed`: never what runs — only its deny hits count);
26
27
  * · `$(…)`, backticks and `<(…)` bodies are nested plans; a word carrying one cannot be resolved from the text;
27
28
  * · the working-directory thread (`shell-read-workdir.ts`) moves the base the LATER segments resolve against, as a
28
29
  * candidate SET (`&&` proves a move, nothing else does), and gives `PWD` / `OLDPWD` their values; a loop body with
@@ -136,6 +137,10 @@ export interface ShellReadSegment {
136
137
  readonly bases: readonly string[] | "unmodelled";
137
138
  /** Substitution bodies, unquoted here-document substitutions, and re-entered shell text, each its own plan. */
138
139
  readonly nested: readonly ShellReadPlan[];
140
+ /** Texts a literal printer's words say this segment's shell is fed (a pipe's producer, the body of a `<(…)` script file or
141
+ * of a `< <(…)` input), each its own plan — never a text known to run, so no reader of what runs (`nested`) reads them: the
142
+ * read station judges them on their spelling, and only a deny hit among them counts (it refuses the call). */
143
+ readonly printed?: readonly ShellReadPlan[];
139
144
  readonly reach: SegmentReach;
140
145
  /** The names a change that can reach this segment touched (`BindingTable.rebound`): any other name still holds what the
141
146
  * shell provides here. `all`: any name may have changed. */
@@ -8,7 +8,7 @@ import { POLL_LOOP_MAX_BEATS, attachedOptionPayloads, resolveOperandLexically, i
8
8
  import { BLOCK_WORD_NAMES, commandLineOf, commandLineOptionSpellings, declaredAttributes, isDeclarationBuiltin, isInertBuiltin, launcherOptionPathRole, launcherOptionStep, readOptionRole, programLanguageOf, programTextOpensOf, selectedOptions, movesBaseByStack, opensNoOperand, programDelivery, programRow, readArgRoles, runsShellText, } from "./program-read-model.js";
9
9
  import { shellWordsOf } from "../../shell/shell-words.js";
10
10
  import { isAbsoluteForFamily } from "./safety.js";
11
- import { codeBodies, launchedInput, reentersShell, reentryText, scriptFileAt, stdinTextsOf } from "./shell-reentry-text.js";
11
+ import { codeBodies, launchedInput, pipedTextOf, printedByProcess, reentersShell, reentryText, scriptFileAt, stdinTextsOf } from "./shell-reentry-text.js";
12
12
  import { heldAt, plannedOnce, rebasePlan, startedAt, stdinFeeds } from "./shell-read-start.js";
13
13
  import { markStandardDevices } from "./shell-read-device.js";
14
14
  export const READ_CANDIDATE_PROVENANCES = Object.freeze([
@@ -68,7 +68,7 @@ function planText(command, decl, depth, start, from) {
68
68
  const empty = lexed.segments.map((segment, si) => segmentIsEmpty(segment, projected[si]));
69
69
  const facts = projected.map(() => undefined);
70
70
  const tables = projected.map(() => undefined);
71
- const fedAt = stdinFeeds(lexed.segments, start?.stdin ?? [], (si) => [{ from: `${lexed.segments[si - 1].text.trim()} |` }]);
71
+ const fedAt = stdinFeeds(lexed.segments, start?.stdin ?? [], (si) => [pipedTextOf(lexed.segments[si - 1])]);
72
72
  const inheritedFns = new Set([...(start?.exportedFunctions ?? [])].flatMap(([name, body]) => (body === "unread" ? [name] : [])));
73
73
  const factsAt = (si, table) => {
74
74
  tables[si] ??= table;
@@ -202,6 +202,7 @@ function planText(command, decl, depth, start, from) {
202
202
  const moved = readProgramPosition(f.argv).launcherMovesBase;
203
203
  const programPlaced = moved ? placedAt("unmodelled", bases !== "unmodelled" ? bases : floor) : withBases;
204
204
  const programRead = (c) => (c.provenance === "stdin_redirect" ? withBases(c) : programPlaced(c));
205
+ const placeNested = (n) => (f.elsewhere?.has(n) === true ? n : rebasePlan(n, decl.cwd, moved && f.shellSide?.has(n) !== true ? "unmodelled" : bases, bases === "unmodelled" ? floor : bases));
205
206
  segments.push({
206
207
  text: f.text,
207
208
  connector: f.connector,
@@ -216,7 +217,8 @@ function planText(command, decl, depth, start, from) {
216
217
  redirects: f.redirects.map((r) => ({ op: r.op, direction: r.direction, ...(r.fd !== undefined ? { fd: r.fd } : {}), ...(r.target !== undefined ? { target: withBases(r.target) } : {}) })),
217
218
  ...(move !== undefined ? { baseMove: { target: typeof move.target === "string" ? move.target : withBases(move.target) } } : {}),
218
219
  bases,
219
- nested: f.nested.map((n) => (f.elsewhere?.has(n) === true ? n : rebasePlan(n, decl.cwd, moved && f.shellSide?.has(n) !== true ? "unmodelled" : bases, bases === "unmodelled" ? floor : bases))),
220
+ nested: f.nested.map(placeNested),
221
+ ...(f.printed.length > 0 ? { printed: f.printed.map(placeNested) } : {}),
220
222
  reach: reaches[si] ?? { andJoined: false, orBroken: false, moveProvable: false },
221
223
  rebound: tables[si]?.rebound ?? "all",
222
224
  });
@@ -310,6 +312,7 @@ function readingFacts(segment, p, decl, reading, nestedPlan, fed, inheritedFns =
310
312
  }
311
313
  function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks, inheritedFns = new Set()) {
312
314
  const nested = [];
315
+ const printed = [];
313
316
  const elsewhere = new Set();
314
317
  const ctx = { table, reentered: [], programTextSeen: false };
315
318
  const enclosedToo = (e) => [e, ...(e.inner ?? []).flatMap(enclosedToo)];
@@ -356,6 +359,7 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks, inheri
356
359
  argv: p.argv,
357
360
  redirects,
358
361
  nested,
362
+ printed,
359
363
  };
360
364
  const done = (f) => {
361
365
  const reentered = [...new Set(ctx.reentered)];
@@ -488,8 +492,10 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks, inheri
488
492
  const reenterShell = (verb, argvs) => {
489
493
  const stdin = stdinTextsOf(segment, fed);
490
494
  const scripts = new Map();
491
- const script = (text, at) => { if (text !== undefined)
492
- scripts.set(JSON.stringify([text, at]), { ...at, text }); };
495
+ const prints = new Map();
496
+ const into = (to) => (text, at) => { if (text !== undefined)
497
+ to.set(JSON.stringify([text, at]), { ...at, text }); };
498
+ const script = into(scripts), print = into(prints);
493
499
  for (const { shell, texts: t, args: a, as } of argvs) {
494
500
  const user = as !== undefined ? { as } : {};
495
501
  const argvText = [reentryText(shell, t), reentryText(shell, a)];
@@ -497,20 +503,21 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks, inheri
497
503
  script(text, { ...user, ...(stdin.length > 0 ? { stdin } : {}) });
498
504
  if (argvText.every((text) => text === undefined))
499
505
  for (const s of stdin)
500
- if (s.literal !== undefined)
501
- script(reentryText(shell, t, s.literal), user);
506
+ void (s.literal !== undefined && script(reentryText(shell, t, s.literal), user), s.printed !== undefined && print(reentryText(shell, t, s.printed), user));
502
507
  }
503
- for (const { text, ...at } of scripts.values()) {
504
- const plan = nestedPlan(text, "now", at);
505
- nested.push(plan);
506
- if (at.as?.login === true)
507
- elsewhere.add(plan);
508
- }
509
- for (const { shell, args: a, words } of argvs) {
508
+ for (const { shell, args: a, words, as } of argvs) {
510
509
  const at = shell === "source" || shell === "." ? a.findIndex((w) => !w.startsWith("-") || w === "-") : scriptFileAt(shell, a);
511
510
  const file = at === undefined ? undefined : words[at];
512
511
  if (file !== undefined)
513
- reads.push(bare(file, "operand"));
512
+ void (reads.push(bare(file, "operand")), print(printedByProcess(file.word), as !== undefined ? { as } : {}));
513
+ }
514
+ for (const [to, plans] of [[scripts, nested], [prints, printed]]) {
515
+ for (const { text, ...at } of to.values()) {
516
+ const plan = nestedPlan(text, "now", at);
517
+ plans.push(plan);
518
+ if (at.as?.login === true)
519
+ elsewhere.add(plan);
520
+ }
514
521
  }
515
522
  return done({ empty: false, launcherChain, verb, reentry: "shell", declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), ...(stdin.length > 0 ? { stdin } : {}), ...(shift !== undefined ? { shift } : {}) });
516
523
  };
@@ -94,6 +94,7 @@ export function rebasePlan(plan, from, to, floor) {
94
94
  ...(s.baseMove !== undefined ? { baseMove: { target: typeof s.baseMove.target === "string" ? s.baseMove.target : moveCandidate(s.baseMove.target) } } : {}),
95
95
  bases: s.bases === "unmodelled" || to === "unmodelled" ? "unmodelled" : [...new Set(s.bases.flatMap(moveBase))],
96
96
  nested: s.nested.map((n) => rebasePlan(n, from, to, floor)),
97
+ ...(s.printed !== undefined ? { printed: s.printed.map((n) => rebasePlan(n, from, to, floor)) } : {}),
97
98
  })),
98
99
  };
99
100
  }
@@ -136,11 +136,25 @@ export declare function spellLaunched(argv: readonly LexedWord[], args: readonly
136
136
  export declare function scriptFileAt(basename: string, args: readonly string[]): number | undefined;
137
137
  /** One text that may arrive on a segment's standard input: `from` = its source as written (a here-document's body,
138
138
  * `<<<WORD`, `<FILE`, `<&N`, the segment the pipe comes from); `literal` = the text, where the command spells it — a
139
- * here-document or here-string written in the command; never a pipe's text, which a program PRODUCES. */
139
+ * here-document or here-string written in the command; never a pipe's text, which a program PRODUCES. `printed` = the
140
+ * text a literal printer producing it spells ({@link printedBy}: the pipe's producer, the body of a `< <(…)`) — what the
141
+ * printer's words say it prints, never what the shell is known to receive: read only for what it refuses. */
140
142
  export interface StdinText {
141
143
  readonly from: string;
142
144
  readonly literal?: string;
145
+ readonly printed?: string;
143
146
  }
147
+ /** The text a producer's words say it prints ({@link printedText}): one simple command — no redirection, here-document or
148
+ * group — whose program word and every argument are literal, run by a printer row. `undefined` for any other producer. The
149
+ * reading is no claim about the stream (a function, an alias or a trap of the printer's name, a second writer on it are not
150
+ * read): its one reader refuses by it and never clears by it (`ShellReadSegment.printed`). */
151
+ export declare function printedBy(segment: LexedSegment): string | undefined;
152
+ /** What a pipe hands the segment after it: the producing segment as written, and the text it spells where it is a literal
153
+ * printer ({@link printedBy}). */
154
+ export declare function pipedTextOf(producer: LexedSegment): StdinText;
155
+ /** The text a word that is one process substitution prints, where its body is one literal printer ({@link printedBy}):
156
+ * `<(printf 'X')` — a script file a shell is handed, or the file its standard input is redirected from. */
157
+ export declare function printedByProcess(word: LexedWord): string | undefined;
144
158
  /** What may arrive on a segment's standard input: each here-document (its descriptor is not read: every one counts) —
145
159
  * its body, literal when quoted or when nothing in it expands — each here-string (literal when its word is), `<` file
146
160
  * or `<&` descriptor written to no other descriptor, and what it inherits (`fed`: the pipe it is reached through, the
@@ -1,6 +1,6 @@
1
- import { literalHeredocBody, literalTextOf } from "../../shell/lex.js";
1
+ import { lexShell, literalHeredocBody, literalTextOf } from "../../shell/lex.js";
2
2
  import { programBasename, readProgramPosition } from "./bash-program-position.js";
3
- import { implementationRejects, implementationsOf, programRow, readArgRoles, selectedOptions, selectedSpellings, targetUserOf } from "./program-read-model.js";
3
+ import { implementationRejects, implementationsOf, printedText, programRow, readArgRoles, selectedOptions, selectedSpellings, targetUserOf } from "./program-read-model.js";
4
4
  import { namesStandardInput } from "./safety.js";
5
5
  export function codeBodies(basename, args) {
6
6
  const row = programRow(basename);
@@ -240,6 +240,27 @@ function scriptSourceOf(row, args) {
240
240
  return { stdin: true };
241
241
  return { file: first.at, stdin: options.some((e) => e.kind === "option" && e.reading === "speculative") };
242
242
  }
243
+ export function printedBy(segment) {
244
+ if (segment.tokens.some((t) => t.kind !== "word"))
245
+ return undefined;
246
+ const argv = segment.tokens.filter((t) => t.kind === "word");
247
+ const pos = readProgramPosition(argv);
248
+ const program = pos.program;
249
+ if (program === undefined || pos.refusal !== undefined || pos.launchers.length > 0 || literalTextOf(argv[program.index].pieces) === undefined)
250
+ return undefined;
251
+ return printedText(programRow(program.basename), argv.slice(program.index + 1).map((w) => literalTextOf(w.pieces)));
252
+ }
253
+ export function pipedTextOf(producer) {
254
+ const printed = printedBy(producer);
255
+ return { from: `${producer.text.trim()} |`, ...(printed !== undefined ? { printed } : {}) };
256
+ }
257
+ export function printedByProcess(word) {
258
+ const e = word.pieces.length === 1 ? word.pieces[0].expansion : undefined;
259
+ if (e?.kind !== "process" || e.body === undefined || !word.raw.startsWith("<("))
260
+ return undefined;
261
+ const lexed = lexShell(e.body);
262
+ return "parseFailure" in lexed || lexed.segments.length !== 1 ? undefined : printedBy(lexed.segments[0]);
263
+ }
243
264
  export function stdinTextsOf(segment, fed) {
244
265
  const out = [];
245
266
  let replacesPipe = false;
@@ -250,7 +271,8 @@ export function stdinTextsOf(segment, fed) {
250
271
  }
251
272
  else if (t.kind === "redirect" && (t.fd ?? 0) === 0 && (t.op === "<<<" || t.op === "<" || t.op === "<>" || (t.op === "<&" && t.dup !== "-"))) {
252
273
  const literal = t.op === "<<<" && t.target !== undefined ? literalTextOf(t.target.pieces) : undefined;
253
- out.push({ from: `${t.op}${t.target?.raw ?? t.dup ?? ""}`, ...(literal !== undefined ? { literal } : {}) });
274
+ const printed = t.op === "<" && t.target !== undefined ? printedByProcess(t.target) : undefined;
275
+ out.push({ from: `${t.op}${t.target?.raw ?? t.dup ?? ""}`, ...(literal !== undefined ? { literal } : {}), ...(printed !== undefined ? { printed } : {}) });
254
276
  replacesPipe = true;
255
277
  }
256
278
  }
@@ -6,7 +6,7 @@
6
6
  * CC-parity semantics (live-harness schema, the archived ground truth):
7
7
  * ① every stdout LINE becomes one event; ② lines within the 200ms batch window coalesce into ONE
8
8
  * notification; ③ process exit ends the watch (exit code reported); ④ non-persistent watches are killed at
9
- * `timeout_ms` (default 5min, max 60min); ⑤ stderr never notifies but is spooled (TaskOutput-readable);
9
+ * `timeout_ms` (default 5min, max 60min); ⑤ stderr never notifies but is mirrored to the output file (with stdout);
10
10
  * ⑥ an event storm is SUPPRESSED first and auto-stops the monitor only if it persists (RB-334, CC `PCo`
11
11
  * 220:403278-403321 two-level control — the suppressed count and the overload duration are disclosed
12
12
  * on both the suppression frame and the stop notification).
@@ -25,7 +25,8 @@
25
25
  * in-window non-persistent watch alive (process on the dispose except-list, watcher ticking, row kept), so
26
26
  * cross-turn watching — CC's main Monitor use case — works with the default persistent:false too; its
27
27
  * between-turns events AND its timeout/exit terminal ride the same pending lane.
28
- * The handle is a first-class m* registry task: TaskOutput serves the re-readable spool, TaskStop stops the
28
+ * The handle is a first-class m* registry task: its output file is the full record (Read-exempt like a background
29
+ * Bash's, `TaskRegistry.isBackgroundOutputFile`), TaskStop stops the
29
30
  * watch (design/134 stoppedBy attribution applies automatically).
30
31
  *
31
32
  * Security posture: `command` is an arbitrary shell script ⇒ effect:"write", same as Bash; the catalog puts Monitor on the
@@ -40,9 +41,10 @@
40
41
  */
41
42
  import type { AgentTool, ExecutionEnv } from "../internal/harness-types.js";
42
43
  import { type MonitorTimers, type TaskRegistry } from "../core/task-registry.js";
43
- import type { TaskNotificationPayload } from "../core/task-notification.js";
44
+ import { type TaskNotificationPayload } from "../core/task-notification.js";
44
45
  import type { ToolResultStore } from "../core/tool-result-store.js";
45
46
  import type { ShellReadAdmission } from "./fs/shell-read-check.js";
47
+ import type { ReadFloorSeat } from "./fs/read-floor.js";
46
48
  export interface MonitorToolOptions {
47
49
  registry: TaskRegistry;
48
50
  /** Fallbacks when the runtime ctx carries no identity (direct mounts) — same posture as createBashTool. */
@@ -52,7 +54,7 @@ export interface MonitorToolOptions {
52
54
  * turn; reaped by the deployment's session release via `reapSessionBackground`). */
53
55
  sessionId?: string;
54
56
  /** The notification sink (the run-local task-notification lane). Without it the monitor still runs and
55
- * spools — readable via TaskOutput — but no events reach the model (the tool reply says so honestly). */
57
+ * mirrors its output file, but no events reach the model (the tool reply says so honestly). */
56
58
  onTaskNotification?: (n: TaskNotificationPayload, opts?: {
57
59
  priority?: "now" | "next" | "later";
58
60
  }) => void;
@@ -73,6 +75,9 @@ export interface MonitorToolOptions {
73
75
  * spawns a shell command too, so what it runs is what the station judged, re-established before the watch
74
76
  * spawns. Absent ⇒ no station judged this mount; nothing is re-established. */
75
77
  shellReadAdmission?: ShellReadAdmission;
78
+ /** The byte floor's seat (read-floor.ts) — the SAME table the shell faces carry: the watched command's start hands it to
79
+ * the environment. Absent ⇒ the start carries no floor. */
80
+ readFloor?: ReadFloorSeat;
76
81
  /** RB-465-b (HRD-PTL-3 残件): spec-level retain (`TaskSpec.retainBackgroundProcesses`) — the task lane of
77
82
  * THE retain predicate (`retainsBackgroundProcesses`), OR-composed with the env capability. Read twice,
78
83
  * by the same predicate: the persistent-watch receipt's wording, and the row's `retained` mark at
@@ -1,7 +1,8 @@
1
1
  import { Type } from "typebox";
2
2
  import { defineTool, errorResult } from "../core/tools.js";
3
- import { envDeclaresRetain, hasBackgroundShell, retainsBackgroundProcesses } from "../core/background-shell.js";
3
+ import { createBackgroundOutputFile, envDeclaresRetain, hasBackgroundShell, retainsBackgroundProcesses } from "../core/background-shell.js";
4
4
  import { MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, } from "../core/task-registry.js";
5
+ import { resolveCompletionSink } from "../core/task-notification.js";
5
6
  import { toolFace } from "../core/tool-catalog-entries.js";
6
7
  import { isDeadCwd, diagnoseDeadCwd } from "./fs/dead-cwd.js";
7
8
  import { thrownText } from "../core/thrown-value.js";
@@ -11,8 +12,8 @@ const MONITOR_DESCRIPTION = "Run a shell command in the background and watch its
11
12
  "multiple lines arriving within a short window (~200ms) are batched into a single notification.\n" +
12
13
  "- When the command exits, the watch ends and one final notification reports its exit code. A watch that " +
13
14
  `exceeds its timeout is killed and reported (default ${MONITOR_DEFAULT_TIMEOUT_MS}ms, max ${MONITOR_MAX_TIMEOUT_MS}ms).\n` +
14
- "- stderr does NOT trigger notifications, but it is captured — read it any time with TaskOutput(task_id), " +
15
- "which also serves the full re-readable stdout spool.\n" +
15
+ "- stderr does NOT trigger notifications, but it is captured — stdout and stderr are both appended to the output " +
16
+ "file the start receipt names; Read that file any time.\n" +
16
17
  "- A monitor that produces too many events is rate-limited: excess batches are suppressed (a notification tells you how many), and a watch that stays over the limit is stopped automatically.\n" +
17
18
  "- Set persistent: true for a session-resident watch with no watch timeout of its own; it still ends when " +
18
19
  "the execution environment's background time budget expires, when you stop it with TaskStop(task_id), or " +
@@ -79,19 +80,24 @@ export function createMonitorTool(env, opts) {
79
80
  }
80
81
  if (ctx.signal?.aborted === true)
81
82
  return errorResult("Error (Monitor): the call was cancelled before the watch started.");
83
+ const readFloor = opts.readFloor?.(ctx.toolCallId);
82
84
  const spawn = await env.spawnBackground(command, {
83
85
  ...(opts.cwdRef !== undefined ? { cwd: opts.cwdRef.current } : {}),
84
86
  ...(spawnTimeoutSec !== undefined ? { timeout: spawnTimeoutSec } : {}),
87
+ ...(readFloor !== undefined ? { readFloor } : {}),
85
88
  });
86
89
  if (!spawn.ok)
87
90
  return errorResult(`Error (Monitor): ${spawn.error.message}`);
88
91
  const sessionScoped = isPersistent && opts.sessionId !== undefined;
89
92
  const owner = sessionScoped ? opts.sessionId : (ctx.taskId ?? opts.owner);
90
93
  const scope = ctx.principal ?? opts.scope;
91
- const onNotify = opts.onTaskNotification;
94
+ const onNotify = resolveCompletionSink(ctx.onTaskNotification, opts.onTaskNotification);
95
+ const outputFile = await createBackgroundOutputFile(env, "monitor-task-");
92
96
  let taskId;
93
97
  try {
94
98
  taskId = opts.registry.registerMonitor({
99
+ ...(outputFile !== undefined ? { outputFile } : {}),
100
+ ...(ctx.taskArtifacts !== undefined ? { taskArtifacts: ctx.taskArtifacts } : {}),
95
101
  env,
96
102
  shellId: spawn.value.shellId,
97
103
  description,
@@ -124,7 +130,7 @@ export function createMonitorTool(env, opts) {
124
130
  return errorResult(killDetail === undefined
125
131
  ? `Error (Monitor): the watch process was started but could not be registered (${why}); it has been terminated.`
126
132
  : `Error (Monitor): the watch process was started but could not be registered (${why}), and it could NOT be terminated either (${killDetail}). ` +
127
- `It may still be running as background shell ${spawn.value.shellId}; no task id was minted, so TaskOutput/TaskStop cannot reach it — ` +
133
+ `It may still be running as background shell ${spawn.value.shellId}; no task id was minted, so TaskStop cannot reach it — ` +
128
134
  "stop it out of band (the environment's own background time budget and its teardown sweep are the remaining backstops).");
129
135
  }
130
136
  const bgTimeout = envBackgroundWallSec(env.backgroundCapabilities, spawnTimeoutSec);
@@ -157,12 +163,15 @@ export function createMonitorTool(env, opts) {
157
163
  : envWallWins
158
164
  ? `The watch may run up to ${envWallMs}ms — the execution environment's background time budget (${bgTimeout}s) is shorter than the ${timeoutMs}ms watch timeout${clampNote}, and the shorter of the two wins.`
159
165
  : `The watch may run up to ${timeoutMs}ms${clampNote}.`;
166
+ const fileClause = outputFile !== undefined
167
+ ? `Output file: ${outputFile} (stdout and stderr are appended there — Read it any time).`
168
+ : "No output file could be created for this watch.";
160
169
  const content = onNotify !== undefined
161
170
  ? `Monitoring in background; task_id=${taskId}. Each stdout line becomes a notification event (lines within ` +
162
171
  `~200ms are batched); you'll get a final notification with the exit code when it ends — do not poll. ` +
163
- `${lifetime} TaskOutput("${taskId}") reads the full spool (stdout+stderr); TaskStop("${taskId}") stops the watch.`
164
- : `Monitoring in background; task_id=${taskId}. No notification channel is wired in this mount — read output with ` +
165
- `TaskOutput("${taskId}") (re-readable spool, stdout+stderr) and stop with TaskStop("${taskId}"). ${lifetime}`;
172
+ `${lifetime} ${fileClause} TaskStop("${taskId}") stops the watch.`
173
+ : `Monitoring in background; task_id=${taskId}. No notification channel is wired in this mount, so no event or final notification will reach you. ` +
174
+ `${fileClause} Stop it with TaskStop("${taskId}"). ${lifetime}`;
166
175
  return {
167
176
  content,
168
177
  details: {