@sema-agent/core 7.62.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 (193) hide show
  1. package/CHANGELOG.md +528 -0
  2. package/dist/agents/subagent-transcript-placement.d.ts +23 -0
  3. package/dist/agents/subagent-transcript-placement.js +14 -0
  4. package/dist/agents/subagent.js +82 -51
  5. package/dist/brain/route-adjudicator.js +9 -4
  6. package/dist/core/approval-object.js +1 -1
  7. package/dist/core/arg-summary.js +1 -1
  8. package/dist/core/ask-question.d.ts +2 -2
  9. package/dist/core/canonical-json.d.ts +23 -13
  10. package/dist/core/canonical-json.js +4 -4
  11. package/dist/core/checkpoint-queries.d.ts +47 -4
  12. package/dist/core/checkpoint-queries.js +36 -16
  13. package/dist/core/checkpoint-requirements.d.ts +3 -3
  14. package/dist/core/checkpoint-requirements.js +2 -1
  15. package/dist/core/checkpoint-row-verdict.d.ts +15 -4
  16. package/dist/core/checkpoint-row-verdict.js +22 -2
  17. package/dist/core/checkpoint-store.d.ts +23 -10
  18. package/dist/core/checkpoint-store.js +45 -4
  19. package/dist/core/compliance.d.ts +6 -2
  20. package/dist/core/compliance.js +3 -3
  21. package/dist/core/engine-attestation.d.ts +1 -1
  22. package/dist/core/engine-notice.d.ts +19 -4
  23. package/dist/core/git-worktree-env.d.ts +62 -3
  24. package/dist/core/git-worktree-env.js +91 -30
  25. package/dist/core/governance-codes.d.ts +7 -3
  26. package/dist/core/governance-codes.js +13 -3
  27. package/dist/core/memory-engine/consolidation-driver.d.ts +32 -17
  28. package/dist/core/memory-engine/consolidation-driver.js +99 -98
  29. package/dist/core/memory-engine/consolidation.d.ts +73 -10
  30. package/dist/core/memory-engine/consolidation.js +167 -11
  31. package/dist/core/memory-engine/data-plane.d.ts +8 -4
  32. package/dist/core/memory-engine/data-plane.js +11 -6
  33. package/dist/core/memory-engine/delegation-settlement.d.ts +37 -35
  34. package/dist/core/memory-engine/delegation-settlement.js +53 -59
  35. package/dist/core/memory-engine/dual-root.d.ts +12 -6
  36. package/dist/core/memory-engine/dual-root.js +9 -5
  37. package/dist/core/memory-engine/engine.d.ts +98 -35
  38. package/dist/core/memory-engine/engine.js +477 -380
  39. package/dist/core/memory-engine/entry-scan.d.ts +8 -0
  40. package/dist/core/memory-engine/entry-scan.js +3 -0
  41. package/dist/core/memory-engine/file-backend.d.ts +29 -3
  42. package/dist/core/memory-engine/file-backend.js +66 -35
  43. package/dist/core/memory-engine/index.d.ts +7 -7
  44. package/dist/core/memory-engine/index.js +6 -6
  45. package/dist/core/memory-engine/landing-admission.d.ts +5 -3
  46. package/dist/core/memory-engine/landing-admission.js +3 -3
  47. package/dist/core/memory-engine/layout.d.ts +121 -45
  48. package/dist/core/memory-engine/layout.js +252 -102
  49. package/dist/core/memory-engine/memory-backend-contract.d.ts +19 -1
  50. package/dist/core/memory-engine/memory-backend-contract.js +320 -0
  51. package/dist/core/memory-engine/memory-deployment.d.ts +31 -8
  52. package/dist/core/memory-engine/memory-deployment.js +26 -12
  53. package/dist/core/memory-engine/scope-contract.d.ts +52 -11
  54. package/dist/core/memory-engine/scope-contract.js +68 -19
  55. package/dist/core/memory-engine/session-write-home.d.ts +3 -1
  56. package/dist/core/memory-engine/session-write-home.js +1 -1
  57. package/dist/core/memory-engine/sync-client.d.ts +3 -1
  58. package/dist/core/memory-engine/sync-client.js +7 -0
  59. package/dist/core/memory-engine/sync-report.d.ts +3 -2
  60. package/dist/core/memory-engine/sync-report.js +6 -2
  61. package/dist/core/memory-engine/tools.d.ts +2 -2
  62. package/dist/core/memory-engine/tools.js +10 -10
  63. package/dist/core/memory-engine/types.d.ts +118 -19
  64. package/dist/core/memory-engine/types.js +1 -0
  65. package/dist/core/memory.js +15 -6
  66. package/dist/core/mods/stations.d.ts +20 -1
  67. package/dist/core/mods/stations.js +21 -2
  68. package/dist/core/park-selfcheck.js +2 -2
  69. package/dist/core/pause-registry.d.ts +2 -0
  70. package/dist/core/pause-registry.js +3 -0
  71. package/dist/core/permission-rule-consent.d.ts +10 -3
  72. package/dist/core/permission-rule-consent.js +37 -24
  73. package/dist/core/permission-rule-store.d.ts +35 -1
  74. package/dist/core/permission-rule-store.js +27 -8
  75. package/dist/core/read-only-shell.js +3 -2
  76. package/dist/core/redaction-marks.d.ts +8 -0
  77. package/dist/core/redaction-marks.js +6 -0
  78. package/dist/core/remote-env.d.ts +12 -1
  79. package/dist/core/remote-env.js +3 -0
  80. package/dist/core/runner/child-tree.d.ts +29 -3
  81. package/dist/core/runner/child-tree.js +39 -16
  82. package/dist/core/runner/contracts.d.ts +18 -9
  83. package/dist/core/runner/gate-exit.js +2 -2
  84. package/dist/core/runner/inherited-ask-grants.js +1 -1
  85. package/dist/core/runner/memory-consolidation-driver.d.ts +6 -3
  86. package/dist/core/runner/memory-consolidation-driver.js +4 -4
  87. package/dist/core/runner/memory-consolidation-write-judge.d.ts +2 -1
  88. package/dist/core/runner/memory-consolidation-write-judge.js +3 -2
  89. package/dist/core/runner/person-path-rows.d.ts +8 -3
  90. package/dist/core/runner/person-path-rows.js +5 -1
  91. package/dist/core/runner/placement-fence.d.ts +12 -0
  92. package/dist/core/runner/placement-fence.js +20 -6
  93. package/dist/core/runner/prepare-ask-lane.js +2 -2
  94. package/dist/core/runner/prepare-caps-and-workflow.d.ts +4 -1
  95. package/dist/core/runner/prepare-caps-and-workflow.js +5 -2
  96. package/dist/core/runner/prepare-execution-env.js +17 -6
  97. package/dist/core/runner/prepare-hands-readface.d.ts +2 -1
  98. package/dist/core/runner/prepare-hands-readface.js +4 -3
  99. package/dist/core/runner/prepare-inherited-gate.d.ts +10 -8
  100. package/dist/core/runner/prepare-inherited-gate.js +8 -4
  101. package/dist/core/runner/prepare-memory-engine-session.d.ts +2 -4
  102. package/dist/core/runner/prepare-memory-engine-session.js +4 -4
  103. package/dist/core/runner/prepare-memory.d.ts +3 -2
  104. package/dist/core/runner/prepare-memory.js +28 -20
  105. package/dist/core/runner/prepare-park-ask.js +4 -3
  106. package/dist/core/runner/prepare-task.js +15 -12
  107. package/dist/core/runner/prepare-workspace-restore.js +3 -6
  108. package/dist/core/runner/run-leg.js +1 -1
  109. package/dist/core/runner/run-settle-and-teardown.js +3 -2
  110. package/dist/core/runner/terminal-account.js +1 -1
  111. package/dist/core/runner-deps.d.ts +6 -2
  112. package/dist/core/secret-env.d.ts +1 -1
  113. package/dist/core/secret-env.js +4 -4
  114. package/dist/core/session-checkout.d.ts +108 -0
  115. package/dist/core/session-checkout.js +485 -0
  116. package/dist/core/session-store.d.ts +12 -4
  117. package/dist/core/session-store.js +23 -3
  118. package/dist/core/session.d.ts +16 -2
  119. package/dist/core/session.js +3 -0
  120. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +0 -12
  121. package/dist/core/store-contracts/checkpoint-store-contract.js +6 -7
  122. package/dist/core/store-contracts/session-store-contract.js +39 -0
  123. package/dist/core/task-event.d.ts +21 -0
  124. package/dist/core/task-notification.d.ts +9 -1
  125. package/dist/core/task-notification.js +6 -0
  126. package/dist/core/task-registry-agent.d.ts +14 -2
  127. package/dist/core/task-registry-agent.js +45 -19
  128. package/dist/core/task-registry-shared.d.ts +26 -11
  129. package/dist/core/task-registry.d.ts +15 -9
  130. package/dist/core/task-registry.js +9 -10
  131. package/dist/core/task-spec-members.js +1 -1
  132. package/dist/core/task-spec.d.ts +20 -0
  133. package/dist/core/tool-policy.d.ts +14 -12
  134. package/dist/core/tool-policy.js +11 -10
  135. package/dist/core/tool-spec.d.ts +38 -19
  136. package/dist/core/types.d.ts +1 -1
  137. package/dist/core/untrusted-egress.d.ts +15 -4
  138. package/dist/core/untrusted-egress.js +23 -22
  139. package/dist/core/workspace-snapshot.d.ts +3 -1
  140. package/dist/core/workspace-snapshot.js +1 -0
  141. package/dist/engine/harness/types.d.ts +66 -1
  142. package/dist/engine/harness/types.js +108 -0
  143. package/dist/engine/session/import-validate.js +6 -1
  144. package/dist/engine/session/session.d.ts +24 -1
  145. package/dist/engine/session/session.js +45 -1
  146. package/dist/index.d.ts +7 -4
  147. package/dist/index.js +7 -4
  148. package/dist/internal/harness-types.d.ts +1 -1
  149. package/dist/orchestration/run-workflow-tool.d.ts +4 -1
  150. package/dist/orchestration/run-workflow-tool.js +1 -0
  151. package/dist/orchestration/workflow.d.ts +3 -0
  152. package/dist/orchestration/workflow.js +3 -1
  153. package/dist/stores/file/session-store.js +2 -1
  154. package/dist/tools/fs/bash-program-position.js +3 -3
  155. package/dist/tools/fs/program-read-model.d.ts +34 -10
  156. package/dist/tools/fs/program-read-model.js +37 -7
  157. package/dist/tools/fs/program-read-model.rows.js +13 -2
  158. package/dist/tools/fs/read-deny.d.ts +13 -1
  159. package/dist/tools/fs/read-deny.js +10 -2
  160. package/dist/tools/fs/removal-targets.js +3 -3
  161. package/dist/tools/fs/safety.d.ts +2 -0
  162. package/dist/tools/fs/safety.js +1 -1
  163. package/dist/tools/fs/shell-read-argv.d.ts +8 -1
  164. package/dist/tools/fs/shell-read-argv.js +34 -29
  165. package/dist/tools/fs/shell-read-bindings.d.ts +2 -0
  166. package/dist/tools/fs/shell-read-bindings.js +5 -1
  167. package/dist/tools/fs/shell-read-brace.d.ts +18 -0
  168. package/dist/tools/fs/shell-read-brace.js +79 -0
  169. package/dist/tools/fs/shell-read-check.js +10 -8
  170. package/dist/tools/fs/shell-read-establish.js +23 -16
  171. package/dist/tools/fs/shell-read-judge.d.ts +11 -0
  172. package/dist/tools/fs/shell-read-judge.js +3 -3
  173. package/dist/tools/fs/shell-read-plan.d.ts +10 -0
  174. package/dist/tools/fs/shell-read-plan.js +189 -93
  175. package/dist/tools/fs/shell-read-start.d.ts +19 -9
  176. package/dist/tools/fs/shell-read-start.js +20 -12
  177. package/dist/tools/fs/shell-read-word.d.ts +10 -0
  178. package/dist/tools/fs/shell-read-word.js +9 -5
  179. package/dist/tools/fs/shell-read-workdir.d.ts +26 -7
  180. package/dist/tools/fs/shell-read-workdir.js +73 -12
  181. package/dist/tools/fs/shell-read-write-targets.js +13 -8
  182. package/dist/tools/worktree.d.ts +3 -2
  183. package/dist/tools/worktree.js +7 -35
  184. package/package.json +3 -2
  185. package/test/export-surface.snapshot.json +73 -11
  186. package/wire-changes/core-stores-sql@7.63.0.json +30 -0
  187. package/wire-changes/core@7.63.0.json +3523 -0
  188. package/wire-changes/mods-kernel@7.63.0.json +30 -0
  189. package/wire-changes/primitives@7.63.0.json +445 -0
  190. package/dist/core/credential-vocabulary.d.ts +0 -176
  191. package/dist/core/credential-vocabulary.js +0 -190
  192. package/dist/core/redaction-passes.d.ts +0 -82
  193. package/dist/core/redaction-passes.js +0 -377
@@ -150,12 +150,13 @@ function denyTargetViews(canonicalKey, lexicalView, opts) {
150
150
  }
151
151
  export function compileWriteDeny(rules = []) {
152
152
  const ruleRows = rules.filter((r) => r.faces.includes("write"));
153
+ const readRows = new Set(ruleRows.filter((r) => r.faces.includes("read")).map((r) => r.rule));
153
154
  const rows = ruleRows.map(ruleGuardRow);
154
155
  const matchPath = (path) => {
155
156
  const hit = denyTableHit(rows, { views: [{ path, kind: "lexical" }] });
156
157
  return hit === null ? null : { pattern: hit.pattern };
157
158
  };
158
- return { face: "write", ruleRows, matchPath, matchTarget: (canonicalKey, lexicalView, opts) => denyTableHit(rows, denyTargetViews(canonicalKey, lexicalView, opts)) };
159
+ return { face: "write", ruleRows, matchPath, matchTarget: (canonicalKey, lexicalView, opts) => denyTableHit(rows, denyTargetViews(canonicalKey, lexicalView, opts)), guardsReads: (pattern) => readRows.has(pattern) };
159
160
  }
160
161
  export function seatForCall(seat, toolCallId) {
161
162
  const forCall = seat?.forCall;
@@ -185,12 +186,19 @@ export function sensitivePathDenyList(pattern, face = "read") {
185
186
  }
186
187
  export const SENSITIVE_PATH_DENY_SCOPE = "This list guards credential-class paths and applies regardless of the containment roots.";
187
188
  export const WRITE_DENY_SCOPE = "A write deny row holds regardless of the containment roots and of the permission mode.";
189
+ export const READ_ROW_WRITE_SCOPE = "A read deny row holds on writes too, regardless of the containment roots and of the permission mode.";
188
190
  export function readDenySentence(finding) {
189
191
  const write = finding.face === "write";
190
192
  const canonicalNote = finding.canonical !== undefined && finding.canonical !== finding.target ? `(canonical target: "${fitMiddle(finding.canonical, READ_DENY_SENTENCE_PART_MAX)}") ` : "";
191
193
  const lexicalHit = finding.matchedView !== undefined && finding.matchedView !== (finding.canonical ?? finding.target);
194
+ const frame = `${finding.action ?? (write ? "writing" : "reading")} "${fitMiddle(finding.target, READ_DENY_SENTENCE_PART_MAX)}" ${canonicalNote}is refused:`;
195
+ const pattern = fitMiddle(finding.pattern, READ_DENY_SENTENCE_PART_MAX);
196
+ if (write && finding.readRow === true) {
197
+ const reaches = lexicalHit ? `the path passes through "${fitMiddle(finding.matchedView, READ_DENY_SENTENCE_PART_MAX)}", which the read deny row "${pattern}" denies reading` : `the target is a path the read deny row "${pattern}" denies reading`;
198
+ return `${frame} ${reaches} — a path whose reads are denied is not written either. ${READ_ROW_WRITE_SCOPE}`;
199
+ }
192
200
  const judged = lexicalHit ? `the requested path's spelling ("${fitMiddle(finding.matchedView, READ_DENY_SENTENCE_PART_MAX)}") matches` : "the target matches";
193
- return `${finding.action ?? (write ? "writing" : "reading")} "${fitMiddle(finding.target, READ_DENY_SENTENCE_PART_MAX)}" ${canonicalNote}is refused: ${judged} ${sensitivePathDenyList(fitMiddle(finding.pattern, READ_DENY_SENTENCE_PART_MAX), write ? "write" : "read")}. ${write ? WRITE_DENY_SCOPE : SENSITIVE_PATH_DENY_SCOPE}`;
201
+ return `${frame} ${judged} ${sensitivePathDenyList(pattern, write ? "write" : "read")}. ${write ? WRITE_DENY_SCOPE : SENSITIVE_PATH_DENY_SCOPE}`;
194
202
  }
195
203
  export const READ_DENY_SENTENCE_PART_MAX = PROBE_REASON_MAX;
196
204
  export function fitMiddle(s, budget) {
@@ -105,7 +105,7 @@ export function removalFindingsOf(established, seat, safeRoots = KNOWN_SAFE_ROOT
105
105
  const removed = new Set(writeReadings(row, spelled).flatMap((r) => r.written.map((w) => w.at)));
106
106
  const options = new Set(args.filter((_, at) => !removed.has(at)).map((w) => w.raw));
107
107
  const forced = selectsOptions(row, spelled, received.shellChooses, TRAVERSAL, FORCED);
108
- const rm = removal.program === "rm" || !named ? { recursive: selectsOptions(row, spelled, received.shellChooses, TRAVERSAL) } : undefined;
108
+ const rm = row.key === "rm" || !named ? { recursive: selectsOptions(row, spelled, received.shellChooses, TRAVERSAL) } : undefined;
109
109
  if (forced && segment.reentry === "argv")
110
110
  out.push({ guard: "unverifiable_delete", program: removal.program, operand: segment.text.trim(), source: "stream" });
111
111
  const relocated = enclosingRelocated || readProgramPosition(segment.argv).baseMovedAt.length > 0;
@@ -181,8 +181,8 @@ const programNameUnsettled = (s) => s.verb !== undefined && s.reads.some((c) =>
181
181
  const RM_REMOVAL_ROW = programRow("rm");
182
182
  function removalProgramOf(s) {
183
183
  const basename = s.verb?.basename;
184
- const row = basename !== undefined && REMOVAL_COMMAND_SET.has(basename) ? programRow(basename) : undefined;
185
- if (row !== undefined)
184
+ const row = basename !== undefined ? programRow(basename) : undefined;
185
+ if (row !== undefined && REMOVAL_COMMAND_SET.has(row.key))
186
186
  return { program: basename, row, named: true };
187
187
  return programNameUnsettled(s) && RM_REMOVAL_ROW !== undefined ? { program: s.verb.name, row: RM_REMOVAL_ROW, named: false } : undefined;
188
188
  }
@@ -447,6 +447,8 @@ export declare function resolveKey(env: ExecutionEnv, rootCanonical: string, pat
447
447
  pattern: string;
448
448
  matchedView?: string;
449
449
  } | null;
450
+ /** The write face's {@link import("./read-deny.js").WriteDenyMatcher.guardsReads}: the row a hit named also guards reads. */
451
+ guardsReads?(pattern: string): boolean;
450
452
  }, containmentFace?: "open" | "roots"): Promise<{
451
453
  ok: true;
452
454
  key: string;
@@ -470,7 +470,7 @@ export async function resolveKey(env, rootCanonical, path, signal, baseCwd, addi
470
470
  ok: false,
471
471
  violation: {
472
472
  code: write ? "write_path_denied" : "read_path_denied",
473
- message: readDenySentence({ target: path, canonical: key, pattern: hit.pattern, ...(hit.matchedView !== undefined ? { matchedView: hit.matchedView } : {}), ...(write ? { face: "write" } : {}) }),
473
+ message: readDenySentence({ target: path, canonical: key, pattern: hit.pattern, ...(hit.matchedView !== undefined ? { matchedView: hit.matchedView } : {}), ...(write ? { face: "write", ...(readDeny.guardsReads?.(hit.pattern) === true ? { readRow: true } : {}) } : {}) }),
474
474
  target: key,
475
475
  pattern: hit.pattern,
476
476
  },
@@ -62,8 +62,15 @@ export declare function roleReads(r: Read, provenance: ReadCandidateProvenance,
62
62
  * NAME held>` + value, so the whole value is not in the text — but the text it appends IS, and an unset or empty
63
63
  * NAME makes it the whole value, so it is a candidate too. A value that is a substitution is the nested plan
64
64
  * its body already is, never a candidate of its own text (its placeholder is not a path).
65
+ *
66
+ * WHEN the shell expands the value is `expanded`: an ARGUMENT's (a program's, a launcher's or a declaration builtin's
67
+ * `NAME=value` word) is expanded with every other word of the command line, before anything of it runs — through the names
68
+ * the line holds (the table), as {@link readsOf} reads every word: `T=x; dd of="$T"` hands `dd` the value `x`. The shell's
69
+ * OWN assignments expand left to right, each after the ones before it took effect (`A=x B="$A" cmd` binds `B` to `x`) —
70
+ * what the names at the segment's start do not hold — so their value is read as written: `"shell"` (a prefix of a command,
71
+ * or a word in front of where a program would be), `"statement"` (a segment of assignments alone, which BINDS).
65
72
  */
66
- export declare function pushAssignment(reads: Bare[], w: LexedWord, provenance: ReadCandidateProvenance, bound?: boolean): void;
73
+ export declare function pushAssignment(reads: Bare[], w: LexedWord, provenance: ReadCandidateProvenance, expanded: BindingTable | "shell" | "statement"): void;
67
74
  /** Every word of a segment whose program's grammar this parser does not model, from `from` onward: option
68
75
  * payloads and path-shaped option words included, the launcher chain's own words excluded, a program declared
69
76
  * to open no path operand handing only the environment words in front of it. A program with NO row is read the
@@ -1,6 +1,6 @@
1
1
  import { literalTildeSpelling } from "../../shell/lex.js";
2
- import { expandsOf, partPattern, readOfText, rewritten } from "./shell-read-word.js";
3
- import { arithmeticSubstitutions, bindsArrayElement } from "./shell-read-bindings.js";
2
+ import { expandsOf, globMark, partPattern, readOfText, receivedWordOf, rewritten, spellingOf } from "./shell-read-word.js";
3
+ import { arithmeticSubstitutions, bindsArrayElement, judgedSpellingOf, wordValues } from "./shell-read-bindings.js";
4
4
  import { argvProgramOf, attachedOptionPayloads, isPathShapedToken } from "./bash-readonly-classifier.js";
5
5
  import { assignmentArgumentsAreNotPaths, deliversOperands, evaluatesOperands, messageWords, moduleTailOf, objectPathsOf, opensNoOperand, programRow, programTextMayOpen, programTextOpensOf, readArgs, readOptionSlot, selectsContentsTraversal, slotValueCandidates, subcommandOf, valuesAreLiteral, walksCwdWithoutOperand, wordsReadBySomeImplementations, } from "./program-read-model.js";
6
6
  import { objectPathRepositoryOf } from "./shell-read-object-path.js";
@@ -169,30 +169,35 @@ function programTextReads(r, provenance, text, language, ctx) {
169
169
  ctx.programText ??= programTextSentence(language);
170
170
  return [{ ...bare(r, provenance, text), denyOnly: true }];
171
171
  }
172
- export function pushAssignment(reads, w, provenance, bound = false) {
172
+ export function pushAssignment(reads, w, provenance, expanded) {
173
173
  const a = w.assignment;
174
- if (a === undefined || a.form === "compound" || (bound && bindsArrayElement(a)))
174
+ if (a === undefined || a.form === "compound" || (expanded === "statement" && bindsArrayElement(a)))
175
175
  return;
176
176
  const expandsTilde = a.value.expansions.some((p) => p.expansion?.kind === "tilde");
177
- const value = expandsTilde ? a.value.folded : literalTildeSpelling(a.value.folded);
178
- const settled = a.op === "=" && !expandsTilde;
179
- const named = a.value.folded === "" || (a.op === "+=" ? expandsTilde : !settled) ? undefined : value;
180
- if (a.value.folded === "" && settled)
181
- return;
182
- const v = { spelled: value, raw: a.bare ? a.value.raw : w.raw, provenance };
183
- const unsettled = provenance !== "env_assignment" ? { ...v, expands: "unresolvable" } : v.spelled.startsWith("~") && !v.spelled.includes(":") ? { ...v, expands: expandsOf(a.value) } : undefined;
184
- if (!settled && unsettled !== undefined)
185
- reads.push(unsettled);
186
- const substitutes = a.value.expansions.some((p) => p.expansion?.kind === "command" || p.expansion?.kind === "process" || p.expansion?.kind === "arithmetic");
187
- const pattern = named === undefined ? undefined : partPattern({ folded: w.folded, ...(w.judged !== undefined ? { pattern: w.judged } : {}) }, named);
188
- if (named !== undefined && !substitutes)
189
- reads.push({ spelled: named, raw: w.raw, provenance, expands: expandsOf(w), ...(pattern !== undefined ? { pattern } : {}) });
190
- if (a.value.folded.includes(":"))
191
- for (const m of a.value.folded.split(":"))
192
- if (m !== "") {
193
- const r = readOfText(m);
194
- reads.push({ spelled: r.folded, raw: r.raw, provenance, expands: r.expands, denyOnly: true });
195
- }
177
+ const held = typeof expanded === "object" && !expandsTilde ? wordValues(a.value, expanded, true) : undefined;
178
+ const texts = Array.isArray(held) ? held.map((v) => ({ value: spellingOf(v), expands: globMark(v.glob === true), pattern: judgedSpellingOf(v) })) : undefined;
179
+ for (const t of texts ?? [{ value: expandsTilde ? a.value.folded : literalTildeSpelling(a.value.folded), expands: expandsOf(w), pattern: undefined }]) {
180
+ const value = t.value;
181
+ const settled = a.op === "=" && !expandsTilde;
182
+ const named = value === "" || (a.op === "+=" ? expandsTilde : !settled) ? undefined : value;
183
+ if (value === "" && settled)
184
+ continue;
185
+ const v = { spelled: value, raw: a.bare ? a.value.raw : w.raw, provenance };
186
+ const unsettled = provenance !== "env_assignment" ? { ...v, expands: "unresolvable" } : v.spelled.startsWith("~") && !v.spelled.includes(":") ? { ...v, expands: expandsOf(a.value) } : undefined;
187
+ if (!settled && unsettled !== undefined)
188
+ reads.push(unsettled);
189
+ const substitutes = texts === undefined && a.value.expansions.some((p) => p.expansion?.kind === "command" || p.expansion?.kind === "process" || p.expansion?.kind === "arithmetic");
190
+ const pattern = named === undefined ? undefined : texts !== undefined ? t.pattern : partPattern({ folded: w.folded, ...(w.judged !== undefined ? { pattern: w.judged } : {}) }, named);
191
+ if (named !== undefined && !substitutes)
192
+ reads.push({ spelled: named, raw: w.raw, provenance, expands: t.expands, ...(pattern !== undefined ? { pattern } : {}) });
193
+ const list = texts === undefined ? a.value.folded : value;
194
+ if (list.includes(":"))
195
+ for (const m of list.split(":"))
196
+ if (m !== "") {
197
+ const r = readOfText(m);
198
+ reads.push({ spelled: r.folded, raw: r.raw, provenance, expands: r.expands, denyOnly: true });
199
+ }
200
+ }
196
201
  }
197
202
  export function unlistedWords(reads, toks, from, launcherIndices, provenance, ctx, program) {
198
203
  const argv = program !== undefined ? { program: program.basename, from: program.index } : argvProgramOf(toks.map((r) => r.word));
@@ -224,9 +229,9 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
224
229
  expanding.add(j);
225
230
  reads.push(bare(toks[j], j === argvStart ? "program_path" : provenance));
226
231
  if (j < argvStart)
227
- pushAssignment(reads, toks[j].word, "env_assignment");
232
+ pushAssignment(reads, toks[j].word, "env_assignment", ctx.table);
228
233
  else if (j > argvStart && !declaredNotPaths)
229
- pushAssignment(reads, toks[j].word, provenance);
234
+ pushAssignment(reads, toks[j].word, provenance, ctx.table);
230
235
  }
231
236
  const gathered = new RootsGathered();
232
237
  let base = new OperandBase();
@@ -257,7 +262,7 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
257
262
  continue;
258
263
  }
259
264
  reads.push(bare(r, provenance));
260
- pushAssignment(reads, r.word, "env_assignment");
265
+ pushAssignment(reads, receivedWordOf(r), "env_assignment", ctx.table);
261
266
  }
262
267
  }
263
268
  else if (!noPathOperands) {
@@ -273,7 +278,7 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
273
278
  else {
274
279
  reads.push(bare(programWord, "program_path"));
275
280
  if (!declaredNotPaths)
276
- pushAssignment(reads, programWord.word, provenance);
281
+ pushAssignment(reads, receivedWordOf(programWord), provenance, ctx.table);
277
282
  }
278
283
  }
279
284
  }
@@ -380,7 +385,7 @@ export function unlistedWords(reads, toks, from, launcherIndices, provenance, ct
380
385
  speculate(start, r.word.assignment !== undefined ? "whole" : "containment");
381
386
  const values = reads.length;
382
387
  if (!declaredNotPaths && e.slot === undefined)
383
- pushAssignment(reads, r.word, provenance);
388
+ pushAssignment(reads, receivedWordOf(r), provenance, ctx.table);
384
389
  speculate(values, "containment");
385
390
  return;
386
391
  }
@@ -517,7 +522,7 @@ function walkListed(row, argReads, first, last, expanding, reads, ctx, relocated
517
522
  if (slice[e.at].expands !== false)
518
523
  unsettledAt.push({ at: e.at, folded: t });
519
524
  if (row?.operands?.assignmentArguments !== "not-paths")
520
- pushAssignment(reads, slice[e.at].word, "operand");
525
+ pushAssignment(reads, receivedWordOf(slice[e.at]), "operand", ctx.table);
521
526
  break;
522
527
  }
523
528
  }
@@ -443,6 +443,8 @@ export declare class BindingThread {
443
443
  reaches(at: number, j?: number): boolean;
444
444
  /** Does segment `at` stand in a function body (it runs at a call, not here)? */
445
445
  inFunctionBody(at: number): boolean;
446
+ /** The innermost function body segment `at` stands in, as an id one body's segments share (`undefined`: none). */
447
+ bodyOf(at: number): number | undefined;
446
448
  /** Does segment `at` run in a subshell (a `( … )` group, a pipeline member that is not the last, a background job) or a
447
449
  * function body — whatever it changes, the shell that runs the next segment may not see? */
448
450
  runsApart(at: number): boolean;
@@ -3,6 +3,7 @@ import { shellWordsOf } from "../../shell/shell-words.js";
3
3
  import { isShellSyntaxWord, LOOP_LIST_HEADS, readProgramPosition } from "./bash-program-position.js";
4
4
  import { declaredAttributes, programRow, readArgRoles } from "./program-read-model.js";
5
5
  import { codeBodies } from "./shell-reentry-text.js";
6
+ import { braceWordListsOf } from "./shell-read-brace.js";
6
7
  import { BUILTIN_ENABLED, BUILTINS_ALL, ENABLE_BUILTIN, builtinKey, chainAvailability, enableBindings, isBuiltinKey, isDisabledValue, speaksFor } from "./shell-read-builtins.js";
7
8
  export function judgedSpellingOf(v) {
8
9
  if (v.glob !== true)
@@ -589,7 +590,7 @@ export function bindingEffectOf(segment, argv, shape, readValue, shadow, availab
589
590
  let state = "unknown";
590
591
  if (ITERATING_HEADS.has(headWord) && inAt === loopAt + 2 && argv.length > loopAt + 3) {
591
592
  const values = [];
592
- for (const w of argv.slice(loopAt + 3)) {
593
+ for (const w of new Map(braceWordListsOf(argv.slice(loopAt + 3)).flat().map((x) => [x.raw, x])).values()) {
593
594
  const v = readValue(w, false, overlay);
594
595
  if (v === "unknown") {
595
596
  values.length = 0;
@@ -992,6 +993,9 @@ export class BindingThread {
992
993
  inFunctionBody(at) {
993
994
  return this.blocks[at].body !== undefined;
994
995
  }
996
+ bodyOf(at) {
997
+ return this.blocks[at].body?.id;
998
+ }
995
999
  runsApart(at) {
996
1000
  return this.blocks[at].subshells.length > 0 || this.ownSubshell[at] === true || this.blocks[at].body !== undefined;
997
1001
  }
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Brace expansion: the words bash makes of ONE word before any other expansion, in bash's order. A leaf (it reads the lexer
3
+ * only) so that every reader of the words a command runs with reads the same expansion — the plan's words of a simple
4
+ * command (shell-read-plan.ts, both faces) and the words a `for` list binds its variable to (shell-read-bindings.ts).
5
+ */
6
+ import { type LexedWord } from "../../shell/lex.js";
7
+ /** How many readings one segment is read in — every combination of one value for each name its words may hold several
8
+ * values of — before the reader stops claiming to know those names; and how many words one word's braces may make before
9
+ * the reader stops reading them (the word then stays the word it is). */
10
+ export declare const READINGS_MAX = 64;
11
+ /** The bash releases whose brace expansion makes different words of one text: 3.2 (macOS's `/bin/bash`) and every release
12
+ * from 4.0 on, which pads a sequence written with a leading zero and reads a sequence's step (measured on 3.2.57 and 5.3.15).
13
+ * Which one runs a command is not in the text. */
14
+ export type BashRelease = "3.2" | "4+";
15
+ /** The words a list of words makes under each bash release the text may meet ({@link braceWordsOf}): one list where every
16
+ * release makes the same words, one per release where they differ — the command is then read once per list, as a word
17
+ * whose names hold several values is (`readInSeveral`), and a `for` list binds its variable to every list's words. */
18
+ export declare function braceWordListsOf(words: readonly LexedWord[]): readonly (readonly LexedWord[])[];
@@ -0,0 +1,79 @@
1
+ import { argvOf, lexShell } from "../../shell/lex.js";
2
+ export const READINGS_MAX = 64;
3
+ const BASH_RELEASES = ["3.2", "4+"];
4
+ export function braceWordListsOf(words) {
5
+ const lists = BASH_RELEASES.map((release) => words.flatMap((w) => braceWordsOf(w, release)));
6
+ const key = (list) => list.map((w) => w.raw).join("\u0000");
7
+ return lists.filter((list, i) => lists.findIndex((other) => key(other) === key(list)) === i);
8
+ }
9
+ function braceWordsOf(word, release) {
10
+ if (!word.pieces.some((p) => p.expansion?.kind === "brace"))
11
+ return [word];
12
+ const expand = (text) => {
13
+ const w = argumentLexOf(text);
14
+ if (w === undefined || w.unresolved !== undefined)
15
+ return undefined;
16
+ const list = w.pieces.map((p) => ({ p, alternatives: p.expansion?.kind === "brace" ? braceAlternativesOf(p.expansion.body ?? "", release) : undefined })).find((x) => x.alternatives !== undefined);
17
+ if (list === undefined)
18
+ return [w];
19
+ const made = [];
20
+ const [from, to] = [list.p.span[0] - 2, list.p.span[1] - 2];
21
+ for (const alternative of list.alternatives) {
22
+ const next = `${text.slice(0, from)}${alternative}${text.slice(to)}`;
23
+ if (next === "")
24
+ continue;
25
+ const words = expand(next);
26
+ if (words === undefined)
27
+ return undefined;
28
+ made.push(...words);
29
+ if (made.length > READINGS_MAX)
30
+ return undefined;
31
+ }
32
+ return made;
33
+ };
34
+ const words = expand(word.raw);
35
+ return words === undefined || (words.length === 1 && words[0].raw === word.raw) ? [word] : words;
36
+ }
37
+ function argumentLexOf(text) {
38
+ const lexed = lexShell(`: ${text}`);
39
+ const words = "parseFailure" in lexed || lexed.segments.length !== 1 ? undefined : argvOf(lexed.segments[0]);
40
+ return words?.length === 2 && words[1].raw === text ? words[1] : undefined;
41
+ }
42
+ function braceAlternativesOf(body, release) {
43
+ const lexed = lexShell(`""${body}`);
44
+ const words = "parseFailure" in lexed || lexed.segments.length !== 1 ? undefined : argvOf(lexed.segments[0]);
45
+ if (words?.length !== 1)
46
+ return undefined;
47
+ const cuts = [];
48
+ for (const p of words[0].pieces)
49
+ if (p.quotedBy === undefined && p.literal !== undefined)
50
+ for (let i = p.literal.indexOf(","); i >= 0; i = p.literal.indexOf(",", i + 1))
51
+ cuts.push(p.span[0] - 2 + i);
52
+ if (cuts.length === 0)
53
+ return sequenceAlternativesOf(body, release);
54
+ return [...cuts, body.length].map((cut, k) => body.slice(k === 0 ? 0 : cuts[k - 1] + 1, cut));
55
+ }
56
+ function sequenceAlternativesOf(body, release) {
57
+ const m = /^([+-]?\d+|[A-Za-z])\.\.([+-]?\d+|[A-Za-z])(?:\.\.([+-]?\d+))?$/.exec(body);
58
+ if (m === null)
59
+ return undefined;
60
+ const [lhs, rhs, step] = [m[1], m[2], m[3]];
61
+ const letter = (t) => /^[A-Za-z]$/.test(t);
62
+ if (letter(lhs) !== letter(rhs))
63
+ return undefined;
64
+ if (step !== undefined && release === "3.2")
65
+ return [`\\{${body}\\}`];
66
+ const [from, to] = letter(lhs) ? [lhs.charCodeAt(0), rhs.charCodeAt(0)] : [Number(lhs), Number(rhs)];
67
+ const incr = Math.abs(step === undefined ? 1 : Number(step)) || 1;
68
+ if (![from, to, incr].every(Number.isSafeInteger) || Math.abs(to - from) / incr >= READINGS_MAX)
69
+ return undefined;
70
+ const terms = [];
71
+ for (let v = from; from <= to ? v <= to : v >= to; v += from <= to ? incr : -incr)
72
+ terms.push(v);
73
+ if (letter(lhs)) {
74
+ const chars = terms.map((c) => String.fromCharCode(c));
75
+ return chars.every(letter) ? chars : undefined;
76
+ }
77
+ const width = release === "3.2" || ![lhs, rhs].some((t) => /^-?0\d/.test(t)) ? 0 : Math.max(lhs.length, rhs.length);
78
+ return terms.map((v) => (width === 0 ? String(v) : v < 0 ? `-${String(-v).padStart(width - 1, "0")}` : String(v).padStart(width, "0")));
79
+ }
@@ -12,7 +12,7 @@ import { declaredReadDenyHomes, homeViewsAt } from "./read-deny-home.js";
12
12
  import { anyOptionWord, programArgs } from "./shell-read-write-targets.js";
13
13
  import { shellReadFaceWords } from "./shell-read-face.js";
14
14
  import { passesUnasked } from "./shell-read-device.js";
15
- import { programRow, selectedOptions } from "./program-read-model.js";
15
+ import { operandWriterNames, programKeyOf, programRow, selectedOptions } from "./program-read-model.js";
16
16
  import { refusedByRemoval, SHELL_REMOVAL_COMMANDS } from "./removal-targets.js";
17
17
  import { allFindings, anyFaceGuards, decideShellRead, denyRowAtOrBelow, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, stationGuards, writeFaceGuards, } from "./shell-read-judge.js";
18
18
  import { seatOf } from "../../core/tool-name-readings.js";
@@ -57,7 +57,7 @@ function runOrderOf(judged) {
57
57
  return { runs, plans, concurrent };
58
58
  }
59
59
  function lineOrderPlaced(runs, concurrent) {
60
- const reshapes = (s) => RESHAPES_TREE.has(s.segment.verb?.basename ?? "");
60
+ const reshapes = (s) => RESHAPES_TREE.has(programKeyOf(s.segment.verb?.basename ?? ""));
61
61
  const writes = (s) => s.findings.some((f) => f.read.candidate.face === "write");
62
62
  const stepsUp = (s) => s.findings.some((f) => f.read.candidate.spelled.split(/[\\/]/).includes(".."));
63
63
  return runs.every((later, j) => runs.every((earlier, i) => i === j || (i > j && !concurrent) || (!reshapes(earlier) && !(writes(earlier) && stepsUp(later)))));
@@ -68,7 +68,7 @@ function writesPlacedOf(judged, boundary) {
68
68
  return false;
69
69
  const { runs, plans, concurrent } = runOrderOf(judged);
70
70
  const placed = (s) => {
71
- const verb = s.segment.verb?.basename ?? "";
71
+ const verb = programKeyOf(s.segment.verb?.basename ?? "");
72
72
  if (s.segment.reentry === "shell" || s.segment.unreadProgramText !== undefined)
73
73
  return false;
74
74
  if (UNPLACED_OPTIONS[verb]?.(programArgs(s.segment).map((w) => w.spelled)) === true)
@@ -95,7 +95,7 @@ function unplacedOptionsOf(judged) {
95
95
  const nested = s.nested.map(unplacedOptionsOf).find((u) => u !== undefined);
96
96
  if (nested !== undefined)
97
97
  return nested;
98
- const verb = s.segment.verb?.basename;
98
+ const verb = s.segment.verb === undefined ? undefined : programKeyOf(s.segment.verb.basename);
99
99
  if ((verb === "cp" || verb === "mv") && anyOptionWord(programArgs(s.segment).map((w) => w.spelled)))
100
100
  return { program: verb };
101
101
  }
@@ -302,9 +302,9 @@ function refusalOf(tool, fold, boundary, paths) {
302
302
  if (fold.finding === "deny_hit" && w?.deny !== undefined) {
303
303
  const target = w.read.target ?? w.deny.matchedView;
304
304
  const write = w.deny.face === "write";
305
- const core = readDenySentence({ target, pattern: w.deny.pattern, matchedView: w.deny.matchedView, ...(write ? { face: "write" } : {}) });
305
+ const core = readDenySentence({ target, pattern: w.deny.pattern, matchedView: w.deny.matchedView, ...(write ? { face: "write" } : {}), ...(w.deny.readRow === true ? { readRow: true } : {}) });
306
306
  const through = deniedThrough(w.read, boundary);
307
- const sentence = `Error (${tool}): ${core} ${write ? WRITE_DENY_REFUSAL_NOTE : DENY_REFUSAL_NOTE}${through !== undefined ? ` ${DENIED_THROUGH_NOTE[through]}` : ""}`;
307
+ const sentence = `Error (${tool}): ${core} ${write ? writeDenyRefusalNote() : DENY_REFUSAL_NOTE}${through !== undefined ? ` ${DENIED_THROUGH_NOTE[through]}` : ""}`;
308
308
  return { sentence, ...(write ? {} : { details: violationDetails({ code: "read_path_denied", message: sentence, target, pattern: w.deny.pattern }) }) };
309
309
  }
310
310
  const account = findingAccount(fold, boundary);
@@ -325,8 +325,10 @@ function deniedThrough(read, boundary) {
325
325
  return "home";
326
326
  return undefined;
327
327
  }
328
- const WRITE_DENY_REFUSAL_NOTE = "The boundary judges this command's write targets — its output redirections and the operands of mkdir, touch, rm, " +
329
- "rmdir, mv, cp, tee and an in-place sed — against the write deny list; a denied write is refused here rather than escalated.";
328
+ function writeDenyRefusalNote() {
329
+ const names = operandWriterNames();
330
+ return `The boundary judges this command's write targets — its output redirections and the operands of ${names.slice(0, -1).join(", ")} and ${names.at(-1)} — against the write deny list; a denied write is refused here rather than escalated.`;
331
+ }
330
332
  const DENY_REFUSAL_NOTE = "The read boundary judges the paths this command names — as written and, where a filesystem can be consulted, where " +
331
333
  "they resolve and what a pattern among them matches — and refuses a deny-listed one here rather than escalating it; " +
332
334
  "a file the command reaches without naming it is judged only where a segment deny row (built in, or the deployment's " +
@@ -96,25 +96,30 @@ function basesFor(candidate, boundary) {
96
96
  const bases = candidate.bases.length > 0 ? candidate.bases : [boundary.cwd ?? boundary.roots[0] ?? ""];
97
97
  return candidate.repositoryTop !== undefined ? everyAncestor(bases) : bases;
98
98
  }
99
- function lexicalReadsOf(candidate, boundary, placed) {
100
- if (candidate.expands === "unresolvable") {
101
- return [{ candidate, established: "unestablishable", spellings: [candidate.spelled], cause: `"${candidate.raw}" is rewritten by the shell before the program sees it` }];
99
+ function placedSpellings(spelled, bases, homeDir) {
100
+ const out = [];
101
+ for (const base of bases) {
102
+ const at = resolveOperandSpellings(base === "" ? undefined : base, spelled, homeDir);
103
+ if (at === undefined)
104
+ continue;
105
+ out.push(at.folded);
106
+ if (at.spelled !== undefined)
107
+ out.push(at.spelled);
102
108
  }
109
+ return out;
110
+ }
111
+ function lexicalReadsOf(candidate, boundary, placed) {
112
+ const rewritten = candidate.expands === "unresolvable" ? `"${candidate.raw}" is rewritten by the shell before the program sees it` : undefined;
103
113
  const bases = placed ?? basesFor(candidate, boundary);
104
114
  if (bases === "unmodelled") {
105
115
  const floorsAt = candidate.floorBases ?? [boundary.cwd ?? boundary.roots[0] ?? ""];
106
- const floors = candidate.repositoryTop !== undefined ? everyAncestor(floorsAt) : floorsAt;
107
- const spellings = [candidate.spelled];
108
- for (const floorBase of floors) {
109
- const viaFloor = floorBase === "" ? undefined : resolveOperandSpellings(floorBase, candidate.spelled, boundary.homeDir);
110
- if (viaFloor === undefined)
111
- continue;
112
- spellings.push(viaFloor.folded);
113
- if (viaFloor.spelled !== undefined)
114
- spellings.push(viaFloor.spelled);
115
- }
116
- return [{ candidate, established: "unestablishable", spellings, cause: `"${candidate.raw}" is relative to a working directory this command's text does not settle` }];
116
+ const spellings = [candidate.spelled, ...placedSpellings(candidate.spelled, floorsAt.filter((f) => f !== ""), boundary.homeDir)];
117
+ const anywhereAbove = candidate.repositoryTop !== undefined || candidate.unsettledStart === true;
118
+ const ancestorViews = anywhereAbove ? [...new Set(placedSpellings(candidate.spelled, everyAncestor(floorsAt.filter((f) => f !== "")), boundary.homeDir))].filter((v) => !spellings.includes(v)) : [];
119
+ return [{ candidate, established: "unestablishable", spellings, ...(ancestorViews.length > 0 ? { ancestorViews } : {}), cause: rewritten ?? `"${candidate.raw}" is relative to a working directory this command's text does not settle` }];
117
120
  }
121
+ if (rewritten !== undefined)
122
+ return [{ candidate, established: "unestablishable", spellings: [...new Set([candidate.spelled, ...placedSpellings(candidate.spelled, bases, boundary.homeDir)])], cause: rewritten }];
118
123
  const out = [];
119
124
  const seen = new Set();
120
125
  for (const base of bases) {
@@ -174,8 +179,10 @@ function writtenByText(plan, boundary) {
174
179
  return { targets, unplaced };
175
180
  }
176
181
  function unfollowedBackupReads(j, boundary, cause) {
177
- const spellings = sedBackupNames(j.followed.operand.spelled, j.followed.suffix).flatMap((name) => lexicalReadsOf({ ...j.candidate, spelled: name }, boundary).flatMap((r) => [...(r.target !== undefined ? [r.target] : []), ...r.spellings]));
178
- const read = { candidate: j.candidate, established: "unestablishable", spellings: [...new Set(spellings)], cause };
182
+ const named = sedBackupNames(j.followed.operand.spelled, j.followed.suffix).flatMap((name) => lexicalReadsOf({ ...j.candidate, spelled: name }, boundary));
183
+ const spellings = named.flatMap((r) => [...(r.target !== undefined ? [r.target] : []), ...r.spellings]);
184
+ const ancestorViews = [...new Set(named.flatMap((r) => r.ancestorViews ?? []))];
185
+ const read = { candidate: j.candidate, established: "unestablishable", spellings: [...new Set(spellings)], ...(ancestorViews.length > 0 ? { ancestorViews } : {}), cause };
179
186
  return (j.seats ?? ["landing"]).map((seat) => writtenAt(read, j, seat));
180
187
  }
181
188
  function writtenAt(read, j, seat) {
@@ -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")
@@ -75,6 +75,12 @@ export interface ReadCandidate {
75
75
  * A deny row is a floor, so the judge resolves the spelling against these for deny rows ONLY — never to
76
76
  * establish a read. `cd sub && cd $'\x2e' && cat <deny row under sub>` (bash: `cd .`) is refused through it. */
77
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;
78
84
  /** Only on an object path relative to its repository's top (shell-read-object-path.ts): `bases` / `floorBases` are where
79
85
  * git starts, the top one of them or above — the one discovery finds (`discovered`, read where a filesystem answers),
80
86
  * else any: every ancestor meets the deny rows. */
@@ -143,6 +149,10 @@ export interface ShellReadSegment {
143
149
  /** The working directories this segment may be standing in (what every relative candidate's `bases` is), or
144
150
  * `"unmodelled"` when the text does not settle it. */
145
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;
146
156
  /** Substitution bodies, unquoted here-document substitutions, and re-entered shell text, each its own plan. */
147
157
  readonly nested: readonly ShellReadPlan[];
148
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