@sema-agent/core 7.46.0 → 7.48.0

package/dist/tools/fs/bash-program-position.js

@@ -1,5 +1,5 @@
 import { SHELL_CONTROL_PREFIXES } from "../../shell/lex.js";
-import { BLOCK_WORD_NAMES, LAUNCHER_NAMES, feedsArgvFromStdin, launcherOptionStep, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
+import { BLOCK_WORD_NAMES, LAUNCHER_NAMES, feedsArgvFromStdin, launcherOptionStep, launcherRunsShell, programRow, selectedOptions, streamDefaultProgram } from "./program-read-model.js";
 export const NOT_AUTO_ALLOWED = "— not auto-allowed";
 export function programBasename(word) {
     return word.includes("/") ? (word.split("/").pop() ?? word) : word;
@@ -16,9 +16,12 @@ export function writtenAssignmentPrefix(token) {
 }
 export { SHELL_CONTROL_PREFIXES };
 export function isBareControlWord(words, i, set) {
-    const w = words[i];
-    return w !== undefined && w.raw === w.folded && set.has(w.folded);
+    return isShellSyntaxWord(words[i], set);
+}
+export function isShellSyntaxWord(w, set) {
+    return w !== undefined && w.atCommandPosition && w.raw === w.folded && set.has(w.folded);
 }
+export const LOOP_LIST_HEADS = new Set(["for", "select"]);
 export function isLeadingAssignmentWord(words, i) {
     const w = words[i];
     return w !== undefined && w.assignment !== undefined && w.assignment.bare && w.atCommandPosition;
@@ -79,12 +82,12 @@ export function readProgramPosition(words) {
     }
     const launchers = [{ index: i, name: basename }];
     const owner = head;
-    const shellRefusal = (handsText) => ({ kind: "control_syntax_at_program_position", owner, word: "sh", runsShell: true, ...(handsText !== undefined ? { handsText } : {}) });
+    const shellRefusal = (launcher, from) => ({ kind: "control_syntax_at_program_position", owner, word: "sh", runsShell: { launcher, from } });
     let lastRow = launcherRowOf(basename)?.launcher;
     let owedOperands = lastRow?.requiredOperands ?? 0;
     const chain0 = (program, refusal) => ({ controlWords, written, assignments, launchers, argvFromStdin: false, runsDefaultProgram: false, program, refusal });
-    if (lastRow?.shellText === true)
-        return chain0(undefined, shellRefusal(true));
+    if (launcherRunsShell(launcherRowOf(basename), folded.slice(i + 1)))
+        return chain0(undefined, shellRefusal(i, i + 1));
     let argvFromStdin = feedsArgvFromStdin(basename);
     let lastReentry = argvFromStdin ? i : -1;
     let reentryDefault = argvFromStdin ? streamDefaultProgram(basename) : undefined;
@@ -92,6 +95,7 @@ export function readProgramPosition(words) {
         const runsDefaultProgram = lastReentry === folded.length - 1;
         return { controlWords, written, assignments, launchers, argvFromStdin, runsDefaultProgram, ...(runsDefaultProgram && reentryDefault !== undefined ? { defaultProgram: reentryDefault } : {}), program, refusal };
     };
+    const selectsShell = (l, end) => selectedOptions(launcherRowOf(l.name), folded.slice(l.index + 1, end)).some((o) => o.mode === "interactive");
     for (let j = pastLauncherOptions(basename, folded, i + 1); j < folded.length; j++) {
         const t = folded[j];
         if (owedOperands > 0 && !t.startsWith("-")) {
@@ -100,6 +104,8 @@ export function readProgramPosition(words) {
         }
         if (lastRow?.assignmentOperands === true && !t.startsWith("-") && t.includes("="))
             continue;
+        if (lastRow?.shellCommand !== undefined && !t.startsWith("-") && selectsShell(launchers[launchers.length - 1], j))
+            return chain(undefined, shellRefusal(launchers[launchers.length - 1].index, j));
         const wordBasename = programBasename(t);
         if (feedsArgvFromStdin(wordBasename)) {
             argvFromStdin = true;
@@ -112,8 +118,8 @@ export function readProgramPosition(words) {
         if (LAUNCHER_NAMES.has(wordBasename)) {
             launchers.push({ index: j, name: wordBasename });
             lastRow = launcherRowOf(wordBasename)?.launcher;
-            if (lastRow?.shellText === true)
-                return chain(undefined, shellRefusal(true));
+            if (launcherRunsShell(launcherRowOf(wordBasename), folded.slice(j + 1)))
+                return chain(undefined, shellRefusal(j, j + 1));
             owedOperands = lastRow?.requiredOperands ?? 0;
             j = pastLauncherOptions(wordBasename, folded, j + 1) - 1;
             continue;
@@ -126,8 +132,8 @@ export function readProgramPosition(words) {
         return chain({ index: j, name: t, basename: wordBasename });
     }
     const last = launchers[launchers.length - 1];
-    if (lastRow?.whenNoProgram === "shell" || selectedOptions(launcherRowOf(last.name), folded.slice(last.index + 1)).some((o) => o.mode === "interactive"))
-        return chain(undefined, shellRefusal());
+    if (lastRow?.whenNoProgram === "shell" || selectsShell(last, folded.length))
+        return chain(undefined, shellRefusal(last.index, folded.length));
     return chain(undefined);
 }
 export function argvReentryUnjudged(pos, acceptsTarget) {
@@ -139,12 +145,12 @@ export function argvReentryUnjudged(pos, acceptsTarget) {
 export const SHELL_SCAN_DECLINES = Object.freeze(["unreadable_program_position", "stream_fed_operands"]);
 export function programPositionRunsShell(pos, runsShell) {
     if (pos.refusal !== undefined)
-        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell === true;
+        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell !== undefined;
     return pos.program !== undefined && runsShell(pos.program.basename);
 }
 export function shellScanDeclineOf(pos, acceptsStreamTarget) {
     if (pos.refusal !== undefined) {
-        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell === true ? undefined : "unreadable_program_position";
+        return pos.refusal.kind === "control_syntax_at_program_position" && pos.refusal.runsShell !== undefined ? undefined : "unreadable_program_position";
     }
     return argvReentryUnjudged(pos, acceptsStreamTarget) ? "stream_fed_operands" : undefined;
 }

package/dist/tools/fs/index.d.ts

@@ -187,8 +187,9 @@ export interface HandsToolkitOptions {
      *  under a short bound of its own, and a probe of it that fails costs that entry alone. The public shell judgment takes the
      *  same list as {@link import("./shell-read-check.js").ShellReadJudgeInput.readDenyHomes}. */
     readDenyHomes?: readonly string[];
-    /** Where each home-anchored row's literal head leads beyond the home's spellings
-     *  ({@link import("./read-deny-home.js").readDenyHomeLinksOf}, keyed by the row's pattern) — the Runner passes the
+    /** Where each home-anchored row's literal head leads beyond the home's spellings, and each rooted row's (`/…`) beyond its own
+     *  spelling ({@link import("./read-deny-home.js").readDenyHomeLinksOf} / {@link import("./read-deny-home.js").readDenyRootLinksOf},
+     *  keyed by the row's pattern) — the Runner passes the
      *  locations its own judge was compiled with, so the band and the gate judge one placement.
      *  Unless a mount carries both, the band resolves the placement itself the way the Runner does (the homes it carries
      *  are its home set — the account is not asked and no home is added;

package/dist/tools/fs/index.js

@@ -14,7 +14,7 @@ export * from "./read-deny.js";
 export { readDenyHomesOf } from "./read-deny-home.js";
 import { BASH_READONLY_DEFAULT_ALLOW } from "./bash-readonly-classifier.js";
 export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
-import { checkedReadDenyHomes, compileReadDeny, compileWriteDeny, readDenyBuiltinConfigOf, readDenyPatternRun } from "./read-deny.js";
+import { checkedReadDenyHomes, compileReadDeny, compileWriteDeny, isRootedReadDenyPattern, readDenyBuiltinConfigOf, readDenyPatternRun } from "./read-deny.js";
 import { withGateTimeout } from "../../core/gate-bounded-await.js";
 import { carryHomeViews, homeViewsAt, placeReadDenyAtHome, placementViewsOf, readDenyPlacedLater, sayPlacementLost } from "./read-deny-home.js";
 import { deploymentFaceClampNotice, resolveContainmentFace } from "./containment-face.js";
@@ -51,7 +51,7 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
     const carriedViews = carried ? placementViewsOf(opts.readDenyHomes) : undefined;
     if (carried && carriedViews === undefined)
         sayPlacementLost();
-    const placesNothing = !unplaced.entries.some((e) => readDenyPatternRun(e.pattern).homeAnchored);
+    const placesNothing = !unplaced.entries.some((e) => readDenyPatternRun(e.pattern).homeAnchored || isRootedReadDenyPattern(e.pattern));
     const late = carried || placesNothing ? undefined : readDenyPlacedLater(carryHomeViews(unplaced, homeViewsAt(env, [])), () => placeReadDenyAtHome(env, compileAt, readDenyHomes));
     const readDeny = late?.matcher ??
         (carried

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

@@ -75,7 +75,8 @@ export type ArgRole =
  | {
     readonly kind: "shell-text";
 }
-/** The program word a launcher runs; the words after it are that program's argv. */
+/** The program a launcher or a builtin runs by name: a function (`compgen -F`), the program a launcher runs in place of
+ *  a shell (`su -s PROGRAM`). */
  | {
     readonly kind: "command";
 }
@@ -163,10 +164,10 @@ export interface OptionSpec {
     readonly endsOptions?: true;
     /** `banner`: prints and exits; `interactive`: reads commands from its standard input (after its program, `python -i`;
      *  instead of a script file, `sh -s`; a launcher's shell, run where no program follows, `sudo -s`); `names-program`: selects
-     *  the program to run without a value (`node --test`); `follows`: follows its files as they grow, until killed
-     *  (`tail -f`); `repeats`: repeats on an interval until killed (`free -s`); `quiet`: prints only what the program's own
-     *  text tells it to (`sed -n`); `forced`: removes without asking, and passes over an operand that is not there
-     *  (`rm -f`). */
+     *  the program to run without a value (`node --test`; a launcher's, from the caller's environment: `su -m`); `follows`:
+     *  follows its files as they grow, until killed (`tail -f`); `repeats`: repeats on an interval until killed (`free -s`);
+     *  `quiet`: prints only what the program's own text tells it to (`sed -n`); `forced`: removes without asking, and passes
+     *  over an operand that is not there (`rm -f`). */
     readonly mode?: OptionMode;
     /** This switch turns the program's own value glob off (`curl -g`): every {@link ArgRole} `programGlob` value of the
      *  invocation is read literally. */
@@ -250,15 +251,44 @@ export interface LauncherSpec {
     readonly assignmentOperands?: true;
     /** A bare negative integer in its option section is its own argument (`nice -5 <cmd>`). */
     readonly negativeIntegerIsOwnArgument?: true;
-    /** It hands its operands to a SHELL as text (`watch "cat /x"`): there is no program word. */
-    readonly shellText?: true;
+    /** It runs a SHELL in place of a program word, and how the words after it become that shell's argv: `joined` — its
+     *  non-option words, joined by a space, are the shell's `-c` text (`watch "cat /x"`); `user` — its first operand (past
+     *  a lone `-`) names the user it runs as, and the words after the user are the shell's own argv, behind a `-c TEXT` its
+     *  own shell-text option gives (`su [-] [USER [ARG…]]`: an implementation that reads its options anywhere takes them
+     *  past the user too, one that stops at the user hands them on); the program is its option of role `command` where
+     *  one is given (`su -s PROGRAM`), or a `names-program` switch's (`su -m`: the caller's `$SHELL`). */
+    readonly shellText?: "joined" | "user";
+    /** Option spellings that make a {@link shellText} launcher run the program its operands name instead
+     *  (`runuser -u USER CMD…`). */
+    readonly programWith?: readonly string[];
     /** With no program word it runs a shell. */
     readonly whenNoProgram?: "shell";
+    /** Where a switch selecting its shell (mode `interactive`: `sudo -s`) has words after it, they are that shell's `-c`
+     *  text: `escaped` — joined by a space, every character of each but a letter, a digit, `_`, `-` and `$` escaped with a
+     *  backslash. Absent, the launcher takes no such words (`doas -s CMD` is refused) and they are read as the program. */
+    readonly shellCommand?: "escaped";
     /** The spelling a required operand must have (a word spelled otherwise is not one the launcher accepts). Absent: any
      *  word that is not option-shaped. */
     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. */
@@ -550,6 +580,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
@@ -561,6 +605,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";
@@ -643,18 +695,38 @@ 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). */
+/** 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). */

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

@@ -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);
@@ -1023,7 +1036,14 @@ 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))
         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,27 +1053,59 @@ 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;
-    }
-    if (/^-[A-Za-z]+$/.test(tok) && [...tok.slice(1)].every((ch) => launcherOptionArity(row, `-${ch}`) === 0 && steppableLauncherOption(row, `-${ch}`)?.arity === 0))
-        return 1;
-    return undefined;
+    return readLauncherOption(row, tok)?.step;
+}
+export function launcherRunsShell(row, args) {
+    const l = row.launcher;
+    if (l?.shellText === undefined)
+        return false;
+    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)
@@ -1063,6 +1115,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;

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

@@ -360,8 +360,19 @@ const launcherGrammar = (g, extra = {}) => {
         put(spelling, val(SHELL_TEXT));
     for (const spelling of g.shells ?? [])
         put(spelling, { arity: 0, mode: "interactive" });
+    for (const spelling of g.programs ?? [])
+        put(spelling, { arity: 0, mode: "names-program" });
     return { dialect: "any", short, long, afterFirstOperand: "either", ...extra };
 };
+const SU_OPTIONS = {
+    switches: ["-f", "-l", "-P", "-T", "-h", "-V", "--fast", "--login", "--pty", "--no-pty", "--help", "--version"],
+    banners: ["-h", "-V"],
+    values: { "-g": LABEL, "-G": LABEL, "-w": LABEL, "-s": COMMAND, "--group": LABEL, "--supp-group": LABEL, "--whitelist-environment": LABEL, "--shell": COMMAND },
+    shellText: ["-c", "--command", "--session-command"],
+    programs: ["-m", "-p", "--preserve-environment"],
+};
+const SU = launcherGrammar(SU_OPTIONS, { stepsDashDash: true });
+const SU_LINUX_ONLY = [...SU_OPTIONS.switches, ...Object.keys(SU_OPTIONS.values), ...SU_OPTIONS.shellText, ...SU_OPTIONS.programs].filter((s) => !["-f", "-l", "-m"].includes(s));
 const launchers = [
     { key: "env", grammars: implementations(launcherGrammar({
             switches: ["-i", "-v", "--ignore-environment", "--debug", "--list-signal-handling", "--help", "--version"],
@@ -380,18 +391,18 @@ 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 }, 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: {
             "-u": LABEL, "-g": LABEL, "-U": LABEL, "-C": COUNT, "-D": WORKDIR, "-h": LABEL, "-p": LABEL, "-r": LABEL, "-R": ROOTDIR, "-t": LABEL, "-T": COUNT, "-a": LABEL,
             "--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,
         },
-    }), { witness: PRIVILEGED }),
-    launcher("doas", {}, launcherGrammar({ switches: ["-L", "-n"], shells: ["-s"], values: { "-a": LABEL, "-u": LABEL, "-C": READ } }), { witness: PRIVILEGED }),
+    }, { 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 }),
-    launcher("su", { shellText: true }, undefined, { witness: PRIVILEGED }),
-    launcher("runuser", { shellText: true }, undefined, { 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)),
@@ -409,7 +420,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: true }, 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"],
@@ -425,7 +444,7 @@ const launchers = [
         values: { "-t": COUNT, "-S": LABEL, "-G": LABEL, "--target": COUNT, "--setuid": LABEL, "--setgid": LABEL },
         optional: { "-r": ROOTDIR, "-w": WORKDIR, "--root": ROOTDIR, "--wd": WORKDIR },
     }), { witness: LINUX_NAMESPACE }),
-    launcher("script", { shellText: true }, launcherGrammar({ shellText: ["-c", "--command"] }), { witness: SHELL_TEXT_LAUNCHER }),
+    launcher("script", { shellText: "joined" }, launcherGrammar({ shellText: ["-c", "--command"] }), { witness: SHELL_TEXT_LAUNCHER }),
     launcher("numactl", {}, undefined, { witness: LINUX_NAMESPACE }),
     launcher("prlimit", {}, undefined, { witness: LINUX_NAMESPACE }),
     launcher("systemd-run", {}, undefined, { witness: { declared: "hands the program to a service manager" } }),

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

@@ -38,6 +38,23 @@ export declare function readDenyHomeLinksOf(env: ExecutionEnv, entries: readonly
     readonly linked: Map<string, string[]>;
     readonly whole: boolean;
 }>;
+/**
+ * Where the ROOTED rows of a table (`/app/config-lkg.json`, read-deny.ts) lead — the same `linked` answer
+ * {@link readDenyHomeLinksOf} gives for home-anchored rows, by the same machine ({@link linkedLocationsOf}): the row's
+ * LITERAL HEAD is spelled under the root and resolved the way the read faces mint their keys, and a location that differs
+ * from the spelling is where one of the head's segments is a link (`/app` a link to `/data/app`) — the row is placed
+ * there too, so a read of the link's target meets it. The laws are `readDenyHomeLinksOf`'s: a head that resolves to its own
+ * spelling adds nothing, a head with nothing below it adds nothing, a head the environment does not answer adds
+ * nothing and the answer is not WHOLE, a row whose head is empty (`/*.json`) has no location to resolve. A root is no
+ * home, so the answer does not depend on the homes: it is read whether or not a home answered.
+ */
+export declare function readDenyRootLinksOf(env: ExecutionEnv, entries: readonly {
+    readonly pattern: string;
+    readonly caseSensitive?: boolean;
+}[], signal?: AbortSignal, deadline?: number): Promise<{
+    readonly linked: Map<string, string[]>;
+    readonly whole: boolean;
+}>;
 /**
  * Where the rows that open with the configuration directory's name (`~/.sema/…`, {@link agentConfigDirTail}) lead when
  * the host declares the directory's root (`RunnerDeps.agentConfigDir`) — the same `linked` answer
@@ -138,7 +155,9 @@ export declare function carryHomeViews<T extends object>(judge: T, source: HomeV
  *    with no answer, or a declared home that did not answer, places nothing: the rows are held anywhere (`compile([])`)
  *    rather than at a spelling that may miss the home's canonical one;
  *  · each AUXILIARY home (see the module head) read once under {@link AUXILIARY_HOME_PROBE_MS} — its spellings, its
- *    chain, its rows' heads — at the same time; whatever of it did not answer costs that home alone and never `whole`.
+ *    chain, its rows' heads — at the same time; whatever of it did not answer costs that home alone and never `whole`;
+ *  · the ROOTED rows' heads ({@link readDenyRootLinksOf}), read whether or not a home answered: a head that did not answer
+ *    leaves the placement not WHOLE, and a placement that held the rows anywhere still places them.
  *  `compile` is the mount's own compile; the rows' patterns are read off its compile at no home. */
 export declare function placeReadDenyAtHome(env: ExecutionEnv, compile: (homes: readonly string[], linked?: ReadonlyMap<string, readonly string[]>) => ReadDenyMatcher, homes?: readonly string[], signal?: AbortSignal, configRoot?: string): Promise<{
     readonly matcher: PlacedReadDenyMatcher;