@sema-agent/core 7.48.0 → 7.49.1

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];
@@ -8,7 +29,7 @@ export declare const PATH_VALUE_FORMS: readonly ["indirect", "form", "header", "
 export type PathValueForm = (typeof PATH_VALUE_FORMS)[number];
 /** What selecting an option does to how the program runs ({@link OptionSpec.mode}) — a CLOSED set (`docs/CLOSED-SETS.md`,
  *  `OptionMode`). */
-export declare const OPTION_MODES: readonly ["banner", "interactive", "names-program", "follows", "repeats", "quiet", "forced"];
+export declare const OPTION_MODES: readonly ["banner", "interactive", "names-program", "follows", "repeats", "quiet", "forced", "queries"];
 export type OptionMode = (typeof OPTION_MODES)[number];
 /**
  * What one word is in this program's hands — a CLOSED set (`docs/CLOSED-SETS.md`, `ArgRoleKind`), the eleven members the
@@ -167,7 +188,8 @@ export interface OptionSpec {
      *  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`). */
+     *  over an operand that is not there (`rm -f`); `queries`: a LOOKUP — the operands are names it looks up and describes, and
+     *  it runs none of them (`command -v`). */
     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. */
@@ -339,11 +361,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
@@ -383,7 +403,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;
@@ -668,14 +688,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
@@ -701,6 +713,15 @@ export declare function launcherOptionArity(row: ProgramRow, tok: string): 0 | 1
 export declare function launcherOptionPathRole(row: ProgramRow, tok: string): Extract<ArgRole, {
     kind: "path";
 }> | undefined;
+/** 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;
+/** Does this launcher option word select a LOOKUP ({@link OptionSpec.mode} `queries`: `command -v`, `-V`, a cluster
+ *  carrying one — `-pv`), so that the words after the options are names and no program is run? 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 launcherOptionQueries(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;
@@ -754,13 +775,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

@@ -2,7 +2,7 @@ import { literalTildeSpelling } from "../../shell/lex.js";
 import { PROGRAM_ROWS } from "./program-read-model.rows.js";
 export const DATUM_FORMS = Object.freeze(["count", "pattern", "name-pattern", "label", "message", "delimiter"]);
 export const PATH_VALUE_FORMS = Object.freeze(["indirect", "form", "header", "url"]);
-export const OPTION_MODES = Object.freeze(["banner", "interactive", "names-program", "follows", "repeats", "quiet", "forced"]);
+export const OPTION_MODES = Object.freeze(["banner", "interactive", "names-program", "follows", "repeats", "quiet", "forced", "queries"]);
 export const ARG_ROLE_KINDS = Object.freeze(["path", "mount-source", "object-path", "program-text", "program-file", "shell-text", "command", "assignment", "binds-name", "entry-probe", "datum"]);
 export const PATH_EFFECTS = Object.freeze(["read", "names", "write", "create", "edit-in-place"]);
 export const WRITING_EFFECTS = new Set(["write", "create", "edit-in-place"]);
@@ -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)
@@ -979,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();
@@ -1034,7 +1019,7 @@ 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" || takesNoWordBare(row, tok) ? m : undefined;
 }
@@ -1085,6 +1070,47 @@ export function launcherOptionPathRole(row, tok) {
     const role = readLauncherOption(row, tok)?.valued?.spec.value;
     return role?.kind === "path" ? role : undefined;
 }
+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 (!/^-[^-]/.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 launcherOptionQueries(row, tok) {
+    if (tok === "-" || tok === "--")
+        return false;
+    if (tok.startsWith("--")) {
+        const eq = tok.indexOf("=");
+        return steppableLauncherOption(row, eq > 2 ? tok.slice(0, eq) : tok)?.spec.mode === "queries";
+    }
+    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 (m.spec.mode === "queries")
+            return true;
+        if (m.arity !== 0)
+            return false;
+    }
+    return false;
+}
 export function launcherOptionStep(row, tok) {
     return readLauncherOption(row, tok)?.step;
 }
@@ -1267,12 +1293,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" };
@@ -30,6 +31,7 @@ const OBJECT_PATH = { kind: "object-path" };
 const text = (language) => ({ kind: "program-text", language });
 const file = (language) => ({ kind: "program-file", language });
 const SWITCH = { arity: 0 };
+const QUERY = { arity: 0, mode: "queries" };
 const val = (value, extra = {}) => ({ arity: 1, ...(value !== undefined ? { value } : {}), ...extra });
 const optional = (value) => ({ arity: "attached", ...(value !== undefined ? { value } : {}) });
 const switches = (letters, extra = {}) => Object.fromEntries([...letters].map((l) => [l, { arity: 0, ...extra }]));
@@ -379,10 +381,10 @@ const launchers = [
             values: { "-u": LABEL, "--unset": LABEL, "-C": WORKDIR, "--chdir": WORKDIR, "-a": LABEL, "--argv0": LABEL, "-P": PROGRAM_SEARCH },
             optional: { "--default-signal": LABEL, "--ignore-signal": LABEL },
             shellText: ["-S", "--split-string"],
-        }), { lacks: ["-P"] }, { lacks: ["-a", "--ignore-environment", "--debug", "--list-signal-handling", "--help", "--version", "--unset", "--chdir", "--argv0", "--default-signal", "--ignore-signal", "--split-string"] }), launcher: { assignmentOperands: true, bareDash: true }, witness: BINARY },
-    launcher("command", {}, grammar({ p: SWITCH })),
-    launcher("builtin"),
-    launcher("exec", {}, launcherGrammar({ switches: ["-c", "-l"], values: { "-a": LABEL } })),
+        }, { stepsDashDash: true }), { lacks: ["-P"] }, { lacks: ["-a", "--ignore-environment", "--debug", "--list-signal-handling", "--help", "--version", "--unset", "--chdir", "--argv0", "--default-signal", "--ignore-signal", "--split-string"] }), launcher: { assignmentOperands: true, bareDash: true }, witness: BINARY },
+    launcher("command", {}, grammar({ p: SWITCH, v: QUERY, V: QUERY }, {}, { stepsDashDash: true })),
+    launcher("builtin", {}, grammar({}, {}, { stepsDashDash: true })),
+    launcher("exec", {}, launcherGrammar({ switches: ["-c", "-l"], values: { "-a": LABEL } }, { stepsDashDash: true })),
     launcher("noglob", {}, undefined, { witness: { declared: "a zsh precommand modifier" } }),
     launcher("nocorrect", {}, undefined, { witness: { declared: "a zsh precommand modifier" } }),
     { key: "xargs", grammars: implementations(launcherGrammar({
@@ -405,8 +407,8 @@ const launchers = [
     { 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)),
-    { key: "nice", grammars: implementations(grammar({ n: val(COUNT) }, { adjustment: val(COUNT), ...BANNERS }), {}, { lacks: ["--adjustment", "--help", "--version"] }), launcher: { negativeIntegerIsOwnArgument: true }, witness: BINARY },
+    launcher("nohup", {}, grammar({}, BANNERS, { stepsDashDash: true })),
+    { key: "nice", grammars: implementations(grammar({ n: val(COUNT) }, { adjustment: val(COUNT), ...BANNERS }, { stepsDashDash: true }), {}, { lacks: ["--adjustment", "--help", "--version"] }), launcher: { negativeIntegerIsOwnArgument: true }, witness: BINARY },
     launcher("ionice", {}, launcherGrammar({
         switches: ["-t", "--ignore", "-h", "--help", "-V", "--version"],
         banners: ["-h", "-V"],
@@ -417,8 +419,8 @@ const launchers = [
         values: { "-p": COUNT, "--pid": COUNT, "-T": COUNT, "-P": COUNT, "-D": COUNT, "--sched-runtime": COUNT, "--sched-period": COUNT, "--sched-deadline": COUNT },
     }), { witness: LINUX_NAMESPACE }),
     launcher("taskset", { requiredOperands: 1, requiredOperandSpelling: /^(?:0x)?[\da-f]+$|^[\d,:-]+$/i }, launcherGrammar({ switches: ["-a", "-p", "-c", "--all-tasks", "--pid", "--cpu-list", "--help", "--version"] }), { witness: LINUX_NAMESPACE }),
-    { 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: "stdbuf", grammars: implementations(grammar({ i: val(LABEL), o: val(LABEL), e: val(LABEL) }, { input: val(LABEL), output: val(LABEL), error: val(LABEL), ...BANNERS }, { stepsDashDash: true }), {}, { 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 }, { stepsDashDash: true })),
     { 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 },
     { key: "watch", grammars: [
             launcherGrammar({
@@ -429,12 +431,12 @@ const launchers = [
             }, { 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("setsid", {}, launcherGrammar({ switches: ["-c", "-f", "-w", "--ctty", "--fork", "--wait", "--help", "--version"] }, { stepsDashDash: true })),
     launcher("flock", { requiredOperands: 1 }, launcherGrammar({
         switches: ["-s", "-x", "-u", "-n", "-o", "-F", "--shared", "--exclusive", "--unlock", "--nonblock", "--nb", "--close", "--no-fork", "--verbose", "--help", "--version"],
         values: { "-w": COUNT, "-E": COUNT, "--timeout": COUNT, "--wait": COUNT, "--conflict-exit-code": COUNT },
         shellText: ["-c", "--command"],
-    }), { operands: { rest: CREATED } }),
+    }, { stepsDashDash: true }), { operands: { rest: CREATED } }),
     launcher("unshare", { whenNoProgram: "shell" }, launcherGrammar({
         switches: ["-m", "-u", "-i", "-n", "-p", "-U", "-C", "-T", "-f", "-r", "-c", "--mount", "--uts", "--ipc", "--net", "--pid", "--user", "--cgroup", "--time", "--fork", "--map-root-user", "--map-current-user", "--kill-child", "--mount-proc", "--keep-caps", "--help", "--version"],
         values: { "-R": ROOTDIR, "-w": WORKDIR, "-S": LABEL, "-G": LABEL, "--setuid": LABEL, "--setgid": LABEL, "--root": ROOTDIR, "--wd": WORKDIR, "--propagation": LABEL, "--setgroups": LABEL, "--monotonic": COUNT, "--boottime": COUNT, "--map-user": LABEL, "--map-group": LABEL },
@@ -504,7 +506,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),
@@ -583,6 +585,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),
@@ -622,11 +625,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])),
 ];

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

@@ -15,68 +15,54 @@ export declare function declaredReadDenyHomes(env: Pick<ExecutionEnv, "homeDir">
  *  gave no answer, or where the declared home's own probe did not answer (ask again later). */
 export declare function readDenyHomesOf(env: Pick<ExecutionEnv, "homeDir" | "canonicalPath">, signal?: AbortSignal): Promise<string[]>;
 /**
- * Where the home-anchored rows of a table LEAD beyond the home's own spellings, keyed by the row's pattern — the
- * `linked` argument of `compileReadDeny`. For each row, its LITERAL HEAD (`readDenyRunHead`: the run's segments before
- * the first one carrying `*`) is spelled under each home and resolved the way the read faces mint their keys
- * (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined); a location that differs from every
- * home's own spelling of the head is where one of the head's segments is a link, and the row is placed there too.
- *  · a head that resolves to its own spelling under a home adds nothing (the row is already placed there);
+ * Where a table's deny rows LEAD past the places their own runs anchor them, keyed by the row's pattern — the `linked`
+ * argument of `compileReadDeny`. ONE constructor for every anchor ({@link ReadDenyRowAnchor}): the rows the anchor
+ * places, each row's LITERAL HEAD ({@link literalHeadOf}) spelled under each of the anchor's places and resolved the way the
+ * read faces mint their keys (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined); a location
+ * that differs from the spellings the row is already anchored at is where one of the head's segments is a link (`~/.sema`
+ * into a dotfiles directory, `/app` a link to `/data/app`), and the row is placed there too.
+ *  · a head that resolves to its own spelling at an anchored place adds nothing (the row is already placed there);
  *  · a head under a spelling that is no directory (a segment of it is a file, a symlink to a file, a device node or a
  *    socket — the environment answers `not_directory` for the head) has nothing below it: an answer that adds nothing;
  *  · any other head that cannot be resolved (an unanswered or refused probe — a directory the probe may not enter — a
- *    probe that throws) adds nothing, and the answer is not WHOLE (`whole: false`): the row stays placed at the home's
- *    spellings until the mount places again;
- *  · a row whose head is empty (`~/.sema.*`) has no location to resolve and adds nothing;
+ *    probe that throws) adds nothing, and the answer is not WHOLE (`whole: false`): the row stays at the places its run
+ *    anchors until the mount places again;
  *  · the heads are resolved together, so one placement waits at most one probe bound — or, with `deadline` (an absolute
  *    time), each head until then: a head still unresolved at the deadline is a head that did not answer;
  *  · read per placement — a link created afterwards is followed from the next placement on.
  */
-export declare function readDenyHomeLinksOf(env: ExecutionEnv, entries: readonly {
+export declare function readDenyLinksOf(env: ExecutionEnv, entries: readonly {
     readonly pattern: string;
     readonly caseSensitive?: boolean;
-}[], homes: readonly string[], signal?: AbortSignal, deadline?: number): Promise<{
+}[], anchor: ReadDenyRowAnchor, signal?: AbortSignal, deadline?: number): Promise<{
     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.
+ * Which rows one placement reads, and where their heads are spelled:
+ *  · `home` — the home-anchored rows (`~/…`), under each home; the row's run anchors it there;
+ *  · `root` — the ROOTED rows (`/app/config-lkg.json`, {@link isRootedReadDenyPattern}), under the filesystem root; the run
+ *    anchors it there. A root is no home: read whether or not a home answered;
+ *  · `unanchored` — the rows that open with the configuration directory's name (`~/.sema/…`, {@link agentConfigDirTail})
+ *    under each spelling of the root the host declares for that directory (`RunnerDeps.agentConfigDir`): the head BELOW
+ *    the directory name, a head that ends at it (`~/.sema/*.json`, `~/.sema`) the root itself. The row's run does not
+ *    anchor it there (it is anchored at the homes), so every location — the spelling itself and where it leads — is one
+ *    the row is placed at in addition; the row's name in every refusal is unchanged.
+ * A home or rooted row whose head is empty (`~/.sema.*`, `/*.json`) has no location to resolve and adds nothing.
  */
-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
- * {@link readDenyHomeLinksOf} gives, for the same rows: the row's literal head below the directory name is spelled under
- * each spelling of the root and resolved the way the read faces mint their keys. A row is not anchored at the root by
- * its own run (it is anchored at the homes), so every location here — the spelling itself and where it leads — is one the
- * row is placed at in addition; the home spelling stays placed. The row's name in every refusal is unchanged.
- *  · a row whose run does not open with the directory's name (`~/.sema.*`, the external tools' files) adds nothing;
- *  · a row whose head ends at the directory name (`~/.sema/*.json`, `~/.sema`) is placed at the root itself, the rest of
- *    its run matched below it.
- */
-export declare function readDenyConfigRootLinksOf(env: ExecutionEnv, entries: readonly {
-    readonly pattern: string;
-    readonly caseSensitive?: boolean;
-}[], roots: readonly string[], signal?: AbortSignal, deadline?: number): Promise<{
-    readonly linked: Map<string, string[]>;
-    readonly whole: boolean;
-}>;
+export type ReadDenyRowAnchor = {
+    readonly at: "home";
+    readonly homes: readonly string[];
+} | {
+    readonly at: "root";
+} | {
+    readonly at: "unanchored";
+    readonly roots: readonly string[];
+};
 /** Where an absolute location LEADS in one environment — resolved the way the read and write faces mint their keys
  *  (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined). `undefined` when the environment
  *  does not answer (a refused or failed probe, one that throws). The one resolution a deny row's placement reads: a
- *  home-anchored row's head ({@link readDenyHomeLinksOf}) and a rule row's head ({@link whereItsAnsweredPrefixLeads}). */
+ *  deny row's head ({@link readDenyLinksOf}) and a rule row's head ({@link whereItsAnsweredPrefixLeads}). */
 export declare function whereItLeads(env: ExecutionEnv, at: string, family?: PathFamily, signal?: AbortSignal): Promise<string | undefined>;
 /** {@link whereItLeads} with a floor: where the environment does not answer for `at` (a probe that fails), the longest
  *  prefix it does answer for is resolved and the rest rejoined — a rule row's head below a base that resolves is never
@@ -150,13 +136,13 @@ export declare function carryHomeViews<T extends object>(judge: T, source: HomeV
  *  · the HOME SET — `homes` when the mount carries a list (the account is not asked and no home is added), else the
  *    declared home and the account lookup's answer ({@link declaredReadDenyHomes}); every home of the set is anchored at
  *    its spelling and, where the environment answered one, its canonical spelling — one rule for both forms;
- *  · the DECLARED home's canonical spelling under the tree's gate bound, and its rows' heads ({@link readDenyHomeLinksOf}):
+ *  · the DECLARED home's canonical spelling under the tree's gate bound, and its rows' heads ({@link readDenyLinksOf}):
  *    a declared home, or a head under it, that did not answer leaves the placement not WHOLE — and an account lookup
  *    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`;
- *  · the ROOTED rows' heads ({@link readDenyRootLinksOf}), read whether or not a home answered: a head that did not answer
+ *  · the ROOTED rows' heads ({@link readDenyLinksOf}), 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<{