@sema-agent/core 7.58.0 → 7.59.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (284) hide show
  1. package/CHANGELOG.md +776 -0
  2. package/README.md +6 -4
  3. package/dist/agents/cc-peer-directory.js +8 -8
  4. package/dist/agents/child-model-seat.d.ts +4 -2
  5. package/dist/agents/child-model-seat.js +5 -3
  6. package/dist/agents/peer-directory.d.ts +9 -0
  7. package/dist/agents/peer-directory.js +6 -2
  8. package/dist/agents/send-message-tool.js +21 -12
  9. package/dist/agents/subagent.js +33 -34
  10. package/dist/brain/anthropic.js +161 -45
  11. package/dist/brain/errors.d.ts +9 -3
  12. package/dist/brain/errors.js +7 -1
  13. package/dist/brain/failover.js +2 -1
  14. package/dist/brain/open-responses.js +3 -3
  15. package/dist/brain/openai.js +103 -53
  16. package/dist/brain/provider-dialect.d.ts +11 -0
  17. package/dist/brain/provider-dialect.js +5 -2
  18. package/dist/brain/reasoning-request.js +5 -4
  19. package/dist/brain/reasoning.d.ts +19 -0
  20. package/dist/brain/reasoning.js +17 -2
  21. package/dist/brain/request-route.d.ts +4 -1
  22. package/dist/brain/request-route.js +4 -1
  23. package/dist/brain/route-adjudicator.d.ts +84 -18
  24. package/dist/brain/route-adjudicator.js +87 -21
  25. package/dist/brain/route-conformance.js +1 -1
  26. package/dist/brain/stream-engine.js +84 -49
  27. package/dist/brain/stream-shared.d.ts +30 -0
  28. package/dist/brain/stream-shared.js +34 -1
  29. package/dist/brain/timeout.d.ts +62 -5
  30. package/dist/brain/timeout.js +93 -6
  31. package/dist/core/account-row.d.ts +61 -0
  32. package/dist/core/account-row.js +51 -0
  33. package/dist/core/advisor-verdict.d.ts +2 -1
  34. package/dist/core/advisor-verdict.js +1 -1
  35. package/dist/core/allow-entry.d.ts +18 -6
  36. package/dist/core/allow-entry.js +16 -8
  37. package/dist/core/approval-object.d.ts +29 -15
  38. package/dist/core/approval-object.js +47 -19
  39. package/dist/core/auto-compaction.js +1 -1
  40. package/dist/core/background-agent-store.d.ts +16 -3
  41. package/dist/core/checkpoint-requirements.d.ts +13 -1
  42. package/dist/core/checkpoint-requirements.js +3 -1
  43. package/dist/core/checkpoint-store.d.ts +58 -12
  44. package/dist/core/checkpoint-store.js +18 -6
  45. package/dist/core/child-clamp-seats.d.ts +29 -0
  46. package/dist/core/child-clamp-seats.js +56 -1
  47. package/dist/core/compliance.d.ts +2 -2
  48. package/dist/core/compliance.js +1 -1
  49. package/dist/core/effective-path-target.d.ts +8 -2
  50. package/dist/core/effective-path-target.js +8 -3
  51. package/dist/core/engine-notice.d.ts +98 -8
  52. package/dist/core/engine-notice.js +19 -5
  53. package/dist/core/gate-fold.js +1 -1
  54. package/dist/core/gate-lanes.js +8 -4
  55. package/dist/core/gate-outcome.d.ts +32 -3
  56. package/dist/core/gate-outcome.js +19 -1
  57. package/dist/core/governance-codes.d.ts +9 -1
  58. package/dist/core/governance-codes.js +13 -0
  59. package/dist/core/hooks.d.ts +31 -3
  60. package/dist/core/hooks.js +5 -6
  61. package/dist/core/image-admission.d.ts +6 -5
  62. package/dist/core/image-admission.js +18 -14
  63. package/dist/core/locked-config.d.ts +5 -2
  64. package/dist/core/locked-config.js +2 -1
  65. package/dist/core/mailbox-store.d.ts +45 -1
  66. package/dist/core/mailbox-store.js +53 -9
  67. package/dist/core/mcp-failure.d.ts +114 -18
  68. package/dist/core/mcp-failure.js +63 -5
  69. package/dist/core/mcp-server-link.d.ts +22 -1
  70. package/dist/core/mcp-server-link.js +25 -1
  71. package/dist/core/mcp.d.ts +12 -8
  72. package/dist/core/mcp.js +42 -25
  73. package/dist/core/memory-engine/consolidation-driver.d.ts +2 -4
  74. package/dist/core/memory-engine/consolidation-driver.js +3 -3
  75. package/dist/core/memory-engine/consolidation.d.ts +4 -0
  76. package/dist/core/memory-engine/consolidation.js +1 -0
  77. package/dist/core/memory-engine/delegation-settlement.js +5 -12
  78. package/dist/core/memory-engine/distiller.js +2 -2
  79. package/dist/core/memory-engine/dual-root.d.ts +50 -1
  80. package/dist/core/memory-engine/dual-root.js +44 -1
  81. package/dist/core/memory-engine/engine.d.ts +67 -14
  82. package/dist/core/memory-engine/engine.js +384 -212
  83. package/dist/core/memory-engine/export-bundle.d.ts +23 -0
  84. package/dist/core/memory-engine/export-bundle.js +23 -4
  85. package/dist/core/memory-engine/file-backend.d.ts +128 -55
  86. package/dist/core/memory-engine/file-backend.js +290 -117
  87. package/dist/core/memory-engine/index.d.ts +1 -1
  88. package/dist/core/memory-engine/layout.d.ts +59 -11
  89. package/dist/core/memory-engine/layout.js +190 -40
  90. package/dist/core/memory-engine/memory-backend-contract.d.ts +1 -1
  91. package/dist/core/memory-engine/memory-backend-contract.js +39 -2
  92. package/dist/core/memory-engine/sync-client.d.ts +9 -1
  93. package/dist/core/memory-engine/sync-client.js +31 -8
  94. package/dist/core/memory-engine/sync.d.ts +5 -0
  95. package/dist/core/memory-engine/types.d.ts +6 -0
  96. package/dist/core/mods/classic-events.d.ts +5 -1
  97. package/dist/core/mods/kernel/dispatch.js +2 -1
  98. package/dist/core/mods/kernel/events.d.ts +2 -1
  99. package/dist/core/mods/kernel/events.js +2 -2
  100. package/dist/core/mods/kernel/registration.d.ts +4 -0
  101. package/dist/core/mods/kernel/registration.js +3 -0
  102. package/dist/core/mods/stations.d.ts +31 -10
  103. package/dist/core/mods/stations.js +44 -10
  104. package/dist/core/mods/tool-call.js +1 -1
  105. package/dist/core/parent-spec-seat.d.ts +8 -3
  106. package/dist/core/parent-spec-seat.js +2 -0
  107. package/dist/core/park-selfcheck.js +6 -0
  108. package/dist/core/peer-seat.d.ts +70 -8
  109. package/dist/core/peer-seat.js +143 -11
  110. package/dist/core/permission-rule-consent.js +10 -4
  111. package/dist/core/permission-rule-model.d.ts +16 -0
  112. package/dist/core/permission-rule-model.js +1 -1
  113. package/dist/core/present-plan-tool.d.ts +11 -3
  114. package/dist/core/present-plan-tool.js +2 -2
  115. package/dist/core/resume-startup-cause.js +1 -0
  116. package/dist/core/rewrite-rejudge.d.ts +1 -0
  117. package/dist/core/rewrite-rejudge.js +2 -2
  118. package/dist/core/roles.d.ts +34 -2
  119. package/dist/core/roles.js +43 -4
  120. package/dist/core/runner/announce-once-ledger.d.ts +5 -4
  121. package/dist/core/runner/announce-once-ledger.js +4 -2
  122. package/dist/core/runner/call-hook-stations.js +2 -2
  123. package/dist/core/runner/contracts.d.ts +20 -16
  124. package/dist/core/runner/credential-origin-seat.js +4 -3
  125. package/dist/core/runner/cwd-alignment-probe.d.ts +20 -0
  126. package/dist/core/runner/cwd-alignment-probe.js +21 -0
  127. package/dist/core/runner/decide-continuation.d.ts +2 -2
  128. package/dist/core/runner/gate-exit.d.ts +12 -4
  129. package/dist/core/runner/gate-exit.js +10 -7
  130. package/dist/core/runner/image-removed-seat.d.ts +12 -0
  131. package/dist/core/runner/image-removed-seat.js +19 -0
  132. package/dist/core/runner/inline-image.js +1 -1
  133. package/dist/core/runner/memory-consolidation-driver.js +3 -3
  134. package/dist/core/runner/park-commit.d.ts +1 -1
  135. package/dist/core/runner/park-commit.js +3 -0
  136. package/dist/core/runner/prepare-ask-lane.d.ts +1 -1
  137. package/dist/core/runner/prepare-ask-lane.js +2 -1
  138. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  139. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -5
  140. package/dist/core/runner/prepare-caps-and-workflow.js +2 -0
  141. package/dist/core/runner/prepare-config-doors.js +2 -0
  142. package/dist/core/runner/prepare-context-lane.js +2 -0
  143. package/dist/core/runner/prepare-delegation-surface.d.ts +4 -0
  144. package/dist/core/runner/prepare-delegation-surface.js +1 -0
  145. package/dist/core/runner/prepare-hands-readface.d.ts +4 -0
  146. package/dist/core/runner/prepare-hands-readface.js +5 -0
  147. package/dist/core/runner/prepare-inherited-gate.d.ts +1 -3
  148. package/dist/core/runner/prepare-inherited-gate.js +14 -27
  149. package/dist/core/runner/prepare-memory.js +10 -17
  150. package/dist/core/runner/prepare-park-ask.d.ts +1 -1
  151. package/dist/core/runner/prepare-park-ask.js +2 -1
  152. package/dist/core/runner/prepare-policy-chain.d.ts +3 -3
  153. package/dist/core/runner/prepare-policy-chain.js +16 -13
  154. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  155. package/dist/core/runner/prepare-project-context.js +2 -2
  156. package/dist/core/runner/prepare-prompt-inputs.d.ts +1 -1
  157. package/dist/core/runner/prepare-prompt-inputs.js +8 -19
  158. package/dist/core/runner/prepare-protocol-tools.js +9 -1
  159. package/dist/core/runner/prepare-run-refs.d.ts +2 -3
  160. package/dist/core/runner/prepare-run-refs.js +4 -1
  161. package/dist/core/runner/prepare-task.js +4 -2
  162. package/dist/core/runner/prepare-wiring-manifest.d.ts +1 -1
  163. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  164. package/dist/core/runner/reply-pricing.d.ts +30 -0
  165. package/dist/core/runner/reply-pricing.js +19 -0
  166. package/dist/core/runner/resume-admission.js +4 -2
  167. package/dist/core/runner/resume-apply.js +6 -1
  168. package/dist/core/runner/resume-policy-outcome.js +5 -5
  169. package/dist/core/runner/role-seat-defaulted.d.ts +44 -0
  170. package/dist/core/runner/role-seat-defaulted.js +40 -0
  171. package/dist/core/runner/run-brain-sinks.js +2 -0
  172. package/dist/core/runner/run-identity-wiring.d.ts +2 -5
  173. package/dist/core/runner/run-identity-wiring.js +5 -4
  174. package/dist/core/runner/run-leg.d.ts +2 -0
  175. package/dist/core/runner/run-leg.js +37 -28
  176. package/dist/core/runner/run-stop-and-final-verify.js +2 -2
  177. package/dist/core/runner/run-terminal-adoption.d.ts +2 -5
  178. package/dist/core/runner/run-terminal-adoption.js +9 -3
  179. package/dist/core/runner/run-turn-boundary.js +77 -70
  180. package/dist/core/runner/runtask.d.ts +1 -1
  181. package/dist/core/runner/runtask.js +2 -2
  182. package/dist/core/runner/side-call-account.d.ts +1 -1
  183. package/dist/core/runner/side-call-account.js +3 -18
  184. package/dist/core/runner/sub-agent-deny-lists.d.ts +24 -0
  185. package/dist/core/runner/sub-agent-deny-lists.js +10 -0
  186. package/dist/core/runner/tool-end-body.js +2 -2
  187. package/dist/core/runner/tool-occurrence.d.ts +1 -1
  188. package/dist/core/runner/tool-occurrence.js +2 -2
  189. package/dist/core/runner/turn-attachments.d.ts +26 -22
  190. package/dist/core/runner/turn-attachments.js +24 -26
  191. package/dist/core/runner-deps.d.ts +1 -1
  192. package/dist/core/secret-env.d.ts +32 -2
  193. package/dist/core/secret-env.js +65 -3
  194. package/dist/core/sensitive-path-policy.js +3 -3
  195. package/dist/core/session-policy-store.d.ts +3 -1
  196. package/dist/core/session-policy-store.js +13 -9
  197. package/dist/core/session-store.d.ts +2 -5
  198. package/dist/core/side-query.d.ts +11 -1
  199. package/dist/core/side-query.js +9 -0
  200. package/dist/core/skill-grant-binding.d.ts +31 -2
  201. package/dist/core/skill-grant-binding.js +31 -1
  202. package/dist/core/skill-grant.d.ts +8 -5
  203. package/dist/core/skill-grant.js +6 -6
  204. package/dist/core/store-contracts/background-agent-store-contract.js +27 -0
  205. package/dist/core/store-contracts/checkpoint-store-contract.js +3 -2
  206. package/dist/core/store-contracts/mailbox-store-contract.js +31 -1
  207. package/dist/core/synthetic-read-verdict.js +2 -1
  208. package/dist/core/task-event.d.ts +32 -8
  209. package/dist/core/task-notification.js +16 -10
  210. package/dist/core/task-registry-agent.js +1 -0
  211. package/dist/core/task-registry-shared.d.ts +5 -0
  212. package/dist/core/task-spec.d.ts +12 -1
  213. package/dist/core/terminal-cause.d.ts +10 -0
  214. package/dist/core/tool-check-reading.d.ts +1 -0
  215. package/dist/core/tool-check-reading.js +3 -3
  216. package/dist/core/tool-policy.d.ts +16 -0
  217. package/dist/core/tool-roster.d.ts +112 -5
  218. package/dist/core/tool-roster.js +42 -1
  219. package/dist/core/tool-spec.d.ts +3 -1
  220. package/dist/core/types.d.ts +2 -2
  221. package/dist/core/types.js +1 -1
  222. package/dist/core/user-attachment.js +1 -1
  223. package/dist/core/wiring-manifest.d.ts +6 -3
  224. package/dist/engine/compaction/compaction.js +29 -3
  225. package/dist/engine/execution-env/node-execution-env.d.ts +4 -3
  226. package/dist/engine/execution-env/node-execution-env.js +9 -12
  227. package/dist/engine/harness/agent-harness.d.ts +25 -2
  228. package/dist/engine/harness/agent-harness.js +41 -12
  229. package/dist/engine/harness/messages.d.ts +3 -1
  230. package/dist/engine/harness/messages.js +3 -2
  231. package/dist/engine/harness/types.d.ts +8 -0
  232. package/dist/engine/llm/rejected-images.d.ts +46 -0
  233. package/dist/engine/llm/rejected-images.js +54 -0
  234. package/dist/engine/llm/tool-turns.d.ts +2 -1
  235. package/dist/engine/llm/types.d.ts +18 -7
  236. package/dist/engine/loop/agent-loop.d.ts +8 -0
  237. package/dist/engine/loop/agent-loop.js +52 -15
  238. package/dist/engine/loop/types.d.ts +3 -1
  239. package/dist/engine/session/path-to-root.d.ts +38 -0
  240. package/dist/engine/session/path-to-root.js +39 -0
  241. package/dist/engine/session/storage-base.js +4 -21
  242. package/dist/index.d.ts +16 -10
  243. package/dist/index.js +11 -7
  244. package/dist/internal/harness-types.d.ts +1 -1
  245. package/dist/internal/harness.d.ts +1 -0
  246. package/dist/internal/llm.d.ts +1 -0
  247. package/dist/orchestration/workflow-observe.d.ts +17 -1
  248. package/dist/orchestration/workflow-observe.js +20 -0
  249. package/dist/orchestration/workflow-types.d.ts +32 -7
  250. package/dist/orchestration/workflow.js +739 -489
  251. package/dist/shell/counting-pass.d.ts +50 -0
  252. package/dist/shell/counting-pass.js +502 -0
  253. package/dist/shell/lex.d.ts +4 -2
  254. package/dist/shell/lex.js +93 -34
  255. package/dist/shell/shell-words.d.ts +1 -1
  256. package/dist/shell/shell-words.js +7 -6
  257. package/dist/stores/file/mailbox-store.js +6 -10
  258. package/dist/tools/fs/fs-bash.d.ts +6 -0
  259. package/dist/tools/fs/fs-bash.js +6 -3
  260. package/dist/tools/fs/index.js +6 -2
  261. package/dist/tools/fs/program-read-model.d.ts +13 -0
  262. package/dist/tools/fs/program-read-model.js +15 -0
  263. package/dist/tools/fs/program-read-model.rows.js +1 -1
  264. package/dist/tools/fs/read-deny.d.ts +13 -10
  265. package/dist/tools/fs/read-deny.js +25 -5
  266. package/dist/tools/fs/read-floor.d.ts +19 -0
  267. package/dist/tools/fs/read-floor.js +23 -0
  268. package/dist/tools/fs/shell-read-check.d.ts +1 -1
  269. package/dist/tools/fs/shell-read-check.js +2 -1
  270. package/dist/tools/fs/shell-read-judge.d.ts +16 -8
  271. package/dist/tools/fs/shell-read-judge.js +10 -6
  272. package/dist/tools/fs/shell-read-plan.d.ts +6 -1
  273. package/dist/tools/fs/shell-read-plan.js +22 -15
  274. package/dist/tools/fs/shell-read-start.js +1 -0
  275. package/dist/tools/fs/shell-reentry-text.d.ts +15 -1
  276. package/dist/tools/fs/shell-reentry-text.js +25 -3
  277. package/dist/tools/monitor.d.ts +4 -0
  278. package/dist/tools/monitor.js +2 -0
  279. package/package.json +3 -2
  280. package/test/export-surface.snapshot.json +87 -1
  281. package/wire-changes/core-stores-sql@7.59.0.json +29 -0
  282. package/wire-changes/core@7.59.0.json +2459 -0
  283. package/wire-changes/mods-kernel@7.59.0.json +29 -0
  284. package/wire-changes/primitives@7.59.0.json +29 -0
package/dist/shell/lex.js CHANGED
@@ -1,4 +1,5 @@
1
1
  import { shellWordsOf } from "./shell-words.js";
2
+ import { arithmeticCommandEnd, bracePassEnd, countingPassEnd, holdsHashFrom, passesFor, whileReading } from "./counting-pass.js";
2
3
  export const SHELL_LEX_DIALECT = "bash";
3
4
  export const QUOTE_KINDS = Object.freeze(["'", '"', "$'", '$"', "\\"]);
4
5
  export const EXPANSION_KINDS = Object.freeze(["parameter", "command", "process", "arithmetic", "tilde", "brace", "glob"]);
@@ -23,6 +24,7 @@ export const PARSE_FAILURE_REASONS = Object.freeze([
23
24
  "unterminated_arithmetic_expansion",
24
25
  "unterminated_heredoc",
25
26
  "undelimited_substitution",
27
+ "undelimited_substitution_heredoc",
26
28
  "redirect_without_target",
27
29
  "heredoc_without_delimiter",
28
30
  "heredoc_delimiter_expands",
@@ -39,6 +41,7 @@ export const PARSE_FAILURE_SENTENCE = {
39
41
  unterminated_arithmetic_expansion: "an arithmetic expansion never terminates",
40
42
  unterminated_heredoc: "a here-document body never terminates",
41
43
  undelimited_substitution: "a command substitution carries a construct this lexer cannot delimit",
44
+ undelimited_substitution_heredoc: "a here-document in a command substitution that shell versions end at different places — feed the text as stdin (`git commit -F -`) or reword it",
42
45
  redirect_without_target: "a redirection names no target",
43
46
  heredoc_without_delimiter: "a here-document operator names no delimiter",
44
47
  heredoc_delimiter_expands: "a here-document delimiter is not a plain word",
@@ -149,7 +152,19 @@ function heredocHeaderOf(word, dash) {
149
152
  return undefined;
150
153
  return { delimiter: word.folded, quoted: /["'\\]/.test(word.raw), dash };
151
154
  }
152
- function heredocBodies(text, from, headers, inSubstitution) {
155
+ function documentLine(text, p, joined) {
156
+ let nl = text.indexOf("\n", p);
157
+ let line = nl < 0 ? text.slice(p) : text.slice(p, nl);
158
+ if (joined) {
159
+ while (nl >= 0 && /(?<!\\)(?:\\\\)*\\$/.test(line)) {
160
+ const after = text.indexOf("\n", nl + 1);
161
+ line = line.slice(0, -1) + (after < 0 ? text.slice(nl + 1) : text.slice(nl + 1, after));
162
+ nl = after;
163
+ }
164
+ }
165
+ return { line, nl };
166
+ }
167
+ function heredocBodies(text, from, headers, closer) {
153
168
  const bodies = [];
154
169
  let p = from;
155
170
  for (const h of headers) {
@@ -157,21 +172,15 @@ function heredocBodies(text, from, headers, inSubstitution) {
157
172
  for (;;) {
158
173
  if (p > text.length)
159
174
  return "unterminated";
160
- let nl = text.indexOf("\n", p);
161
- let line = nl < 0 ? text.slice(p) : text.slice(p, nl);
162
- if (!h.quoted) {
163
- while (nl >= 0 && /(?<!\\)(?:\\\\)*\\$/.test(line)) {
164
- const after = text.indexOf("\n", nl + 1);
165
- line = line.slice(0, -1) + (after < 0 ? text.slice(nl + 1) : text.slice(nl + 1, after));
166
- nl = after;
167
- }
168
- }
175
+ const { line, nl } = documentLine(text, p, !h.quoted);
176
+ if (closer !== undefined && text.slice(p, nl < 0 ? text.length : nl + 1).includes("\\\n"))
177
+ return "ambiguous";
169
178
  const compared = h.dash ? line.replace(/^\t+/, "") : line;
170
179
  if (compared === h.delimiter) {
171
180
  p = nl < 0 ? text.length + 1 : nl + 1;
172
181
  break;
173
182
  }
174
- if (inSubstitution && compared.startsWith(h.delimiter))
183
+ if (closer !== undefined && compared.startsWith(h.delimiter) && (closer === ")" ? compared.indexOf(")", h.delimiter.length) >= 0 : /^[ \t]*\}/.test(compared.slice(h.delimiter.length))))
175
184
  return "ambiguous";
176
185
  if (nl < 0)
177
186
  return "unterminated";
@@ -231,7 +240,10 @@ function heredocHeaderAt(text, from, dash, op) {
231
240
  return header === undefined ? fail("heredoc_delimiter_expands", start) : { ...header, end: j };
232
241
  }
233
242
  const BASH_READING = { heredoc: true, startComment: true };
234
- const BASH32_READINGS = [{ heredoc: false, startComment: true }, { heredoc: false, startComment: false }];
243
+ const BASH32_PARSE = { heredoc: false, startComment: true };
244
+ const BASH32_EXPAND = { heredoc: false, startComment: false };
245
+ const NO_COMMENT_COUNT = { heredoc: false, startComment: false, noComments: true };
246
+ const BASH32_DOUBLE_QUOTED = { ...NO_COMMENT_COUNT };
235
247
  const ARITHMETIC_READING = { heredoc: false, startComment: true, arithmetic: true };
236
248
  const BODY_NESTING_MAX = 64;
237
249
  function walkBody(text, open, reading, inDouble, level) {
@@ -308,10 +320,12 @@ function walkBody(text, open, reading, inDouble, level) {
308
320
  word = "";
309
321
  continue;
310
322
  }
311
- if (c === "#" && wordStart) {
323
+ if (c === "#" && wordStart && reading.noComments !== true) {
312
324
  const nl = text.indexOf("\n", j);
313
325
  if (nl < 0)
314
326
  return "unterminated";
327
+ if (text[nl - 1] === "\\")
328
+ return "undelimited";
315
329
  j = nl - 1;
316
330
  word = "";
317
331
  continue;
@@ -351,6 +365,8 @@ function walkBody(text, open, reading, inDouble, level) {
351
365
  }
352
366
  const dash = text[third] === "-";
353
367
  const header = heredocHeaderAt(text, dash ? third + 1 : third, dash, j);
368
+ if (header === "undelimited")
369
+ return fail("undelimited_substitution_heredoc", j);
354
370
  if (typeof header !== "object" || !("delimiter" in header))
355
371
  return header;
356
372
  owed.push(header);
@@ -390,17 +406,26 @@ function walkBody(text, open, reading, inDouble, level) {
390
406
  continue;
391
407
  }
392
408
  if (c === "\n" && owed.length > 0) {
393
- const read = heredocBodies(text, j + 1, owed, true);
409
+ const read = heredocBodies(text, j + 1, owed, ")");
394
410
  if (read === "unterminated")
395
411
  return fail("unterminated_heredoc", j + 1);
396
412
  if (read === "ambiguous")
397
- return "undelimited";
413
+ return fail("undelimited_substitution_heredoc", j + 1);
398
414
  owed.length = 0;
399
415
  j = read.resume - 1;
400
416
  wordStart = true;
401
417
  word = "";
402
418
  continue;
403
419
  }
420
+ if (reading.heredoc && j > open && c === "(" && text[k] === "(") {
421
+ const end = arithmeticCommandEnd(text, k);
422
+ if (end !== undefined) {
423
+ j = end - 1;
424
+ wordStart = false;
425
+ word = "";
426
+ continue;
427
+ }
428
+ }
404
429
  if (c === "(")
405
430
  depth++;
406
431
  else if (c === ")") {
@@ -408,7 +433,7 @@ function walkBody(text, open, reading, inDouble, level) {
408
433
  if (depth === 1)
409
434
  innerClose ??= j;
410
435
  if (depth === 0)
411
- return owed.length > 0 ? "undelimited" : { end: j + 1, heredoc, ...(innerClose !== undefined ? { innerClose } : {}) };
436
+ return owed.length > 0 ? fail("undelimited_substitution_heredoc", j) : { end: j + 1, heredoc, ...(innerClose !== undefined ? { innerClose } : {}) };
412
437
  }
413
438
  if (!reading.heredoc) {
414
439
  wordStart = j === open ? reading.startComment && !inDouble && level === 0 : c === " " || c === "\t" || c === "\n";
@@ -422,21 +447,40 @@ function walkBody(text, open, reading, inDouble, level) {
422
447
  }
423
448
  return "unterminated";
424
449
  }
425
- function substitutionBodyEnd(text, open, inDouble, level) {
450
+ function doubleQuotedWordHolds(text, from, to) {
451
+ let inDq = true;
452
+ for (let j = from; j < to; j++) {
453
+ const c = text[j];
454
+ if (c === "\"")
455
+ inDq = !inDq;
456
+ else if (inDq ? c === "`" || (c === "$" && "({[".includes(text[j + 1] ?? "")) : " \t\n;&|<>()'`$\\".includes(c))
457
+ return false;
458
+ else if (inDq && c === "\\")
459
+ j++;
460
+ }
461
+ return inDq;
462
+ }
463
+ function substitutionBodyEnd(text, open, inDouble, level, form = "command") {
426
464
  const arithmetic = arithmeticWalk(text, open, inDouble, level);
427
- if (arithmetic !== undefined)
428
- return { end: arithmetic.end, arithmetic: true };
429
- const read = walkBody(text, open, BASH_READING, inDouble, level);
465
+ const read = arithmetic ?? walkBody(text, open, BASH_READING, inDouble, level);
430
466
  if (typeof read !== "object" || !("end" in read))
431
467
  return read;
432
- if (!read.heredoc)
433
- return { end: read.end, arithmetic: false };
434
- for (const reading of BASH32_READINGS) {
468
+ const refused = fail(read.heredoc ? "undelimited_substitution_heredoc" : "undelimited_substitution", open);
469
+ const doubled = text[past(text, open + 1)] === "(";
470
+ if (form !== "document")
471
+ for (const pass of passesFor(text, open)) {
472
+ const end = countingPassEnd(text, open, pass);
473
+ if (end !== read.end && end !== "unterminated")
474
+ return refused;
475
+ }
476
+ const counts = [...(form === "document" ? [] : [inDouble ? BASH32_DOUBLE_QUOTED : BASH32_PARSE]), BASH32_EXPAND, ...(doubled || form === "process" ? [NO_COMMENT_COUNT] : [])];
477
+ for (const reading of holdsHashFrom(text, open) ? counts : counts.slice(-1)) {
435
478
  const counted = walkBody(text, open, reading, inDouble, level);
436
- if (counted !== "unterminated" && !(typeof counted === "object" && "end" in counted && counted.end === read.end))
437
- return "undelimited";
479
+ if (counted === "unterminated" || (typeof counted === "object" && "end" in counted && (counted.end === read.end || (reading === BASH32_DOUBLE_QUOTED && counted.end < read.end && doubleQuotedWordHolds(text, counted.end, read.end)))))
480
+ continue;
481
+ return refused;
438
482
  }
439
- return { end: read.end, arithmetic: false };
483
+ return { end: read.end, arithmetic: arithmetic !== undefined };
440
484
  }
441
485
  function arithmeticWalk(text, open, inDouble, level) {
442
486
  if (text[past(text, open + 1)] !== "(")
@@ -478,10 +522,17 @@ function currentShellSubstitutionEnd(text, open, level) {
478
522
  if (level > BODY_NESTING_MAX)
479
523
  return "undelimited";
480
524
  const list = { from: open + (text[open + 1] === "|" ? 2 : 1), groups: 0 };
481
- const read = scan(text, false, [firstSegment(text)], level, list);
525
+ const segments = [firstSegment(text)];
526
+ const read = scan(text, false, segments, level, list);
482
527
  if ("parseFailure" in read)
483
528
  return read;
484
- return list.closed === undefined ? "undelimited" : { end: list.closed, from: list.from };
529
+ if (list.closed === undefined)
530
+ return "undelimited";
531
+ const closed = list.closed;
532
+ if (passesFor(text, open).some((pass) => { const end = bracePassEnd(text, open, pass); return end !== closed && end !== "unterminated"; })) {
533
+ return fail(segments.some((s) => s.tokens.some((t) => t.kind === "heredoc")) ? "undelimited_substitution_heredoc" : "undelimited_substitution", open);
534
+ }
535
+ return { end: closed, from: list.from };
485
536
  }
486
537
  function bracketExpansionEnd(text, open) {
487
538
  let depth = 0;
@@ -587,6 +638,9 @@ function backtickBody(source, open) {
587
638
  return undefined;
588
639
  }
589
640
  export function expansionsInHeredocBody(body) {
641
+ return whileReading(body, () => expansionsInBody(body));
642
+ }
643
+ function expansionsInBody(body) {
590
644
  const out = [];
591
645
  for (let i = 0; i < body.length; i++) {
592
646
  const ch = body[i];
@@ -606,7 +660,7 @@ export function expansionsInHeredocBody(body) {
606
660
  continue;
607
661
  const open = body[i + 1];
608
662
  if (open === "(") {
609
- const close = substitutionBodyEnd(body, i + 1, true, 0);
663
+ const close = substitutionBodyEnd(body, i + 1, true, 0, "document");
610
664
  if (typeof close !== "object" || !("end" in close))
611
665
  return undefined;
612
666
  out.push({ expansion: { kind: close.arithmetic ? "arithmetic" : "command", yields: "one", body: body.slice(i + 2, close.end - 1) } });
@@ -1151,6 +1205,9 @@ class WordBuilder {
1151
1205
  }
1152
1206
  }
1153
1207
  function scan(source, connectorsAreText, segments, level, list) {
1208
+ return whileReading(source, () => scanText(source, connectorsAreText, segments, level, list));
1209
+ }
1210
+ function scanText(source, connectorsAreText, segments, level, list) {
1154
1211
  const split = !connectorsAreText;
1155
1212
  const current = () => segments[segments.length - 1];
1156
1213
  const pendingHeredocs = [];
@@ -1278,7 +1335,9 @@ function scan(source, connectorsAreText, segments, level, list) {
1278
1335
  return undefined;
1279
1336
  };
1280
1337
  const readHeredocBodies = (from) => {
1281
- const read = heredocBodies(source, from, pendingHeredocs, false);
1338
+ const read = heredocBodies(source, from, pendingHeredocs, list === undefined ? undefined : "}");
1339
+ if (read === "ambiguous")
1340
+ return fail("undelimited_substitution_heredoc", from);
1282
1341
  if (typeof read !== "object")
1283
1342
  return fail("unterminated_heredoc", from);
1284
1343
  pendingHeredocs.forEach((h, k) => { h.token.body = read.bodies[k]; });
@@ -1295,7 +1354,7 @@ function scan(source, connectorsAreText, segments, level, list) {
1295
1354
  const ch = source[i];
1296
1355
  if (list !== undefined && ch === "}" && list.groups === 0 && !inSingle && !inDouble && !w.started && acceptable && pendingRedirect === undefined && pendingHeredoc === undefined) {
1297
1356
  if (pendingHeredocs.length > 0)
1298
- return fail("undelimited_substitution", i);
1357
+ return fail("undelimited_substitution_heredoc", i);
1299
1358
  list.closed = i + 1;
1300
1359
  return { command: { segments: [], substitutions: [] } };
1301
1360
  }
@@ -1472,7 +1531,7 @@ function scan(source, connectorsAreText, segments, level, list) {
1472
1531
  continue;
1473
1532
  }
1474
1533
  if ((ch === "<" || ch === ">") && source[n1] === "(") {
1475
- const close = substitutionBodyEnd(source, n1, false, level);
1534
+ const close = substitutionBodyEnd(source, n1, false, level, "process");
1476
1535
  if (typeof close !== "object" || !("end" in close))
1477
1536
  return close === "unterminated" ? fail("unterminated_process_substitution", i) : close === "undelimited" ? fail("undelimited_substitution", i) : close;
1478
1537
  substitution(i, close.end, source.slice(n1 + 1, close.end - 1), "process");
@@ -1535,7 +1594,7 @@ function scan(source, connectorsAreText, segments, level, list) {
1535
1594
  if (ch === "(") {
1536
1595
  if (arithParens > 0)
1537
1596
  arithParens++;
1538
- else if (split && source[next(i)] === "(")
1597
+ else if (split && source[next(i)] === "(" && arithmeticCommandEnd(source, next(i)) !== undefined)
1539
1598
  arithParens = 1;
1540
1599
  }
1541
1600
  else if (arithParens > 0)
@@ -1544,7 +1603,7 @@ function scan(source, connectorsAreText, segments, level, list) {
1544
1603
  resetPosition();
1545
1604
  continue;
1546
1605
  }
1547
- if (ch === "<" || ch === ">" || (ch === "&" && source[n1] === ">")) {
1606
+ if (arithParens === 0 && (ch === "<" || ch === ">" || (ch === "&" && source[n1] === ">"))) {
1548
1607
  let fd;
1549
1608
  if (ch !== "&" && w.started && w.raw === w.folded && /^\d+$/.test(w.raw)) {
1550
1609
  fd = Number(w.raw);
@@ -25,7 +25,7 @@
25
25
  *
26
26
  * Pure data and a pure projection: this module imports nothing.
27
27
  */
28
- export declare const SHELL_WORD_ROLES: readonly ["control_prefix", "group", "block", "compound_open", "loop_list_head", "loop_iterates", "loop_condition", "loop_end", "definition", "background", "case_arms", "timer", "scope_open", "scope_close", "scope_switch", "stripped_prefix", "stripped_standalone", "opaque", "rule_reserved", "base_mover", "stack_mover", "stack_editor"];
28
+ export declare const SHELL_WORD_ROLES: readonly ["control_prefix", "group", "block", "compound_open", "loop_list_head", "loop_iterates", "loop_condition", "loop_end", "definition", "background", "case_arms", "pass_keeps_reserved", "timer", "scope_open", "scope_close", "scope_switch", "stripped_prefix", "stripped_standalone", "opaque", "rule_reserved", "base_mover", "stack_mover", "stack_editor"];
29
29
  export type ShellWordRole = (typeof SHELL_WORD_ROLES)[number];
30
30
  /** Every word that plays `role`. The same set object on every call: a projection is a view, not a copy to edit. */
31
31
  export declare function shellWordsOf(role: ShellWordRole): ReadonlySet<string>;
@@ -10,6 +10,7 @@ export const SHELL_WORD_ROLES = Object.freeze([
10
10
  "definition",
11
11
  "background",
12
12
  "case_arms",
13
+ "pass_keeps_reserved",
13
14
  "timer",
14
15
  "scope_open",
15
16
  "scope_close",
@@ -25,21 +26,21 @@ export const SHELL_WORD_ROLES = Object.freeze([
25
26
  const ROWS = [
26
27
  ["!", "control_prefix", "stripped_prefix", "rule_reserved"],
27
28
  ["if", "control_prefix", "compound_open", "scope_open", "stripped_prefix", "rule_reserved"],
28
- ["then", "control_prefix", "stripped_prefix", "rule_reserved"],
29
- ["elif", "control_prefix", "scope_switch", "stripped_prefix", "rule_reserved"],
30
- ["else", "control_prefix", "scope_switch", "stripped_prefix", "rule_reserved"],
29
+ ["then", "control_prefix", "stripped_prefix", "rule_reserved", "pass_keeps_reserved"],
30
+ ["elif", "control_prefix", "scope_switch", "stripped_prefix", "rule_reserved", "pass_keeps_reserved"],
31
+ ["else", "control_prefix", "scope_switch", "stripped_prefix", "rule_reserved", "pass_keeps_reserved"],
31
32
  ["while", "control_prefix", "compound_open", "loop_condition", "scope_open", "stripped_prefix", "rule_reserved"],
32
33
  ["until", "control_prefix", "compound_open", "loop_condition", "scope_open", "stripped_prefix", "rule_reserved"],
33
34
  ["do", "control_prefix", "stripped_prefix", "rule_reserved"],
34
- ["time", "control_prefix", "timer", "rule_reserved"],
35
+ ["time", "control_prefix", "timer", "rule_reserved", "pass_keeps_reserved"],
35
36
  ["{", "group", "compound_open", "scope_open", "stripped_standalone", "rule_reserved"],
36
37
  ["}", "group", "scope_close", "stripped_standalone", "rule_reserved"],
37
38
  ["for", "block", "compound_open", "loop_list_head", "loop_iterates", "scope_open", "opaque", "rule_reserved"],
38
39
  ["select", "block", "compound_open", "loop_list_head", "scope_open", "opaque", "rule_reserved"],
39
40
  ["case", "block", "compound_open", "case_arms", "scope_open", "opaque", "rule_reserved"],
40
- ["esac", "block", "scope_close", "stripped_standalone", "rule_reserved"],
41
+ ["esac", "block", "scope_close", "stripped_standalone", "rule_reserved", "pass_keeps_reserved"],
41
42
  ["fi", "block", "scope_close", "stripped_standalone", "rule_reserved"],
42
- ["done", "block", "loop_end", "scope_close", "stripped_standalone", "rule_reserved"],
43
+ ["done", "block", "loop_end", "scope_close", "stripped_standalone", "rule_reserved", "pass_keeps_reserved"],
43
44
  ["function", "block", "definition", "opaque", "rule_reserved"],
44
45
  ["coproc", "block", "background", "opaque", "rule_reserved"],
45
46
  ["]]", "block", "stripped_standalone", "rule_reserved"],
@@ -2,7 +2,7 @@ import { join, resolve, sep } from "node:path";
2
2
  import { createHash, randomBytes } from "node:crypto";
3
3
  import { assertRetentionPolicy } from "../../core/retention-policy.js";
4
4
  import { existsSync, linkSync, readdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from "node:fs";
5
- import { assertMailboxDecisionMove, detachMailboxMessage, newestSentAt, readStoredMailboxDecision, readMailboxPeerMeta, } from "../../core/mailbox-store.js";
5
+ import { assertMailboxDecisionMove, detachMailboxMessage, newestSentAt, readStoredMailboxDecision, readMailboxAppend, judgeMailboxAppendById, } from "../../core/mailbox-store.js";
6
6
  import { AppendLog, atomicWriteFile, canonicalStoreKey, ensureDir, readJsonlRecords, sanitizeScope, sanitizePathComponent } from "./fs-atomic.js";
7
7
  import { guardCorruptSink } from "./corrupt-read-sink.js";
8
8
  import { physicalPathOf } from "../../core/physical-path.js";
@@ -441,18 +441,14 @@ export class FileMailboxStore {
441
441
  async append(scope, handle, msg) {
442
442
  if (scope === undefined || scope === "")
443
443
  throw new Error("MailboxStore.append: refusing a message without a scope");
444
- const peerMeta = readMailboxPeerMeta(msg.peerMeta);
444
+ const record = readMailboxAppend(msg);
445
445
  return this.withBox(this.lockKey(scope, handle), this.boxPath(scope, handle), () => {
446
446
  const b = this.load(scope, handle);
447
+ const held = judgeMailboxAppendById(b.messages, record);
448
+ if (held !== undefined)
449
+ return held;
447
450
  const seq = b.nextSeq;
448
- const m = {
449
- seq,
450
- ...(msg.from !== undefined ? { from: msg.from } : {}),
451
- content: msg.content,
452
- sentAt: msg.sentAt,
453
- ...(msg.hopChain !== undefined ? { hopChain: [...msg.hopChain] } : {}),
454
- ...(peerMeta !== undefined ? { peerMeta } : {}),
455
- };
451
+ const m = { seq, ...record };
456
452
  this.commit(b, this.boxPath(scope, handle), { t: "append", m });
457
453
  return seq;
458
454
  });
@@ -3,6 +3,7 @@ import { type TaskRegistry } from "../../core/task-registry.js";
3
3
  import { type CwdRef } from "./fs-shared.js";
4
4
  import type { ReversibilityVerdict } from "../../core/types.js";
5
5
  import type { ShellReadAdmission } from "./shell-read-check.js";
6
+ import type { ReadFloorSeat } from "./read-floor.js";
6
7
  /**
7
8
  * The full shell face's SHAPE classifier for the `bash` tool, exposed as a `ToolSpec.reversibilityProbe`
8
9
  * (the "maybe" tier's probe, installed on every full shell). A command is reversible ONLY if every connected
@@ -144,6 +145,9 @@ export declare function createBashTool(env: ExecutionEnv, rootCanonical: string,
144
145
  * nothing is re-established, and the full shell runs unconfined as it always did.
145
146
  */
146
147
  shellReadAdmission?: ShellReadAdmission;
148
+ /** The byte floor's seat (read-floor.ts): every command this leg starts, foreground or background, carries the
149
+ * read-deny table its call judges with to the environment. Absent ⇒ no table, the starts carry nothing. */
150
+ readFloor?: ReadFloorSeat;
147
151
  /** Override of the `timeout` parameter's DEFAULT budget, in ms — see
148
152
  * {@link import("./index.js").HandsToolkitOptions.bashDefaultTimeoutMs} for the resolution
149
153
  * contract (options over env over constant; invalid values discarded). */
@@ -201,6 +205,8 @@ export declare function createBashReadonlyTool(env: ExecutionEnv, rootCanonical:
201
205
  * containment IS the station, and a consumer mounting it without one must run `runToolGate` with the
202
206
  * station's `shellReadCheck` (the Runner does). */
203
207
  shellReadAdmission?: ShellReadAdmission;
208
+ /** The byte floor's seat — the SAME one the full shell leg takes (read-floor.ts). */
209
+ readFloor?: ReadFloorSeat;
204
210
  /** The run's tool-progress sink — the SAME seat the full shell leg takes, for the same reason its
205
211
  * two neighbours above are shared: both foreground legs run through `runShell`, so a long command
206
212
  * must breathe on both or a person watching one of them is told nothing. This face has no detach
@@ -292,7 +292,7 @@ function startLivenessTicks(onTick, filterStderr) {
292
292
  stop: () => clearInterval(timer),
293
293
  };
294
294
  }
295
- async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, cwdRef, detach, readOnly, containmentRoots, onTick) {
295
+ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, cwdRef, detach, readOnly, containmentRoots, onTick, readFloor) {
296
296
  const requestedSec = Math.max(1, Math.floor(timeoutSec ?? caps.defaultSec));
297
297
  let timeout = Math.min(caps.maxSec, requestedSec);
298
298
  const cappedByMaxTimeout = requestedSec > caps.maxSec;
@@ -311,6 +311,7 @@ async function runShell(env, cwd, toolName, command, timeoutSec, caps, signal, c
311
311
  abortSignal: signal,
312
312
  ...execEnv,
313
313
  ...(live !== undefined ? { onStdout: live.onStdout, onStderr: live.onStderr } : {}),
314
+ ...(readFloor !== undefined ? { readFloor } : {}),
314
315
  ...(detach
315
316
  ? {
316
317
  detachSignal: detach.signal,
@@ -607,9 +608,11 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
607
608
  if (ctx.signal?.aborted === true)
608
609
  return errorResult("Error (Bash): the call was cancelled before the background command started.");
609
610
  const requestedTimeoutSec = timeout !== undefined ? Math.max(1, Math.round(timeout / 1000)) : undefined;
611
+ const readFloor = taskOpts.readFloor?.(ctx.toolCallId);
610
612
  const r = await env.spawnBackground(command, {
611
613
  cwd: cwdRef.current,
612
614
  ...(requestedTimeoutSec !== undefined ? { timeout: requestedTimeoutSec } : {}),
615
+ ...(readFloor !== undefined ? { readFloor } : {}),
613
616
  });
614
617
  if (!r.ok)
615
618
  return errorResult(`Error (Bash): the background process could not be started (${r.error.code}): ${envErrorDetail(r.error.message)}`);
@@ -765,7 +768,7 @@ export function createBashTool(env, rootCanonical, coAuthor = false, cwdRef = {
765
768
  : undefined;
766
769
  let res;
767
770
  try {
768
- res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, cwdRef, detachChain, false, [rootCanonical, ...(taskOpts.additionalRoots ?? [])], onTick);
771
+ res = await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, cwdRef, detachChain, false, [rootCanonical, ...(taskOpts.additionalRoots ?? [])], onTick, taskOpts.readFloor?.(ctx.toolCallId));
769
772
  }
770
773
  finally {
771
774
  taskOpts.detachHub?.gc(ctx.toolCallId);
@@ -811,7 +814,7 @@ export function createBashReadonlyTool(env, rootCanonical, allow, opts) {
811
814
  if (refused !== undefined)
812
815
  return refused;
813
816
  const readOnlyTick = opts?.onToolProgress === undefined ? undefined : (t) => describeSafely(opts.onToolProgress, { toolCallId: ctx.toolCallId, toolName: "Bash", ...t });
814
- return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true, undefined, readOnlyTick);
817
+ return await runShell(env, rootCanonical, "Bash", command, msTimeoutToRequestedSec(timeout), timeoutCapsSecView, ctx.signal, undefined, undefined, true, undefined, readOnlyTick, opts?.readFloor?.(ctx.toolCallId));
815
818
  },
816
819
  });
817
820
  }
@@ -17,6 +17,7 @@ export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-read
17
17
  import { checkedReadDenyHomes, compileReadDeny, compileWriteDeny, readDenyBuiltinConfigOf, readDenyRowAnchor } from "./read-deny.js";
18
18
  import { withGateTimeout } from "../../core/gate-bounded-await.js";
19
19
  import { carriedReadFaceOf, carryHomeViews, homeViewsAt, placeReadDenyAtHome, placementViewsOf, readDenyPlacedLater, sayPlacementLost } from "./read-deny-home.js";
20
+ import { readFloorSeat } from "./read-floor.js";
20
21
  import { deploymentFaceClampNotice, resolveContainmentFace } from "./containment-face.js";
21
22
  export * from "./containment-face.js";
22
23
  import {} from "./fs-shared.js";
@@ -43,6 +44,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
43
44
  ? undefined
44
45
  : (canonicalKey, c) => readAdmission?.(c.toolCallId, canonicalKey) === true || (bgOutput?.(canonicalKey, c) ?? false);
45
46
  const { readDeny, writeDeny, afterPlacement } = carriedFace !== undefined ? { readDeny: carriedFace.readDeny, writeDeny: carriedFace.writeDeny, afterPlacement: (tool) => tool } : bandOwnTables(env, opts);
47
+ const readFloor = readFloorSeat(readDeny);
46
48
  const readFace = resolveContainmentFace({
47
49
  kind: "read",
48
50
  depsFace: opts.readFace,
@@ -85,12 +87,13 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
85
87
  }
86
88
  tools.push(afterPlacement(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)), afterPlacement(createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)), afterPlacement(createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)));
87
89
  if (includeShell) {
88
- tools.push(readOnly
90
+ tools.push(afterPlacement(readOnly
89
91
  ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), {
90
92
  ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
91
93
  ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
92
94
  ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),
93
95
  ...(opts.shellReadAdmission !== undefined ? { shellReadAdmission: opts.shellReadAdmission } : {}),
96
+ ...(readFloor !== undefined ? { readFloor } : {}),
94
97
  ...(opts.onToolProgress !== undefined ? { onToolProgress: opts.onToolProgress } : {}),
95
98
  })
96
99
  : createBashTool(env, rootCanonical, commitCoAuthor, cwdRef, {
@@ -107,12 +110,13 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
107
110
  ...(opts.oneShot !== undefined ? { oneShot: opts.oneShot } : {}),
108
111
  ...(additionalRoots !== undefined ? { additionalRoots } : {}),
109
112
  ...(opts.shellReadAdmission !== undefined ? { shellReadAdmission: opts.shellReadAdmission } : {}),
113
+ ...(readFloor !== undefined ? { readFloor } : {}),
110
114
  ...(opts.bashDefaultTimeoutMs !== undefined ? { bashDefaultTimeoutMs: opts.bashDefaultTimeoutMs } : {}),
111
115
  ...(opts.bashMaxTimeoutMs !== undefined ? { bashMaxTimeoutMs: opts.bashMaxTimeoutMs } : {}),
112
116
  ...(opts.onNotice !== undefined ? { onNotice: opts.onNotice } : {}),
113
117
  ...(opts.monitorToolActive !== undefined ? { monitorToolActive: opts.monitorToolActive } : {}),
114
118
  ...(opts.reminderMark !== undefined ? { reminderMark: opts.reminderMark } : {}),
115
- }));
119
+ })));
116
120
  if (!readOnly && mountBackgroundTaskTools && hasBackgroundShell(env)) {
117
121
  const sessionAxis = opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {};
118
122
  tools.push(opts.taskRegistry
@@ -422,6 +422,9 @@ export interface ProgramRow {
422
422
  readonly movesBase?: "stack";
423
423
  /** A shell block word at the program position: it names no command of its own. */
424
424
  readonly syntax?: "block";
425
+ /** What it writes to its standard output, read off its operands ({@link printedText}): `words` = its operands joined
426
+ * by a space (`echo`), `format` = its one operand as a format (`printf`). */
427
+ readonly prints?: "words" | "format";
425
428
  /** Git-style subcommands: the word after the program's own options names one, and the words after it are read by
426
429
  * ITS grammar, operands and traversal ({@link subcommandOf}). */
427
430
  readonly subcommands?: Readonly<Record<string, Subcommand>>;
@@ -875,6 +878,16 @@ export declare function readProgramTextLanguage(row: ProgramRow | undefined): st
875
878
  /** The program text of an invocation of a row whose first positional is program text, under EACH implementation's
876
879
  * grammar (no text says which one runs, so a reader combines the readings). */
877
880
  export declare function programTextReadings(row: ProgramRow, args: readonly string[]): ProgramTextReading[];
881
+ /**
882
+ * The text a printer row ({@link ProgramRow.prints}) writes to its standard output, read off its argv (the program word
883
+ * excluded; `undefined` = a word whose value the command does not spell). `undefined` wherever the words do not spell the
884
+ * text: such a word, an option the row does not explain, an escape the program may interpret (a backslash: `echo -e`, an
885
+ * `echo` that reads escapes by default, every `printf` format), a format with a directive (`%`), a format behind an
886
+ * option (`printf -v NAME` writes a variable, not the output), or a row that prints nothing it is handed. What the printer
887
+ * is where the command runs (a function or an alias of its name, a trap around it)
888
+ * is not read here: the one reader of this text uses it to refuse, never to clear (`ShellReadSegment.printed`).
889
+ */
890
+ export declare function printedText(row: ProgramRow | undefined, args: readonly (string | undefined)[]): string | undefined;
878
891
  /**
879
892
  * The subcommand an argv (the program word excluded) names, and the row it is read by: the first word past the
880
893
  * program's own options, which are read EXACTLY by the row's grammar — an option the row does not declare may take the
@@ -1331,6 +1331,21 @@ function programTextUnder(g, args) {
1331
1331
  const script = supplied ? scripts.join("\n") : firstOperand;
1332
1332
  return script === undefined ? "none" : { text: script };
1333
1333
  }
1334
+ export function printedText(row, args) {
1335
+ const words = args.filter((a) => a !== undefined);
1336
+ if (row?.prints === undefined || words.length !== args.length)
1337
+ return undefined;
1338
+ const events = readArgRoles(row, words);
1339
+ const from = events.find((e) => e.kind === "operand" || e.kind === "dash-word-operand")?.at ?? words.length;
1340
+ if (events.some((e) => e.at < from && e.kind === "option" && e.reading === "speculative"))
1341
+ return undefined;
1342
+ const printed = words.slice(from);
1343
+ if (printed.some((w) => w.includes("\\")))
1344
+ return undefined;
1345
+ if (row.prints === "words")
1346
+ return printed.join(" ");
1347
+ return from === 0 && printed.length === 1 && !printed[0].includes("%") ? printed[0] : undefined;
1348
+ }
1334
1349
  function exactSpec(g, tok) {
1335
1350
  if (tok.startsWith("--"))
1336
1351
  return tok.includes("=") ? undefined : g.long[tok.slice(2)];
@@ -585,7 +585,7 @@ const git = {
585
585
  const noPath = (key, rest, extra = {}) => ({ key, grammars: [], operands: { rest }, witness: BINARY, ...extra });
586
586
  const BUILTIN_ONLY = { declared: "a shell builtin with no binary of its own on every host: its words are read by the shell" };
587
587
  const noPathRows = [
588
- noPath("pwd", LABEL, { builtin: "inert" }), noPath("echo", LABEL, { builtin: "inert", grammars: [grammar(switches("neE"), {}, { afterFirstOperand: "operands" })] }), noPath("printf", LABEL, { grammars: [grammar({ v: val(BINDS_NAME) })] }), noPath("whoami", LABEL), noPath("uname", LABEL),
588
+ noPath("pwd", LABEL, { builtin: "inert" }), noPath("echo", LABEL, { builtin: "inert", grammars: [grammar(switches("neE"), {}, { afterFirstOperand: "operands" })], prints: "words" }), noPath("printf", LABEL, { grammars: [grammar({ v: val(BINDS_NAME) })], prints: "format" }), noPath("whoami", LABEL), noPath("uname", LABEL),
589
589
  noPath("which", LABEL), noPath("basename", LABEL), noPath("dirname", LABEL),
590
590
  { key: "tr", grammars: [], operands: { rest: LABEL, stdinBelow: "always" }, witness: BINARY },
591
591
  noPath("cal", COUNT), noPath("uptime", LABEL), noPath("id", LABEL), noPath("groups", LABEL), noPath("nproc", LABEL), noPath("locale", LABEL),
@@ -12,9 +12,10 @@ import { type PathGuardFold, type PathGuardRow, type PathRowsHit, type TargetVie
12
12
  * absolute path (a path that is not absolute is not placed, and the row does not judge it).
13
13
  * String shorthand ≡ `{ pattern }`. Matching is ASCII-case-insensitive by default (a case-insensitive
14
14
  * filesystem serves `.SSH` and `.ssh` as the same directory); `caseSensitive: true` opts a single
15
- * entry out. Unicode normalization (NFC/NFD) and volume-level case semantics are NOT modeled (v1
16
- * residual, shared with the write guard; the canonical view — realpath returns the on-disk spelling —
17
- * covers half of it).
15
+ * entry out. Names are compared in canonical composition (NFC) whatever the case setting — `ü` as one code point and `u` plus a
16
+ * combining diaeresis are one name, as on a filesystem that compares names by canonical equivalence; a compatibility form
17
+ * (a ligature) is another name. Volume-level case semantics are NOT modeled (v1 residual, shared with the write guard; the
18
+ * canonical view — realpath returns the on-disk spelling — covers half of it).
18
19
  */
19
20
  export type ReadDenyEntry = string | {
20
21
  pattern: string;
@@ -422,11 +423,13 @@ export declare const READ_FACE_DEFAULT_DENY_ENTRIES: readonly ReadDenyEntry[];
422
423
  * themselves, `ß` stays `ß`). Both sides of a comparison go through it.
423
424
  */
424
425
  export declare function ignoreCaseFold(s: string): string;
425
- /** How a compiled pattern compares: `none` byte for byte; `ascii` and `unicode` through the fold of that name, both sides —
426
- * the pattern's side at compile, the segments' side by whoever tests (once per path: {@link segmentReadingsOf}). */
426
+ /** How a compiled pattern compares, both sides composed ({@link composed}), then: `none` byte for byte; `ascii` and `unicode`
427
+ * through the case fold of that name — the pattern's side at compile, the segments' side by whoever tests (once per path:
428
+ * {@link segmentReadingsOf}). */
427
429
  export type SegmentFold = "none" | "ascii" | "unicode";
428
430
  /** The function that folds a string as each fold folds — the one place that says which function that is (the pattern at compile,
429
- * a path's segments in the readings, an anchor's segments all read it, at the time they fold). */
431
+ * a path's segments in the readings, an anchor's segments all read it, at the time they fold): composition first, in every
432
+ * fold, then the fold's own case mapping. */
430
433
  export declare const SEGMENT_FOLDS: Record<SegmentFold, (s: string) => string>;
431
434
  /** One compiled segment of a pattern: `*` stands for any run of characters but a separator, every other character for itself. */
432
435
  export interface SegmentMatcher {
@@ -454,11 +457,11 @@ export interface CompiledSegmentPattern {
454
457
  unplacedHome?: true;
455
458
  }
456
459
  /**
457
- * Compile one segment-glob pattern (shared engine). `fold`:
458
- * · "none" — byte-exact segments;
460
+ * Compile one segment-glob pattern (shared engine). `fold` (every fold first composes the name, {@link composed}):
461
+ * · "none" — exact segments, case included;
459
462
  * · "ascii" — ASCII-case-insensitive (deny-set contract);
460
- * · "unicode" — the fold a RegExp `i` flag applies, {@link ignoreCaseFold} (the write guard's historical host-keyed
461
- * behavior — kept for it answer for answer; NOT used by the deny set).
463
+ * · "unicode" — the fold a RegExp `i` flag applies, {@link ignoreCaseFold}, over the composed name (the write guard's
464
+ * historical host-keyed case behavior; NOT used by the deny set).
462
465
  * The pattern is folded here, once; the segments a row is tested on are folded by whoever tests, once per path
463
466
  * ({@link segmentReadingsOf}) — never once per row per test.
464
467
  * Returns null when the pattern reduces to zero segments — the CALLER owns its loud path (the two