@sema-agent/core 7.47.0 → 7.48.0

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

@@ -272,6 +272,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. */
@@ -563,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
@@ -574,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";
@@ -656,22 +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,34 +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 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 +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

@@ -391,7 +391,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 +399,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 +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: "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"],

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;

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

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

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

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

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

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

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

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