@sema-agent/core 7.60.0 → 7.62.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 (560) hide show
  1. package/CHANGELOG.md +917 -0
  2. package/README.md +2 -2
  3. package/dist/agents/agent-transcript-tool.d.ts +2 -2
  4. package/dist/agents/agent-transcript-tool.js +1 -1
  5. package/dist/agents/cascade.d.ts +71 -12
  6. package/dist/agents/cascade.js +61 -21
  7. package/dist/agents/composition-allowance.d.ts +53 -0
  8. package/dist/agents/composition-allowance.js +49 -0
  9. package/dist/agents/composition-placement.d.ts +29 -0
  10. package/dist/agents/composition-placement.js +24 -0
  11. package/dist/agents/cumulative-stats.d.ts +4 -0
  12. package/dist/agents/cumulative-stats.js +3 -0
  13. package/dist/agents/inherited-tool-pool.d.ts +5 -3
  14. package/dist/agents/inherited-tool-pool.js +2 -2
  15. package/dist/agents/list-agents-tool.d.ts +1 -1
  16. package/dist/agents/peer-held-queue.d.ts +27 -4
  17. package/dist/agents/peer-held-queue.js +81 -36
  18. package/dist/agents/peer-notice-route.d.ts +1 -1
  19. package/dist/agents/peer-notice-route.js +4 -3
  20. package/dist/agents/peer-notices.d.ts +4 -4
  21. package/dist/agents/peer-notices.js +8 -4
  22. package/dist/agents/peer-session-drain.d.ts +8 -1
  23. package/dist/agents/peer-session-drain.js +49 -10
  24. package/dist/agents/repair-loop.js +16 -6
  25. package/dist/agents/retain-ledger.js +3 -1
  26. package/dist/agents/roster-store.d.ts +1 -1
  27. package/dist/agents/roster-store.js +7 -4
  28. package/dist/agents/send-message-tool.d.ts +8 -10
  29. package/dist/agents/send-message-tool.js +43 -23
  30. package/dist/agents/subagent-completion-gate.d.ts +35 -0
  31. package/dist/agents/subagent-completion-gate.js +62 -0
  32. package/dist/agents/subagent-steps.d.ts +7 -6
  33. package/dist/agents/subagent.d.ts +36 -41
  34. package/dist/agents/subagent.js +245 -200
  35. package/dist/agents/suspend-guard.d.ts +47 -16
  36. package/dist/agents/suspend-guard.js +13 -4
  37. package/dist/agents/verify.d.ts +41 -14
  38. package/dist/agents/verify.js +41 -30
  39. package/dist/brain/anthropic.js +1 -0
  40. package/dist/brain/errors.d.ts +7 -1
  41. package/dist/brain/errors.js +6 -0
  42. package/dist/brain/failover.js +2 -1
  43. package/dist/brain/open-responses.js +1 -0
  44. package/dist/brain/openai.js +1 -0
  45. package/dist/brain/provider-dialect.d.ts +10 -0
  46. package/dist/brain/provider-dialect.js +13 -2
  47. package/dist/brain/stream-engine.d.ts +3 -0
  48. package/dist/brain/stream-engine.js +4 -0
  49. package/dist/core/agent-state.d.ts +1 -1
  50. package/dist/core/allow-entry.d.ts +59 -23
  51. package/dist/core/allow-entry.js +131 -38
  52. package/dist/core/ask-origin.d.ts +79 -0
  53. package/dist/core/ask-origin.js +76 -0
  54. package/dist/core/ask-question.d.ts +19 -13
  55. package/dist/core/ask-question.js +8 -2
  56. package/dist/core/auto-compaction.d.ts +2 -0
  57. package/dist/core/auto-compaction.js +2 -1
  58. package/dist/core/auto-mode.js +3 -5
  59. package/dist/core/background-agent-store.d.ts +7 -5
  60. package/dist/core/background-agent-store.js +12 -11
  61. package/dist/core/checkpoint-features.d.ts +722 -0
  62. package/dist/core/checkpoint-features.js +98 -0
  63. package/dist/core/checkpoint-requirements.d.ts +33 -5
  64. package/dist/core/checkpoint-requirements.js +18 -5
  65. package/dist/core/checkpoint-row-verdict.d.ts +99 -0
  66. package/dist/core/checkpoint-row-verdict.js +225 -0
  67. package/dist/core/checkpoint-store.d.ts +107 -738
  68. package/dist/core/checkpoint-store.js +45 -143
  69. package/dist/core/child-clamp-seats.d.ts +3 -2
  70. package/dist/core/child-clamp-seats.js +4 -3
  71. package/dist/core/closest-name.d.ts +13 -0
  72. package/dist/core/closest-name.js +35 -0
  73. package/dist/core/context-settings.js +3 -5
  74. package/dist/core/cross-boundary-taint.d.ts +1 -1
  75. package/dist/core/decision-receipt.d.ts +14 -1
  76. package/dist/core/decision-receipt.js +6 -3
  77. package/dist/core/delegation-frames.d.ts +13 -9
  78. package/dist/core/effective-path-target.js +2 -3
  79. package/dist/core/engine-attestation.d.ts +11 -1
  80. package/dist/core/engine-attestation.js +2 -0
  81. package/dist/core/engine-notice.d.ts +68 -21
  82. package/dist/core/engine-notice.js +9 -2
  83. package/dist/core/file-history-retention.d.ts +8 -0
  84. package/dist/core/file-history-retention.js +14 -11
  85. package/dist/core/file-history-store.d.ts +31 -1
  86. package/dist/core/file-history-store.js +31 -2
  87. package/dist/core/frame-settlement.d.ts +10 -0
  88. package/dist/core/frame-settlement.js +6 -1
  89. package/dist/core/fs-write-gate-policy.d.ts +3 -3
  90. package/dist/core/fs-write-gate-policy.js +8 -7
  91. package/dist/core/gate-fold.js +4 -3
  92. package/dist/core/gate-lanes.js +7 -4
  93. package/dist/core/gate-outcome.d.ts +40 -1
  94. package/dist/core/gate-outcome.js +10 -0
  95. package/dist/core/git-worktree-env.d.ts +7 -3
  96. package/dist/core/git-worktree-env.js +16 -13
  97. package/dist/core/governance-codes.d.ts +14 -4
  98. package/dist/core/governance-codes.js +19 -4
  99. package/dist/core/hooks.d.ts +25 -4
  100. package/dist/core/hooks.js +11 -4
  101. package/dist/core/host-floor.js +3 -5
  102. package/dist/core/human-input-projection.d.ts +1 -0
  103. package/dist/core/human-input-projection.js +3 -0
  104. package/dist/core/image-admission.d.ts +47 -7
  105. package/dist/core/image-admission.js +35 -4
  106. package/dist/core/input-author.d.ts +36 -0
  107. package/dist/core/input-author.js +39 -0
  108. package/dist/core/leg-identity.d.ts +62 -0
  109. package/dist/core/leg-identity.js +18 -0
  110. package/dist/core/locked-config.d.ts +4 -3
  111. package/dist/core/locked-config.js +5 -3
  112. package/dist/core/lsp.d.ts +5 -3
  113. package/dist/core/lsp.js +3 -2
  114. package/dist/core/mailbox-store.d.ts +85 -10
  115. package/dist/core/mailbox-store.js +31 -10
  116. package/dist/core/mcp-connection-pool.d.ts +6 -20
  117. package/dist/core/mcp-connection-pool.js +10 -28
  118. package/dist/core/mcp-failure.d.ts +76 -15
  119. package/dist/core/mcp-failure.js +60 -33
  120. package/dist/core/mcp-host-seat.d.ts +92 -53
  121. package/dist/core/mcp-host-seat.js +225 -46
  122. package/dist/core/mcp-probe.js +2 -2
  123. package/dist/core/mcp-server-link.d.ts +18 -6
  124. package/dist/core/mcp-server-link.js +19 -4
  125. package/dist/core/mcp-server-spec.d.ts +2 -1
  126. package/dist/core/mcp-session-end.d.ts +1 -2
  127. package/dist/core/mcp-session-end.js +1 -1
  128. package/dist/core/mcp.d.ts +6 -49
  129. package/dist/core/mcp.js +115 -111
  130. package/dist/core/media-byte-cap.d.ts +21 -46
  131. package/dist/core/media-byte-cap.js +55 -55
  132. package/dist/core/member-group.d.ts +7 -0
  133. package/dist/core/member-group.js +35 -0
  134. package/dist/core/memory-engine/consolidation-driver.d.ts +1 -1
  135. package/dist/core/memory-engine/consolidation.d.ts +1 -1
  136. package/dist/core/memory-engine/consolidation.js +7 -1
  137. package/dist/core/memory-engine/dual-root.d.ts +31 -0
  138. package/dist/core/memory-engine/dual-root.js +59 -11
  139. package/dist/core/memory-engine/engine.js +27 -24
  140. package/dist/core/memory-engine/file-backend.d.ts +13 -0
  141. package/dist/core/memory-engine/file-backend.js +35 -15
  142. package/dist/core/memory-engine/layout.d.ts +3 -0
  143. package/dist/core/memory-engine/layout.js +13 -3
  144. package/dist/core/memory-engine/memory-deployment.d.ts +110 -0
  145. package/dist/core/memory-engine/memory-deployment.js +182 -0
  146. package/dist/core/memory-engine/sync-client.d.ts +39 -18
  147. package/dist/core/memory-engine/sync-client.js +72 -14
  148. package/dist/core/memory-engine/sync-report.d.ts +7 -4
  149. package/dist/core/memory-engine/sync.d.ts +9 -1
  150. package/dist/core/memory-vector.d.ts +1 -1
  151. package/dist/core/memory.d.ts +10 -10
  152. package/dist/core/mode-policy.d.ts +8 -8
  153. package/dist/core/mode-policy.js +8 -6
  154. package/dist/core/mods/agent-stations.d.ts +39 -4
  155. package/dist/core/mods/agent-stations.js +59 -10
  156. package/dist/core/mods/classic-events.d.ts +9 -1
  157. package/dist/core/mods/dollar.d.ts +94 -1
  158. package/dist/core/mods/dollar.js +13 -1
  159. package/dist/core/mods/extension-call.d.ts +15 -1
  160. package/dist/core/mods/extension-call.js +7 -2
  161. package/dist/core/mods/kernel/dispatch.d.ts +4 -3
  162. package/dist/core/mods/kernel/dispatch.js +4 -4
  163. package/dist/core/mods/kernel/events.d.ts +14 -3
  164. package/dist/core/mods/kernel/events.js +18 -15
  165. package/dist/core/mods/kernel/registration.d.ts +3 -0
  166. package/dist/core/mods/kernel/registration.js +5 -0
  167. package/dist/core/mods/kernel/site-rules.d.ts +6 -3
  168. package/dist/core/mods/kernel/site-rules.js +10 -2
  169. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  170. package/dist/core/mods/lifecycle-stations.js +44 -9
  171. package/dist/core/mods/session-append.d.ts +118 -0
  172. package/dist/core/mods/session-append.js +318 -0
  173. package/dist/core/mods/session-compact.d.ts +48 -0
  174. package/dist/core/mods/session-compact.js +194 -0
  175. package/dist/core/mods/session-receive.d.ts +93 -0
  176. package/dist/core/mods/session-receive.js +138 -0
  177. package/dist/core/mods/session-send.d.ts +72 -0
  178. package/dist/core/mods/session-send.js +88 -0
  179. package/dist/core/mods/stations.d.ts +88 -21
  180. package/dist/core/mods/stations.js +149 -11
  181. package/dist/core/mods/tool-call.d.ts +2 -0
  182. package/dist/core/mods/tool-call.js +4 -4
  183. package/dist/core/output-style.js +3 -4
  184. package/dist/core/own-property-receipt.d.ts +68 -2
  185. package/dist/core/own-property-receipt.js +45 -2
  186. package/dist/core/park-selfcheck.js +4 -2
  187. package/dist/core/path-identity.d.ts +11 -0
  188. package/dist/core/path-identity.js +4 -0
  189. package/dist/core/path-rule-binding.d.ts +3 -1
  190. package/dist/core/path-rule-binding.js +3 -1
  191. package/dist/core/peer-seat.d.ts +3 -3
  192. package/dist/core/peer-seat.js +20 -8
  193. package/dist/core/permission-rule-consent.d.ts +21 -5
  194. package/dist/core/permission-rule-consent.js +21 -1
  195. package/dist/core/permission-rule-model.d.ts +34 -11
  196. package/dist/core/permission-rule-model.js +47 -10
  197. package/dist/core/permission-rule-org.d.ts +1 -1
  198. package/dist/core/permission-rule-provider.js +4 -1
  199. package/dist/core/permission-rules.d.ts +4 -0
  200. package/dist/core/permission-rules.js +11 -16
  201. package/dist/core/read-root-candidate.js +1 -1
  202. package/dist/core/remote-env.d.ts +74 -26
  203. package/dist/core/remote-env.js +20 -0
  204. package/dist/core/resume-startup-cause.d.ts +5 -4
  205. package/dist/core/retention-policy.d.ts +24 -23
  206. package/dist/core/retention-policy.js +36 -2
  207. package/dist/core/retention.d.ts +4 -1
  208. package/dist/core/retired-keys.d.ts +4 -4
  209. package/dist/core/row-admission.d.ts +10 -0
  210. package/dist/core/row-admission.js +5 -0
  211. package/dist/core/runner/advisor-instructions.d.ts +2 -1
  212. package/dist/core/runner/advisor-instructions.js +2 -1
  213. package/dist/core/runner/announce-once-ledger.d.ts +4 -4
  214. package/dist/core/runner/assemble-result.d.ts +13 -3
  215. package/dist/core/runner/assemble-result.js +12 -7
  216. package/dist/core/runner/caller-roster.d.ts +12 -9
  217. package/dist/core/runner/caller-roster.js +5 -2
  218. package/dist/core/runner/checkpoint-scope.d.ts +16 -1
  219. package/dist/core/runner/checkpoint-scope.js +21 -0
  220. package/dist/core/runner/compact-session.js +18 -3
  221. package/dist/core/runner/compaction-call-options.d.ts +1 -1
  222. package/dist/core/runner/compaction-restate.d.ts +2 -2
  223. package/dist/core/runner/compaction-restate.js +4 -3
  224. package/dist/core/runner/construction-doors.d.ts +2 -2
  225. package/dist/core/runner/construction-doors.js +2 -2
  226. package/dist/core/runner/contracts.d.ts +116 -34
  227. package/dist/core/runner/cross-boundary-lane.d.ts +1 -1
  228. package/dist/core/runner/decide-continuation.d.ts +4 -2
  229. package/dist/core/runner/decide-continuation.js +7 -4
  230. package/dist/core/runner/delegation-owner.d.ts +43 -0
  231. package/dist/core/runner/delegation-owner.js +59 -0
  232. package/dist/core/runner/denial-limit-arms.d.ts +15 -21
  233. package/dist/core/runner/denial-limit-arms.js +17 -10
  234. package/dist/core/runner/expire-settle.d.ts +44 -0
  235. package/dist/core/runner/expire-settle.js +55 -0
  236. package/dist/core/runner/git-status-frame.d.ts +3 -3
  237. package/dist/core/runner/git-status-frame.js +2 -1
  238. package/dist/core/runner/halt-attribution.d.ts +2 -1
  239. package/dist/core/runner/halt-attribution.js +2 -1
  240. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  241. package/dist/core/runner/lineage-reroot-view.js +108 -0
  242. package/dist/core/runner/local-claims.d.ts +17 -0
  243. package/dist/core/runner/local-claims.js +18 -0
  244. package/dist/core/runner/media-removed-seat.d.ts +46 -0
  245. package/dist/core/runner/media-removed-seat.js +88 -0
  246. package/dist/core/runner/park-commit.d.ts +2 -2
  247. package/dist/core/runner/permission-rule-lanes.d.ts +7 -2
  248. package/dist/core/runner/permission-rule-lanes.js +28 -9
  249. package/dist/core/runner/person-path-rows.d.ts +15 -0
  250. package/dist/core/runner/person-path-rows.js +27 -4
  251. package/dist/core/runner/placement-fence.d.ts +26 -0
  252. package/dist/core/runner/placement-fence.js +38 -0
  253. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  254. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  255. package/dist/core/runner/prepare-ask-lane.d.ts +6 -12
  256. package/dist/core/runner/prepare-ask-lane.js +4 -4
  257. package/dist/core/runner/prepare-boundary-parks.d.ts +4 -1
  258. package/dist/core/runner/prepare-boundary-parks.js +2 -2
  259. package/dist/core/runner/prepare-caps-and-workflow.d.ts +3 -0
  260. package/dist/core/runner/prepare-caps-and-workflow.js +2 -1
  261. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  262. package/dist/core/runner/prepare-config-doors.js +19 -21
  263. package/dist/core/runner/prepare-context-lane.d.ts +6 -2
  264. package/dist/core/runner/prepare-context-lane.js +13 -13
  265. package/dist/core/runner/prepare-delegation-surface.d.ts +9 -9
  266. package/dist/core/runner/prepare-delegation-surface.js +4 -5
  267. package/dist/core/runner/prepare-execution-env.d.ts +5 -2
  268. package/dist/core/runner/prepare-execution-env.js +7 -4
  269. package/dist/core/runner/prepare-gate-stations.d.ts +19 -14
  270. package/dist/core/runner/prepare-gate-stations.js +6 -4
  271. package/dist/core/runner/prepare-hands-readface.d.ts +6 -6
  272. package/dist/core/runner/prepare-hands-readface.js +32 -11
  273. package/dist/core/runner/prepare-inherited-gate.d.ts +8 -0
  274. package/dist/core/runner/prepare-inherited-gate.js +10 -3
  275. package/dist/core/runner/prepare-lsp.d.ts +3 -0
  276. package/dist/core/runner/prepare-lsp.js +2 -2
  277. package/dist/core/runner/prepare-park-ask.d.ts +5 -2
  278. package/dist/core/runner/prepare-park-ask.js +4 -5
  279. package/dist/core/runner/prepare-policy-chain.d.ts +10 -21
  280. package/dist/core/runner/prepare-policy-chain.js +16 -25
  281. package/dist/core/runner/prepare-project-context.d.ts +2 -2
  282. package/dist/core/runner/prepare-prompt-inputs.d.ts +5 -4
  283. package/dist/core/runner/prepare-prompt-inputs.js +3 -2
  284. package/dist/core/runner/prepare-question-face.d.ts +6 -4
  285. package/dist/core/runner/prepare-question-face.js +2 -2
  286. package/dist/core/runner/prepare-run-refs.d.ts +3 -0
  287. package/dist/core/runner/prepare-run-refs.js +2 -2
  288. package/dist/core/runner/prepare-suspend-saga.d.ts +11 -7
  289. package/dist/core/runner/prepare-suspend-saga.js +17 -7
  290. package/dist/core/runner/prepare-task.d.ts +1 -1
  291. package/dist/core/runner/prepare-task.js +61 -30
  292. package/dist/core/runner/prepare-tool-disclosure-mount.d.ts +6 -0
  293. package/dist/core/runner/prepare-tool-disclosure-mount.js +3 -1
  294. package/dist/core/runner/prepare-wiring-manifest.d.ts +3 -0
  295. package/dist/core/runner/prepare-wiring-manifest.js +2 -1
  296. package/dist/core/runner/prepare-workspace-restore.d.ts +5 -0
  297. package/dist/core/runner/prepare-workspace-restore.js +10 -6
  298. package/dist/core/runner/read-root-grant.d.ts +1 -1
  299. package/dist/core/runner/read-root-grant.js +2 -1
  300. package/dist/core/runner/resume-admission.d.ts +8 -6
  301. package/dist/core/runner/resume-admission.js +23 -6
  302. package/dist/core/runner/resume-apply.d.ts +4 -0
  303. package/dist/core/runner/resume-apply.js +14 -5
  304. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  305. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  306. package/dist/core/runner/resume-claim.d.ts +8 -3
  307. package/dist/core/runner/resume-claim.js +28 -12
  308. package/dist/core/runner/resume-internals-and-config.d.ts +2 -2
  309. package/dist/core/runner/resume-internals-and-config.js +10 -1
  310. package/dist/core/runner/resume-preflight.d.ts +3 -2
  311. package/dist/core/runner/resume-preflight.js +13 -26
  312. package/dist/core/runner/retired-runner-deps.js +2 -0
  313. package/dist/core/runner/run-git-lane.d.ts +2 -0
  314. package/dist/core/runner/run-git-lane.js +6 -2
  315. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  316. package/dist/core/runner/run-harness-handlers.js +5 -4
  317. package/dist/core/runner/run-identity-wiring.d.ts +2 -2
  318. package/dist/core/runner/run-identity-wiring.js +14 -5
  319. package/dist/core/runner/run-leg.d.ts +3 -3
  320. package/dist/core/runner/run-leg.js +64 -36
  321. package/dist/core/runner/run-notification-lane.js +20 -2
  322. package/dist/core/runner/run-recovery-lanes.js +3 -2
  323. package/dist/core/runner/run-settle-and-teardown.js +12 -9
  324. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  325. package/dist/core/runner/run-telemetry-and-budget-seats.d.ts +1 -1
  326. package/dist/core/runner/run-terminal-adoption.d.ts +1 -1
  327. package/dist/core/runner/run-terminal-adoption.js +26 -17
  328. package/dist/core/runner/run-turn-boundary.js +34 -18
  329. package/dist/core/runner/runtask.d.ts +18 -3
  330. package/dist/core/runner/runtask.js +33 -17
  331. package/dist/core/runner/session-rule-policy.d.ts +1 -1
  332. package/dist/core/runner/session-rule-policy.js +6 -1
  333. package/dist/core/runner/shell-env-withheld.d.ts +1 -1
  334. package/dist/core/runner/steering-preview.d.ts +9 -0
  335. package/dist/core/runner/steering-preview.js +5 -0
  336. package/dist/core/runner/stream-halt-verbs.d.ts +1 -14
  337. package/dist/core/runner/stream-halt-verbs.js +4 -3
  338. package/dist/core/runner/stream-reap.d.ts +7 -6
  339. package/dist/core/runner/stream-reap.js +13 -16
  340. package/dist/core/runner/stream-settle-backstop.d.ts +3 -2
  341. package/dist/core/runner/stream-settle-backstop.js +5 -3
  342. package/dist/core/runner/stream-steer-verb.d.ts +5 -2
  343. package/dist/core/runner/stream-steer-verb.js +16 -7
  344. package/dist/core/runner/terminal-account.d.ts +11 -1
  345. package/dist/core/runner/terminal-account.js +20 -0
  346. package/dist/core/runner/terminal-projection.d.ts +8 -2
  347. package/dist/core/runner/terminal-projection.js +2 -2
  348. package/dist/core/runner/tool-disclosure.d.ts +3 -0
  349. package/dist/core/runner/tool-disclosure.js +5 -2
  350. package/dist/core/runner/tool-end-body.d.ts +3 -3
  351. package/dist/core/runner/tool-end-body.js +1 -1
  352. package/dist/core/runner/tool-face-overlay.js +2 -0
  353. package/dist/core/runner/tool-output-projection.d.ts +3 -3
  354. package/dist/core/runner/tool-output-projection.js +7 -6
  355. package/dist/core/runner/tool-table-view.d.ts +56 -0
  356. package/dist/core/runner/tool-table-view.js +51 -0
  357. package/dist/core/runner/turn-attachments.d.ts +8 -2
  358. package/dist/core/runner/turn-attachments.js +2 -2
  359. package/dist/core/runner/void-verifier-pause.d.ts +33 -0
  360. package/dist/core/runner/void-verifier-pause.js +41 -0
  361. package/dist/core/runner-deps.d.ts +26 -27
  362. package/dist/core/secret-env.d.ts +19 -16
  363. package/dist/core/secret-env.js +45 -27
  364. package/dist/core/session-log-transfer.js +9 -10
  365. package/dist/core/session-policy-store.d.ts +1 -1
  366. package/dist/core/session-policy-store.js +5 -2
  367. package/dist/core/session-reconcile.d.ts +3 -2
  368. package/dist/core/session-reconcile.js +7 -4
  369. package/dist/core/session-store.d.ts +3 -1
  370. package/dist/core/session-store.js +10 -8
  371. package/dist/core/session.d.ts +16 -5
  372. package/dist/core/shell-confinement.d.ts +37 -0
  373. package/dist/core/shell-confinement.js +56 -0
  374. package/dist/core/skill-grant.js +1 -1
  375. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +8 -2
  376. package/dist/core/store-contracts/checkpoint-store-contract.js +83 -2
  377. package/dist/core/store-contracts/file-history-store-contract.d.ts +5 -2
  378. package/dist/core/store-contracts/file-history-store-contract.js +25 -1
  379. package/dist/core/store-contracts/mailbox-store-contract.d.ts +12 -5
  380. package/dist/core/store-contracts/mailbox-store-contract.js +156 -9
  381. package/dist/core/store-contracts/session-store-contract.js +22 -8
  382. package/dist/core/store-contracts/tool-result-store-contract.d.ts +1 -1
  383. package/dist/core/store-contracts/tool-result-store-contract.js +30 -0
  384. package/dist/core/task-event.d.ts +24 -9
  385. package/dist/core/task-limits.d.ts +5 -0
  386. package/dist/core/task-notification.d.ts +89 -12
  387. package/dist/core/task-notification.js +89 -14
  388. package/dist/core/task-registry-agent.d.ts +32 -50
  389. package/dist/core/task-registry-agent.js +36 -56
  390. package/dist/core/task-registry-monitor.d.ts +1 -1
  391. package/dist/core/task-registry-monitor.js +15 -60
  392. package/dist/core/task-registry-shared.d.ts +22 -112
  393. package/dist/core/task-registry-shared.js +3 -41
  394. package/dist/core/task-registry-workflow.js +5 -21
  395. package/dist/core/task-registry.d.ts +32 -62
  396. package/dist/core/task-registry.js +30 -110
  397. package/dist/core/task-result.d.ts +29 -12
  398. package/dist/core/task-spec-members.d.ts +39 -0
  399. package/dist/core/task-spec-members.js +92 -0
  400. package/dist/core/task-spec.d.ts +11 -11
  401. package/dist/core/task-tool-shape.d.ts +7 -57
  402. package/dist/core/task-tool-shape.js +7 -66
  403. package/dist/core/terminal-cause.d.ts +36 -6
  404. package/dist/core/terminal-cause.js +1 -0
  405. package/dist/core/tool-catalog-entries.js +2 -5
  406. package/dist/core/tool-check-reading.js +16 -10
  407. package/dist/core/tool-conformance.js +1 -2
  408. package/dist/core/tool-errors.d.ts +6 -3
  409. package/dist/core/tool-errors.js +2 -0
  410. package/dist/core/tool-face-reader.js +3 -2
  411. package/dist/core/tool-face.d.ts +8 -5
  412. package/dist/core/tool-face.js +1 -1
  413. package/dist/core/tool-name-aliases.d.ts +5 -29
  414. package/dist/core/tool-name-aliases.js +9 -5
  415. package/dist/core/tool-name-readings.d.ts +14 -3
  416. package/dist/core/tool-name-readings.js +2 -0
  417. package/dist/core/tool-policy.d.ts +109 -18
  418. package/dist/core/tool-policy.js +84 -14
  419. package/dist/core/tool-result-store.d.ts +23 -0
  420. package/dist/core/tool-result-store.js +3 -2
  421. package/dist/core/tool-roster.d.ts +4 -4
  422. package/dist/core/tool-spec.d.ts +23 -6
  423. package/dist/core/trace.d.ts +18 -1
  424. package/dist/core/types.d.ts +1 -1
  425. package/dist/core/types.js +1 -1
  426. package/dist/core/user-attachment.js +26 -21
  427. package/dist/core/workflow-journal-store.d.ts +1 -1
  428. package/dist/core/workflow-run-store.d.ts +2 -0
  429. package/dist/core/workflow-run-store.js +6 -5
  430. package/dist/core/workflow-settled-run.d.ts +5 -0
  431. package/dist/core/workflow-settled-run.js +7 -0
  432. package/dist/engine/execution-env/node-execution-env.d.ts +37 -9
  433. package/dist/engine/execution-env/node-execution-env.js +221 -22
  434. package/dist/engine/harness/agent-harness.d.ts +65 -18
  435. package/dist/engine/harness/agent-harness.js +90 -23
  436. package/dist/engine/harness/messages.d.ts +4 -3
  437. package/dist/engine/harness/messages.js +2 -2
  438. package/dist/engine/harness/types.d.ts +52 -7
  439. package/dist/engine/llm/media-removed.d.ts +14 -0
  440. package/dist/engine/llm/media-removed.js +9 -0
  441. package/dist/engine/llm/rejected-images.d.ts +35 -25
  442. package/dist/engine/llm/rejected-images.js +59 -10
  443. package/dist/engine/llm/types.d.ts +24 -3
  444. package/dist/engine/llm/types.js +7 -3
  445. package/dist/engine/loop/agent-loop.d.ts +6 -1
  446. package/dist/engine/loop/agent-loop.js +20 -11
  447. package/dist/engine/loop/types.d.ts +12 -3
  448. package/dist/engine/session/import-validate.js +7 -0
  449. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  450. package/dist/engine/session/parent-chain-guard.js +1 -1
  451. package/dist/engine/session/path-to-root.d.ts +18 -3
  452. package/dist/engine/session/path-to-root.js +15 -1
  453. package/dist/engine/session/repo-utils.d.ts +12 -1
  454. package/dist/engine/session/repo-utils.js +41 -0
  455. package/dist/engine/session/session.js +1 -1
  456. package/dist/engine/session/storage-base.d.ts +20 -0
  457. package/dist/engine/session/storage-base.js +28 -9
  458. package/dist/fixtures/index.d.ts +7 -5
  459. package/dist/fixtures/index.js +5 -3
  460. package/dist/index.d.ts +29 -18
  461. package/dist/index.js +19 -11
  462. package/dist/internal/harness-types.d.ts +2 -0
  463. package/dist/internal/harness.d.ts +4 -3
  464. package/dist/internal/harness.js +3 -2
  465. package/dist/internal/llm.d.ts +2 -1
  466. package/dist/internal/llm.js +1 -0
  467. package/dist/orchestration/goal.d.ts +6 -2
  468. package/dist/orchestration/goal.js +6 -3
  469. package/dist/orchestration/run-workflow-tool.d.ts +14 -17
  470. package/dist/orchestration/run-workflow-tool.js +43 -50
  471. package/dist/orchestration/workflow-types.d.ts +2 -2
  472. package/dist/orchestration/workflow.d.ts +7 -0
  473. package/dist/orchestration/workflow.js +10 -12
  474. package/dist/stores/file/background-agent-store.js +18 -15
  475. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  476. package/dist/stores/file/checkpoint-store.js +13 -9
  477. package/dist/stores/file/file-history-store.js +3 -2
  478. package/dist/stores/file/fs-atomic.d.ts +0 -22
  479. package/dist/stores/file/fs-atomic.js +0 -17
  480. package/dist/stores/file/index.d.ts +7 -12
  481. package/dist/stores/file/index.js +25 -12
  482. package/dist/stores/file/ledger-tuning.d.ts +23 -0
  483. package/dist/stores/file/ledger-tuning.js +21 -0
  484. package/dist/stores/file/mailbox-store.js +42 -22
  485. package/dist/stores/file/memory-store.js +3 -2
  486. package/dist/stores/file/permission-rule-adopt.js +24 -21
  487. package/dist/stores/file/permission-rule-store.js +6 -3
  488. package/dist/stores/file/session-policy-store.js +3 -2
  489. package/dist/stores/file/session-store.d.ts +26 -7
  490. package/dist/stores/file/session-store.js +59 -35
  491. package/dist/stores/file/tool-result-store.d.ts +11 -0
  492. package/dist/stores/file/tool-result-store.js +57 -3
  493. package/dist/stores/file/usage-window-store.js +3 -2
  494. package/dist/stores/file/workflow-journal-store.d.ts +0 -2
  495. package/dist/stores/file/workflow-journal-store.js +3 -18
  496. package/dist/stores/file/workflow-run-store.d.ts +1 -1
  497. package/dist/stores/file/workflow-run-store.js +15 -10
  498. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  499. package/dist/tools/fs/bash-program-position.js +7 -7
  500. package/dist/tools/fs/dead-cwd.d.ts +5 -5
  501. package/dist/tools/fs/dead-cwd.js +4 -11
  502. package/dist/tools/fs/fs-bash-background-text.d.ts +6 -0
  503. package/dist/tools/fs/fs-bash-background-text.js +6 -0
  504. package/dist/tools/fs/fs-bash.d.ts +3 -18
  505. package/dist/tools/fs/fs-bash.js +37 -124
  506. package/dist/tools/fs/fs-pdf.js +8 -6
  507. package/dist/tools/fs/fs-read.js +2 -2
  508. package/dist/tools/fs/fs-shared.d.ts +28 -3
  509. package/dist/tools/fs/fs-shared.js +15 -0
  510. package/dist/tools/fs/index.d.ts +1 -1
  511. package/dist/tools/fs/index.js +4 -14
  512. package/dist/tools/fs/pdf.d.ts +4 -4
  513. package/dist/tools/fs/pdf.js +6 -6
  514. package/dist/tools/fs/read-deny-home.js +8 -1
  515. package/dist/tools/fs/read-deny.d.ts +26 -2
  516. package/dist/tools/fs/read-deny.js +9 -2
  517. package/dist/tools/fs/read-floor.d.ts +13 -5
  518. package/dist/tools/fs/read-floor.js +206 -2
  519. package/dist/tools/fs/removal-targets.js +2 -2
  520. package/dist/tools/fs/search.d.ts +3 -2
  521. package/dist/tools/fs/search.js +6 -6
  522. package/dist/tools/fs/shell-read-argv.d.ts +4 -2
  523. package/dist/tools/fs/shell-read-argv.js +14 -3
  524. package/dist/tools/fs/shell-read-bindings.d.ts +18 -2
  525. package/dist/tools/fs/shell-read-bindings.js +148 -68
  526. package/dist/tools/fs/shell-read-check.js +20 -4
  527. package/dist/tools/fs/shell-read-establish.js +25 -9
  528. package/dist/tools/fs/shell-read-functions.js +2 -2
  529. package/dist/tools/fs/shell-read-identity.d.ts +3 -1
  530. package/dist/tools/fs/shell-read-identity.js +4 -2
  531. package/dist/tools/fs/shell-read-judge.d.ts +7 -1
  532. package/dist/tools/fs/shell-read-judge.js +1 -1
  533. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  534. package/dist/tools/fs/shell-read-object-path.js +119 -0
  535. package/dist/tools/fs/shell-read-plan.d.ts +8 -0
  536. package/dist/tools/fs/shell-read-plan.js +47 -30
  537. package/dist/tools/fs/shell-read-start.d.ts +66 -13
  538. package/dist/tools/fs/shell-read-start.js +89 -17
  539. package/dist/tools/fs/shell-read-workdir.d.ts +29 -8
  540. package/dist/tools/fs/shell-read-workdir.js +31 -8
  541. package/dist/tools/monitor.d.ts +8 -7
  542. package/dist/tools/monitor.js +12 -10
  543. package/dist/tools/worktree.d.ts +5 -1
  544. package/dist/tools/worktree.js +20 -17
  545. package/package.json +6 -3
  546. package/test/export-surface.snapshot.json +112 -42
  547. package/wire-changes/core-stores-sql@7.61.0.json +480 -0
  548. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  549. package/wire-changes/core@7.61.0.json +4405 -0
  550. package/wire-changes/core@7.62.0.json +2181 -0
  551. package/wire-changes/mods-kernel@7.61.0.json +65 -0
  552. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  553. package/wire-changes/primitives@7.61.0.json +30 -0
  554. package/wire-changes/primitives@7.62.0.json +30 -0
  555. package/dist/core/consolidate-scope.d.ts +0 -93
  556. package/dist/core/consolidate-scope.js +0 -98
  557. package/dist/core/runner/image-removed-seat.d.ts +0 -12
  558. package/dist/core/runner/image-removed-seat.js +0 -19
  559. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  560. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -2,7 +2,9 @@ import type { EstablishedPlan } from "./shell-read-establish.js";
2
2
  import type { ObservedEnvironment } from "./shell-read-environment.js";
3
3
  import type { EstablishedRead } from "./shell-read-judge.js";
4
4
  import { type HomeViewsCarrier } from "./read-deny-home.js";
5
- /** Every read of either establishment whose candidate's settled target set differs between the two. */
5
+ /** Every read of either establishment whose candidate's settled target set — or the set of link-chain hops it was judged
6
+ * through ({@link EstablishedRead.hops}: a chain re-pointed through another directory may keep its terminal) — differs
7
+ * between the two. */
6
8
  export declare function movedReads(previous: EstablishedPlan, again: EstablishedPlan): EstablishedRead[];
7
9
  /** One read candidate's landing: its key and where it settled, each as a sha256 hex digest (the key's raw tuple joins on
8
10
  * NUL and follows the command's length; a pattern lands on up to thousands of entries), with the raw word and the
@@ -7,7 +7,7 @@ export function movedReads(previous, again) {
7
7
  for (const key of new Set([...before.keys(), ...after.keys()])) {
8
8
  const b = before.get(key);
9
9
  const a = after.get(key);
10
- if (b !== undefined && a !== undefined && landingOf(b.targets) === landingOf(a.targets))
10
+ if (b !== undefined && a !== undefined && landingOf(b.targets) === landingOf(a.targets) && landingOf(b.hops) === landingOf(a.hops))
11
11
  continue;
12
12
  changed.push(...(b?.reads ?? []), ...(a?.reads ?? []));
13
13
  }
@@ -27,11 +27,13 @@ function targetsByCandidate(e) {
27
27
  for (const r of p.reads.get(segment) ?? []) {
28
28
  const c = r.candidate;
29
29
  const key = [at, si, c.denyOnly === true ? "floor" : "read", c.provenance, c.spelled, String(c.expands), c.raw].join("\0");
30
- const landing = out.get(key) ?? { targets: new Set(), reads: [] };
30
+ const landing = out.get(key) ?? { targets: new Set(), hops: new Set(), reads: [] };
31
31
  out.set(key, landing);
32
32
  landing.reads.push(r);
33
33
  if ((r.established === "canonical" || r.established === "expansion") && r.target !== undefined)
34
34
  landing.targets.add(r.target);
35
+ for (const hop of r.hops ?? [])
36
+ landing.hops.add(hop);
35
37
  }
36
38
  segment.nested.forEach((n, ni) => {
37
39
  const nested = p.nested.get(n);
@@ -5,7 +5,8 @@
5
5
  *
6
6
  * · `judgeRead` judges ONE established candidate: the deny half first, over every view the candidate has
7
7
  * (its canonical target, its folded spelling, the kernel spelling of a `..` operand, the folded spelling
8
- * of a candidate that could not be established), then containment over the canonical target alone. The
8
+ * of a candidate that could not be established, the hops of its leaf symlink chain), then containment over
9
+ * the canonical target alone. The
9
10
  * deny judge is the boundary's own `denyMatch` closure (`readDenySeat`, read-deny.ts) — the same function
10
11
  * object every read face mounts; nothing here compiles a pattern or re-derives a view set. The containment
11
12
  * judge is `withinAnyRoot` over the roots the boundary declares — a WRITE target's over the write roots, at the
@@ -248,6 +249,11 @@ export interface EstablishedRead {
248
249
  * name of a GNU sed `--follow-symlinks` backup when the operand's links supplied it. Every other spelling is the command's
249
250
  * own text (folded, or as the kernel walks it). Absent ⇒ none. */
250
251
  readonly derivedSpellings?: readonly string[];
252
+ /** The hops of the landed target's LEAF symlink chain — each an unresolved spelling some link on the way wrote — where the
253
+ * program follows the target's links (the landing seat): the views a call's target reading judges beside the canonical
254
+ * and the lexical one, read through the same chain reader. Deny views only: not a spelling the
255
+ * command wrote, not a containment candidate, not a write view of its own. Absent ⇒ none read. */
256
+ readonly hops?: readonly string[];
251
257
  /** The pattern or traversal root an `expansion` came from, as folded. */
252
258
  readonly origin?: string;
253
259
  /** What the environment said the target IS, where a read asked — only a traversal root asks (it lists the root
@@ -46,7 +46,7 @@ export function judgeRead(read, boundary) {
46
46
  const writeTarget = read.candidate.face === "write";
47
47
  const deny = writeTarget ? boundary.writeDenyMatch : boundary.denyMatch;
48
48
  if (deny !== undefined) {
49
- const views = [...(read.target !== undefined ? [read.target] : []), ...read.spellings];
49
+ const views = [...(read.target !== undefined ? [read.target] : []), ...read.spellings, ...(read.hops ?? [])];
50
50
  for (const view of views) {
51
51
  const folded = normalizeAbsPathLexically(view);
52
52
  const pattern = writeTarget ? boundary.writeDenyMatch(folded) : boundary.denyMatch(folded);
@@ -0,0 +1,59 @@
1
+ /**
2
+ * AN OBJECT PATH — `<rev>:<path>` (`git show HEAD:x`, `git cat-file -p :0:x`) — and the file of the working tree it names,
3
+ * which is what the deny rows are met at. The place is where git resolves the path (gitrevisions(7)):
4
+ * · spelled `./…` / `../…`, it is relative to the directory git starts in;
5
+ * · any other spelling is relative to the repository's TOP: the directory `--work-tree` names, else the one git's discovery
6
+ * finds walking up from where it starts — a filesystem fact ({@link repositoryTopOf}), read by the establishment where it
7
+ * has a filesystem, never by the plan;
8
+ * · git starts in the command's directory moved by each `-C` (git chdir()s to the spelling: the kernel's walk of it).
9
+ * Where git may be pointed at a repository by other means (`--git-dir`, `--bare`, a `GIT_*` variable the command's
10
+ * environment may carry — bound in the text, or received from the environment that runs it, `ExecutionEnv.receivedEnvNames`),
11
+ * where the text does not settle where git starts, or where the filesystem does not say, the top is any directory at or above
12
+ * where git starts: every ancestor meets the deny rows.
13
+ */
14
+ import type { ExecutionEnv } from "../../internal/harness-types.js";
15
+ import { type ProgramRow } from "./program-read-model.js";
16
+ import { type PathFamily } from "./safety.js";
17
+ import type { Read } from "./shell-read-word.js";
18
+ /** What git's own options in front of the subcommand say about the repository an object path resolves in. */
19
+ export interface ObjectPathRepository {
20
+ /** Each `-C` value, in order (`undefined`: one the text does not settle). */
21
+ readonly moves: readonly (string | undefined)[];
22
+ /** The last `--work-tree` value (`null`: one the text does not settle). */
23
+ readonly workTree?: string | null;
24
+ /** `--git-dir` / `--bare`: the repository is named, and only its configuration knows its top. */
25
+ readonly named?: true;
26
+ }
27
+ /** How an object path's top is found: `discovered` — by git's discovery from where it starts; `unknown` — not from the text. */
28
+ export type RepositoryTop = "discovered" | "unknown";
29
+ /** {@link ObjectPathRepository} of the program's words in front of its subcommand, read by the program's own row. */
30
+ export declare function objectPathRepositoryOf(row: ProgramRow | undefined, globals: readonly Read[]): ObjectPathRepository;
31
+ /** Whether a command's environment may carry a variable git reads for its repository (any `GIT_*` name one of its parts holds;
32
+ * `all`: a part whose names are not known). */
33
+ export declare function mayCarryGitVariables(...names: readonly (Iterable<string> | "all")[]): boolean;
34
+ /** Where a process stands after it `chdir()`s to `spelling` from each of `bases` (git's `-C`, a launcher's working-directory
35
+ * option): the kernel's walk of the spelling, a `..` kept (`<base>/link/..` is the link target's parent, not `<base>`).
36
+ * `undefined` where the spelling resolves to no place from some base (`~user`, a namespace spelling the base's family refuses). */
37
+ export declare function chdirFrom(bases: readonly string[], spelling: string, homeDir: string | undefined): string[] | undefined;
38
+ /** The place of a RELATIVE object path: the directories it is relative to (`at`: where the command stands; `floor`: the deny
39
+ * floor of an unsettled `at`), and how its top is found where it is relative to the top. */
40
+ export declare function objectPathPlacement(spelled: string, repository: ObjectPathRepository | undefined, at: readonly string[] | "unmodelled", floor: readonly string[] | undefined, homeDir: string | undefined, variables: boolean): {
41
+ readonly bases: readonly string[] | "unmodelled";
42
+ readonly floorBases?: readonly string[];
43
+ readonly repositoryTop?: RepositoryTop;
44
+ };
45
+ /** Each directory, and every directory above it (its `..`-folded spelling's, a spelling that climbs kept beside them). */
46
+ export declare function everyAncestor(dirs: readonly string[]): string[];
47
+ /** What {@link repositoryTopOf} asks of the environment (the station's door, where it has one). */
48
+ export type RepositoryProbe = Pick<ExecutionEnv, "canonicalPath" | "fileInfo" | "readTextFile" | "readLink">;
49
+ /**
50
+ * The repository top git's discovery finds starting in `dir` (setup.c `setup_git_directory_gently_1`): walking up from the
51
+ * directory's canonical form, the first directory holding a `.git` DIRECTORY that is a repository (`HEAD` naming a ref or an
52
+ * object id, `objects/` and `refs/` directories) whose own `config` names no work tree. `undefined` wherever git's answer may be
53
+ * another directory, or the history it reads another directory's: a `.git` that is not such a directory — a `gitdir:` file or a
54
+ * link, which name a repository kept elsewhere (a linked work tree's, a submodule's, the home's own), or one git skips (an
55
+ * empty or broken one) and walks on from —, a directory that is itself a repository (a bare one, the inside of a `.git`), a
56
+ * configuration that may name the work tree, no repository at all, or a lookup the environment did not answer. Any reader of
57
+ * "which repository does git run in from here" reads it.
58
+ */
59
+ export declare function repositoryTopOf(fs: RepositoryProbe, dir: string, family: PathFamily, signal?: AbortSignal): Promise<string | undefined>;
@@ -0,0 +1,119 @@
1
+ import { literalTildeSpelling } from "../../shell/lex.js";
2
+ import { resolveOperandLexically, resolveOperandSpellings } from "./bash-readonly-classifier.js";
3
+ import { readArgRoles } from "./program-read-model.js";
4
+ import { anchorSpelling, normalizeAbsPathLexically } from "./safety.js";
5
+ import { isAbsence } from "./shell-read-environment.js";
6
+ const STARTS_IN = "-C";
7
+ const NAMES_TOP = "--work-tree";
8
+ const NAMES_REPOSITORY = new Set(["--git-dir", "--bare"]);
9
+ export function objectPathRepositoryOf(row, globals) {
10
+ const words = globals.map((r) => r.folded);
11
+ const settled = (r, value) => (r.expands === false && (r.values?.length ?? 1) <= 1 ? value : undefined);
12
+ const moves = [];
13
+ let workTree;
14
+ let named = false;
15
+ for (const e of row === undefined ? [] : readArgRoles(row, words)) {
16
+ if (e.kind !== "value" && e.kind !== "option")
17
+ continue;
18
+ const option = e.kind === "value" ? words[e.of] : words[e.at].split("=")[0];
19
+ const value = e.kind === "value" ? settled(globals[e.at], words[e.at]) : typeof e.reading === "object" ? settled(globals[e.at], literalTildeSpelling(e.reading.attached)) : undefined;
20
+ if (option === STARTS_IN)
21
+ moves.push(value);
22
+ else if (option === NAMES_TOP)
23
+ workTree = value ?? null;
24
+ else if (NAMES_REPOSITORY.has(option))
25
+ named = true;
26
+ }
27
+ return { moves, ...(workTree !== undefined ? { workTree } : {}), ...(named ? { named: true } : {}) };
28
+ }
29
+ export function mayCarryGitVariables(...names) {
30
+ return names.some((part) => part === "all" || [...part].some((n) => n.startsWith("GIT_")));
31
+ }
32
+ export function chdirFrom(bases, spelling, homeDir) {
33
+ const out = bases.map((b) => resolveOperandSpellings(b, spelling, homeDir)).map((s) => s?.spelled ?? s?.folded);
34
+ return out.every((p) => p !== undefined) ? [...new Set(out)] : undefined;
35
+ }
36
+ export function objectPathPlacement(spelled, repository, at, floor, homeDir, variables) {
37
+ const dotted = /^\.\.?(?:\/|$)/.test(spelled);
38
+ const place = (bases, word) => chdirFrom(bases, word, homeDir);
39
+ const unplaced = (top) => {
40
+ const floors = at === "unmodelled" ? floor : at;
41
+ return { bases: "unmodelled", ...(floors !== undefined && floors.length > 0 ? { floorBases: floors } : {}), ...(top !== undefined ? { repositoryTop: top } : {}) };
42
+ };
43
+ let starts = at === "unmodelled" ? undefined : at;
44
+ for (const move of repository?.moves ?? [])
45
+ if (starts !== undefined && move !== "")
46
+ starts = move === undefined ? undefined : place(starts, move);
47
+ if (starts === undefined)
48
+ return unplaced(dotted ? undefined : "unknown");
49
+ if (dotted)
50
+ return { bases: starts };
51
+ const workTree = repository?.workTree;
52
+ if (workTree !== undefined) {
53
+ const tops = workTree === null ? undefined : place(starts, workTree);
54
+ return tops === undefined ? unplaced("unknown") : { bases: tops };
55
+ }
56
+ return { bases: starts, repositoryTop: repository?.named === true || variables ? "unknown" : "discovered" };
57
+ }
58
+ export function everyAncestor(dirs) {
59
+ const out = new Set(dirs);
60
+ for (const dir of dirs) {
61
+ for (let d = resolveOperandLexically(dir, ".", undefined) ?? dir;;) {
62
+ out.add(d);
63
+ const up = resolveOperandLexically(d, "..", undefined) ?? d;
64
+ if (up === d)
65
+ break;
66
+ d = up;
67
+ }
68
+ }
69
+ return [...out];
70
+ }
71
+ const READ_LIMIT = 65_536;
72
+ export async function repositoryTopOf(fs, dir, family, signal) {
73
+ const start = await fs.canonicalPath(dir, signal);
74
+ if (!start.ok)
75
+ return undefined;
76
+ const entry = async (path) => {
77
+ const info = await fs.fileInfo(path, signal);
78
+ if (!info.ok)
79
+ return isAbsence(info.error.code) ? "absent" : "unanswered";
80
+ return info.value.kind === "symlink" ? "link" : info.value.kind;
81
+ };
82
+ const text = async (path) => {
83
+ const info = await fs.fileInfo(path, signal);
84
+ if (!info.ok || info.value.kind !== "file" || info.value.size > READ_LIMIT)
85
+ return undefined;
86
+ const read = await fs.readTextFile(path, signal);
87
+ return read.ok ? read.value : undefined;
88
+ };
89
+ const isRepository = async (git) => {
90
+ for (const name of ["objects", "refs"]) {
91
+ const info = await fs.fileInfo(anchorSpelling(family, git, name), signal);
92
+ if (!info.ok || info.value.kind !== "directory" || (info.value.mode !== undefined && (info.value.mode & 0o100) === 0))
93
+ return false;
94
+ }
95
+ const head = anchorSpelling(family, git, "HEAD");
96
+ const headRef = (await entry(head)) === "link" ? await fs.readLink?.(head, signal).then((r) => (r.ok && r.value.startsWith("refs/") ? "ref: refs/" : undefined)) : await text(head);
97
+ if (headRef === undefined || !/^(?:ref:[ \t\n\r]*refs\/|[0-9a-fA-F]{40})/.test(headRef.slice(0, 255)))
98
+ return false;
99
+ const config = anchorSpelling(family, git, "config");
100
+ return (await entry(config)) === "absent" || ((await text(config)) ?? "worktree").search(/worktree/i) < 0;
101
+ };
102
+ for (let d = start.value;;) {
103
+ const git = anchorSpelling(family, d, ".git");
104
+ const found = await entry(git);
105
+ if (found === "directory")
106
+ return (await isRepository(git)) ? d : undefined;
107
+ if (found !== "absent")
108
+ return undefined;
109
+ const head = await entry(anchorSpelling(family, d, "HEAD"));
110
+ if (head === "unanswered")
111
+ return undefined;
112
+ if (head !== "absent" && ((await entry(anchorSpelling(family, d, "refs"))) !== "absent" || (await entry(anchorSpelling(family, d, "commondir"))) !== "absent"))
113
+ return undefined;
114
+ const up = normalizeAbsPathLexically(anchorSpelling(family, d, ".."));
115
+ if (up === d)
116
+ return undefined;
117
+ d = up;
118
+ }
119
+ }
@@ -32,6 +32,7 @@
32
32
  */
33
33
  import { type LenientConnector, type LexedRedirect, type LexedWord } from "../../shell/lex.js";
34
34
  import { type ShellScanDecline } from "./bash-program-position.js";
35
+ import { type RepositoryTop } from "./shell-read-object-path.js";
35
36
  import { type StdinText } from "./shell-reentry-text.js";
36
37
  import { type PlanStart } from "./shell-read-start.js";
37
38
  /** WHY a word is a read candidate — a closed set, registered in `docs/CLOSED-SETS.md`. */
@@ -51,6 +52,9 @@ export interface ShellReadDeclarations {
51
52
  /** The `CDPATH` the shell starts with (the environment's declared one, `ExecutionEnv.cdPath`; a bare relative `cd` is
52
53
  * searched through it): absent ⇒ none declared, read as unset; `unknown` ⇒ the text cannot know it. */
53
54
  readonly cdPath?: readonly string[] | "unknown";
55
+ /** The names of the environment the shell starts with (the environment's declared ones, `ExecutionEnv.receivedEnvNames`):
56
+ * absent ⇒ none declared, read as any name. */
57
+ readonly receivedEnvNames?: readonly string[];
54
58
  }
55
59
  export interface ReadCandidate {
56
60
  /** The folded word (quotes removed, a literal leading tilde spelled `./~`) — a pattern's name where nothing matches. */
@@ -71,6 +75,10 @@ export interface ReadCandidate {
71
75
  * A deny row is a floor, so the judge resolves the spelling against these for deny rows ONLY — never to
72
76
  * establish a read. `cd sub && cd $'\x2e' && cat <deny row under sub>` (bash: `cd .`) is refused through it. */
73
77
  readonly floorBases?: readonly string[];
78
+ /** Only on an object path relative to its repository's top (shell-read-object-path.ts): `bases` / `floorBases` are where
79
+ * git starts, the top one of them or above — the one discovery finds (`discovered`, read where a filesystem answers),
80
+ * else any: every ancestor meets the deny rows. */
81
+ readonly repositoryTop?: RepositoryTop;
74
82
  /** A home word the plan does not place (the text may rebind `HOME`, it sits in a value, or it is a literal tilde the
75
83
  * program may expand itself): spelled with the DECLARED home. The judge reads it for deny rows ONLY. */
76
84
  readonly floorSpelled?: string;
@@ -1,15 +1,16 @@
1
1
  import { expansionsInHeredocBody, lexShell, PARSE_FAILURE_SENTENCE, substitutionsInHeredocBody, literalTextOf, literalTildeSpelling, parameterRereadsValue, UNRESOLVED_SENTENCE, } from "../../shell/lex.js";
2
2
  import { programTextOf, readOfText, readsOf, rewritten, segmentReadingsOf, settledFieldsOf, spelledWithHome, unreadableSentenceOf } from "./shell-read-word.js";
3
3
  import { assignmentArithmetic, bare, listedVerbCandidates, pathSubcommandOf, programTextSentence, pushAssignment, roleReads, subscriptOnly, unlistedWords } from "./shell-read-argv.js";
4
- import { ARITHMETIC_TEST_OPERATORS, BindingThread, arithmeticSubstitutions, inheritedFunctionsOf, inheritedExportedFunctions, isArithmeticCommand, bindingEffectOf, joinRebound, loopListHeadAt, namesBoundIn, parameterBodySubstitutions, projectSegment, valueOf, } from "./shell-read-bindings.js";
4
+ import { ARITHMETIC_TEST_OPERATORS, BindingThread, arithmeticSubstitutions, assignsAsStatement, inheritedFunctionsOf, inheritedExportedFunctions, isArithmeticCommand, bindingEffectOf, joinRebound, loopListHeadAt, namesBoundIn, parameterBodySubstitutions, projectSegments, valueOf, } from "./shell-read-bindings.js";
5
5
  import { commandEnvironmentNames, isShellSyntaxWord, programBasename, programPositionRunsShell, readProgramPosition, shellScanDeclineOf, } from "./bash-program-position.js";
6
6
  import { WorkdirThread, baseShiftOf, textCalls, textMayMove, textMovesOf, textSetsPhysical, withCommandEnvironment } from "./shell-read-workdir.js";
7
- import { POLL_LOOP_MAX_BEATS, attachedOptionPayloads, resolveOperandLexically, isPathShapedToken, programTextSlotFiles, } from "./bash-readonly-classifier.js";
7
+ import { POLL_LOOP_MAX_BEATS, attachedOptionPayloads, isPathShapedToken, programTextSlotFiles, } from "./bash-readonly-classifier.js";
8
+ import { mayCarryGitVariables, objectPathPlacement } from "./shell-read-object-path.js";
8
9
  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
10
  import { shellWordsOf } from "../../shell/shell-words.js";
10
11
  import { isAbsoluteForFamily } from "./safety.js";
11
12
  import { codeBodies, launchedInput, pipedTextOf, printedByProcess, reentersShell, reentryText, scriptFileAt, stdinTextsOf } from "./shell-reentry-text.js";
12
- import { heldAt, plannedOnce, rebasePlan, startedAt, stdinFeeds } from "./shell-read-start.js";
13
+ import { heldAt, launchedAt, launchedInOf, nestedStartOf, plannedOnce, rebasePlan, startedAt, stdinFeeds } from "./shell-read-start.js";
13
14
  import { markStandardDevices } from "./shell-read-device.js";
14
15
  export const READ_CANDIDATE_PROVENANCES = Object.freeze([
15
16
  "operand",
@@ -33,13 +34,14 @@ export function planShellReads(command, decl, depth = 0, start) {
33
34
  }
34
35
  function planText(command, decl, depth, start, from) {
35
36
  const shape = { grouped: false, backgrounded: false, strayRedirection: false };
37
+ const none = new Set();
36
38
  if (depth > NESTING_MAX)
37
- return { plan: { segments: [], unreadable: `command text nested more than ${NESTING_MAX} levels deep`, shape }, end: "unmodelled", physical: false };
39
+ return { plan: { segments: [], unreadable: `command text nested more than ${NESTING_MAX} levels deep`, shape }, end: "unmodelled", physical: false, reached: none };
38
40
  const lexed = lexShell(command);
39
41
  if ("parseFailure" in lexed)
40
- return { plan: { segments: [], unreadable: PARSE_FAILURE_SENTENCE[lexed.parseFailure.reason], shape }, end: "unmodelled", physical: false };
42
+ return { plan: { segments: [], unreadable: PARSE_FAILURE_SENTENCE[lexed.parseFailure.reason], shape }, end: "unmodelled", physical: false, reached: none };
41
43
  const unreadable = unreadableSentenceOf(lexed, command);
42
- const projected = lexed.segments.map((segment) => projectSegment(segment));
44
+ const projected = projectSegments(lexed.segments);
43
45
  const exportedFunctions = inheritedFunctionsOf(projected, start?.exportedFunctions), exportedNames = new Set(exportedFunctions.keys());
44
46
  const named = projected.map((p, si) => bindingEffectOf(lexed.segments[si], p.argv, p, () => "unknown"));
45
47
  const boundHere = (name) => named.some((e) => e.all === "unknown" || e.bindings.some((b) => b.name === name));
@@ -64,7 +66,7 @@ function planText(command, decl, depth, start, from) {
64
66
  }
65
67
  const names = new BindingThread(lexed.segments, named, initial, boundAnywhere, loopEndOf, start?.homeTouched === true, start?.inherited, start?.names);
66
68
  const laterStart = { initial: (name) => declared(name, boundAnywhere(name)), boundAnywhere, homeTouched: boundAnywhere("HOME"), inherited: names.inheritedAt() };
67
- const nestedPlanner = (table, si) => (text, kind, at) => planShellReads(text, decl, depth + 1, kind === "substitution" ? { initial: (name) => table.stateOf(name), boundAnywhere, homeTouched: table.homeTouched, inherited: table.inherited, thread: heldThread(moves.functions), names: heldAt(table), ...(exportedFunctions.size > 0 ? { exportedFunctions } : {}) } : startedAt(kind === "now" ? { ...laterStart, inherited: { ...laterStart.inherited, rebound: joinRebound(table.inherited.rebound, commandEnvironmentNames(projected[si].argv)) }, ...(exportedFunctions.size > 0 ? { exportedFunctions } : {}), ...(readProgramPosition(projected[si].argv).program?.basename === "eval" ? { thread: heldThread(moves.unread), names: heldAt(table, names.functionBound()) } : exportedFunctions.size > 0 ? { thread: { physical: false, functions: exportedNames, unread: exportedNames }, names: inheritedExportedFunctions(exportedFunctions) } : {}) } : { ...laterStart, thread: heldThread(moves.functions, workdir.mayBePhysical || moves.physicalAt.some(Boolean)), names: names.heldAnywhere(), ...(exportedFunctions.size > 0 ? { exportedFunctions } : {}) }, at));
69
+ const nestedPlanner = (table, si) => (text, kind, at) => planShellReads(text, decl, depth + 1, kind === "substitution" ? { initial: (name) => table.stateOf(name), boundAnywhere, homeTouched: table.homeTouched, inherited: table.inherited, thread: heldThread(moves.functions), names: heldAt(table), ...(exportedFunctions.size > 0 ? { exportedFunctions } : {}) } : startedAt(kind === "now" ? { ...laterStart, inherited: { ...laterStart.inherited, rebound: joinRebound(table.inherited.rebound, commandEnvironmentNames(projected[si].argv)) }, ...(exportedFunctions.size > 0 ? { exportedFunctions } : {}), ...(readProgramPosition(projected[si].argv).program?.basename === "eval" ? { thread: heldThread(moves.unread), names: heldAt(table, names.functionBound()) } : exportedFunctions.size > 0 ? { thread: { physical: false, functions: exportedNames, unread: exportedNames, reached: workdir.reached }, names: inheritedExportedFunctions(exportedFunctions) } : {}) } : { ...laterStart, thread: heldThread(moves.functions, workdir.mayBePhysical || moves.physicalAt.some(Boolean)), names: names.heldAnywhere(), ...(exportedFunctions.size > 0 ? { exportedFunctions } : {}) }, at));
68
70
  const empty = lexed.segments.map((segment, si) => segmentIsEmpty(segment, projected[si]));
69
71
  const facts = projected.map(() => undefined);
70
72
  const tables = projected.map(() => undefined);
@@ -78,27 +80,38 @@ function planText(command, decl, depth, start, from) {
78
80
  const unmodelled = projected.map(() => false);
79
81
  const moves = textMovesOf(new Set(projected.flatMap((p) => p.defines)), projected.map((p) => p.argv), (si) => names.inFunctionBody(si), start?.thread);
80
82
  names.runsBodies(moves.runsBodyAt, moves.bodiesAt.some((b) => b.length > 0), moves.mayCallAt.map((c, si) => (c ? commandEnvironmentNames(projected[si].argv) : undefined)));
81
- const workdir = new WorkdirThread(from ?? start?.bases ?? [decl.cwd], depth === 0 || start?.bases !== undefined || from !== undefined, start?.thread?.physical === true);
83
+ const workdir = new WorkdirThread(depth > 0 && from === undefined && start?.bases === undefined ? [nestedStartOf(decl.cwd)] : (from ?? start?.bases ?? [decl.cwd]), start?.thread?.physical === true);
84
+ if (start?.thread?.reached !== undefined)
85
+ workdir.reach(start.thread.reached);
82
86
  const workdirContext = {
83
87
  ...(decl.homeDir !== undefined ? { homeDir: decl.homeDir } : {}),
84
88
  textBinds: boundAnywhere,
85
89
  evalEnd: (text, c, table) => {
86
90
  if (moves.bodyMoves && textCalls(text, moves.functions))
87
- return { end: "unmodelled", physical: false };
91
+ return { end: "unmodelled", physical: false, reached: new Set() };
88
92
  if (!textMayMove(text, moves.functions) && !textSetsPhysical(text))
89
- return { end: [c], physical: false };
93
+ return { end: [c], physical: false, reached: new Set() };
90
94
  const ran = planText(text, decl, depth + 1, { initial: (name) => table.stateOf(name), boundAnywhere, homeTouched: table.homeTouched, inherited: table.inherited, thread: heldThread(moves.unread), names: heldAt(table, names.functionBound()) }, [c]);
91
- return { end: ran.end, physical: ran.physical };
95
+ return { end: ran.end, physical: ran.physical, reached: ran.reached };
92
96
  },
93
97
  };
94
- const heldThread = (unread, physical = workdir.mayBePhysical) => ({ physical, functions: moves.functions, unread });
98
+ const heldThread = (unread, physical = workdir.mayBePhysical) => ({ physical, functions: moves.functions, unread, reached: workdir.reached });
95
99
  let andRunStart = 0;
96
100
  let crossedAllAnd = true;
97
101
  let crossedAnyOr = false;
98
102
  let previousEmitted = -1;
99
103
  const reaches = projected.map(() => undefined);
100
104
  const loops = [];
105
+ const scopes = [];
106
+ const closeScopes = (j) => {
107
+ const k = scopes.findIndex((s) => !names.reaches(s.at, j));
108
+ if (k < 0)
109
+ return;
110
+ workdir.restore(scopes[k].state);
111
+ scopes.length = k;
112
+ };
101
113
  const thread = (si, replay) => {
114
+ closeScopes(si);
102
115
  const connector = lexed.segments[si].connector;
103
116
  if (previousEmitted >= 0) {
104
117
  if (replay || connector !== "&&")
@@ -124,11 +137,14 @@ function planText(command, decl, depth, start, from) {
124
137
  else
125
138
  for (const c of workdir.reachable(andRunStart))
126
139
  basesOf[si].add(c.base);
140
+ const losesBase = moves.losesBaseAt(si, tables[si]);
141
+ if (names.runsApart(si) && (moves.physicalAt[si] || (f.shift !== undefined && call !== "named") || losesBase))
142
+ scopes.push({ at: si, state: workdir.snapshot() });
127
143
  if (moves.physicalAt[si])
128
144
  workdir.setPhysical();
129
145
  if (f.shift !== undefined && call !== "named")
130
146
  workdir.shift(si, { shift: f.shift, provable: reaches[si].moveProvable && call === undefined, andRunStart, table: withCommandEnvironment(tables[si], projected[si].argv), cdable: moves.cdableFrom >= 0 && si > moves.cdableFrom }, workdirContext);
131
- if (moves.losesBaseAt(si, tables[si]))
147
+ if (losesBase)
132
148
  workdir.lose(si, workdir.reachable(andRunStart));
133
149
  };
134
150
  const bind = (si) => {
@@ -176,7 +192,11 @@ function planText(command, decl, depth, start, from) {
176
192
  for (let k = frame.bodyStart; k < si; k++)
177
193
  thread(k, true);
178
194
  }
195
+ if (workdir.lost && frame.beats > 1)
196
+ for (let k = frame.bodyStart; k < si; k++)
197
+ unmodelled[k] = true;
179
198
  }
199
+ closeScopes();
180
200
  const planned = facts.map((f) => f);
181
201
  const inert = depth === 0 && unreadable === undefined && planned.every((f) => (f.readings ?? [f]).every(segmentOpensNothing));
182
202
  const settled = inert ? planned.map((f) => ({ ...f, reads: f.reads.filter((c) => c.provenance !== "env_assignment"), ...(f.readings !== undefined ? { readings: f.readings.map((g) => ({ ...g, reads: g.reads.filter((c) => c.provenance !== "env_assignment") })) } : {}) })) : planned;
@@ -191,18 +211,22 @@ function planText(command, decl, depth, start, from) {
191
211
  const bases = unmodelled[si] ? "unmodelled" : [...basesOf[si]];
192
212
  const floorBases = workdir.floorBases;
193
213
  const floor = unmodelled[si] && floorBases !== undefined && floorBases.length > 0 ? floorBases : undefined;
194
- const placedAt = (at, atFloor) => (c) => {
214
+ const placedAt = (at, atFloor, gitVariables = true) => (c) => {
195
215
  const relative = relativeSpelling(c.spelled);
196
- const here = c.provenance === "object_path" && at !== "unmodelled" ? [...new Set(at.flatMap(ancestorsOf))] : at;
197
- return { ...c, bases: relative ? here : [], ...(relative && atFloor !== undefined ? { floorBases: atFloor } : {}) };
216
+ if (c.provenance === "object_path" && relative) {
217
+ const { repository, ...read } = c;
218
+ return { ...read, ...objectPathPlacement(c.spelled, repository, at, atFloor, decl.homeDir, gitVariables) };
219
+ }
220
+ return { ...c, bases: relative ? at : [], ...(relative && atFloor !== undefined ? { floorBases: atFloor } : {}) };
198
221
  };
199
222
  const withBases = placedAt(bases, floor);
200
223
  const move = threaded.baseMove;
201
224
  for (const f of threaded.readings ?? [threaded]) {
202
- const moved = readProgramPosition(f.argv).launcherMovesBase;
203
- const programPlaced = moved ? placedAt("unmodelled", bases !== "unmodelled" ? bases : floor) : withBases;
225
+ const launched = launchedAt(f.launchedIn, bases, floor, decl.homeDir);
226
+ const gitVariables = mayCarryGitVariables(decl.receivedEnvNames ?? "all", tables[si]?.rebound ?? "all", commandEnvironmentNames(f.argv));
227
+ const programPlaced = launched !== undefined ? placedAt("unmodelled", launched.words, gitVariables) : placedAt(bases, floor, gitVariables);
204
228
  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));
229
+ const placeNested = (n) => (f.elsewhere?.has(n) === true ? n : launched !== undefined && f.shellSide?.has(n) !== true ? rebasePlan(n, launched.to, launched.floor) : rebasePlan(n, bases, bases === "unmodelled" ? floor : bases));
206
230
  segments.push({
207
231
  text: f.text,
208
232
  connector: f.connector,
@@ -224,16 +248,7 @@ function planText(command, decl, depth, start, from) {
224
248
  });
225
249
  }
226
250
  }
227
- return { plan: { segments, shape, ...(unreadable !== undefined ? { unreadable } : {}) }, end: workdir.end(), physical: workdir.mayBePhysical };
228
- }
229
- function ancestorsOf(dir) {
230
- const out = [dir];
231
- for (let d = dir, up = parentOf(d); up !== d; d = up, up = parentOf(d))
232
- out.push(up);
233
- return out;
234
- }
235
- function parentOf(dir) {
236
- return resolveOperandLexically(dir, "..", undefined) ?? dir;
251
+ return { plan: { segments, shape, ...(unreadable !== undefined ? { unreadable } : {}) }, end: workdir.end(), physical: workdir.mayBePhysical, reached: workdir.reached };
237
252
  }
238
253
  function loopShapeOf(p) {
239
254
  if (p.argv[0] === undefined)
@@ -375,10 +390,12 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks, inheri
375
390
  ...(f.unreadProgramText === undefined && ctx.programText !== undefined ? { unreadProgramText: ctx.programText } : {}),
376
391
  ...(elsewhere.size > 0 ? { elsewhere } : {}),
377
392
  ...(shellSide.size > 0 ? { shellSide } : {}),
393
+ ...(launchedIn !== undefined ? { launchedIn } : {}),
378
394
  };
379
395
  };
380
396
  const head = toks[0]?.folded;
381
397
  const pos = readProgramPosition(p.argv);
398
+ const launchedIn = launchedInOf(pos, toks);
382
399
  const coproc = pos.written !== undefined && isShellSyntaxWord(p.argv[pos.written], COPROC) ? pos.written : undefined;
383
400
  if (coproc !== undefined && toks.length > coproc + 1) {
384
401
  const once = plannedOnce(nestedPlan);
@@ -418,7 +435,7 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, fed, toks, inheri
418
435
  const listed = basename !== undefined && (decl.readers.has(basename) || basename === "cd");
419
436
  const verb = program === undefined ? undefined : { name: program.name, basename: program.basename, listed };
420
437
  for (const k of pos.assignments) {
421
- pushAssignment(reads, toks[k].word, "env_assignment");
438
+ pushAssignment(reads, toks[k].word, "env_assignment", assignsAsStatement(pos));
422
439
  assignmentArithmetic(toks[k].word, table.isInteger(toks[k].word.assignment?.name ?? ""), ctx);
423
440
  }
424
441
  for (const l of pos.launchers) {
@@ -1,14 +1,17 @@
1
1
  /**
2
2
  * Where a text the read plan (`shell-read-plan.ts`) plans starts: a nested text's start — its names, the deny floors the
3
3
  * words handing it on carry, the user its shell runs as, its standard input and its working directory — and where each
4
- * segment's standard input comes from. A nested plan parsed against the declarations' working directory is re-based onto
5
- * the segment it sits in ({@link rebasePlan}), unless it starts in a working directory of its own.
4
+ * segment's standard input comes from. A nested plan starts at a placeholder ({@link nestedStartOf}) and is re-based onto
5
+ * the segment it sits in ({@link rebasePlan}) — onto the directory a launcher settles for it ({@link launchedAt}) where one
6
+ * does —, unless it starts in a working directory of its own.
6
7
  */
7
- import type { LexedSegment } from "../../shell/lex.js";
8
+ import { type LexedSegment } from "../../shell/lex.js";
8
9
  import type { BindingTable, FloorValue, InheritedBody, InheritedFunctions, NameReader } from "./shell-read-bindings.js";
9
- import type { TargetUser } from "./program-read-model.js";
10
+ import { type ProgramPosition } from "./bash-program-position.js";
11
+ import { type TargetUser } from "./program-read-model.js";
10
12
  import type { StdinText } from "./shell-reentry-text.js";
11
13
  import type { ReadCandidate, ShellReadPlan } from "./shell-read-plan.js";
14
+ import type { Read } from "./shell-read-word.js";
12
15
  /** Where a nested text starts its names: a substitution body inherits the table of the segment it sits in (a subshell
13
16
  * holds every variable of the shell that forks it); a text the shell runs later or elsewhere (a code body, `eval`'s
14
17
  * text, a child shell's `-c`) starts from the text's own start — every name unknown, `HOME` the declared home unless
@@ -46,6 +49,9 @@ export interface HeldThread {
46
49
  readonly physical: boolean;
47
50
  readonly functions: ReadonlySet<string>;
48
51
  readonly unread: ReadonlySet<string>;
52
+ /** The places the shell's closed scopes went (a function body it may call goes there): the deny floor of a walk in the text
53
+ * that loses track ({@link WorkdirThread.reached}). */
54
+ readonly reached?: ReadonlySet<string>;
49
55
  }
50
56
  /** What a shell holds at a segment, for a text that runs in it or in a fork of it ({@link PlanStart.names}): each function and builtin key
51
57
  * as it stands there, and the names a call to one of its functions may change — the ones the text reads a call of: an `eval` text names
@@ -73,13 +79,60 @@ export declare function plannedOnce<K, P>(plan: (text: string, kind: K, at?: Nes
73
79
  */
74
80
  export declare function stdinFeeds(segments: readonly LexedSegment[], start: readonly StdinText[], piped: (si: number) => readonly StdinText[]): (si: number) => readonly StdinText[];
75
81
  /**
76
- * A nested plan (a substitution body, a here-document's substitution, a launcher's command string) was parsed
77
- * against the declarations' working directory; the segment it sits in may stand elsewhere (`cd sub && cat <<EOF
78
- * $(cat secret)`), so its relative candidates are re-based onto the ENCLOSING segment's bases — every base the
79
- * nested text derived from the start is carried over by prefix, an unsettled enclosing base leaves every
80
- * relative candidate unplaced, and absolute candidates are untouched. Recursive: a nested plan's own nested plans
81
- * derive from the same start. A candidate left unplaced is judged where the text stood when it lost track (its floor,
82
- * {@link ReadCandidate.floorBases}): the places the nested text was in move with it like its bases, and an enclosing segment that
83
- * lost its base itself hands on its own floor (`floor`).
82
+ * Where a nested text with no working directory of its own starts (a substitution body, a here-document's substitution, a
83
+ * launcher's command string): a PLACEHOLDER below the declared working directory, joined as its path family joins, whose last
84
+ * segment no text can spell: a NUL byte is in no path the shell can name. Every base the nested text derives from where it
85
+ * starts (a relative move, `-C` or `..` walk from it, the start itself) holds that segment; a place the text names itself
86
+ * (`cd /x`, `-C ~`, a `CDPATH` entry, a closed scope's place on the held thread) does not — the one mark {@link rebasePlan}
87
+ * moves by ({@link walkFromStart}), and the one a walk reads `PWD` by (a start holding it is no place the shell names).
84
88
  */
85
- export declare function rebasePlan(plan: ShellReadPlan, from: string, to: ReadCandidate["bases"], floor?: readonly string[]): ShellReadPlan;
89
+ export declare function nestedStartOf(cwd: string): string;
90
+ /**
91
+ * The walk a base made from a placeholder start ({@link nestedStartOf}): what follows the placeholder's segment (`""` for
92
+ * the start itself), or `undefined` for a place the text names itself. Read off the segment, not the spelling above it, so
93
+ * a fold of the declared working directory (`/w/.`, `/w//`) leaves the walk readable. The walk is a relative spelling: the
94
+ * separator after the segment is taken with it, and a spelling joined under the start was relative (an absolute one is
95
+ * not joined), so the anchor step re-bases it by joining.
96
+ */
97
+ export declare function walkFromStart(base: string): string | undefined;
98
+ /** Where a segment's launcher chain runs its program, where a launcher moves the base it runs in ({@link launchedInOf}): each
99
+ * launcher's working directory, in chain order, or `unmodelled` — a move the text does not settle. A candidate's bases' own
100
+ * type: the same two answers, where a read stands. */
101
+ export type LaunchedIn = ReadCandidate["bases"];
102
+ /**
103
+ * {@link LaunchedIn} of a segment whose launcher chain moves the base (`undefined` where none does), read off the options
104
+ * the program position stepped ({@link ProgramPosition.baseMovedAt}): a value whose role is a working directory (`env -C`,
105
+ * `sudo -D`, `unshare -w`) is where that launcher runs what follows, the LAST one of a launcher's options winning (each
106
+ * implementation keeps the last before it changes directory). Any other move — a root, a program search, a directory taken
107
+ * from elsewhere (`nsenter -w` with no value), a value the text does not settle, an optional value spelled `=V` (util-linux
108
+ * 2.41 drops the `=`, getopt and util-linux 2.38 keep it: two places) — leaves it unsaid. Which word is whose option is the
109
+ * walk's reading and no other (env steps a lone `-` and reads on; a `--` ends the options).
110
+ */
111
+ export declare function launchedInOf(pos: ProgramPosition, toks: readonly Read[]): LaunchedIn | undefined;
112
+ /**
113
+ * Where a launcher chain that moves the base ({@link LaunchedIn}) puts its program, from where the command line stands
114
+ * (`bases`, or the deny floor `floor` of a walk that lost track): each launcher's working directory in turn, as the process
115
+ * `chdir()`s to it ({@link chdirFrom}). `to` is where the text the program hands a shell starts ({@link rebasePlan} moves it
116
+ * there) — `unmodelled` where the text does not say (an unsettled move, a lost walk, a spelling naming no place), `floor`
117
+ * its deny floor then; `words` is the deny floor of the segment's own relative words, which may be the launcher's (where
118
+ * the command line stands) or the program's (where the launcher put it). `undefined`: no launcher moves the base.
119
+ */
120
+ export declare function launchedAt(launchedIn: LaunchedIn | undefined, bases: ReadCandidate["bases"], floor: readonly string[] | undefined, homeDir: string | undefined): {
121
+ readonly to: ReadCandidate["bases"];
122
+ readonly floor?: readonly string[];
123
+ readonly words?: readonly string[];
124
+ } | undefined;
125
+ /**
126
+ * A nested plan (a substitution body, a here-document's substitution, a launcher's command string) was planned from
127
+ * its placeholder start ({@link nestedStartOf}); the segment it sits in may stand elsewhere (`cd sub && cat <<EOF
128
+ * $(cat secret)`), so what it derived from the start is re-based onto the ENCLOSING segment's bases (for a text a launcher
129
+ * runs in a working directory it settles, `env -C <dir>`, onto that directory): a base spelled
130
+ * from the placeholder lands under each of them, an unsettled enclosing base leaves every relative candidate
131
+ * unplaced, and every other place (an absolute candidate, a place the nested text named itself) is untouched.
132
+ * Recursive: a nested plan's own nested plans derive from the same start. A candidate left unplaced is judged where the
133
+ * text stood when it lost track (its floor, {@link ReadCandidate.floorBases}): the places the nested text derived move with
134
+ * it like its bases, an enclosing segment that lost its base itself hands on its own floor (`floor`), and a derived place
135
+ * with nowhere to land is no place (an unplaced candidate with no floor is judged at the declared working directory).
136
+ * A plan re-based onto the same place twice is one plan (a segment read in several readings hands its nested plans on alike).
137
+ */
138
+ export declare function rebasePlan(plan: ShellReadPlan, to: ReadCandidate["bases"], floor?: readonly string[]): ShellReadPlan;