@sema-agent/core 7.46.0 → 7.48.0

package/dist/tools/fs/read-deny-home.js

@@ -3,7 +3,7 @@ import { canonicalizeTarget, isAbsolutePathForm, joinForFamily, normalizeAbsPath
 import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, withGateTimeout } from "../../core/gate-bounded-await.js";
 import { thrownText } from "../../core/thrown-value.js";
 import { agentConfigDirTail } from "../../core/agent-config-dir.js";
-import { readDenyPatternRun, readDenyRunHead } from "./read-deny.js";
+import { isRootedReadDenyPattern, readDenyPatternRun, readDenyRunHead } from "./read-deny.js";
 export const AUXILIARY_HOME_PROBE_MS = 2_000;
 const said = new Set();
 function sayOnce(kind, line) {
@@ -111,7 +111,7 @@ export async function readDenyHomeLinksOf(env, entries, homes, signal, deadline)
         const { homeAnchored, run } = readDenyPatternRun(pattern);
         if (!homeAnchored)
             continue;
-        const head = run.split("/").filter(Boolean).slice(0, readDenyRunHead(run)).join("/");
+        const head = literalHeadOf(run);
         if (head.length === 0)
             continue;
         const spelled = homes.map((home) => normalizeAbsPathLexically(joinForFamily(pathFamilyOf({ root: home }), home, head)));
@@ -119,6 +119,23 @@ export async function readDenyHomeLinksOf(env, entries, homes, signal, deadline)
     }
     return await linkedLocationsOf(env, rows, signal, deadline);
 }
+const ROOT = "/";
+export async function readDenyRootLinksOf(env, entries, signal, deadline) {
+    const rows = [];
+    for (const { pattern, caseSensitive } of entries) {
+        if (!isRootedReadDenyPattern(pattern))
+            continue;
+        const head = literalHeadOf(pattern);
+        if (head.length === 0)
+            continue;
+        const spelled = [normalizeAbsPathLexically(joinForFamily(pathFamilyOf({ root: ROOT }), ROOT, head))];
+        rows.push({ pattern, caseSensitive: caseSensitive === true, spelled, anchored: spelled });
+    }
+    return await linkedLocationsOf(env, rows, signal, deadline);
+}
+function literalHeadOf(run) {
+    return run.split("/").filter(Boolean).slice(0, readDenyRunHead(run)).join("/");
+}
 export async function readDenyConfigRootLinksOf(env, entries, roots, signal, deadline) {
     return await linkedLocationsOf(env, configRootRowsOf(entries, roots), signal, deadline);
 }
@@ -129,7 +146,7 @@ function configRootRowsOf(entries, roots) {
         const tail = homeAnchored ? agentConfigDirTail(run, caseSensitive === true) : undefined;
         if (tail === undefined)
             continue;
-        const head = tail.split("/").filter(Boolean).slice(0, readDenyRunHead(tail)).join("/");
+        const head = literalHeadOf(tail);
         const spelled = roots.map((root) => normalizeAbsPathLexically(head.length === 0 ? root : joinForFamily(pathFamilyOf({ root }), root, head)));
         rows.push({ pattern, caseSensitive: caseSensitive === true, spelled, anchored: [] });
     }
@@ -363,8 +380,12 @@ export async function placeReadDenyAtHome(env, compile, homes, signal, configRoo
     const entries = compile([]).entries;
     const declared = declaredHomeOf(env);
     const relocated = configRoot === undefined ? undefined : readAuxiliaryHome(env, configRoot, { entries, configRoot: true }, signal);
+    const rooted = readDenyRootLinksOf(env, entries, signal);
     const heldAnywhere = async (whole) => {
-        const linked = (await relocated)?.linked ?? new Map();
+        const linked = new Map();
+        for (const map of [(await relocated)?.linked, (await rooted).linked])
+            for (const [pattern, locations] of map ?? [])
+                linked.set(pattern, locations);
         return placementOf(carryHomeViews(linked.size === 0 ? compile([]) : compile([], linked), homeViewSourceOver(env, relocated === undefined ? [] : [relocated])), [], linked, whole);
     };
     const listed = homes === undefined ? declaredReadDenyHomesAnswered(env) : { homes, whole: true };
@@ -379,15 +400,15 @@ export async function placeReadDenyAtHome(env, compile, homes, signal, configRoo
         declaredAt = [...new Set([...own, ...ownSpellings.spellings])];
     }
     const auxiliary = readAuxiliaryHomes(env, listed.homes, { entries }, signal);
-    const [heads, readings, root] = await Promise.all([readDenyHomeLinksOf(env, entries, declaredAt, signal), Promise.all(auxiliary), relocated]);
+    const [heads, readings, root, rootedHeads] = await Promise.all([readDenyHomeLinksOf(env, entries, declaredAt, signal), Promise.all(auxiliary), relocated, rooted]);
     const at = [...new Set([...declaredAt, ...readings.flatMap((r) => r.place)])];
     const linked = new Map();
-    for (const map of [heads.linked, ...readings.map((r) => r.linked), ...(root === undefined ? [] : [root.linked])]) {
+    for (const map of [heads.linked, ...readings.map((r) => r.linked), ...(root === undefined ? [] : [root.linked]), rootedHeads.linked]) {
         for (const [pattern, locations] of map)
             linked.set(pattern, [...new Set([...(linked.get(pattern) ?? []), ...locations])]);
     }
     const matcher = linked.size === 0 ? compile(at) : compile(at, linked);
-    return placementOf(carryHomeViews(matcher, homeViewSourceOver(env, relocated === undefined ? auxiliary : [...auxiliary, relocated])), at, linked, heads.whole);
+    return placementOf(carryHomeViews(matcher, homeViewSourceOver(env, relocated === undefined ? auxiliary : [...auxiliary, relocated])), at, linked, heads.whole && rootedHeads.whole);
 }
 export function readDenyPlacedLater(unplaced, place) {
     let current = unplaced;

package/dist/tools/fs/read-deny.d.ts

@@ -5,7 +5,10 @@
  * unless the pattern opens with the HOME word ({@link READ_DENY_HOME_WORD}): `~/<run>` matches only where
  * the run starts right below the execution environment's home directory (`~/.sema/settings.json` is the
  * home's file, never a project's `.sema/settings.json`). Only a FIRST segment that is exactly `~` is the
- * word; `~user` and a `~` further along are literal segments.
+ * word; `~user` and a `~` further along are literal segments. A pattern that opens with `/` (and is not home-anchored)
+ * is ROOTED, the same kind of anchor with the filesystem root as its place: `/app/config-lkg.json` names the file
+ * at exactly that location, never a project's `app/config-lkg.json` — the run must start at the first segment of an
+ * absolute path (a path that is not absolute is not placed, and the row does not judge it).
  * String shorthand ≡ `{ pattern }`. Matching is ASCII-case-insensitive by default (a case-insensitive
  * filesystem serves `.SSH` and `.ssh` as the same directory); `caseSensitive: true` opts a single
  * entry out. Unicode normalization (NFC/NFD) and volume-level case semantics are NOT modeled (v1
@@ -384,8 +387,9 @@ export interface CompiledSegmentPattern {
     /** The segment lists of the directories the run is ANCHORED at (folded as the pattern folds): the run must start
      *  right after one of them. Absent = the run matches anywhere. */
     anchors?: readonly (readonly string[])[];
-    /** Judged in a ROOTED view only: an extra location of a home-anchored row (where its literal head leads). A view that
-     *  is not rooted cannot be placed and is covered by the row's own run, held anywhere. */
+    /** Judged in a ROOTED view only: an extra location of a home-anchored row (where its literal head leads), or a row that is
+     *  itself rooted (anchored at the filesystem root, {@link ReadDenyEntry}). A view that is not rooted cannot be placed: a
+     *  home-anchored row's own run is held anywhere in it (the row cannot be placed, so it holds wider); these two judge it not. */
     rootedOnly?: true;
 }
 /**
@@ -408,6 +412,9 @@ export declare function compileSegmentPattern(raw: string, fold: "none" | "ascii
 export declare function matchSegmentPatterns(path: string, compiled: readonly CompiledSegmentPattern[], opts?: {
     readonly aliasResolved?: boolean;
 }): string | null;
+/** Is a canonical pattern ROOTED — placed at the filesystem root ({@link ReadDenyEntry})? Only {@link canonicalReadDenyPattern}
+ *  puts a leading `/` on a canonical pattern, so the text is the whole answer. */
+export declare function isRootedReadDenyPattern(canonical: string): boolean;
 /**
  * the PURE validation/canonicality predicate over a PERSISTED deny entry (checkpoint v9
  * face section), for the resume pre-CAS ladder: it must refuse BEFORE the approval CAS everything
@@ -437,9 +444,9 @@ export declare function checkedReadDenyHomes(homes: unknown, seat?: string): rea
  * spellings only — any other shape refuses loudly, naming `readDenyHomes`. EMPTY = the environment declares no
  * home: a home-anchored entry then matches its run anywhere — a row that cannot be placed holds wider, never narrower.
  *
- * `linked` — where a home-anchored row's LITERAL HEAD ({@link readDenyRunHead}) really leads, keyed by the row's
- * pattern: the canonical locations a mount resolved (`readDenyHomeLinksOf`, read-deny-home.ts) where one of the
- * head's segments is a link (`~/.sema` linked into a dotfiles directory). The row is placed at each location too —
+ * `linked` — where a home-anchored or a rooted row's LITERAL HEAD ({@link readDenyRunHead}) really leads, keyed by the row's
+ * pattern: the canonical locations a mount resolved (`readDenyHomeLinksOf` / `readDenyRootLinksOf`, read-deny-home.ts) where
+ * one of the head's segments is a link (`~/.sema` linked into a dotfiles directory; `/app` a link to `/data/app`). The row is placed at each location too —
  * the same row, the same name in every refusal — with the rest of its run matched below it. The read faces judge
  * canonical keys, so every spelling that reaches the linked file meets the row there. Absolute locations only.
  */

package/dist/tools/fs/read-deny.js

@@ -418,7 +418,14 @@ function normalizeEntry(entry, layer) {
         throw new Error(`readDenyPatterns (${layer}): pattern ${JSON.stringify(shape.pattern)} contains no path segments${homeAnchored ? " below the home word" : ""} and would ${homeAnchored ? "name the whole home directory" : "deny nothing"}. ` +
             `Patterns are "/"-separated runs of path SEGMENTS (e.g. ".ssh", ".config/gcloud", "id_rsa*", "~/.sema/settings.json"); remove the entry or spell the segments.`);
     }
-    return { pattern: segments.join("/"), caseSensitive: shape.caseSensitive === true };
+    return { pattern: canonicalReadDenyPattern(shape.pattern), caseSensitive: shape.caseSensitive === true };
+}
+function canonicalReadDenyPattern(pattern) {
+    const joined = pattern.split("/").filter(Boolean).join("/");
+    return pattern.startsWith("/") && !readDenyPatternRun(joined).homeAnchored ? `/${joined}` : joined;
+}
+export function isRootedReadDenyPattern(canonical) {
+    return canonical.startsWith("/");
 }
 export function persistedReadDenyEntryProblem(e) {
     if (typeof e !== "object" || e === null)
@@ -434,7 +441,7 @@ export function persistedReadDenyEntryProblem(e) {
     const segments = pattern.split("/").filter(Boolean);
     if (readDenyPatternRun(segments.join("/")).run.length === 0)
         return "pattern has no path segments";
-    if (segments.join("/") !== pattern)
+    if (canonicalReadDenyPattern(pattern) !== pattern)
         return "pattern is not in canonical a/b form";
     return null;
 }
@@ -473,6 +480,8 @@ export function compileReadDeny(additions = [], layer = "additions", builtin, ru
         const c = compileSegmentPattern(run, fold);
         if (c === null)
             throw new Error(`readDenyPatterns: pattern ${JSON.stringify(e.pattern)} compiled to zero segments.`);
+        if (isRootedReadDenyPattern(e.pattern))
+            return { ...c, raw: e.pattern, anchors: [[]], rootedOnly: true };
         if (!homeAnchored || homeSegments.length === 0)
             return { ...c, raw: e.pattern };
         return { ...c, raw: e.pattern, anchors: homeSegments.map((segs) => (fold === "ascii" ? segs.map(asciiLower) : segs)) };
@@ -483,7 +492,7 @@ export function compileReadDeny(additions = [], layer = "additions", builtin, ru
     normalized.forEach((e, i) => {
         const locations = linked.get(e.pattern);
         const { homeAnchored, run } = readDenyPatternRun(e.pattern);
-        if (locations === undefined || !homeAnchored)
+        if (locations === undefined || !(homeAnchored || isRootedReadDenyPattern(e.pattern)))
             return;
         const c = compiled[i];
         const rest = c.segments.slice(readDenyRunHead(run));

package/dist/tools/fs/removal-targets.js

@@ -2,7 +2,8 @@ import { planShellReads } from "./shell-read-plan.js";
 import { literalTextOf } from "../../shell/lex.js";
 import { createShellReadEstablisher, establishShellReadsLexically } from "./shell-read-establish.js";
 import { isAbsolutePathForm, isWinFormPath, normalizeAbsPathLexically } from "./safety.js";
-import { reentryText } from "./shell-reentry-text.js";
+import { launchedCommands, launchedReadings, reentryText, scriptFileAt, spellLaunched } from "./shell-reentry-text.js";
+import { isShellSyntaxWord, LOOP_LIST_HEADS, readProgramPosition } from "./bash-program-position.js";
 import { bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { programArgs } from "./shell-read-write-targets.js";
 import { implementationsOf, programRow, runsShellText, selectedOptions, writeReadings } from "./program-read-model.js";
@@ -67,7 +68,7 @@ function bindingsOf(plan) {
             if (w.assignment !== undefined)
                 bind(w.assignment.name, w.assignment.settlesWholeName ? literalTextOf(w.assignment.value.pieces) : undefined);
         const [head, name] = segment.argv;
-        if ((head?.folded === "for" || head?.folded === "select") && name !== undefined && NAME.test(name.folded)) {
+        if (isShellSyntaxWord(head, LOOP_LIST_HEADS) && name !== undefined && NAME.test(name.folded)) {
             const at = segment.argv.findIndex((w, i) => i > 1 && w.folded === "in");
             const words = at < 0 ? [undefined] : segment.argv.slice(at + 1).map((w) => literalTextOf(w.pieces));
             for (const v of words.length > 0 ? words : [undefined])
@@ -167,10 +168,28 @@ function runtimeScriptOf(segment) {
     const program = segment.verb;
     if (segment.reentry !== "shell" || program === undefined || !runsShellText(program.basename))
         return undefined;
-    const at = segment.argv.findIndex((w) => w.folded === program.name);
     const MARK = "\u0000";
-    const words = at < 0 ? [] : segment.argv.slice(at + 1).map((w) => literalTextOf(w.pieces) ?? `${MARK}${w.raw}`);
-    const texts = [reentryText(program.basename, words), ...(segment.stdin ?? []).map((s) => reentryText(program.basename, words, s.literal ?? `${MARK}${s.from}`))];
+    const spell = (k, from = 0) => {
+        const w = segment.argv[k];
+        const literal = literalTextOf(w.pieces);
+        return literal !== undefined ? literal.slice(from) : `${MARK}${w.raw.slice(from)}`;
+    };
+    const pos = readProgramPosition(segment.argv);
+    if (pos.program !== undefined && pos.refusal === undefined) {
+        const argv = segment.argv.slice(pos.program.index + 1);
+        const file = scriptFileAt(program.basename, argv.map((w) => w.folded));
+        const source = file === undefined ? undefined : argv[file];
+        if (source !== undefined && source.pieces.length === 1 && source.pieces[0].expansion?.kind === "process")
+            return source.raw;
+        if (pos.argvFromStdin)
+            return segment.text.trim();
+    }
+    const named = pos.program !== undefined && pos.refusal === undefined ? [{ shell: program.basename, words: segment.argv.slice(pos.program.index + 1).map((_, k) => spell(pos.program.index + 1 + k)) }] : [];
+    const launched = launchedCommands(segment.argv, pos).flatMap((c) => {
+        const shell = launchedReadings(segment.argv, c).shell;
+        return shell === undefined ? [] : spellLaunched(segment.argv, c.args, { word: spell }).map((words) => ({ shell, words }));
+    });
+    const texts = [...named, ...launched].flatMap(({ shell, words }) => [reentryText(shell, words), ...(segment.stdin ?? []).map((s) => reentryText(shell, words, s.literal ?? `${MARK}${s.from}`))]);
     const text = texts.find((t) => t?.includes(MARK) === true);
     return text === undefined ? undefined : text.split(MARK).join("");
 }

package/dist/tools/fs/shell-read-argv.d.ts

@@ -7,14 +7,13 @@
  */
 import { type LexedWord } from "../../shell/lex.js";
 import { type Read } from "./shell-read-word.js";
-import { type BindingTable, type BoundValue } from "./shell-read-bindings.js";
+import { type BindingTable, type FloorValue } from "./shell-read-bindings.js";
 import { subcommandOf, type ArgRole, type ProgramRow } from "./program-read-model.js";
 import type { ReadCandidate, ReadCandidateProvenance } from "./shell-read-plan.js";
-/** A candidate before the threading fills its bases. `alternatives`: the other spellings its word may expand to (a name
- *  bound to several values) — one candidate each once the segment's reads are read. */
+/** A candidate before the threading fills its bases. `floors`: the spellings its word's names left for the deny judge
+ *  alone (a word whose names are unknown here). */
 export type Bare = Omit<ReadCandidate, "bases"> & {
-    readonly alternatives?: readonly string[];
-    readonly floors?: readonly BoundValue[];
+    readonly floors?: readonly FloorValue[];
 };
 /** What reading a segment's words found beside its candidates. */
 export interface WordContext {
@@ -35,9 +34,8 @@ export declare function pathSubcommandOf(row: ProgramRow | undefined, args: read
 /** The sentence of inline program text the station does not read. */
 export declare const programTextSentence: (language: string) => string;
 /** One candidate without its bases (filled by the threading pass): the word's spelling — or `spelled`, a caller's
- *  reading of PART of it (an option payload, a `key=value` value) — with the word's own expansion facts. A word whose
- *  names may hold several values offers each as its whole spelling; a PART of such a word is not followed through them
- *  (it is unresolvable). */
+ *  reading of PART of it (an option payload, a `key=value` value) — with the word's own expansion facts. The word is read
+ *  in one reading of the segment's names (`segmentReadingsOf`): its names hold one value each, or are unknown. */
 export declare function bare(r: Read, provenance: ReadCandidateProvenance, spelled?: string): Bare;
 /** The reads one value of a declared role hands over: a candidate per file it names, or — a value the program expands
  *  past the listed bound — the word itself, unresolvable. A mount source is a read the daemon makes of the whole tree

package/dist/tools/fs/shell-read-argv.js

@@ -1,5 +1,5 @@
 import { literalTildeSpelling } from "../../shell/lex.js";
-import { expandsOf, readOfText, rewritten } from "./shell-read-word.js";
+import { expandsOf, partPattern, readOfText, rewritten } from "./shell-read-word.js";
 import { arithmeticSubstitutions } from "./shell-read-bindings.js";
 import { argvProgramOf, attachedOptionPayloads, isPathShapedToken } from "./bash-readonly-classifier.js";
 import { assignmentArgumentsAreNotPaths, evaluatesOperands, messageWords, moduleTailOf, objectPathsOf, opensNoOperand, programRow, programTextMayOpen, programTextOpensOf, readArgs, selectsContentsTraversal, slotValueCandidates, subcommandOf, valuesAreLiteral, walksCwdWithoutOperand, wordsReadBySomeImplementations, } from "./program-read-model.js";
@@ -10,14 +10,13 @@ export function pathSubcommandOf(row, args) {
 export const programTextSentence = (language) => `runs inline ${language} program text, which may open files this station does not read`;
 export function bare(r, provenance, spelled = r.folded) {
     const whole = spelled === r.folded;
-    if (!whole && r.values !== undefined)
-        return { spelled, raw: r.raw, provenance, expands: "unresolvable" };
+    const pattern = whole ? r.pattern : partPattern(r, spelled);
     return {
         spelled,
         raw: r.raw,
         provenance,
         expands: r.expands,
-        ...(whole && r.values !== undefined ? { alternatives: r.values.slice(1) } : {}),
+        ...(pattern !== undefined ? { pattern } : {}),
         ...(whole && r.homeFloor !== undefined ? { floorSpelled: r.homeFloor } : {}),
         ...(whole && r.floorValues !== undefined ? { floors: r.floorValues } : {}),
     };
@@ -62,8 +61,9 @@ export function pushAssignment(reads, w, provenance) {
     if (!settled && unsettled !== undefined)
         reads.push(unsettled);
     const substitutes = a.value.expansions.some((p) => p.expansion?.kind === "command" || p.expansion?.kind === "process" || p.expansion?.kind === "arithmetic");
+    const pattern = named === undefined ? undefined : partPattern({ folded: w.folded, ...(w.judged !== undefined ? { pattern: w.judged } : {}) }, named);
     if (named !== undefined && !substitutes)
-        reads.push({ spelled: named, raw: w.raw, provenance, expands: expandsOf(w) });
+        reads.push({ spelled: named, raw: w.raw, provenance, expands: expandsOf(w), ...(pattern !== undefined ? { pattern } : {}) });
     if (a.value.folded.includes(":"))
         for (const m of a.value.folded.split(":"))
             if (m !== "") {

package/dist/tools/fs/shell-read-bindings.d.ts

@@ -26,12 +26,46 @@
  */
 import { type LexedRedirect, type LexedSegment, type LexedToken, type LexedWord } from "../../shell/lex.js";
 import { type DeclaredAttribute } from "./program-read-model.js";
-/** A value a name may hold: the text it holds, and whether that text is a PATTERN whose matches are the values (a `for`
- *  list word the shell globs before the loop binds it). */
-export interface BoundValue {
+/** A value a name may hold — the text the program receives ({@link spelled}: what a shell re-parsing it reads), literal
+ *  throughout, or a PATTERN whose matches are the values (a `for` list word the shell globs before the loop binds it;
+ *  `spelled` is then the pattern as the program receives it where it matches nothing): `glob`, with its `parts` — the
+ *  value in runs: a literal run (quoted or literal text, a settled value) and a pattern run (glob pieces as written,
+ *  quoting kept, and as a reader judges them — {@link WordExpansion.pattern}). The one producer is the piece walk
+ *  ({@link valueOf}). */
+export type BoundValue = {
+    readonly spelled: string;
+    readonly glob?: never;
+    readonly parts?: never;
+    readonly fields?: readonly string[];
+} | {
+    readonly spelled: string;
+    readonly glob: true;
+    readonly parts: readonly ValuePart[];
+    readonly fields?: never;
+};
+/** One run of a pattern {@link BoundValue}: literal text, or a pattern — the shell expands its characters — `text` as
+ *  written (what a shell re-reading it matches by), `judged` as a reader judges the names it matches. */
+export type ValuePart = {
+    readonly text: string;
+    readonly pattern: false;
+} | {
+    readonly text: string;
+    readonly pattern: true;
+    readonly judged: string;
+};
+/** A spelling the deny judge alone reads ({@link Binding.floor}, {@link wordFloorValues}): a value, or a word as written
+ *  where its names are unknown — nothing re-reads it, so a pattern says no more than that it is one. */
+export interface FloorValue {
     readonly spelled: string;
     readonly glob?: true;
+    /** A pattern's spelling as a reader judges the names it matches, where it is not `spelled` ({@link judgedSpellingOf}). */
+    readonly pattern?: string;
 }
+/** A pattern value's names as a reader judges them, where that is not its spelling: its runs, a class the judge widens
+ *  as `?` (the lexer's `WordExpansion.pattern.judged`), a leading `~` the literal tilde it is. */
+export declare function judgedSpellingOf(v: BoundValue): string | undefined;
+/** A value as a deny-floor spelling, its judged spelling with it. */
+export declare function floorOf(v: BoundValue): FloorValue;
 /** What a name holds at one point of a text: its possible values, or `"unknown"`. */
 type NameState = readonly BoundValue[] | "unknown";
 /**
@@ -58,7 +92,7 @@ export interface Binding {
     readonly scope?: "local" | "unread";
     /** Spellings the name may hold that the deny judge still reads where the name is otherwise unknown (an array's
      *  elements: what `${A[k]}` expands to is one of them). */
-    readonly floor?: readonly BoundValue[];
+    readonly floor?: readonly FloorValue[];
 }
 /** An attribute a declaration gives a name — or every name (`name` absent: the declaration computed it): a later
  *  assignment to it is evaluated as arithmetic (`integer`), stores a case change or an array element (`transformed`), or
@@ -104,27 +138,40 @@ export declare function projectSegment(segment: LexedSegment): ProjectedSegment;
  *  token, a head whose body opens in a later segment). */
 export declare function dropDefinitionHeads(tokens: LexedToken[]): readonly number[];
 /**
- * What a word holds through the names it refers to — `$NAME`, `${NAME}`, a leading `~` (the value of `HOME`):
- *  · `undefined` — it refers to no name (it reads as written);
- *  · its values — every combination of the values its names may hold here (a piece the shell globs keeps its written
- *    pattern, and the value is then a pattern);
+ * What a word holds through the names it refers to — `$NAME`, `${NAME}`, a leading `~` (the value of `HOME`): `undefined`
+ * where it refers to no name (it reads as written), else {@link valueOf}. `table.stateOf` is read after `overlay` (the
+ * names the same segment bound earlier).
+ */
+export declare function wordValues(word: Pick<LexedWord, "pieces">, table: BindingTable | undefined, quoted: boolean, overlay?: ReadonlyMap<string, NameState>, split?: boolean): readonly BoundValue[] | "unknown" | undefined;
+/** The names a word's expansions read as values — a bare `$NAME` / `${NAME}`, and one written inside a bracket the shell
+ *  forms its class from after expanding it ({@link valueOf}) — in the order they stand. */
+export declare function namesIn(word: Pick<LexedWord, "pieces">): string[];
+/**
+ * What a VALUE word holds (an assignment's value, a `for` list word, a word handed to a program) — THE piece walk, the one
+ * producer of {@link BoundValue}s: every combination of the values its pieces take, each field's pattern formed once the
+ * whole field has expanded ({@link formedField}) — a literal piece its text, a glob piece its pattern as written (a bracket
+ * holding an expansion its brackets and its body, the body's names substituted in place), `~` and `$NAME` the values the
+ * table gives:
+ *  · its values — a field the shell globs makes the value a pattern;
  *  · `"unknown"` — a name it refers to is not settled here, it carries an expansion no name answers (a modifier, a
- *    substitution, a brace list, `~user`), an UNQUOTED expansion's value is not one word or `IFS` may have changed
- *    (`quoted` = the whole word is read as one value: an assignment's value, which is never split), or it would list
- *    more than {@link WORD_VALUES_MAX} values.
- * `table.stateOf` is read after `overlay` (the names the same segment bound earlier).
+ *    substitution, a brace list, `~user`), an UNQUOTED expansion's value is no {@link READABLE_VALUE} (or holds
+ *    whitespace outside `split`), `IFS` may have changed (`quoted` = the whole word is read as one value: an assignment's
+ *    value, which is never split), a field is not formed or a split one forms a pattern, or it would list more than
+ *    {@link WORD_VALUES_MAX} values.
+ * `split` = the word is read as the ARGUMENTS it becomes: an unquoted value is split into its words on the default `IFS`
+ * (a value then carries its {@link BoundValue} `fields`).
  */
-export declare function wordValues(word: Pick<LexedWord, "pieces">, table: BindingTable | undefined, quoted: boolean, overlay?: ReadonlyMap<string, NameState>): readonly BoundValue[] | "unknown" | undefined;
+export declare function valueOf(word: Pick<LexedWord, "pieces">, table: BindingTable | undefined, quoted: boolean, overlay?: ReadonlyMap<string, NameState>, split?: boolean): NameState;
 /**
  * The spellings a word the table leaves unknown may still take through the deny floors of the names it refers to
  * ({@link BindingTable.floorOf}) — `${A[k]}`, `${A[@]}`, `$A` reading an array's elements — or through their values where
  * known: for the deny judge alone. Empty where some name it refers to leaves neither.
  */
-export declare function wordFloorValues(word: Pick<LexedWord, "pieces">, table: BindingTable | undefined): readonly BoundValue[];
-/** What a VALUE word holds (an assignment's value, a `for` list word): {@link wordValues}, or — a word referring to no
- *  name — its own text (a word the shell globs is a pattern; one carrying any other expansion holds what the text does
- *  not say). */
-export declare function valueOf(word: Pick<LexedWord, "pieces">, table: BindingTable | undefined, quoted: boolean, overlay?: ReadonlyMap<string, NameState>): NameState;
+export declare function wordFloorValues(word: Pick<LexedWord, "pieces">, table: BindingTable | undefined): readonly FloorValue[];
+/** Where a segment's argv heads a `for` / `select` loop: the index of that bare word, at the segment's start or past the
+ *  bare control words in front of it (`do for x in …`, `then for …` — a loop nested in a body or a branch); `undefined`
+ *  for any other segment. */
+export declare function loopListHeadAt(argv: readonly LexedWord[]): number | undefined;
 /**
  * What ONE segment does to the names (see the module header). `argv` = the segment's argv projection (structure
  * dropped); `readValue` folds a value word against the table (a reader that answers `unknown` gives the names alone).
@@ -153,6 +200,9 @@ export type NameReader = (name: string) => NameState;
 export interface InheritedNames {
     readonly attributes: readonly NameAttribute[];
     readonly references: boolean;
+    /** The deny floors a name starts the text with ({@link BindingTable.floorOf}): what the words handing it this text as
+     *  written may name there — or, for a substitution body, the floors its segment reads. */
+    readonly floors?: ReadonlyMap<string, readonly FloorValue[]>;
 }
 /** What the thread answers for one reader: what a name may hold, and whether a name carries the integer attribute. */
 export interface BindingTable {
@@ -164,7 +214,7 @@ export interface BindingTable {
     /** `HOME` may hold something other than the declared home here. */
     readonly homeTouched: boolean;
     /** Every spelling any binding of this name before here left for the deny judge alone ({@link Binding.floor}). */
-    floorOf(name: string): readonly BoundValue[];
+    floorOf(name: string): readonly FloorValue[];
     /** What a substitution body here starts with. */
     readonly inherited: InheritedNames;
 }
@@ -208,6 +258,8 @@ export declare class BindingThread {
     private readonly blocks;
     /** Segments that are a pipeline member or run in the background. */
     private readonly detached;
+    /** The floors the names start the text with ({@link InheritedNames.floors}). */
+    private readonly startFloors;
     constructor(segments: readonly LexedSegment[], 
     /** What each segment binds, its names alone (a value is the reader's to read). */
     named: readonly BindingEffect[],