@sema-agent/core 7.61.0 → 7.63.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 (298) hide show
  1. package/CHANGELOG.md +840 -0
  2. package/dist/agents/cascade.d.ts +11 -3
  3. package/dist/agents/cascade.js +1 -1
  4. package/dist/agents/peer-held-queue.d.ts +27 -4
  5. package/dist/agents/peer-held-queue.js +81 -36
  6. package/dist/agents/peer-session-drain.js +13 -3
  7. package/dist/agents/subagent-transcript-placement.d.ts +23 -0
  8. package/dist/agents/subagent-transcript-placement.js +14 -0
  9. package/dist/agents/subagent.d.ts +6 -1
  10. package/dist/agents/subagent.js +143 -58
  11. package/dist/agents/suspend-guard.d.ts +38 -16
  12. package/dist/agents/suspend-guard.js +9 -4
  13. package/dist/agents/verify.js +4 -3
  14. package/dist/brain/route-adjudicator.js +9 -4
  15. package/dist/core/approval-object.js +1 -1
  16. package/dist/core/arg-summary.js +1 -1
  17. package/dist/core/ask-question.d.ts +2 -2
  18. package/dist/core/canonical-json.d.ts +23 -13
  19. package/dist/core/canonical-json.js +4 -4
  20. package/dist/core/checkpoint-features.d.ts +722 -0
  21. package/dist/core/checkpoint-features.js +98 -0
  22. package/dist/core/checkpoint-queries.d.ts +47 -4
  23. package/dist/core/checkpoint-queries.js +36 -16
  24. package/dist/core/checkpoint-requirements.d.ts +12 -5
  25. package/dist/core/checkpoint-requirements.js +11 -5
  26. package/dist/core/checkpoint-row-verdict.d.ts +110 -0
  27. package/dist/core/checkpoint-row-verdict.js +245 -0
  28. package/dist/core/checkpoint-store.d.ts +76 -753
  29. package/dist/core/checkpoint-store.js +83 -144
  30. package/dist/core/compliance.d.ts +6 -2
  31. package/dist/core/compliance.js +3 -3
  32. package/dist/core/engine-attestation.d.ts +1 -1
  33. package/dist/core/engine-notice.d.ts +38 -7
  34. package/dist/core/engine-notice.js +9 -2
  35. package/dist/core/gate-fold.js +2 -2
  36. package/dist/core/git-worktree-env.d.ts +62 -3
  37. package/dist/core/git-worktree-env.js +91 -30
  38. package/dist/core/governance-codes.d.ts +9 -3
  39. package/dist/core/governance-codes.js +16 -3
  40. package/dist/core/hooks.d.ts +13 -0
  41. package/dist/core/human-input-projection.d.ts +1 -0
  42. package/dist/core/human-input-projection.js +3 -0
  43. package/dist/core/image-admission.d.ts +1 -1
  44. package/dist/core/locked-config.d.ts +2 -2
  45. package/dist/core/mcp-host-seat.js +6 -1
  46. package/dist/core/memory-engine/consolidation-driver.d.ts +33 -18
  47. package/dist/core/memory-engine/consolidation-driver.js +99 -98
  48. package/dist/core/memory-engine/consolidation.d.ts +73 -10
  49. package/dist/core/memory-engine/consolidation.js +167 -11
  50. package/dist/core/memory-engine/data-plane.d.ts +8 -4
  51. package/dist/core/memory-engine/data-plane.js +11 -6
  52. package/dist/core/memory-engine/delegation-settlement.d.ts +37 -35
  53. package/dist/core/memory-engine/delegation-settlement.js +53 -59
  54. package/dist/core/memory-engine/dual-root.d.ts +12 -6
  55. package/dist/core/memory-engine/dual-root.js +9 -5
  56. package/dist/core/memory-engine/engine.d.ts +98 -35
  57. package/dist/core/memory-engine/engine.js +477 -380
  58. package/dist/core/memory-engine/entry-scan.d.ts +8 -0
  59. package/dist/core/memory-engine/entry-scan.js +3 -0
  60. package/dist/core/memory-engine/file-backend.d.ts +29 -3
  61. package/dist/core/memory-engine/file-backend.js +66 -35
  62. package/dist/core/memory-engine/index.d.ts +7 -7
  63. package/dist/core/memory-engine/index.js +6 -6
  64. package/dist/core/memory-engine/landing-admission.d.ts +5 -3
  65. package/dist/core/memory-engine/landing-admission.js +3 -3
  66. package/dist/core/memory-engine/layout.d.ts +121 -45
  67. package/dist/core/memory-engine/layout.js +252 -102
  68. package/dist/core/memory-engine/memory-backend-contract.d.ts +19 -1
  69. package/dist/core/memory-engine/memory-backend-contract.js +320 -0
  70. package/dist/core/memory-engine/memory-deployment.d.ts +31 -8
  71. package/dist/core/memory-engine/memory-deployment.js +26 -12
  72. package/dist/core/memory-engine/scope-contract.d.ts +52 -11
  73. package/dist/core/memory-engine/scope-contract.js +68 -19
  74. package/dist/core/memory-engine/session-write-home.d.ts +3 -1
  75. package/dist/core/memory-engine/session-write-home.js +1 -1
  76. package/dist/core/memory-engine/sync-client.d.ts +3 -1
  77. package/dist/core/memory-engine/sync-client.js +7 -0
  78. package/dist/core/memory-engine/sync-report.d.ts +3 -2
  79. package/dist/core/memory-engine/sync-report.js +6 -2
  80. package/dist/core/memory-engine/tools.d.ts +2 -2
  81. package/dist/core/memory-engine/tools.js +10 -10
  82. package/dist/core/memory-engine/types.d.ts +118 -19
  83. package/dist/core/memory-engine/types.js +1 -0
  84. package/dist/core/memory-vector.d.ts +1 -1
  85. package/dist/core/memory.d.ts +10 -10
  86. package/dist/core/memory.js +15 -6
  87. package/dist/core/mode-policy.js +1 -1
  88. package/dist/core/mods/classic-events.d.ts +9 -1
  89. package/dist/core/mods/dollar.d.ts +32 -1
  90. package/dist/core/mods/dollar.js +13 -1
  91. package/dist/core/mods/kernel/events.d.ts +11 -3
  92. package/dist/core/mods/kernel/events.js +13 -10
  93. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  94. package/dist/core/mods/lifecycle-stations.js +44 -9
  95. package/dist/core/mods/session-append.d.ts +4 -1
  96. package/dist/core/mods/session-append.js +7 -0
  97. package/dist/core/mods/session-receive.js +12 -15
  98. package/dist/core/mods/stations.d.ts +70 -6
  99. package/dist/core/mods/stations.js +144 -1
  100. package/dist/core/own-property-receipt.d.ts +7 -0
  101. package/dist/core/own-property-receipt.js +3 -0
  102. package/dist/core/park-selfcheck.js +2 -2
  103. package/dist/core/pause-registry.d.ts +2 -0
  104. package/dist/core/pause-registry.js +3 -0
  105. package/dist/core/permission-rule-consent.d.ts +10 -3
  106. package/dist/core/permission-rule-consent.js +37 -24
  107. package/dist/core/permission-rule-store.d.ts +35 -1
  108. package/dist/core/permission-rule-store.js +27 -8
  109. package/dist/core/read-only-shell.js +3 -2
  110. package/dist/core/read-root-candidate.js +1 -1
  111. package/dist/core/redaction-marks.d.ts +8 -0
  112. package/dist/core/redaction-marks.js +6 -0
  113. package/dist/core/remote-env.d.ts +12 -1
  114. package/dist/core/remote-env.js +3 -0
  115. package/dist/core/resume-startup-cause.d.ts +5 -4
  116. package/dist/core/runner/child-tree.d.ts +29 -3
  117. package/dist/core/runner/child-tree.js +39 -16
  118. package/dist/core/runner/compact-session.js +5 -2
  119. package/dist/core/runner/contracts.d.ts +36 -17
  120. package/dist/core/runner/delegation-owner.d.ts +43 -0
  121. package/dist/core/runner/delegation-owner.js +59 -0
  122. package/dist/core/runner/gate-exit.js +2 -2
  123. package/dist/core/runner/inherited-ask-grants.js +1 -1
  124. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  125. package/dist/core/runner/lineage-reroot-view.js +108 -0
  126. package/dist/core/runner/memory-consolidation-driver.d.ts +6 -3
  127. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  128. package/dist/core/runner/memory-consolidation-write-judge.d.ts +2 -1
  129. package/dist/core/runner/memory-consolidation-write-judge.js +3 -2
  130. package/dist/core/runner/permission-rule-lanes.d.ts +2 -1
  131. package/dist/core/runner/permission-rule-lanes.js +2 -2
  132. package/dist/core/runner/person-path-rows.d.ts +23 -3
  133. package/dist/core/runner/person-path-rows.js +31 -4
  134. package/dist/core/runner/placement-fence.d.ts +12 -0
  135. package/dist/core/runner/placement-fence.js +20 -6
  136. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  137. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  138. package/dist/core/runner/prepare-ask-lane.js +2 -2
  139. package/dist/core/runner/prepare-caps-and-workflow.d.ts +5 -1
  140. package/dist/core/runner/prepare-caps-and-workflow.js +6 -3
  141. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  142. package/dist/core/runner/prepare-config-doors.js +3 -4
  143. package/dist/core/runner/prepare-execution-env.js +17 -6
  144. package/dist/core/runner/prepare-hands-readface.d.ts +3 -2
  145. package/dist/core/runner/prepare-hands-readface.js +32 -10
  146. package/dist/core/runner/prepare-inherited-gate.d.ts +12 -8
  147. package/dist/core/runner/prepare-inherited-gate.js +14 -6
  148. package/dist/core/runner/prepare-memory-engine-session.d.ts +2 -4
  149. package/dist/core/runner/prepare-memory-engine-session.js +4 -4
  150. package/dist/core/runner/prepare-memory.d.ts +3 -2
  151. package/dist/core/runner/prepare-memory.js +28 -20
  152. package/dist/core/runner/prepare-park-ask.js +4 -3
  153. package/dist/core/runner/prepare-task.js +22 -16
  154. package/dist/core/runner/prepare-workspace-restore.js +3 -6
  155. package/dist/core/runner/resume-admission.d.ts +3 -3
  156. package/dist/core/runner/resume-admission.js +6 -3
  157. package/dist/core/runner/resume-apply.d.ts +4 -0
  158. package/dist/core/runner/resume-apply.js +11 -4
  159. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  160. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  161. package/dist/core/runner/run-git-lane.d.ts +2 -0
  162. package/dist/core/runner/run-git-lane.js +4 -1
  163. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  164. package/dist/core/runner/run-harness-handlers.js +3 -2
  165. package/dist/core/runner/run-leg.js +25 -8
  166. package/dist/core/runner/run-settle-and-teardown.js +6 -4
  167. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  168. package/dist/core/runner/run-turn-boundary.js +7 -4
  169. package/dist/core/runner/runtask.js +6 -6
  170. package/dist/core/runner/steering-preview.d.ts +9 -0
  171. package/dist/core/runner/steering-preview.js +5 -0
  172. package/dist/core/runner/stream-steer-verb.js +8 -0
  173. package/dist/core/runner/terminal-account.js +1 -1
  174. package/dist/core/runner/tool-face-overlay.js +2 -0
  175. package/dist/core/runner/turn-attachments.d.ts +5 -0
  176. package/dist/core/runner/turn-attachments.js +1 -1
  177. package/dist/core/runner-deps.d.ts +8 -4
  178. package/dist/core/secret-env.d.ts +9 -6
  179. package/dist/core/secret-env.js +41 -22
  180. package/dist/core/session-checkout.d.ts +108 -0
  181. package/dist/core/session-checkout.js +485 -0
  182. package/dist/core/session-store.d.ts +13 -5
  183. package/dist/core/session-store.js +28 -4
  184. package/dist/core/session.d.ts +29 -5
  185. package/dist/core/session.js +3 -0
  186. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +6 -12
  187. package/dist/core/store-contracts/checkpoint-store-contract.js +73 -6
  188. package/dist/core/store-contracts/session-store-contract.js +61 -8
  189. package/dist/core/task-event.d.ts +28 -1
  190. package/dist/core/task-notification.d.ts +9 -1
  191. package/dist/core/task-notification.js +8 -1
  192. package/dist/core/task-registry-agent.d.ts +40 -8
  193. package/dist/core/task-registry-agent.js +57 -24
  194. package/dist/core/task-registry-shared.d.ts +33 -11
  195. package/dist/core/task-registry-workflow.js +4 -3
  196. package/dist/core/task-registry.d.ts +27 -10
  197. package/dist/core/task-registry.js +19 -13
  198. package/dist/core/task-result.d.ts +5 -5
  199. package/dist/core/task-spec-members.js +1 -1
  200. package/dist/core/task-spec.d.ts +21 -1
  201. package/dist/core/terminal-cause.d.ts +6 -6
  202. package/dist/core/tool-face.d.ts +6 -2
  203. package/dist/core/tool-face.js +1 -1
  204. package/dist/core/tool-policy.d.ts +16 -13
  205. package/dist/core/tool-policy.js +11 -10
  206. package/dist/core/tool-roster.d.ts +4 -4
  207. package/dist/core/tool-spec.d.ts +42 -19
  208. package/dist/core/types.d.ts +2 -2
  209. package/dist/core/types.js +1 -1
  210. package/dist/core/untrusted-egress.d.ts +15 -4
  211. package/dist/core/untrusted-egress.js +23 -22
  212. package/dist/core/workspace-snapshot.d.ts +3 -1
  213. package/dist/core/workspace-snapshot.js +1 -0
  214. package/dist/engine/execution-env/node-execution-env.d.ts +3 -0
  215. package/dist/engine/execution-env/node-execution-env.js +12 -5
  216. package/dist/engine/harness/types.d.ts +77 -1
  217. package/dist/engine/harness/types.js +108 -0
  218. package/dist/engine/session/import-validate.js +6 -1
  219. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  220. package/dist/engine/session/parent-chain-guard.js +1 -1
  221. package/dist/engine/session/path-to-root.d.ts +18 -3
  222. package/dist/engine/session/path-to-root.js +15 -1
  223. package/dist/engine/session/repo-utils.d.ts +12 -1
  224. package/dist/engine/session/repo-utils.js +41 -0
  225. package/dist/engine/session/session.d.ts +24 -1
  226. package/dist/engine/session/session.js +46 -2
  227. package/dist/engine/session/storage-base.d.ts +20 -0
  228. package/dist/engine/session/storage-base.js +28 -9
  229. package/dist/index.d.ts +16 -12
  230. package/dist/index.js +11 -8
  231. package/dist/internal/harness-types.d.ts +1 -1
  232. package/dist/internal/harness.d.ts +4 -3
  233. package/dist/internal/harness.js +3 -2
  234. package/dist/orchestration/run-workflow-tool.d.ts +7 -1
  235. package/dist/orchestration/run-workflow-tool.js +28 -11
  236. package/dist/orchestration/workflow-governance.d.ts +1 -1
  237. package/dist/orchestration/workflow.d.ts +6 -0
  238. package/dist/orchestration/workflow.js +5 -8
  239. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  240. package/dist/stores/file/checkpoint-store.js +7 -6
  241. package/dist/stores/file/fs-atomic.d.ts +0 -22
  242. package/dist/stores/file/fs-atomic.js +0 -17
  243. package/dist/stores/file/index.d.ts +2 -9
  244. package/dist/stores/file/index.js +2 -4
  245. package/dist/stores/file/session-store.d.ts +13 -7
  246. package/dist/stores/file/session-store.js +42 -18
  247. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  248. package/dist/tools/fs/bash-program-position.js +10 -10
  249. package/dist/tools/fs/program-read-model.d.ts +34 -10
  250. package/dist/tools/fs/program-read-model.js +37 -7
  251. package/dist/tools/fs/program-read-model.rows.js +13 -2
  252. package/dist/tools/fs/read-deny.d.ts +13 -1
  253. package/dist/tools/fs/read-deny.js +10 -2
  254. package/dist/tools/fs/removal-targets.js +5 -5
  255. package/dist/tools/fs/safety.d.ts +2 -0
  256. package/dist/tools/fs/safety.js +1 -1
  257. package/dist/tools/fs/shell-read-argv.d.ts +11 -2
  258. package/dist/tools/fs/shell-read-argv.js +45 -29
  259. package/dist/tools/fs/shell-read-bindings.d.ts +20 -2
  260. package/dist/tools/fs/shell-read-bindings.js +153 -69
  261. package/dist/tools/fs/shell-read-brace.d.ts +18 -0
  262. package/dist/tools/fs/shell-read-brace.js +79 -0
  263. package/dist/tools/fs/shell-read-check.js +29 -11
  264. package/dist/tools/fs/shell-read-establish.js +43 -22
  265. package/dist/tools/fs/shell-read-functions.js +2 -2
  266. package/dist/tools/fs/shell-read-judge.d.ts +11 -0
  267. package/dist/tools/fs/shell-read-judge.js +3 -3
  268. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  269. package/dist/tools/fs/shell-read-object-path.js +119 -0
  270. package/dist/tools/fs/shell-read-plan.d.ts +18 -0
  271. package/dist/tools/fs/shell-read-plan.js +217 -104
  272. package/dist/tools/fs/shell-read-start.d.ts +76 -13
  273. package/dist/tools/fs/shell-read-start.js +97 -17
  274. package/dist/tools/fs/shell-read-word.d.ts +10 -0
  275. package/dist/tools/fs/shell-read-word.js +9 -5
  276. package/dist/tools/fs/shell-read-workdir.d.ts +54 -14
  277. package/dist/tools/fs/shell-read-workdir.js +103 -19
  278. package/dist/tools/fs/shell-read-write-targets.js +13 -8
  279. package/dist/tools/worktree.d.ts +3 -2
  280. package/dist/tools/worktree.js +7 -35
  281. package/package.json +3 -2
  282. package/test/export-surface.snapshot.json +93 -43
  283. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  284. package/wire-changes/core-stores-sql@7.63.0.json +30 -0
  285. package/wire-changes/core@7.62.0.json +2181 -0
  286. package/wire-changes/core@7.63.0.json +3523 -0
  287. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  288. package/wire-changes/mods-kernel@7.63.0.json +30 -0
  289. package/wire-changes/primitives@7.62.0.json +30 -0
  290. package/wire-changes/primitives@7.63.0.json +445 -0
  291. package/dist/core/consolidate-scope.d.ts +0 -93
  292. package/dist/core/consolidate-scope.js +0 -98
  293. package/dist/core/credential-vocabulary.d.ts +0 -176
  294. package/dist/core/credential-vocabulary.js +0 -190
  295. package/dist/core/redaction-passes.d.ts +0 -82
  296. package/dist/core/redaction-passes.js +0 -377
  297. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  298. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -1,6 +1,6 @@
1
1
  import { lexShell, literalTextOf } from "../../shell/lex.js";
2
2
  import { readProgramPosition } from "./bash-program-position.js";
3
- import { SPECIAL_BUILTINS, projectSegment } from "./shell-read-bindings.js";
3
+ import { SPECIAL_BUILTINS, projectSegments } from "./shell-read-bindings.js";
4
4
  import { reentryText } from "./shell-reentry-text.js";
5
5
  export function functionCallOf(argv, functions, stateOf = () => "maybe") {
6
6
  const pos = readProgramPosition(argv);
@@ -23,7 +23,7 @@ export function evalDefinedFunctions(argvs, depth = 0) {
23
23
  const lexed = words.length > 0 && words.every((t) => t !== undefined) ? lexShell(reentryText("eval", words) ?? "") : undefined;
24
24
  if (lexed === undefined || "parseFailure" in lexed)
25
25
  return [];
26
- const inner = lexed.segments.map((segment) => projectSegment(segment));
26
+ const inner = projectSegments(lexed.segments);
27
27
  return [...inner.flatMap((p) => p.defines), ...evalDefinedFunctions(inner.map((p) => p.argv), depth + 1)];
28
28
  });
29
29
  }
@@ -198,6 +198,9 @@ export interface ShellReadBoundary extends BashReadonlyRootBoundary {
198
198
  /** The deny table's WRITE face (`compileWriteDeny`, read-deny.ts): judges a command's write targets (candidates marked
199
199
  * `face: "write"`) and returns the matched row's rule, or null. PRESENT-IFF there is something to judge. */
200
200
  readonly writeDenyMatch?: (resolvedPath: string) => string | null;
201
+ /** Does the row `writeDenyMatch` named (its rule) guard the READ face too — a `Read(…)` rule on the write face
202
+ * ({@link import("./read-deny.js").WriteDenyMatcher.guardsReads})? Read once per hit, so the refusal says which family refused. */
203
+ readonly writeDenyGuardsReads?: (pattern: string) => boolean;
201
204
  /** The read table's rows AT or BELOW a path (`readDenySeat`'s `denyAtOrBelow`, read-deny.ts): read by the station's
202
205
  * `writesPlaced` fact only, through {@link denyRowAtOrBelow}. */
203
206
  readonly denyAtOrBelow?: (resolvedPath: string) => string | null;
@@ -254,6 +257,13 @@ export interface EstablishedRead {
254
257
  * and the lexical one, read through the same chain reader. Deny views only: not a spelling the
255
258
  * command wrote, not a containment candidate, not a write view of its own. Absent ⇒ none read. */
256
259
  readonly hops?: readonly string[];
260
+ /** Beside an unplaced read whose start may be any directory at or above its floor — a word made from a directory the text
261
+ * does not know ({@link ReadCandidate.unsettledStart}), an object path relative to a repository top it does not settle
262
+ * ({@link ReadCandidate.repositoryTop}) —: the spelling at each directory above the floor. Views of the word itself, met by
263
+ * the deny rows' match and by nothing else: not where the text stood (that is {@link spellings}, which the removal guard
264
+ * judges), not a containment candidate, and not a place a row may lie below (a recursive read's root, a moved or copied
265
+ * target) — each reaches `/`, below which every row lies. Absent ⇒ none. */
266
+ readonly ancestorViews?: readonly string[];
257
267
  /** The pattern or traversal root an `expansion` came from, as folded. */
258
268
  readonly origin?: string;
259
269
  /** What the environment said the target IS, where a read asked — only a traversal root asks (it lists the root
@@ -287,6 +297,7 @@ export interface ReadFinding {
287
297
  readonly pattern: string;
288
298
  readonly matchedView: string;
289
299
  readonly face?: "write";
300
+ readonly readRow?: true;
290
301
  };
291
302
  readonly containment: "inside" | "outside" | "open" | "unknown";
292
303
  }
@@ -46,16 +46,16 @@ 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, ...(read.hops ?? [])];
49
+ const views = [...(read.target !== undefined ? [read.target] : []), ...read.spellings, ...(read.ancestorViews ?? []), ...(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);
53
53
  if (pattern !== null)
54
- return { read, kind: "deny_hit", deny: { pattern, matchedView: folded, ...(writeTarget ? { face: "write" } : {}) }, containment: writeTarget ? writeContainmentOf(read, boundary) : containmentOf(read, boundary) };
54
+ return { read, kind: "deny_hit", deny: { pattern, matchedView: folded, ...(writeTarget ? { face: "write", ...(boundary.writeDenyGuardsReads?.(pattern) === true ? { readRow: true } : {}) } : {}) }, containment: writeTarget ? writeContainmentOf(read, boundary) : containmentOf(read, boundary) };
55
55
  }
56
56
  if (!writeTarget && read.candidate.provenance === "traversal_root" && boundary.denyUnder !== undefined) {
57
57
  let unplaced;
58
- for (const view of views) {
58
+ for (const view of [...(read.target !== undefined ? [read.target] : []), ...read.spellings, ...(read.hops ?? [])]) {
59
59
  const folded = normalizeAbsPathLexically(view);
60
60
  const under = boundary.denyUnder(folded);
61
61
  if (typeof under === "string")
@@ -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,16 @@ 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 beside `bases: "unmodelled"`: the text makes this word from a directory it does not know — a launcher's working
79
+ * directory value or a `cd` target the shell computes (a substitution, a name, a pattern) —, one that may be anywhere at
80
+ * or above where the text stood. The deny rows' match meets the spelling at every directory at or above its floor
81
+ * ({@link floorBases}), as it meets a word relative to a repository top the text does not settle; the floor itself stays
82
+ * where the text stood, and is where a row below the word (a recursive read's root) is looked for. */
83
+ readonly unsettledStart?: true;
84
+ /** Only on an object path relative to its repository's top (shell-read-object-path.ts): `bases` / `floorBases` are where
85
+ * git starts, the top one of them or above — the one discovery finds (`discovered`, read where a filesystem answers),
86
+ * else any: every ancestor meets the deny rows. */
87
+ readonly repositoryTop?: RepositoryTop;
74
88
  /** 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
89
  * program may expand itself): spelled with the DECLARED home. The judge reads it for deny rows ONLY. */
76
90
  readonly floorSpelled?: string;
@@ -135,6 +149,10 @@ export interface ShellReadSegment {
135
149
  /** The working directories this segment may be standing in (what every relative candidate's `bases` is), or
136
150
  * `"unmodelled"` when the text does not settle it. */
137
151
  readonly bases: readonly string[] | "unmodelled";
152
+ /** The directory the segment's PROGRAM starts in, as the candidate `.` placed where the program's relative words are: where
153
+ * the command line stands, or where a launcher moved it (`env -C <dir>` — its deny floor both places). Set on every segment
154
+ * the planner makes; a segment without it names no place its program starts in. */
155
+ readonly programStart?: ReadCandidate;
138
156
  /** Substitution bodies, unquoted here-document substitutions, and re-entered shell text, each its own plan. */
139
157
  readonly nested: readonly ShellReadPlan[];
140
158
  /** Texts a literal printer's words say this segment's shell is fed (a pipe's producer, the body of a `<(…)` script file or