@sema-agent/core 7.46.0 → 7.47.0

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

@@ -2,6 +2,13 @@ import { argvOf, lexShell, literalTildeSpelling, substitutionsInHeredocBody } fr
 import { readProgramPosition } from "./bash-program-position.js";
 import { declaredAttributes, programRow, readArgRoles } from "./program-read-model.js";
 import { codeBodies } from "./shell-reentry-text.js";
+function sameValue(a, b) {
+    if (a.spelled !== b.spelled)
+        return false;
+    if (a.glob !== true || b.glob !== true)
+        return a.glob === b.glob;
+    return a.parts.length === b.parts.length && a.parts.every((p, i) => p.text === b.parts[i].text && p.pattern === b.parts[i].pattern);
+}
 export const SHELL_INTEGER_VARIABLES = new Set([
     "RANDOM", "SECONDS", "LINENO", "OPTIND", "MAILCHECK", "HISTCMD", "SRANDOM", "EPOCHSECONDS", "EPOCHREALTIME", "BASHPID", "BASH_MONOSECONDS",
     "BASH_TRAPSIG", "COLUMNS", "LINES", "SHLVL", "ERRNO", "TMOUT", "HISTSIZE", "SAVEHIST", "TRY_BLOCK_ERROR", "TRY_BLOCK_INTERRUPT", "KEYTIMEOUT",
@@ -199,16 +206,28 @@ function blockStructure(segments) {
 const ONE_WORD = /^[A-Za-z0-9_./+@:%=,-]+$/;
 const WORD_VALUES_MAX = 64;
 export function wordValues(word, table, quoted, overlay = new Map()) {
-    const pieces = word.pieces;
-    if (!pieces.some((p) => p.expansion?.kind === "parameter" || p.expansion?.kind === "tilde"))
+    if (!word.pieces.some((p) => p.expansion?.kind === "parameter" || p.expansion?.kind === "tilde"))
         return undefined;
-    if (table === undefined)
-        return "unknown";
-    const start = pieces[0]?.span[0] ?? 0;
-    const raw = word.raw;
-    let combos = [{ text: "", glob: false }];
-    const stateOf = (name) => overlay.get(name) ?? table.stateOf(name);
-    for (const p of pieces) {
+    return valueOf(word, table, quoted, overlay);
+}
+const runsOf = (v) => (v.glob === true ? v.parts : [{ text: v.spelled, pattern: false }]);
+function joinRuns(runs, more) {
+    const out = [...runs];
+    for (const r of more) {
+        const last = out[out.length - 1];
+        if (last !== undefined && last.pattern && r.pattern)
+            out[out.length - 1] = { text: last.text + r.text, pattern: true, judged: last.judged + r.judged };
+        else if (last !== undefined && !last.pattern && !r.pattern)
+            out[out.length - 1] = { text: last.text + r.text, pattern: false };
+        else if (r.text !== "")
+            out.push(r);
+    }
+    return out;
+}
+export function valueOf(word, table, quoted, overlay = new Map()) {
+    const stateOf = (name) => (table === undefined ? "unknown" : overlay.get(name) ?? table.stateOf(name));
+    let combos = [{ text: "", glob: false, parts: [] }];
+    for (const p of word.pieces) {
         const e = p.expansion;
         let options;
         if (e === undefined) {
@@ -217,10 +236,9 @@ export function wordValues(word, table, quoted, overlay = new Map()) {
             options = [{ spelled: p.literal }];
         }
         else if (e.kind === "glob") {
-            const written = raw === undefined ? undefined : raw.slice(p.span[0] - start, p.span[1] - start);
-            if (written === undefined)
+            if (e.pattern === undefined)
                 return "unknown";
-            options = [{ spelled: written, glob: true }];
+            options = [{ spelled: e.pattern.folded, glob: true, parts: [{ text: e.pattern.written, pattern: true, judged: e.pattern.judged }] }];
         }
         else if (e.kind === "tilde") {
             if (e.body !== "~")
@@ -234,7 +252,7 @@ export function wordValues(word, table, quoted, overlay = new Map()) {
             const state = stateOf(e.name);
             if (state === "unknown")
                 return "unknown";
-            if (p.quotedBy === undefined && !quoted && (table.ifsTouched || state.some((v) => v.glob === true || !ONE_WORD.test(v.spelled))))
+            if (p.quotedBy === undefined && !quoted && (table?.ifsTouched === true || state.some((v) => v.glob === true || !ONE_WORD.test(v.spelled))))
                 return "unknown";
             options = state;
         }
@@ -243,15 +261,17 @@ export function wordValues(word, table, quoted, overlay = new Map()) {
         const next = [];
         for (const c of combos)
             for (const o of options)
-                next.push({ text: c.text + o.spelled, glob: c.glob || o.glob === true });
+                next.push({ text: c.text + o.spelled, glob: c.glob || o.glob === true, parts: joinRuns(c.parts, runsOf(o)) });
         if (next.length > WORD_VALUES_MAX)
             return "unknown";
         combos = next;
     }
     const out = [];
-    for (const c of combos)
-        if (!out.some((v) => v.spelled === c.text && (v.glob === true) === c.glob))
-            out.push(c.glob ? { spelled: c.text, glob: true } : { spelled: c.text });
+    for (const c of combos) {
+        const v = c.glob ? { spelled: c.text, glob: true, parts: c.parts } : { spelled: c.text };
+        if (!out.some((x) => sameValue(x, v)))
+            out.push(v);
+    }
     return out;
 }
 export function wordFloorValues(word, table) {
@@ -284,17 +304,6 @@ export function wordFloorValues(word, table) {
     }
     return combos;
 }
-export function valueOf(word, table, quoted, overlay = new Map()) {
-    const values = wordValues(word, table, quoted, overlay);
-    if (values !== undefined)
-        return values;
-    if (word.pieces.every((p) => p.expansion === undefined && p.literal !== undefined))
-        return [{ spelled: word.pieces.map((p) => p.literal).join("") }];
-    const folded = word.folded;
-    if (folded !== undefined && word.pieces.every((p) => p.expansion === undefined ? p.literal !== undefined : p.expansion.kind === "glob"))
-        return [{ spelled: folded, glob: true }];
-    return "unknown";
-}
 export function bindingEffectOf(segment, argv, shape, readValue) {
     const bindings = [];
     let all = shape.definesFunction ? "reset" : undefined;
@@ -652,7 +661,7 @@ export class BindingThread {
                 return "unknown";
             const values = [];
             const add = (vs) => { for (const v of vs)
-                if (!values.some((x) => x.spelled === v.spelled && x.glob === v.glob))
+                if (!values.some((x) => sameValue(x, v)))
                     values.push(v); };
             for (let i = this.entries.length - 1; i >= 0; i--) {
                 const e = this.entries[i];

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

@@ -557,7 +557,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
                 for (const m of walkedTree.members)
                     out.push({ ...(await canonicalReadOf(candidate, m.path, [m.path], "expansion", folded, m.canonical, signal)), node: m.node, walked: true });
             };
-            for (const lexical of lexicalReadsOf(candidate, boundary)) {
+            for (const [i, lexical] of lexicalReadsOf(candidate, boundary).entries()) {
                 if (lexical.established !== "lexical") {
                     out.push(lexical);
                     continue;
@@ -567,7 +567,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
                 const walked = spellings.find((s) => s !== folded) ?? folded;
                 if (candidate.expands === "glob") {
                     let matched = false;
-                    for (const p of spellings) {
+                    for (const p of candidate.pattern === undefined ? spellings : lexicalReadsOf({ ...candidate, spelled: candidate.pattern }, boundary)[i]?.spellings ?? spellings) {
                         const expanded = await expandGlobCandidate(p, roots, signal);
                         if (expanded !== undefined && "unverifiable" in expanded) {
                             out.push({ candidate, established: "unestablishable", spellings, origin: folded, cause: expanded.unverifiable });
@@ -581,7 +581,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
                                     await land(read, spellings, folded);
                         }
                     }
-                    if (!matched)
+                    if (!matched || candidate.pattern !== undefined)
                         for (const read of await atSeats(walked, spellings, "canonical", undefined, undefined))
                             await land(read, spellings, folded);
                     continue;

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

@@ -49,8 +49,9 @@ export interface ShellReadDeclarations {
     readonly face?: "open" | "roots";
 }
 export interface ReadCandidate {
-    /** The folded word (quotes removed, a literal leading tilde spelled `./~`). */
+    /** The folded word (quotes removed, a literal leading tilde spelled `./~`) — a pattern's name where nothing matches. */
     readonly spelled: string;
+    /** The spelling a pattern's names are matched by where the matcher widens a class (`["!"a]`, `[[:alpha:]]`: any one character). */ readonly pattern?: string;
     /** The raw spelling, quotes retained — where "is this metacharacter quoted" is still answerable. */
     readonly raw: string;
     readonly provenance: ReadCandidateProvenance;

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

@@ -1,12 +1,12 @@
 import { lexShell, PARSE_FAILURE_SENTENCE, substitutionsInHeredocBody, literalTextOf, literalTildeSpelling, } from "../../shell/lex.js";
-import { readOfText, readsOf, rewritten, spelledWithHome, isArithmeticBody, unreadableSentenceOf } from "./shell-read-word.js";
+import { programTextOf, readOfText, readsOf, renamed, rewritten, settledFieldsOf, spelledWithHome, isArithmeticBody, unreadableSentenceOf } from "./shell-read-word.js";
 import { assignmentArithmetic, bare, listedVerbCandidates, pathSubcommandOf, programTextSentence, pushAssignment, roleReads, subscriptOnly, unlistedWords } from "./shell-read-argv.js";
 import { ARITHMETIC_TEST_OPERATORS, BindingThread, arithmeticSubstitutions, isArithmeticCommand, bindingEffectOf, parameterBodySubstitutions, projectSegment, valueOf, } from "./shell-read-bindings.js";
 import { programBasename, programPositionRunsShell, readProgramPosition, shellScanDeclineOf, } from "./bash-program-position.js";
 import { POLL_LOOP_MAX_BEATS, attachedOptionPayloads, resolveOperandLexically, isPathShapedToken, programTextSlotFiles, } from "./bash-readonly-classifier.js";
 import { BLOCK_WORD_NAMES, commandLineOptionSpellings, declaredAttributes, isDeclarationBuiltin, isInertBuiltin, launcherOptionPathRole, launcherOptionStep, readOptionRole, programLanguageOf, programTextOpensOf, selectedOptions, movesBaseUnfollowed, opensNoOperand, programDelivery, programRow, readArgRoles, runsShellText, } from "./program-read-model.js";
 import { isAbsolutePathForm } from "./safety.js";
-import { codeBodies, pipedTextOf, reentryText, scriptFileAt, stdinTextsOf } from "./shell-reentry-text.js";
+import { codeBodies, launchedInput, pipedTextOf, reentryText, scriptFileAt, stdinTextsOf } from "./shell-reentry-text.js";
 export const READ_CANDIDATE_PROVENANCES = Object.freeze([
     "operand",
     "option_value",
@@ -271,7 +271,7 @@ function segmentFacts(segment, p, decl, table, nestedPlan, piped) {
     const each = (c) => {
         const { alternatives, floors, ...one } = c;
         const shadows = (floors ?? []).map((v) => ({ spelled: v.spelled, raw: one.raw, provenance: one.provenance, expands: v.glob === true ? "glob" : false, denyOnly: true }));
-        return [...[one, ...(alternatives ?? []).map((spelled) => ({ ...one, spelled }))].map(unsettle), ...shadows];
+        return [...[one, ...(alternatives ?? []).map((a) => ({ ...renamed(one, a.spelled), ...a }))].map(unsettle), ...shadows];
     };
     const move = facts.baseMove;
     return {
@@ -460,6 +460,20 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
     let reentry;
     if (pos.argvFromStdin)
         reentry = "argv";
+    const reenterShell = (verb, argvs) => {
+        const stdin = stdinTextsOf(segment, piped);
+        const scripts = argvs.flatMap(({ shell, texts: t, args: a }) => [reentryText(shell, t), reentryText(shell, a), ...stdin.map((s) => (s.literal === undefined ? undefined : reentryText(shell, t, s.literal)))]);
+        for (const t of new Set(scripts))
+            if (t !== undefined)
+                nested.push(nestedPlan(t, "later"));
+        for (const { shell, args: a, words } of argvs) {
+            const at = shell === "source" || shell === "." ? a.findIndex((w) => !w.startsWith("-") || w === "-") : scriptFileAt(shell, a);
+            const file = at === undefined ? undefined : words[at];
+            if (file !== undefined)
+                reads.push(bare(file, "operand"));
+        }
+        return done({ empty: false, launcherChain, verb, reentry: "shell", declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), ...(stdin.length > 0 ? { stdin } : {}) });
+    };
     if (pos.refusal !== undefined) {
         const commandLine = commandLineOptionSpellings(programRow(programBasename(pos.refusal.owner)));
         if (pos.refusal.kind === "option_at_program_position" && commandLine.length > 0) {
@@ -472,16 +486,16 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
             }
         }
         if (programPositionRunsShell(pos, runsShellText)) {
-            reentry = "shell";
-            const first = pos.launchers[0]?.index ?? written;
-            const runs = pos.refusal.kind === "control_syntax_at_program_position" ? pos.refusal : undefined;
-            const text = runs?.handsText === true ? toks.slice(first + 1).map((r) => r.folded).filter((w) => !w.startsWith("-") || w === "-").join(" ") : "";
-            const shell = { name: runs?.word ?? "sh", basename: "sh", listed: decl.readers.has("sh") };
-            const stdin = text.length > 0 ? [] : stdinTextsOf(segment, piped);
-            for (const t of new Set([text, ...stdin.map((s) => (s.literal === undefined ? "" : reentryText(shell.basename, [], s.literal) ?? ""))]))
-                if (t.length > 0)
-                    nested.push(nestedPlan(t, "later"));
-            return done({ empty: false, launcherChain, verb: shell, reentry, declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), ...(stdin.length > 0 ? { stdin } : {}) });
+            const launched = launchedInput(p.argv, pos, { text: (k) => literalTextOf(toks[k].word.pieces) ?? programTextOf(toks[k]), folded: (k) => programTextOf(toks[k]), values: (k) => settledFieldsOf(toks[k]) });
+            for (const k of launched.programWords)
+                if (isPathShapedToken(toks[k].folded))
+                    reads.push(bare(toks[k], "program_path"));
+            for (const text of launched.lines)
+                nested.push(nestedPlan(text, "substitution"));
+            const argvs = launched.shells.map((a) => ({ ...a, words: a.words.map((k) => (k === undefined ? undefined : toks[k])) }));
+            if (argvs.length === 0)
+                return done({ empty: false, launcherChain, reentry: "shell", declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}) });
+            return reenterShell({ name: argvs[0].shell, basename: argvs[0].shell, listed: decl.readers.has(argvs[0].shell) }, argvs);
         }
         const from = pos.launchers[0]?.index ?? written;
         unlistedWords(reads, toks, from, launcherIndices, "unlisted_word", ctx);
@@ -493,31 +507,13 @@ function segmentFactsRead(segment, p, decl, table, nestedPlan, piped) {
         return done({ empty: false, launcherChain, ...(reentry !== undefined ? { reentry } : {}), declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}) });
     }
     const argReads = toks.slice(program.index + 1);
-    const args = argReads.map((r) => r.folded);
-    const texts = argReads.map((r) => literalTextOf(r.word.pieces) ?? r.folded);
+    const args = argReads.map(programTextOf);
+    const texts = argReads.map((r) => literalTextOf(r.word.pieces) ?? programTextOf(r));
     const programRead = toks[program.index];
     if (rewritten(programRead) || isPathShapedToken(programRead.folded))
         reads.push(bare(programRead, "program_path"));
-    if (runsShellText(basename)) {
-        reentry = "shell";
-        const stdin = stdinTextsOf(segment, piped);
-        const text = reentryText(basename, texts);
-        const scripts = [text, reentryText(basename, args), ...stdin.map((s) => (s.literal === undefined ? undefined : reentryText(basename, texts, s.literal)))];
-        for (const t of new Set(scripts))
-            if (t !== undefined)
-                nested.push(nestedPlan(t, "later"));
-        if (basename === "source" || basename === ".") {
-            const file = argReads.find((a) => !a.folded.startsWith("-") || a.folded === "-");
-            if (file !== undefined)
-                reads.push(bare(file, "operand"));
-        }
-        else {
-            const file = scriptFileAt(basename, args);
-            if (file !== undefined)
-                reads.push(bare(argReads[file], "operand"));
-        }
-        return done({ empty: false, launcherChain, verb: verb, reentry, declines, reads, moveProvable: false, ...(loopHead !== undefined ? { loopHead } : {}), ...(stdin.length > 0 ? { stdin } : {}) });
-    }
+    if (runsShellText(basename))
+        return reenterShell(verb, [{ shell: basename, texts, args, words: argReads }]);
     const row = programRow(basename);
     const delivery = programDelivery(row, args);
     if (delivery !== undefined)
@@ -665,7 +661,7 @@ function commandStringValue(options, toks, option) {
         return undefined;
     for (const spelling of options) {
         if (option === spelling) {
-            const value = toks[at + 1]?.folded;
+            const value = toks[at + 1] === undefined ? undefined : programTextOf(toks[at + 1]);
             return value === undefined ? undefined : { value, next: at + 2 };
         }
         if (spelling.startsWith("--") && option.startsWith(`${spelling}=`))

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

@@ -5,34 +5,65 @@
  * does to the word before the program sees it.
  */
 import { type LexedCommand, type LexedWord, type WordPiece } from "../../shell/lex.js";
-import { type BindingTable, type BoundValue } from "./shell-read-bindings.js";
+import { type BindingTable, type BoundValue, type FloorValue } from "./shell-read-bindings.js";
 /** `"glob"` = an unquoted pathname-expansion character; `"unresolvable"` = the shell rewrites the word (a brace,
  *  variable or command substitution) so its text is not the path. The read candidate's own field, spelled here. */
 export type WordExpands = false | "glob" | "unresolvable";
-/** A word as the candidate readers name it: the lexer's word, the spelling the program receives — the names the word
- *  refers to read through the binding table ({@link wordValues}: `"$F"` after `F=/x` is `/x`) — and what the shell does to
- *  it before the program sees it. */
+/** A word as the candidate readers name it: the lexer's word, the spelling a reader names it by — the names the word
+ *  refers to read through the binding table ({@link wordValues}: `"$F"` after `F=/x` is `/x`; {@link spellingOf}) — and
+ *  what the shell does to it before the program sees it. A text handed to a shell that re-parses it is the program's
+ *  ({@link programTextOf}), never this one. */
 export interface Read {
     readonly word: LexedWord;
     readonly raw: string;
     readonly folded: string;
+    /** A pattern's names are matched by this spelling where it is not {@link folded} (a class the judge widens, read as
+     *  any one character — {@link LexedWord.judged}, {@link patternOf}); `folded` stays the name opened where none match. */
+    readonly pattern?: string;
     readonly expands: WordExpands;
     /** The names the word refers to were read through the table: its expansion IS the spelling above (and, where the
      *  names may hold several values, {@link values}). */
     readonly settled?: true;
-    /** Every spelling the word may expand to (the first is {@link folded}); present only where there are several. */
-    readonly values?: readonly string[];
+    /** Every value the word may expand to (the first spelled {@link folded}, {@link spellingOf}; matched by {@link pattern}),
+     *  each with the parts of it the shell expands as a pattern ({@link BoundValue}); present wherever the names were read
+     *  through the table ({@link settled}). */
+    readonly values?: readonly BoundValue[];
     /** The word refers to `HOME` and `HOME` may hold something other than the declared home here: the spelling the
      *  word has with the declared home, for the deny judge alone. */
     readonly homeFloor?: string;
     /** The word's names are unknown here, but their bindings left spellings for the deny judge (an array's elements):
      *  what the word may then spell, for the deny judge alone. */
-    readonly floorValues?: readonly BoundValue[];
+    readonly floorValues?: readonly FloorValue[];
 }
 /** The reads of a segment's words against the binding table at that segment (`homeDir` = the declared home, the
  *  state `HOME` starts in). A word that refers to no name, or only to a `HOME` the text has not touched (`~/x`, placed
  *  by the establishment at the declared home), reads as written. */
 export declare function readsOf(words: readonly LexedWord[], table: BindingTable | undefined, homeDir: string | undefined): Read[];
+/** The spelling a reader names a value by, read directly as a path — for a pattern, the name the program opens where it
+ *  matches nothing: its text, a leading `~` spelled as the literal tilde it is ({@link literalTildeSpelling}, the lexer's
+ *  spelling of a written one) — the shell never tilde-expands what a quoted piece or an expansion produced, so a value that
+ *  starts with `~` starts with a literal one (`X=/w; rm \~$X/*` reads `./~/w/*`, as `rm \~/w/*` does). A shell that
+ *  re-parses the value reads {@link programTextOf} instead. */
+export declare const spellingOf: (v: BoundValue) => string;
+/** The spelling a pattern value's names are matched by, where it is not {@link spellingOf}: its runs as a reader judges
+ *  them (a class the judge widens as `?`, the lexer's `WordExpansion.pattern.judged`) — a candidate's
+ *  `pattern`. */
+export declare function patternOf(v: BoundValue): string | undefined;
+/** A candidate under another name (a value of several, a backup, a copy's child): the word's `pattern` matched the word,
+ *  not that name — the name is matched by its own text. */
+export declare function renamed<C extends {
+    readonly spelled: string;
+    readonly pattern?: string;
+}>(c: C, spelled: string): Omit<C, "pattern">;
+/** The text a read's word hands a program, as a shell re-parsing it reads it (`eval`, `sh -c`, a launcher's line): its
+ *  first established value as the program receives it, or the lexer's folded spelling — never {@link spellingOf}'s path
+ *  spelling (`X='~'; eval rm -rf "$X"` re-parses `rm -rf ~`, the home). */
+export declare const programTextOf: (r: Read) => string;
+/** What a read's word hands the program, where the reader knows it: each value its names settled into — one field each
+ *  (an unquoted expansion whose value is not one word is never settled, {@link wordValues}), or, where the word is a
+ *  pattern, the pattern whose matches are the fields, its parts telling pattern characters from literal ones;
+ *  `undefined` for a word the table did not settle (or that names nothing). */
+export declare function settledFieldsOf(r: Read): readonly BoundValue[] | undefined;
 /** The shell REWRITES this read's word before the program sees it (a parameter, command, process, arithmetic or
  *  brace expansion, or the character of one) — a word whose names the table settled excepted: its expansion is its
  *  spelling. */

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

@@ -1,33 +1,51 @@
-import { argvOf, lexShell, UNRESOLVED_SENTENCE } from "../../shell/lex.js";
+import { argvOf, lexShell, literalTildeSpelling, UNRESOLVED_SENTENCE } from "../../shell/lex.js";
 import { expansionInWord, extglobOpenerIn, globInWord, homeExpansionOf } from "./bash-readonly-classifier.js";
 import { wordFloorValues, wordValues } from "./shell-read-bindings.js";
 export function readsOf(words, table, homeDir) {
     return words.map((word) => {
         const refersToName = word.pieces.some((p) => p.expansion?.kind === "parameter");
+        const asWritten = { word, raw: word.raw, folded: word.folded, ...(word.judged !== undefined ? { pattern: word.judged } : {}) };
         if (!refersToName && table?.homeTouched !== true)
-            return { word, raw: word.raw, folded: word.folded, expands: expandsOf(word) };
+            return { ...asWritten, expands: expandsOf(word) };
         const values = wordValues(word, table, false);
         if (values === undefined)
-            return { word, raw: word.raw, folded: word.folded, expands: expandsOf(word) };
+            return { ...asWritten, expands: expandsOf(word) };
         if (values === "unknown") {
             const floors = refersToName ? wordFloorValues(word, table) : [];
-            return { word, raw: word.raw, folded: word.folded, expands: refersToName ? "unresolvable" : expandsOf(word), ...(floors.length > 0 ? { floorValues: floors } : {}) };
+            return { ...asWritten, expands: refersToName ? "unresolvable" : expandsOf(word), ...(floors.length > 0 ? { floorValues: floors } : {}) };
         }
         const glob = values.some((v) => v.glob === true) || globInWord(word);
         const refersToHome = word.pieces.some((p) => p.expansion?.kind === "tilde" || (p.expansion?.kind === "parameter" && p.expansion.name === "HOME"));
         const declared = refersToHome && homeDir !== undefined && table?.homeTouched === true ? wordValues(word, table, false, new Map([["HOME", [{ spelled: homeDir }]]])) : undefined;
-        const floor = declared !== undefined && declared !== "unknown" ? declared[0]?.spelled : undefined;
+        const floor = declared !== undefined && declared !== "unknown" && declared[0] !== undefined ? spellingOf(declared[0]) : undefined;
+        const pattern = patternOf(values[0]);
         return {
             word,
             raw: word.raw,
-            folded: values[0].spelled,
+            folded: spellingOf(values[0]),
+            ...(pattern !== undefined ? { pattern } : {}),
             expands: glob ? "glob" : false,
             settled: true,
-            ...(values.length > 1 ? { values: values.map((v) => v.spelled) } : {}),
-            ...(floor !== undefined && !values.every((v) => v.spelled === floor) ? { homeFloor: floor } : {}),
+            values,
+            ...(floor !== undefined && !values.every((v) => spellingOf(v) === floor) ? { homeFloor: floor } : {}),
         };
     });
 }
+export const spellingOf = (v) => literalTildeSpelling(v.spelled);
+export function patternOf(v) {
+    if (v.glob !== true)
+        return undefined;
+    const judged = literalTildeSpelling(v.parts.map((p) => (p.pattern ? p.judged : p.text)).join(""));
+    return judged === spellingOf(v) ? undefined : judged;
+}
+export function renamed(c, spelled) {
+    const { pattern: _matched, ...rest } = c;
+    return { ...rest, spelled };
+}
+export const programTextOf = (r) => r.values?.[0]?.spelled ?? r.word.folded;
+export function settledFieldsOf(r) {
+    return r.settled === true ? r.values : undefined;
+}
 export const rewritten = (r) => r.settled !== true && expansionInWord(r.word);
 export function readOfText(text) {
     const l = lexShell(text);

package/dist/tools/fs/shell-read-write-targets.js

@@ -1,4 +1,5 @@
 import { denyFloorShadowsOf } from "./shell-read-judge.js";
+import { renamed } from "./shell-read-word.js";
 import { implementationsOf, programRow, selectedOptions, writeReadings } from "./program-read-model.js";
 import { programBasename, readProgramPosition } from "./bash-program-position.js";
 export function programArgs(segment) {
@@ -85,8 +86,8 @@ function backupTargetsOf(edited, readings, override) {
     const suffixes = [...new Set(readings.flatMap((r) => r.suffixes))];
     const follows = override !== undefined && !override.includes("entry");
     return edited.flatMap(({ candidate: f, onlyIfExists }) => suffixes.flatMap((suffix) => follows
-        ? [{ candidate: { ...f, spelled: `${f.spelled}${suffix}`, face: "write" }, seats: ["entry"], followed: { operand: f, suffix }, ...(onlyIfExists !== undefined ? { onlyIfExists } : {}) }]
-        : sedBackupNames(f.spelled, suffix).map((spelled) => ({ candidate: { ...f, spelled, face: "write" }, seats: ["entry"], ...(onlyIfExists !== undefined ? { onlyIfExists } : {}) }))));
+        ? [{ candidate: { ...renamed(f, `${f.spelled}${suffix}`), face: "write" }, seats: ["entry"], followed: { operand: f, suffix }, ...(onlyIfExists !== undefined ? { onlyIfExists } : {}) }]
+        : sedBackupNames(f.spelled, suffix).map((spelled) => ({ candidate: { ...renamed(f, spelled), face: "write" }, seats: ["entry"], ...(onlyIfExists !== undefined ? { onlyIfExists } : {}) }))));
 }
 function copyDestinationChildren(segment, words, readings) {
     const candidateOf = (raw) => segment.reads.find((c) => c.raw === raw && WORD_PROVENANCES.has(c.provenance));
@@ -107,7 +108,7 @@ function copyDestinationChildren(segment, words, readings) {
             const child = `${dest.spelled.replace(/\/+$/, "")}/${src.spelled.replace(/\/+$/, "").split("/").pop() ?? ""}`;
             if (child.endsWith("/") || children.has(child))
                 continue;
-            children.set(child, destCandidate !== undefined && source !== undefined ? { ...destCandidate, spelled: child } : { spelled: child, raw: src.raw, provenance: "unlisted_word", expands: "unresolvable", bases: [] });
+            children.set(child, destCandidate !== undefined && source !== undefined ? renamed(destCandidate, child) : { spelled: child, raw: src.raw, provenance: "unlisted_word", expands: "unresolvable", bases: [] });
         }
     }
     return [...children.values()];

package/dist/tools/fs/shell-reentry-text.d.ts

@@ -5,6 +5,8 @@
  * re-entry (`shell-read-plan.ts`); this module is the one reader of which operand — or which input — that text is.
  */
 import { type LexedSegment, type LexedWord } from "../../shell/lex.js";
+import { type ProgramPosition } from "./bash-program-position.js";
+import type { BoundValue } from "./shell-read-bindings.js";
 /**
  * The code bodies a builtin keeps among its operands, one per body; empty for every other program. The program read
  * model's row says where the body is: the action of a `trap` (its first operand after the options), the value of an
@@ -24,6 +26,102 @@ export declare function codeBodies(basename: string, args: readonly string[]): r
  *  the argv names no text and the program runs its standard input ({@link scriptSourceOf}: the row runs it unnamed, or
  *  the script file named is standard input), the text is `stdin` — one text that may arrive there, as the caller spells it. */
 export declare function reentryText(basename: string, args: readonly string[], stdin?: string): string | undefined;
+/** One argument of the argv a launcher hands the SHELL it runs: a word of the command line passed on as it stands (`at`,
+ *  its argv index; `from` — only the word's characters from there on, an option value attached to its option word), a word
+ *  of the launcher's own (`fixed`: the `-c` in front of a text it builds), or a text it builds from several words
+ *  (`joined`: their argv indices, joined by a space; `escaped` — every character of a word's value but a letter, a digit,
+ *  `_`, `-` and `$` escaped with a backslash, as `sudo -s` builds its shell's `-c` text). */
+export type LaunchedArg = {
+    readonly at: number;
+    readonly from?: number;
+} | {
+    readonly fixed: string;
+} | {
+    readonly joined: readonly number[];
+    readonly escaped?: true;
+};
+/** What a launcher that runs a program named by no word of its own runs: `program` — absent, a SHELL named by no word
+ *  (sudo's, chroot's, the user's login shell `su` runs); `at` — the word naming it (`su -s PROGRAM`, from its `from`-th
+ *  character where the value is attached to its option word); `spelled` — a program the launcher takes from elsewhere,
+ *  as a shell spells it (`su -m`: the caller's `"$SHELL"`) — and the argv it hands that program. */
+export interface LaunchedCommand {
+    readonly program?: {
+        readonly at: number;
+        readonly from?: number;
+    } | {
+        readonly spelled: string;
+    };
+    readonly args: readonly LaunchedArg[];
+}
+/**
+ * What a launcher that runs a program named by no word of its own runs ({@link readProgramPosition}'s `runsShell`: the
+ * launcher, and the first word it hands on), one command per reading of the launcher's row where its implementations
+ * read it differently; empty when no launcher of the segment runs one. A shell's argv is read by that shell's row
+ * ({@link reentryText}, {@link scriptFileAt}): its `-c` text, its script file, else its standard input. By the launcher
+ * row (`LauncherSpec`, program-read-model.ts):
+ *  · no word handed on (`sudo -s`, `chroot DIR`, a bare `su`): the shell is handed nothing;
+ *  · `shellCommand: "escaped"` (`sudo -s CMD…`): `-c` and the words, escaped and joined;
+ *  · `shellText: "joined"` (`watch CMD…`): `-c` and the non-option words, joined — and `-c` with each shell-text value
+ *    attached to its option word (`script -c'CMD'`);
+ *  · `shellText: "user"` (`su [-] [USER [ARG…]]`): per implementation — its first operand past a lone `-` names the user;
+ *    one that reads its options anywhere hands `-c TEXT` for each shell-text value of its own (a command each) and its
+ *    operands after the user, one that stops at the user hands every word after the user. The program is the value of
+ *    its option of role `command` (`-s PROGRAM`), else the program a selected `names-program` switch takes from the
+ *    caller's environment (`-m`: `"$SHELL"`), else the user's login shell.
+ */
+export declare function launchedCommands(argv: readonly LexedWord[], pos?: ProgramPosition): readonly LaunchedCommand[];
+/** How a launched command is read: as a SHELL's argv (`shell`: the shell whose row reads it — a program that runs its
+ *  `-c` text, `sh`, `bash`, `fish`, …, or `sh` for the shell named by no word), as the command line it is (`line`: a
+ *  program that is no shell, `su -s /bin/rm …`, its words as written, so its expansions are the command line's), or
+ *  both — a program the text does not spell (`su -s "$X"`, `su -m`: the caller's `"$SHELL"`) may be any program, a shell
+ *  among them. */
+export declare function launchedReadings(argv: readonly LexedWord[], command: LaunchedCommand): {
+    readonly shell?: string;
+    readonly line?: string;
+};
+/** What a launcher runs ({@link launchedCommands}, {@link launchedReadings}), as a reader of the command line reads it:
+ *  each shell's argv in two spellings — `texts` (a word's literal value, else `spell.text`) and `args` (`spell.folded`) —
+ *  with the argv index each position stands for (`words`), one argv per reading of the values its words may take
+ *  (`spell.values`, {@link spellLaunched}); the word naming a shell (`su -s /bin/bash`, `programWords`); and each command
+ *  line a program that is no shell runs (`lines`, once each). */
+export declare function launchedInput(argv: readonly LexedWord[], pos: ProgramPosition, spell: {
+    readonly text: (k: number) => string;
+    readonly folded: (k: number) => string;
+    readonly values: (k: number) => readonly BoundValue[] | undefined;
+}): {
+    readonly shells: readonly {
+        readonly shell: string;
+        readonly texts: readonly string[];
+        readonly args: readonly string[];
+        readonly words: readonly (number | undefined)[];
+    }[];
+    readonly programWords: readonly number[];
+    readonly lines: readonly string[];
+};
+/** How a reader spells the words of a command line it hands a launched shell ({@link spellLaunched}): `word` — a word as
+ *  it stands, from its `from`-th character; `values` — for a word the shell rewrites before the launcher sees it, the
+ *  values it may take where the reader knows them (each one field, or a pattern whose matches are the fields — its parts
+ *  say which characters the shell expands), `undefined` where it does not; absent — the reader knows none. */
+export interface LaunchedSpelling {
+    readonly word: (at: number, from: number) => string;
+    readonly values?: (at: number) => readonly BoundValue[] | undefined;
+}
+/**
+ * The argv a launched shell is handed ({@link launchedCommands}), spelled as `spell` spells the command line's words — one
+ * argv per reading of the values its words may take. A word an escaping launcher joins (`sudo -s CMD…`) is handed as the
+ * launcher hands it: each FIELD the command line's shell gives the launcher, escaped ({@link sudoEscaped}) — the field a
+ * literal word spells, or each field the shell established for a word it rewrites first (`X='#'; sudo -s rm -r "$X" d`
+ * hands `rm -r \# d`: the value is an operand, never a comment), a pattern's literal characters escaped and its pattern
+ * characters bare ({@link launchedSpellingOf}). A word whose fields the reader does not know is handed AS WRITTEN: the
+ * launched shell re-reads the expansion with the command line's quoting, so the word stays one argument (an unknown there)
+ * and its neighbours stay theirs (`"#$Y" d` is never `#$Y d`). A reading gives each distinct word spelling one value — the
+ * same word spelled twice expands alike — and words with several values are read in every combination of them (a value in
+ * the program's position meets each operand); past {@link LAUNCHED_READINGS_MAX}
+ * combinations reading `i` hands each word its `i`-th value (its last where it holds fewer) — every value of every word is
+ * still read, the same word spelled twice takes one value per reading as the shell expands it, and the readings stay as
+ * many as one word's values: their cost is linear in the command, whatever its length.
+ */
+export declare function spellLaunched(argv: readonly LexedWord[], args: readonly LaunchedArg[], spell: LaunchedSpelling): string[][];
 /** The argv index of the SCRIPT FILE a shell runs where its argv carries no text ({@link scriptSourceOf}). */
 export declare function scriptFileAt(basename: string, args: readonly string[]): number | undefined;
 /** One text that may arrive on a segment's standard input: `from` = its source as written (a here-document's body,