@sema-agent/core 7.47.0 → 7.49.0

package/dist/tools/fs/program-read-model.d.ts

@@ -1,3 +1,24 @@
+/**
+ * The PROGRAM READ MODEL — one table that answers "what does this program do with its k-th word", and the readers
+ * every shell face reads it through.
+ *
+ * A row is one program (the basename bash runs; a versioned spelling of an interpreter is its row), carrying every
+ * argument fact the shell faces need: its option grammar (one per implementation where implementations disagree),
+ * the ROLE each option value and each operand plays, whether a form walks a tree, how an interpreter receives the
+ * program it runs, what a launcher steps over before the program it runs, which words a builtin keeps as shell text
+ * to run later. The rows live in `program-read-model.rows.ts`; this module is the schema and the readers.
+ *
+ * Every reader below is a PROJECTION of the same row: the option-slot reading the candidate extraction walks
+ * (`readArgs`), the traversal reading, the program-delivery reading, the launcher step, the program-text reading of a
+ * language the station parses, the message slots, the code bodies. A reader never carries a table of its own; a fact
+ * one reader needs and the row does not state is added to the row, where every other reader sees it too.
+ *
+ * Rows are checked against the real binaries by `test/program-read-model.binary-gate.test.ts`: each declared option
+ * of each row is run, per implementation, on fixtures whose every word is a FIFO, and the words the binary OPENED are
+ * compared with the words the row predicts it opens. A row whose opener cannot be witnessed locally (a daemon, an
+ * object store, a shell builtin) says so in its `witness`, with the reason.
+ */
+import { type WordPiece } from "../../shell/lex.js";
 /** What a datum names: never a file. */
 export declare const DATUM_FORMS: readonly ["count", "pattern", "name-pattern", "label", "message", "delimiter"];
 export type DatumForm = (typeof DATUM_FORMS)[number];
@@ -272,6 +293,23 @@ export interface LauncherSpec {
     readonly requiredOperandSpelling?: RegExp;
     /** A lone `-` in its option section is its own switch (`env -`, the obsolete spelling of `env -i`). */
     readonly bareDash?: true;
+    /** It runs its shell as ANOTHER user ({@link TargetUser}): the user an option of `userWith` names (`sudo -u USER`), or —
+     *  a {@link shellText} `user` launcher — its user operand; root where none is named. The shell's `HOME` is that user's
+     *  home (`target`), or the caller's or that user's as the launcher's policy decides (`policy`: `sudo -s`); a switch of
+     *  `loginWith` (`sudo -i`, `su -l`, su's lone `-` operand) starts it as a LOGIN shell — its `HOME` that user's, and it
+     *  stands in that home. A `names-program` switch (`su -m`) keeps the caller's environment, `HOME` with it. */
+    readonly asUser?: {
+        readonly userWith?: readonly string[];
+        readonly home: "target" | "policy";
+        readonly loginWith: readonly string[];
+    };
+}
+/** The user a launcher runs its shell as ({@link LauncherSpec.asUser}): the name, where a word spells it literally; the
+ *  shell's `HOME` (`caller` — kept; `target` — that user's; `either` — one of the two); whether it is a login shell. */
+export interface TargetUser {
+    readonly name?: string;
+    readonly home: "caller" | "target" | "either";
+    readonly login: boolean;
 }
 /** How a program receives the PROGRAM it runs (an interpreter): an option value, an operand (`operands.positional`),
  *  or standard input when it names none. */
@@ -322,11 +360,9 @@ export interface ProgramRow {
     /** What a declaration builtin does to every name it binds with no switch selected ({@link OptionSpec.assigns}):
      *  `readonly` makes them read-only, as `declare -r` does. */
     readonly assigns?: DeclaredAttribute;
-    /** It moves the working directory in a way the station does not follow (`pushd`). */
-    readonly movesBase?: "unfollowed";
-    /** What it writes to its standard output, read off its operands ({@link printedText}): `words` = its operands joined
-     *  by a space (`echo`), `format` = its one operand as a format (`printf`). */
-    readonly prints?: "words" | "format";
+    /** It moves the working directory through the directory stack (`pushd` / `popd`): the working-directory thread reads
+     *  how (`shell-read-workdir.ts`). */
+    readonly movesBase?: "stack";
     /** A shell block word at the program position: it names no command of its own. */
     readonly syntax?: "block";
     /** Git-style subcommands: the word after the program's own options names one, and the words after it are read by
@@ -366,7 +402,7 @@ export declare function isDeclarationBuiltin(name: string): boolean;
 export declare function declaredAttributes(row: ProgramRow | undefined, args: readonly string[]): ReadonlySet<DeclaredAttribute>;
 /** Opens no file, starts no program and evaluates nothing (a declaration builtin: only bare — its caller checks). */
 export declare function isInertBuiltin(name: string): boolean;
-export declare function movesBaseUnfollowed(name: string): boolean;
+export declare function movesBaseByStack(name: string): boolean;
 /** The LONG-OPTION name carried by a token (`--file=p` → `file`, `--reg` → `reg`); `undefined` for anything that is
  *  not a long option with a non-empty name (`--`, `--=x`, a short option). */
 export declare function longOptionNameOf(tok: string): string | undefined;
@@ -563,6 +599,20 @@ export declare function attachedStdinFile(row: ProgramRow | undefined, tok: stri
 /** The row read under each implementation's grammar alone (one view per grammar), or the row itself when it declares
  *  at most one. A reader that needs to know what ONE implementation does with an argv reads these views. */
 export declare function implementationsOf(row: ProgramRow): readonly ProgramRow[];
+/** What a scan over an argv's option words found: the specs selected, the values they took (argv index; the value
+ *  inside the option word when it is attached), and the operands (argv indices). */
+interface OptionScan {
+    readonly specs: readonly OptionSpec[];
+    /** Each selected option's spelling as its row declares it (`-x`, `--exec`), in step with `specs`. */
+    readonly names: readonly string[];
+    readonly values: readonly {
+        readonly at: number;
+        readonly value?: string;
+        readonly spec: OptionSpec;
+        readonly name: string;
+    }[];
+    readonly operands: readonly number[];
+}
 /**
  * Every option spec an argv selects. A short cluster is read as getopt reads it, scanning left to right: a declared
  * letter is selected; a value-taking letter owns the rest of the token (and the next word, when it ends the token); a
@@ -574,6 +624,14 @@ export declare function implementationsOf(row: ProgramRow): readonly ProgramRow[
  *    option, and a word past `--`, included. The reading a check that only ever refuses takes: it errs to more options.
  */
 export declare function selectedOptions(row: ProgramRow | undefined, args: readonly string[], under?: "one-implementation"): OptionSpec[];
+/** The options ONE implementation's reading of an argv selects ({@link selectedOptions}), named by the spelling its row
+ *  declares them under (`-x`, `--exec`), and the values they take. An option is told apart by its spelling, never by its
+ *  spec: spellings share specs (every switch of a row is one). */
+export declare function selectedSpellings(row: ProgramRow, args: readonly string[]): Pick<OptionScan, "names" | "values">;
+/** Does ONE implementation of a row (`view`, {@link implementationsOf}) reject these option words — a spelling the row
+ *  declares (another implementation's) that this one does not? getopt calls it an invalid option: the program runs
+ *  nothing. */
+export declare function implementationRejects(row: ProgramRow, view: ProgramRow, words: readonly string[]): boolean;
 /** A path role whose effect writes. */
 export type WritingRole = Extract<ArgRole, {
     kind: "path";
@@ -629,14 +687,6 @@ export declare function programDelivery(row: ProgramRow | undefined, args: reado
 /** The language of the program an interpreter row runs: the language of its program operand, or of the first option that
  *  delivers program text or a program file. `undefined` for a row that runs no program text. */
 export declare function programLanguageOf(row: ProgramRow | undefined): string | undefined;
-/**
- * The text a printer row ({@link ProgramRow.prints}) writes to its standard output, read off its argv (the program word
- * excluded; `undefined` = a word whose value the command does not spell). `undefined` wherever the words do not spell the
- * text: such a word, an option the row does not explain, an escape the program may interpret (a backslash: `echo -e`, an
- * `echo` that reads escapes by default, every `printf` format), a format with a directive (`%`) or values to fill it, or a
- * row that prints nothing it is handed.
- */
-export declare function printedText(row: ProgramRow | undefined, args: readonly (string | undefined)[]): string | undefined;
 /**
  * The argv indices some implementation of the row reads as a path it OPENS (an ordinary operand, a value or operand of a
  * reading path role, a program file) while another reads them as something else (program text, a backup suffix, a
@@ -656,22 +706,43 @@ export declare function moduleTailOf(row: ProgramRow | undefined, args: readonly
  *  value exists only attached (spelled bare, it takes nothing), 1 for one that takes the next word; `undefined` for any
  *  other spelling and for an option the walk does not step over. */
 export declare function launcherOptionArity(row: ProgramRow, tok: string): 0 | 1 | undefined;
-/** The PATH role of the value a launcher option spelled EXACTLY takes (`xargs -a FILE`, `strace -o FILE`), or `undefined`
- *  when its value names no path. Such a value is a word the launcher opens or writes, not an operand of its own. */
+/** The PATH role of the value a launcher option word takes (`xargs -a FILE`, `strace -fo FILE`, `strace -oFILE`), or
+ *  `undefined` when its value names no path ({@link readLauncherOption}). Such a value is a word the launcher opens or
+ *  writes, not an operand of its own. */
 export declare function launcherOptionPathRole(row: ProgramRow, tok: string): Extract<ArgRole, {
     kind: "path";
 }> | undefined;
-/** How many tokens one launcher option occupies, or `undefined` where the row does not explain it: an arity-1 option
- *  separated (2), a value fused to its long name or short letter (1); a switch, an attached-only option, or a cluster of
- *  switches (1); a lone `-` where the launcher reads it as its own switch (1). */
+/** Does this launcher option word move the base its program runs in — the directory, the root, or where its word is looked
+ *  up (an option whose value's role is a path with a `base`) — read off the option itself, whether or not its value is
+ *  written (`nsenter -w` bare takes the target process's directory)? In a cluster, a letter up to the first that takes a
+ *  value. `false` for any word the walk does not step. */
+export declare function launcherOptionMovesBase(row: ProgramRow, tok: string): boolean;
+/** How many words one launcher option occupies ({@link readLauncherOption}), or `undefined` where the row does not
+ *  explain it. */
 export declare function launcherOptionStep(row: ProgramRow, tok: string): 1 | 2 | undefined;
 /** Does a launcher that runs a shell ({@link LauncherSpec.shellText}) run one over these words — the words after it —
  *  rather than the program they name? Not where an implementation selects one of its {@link LauncherSpec.programWith}
  *  options (as that implementation reads them: past `--` a word is an operand). */
 export declare function launcherRunsShell(row: ProgramRow, args: readonly string[]): boolean;
+/** The user a launcher runs its shell as ({@link LauncherSpec.asUser}), read off its own words (`words`, as the program
+ *  receives them) by its row's walk: the value of its last `userWith` option, else its user operand (`operand`; a lone `-`
+ *  in front of it starts a login shell, `dash`), else root — a name only where it is spelled as one (`root`, `#0`, a login
+ *  name); `undefined` for a launcher that runs no other user. */
+export declare function targetUserOf(row: ProgramRow, words: readonly string[], operand?: {
+    readonly name?: string;
+    readonly dash: boolean;
+}): TargetUser | undefined;
 /** The spellings of a launcher's command-line options (`env -S` / `--split-string`): the value is a command line the
  *  launcher splits and runs. */
 export declare function commandLineOptionSpellings(row: ProgramRow | undefined): readonly string[];
+/** The command line ONE launcher option word carries, read as getopt reads the word ({@link readLauncherOption}): a
+ *  command-line spelling ({@link commandLineOptionSpellings}) exactly — `"next"`, the next word is the line — or with its
+ *  value after `=` (long) or after the letter (short, `attached`); in a short cluster every letter before the
+ *  command-line letter is a switch the walk steps (`env -vS 'S'`, `env -iS'S'`). `undefined` where the word carries
+ *  none. */
+export declare function commandLineOf(row: ProgramRow, tok: string): {
+    readonly attached: string;
+} | "next" | undefined;
 /** One implementation's reading of where the program text is: the text (every text option's value joined by newlines,
  *  or the first operand), `from-file` (an option names a FILE holding it), `unparsed` (an option the grammar does not
  *  declare, or a text option with nothing left to take), or `none` (no program text at all). */
@@ -699,13 +770,18 @@ export declare function subcommandOf(row: ProgramRow | undefined, words: readonl
     readonly relocated: boolean;
 } | undefined;
 /**
- * The indices of the SETTLED words a row's subcommand reads as message text: the value of its message option attached
- * or as the next word, by its own grammar. The global options are read exactly ({@link subcommandOf}); in the subcommand
- * an unknown long option takes no value, an unknown short letter or an unsettled word takes the next word (which is
- * then never a message).
+ * The indices of the words a row's subcommand reads as message text: the value of its message option attached or as the
+ * next word, by its own grammar. The global options are read exactly ({@link subcommandOf}); in the subcommand an unknown
+ * long option takes no value, an unknown short letter or an unsettled word takes the next word (which is then never a
+ * message). The option word itself is settled; its separate value is a message whether the text settles it or the shell
+ * computes it as ONE argument — every expansion in it a command substitution in double quotes, whose output is one field
+ * (a parameter is not taken so: `"$@"` and `"${a[@]}"` are several).
  */
 export declare function messageWords(program: string, words: readonly {
     readonly folded: string;
     readonly expands: unknown;
+    readonly word?: {
+        readonly expansions: readonly WordPiece[];
+    };
 }[], programIndex: number): Set<number>;
 export {};

package/dist/tools/fs/program-read-model.js

@@ -66,8 +66,8 @@ export function isInertBuiltin(name) {
     const b = programRow(name)?.builtin;
     return b === "inert" || b === "declaration";
 }
-export function movesBaseUnfollowed(name) {
-    return programRow(name)?.movesBase === "unfollowed";
+export function movesBaseByStack(name) {
+    return programRow(name)?.movesBase === "stack";
 }
 export function longOptionNameOf(tok) {
     if (!tok.startsWith("--") || tok.length === 2)
@@ -682,6 +682,16 @@ export function implementationsOf(row) {
 export function selectedOptions(row, args, under) {
     return row === undefined ? [] : [...scanOptions(row, args, under === "one-implementation").specs];
 }
+export function selectedSpellings(row, args) {
+    const scan = scanOptions(row, args, true);
+    return { names: scan.names, values: scan.values };
+}
+export function implementationRejects(row, view, words) {
+    if (view === row)
+        return false;
+    const declares = (n) => (n.startsWith("--") ? mergedTable(view, "long").has(n.slice(2)) : mergedTable(view, n.length === 2 ? "short" : "dashWords").has(n.slice(1)));
+    return selectedSpellings(row, words).names.some((n) => !declares(n));
+}
 function scanOptions(row, args, one) {
     const stopsAtOperand = one && row.grammars[0]?.afterFirstOperand === "operands";
     const shorts = mergedTable(row, "short");
@@ -689,8 +699,10 @@ function scanOptions(row, args, one) {
     const dashWords = mergedTable(row, "dashWords");
     const obsolete = row.grammars.flatMap((g) => (g.obsoleteFirst === undefined ? [] : [g.obsoleteFirst]));
     const specs = [];
+    const names = [];
     const values = [];
     const operands = [];
+    const select = (spec, name) => { specs.push(spec); names.push(name); };
     let endOfOptions = false;
     for (let k = 0; k < args.length; k++) {
         const t = args[k];
@@ -704,7 +716,7 @@ function scanOptions(row, args, one) {
                 for (const ch of t.replace(/^.\d+/, "")) {
                     const spec = o.letters[ch];
                     if (spec !== undefined)
-                        specs.push(spec);
+                        select(spec, `-${ch}`);
                 }
             continue;
         }
@@ -719,13 +731,13 @@ function scanOptions(row, args, one) {
                 endOfOptions = true;
             continue;
         }
-        const take = (spec, attached) => {
+        const take = (spec, name, attached) => {
             if (attached !== undefined) {
-                values.push({ at: k, value: attached, spec });
+                values.push({ at: k, value: attached, spec, name });
                 return;
             }
             if (one && k + 1 < args.length) {
-                values.push({ at: k + 1, spec });
+                values.push({ at: k + 1, spec, name });
                 k++;
             }
         };
@@ -735,22 +747,23 @@ function scanOptions(row, args, one) {
                 continue;
             const eq = t.indexOf("=");
             const exact = longs.get(name);
-            const hits = exact !== undefined ? [exact] : [...longs].filter(([full]) => isLongOptionAbbrevOf(name, full)).map(([, m]) => m);
-            for (const m of hits)
-                specs.push(m.spec);
-            if (hits.length === 1 && (hits[0].arity === 1 || (eq >= 0 && hits[0].arity === "attached")))
-                take(hits[0].spec, eq >= 0 ? t.slice(eq + 1) : undefined);
-            else if (one && eq < 0 && hits.length > 1 && hits.every((m) => m.arity === 1))
+            const hits = exact !== undefined ? [[name, exact]] : [...longs].filter(([full]) => isLongOptionAbbrevOf(name, full));
+            for (const [full, m] of hits)
+                select(m.spec, `--${full}`);
+            const [full, only] = hits[0] ?? [];
+            if (hits.length === 1 && (only.arity === 1 || (eq >= 0 && only.arity === "attached")))
+                take(only.spec, `--${full}`, eq >= 0 ? t.slice(eq + 1) : undefined);
+            else if (one && eq < 0 && hits.length > 1 && hits.every(([, m]) => m.arity === 1))
                 k++;
             continue;
         }
         const word = /^-([A-Za-z_][\w-]+)$/.exec(t)?.[1];
         const dash = word === undefined ? undefined : dashWords.get(word);
         if (dash !== undefined) {
-            specs.push(dash.spec);
+            select(dash.spec, t);
             if (one) {
                 if (dash.arity === 1)
-                    take(dash.spec, undefined);
+                    take(dash.spec, t, undefined);
                 continue;
             }
         }
@@ -761,18 +774,18 @@ function scanOptions(row, args, one) {
                     continue;
                 break;
             }
-            specs.push(m.spec);
+            select(m.spec, `-${t[i]}`);
             if (m.arity === 0)
                 continue;
             const rest = t.slice(i + 1);
             if (rest !== "")
-                values.push({ at: k, value: rest, spec: m.spec });
+                values.push({ at: k, value: rest, spec: m.spec, name: `-${t[i]}` });
             else if (m.arity === 1 || m.arity === "suffix")
-                take(m.spec, undefined);
+                take(m.spec, `-${t[i]}`, undefined);
             break;
         }
     }
-    return { specs, values, operands };
+    return { specs, names, values, operands };
 }
 export function writesPath(role) {
     return role?.kind === "path" && WRITING_EFFECTS.has(role.effect);
@@ -966,21 +979,6 @@ export function programLanguageOf(row) {
             return r.language;
     return undefined;
 }
-export function printedText(row, args) {
-    const words = args.filter((a) => a !== undefined);
-    if (row?.prints === undefined || words.length !== args.length)
-        return undefined;
-    const events = readArgRoles(row, words);
-    const from = events.find((e) => e.kind === "operand" || e.kind === "dash-word-operand")?.at ?? words.length;
-    if (events.some((e) => e.at < from && e.kind === "option" && e.reading === "speculative"))
-        return undefined;
-    const printed = words.slice(from);
-    if (printed.some((w) => w.includes("\\")))
-        return undefined;
-    if (row.prints === "words")
-        return printed.join(" ");
-    return printed.length === 1 && !printed[0].includes("%") ? printed[0] : undefined;
-}
 export function wordsReadBySomeImplementations(row, args) {
     if (row === undefined || row.grammars.length < 2)
         return new Set();
@@ -1021,9 +1019,16 @@ export function moduleTailOf(row, args) {
 }
 function steppableLauncherOption(row, tok) {
     const m = tok.startsWith("--") ? (tok.includes("=") ? undefined : mergedTable(row, "long").get(tok.slice(2))) : tok.length === 2 && tok.startsWith("-") ? mergedTable(row, "short").get(tok[1]) : undefined;
-    if (m === undefined || m.spec.value?.kind === "shell-text" || (m.spec.value?.kind === "path" && m.spec.value.base !== undefined))
+    if (m === undefined || m.spec.value?.kind === "shell-text")
         return undefined;
-    return m.arity === "disputed" ? undefined : m;
+    return m.arity !== "disputed" || takesNoWordBare(row, tok) ? m : undefined;
+}
+function takesNoWordBare(row, spelling) {
+    const key = spelling.startsWith("--") ? spelling.slice(2) : spelling.slice(1);
+    return row.grammars.every((g) => {
+        const s = (spelling.startsWith("--") ? g.long : g.short)[key];
+        return s === undefined || s.arity === 0 || s.arity === "attached";
+    });
 }
 export function launcherOptionArity(row, tok) {
     if (row.grammars.length === 0)
@@ -1033,34 +1038,80 @@ export function launcherOptionArity(row, tok) {
     const m = steppableLauncherOption(row, tok);
     return m === undefined ? undefined : m.arity === 1 ? 1 : 0;
 }
+function readLauncherOption(row, tok) {
+    if (tok === "-")
+        return row.launcher?.bareDash === true ? { step: 1 } : undefined;
+    if (tok === "--")
+        return launcherOptionArity(row, tok) === 0 ? { step: 1 } : undefined;
+    if (tok.startsWith("--")) {
+        const eq = tok.indexOf("=");
+        const m = steppableLauncherOption(row, eq > 2 ? tok.slice(0, eq) : tok);
+        if (m === undefined)
+            return undefined;
+        if (eq > 2)
+            return m.arity === 0 || m.arity === "disputed" ? undefined : { step: 1, valued: m };
+        return m.arity === 1 ? { step: 2, valued: m } : { step: 1 };
+    }
+    if (!/^-[^-]/.test(tok))
+        return undefined;
+    for (let i = 1; i < tok.length; i++) {
+        const m = steppableLauncherOption(row, `-${tok[i]}`);
+        if (m === undefined)
+            return undefined;
+        if (m.arity === 0)
+            continue;
+        if (i + 1 < tok.length)
+            return m.arity === "disputed" ? undefined : { step: 1, valued: m };
+        return m.arity === 1 ? { step: 2, valued: m } : { step: 1 };
+    }
+    return { step: 1 };
+}
 export function launcherOptionPathRole(row, tok) {
-    const role = steppableLauncherOption(row, tok)?.spec.value;
+    const role = readLauncherOption(row, tok)?.valued?.spec.value;
     return role?.kind === "path" ? role : undefined;
 }
-export function launcherOptionStep(row, tok) {
-    if (tok === "-" && row.launcher?.bareDash === true)
-        return 1;
-    const exact = launcherOptionArity(row, tok);
-    if (exact !== undefined)
-        return exact === 1 ? 2 : 1;
-    const eq = tok.startsWith("--") ? tok.indexOf("=") : -1;
-    if (eq > 2 && steppableLauncherOption(row, tok.slice(0, eq))?.arity !== undefined && steppableLauncherOption(row, tok.slice(0, eq)).arity !== 0)
-        return 1;
-    if (/^-[A-Za-z]./.test(tok) && !tok.startsWith("--")) {
-        const first = steppableLauncherOption(row, tok.slice(0, 2));
-        if (first !== undefined && first.arity !== 0)
-            return 1;
+export function launcherOptionMovesBase(row, tok) {
+    const moves = (m) => m?.spec.value?.kind === "path" && m.spec.value.base !== undefined;
+    if (tok === "-" || tok === "--")
+        return false;
+    if (tok.startsWith("--")) {
+        const eq = tok.indexOf("=");
+        return moves(steppableLauncherOption(row, eq > 2 ? tok.slice(0, eq) : tok));
     }
-    if (/^-[A-Za-z]+$/.test(tok) && [...tok.slice(1)].every((ch) => launcherOptionArity(row, `-${ch}`) === 0 && steppableLauncherOption(row, `-${ch}`)?.arity === 0))
-        return 1;
-    return undefined;
+    if (!/^-[^-]/.test(tok))
+        return false;
+    for (let i = 1; i < tok.length; i++) {
+        const m = steppableLauncherOption(row, `-${tok[i]}`);
+        if (m === undefined)
+            return false;
+        if (moves(m))
+            return true;
+        if (m.arity !== 0)
+            return false;
+    }
+    return false;
+}
+export function launcherOptionStep(row, tok) {
+    return readLauncherOption(row, tok)?.step;
 }
 export function launcherRunsShell(row, args) {
     const l = row.launcher;
     if (l?.shellText === undefined)
         return false;
-    const specs = new Set((l.programWith ?? []).map((s) => (s.startsWith("--") ? mergedTable(row, "long").get(s.slice(2)) : mergedTable(row, "short").get(s.slice(1)))?.spec));
-    return !implementationsOf(row).some((view) => selectedOptions(view, args, "one-implementation").some((o) => specs.has(o)));
+    const programWith = l.programWith ?? [];
+    return !implementationsOf(row).some((view) => selectedSpellings(view, args).names.some((n) => programWith.includes(n)));
+}
+export function targetUserOf(row, words, operand) {
+    const as = row.launcher?.asUser;
+    if (as === undefined)
+        return undefined;
+    const own = selectedSpellings(row, words);
+    const user = own.values.filter((v) => as.userWith?.includes(v.name) === true).at(-1);
+    const named = user !== undefined ? user.value ?? words[user.at] : operand === undefined ? "root" : operand.name;
+    const login = operand?.dash === true || own.names.some((n) => as.loginWith.includes(n));
+    const keepsCaller = selectedOptions(row, words).some((o) => o.mode === "names-program");
+    const name = named === "#0" ? "root" : named !== undefined && /^[A-Za-z_][A-Za-z0-9_.-]*$/.test(named) ? named : undefined;
+    return { ...(name !== undefined ? { name } : {}), home: login ? "target" : as.home === "policy" ? "either" : keepsCaller ? "caller" : "target", login };
 }
 export function commandLineOptionSpellings(row) {
     if (row === undefined)
@@ -1070,6 +1121,25 @@ export function commandLineOptionSpellings(row) {
         ...[...mergedTable(row, "long")].filter(([, m]) => m.spec.value?.kind === "shell-text").map(([n]) => `--${n}`),
     ];
 }
+export function commandLineOf(row, tok) {
+    const lines = new Set(commandLineOptionSpellings(row));
+    if (tok.startsWith("--")) {
+        const eq = tok.indexOf("=");
+        if (!lines.has(eq > 2 ? tok.slice(0, eq) : tok))
+            return undefined;
+        return eq > 2 ? { attached: tok.slice(eq + 1) } : "next";
+    }
+    if (!/^-[^-]/.test(tok))
+        return undefined;
+    for (let i = 1; i < tok.length; i++) {
+        const letter = `-${tok[i]}`;
+        if (lines.has(letter))
+            return i + 1 < tok.length ? { attached: tok.slice(i + 1) } : "next";
+        if (steppableLauncherOption(row, letter)?.arity !== 0)
+            return undefined;
+    }
+    return undefined;
+}
 export function readProgramTextLanguage(row) {
     const first = row?.operands?.positional?.[0];
     return first?.kind === "program-text" && READ_LANGUAGES.has(first.language) ? first.language : undefined;
@@ -1203,12 +1273,16 @@ export function messageWords(program, words, programIndex) {
     const j = programIndex + 1 + found.at;
     const sub = found.row.grammars[0];
     const settled = (k) => words[k] !== undefined && words[k].expands === false;
+    const oneArgument = (k) => {
+        const pieces = words[k]?.word?.expansions ?? [];
+        return pieces.length > 0 && pieces.every((p) => p.expansion?.kind === "command" && p.expansion.yields === "one");
+    };
     const longValues = Object.entries(sub.long).filter(([, s]) => s.arity === 1);
     let pending;
     for (let k = j + 1; k < words.length; k++) {
         const w = words[k].folded;
         if (pending !== undefined) {
-            if (pending === "message" && settled(k))
+            if (pending === "message" && (settled(k) || oneArgument(k)))
                 out.add(k);
             pending = undefined;
             continue;

package/dist/tools/fs/program-read-model.rows.d.ts

@@ -1,17 +1,3 @@
-/**
- * The rows of the program read model (`program-read-model.ts` is the schema and the readers). One row per program
- * bash can run at a segment's program position, grouped by family. Every row is DATA: adding a program, an option or
- * an implementation is a row edit, never a reader branch.
- *
- * How a row is written:
- *  · an option is declared with its arity and, where it is known, the ROLE of its value; a value whose role is not
- *    known is declared by arity alone, and every reader then reads that option the speculative way;
- *  · where two implementations of one program disagree, the row carries one grammar per implementation, and the
- *    readers combine them (a short letter whose arity they dispute is read as nothing; a disputed long name as
- *    optional-valued; a spelling one implementation does not declare is one it rejects, opening nothing);
- *  · a row is checked against the real binaries by the gate (`test/program-read-model.binary-gate.test.ts`);
- *    a row the gate cannot run says why in `witness`.
- */
 import type { ProgramRow } from "./program-read-model.js";
 /** The time a launcher waits (`timeout 5s …`): a number with an optional unit. */
 export declare const DURATION_SPELLING: RegExp;

package/dist/tools/fs/program-read-model.rows.js

@@ -1,3 +1,4 @@
+import { shellWordsOf } from "../../shell/shell-words.js";
 const READ = { kind: "path", effect: "read" };
 const WRITE = { kind: "path", effect: "write" };
 const CREATED = { kind: "path", effect: "create" };
@@ -391,7 +392,7 @@ const launchers = [
             optional: { "-i": LABEL, "-l": COUNT, "--replace": LABEL, "--eof": LABEL, "--max-lines": COUNT },
         }, {}), { reads: { "-a": val(READ, { delivers: "operands" }), "--arg-file": val(READ, { delivers: "operands" }) } }, { lacks: ["-d", "-i", "-l", "-a", "--arg-file", "--null", "--no-run-if-empty", "--verbose", "--exit", "--interactive", "--open-tty", "--show-limits", "--help", "--version", "--max-args", "--max-procs", "--delimiter", "--max-chars", "--process-slot-var", "--replace", "--eof", "--max-lines"] }), launcher: {}, reentry: { kind: "argv", defaultProgram: "echo" }, witness: BINARY },
     launcher("busybox"),
-    launcher("sudo", { assignmentOperands: true, shellCommand: "escaped" }, launcherGrammar({
+    launcher("sudo", { assignmentOperands: true, shellCommand: "escaped", asUser: { userWith: ["-u", "--user"], home: "policy", loginWith: ["-i", "--login"] } }, launcherGrammar({
         switches: ["-A", "-b", "-E", "-H", "-K", "-k", "-l", "-n", "-P", "-S", "-V", "-v", "--askpass", "--background", "--preserve-env", "--set-home", "--remove-timestamp", "--reset-timestamp", "--list", "--non-interactive", "--preserve-groups", "--stdin", "--version", "--validate", "--bell", "--help"],
         shells: ["-i", "-s", "--login", "--shell"],
         values: {
@@ -399,10 +400,10 @@ const launchers = [
             "--user": LABEL, "--group": LABEL, "--other-user": LABEL, "--close-from": COUNT, "--chdir": WORKDIR, "--host": LABEL, "--prompt": LABEL, "--role": LABEL, "--chroot": ROOTDIR, "--type": LABEL, "--command-timeout": COUNT, "--auth-type": LABEL,
         },
     }, { stepsDashDash: true }), { witness: PRIVILEGED }),
-    launcher("doas", {}, launcherGrammar({ switches: ["-L", "-n"], shells: ["-s"], values: { "-a": LABEL, "-u": LABEL, "-C": READ } }, { stepsDashDash: true }), { witness: PRIVILEGED }),
+    launcher("doas", { asUser: { userWith: ["-u"], home: "target", loginWith: [] } }, launcherGrammar({ switches: ["-L", "-n"], shells: ["-s"], values: { "-a": LABEL, "-u": LABEL, "-C": READ } }, { stepsDashDash: true }), { witness: PRIVILEGED }),
     launcher("pkexec", { whenNoProgram: "shell" }, launcherGrammar({ switches: ["--disable-internal-agent", "--keep-cwd", "--version", "--help"], values: { "--user": LABEL } }), { witness: PRIVILEGED }),
-    { key: "su", grammars: implementations(SU, { afterFirstOperand: "options" }, { lacks: SU_LINUX_ONLY, afterFirstOperand: "operands" }), launcher: { shellText: "user" }, witness: PRIVILEGED },
-    { key: "runuser", grammars: [launcherGrammar({ ...SU_OPTIONS, values: { ...SU_OPTIONS.values, "-u": LABEL, "--user": LABEL } }, { afterFirstOperand: "options", stepsDashDash: true })], launcher: { shellText: "user", programWith: ["-u", "--user"] }, witness: PRIVILEGED },
+    { key: "su", grammars: implementations(SU, { afterFirstOperand: "options" }, { lacks: SU_LINUX_ONLY, afterFirstOperand: "operands" }), launcher: { shellText: "user", asUser: { home: "target", loginWith: ["-l", "--login"] } }, witness: PRIVILEGED },
+    { key: "runuser", grammars: [launcherGrammar({ ...SU_OPTIONS, values: { ...SU_OPTIONS.values, "-u": LABEL, "--user": LABEL } }, { afterFirstOperand: "options", stepsDashDash: true })], launcher: { shellText: "user", programWith: ["-u", "--user"], asUser: { home: "target", loginWith: ["-l", "--login"] } }, witness: PRIVILEGED },
     launcher("chroot", { requiredOperands: 1, whenNoProgram: "shell" }, undefined, { witness: PRIVILEGED }),
     launcher("setpriv", {}, undefined, { witness: PRIVILEGED }),
     launcher("nohup", {}, grammar({}, BANNERS)),
@@ -420,7 +421,15 @@ const launchers = [
     { key: "stdbuf", grammars: implementations(grammar({ i: val(LABEL), o: val(LABEL), e: val(LABEL) }, { input: val(LABEL), output: val(LABEL), error: val(LABEL), ...BANNERS }), {}, { lacks: ["--input", "--output", "--error", "--help", "--version"] }), launcher: {}, witness: BINARY },
     launcher("timeout", { requiredOperands: 1, requiredOperandSpelling: DURATION_SPELLING }, grammar({ v: SWITCH, k: val(COUNT), s: val(LABEL) }, { foreground: SWITCH, "preserve-status": SWITCH, verbose: SWITCH, "kill-after": val(COUNT), signal: val(LABEL), ...BANNERS })),
     { key: "time", grammars: implementations(grammar({ p: SWITCH, a: SWITCH, v: SWITCH, q: SWITCH, f: val(LABEL), o: val(WRITE) }, { portability: SWITCH, append: SWITCH, verbose: SWITCH, quiet: SWITCH, help: SWITCH, version: SWITCH, format: val(LABEL), output: val(WRITE) }, { stepsDashDash: true }), {}, { lacks: ["-v", "-q", "-f", "--portability", "--append", "--verbose", "--quiet", "--help", "--version", "--format", "--output"] }), launcher: {}, witness: BINARY },
-    launcher("watch", { shellText: "joined" }, undefined, { witness: SHELL_TEXT_LAUNCHER }),
+    { key: "watch", grammars: [
+            launcherGrammar({
+                switches: ["-b", "-C", "-c", "-e", "-f", "-g", "-h", "-p", "-r", "-t", "-w", "-v", "-x", "--beep", "--color", "--no-color", "--errexit", "--follow", "--chgexit", "--exec", "--precise", "--no-rerun", "--no-title", "--no-wrap", "--help", "--version"],
+                banners: ["-h", "-v"],
+                values: { "-n": COUNT, "--interval": COUNT, "-q": COUNT, "--equexit": COUNT, "-s": WRITE, "--shotsdir": WRITE },
+                optional: { "-d": LABEL, "--differences": LABEL },
+            }, { afterFirstOperand: "operands", stepsDashDash: true }),
+            launcherGrammar({ switches: ["-d", "-t"], values: { "-n": COUNT } }, { afterFirstOperand: "operands", stepsDashDash: true }),
+        ], launcher: { shellText: "joined", programWith: ["-x", "--exec"] }, witness: SHELL_TEXT_LAUNCHER },
     launcher("setsid", {}, launcherGrammar({ switches: ["-c", "-f", "-w", "--ctty", "--fork", "--wait", "--help", "--version"] })),
     launcher("flock", { requiredOperands: 1 }, launcherGrammar({
         switches: ["-s", "-x", "-u", "-n", "-o", "-F", "--shared", "--exclusive", "--unlock", "--nonblock", "--nb", "--close", "--no-fork", "--verbose", "--help", "--version"],
@@ -496,7 +505,7 @@ const git = {
 const noPath = (key, rest, extra = {}) => ({ key, grammars: [], operands: { rest }, witness: BINARY, ...extra });
 const BUILTIN_ONLY = { declared: "a shell builtin with no binary of its own on every host: its words are read by the shell" };
 const noPathRows = [
-    noPath("pwd", LABEL, { builtin: "inert" }), noPath("echo", LABEL, { builtin: "inert", grammars: [grammar(switches("neE"), {}, { afterFirstOperand: "operands" })], prints: "words" }), noPath("printf", LABEL, { grammars: [grammar({ v: val(BINDS_NAME) })], prints: "format" }), noPath("whoami", LABEL), noPath("uname", LABEL),
+    noPath("pwd", LABEL, { builtin: "inert" }), noPath("echo", LABEL, { builtin: "inert", grammars: [grammar(switches("neE"), {}, { afterFirstOperand: "operands" })] }), noPath("printf", LABEL, { grammars: [grammar({ v: val(BINDS_NAME) })] }), noPath("whoami", LABEL), noPath("uname", LABEL),
     noPath("which", LABEL), noPath("basename", LABEL), noPath("dirname", LABEL),
     { key: "tr", grammars: [], operands: { rest: LABEL, stdinBelow: "always" }, witness: BINARY },
     noPath("cal", COUNT), noPath("uptime", LABEL), noPath("id", LABEL), noPath("groups", LABEL), noPath("nproc", LABEL), noPath("locale", LABEL),
@@ -575,6 +584,7 @@ const stdinReaders = [
 ];
 const SYNTAX = { declared: "shell syntax, not a program: read by the lexer" };
 const block = (key, g = []) => ({ key, grammars: g, syntax: "block", witness: SYNTAX });
+const BLOCK_GRAMMARS = { "[[": [grammar({ v: val(BINDS_NAME) })] };
 export const PROGRAM_ROWS = [
     head, tail, cut, grepRow("grep"), grepRow("egrep"), grepRow("fgrep"), diff, cmp, sed, date, tar, find, curl,
     ls, walker("du", "names", true), walker("rg", "contents", false), walker("tree", "names", true), walker("ag", "contents", false), walker("ack", "contents", false),
@@ -614,11 +624,9 @@ export const PROGRAM_ROWS = [
     ...nameBinders,
     ...["make", "gmake", "bmake", "cmake", "ninja", "meson"].map(assignmentNotPaths),
     containerRuntime("docker"), containerRuntime("podman"),
-    { key: "pushd", grammars: [], movesBase: "unfollowed", witness: BUILTIN_ONLY },
-    { key: "popd", grammars: [], movesBase: "unfollowed", witness: BUILTIN_ONLY },
+    ...[...shellWordsOf("stack_mover")].map((key) => ({ key, grammars: [], movesBase: "stack", witness: BUILTIN_ONLY })),
     ...SHELLS.map((s) => shellRow(s, "c-option", BINARY, [SHELL_GRAMMARS[s]], "script")),
     shellRow("eval", "words", BUILTIN_ONLY), shellRow("source", "file-operand", BUILTIN_ONLY), shellRow(".", "file-operand", BUILTIN_ONLY), shellRow("parallel", "non-option-words", BINARY, [], "script"),
     ...codeBodyRows,
-    ...["for", "select", "case", "esac", "fi", "done", "function", "coproc", "]]", "in"].map((k) => block(k)),
-    block("[[", [grammar({ v: val(BINDS_NAME) })]),
+    ...[...shellWordsOf("block")].map((k) => block(k, BLOCK_GRAMMARS[k])),
 ];