@sema-agent/core 7.61.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 (176) hide show
  1. package/CHANGELOG.md +312 -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.d.ts +6 -1
  8. package/dist/agents/subagent.js +66 -12
  9. package/dist/agents/suspend-guard.d.ts +38 -16
  10. package/dist/agents/suspend-guard.js +9 -4
  11. package/dist/agents/verify.js +4 -3
  12. package/dist/core/checkpoint-features.d.ts +722 -0
  13. package/dist/core/checkpoint-features.js +98 -0
  14. package/dist/core/checkpoint-requirements.d.ts +9 -2
  15. package/dist/core/checkpoint-requirements.js +9 -4
  16. package/dist/core/checkpoint-row-verdict.d.ts +99 -0
  17. package/dist/core/checkpoint-row-verdict.js +225 -0
  18. package/dist/core/checkpoint-store.d.ts +55 -745
  19. package/dist/core/checkpoint-store.js +39 -141
  20. package/dist/core/engine-notice.d.ts +19 -3
  21. package/dist/core/engine-notice.js +9 -2
  22. package/dist/core/gate-fold.js +2 -2
  23. package/dist/core/governance-codes.d.ts +3 -1
  24. package/dist/core/governance-codes.js +3 -0
  25. package/dist/core/hooks.d.ts +13 -0
  26. package/dist/core/human-input-projection.d.ts +1 -0
  27. package/dist/core/human-input-projection.js +3 -0
  28. package/dist/core/image-admission.d.ts +1 -1
  29. package/dist/core/locked-config.d.ts +2 -2
  30. package/dist/core/mcp-host-seat.js +6 -1
  31. package/dist/core/memory-engine/consolidation-driver.d.ts +1 -1
  32. package/dist/core/memory-vector.d.ts +1 -1
  33. package/dist/core/memory.d.ts +10 -10
  34. package/dist/core/mode-policy.js +1 -1
  35. package/dist/core/mods/classic-events.d.ts +9 -1
  36. package/dist/core/mods/dollar.d.ts +32 -1
  37. package/dist/core/mods/dollar.js +13 -1
  38. package/dist/core/mods/kernel/events.d.ts +11 -3
  39. package/dist/core/mods/kernel/events.js +13 -10
  40. package/dist/core/mods/lifecycle-stations.d.ts +36 -4
  41. package/dist/core/mods/lifecycle-stations.js +44 -9
  42. package/dist/core/mods/session-append.d.ts +4 -1
  43. package/dist/core/mods/session-append.js +7 -0
  44. package/dist/core/mods/session-receive.js +12 -15
  45. package/dist/core/mods/stations.d.ts +51 -6
  46. package/dist/core/mods/stations.js +124 -0
  47. package/dist/core/own-property-receipt.d.ts +7 -0
  48. package/dist/core/own-property-receipt.js +3 -0
  49. package/dist/core/read-root-candidate.js +1 -1
  50. package/dist/core/resume-startup-cause.d.ts +5 -4
  51. package/dist/core/runner/compact-session.js +5 -2
  52. package/dist/core/runner/contracts.d.ts +18 -8
  53. package/dist/core/runner/delegation-owner.d.ts +43 -0
  54. package/dist/core/runner/delegation-owner.js +59 -0
  55. package/dist/core/runner/lineage-reroot-view.d.ts +56 -0
  56. package/dist/core/runner/lineage-reroot-view.js +108 -0
  57. package/dist/core/runner/permission-rule-lanes.d.ts +2 -1
  58. package/dist/core/runner/permission-rule-lanes.js +2 -2
  59. package/dist/core/runner/person-path-rows.d.ts +15 -0
  60. package/dist/core/runner/person-path-rows.js +26 -3
  61. package/dist/core/runner/prepare-acquire-reconcile.d.ts +4 -1
  62. package/dist/core/runner/prepare-acquire-reconcile.js +7 -2
  63. package/dist/core/runner/prepare-caps-and-workflow.d.ts +1 -0
  64. package/dist/core/runner/prepare-caps-and-workflow.js +1 -1
  65. package/dist/core/runner/prepare-config-doors.d.ts +6 -6
  66. package/dist/core/runner/prepare-config-doors.js +3 -4
  67. package/dist/core/runner/prepare-hands-readface.d.ts +1 -1
  68. package/dist/core/runner/prepare-hands-readface.js +28 -7
  69. package/dist/core/runner/prepare-inherited-gate.d.ts +2 -0
  70. package/dist/core/runner/prepare-inherited-gate.js +7 -3
  71. package/dist/core/runner/prepare-task.js +10 -7
  72. package/dist/core/runner/resume-admission.d.ts +3 -3
  73. package/dist/core/runner/resume-admission.js +6 -3
  74. package/dist/core/runner/resume-apply.d.ts +4 -0
  75. package/dist/core/runner/resume-apply.js +11 -4
  76. package/dist/core/runner/resume-checkpoint-screen.d.ts +9 -0
  77. package/dist/core/runner/resume-checkpoint-screen.js +4 -84
  78. package/dist/core/runner/run-git-lane.d.ts +2 -0
  79. package/dist/core/runner/run-git-lane.js +4 -1
  80. package/dist/core/runner/run-harness-handlers.d.ts +2 -0
  81. package/dist/core/runner/run-harness-handlers.js +3 -2
  82. package/dist/core/runner/run-leg.js +24 -7
  83. package/dist/core/runner/run-settle-and-teardown.js +3 -2
  84. package/dist/core/runner/run-stop-and-final-verify.js +2 -1
  85. package/dist/core/runner/run-turn-boundary.js +7 -4
  86. package/dist/core/runner/runtask.js +6 -6
  87. package/dist/core/runner/steering-preview.d.ts +9 -0
  88. package/dist/core/runner/steering-preview.js +5 -0
  89. package/dist/core/runner/stream-steer-verb.js +8 -0
  90. package/dist/core/runner/tool-face-overlay.js +2 -0
  91. package/dist/core/runner/turn-attachments.d.ts +5 -0
  92. package/dist/core/runner/turn-attachments.js +1 -1
  93. package/dist/core/runner-deps.d.ts +2 -2
  94. package/dist/core/secret-env.d.ts +8 -5
  95. package/dist/core/secret-env.js +37 -18
  96. package/dist/core/session-store.d.ts +1 -1
  97. package/dist/core/session-store.js +5 -1
  98. package/dist/core/session.d.ts +14 -4
  99. package/dist/core/store-contracts/checkpoint-store-contract.d.ts +6 -0
  100. package/dist/core/store-contracts/checkpoint-store-contract.js +68 -0
  101. package/dist/core/store-contracts/session-store-contract.js +22 -8
  102. package/dist/core/task-event.d.ts +7 -1
  103. package/dist/core/task-notification.js +2 -1
  104. package/dist/core/task-registry-agent.d.ts +27 -7
  105. package/dist/core/task-registry-agent.js +12 -5
  106. package/dist/core/task-registry-shared.d.ts +7 -0
  107. package/dist/core/task-registry-workflow.js +4 -3
  108. package/dist/core/task-registry.d.ts +13 -2
  109. package/dist/core/task-registry.js +11 -4
  110. package/dist/core/task-result.d.ts +5 -5
  111. package/dist/core/task-spec.d.ts +1 -1
  112. package/dist/core/terminal-cause.d.ts +6 -6
  113. package/dist/core/tool-face.d.ts +6 -2
  114. package/dist/core/tool-face.js +1 -1
  115. package/dist/core/tool-policy.d.ts +2 -1
  116. package/dist/core/tool-roster.d.ts +4 -4
  117. package/dist/core/tool-spec.d.ts +4 -0
  118. package/dist/core/types.d.ts +1 -1
  119. package/dist/core/types.js +1 -1
  120. package/dist/engine/execution-env/node-execution-env.d.ts +3 -0
  121. package/dist/engine/execution-env/node-execution-env.js +12 -5
  122. package/dist/engine/harness/types.d.ts +11 -0
  123. package/dist/engine/session/parent-chain-guard.d.ts +3 -3
  124. package/dist/engine/session/parent-chain-guard.js +1 -1
  125. package/dist/engine/session/path-to-root.d.ts +18 -3
  126. package/dist/engine/session/path-to-root.js +15 -1
  127. package/dist/engine/session/repo-utils.d.ts +12 -1
  128. package/dist/engine/session/repo-utils.js +41 -0
  129. package/dist/engine/session/session.js +1 -1
  130. package/dist/engine/session/storage-base.d.ts +20 -0
  131. package/dist/engine/session/storage-base.js +28 -9
  132. package/dist/index.d.ts +9 -8
  133. package/dist/index.js +4 -4
  134. package/dist/internal/harness.d.ts +4 -3
  135. package/dist/internal/harness.js +3 -2
  136. package/dist/orchestration/run-workflow-tool.d.ts +3 -0
  137. package/dist/orchestration/run-workflow-tool.js +27 -11
  138. package/dist/orchestration/workflow-governance.d.ts +1 -1
  139. package/dist/orchestration/workflow.d.ts +3 -0
  140. package/dist/orchestration/workflow.js +2 -7
  141. package/dist/stores/file/checkpoint-store.d.ts +2 -0
  142. package/dist/stores/file/checkpoint-store.js +7 -6
  143. package/dist/stores/file/fs-atomic.d.ts +0 -22
  144. package/dist/stores/file/fs-atomic.js +0 -17
  145. package/dist/stores/file/index.d.ts +2 -9
  146. package/dist/stores/file/index.js +2 -4
  147. package/dist/stores/file/session-store.d.ts +13 -7
  148. package/dist/stores/file/session-store.js +40 -17
  149. package/dist/tools/fs/bash-program-position.d.ts +3 -2
  150. package/dist/tools/fs/bash-program-position.js +7 -7
  151. package/dist/tools/fs/removal-targets.js +2 -2
  152. package/dist/tools/fs/shell-read-argv.d.ts +4 -2
  153. package/dist/tools/fs/shell-read-argv.js +14 -3
  154. package/dist/tools/fs/shell-read-bindings.d.ts +18 -2
  155. package/dist/tools/fs/shell-read-bindings.js +148 -68
  156. package/dist/tools/fs/shell-read-check.js +20 -4
  157. package/dist/tools/fs/shell-read-establish.js +22 -8
  158. package/dist/tools/fs/shell-read-functions.js +2 -2
  159. package/dist/tools/fs/shell-read-object-path.d.ts +59 -0
  160. package/dist/tools/fs/shell-read-object-path.js +119 -0
  161. package/dist/tools/fs/shell-read-plan.d.ts +8 -0
  162. package/dist/tools/fs/shell-read-plan.js +47 -30
  163. package/dist/tools/fs/shell-read-start.d.ts +66 -13
  164. package/dist/tools/fs/shell-read-start.js +89 -17
  165. package/dist/tools/fs/shell-read-workdir.d.ts +29 -8
  166. package/dist/tools/fs/shell-read-workdir.js +31 -8
  167. package/package.json +2 -2
  168. package/test/export-surface.snapshot.json +21 -33
  169. package/wire-changes/core-stores-sql@7.62.0.json +30 -0
  170. package/wire-changes/core@7.62.0.json +2181 -0
  171. package/wire-changes/mods-kernel@7.62.0.json +42 -0
  172. package/wire-changes/primitives@7.62.0.json +30 -0
  173. package/dist/core/consolidate-scope.d.ts +0 -93
  174. package/dist/core/consolidate-scope.js +0 -98
  175. package/dist/core/runner/memory-consolidation.d.ts +0 -109
  176. package/dist/core/runner/memory-consolidation.js +0 -251
@@ -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;
@@ -1,3 +1,8 @@
1
+ import { literalTildeSpelling } from "../../shell/lex.js";
2
+ import { programBasename } from "./bash-program-position.js";
3
+ import { launcherOptionPathRole, launcherOptionStep, programRow, readOptionRole } from "./program-read-model.js";
4
+ import { chdirFrom } from "./shell-read-object-path.js";
5
+ import { anchorSpelling, pathFamilyOf } from "./safety.js";
1
6
  const NO_NAMES = new Set();
2
7
  export function heldAt(table, bound = NO_NAMES) {
3
8
  return { start: (key) => table.stateOf(key), bound };
@@ -62,27 +67,94 @@ export function stdinFeeds(segments, start, piped) {
62
67
  };
63
68
  return fedAt;
64
69
  }
65
- export function rebasePlan(plan, from, to, floor) {
66
- if (to !== "unmodelled" && to.length === 1 && to[0] === from)
67
- return plan;
68
- const fromSep = from.endsWith("/") || from.endsWith("\\") ? from : `${from}/`;
69
- const moveInto = (into, b) => {
70
- if (b === from)
71
- return [...into];
72
- if (b.startsWith(fromSep))
73
- return into.map((t) => `${t.endsWith("/") || t.endsWith("\\") ? t : `${t}/`}${b.slice(fromSep.length)}`);
74
- return [b];
70
+ export function nestedStartOf(cwd) {
71
+ return anchorSpelling(pathFamilyOf({ cwd }), cwd, "\u0000");
72
+ }
73
+ export function walkFromStart(base) {
74
+ const at = base.search(/[\\/]\u0000(?:[\\/]|$)/);
75
+ return at < 0 ? undefined : base.slice(at + 3);
76
+ }
77
+ const settledWord = (r) => r.expands === false && (r.values?.length ?? 1) <= 1 && r.homeFloor === undefined && r.word.pieces.every((q) => q.literal !== undefined || q.expansion !== undefined);
78
+ export function launchedInOf(pos, toks) {
79
+ if (pos.baseMovedAt.length === 0)
80
+ return undefined;
81
+ const dirs = [];
82
+ let owner;
83
+ for (const at of pos.baseMovedAt) {
84
+ const l = pos.launchers.filter((x) => x.index < at).at(-1);
85
+ const row = programRow(programBasename(l.name));
86
+ const w = toks[at].folded;
87
+ const step = launcherOptionStep(row, w);
88
+ const own = step === 2 ? undefined : readOptionRole(row, w);
89
+ const role = step === 2 ? launcherOptionPathRole(row, w) : own?.form === "attached" ? own.role : undefined;
90
+ if (role?.kind !== "path" || role.base !== "working-directory")
91
+ return "unmodelled";
92
+ const word = toks[step === 2 ? at + 1 : at];
93
+ const twoWays = own?.form === "attached" && own.spec?.arity === "attached" && own.value.startsWith("=");
94
+ const value = step === 2 ? word.folded : own?.form === "attached" && !twoWays ? literalTildeSpelling(own.value) : undefined;
95
+ const dir = value !== undefined && value !== "" && settledWord(word) ? value : null;
96
+ if (l.index === owner)
97
+ dirs[dirs.length - 1] = dir;
98
+ else
99
+ dirs.push(dir);
100
+ owner = l.index;
101
+ }
102
+ return dirs.every((d) => d !== null) ? dirs : "unmodelled";
103
+ }
104
+ export function launchedAt(launchedIn, bases, floor, homeDir) {
105
+ if (launchedIn === undefined)
106
+ return undefined;
107
+ const here = bases !== "unmodelled" ? bases : floor;
108
+ let to = launchedIn === "unmodelled" ? "unmodelled" : bases;
109
+ let toFloor = here;
110
+ for (const dir of launchedIn === "unmodelled" ? [] : launchedIn) {
111
+ if (to !== "unmodelled") {
112
+ const next = chdirFrom(to, dir, homeDir);
113
+ if (next === undefined)
114
+ to = "unmodelled";
115
+ else
116
+ toFloor = to = next;
117
+ }
118
+ else if (toFloor !== undefined)
119
+ toFloor = chdirFrom(toFloor, dir, homeDir) ?? toFloor;
120
+ }
121
+ const words = [...new Set([...(here ?? []), ...(toFloor ?? [])])];
122
+ return { to, ...(toFloor !== undefined && toFloor.length > 0 ? { floor: toFloor } : {}), ...(words.length > 0 ? { words } : {}) };
123
+ }
124
+ export function rebasePlan(plan, to, floor) {
125
+ const key = JSON.stringify([to, floor]);
126
+ const known = REBASED.get(plan)?.get(key);
127
+ if (known !== undefined)
128
+ return known;
129
+ const out = rebasedOnto(plan, to, floor);
130
+ REBASED.set(plan, (REBASED.get(plan) ?? new Map()).set(key, out));
131
+ return out;
132
+ }
133
+ const REBASED = new WeakMap();
134
+ function rebasedOnto(plan, to, floor) {
135
+ const placed = (into, b) => {
136
+ const rest = walkFromStart(b);
137
+ if (rest === undefined)
138
+ return [b];
139
+ return (into ?? []).map((t) => (rest === "" ? t : anchorSpelling(pathFamilyOf({ cwd: t }), t, rest)));
75
140
  };
76
- const moveBase = (b) => (to === "unmodelled" ? [] : moveInto(to, b));
141
+ const moveBase = (b) => (to === "unmodelled" ? [] : placed(to, b));
77
142
  const floorAt = to === "unmodelled" ? floor : to;
78
- const moveFloor = (bases, into) => [...new Set(bases.flatMap((b) => moveInto(into, b)))];
143
+ const floorsOf = (bases, into) => {
144
+ const floors = [...new Set(bases.flatMap((b) => placed(into, b)))];
145
+ return floors.length > 0 ? { floorBases: floors } : {};
146
+ };
79
147
  const moveCandidate = (c) => {
80
- if (c.bases === "unmodelled")
81
- return c.floorBases === undefined || floorAt === undefined ? c : { ...c, floorBases: moveFloor(c.floorBases, floorAt) };
148
+ if (c.bases === "unmodelled") {
149
+ if (c.floorBases === undefined)
150
+ return c;
151
+ const { floorBases: _, ...rest } = c;
152
+ return { ...rest, ...floorsOf(c.floorBases, floorAt) };
153
+ }
82
154
  if (c.bases.length === 0)
83
155
  return c;
84
156
  if (to === "unmodelled")
85
- return floor === undefined ? { ...c, bases: "unmodelled" } : { ...c, bases: "unmodelled", floorBases: moveFloor(c.bases, floor) };
157
+ return { ...c, bases: "unmodelled", ...floorsOf(c.bases, floor) };
86
158
  return { ...c, bases: [...new Set(c.bases.flatMap(moveBase))] };
87
159
  };
88
160
  return {
@@ -93,8 +165,8 @@ export function rebasePlan(plan, from, to, floor) {
93
165
  redirects: s.redirects.map((r) => (r.target === undefined ? r : { ...r, target: moveCandidate(r.target) })),
94
166
  ...(s.baseMove !== undefined ? { baseMove: { target: typeof s.baseMove.target === "string" ? s.baseMove.target : moveCandidate(s.baseMove.target) } } : {}),
95
167
  bases: s.bases === "unmodelled" || to === "unmodelled" ? "unmodelled" : [...new Set(s.bases.flatMap(moveBase))],
96
- nested: s.nested.map((n) => rebasePlan(n, from, to, floor)),
97
- ...(s.printed !== undefined ? { printed: s.printed.map((n) => rebasePlan(n, from, to, floor)) } : {}),
168
+ nested: s.nested.map((n) => rebasePlan(n, to, floor)),
169
+ ...(s.printed !== undefined ? { printed: s.printed.map((n) => rebasePlan(n, to, floor)) } : {}),
98
170
  })),
99
171
  };
100
172
  }
@@ -6,9 +6,10 @@
6
6
  * `popd` with the stack the text pushed, and a literal `eval` text read as the text it is, in this shell. Any other text
7
7
  * that may move the base where the plan cannot follow it (`source`, a non-literal `eval`, a computed program word, a
8
8
  * call into a function body or a code body that may move, an option the stack reading does not follow) LOSES it: what
9
- * stands after it cannot be placed. A move inside a subshell, a pipeline member or a function body nobody called is read
10
- * as a move too — a candidate SET, more places, never fewer (a move may also fail: the unmoved place stays a candidate
11
- * unless an `&&` run proves the move ran).
9
+ * stands after it cannot be placed. The moves are a candidate SET — a move may fail: the unmoved place stays a candidate
10
+ * unless an `&&` run proves the move ran. A move reaches a later segment where a binding of the same segment would: the
11
+ * binding thread's one visibility rule (`BindingThread.reaches`) — a move inside a `( … )` group, a pipeline member that
12
+ * is not the last, a background job or a function body is no move for a segment outside it ({@link WorkdirScope}).
12
13
  */
13
14
  import type { Bare } from "./shell-read-argv.js";
14
15
  import type { BindingTable, WorkingDirectoryState } from "./shell-read-bindings.js";
@@ -51,6 +52,7 @@ export interface WorkdirContext {
51
52
  readonly evalEnd: (text: string, from: BaseCandidate, table: BindingTable) => {
52
53
  readonly end: readonly BaseCandidate[] | "unmodelled";
53
54
  readonly physical: boolean;
55
+ readonly reached: ReadonlySet<string>;
54
56
  };
55
57
  }
56
58
  /** One segment's move as the walk applies it: the shift, whether an `&&` run proves it ran, the first segment of the
@@ -67,8 +69,6 @@ export interface CommandTable extends BindingTable {
67
69
  readonly commandSets: ReadonlySet<string>;
68
70
  }
69
71
  export declare class WorkdirThread {
70
- /** The start is where the shell stands (not a placeholder a nested plan is re-based from): `PWD` reads it. */
71
- private readonly readable;
72
72
  private candidates;
73
73
  private lostAt;
74
74
  /** The reachable bases at the moment the walk lost track — the deny floor of a word it cannot place. */
@@ -78,13 +78,14 @@ export declare class WorkdirThread {
78
78
  private physical;
79
79
  /** The last segment whose move was applied or lost track ({@link WorkingDirectoryState.movedAt}). */
80
80
  private movedAt;
81
+ /** The start is a place the shell stands in — no placeholder start, no base walked from one (an `eval` text a nested text runs): `PWD` reads it. */ private readonly readable;
81
82
  constructor(start: readonly BaseCandidate[] | readonly string[] | "unmodelled",
82
- /** The start is where the shell stands (not a placeholder a nested plan is re-based from): `PWD` reads it. */
83
- readable: boolean,
84
83
  /** The physical mode may already be on where the text starts (an `eval` text run in a shell that set it). */
85
84
  startsPhysical?: boolean);
86
85
  get lost(): boolean;
86
+ /** The deny floor of the words the walk could not place: a closed scope that lost track keeps its floor for its words. */
87
87
  get floorBases(): readonly string[] | undefined;
88
+ private closedFloors;
88
89
  /** The candidates a reader whose `&&` run starts at `andRunStart` may stand in. */
89
90
  reachable(andRunStart: number): readonly BaseCandidate[];
90
91
  /** Where the text ends: every candidate, or `unmodelled`. */
@@ -95,7 +96,18 @@ export declare class WorkdirThread {
95
96
  setPhysical(): void;
96
97
  /** Where the text ends the physical mode may be on (an `eval` text hands it back to the shell that ran it). */
97
98
  get mayBePhysical(): boolean;
98
- /** Stop placing anything from segment `at` on: the reachable bases (and a target's floor spellings) become the deny floor. */
99
+ /** What the walk holds before a segment that runs apart from the shell after it ({@link WorkdirScope}). */
100
+ snapshot(): WorkdirScope;
101
+ /** A scope closed: what its moves did never reached the shell outside it — the walk holds again what it held before them.
102
+ * The places they went stay a deny floor of a walk that later loses track ({@link scopeReached}). */
103
+ restore(s: WorkdirScope): void;
104
+ /** Places a closed scope's moves went (a function body run at a call goes there, `eval`'s text closed one): as a binding's
105
+ * deny floor stays wherever the binding may have run, they join the deny floor where the walk loses track. */
106
+ private scopeReached;
107
+ get reached(): ReadonlySet<string>;
108
+ reach(bases: Iterable<string>): void;
109
+ /** Stop placing anything from segment `at` on: the reachable bases (and a target's floor spellings, the places a closed
110
+ * scope went) become the deny floor. */
99
111
  lose(at: number, reachable: readonly BaseCandidate[], floorTargets?: readonly string[]): void;
100
112
  /** Apply segment `si`'s move. */
101
113
  shift(si: number, at: ShiftAt, ctx: WorkdirContext): void;
@@ -103,6 +115,15 @@ export declare class WorkdirThread {
103
115
  * each with the `PWD`, `OLDPWD` and stack the move leaves — or `lost`. */
104
116
  private movedFrom;
105
117
  }
118
+ /** The walk's state before a segment's moves, where the segment runs apart from the shell after it (a `( … )` group, a
119
+ * pipeline member that is not the last, a background job, a function body): handed back where the scope closes. */
120
+ export interface WorkdirScope {
121
+ readonly candidates: readonly BaseCandidate[];
122
+ readonly lost: boolean;
123
+ readonly floors: readonly string[] | undefined;
124
+ readonly physical: boolean;
125
+ readonly movedAt: number;
126
+ }
106
127
  /** Does bash search `CDPATH` for this `cd` target: not an absolute one, not `.` / `..`, not one starting `./` / `../`? */
107
128
  export declare function searchesCdPath(dir: string): boolean;
108
129
  /** The base shift of a `cd` / `pushd` / `popd` / `dirs` segment, read off its arguments as the program receives them (and