@sema-agent/core 7.46.0 → 7.48.0

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

@@ -5,34 +5,94 @@
  * does to the word before the program sees it.
  */
 import { type LexedCommand, type LexedWord, type WordPiece } from "../../shell/lex.js";
-import { type BindingTable, type BoundValue } from "./shell-read-bindings.js";
+import { type BindingTable, type BoundValue, type FloorValue } from "./shell-read-bindings.js";
 /** `"glob"` = an unquoted pathname-expansion character; `"unresolvable"` = the shell rewrites the word (a brace,
  *  variable or command substitution) so its text is not the path. The read candidate's own field, spelled here. */
 export type WordExpands = false | "glob" | "unresolvable";
-/** A word as the candidate readers name it: the lexer's word, the spelling the program receives — the names the word
- *  refers to read through the binding table ({@link wordValues}: `"$F"` after `F=/x` is `/x`) — and what the shell does to
- *  it before the program sees it. */
+/** A word as the candidate readers name it: the lexer's word, the spelling a reader names it by — the names the word
+ *  refers to read through the binding table ({@link wordValues}: `"$F"` after `F=/x` is `/x`; {@link spellingOf}) — and
+ *  what the shell does to it before the program sees it. A text handed to a shell that re-parses it is the program's
+ *  ({@link programTextOf}), never this one. */
 export interface Read {
     readonly word: LexedWord;
     readonly raw: string;
     readonly folded: string;
+    /** A pattern's names are matched by this spelling where it is not {@link folded} (a class the judge widens, read as
+     *  any one character — {@link LexedWord.judged}, {@link judgedSpellingOf}); `folded` stays the name opened where none match. */
+    readonly pattern?: string;
     readonly expands: WordExpands;
     /** The names the word refers to were read through the table: its expansion IS the spelling above (and, where the
      *  names may hold several values, {@link values}). */
     readonly settled?: true;
-    /** Every spelling the word may expand to (the first is {@link folded}); present only where there are several. */
-    readonly values?: readonly string[];
+    /** Every value the word may expand to (the first spelled {@link folded}, {@link spellingOf}; matched by {@link pattern}),
+     *  each with the parts of it the shell expands as a pattern ({@link BoundValue}); present wherever the names were read
+     *  through the table ({@link settled}). */
+    readonly values?: readonly BoundValue[];
     /** The word refers to `HOME` and `HOME` may hold something other than the declared home here: the spelling the
      *  word has with the declared home, for the deny judge alone. */
     readonly homeFloor?: string;
     /** The word's names are unknown here, but their bindings left spellings for the deny judge (an array's elements):
      *  what the word may then spell, for the deny judge alone. */
-    readonly floorValues?: readonly BoundValue[];
+    readonly floorValues?: readonly FloorValue[];
 }
 /** The reads of a segment's words against the binding table at that segment (`homeDir` = the declared home, the
  *  state `HOME` starts in). A word that refers to no name, or only to a `HOME` the text has not touched (`~/x`, placed
  *  by the establishment at the declared home), reads as written. */
-export declare function readsOf(words: readonly LexedWord[], table: BindingTable | undefined, homeDir: string | undefined): Read[];
+export declare function readsOf(words: readonly LexedWord[], table: BindingTable | undefined, homeDir: string | undefined, split?: boolean): Read[];
+/** One reading of a segment: the binding table with each name its words read held to ONE value (or, past
+ *  {@link READINGS_MAX}, made unknown — every value it held stays a deny-floor spelling, {@link BindingTable.floorOf}),
+ *  the reads of its argv against it ({@link readsOf}), and the argv the shell hands the program in it — a word whose
+ *  names settle into one value that is no pattern is that value, as a literal word (a reader of the program position,
+ *  of a launcher's fields, of a program's options reads it as it reads a literal word); any other word as written, its
+ *  names' deny floors in `floors` (a shell that re-reads the word — `sh -c`, `eval`, a launcher's shell — starts with
+ *  them: the word names in that text what it names here). */
+export interface SegmentReading {
+    readonly table: BindingTable;
+    readonly reads: readonly Read[];
+    readonly argv: readonly LexedWord[];
+    readonly floors: ReadonlyMap<string, readonly FloorValue[]>;
+}
+/**
+ * The readings of one segment's words (its argv and its redirection targets): the names they read through the table that
+ * may hold several values here, in the order the words read them (the program position first), each held to one value
+ * per reading — every combination while the readings stay within {@link READINGS_MAX}, so the program position, a
+ * launcher's fields, a re-entered text and an operand are spelled from the same values (`$P` read twice takes one value
+ * in a reading: the shell expands both alike); a name past that bound is unknown in every reading — its word as written,
+ * every value it held a deny floor — never a sample of its combinations. A segment whose names hold one value each has
+ * one reading.
+ */
+export declare function segmentReadingsOf(argv: readonly LexedWord[], targets: readonly LexedWord[], table: BindingTable, homeDir: string | undefined): SegmentReading[];
+/** The spelling a reader names a value by, read directly as a path — for a pattern, the name the program opens where it
+ *  matches nothing: its text, a leading `~` spelled as the literal tilde it is ({@link literalTildeSpelling}, the lexer's
+ *  spelling of a written one) — the shell never tilde-expands what a quoted piece or an expansion produced, so a value that
+ *  starts with `~` starts with a literal one (`X=/w; rm \~$X/*` reads `./~/w/*`, as `rm \~/w/*` does). A shell that
+ *  re-parses the value reads {@link programTextOf} instead. */
+export declare const spellingOf: (v: BoundValue) => string;
+/** The pattern a PART of a pattern word is matched by (an option value attached to its option word, `--file=["!"a]*`; an
+ *  assignment-shaped word's value, `if=["!"a]*`): the word's own judged spelling (`pattern`) past the text in front of
+ *  the part — bash expands the WHOLE word, so the names the part may take are those the word's widened spelling reaches
+ *  (a superset: a name is judged whether or not the word in front of it matches too). `undefined` where the word carries
+ *  none, the part is not the end of the word's spelling, or the text in front holds a widened class itself (its judged
+ *  spelling no longer lines up). */
+export declare function partPattern(word: {
+    readonly folded: string;
+    readonly pattern?: string;
+}, part: string): string | undefined;
+/** A candidate under another name (a value of several, a backup, a copy's child): the word's `pattern` matched the word,
+ *  not that name — the name is matched by its own text. */
+export declare function renamed<C extends {
+    readonly spelled: string;
+    readonly pattern?: string;
+}>(c: C, spelled: string): Omit<C, "pattern">;
+/** The text a read's word hands a program, as a shell re-parsing it reads it (`eval`, `sh -c`, a launcher's line): its
+ *  first established value as the program receives it, or the lexer's folded spelling — never {@link spellingOf}'s path
+ *  spelling (`X='~'; eval rm -rf "$X"` re-parses `rm -rf ~`, the home). */
+export declare const programTextOf: (r: Read) => string;
+/** What a read's word hands the program, where the reader knows it: each value its names settled into — one field each
+ *  (an unquoted expansion whose value is not one word is never settled, {@link wordValues}), or, where the word is a
+ *  pattern, the pattern whose matches are the fields, its parts telling pattern characters from literal ones;
+ *  `undefined` for a word the table did not settle (or that names nothing). */
+export declare function settledFieldsOf(r: Read): readonly BoundValue[] | undefined;
 /** The shell REWRITES this read's word before the program sees it (a parameter, command, process, arithmetic or
  *  brace expansion, or the character of one) — a word whose names the table settled excepted: its expansion is its
  *  spelling. */

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

@@ -1,33 +1,127 @@
-import { argvOf, lexShell, UNRESOLVED_SENTENCE } from "../../shell/lex.js";
+import { argvOf, lexShell, literalTildeSpelling, UNRESOLVED_SENTENCE } from "../../shell/lex.js";
 import { expansionInWord, extglobOpenerIn, globInWord, homeExpansionOf } from "./bash-readonly-classifier.js";
-import { wordFloorValues, wordValues } from "./shell-read-bindings.js";
-export function readsOf(words, table, homeDir) {
+import { floorOf, judgedSpellingOf, namesIn, wordFloorValues, wordValues } from "./shell-read-bindings.js";
+export function readsOf(words, table, homeDir, split = false) {
     return words.map((word) => {
-        const refersToName = word.pieces.some((p) => p.expansion?.kind === "parameter");
+        const refersToName = word.pieces.some((p) => p.expansion?.kind === "parameter") || namesIn(word).length > 0;
+        const asWritten = { word, raw: word.raw, folded: word.folded, ...(word.judged !== undefined ? { pattern: word.judged } : {}) };
         if (!refersToName && table?.homeTouched !== true)
-            return { word, raw: word.raw, folded: word.folded, expands: expandsOf(word) };
-        const values = wordValues(word, table, false);
+            return { ...asWritten, expands: expandsOf(word) };
+        const values = wordValues(word, table, false, undefined, split);
         if (values === undefined)
-            return { word, raw: word.raw, folded: word.folded, expands: expandsOf(word) };
+            return { ...asWritten, expands: expandsOf(word) };
         if (values === "unknown") {
             const floors = refersToName ? wordFloorValues(word, table) : [];
-            return { word, raw: word.raw, folded: word.folded, expands: refersToName ? "unresolvable" : expandsOf(word), ...(floors.length > 0 ? { floorValues: floors } : {}) };
+            return { ...asWritten, expands: refersToName ? "unresolvable" : expandsOf(word), ...(floors.length > 0 ? { floorValues: floors } : {}) };
         }
         const glob = values.some((v) => v.glob === true) || globInWord(word);
         const refersToHome = word.pieces.some((p) => p.expansion?.kind === "tilde" || (p.expansion?.kind === "parameter" && p.expansion.name === "HOME"));
         const declared = refersToHome && homeDir !== undefined && table?.homeTouched === true ? wordValues(word, table, false, new Map([["HOME", [{ spelled: homeDir }]]])) : undefined;
-        const floor = declared !== undefined && declared !== "unknown" ? declared[0]?.spelled : undefined;
+        const floor = declared !== undefined && declared !== "unknown" && declared[0] !== undefined ? spellingOf(declared[0]) : undefined;
+        const pattern = judgedSpellingOf(values[0]);
         return {
             word,
             raw: word.raw,
-            folded: values[0].spelled,
+            folded: spellingOf(values[0]),
+            ...(pattern !== undefined ? { pattern } : {}),
             expands: glob ? "glob" : false,
             settled: true,
-            ...(values.length > 1 ? { values: values.map((v) => v.spelled) } : {}),
-            ...(floor !== undefined && !values.every((v) => v.spelled === floor) ? { homeFloor: floor } : {}),
+            values,
+            ...(floor !== undefined && !values.every((v) => spellingOf(v) === floor) ? { homeFloor: floor } : {}),
         };
     });
 }
+const READINGS_MAX = 64;
+export function segmentReadingsOf(argv, targets, table, homeDir) {
+    const several = new Map();
+    for (const word of [...argv, ...targets]) {
+        for (const name of namesReadIn(word, table)) {
+            const state = table.stateOf(name);
+            if (state !== "unknown" && state.length > 1)
+                several.set(name, state);
+        }
+    }
+    let overlays = [new Map()];
+    const past = [];
+    for (const [name, values] of several) {
+        if (past.length > 0 || overlays.length * values.length > READINGS_MAX) {
+            past.push(name);
+            continue;
+        }
+        overlays = overlays.flatMap((o) => values.map((v) => new Map(o).set(name, [v])));
+    }
+    for (const o of overlays)
+        for (const name of past)
+            o.set(name, "unknown");
+    return overlays.map((overlay) => {
+        const reading = overlay.size === 0 ? table : overlaidTable(table, overlay);
+        const fielded = readsOf(argv, reading, homeDir, true).flatMap((r) => {
+            const fields = r.values?.length === 1 ? r.values[0].fields : undefined;
+            return fields === undefined ? [r] : fields.map((f) => ({ word: argumentWordOf(f, f) ?? r.word, raw: f, folded: spellingOf({ spelled: f }), expands: false, settled: true, values: [{ spelled: f }] }));
+        });
+        const floors = new Map();
+        for (const r of fielded) {
+            if (r.settled === true)
+                continue;
+            for (const p of r.word.pieces) {
+                const name = p.expansion?.kind === "parameter" ? p.expansion.name : undefined;
+                if (name === undefined)
+                    continue;
+                const held = reading.stateOf(name);
+                const floor = [...(held === "unknown" ? [] : held.map(floorOf)), ...reading.floorOf(name)];
+                if (floor.length > 0)
+                    floors.set(name, floor);
+            }
+        }
+        return { table: reading, reads: fielded, argv: fielded.map((r) => valuedWord(r.word, r)), floors };
+    });
+}
+function namesReadIn(word, table) {
+    return [...namesIn(word), ...(table.homeTouched && word.pieces.some((p) => p.expansion?.kind === "tilde" && p.expansion.body === "~") ? ["HOME"] : [])];
+}
+function overlaidTable(table, overlay) {
+    return {
+        stateOf: (name) => overlay.get(name) ?? table.stateOf(name),
+        isInteger: (name) => table.isInteger(name),
+        ifsTouched: table.ifsTouched,
+        homeTouched: table.homeTouched,
+        floorOf: (name) => {
+            const held = table.stateOf(name);
+            return overlay.get(name) !== "unknown" || held === "unknown" ? table.floorOf(name) : [...table.floorOf(name), ...held.map(floorOf)];
+        },
+        inherited: table.inherited,
+    };
+}
+function valuedWord(word, r) {
+    const v = r.values?.length === 1 ? r.values[0] : undefined;
+    if (word.assignment !== undefined || v === undefined || v.glob === true || v.spelled === word.folded)
+        return word;
+    return argumentWordOf(v.spelled, r.raw) ?? word;
+}
+function argumentWordOf(text, raw) {
+    const quoted = text.replace(/[^A-Za-z0-9_./+@:%=,-]/g, (c) => (c === "'" ? "\\'" : `'${c}'`));
+    const lexed = lexShell(`: ${quoted === "" ? "''" : quoted}`);
+    const words = "parseFailure" in lexed || lexed.segments.length !== 1 ? undefined : argvOf(lexed.segments[0]);
+    return words?.length === 2 ? { ...words[1], raw } : undefined;
+}
+export const spellingOf = (v) => literalTildeSpelling(v.spelled);
+export function partPattern(word, part) {
+    if (word.pattern === undefined || part === word.folded || !word.folded.endsWith(part))
+        return undefined;
+    const front = word.folded.slice(0, word.folded.length - part.length);
+    if (!word.pattern.startsWith(front))
+        return undefined;
+    const judged = word.pattern.slice(front.length);
+    return judged === part ? undefined : judged;
+}
+export function renamed(c, spelled) {
+    const { pattern: _matched, ...rest } = c;
+    return { ...rest, spelled };
+}
+export const programTextOf = (r) => r.values?.[0]?.spelled ?? r.word.folded;
+export function settledFieldsOf(r) {
+    return r.settled === true ? r.values : undefined;
+}
 export const rewritten = (r) => r.settled !== true && expansionInWord(r.word);
 export function readOfText(text) {
     const l = lexShell(text);

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

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

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

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

package/dist/tools/fs/shell-reentry-text.js

@@ -1,6 +1,6 @@
 import { literalHeredocBody, literalTextOf } from "../../shell/lex.js";
-import { readProgramPosition } from "./bash-program-position.js";
-import { printedText, programRow, readArgRoles, selectedOptions } from "./program-read-model.js";
+import { programBasename, readProgramPosition } from "./bash-program-position.js";
+import { implementationRejects, implementationsOf, printedText, programRow, readArgRoles, selectedOptions, targetUserOf } from "./program-read-model.js";
 import { namesStandardInput } from "./safety.js";
 export function codeBodies(basename, args) {
     const row = programRow(basename);
@@ -70,6 +70,124 @@ function argvText(row, at, args) {
     }
     return undefined;
 }
+export function launchedCommands(argv, pos = readProgramPosition(argv)) {
+    const runs = pos.refusal?.kind === "control_syntax_at_program_position" ? pos.refusal.runsShell : undefined;
+    if (runs === undefined)
+        return [];
+    const row = programRow(programBasename(argv[runs.launcher].folded));
+    const words = argv.slice(runs.from).map((w) => w.folded);
+    const at = (k) => runs.from + k;
+    if (row?.launcher?.shellText === "user")
+        return userCommands(row, words, at);
+    const user = row === undefined ? undefined : targetUserOf(row, argv.slice(runs.launcher + 1, runs.from).map((w) => w.folded));
+    const as = user !== undefined ? { as: user } : {};
+    if (words.length === 0 || row?.launcher === undefined)
+        return [{ args: [], ...as }];
+    if (row.launcher.shellText === "joined") {
+        const texts = new Map();
+        for (const view of implementationsOf(row)) {
+            const events = readArgRoles(view, words);
+            const first = events.find((e) => e.kind === "operand" || e.kind === "dash-word-operand")?.at ?? words.length;
+            if (implementationRejects(row, view, words.slice(0, first)))
+                continue;
+            const joined = words.slice(first).map((_, k) => at(first + k));
+            const values = events.flatMap((e) => (e.kind === "option" || (e.kind === "value" && e.at < first) ? roleValue(e, "shell-text", words, at) ?? [] : []));
+            for (const t of [...(joined.length === 0 ? [] : [{ joined }]), ...values])
+                texts.set(JSON.stringify(t), t);
+        }
+        return texts.size === 0 ? [{ args: [], ...as }] : [...texts.values()].map((t) => ({ args: [{ fixed: "-c" }, t], ...as }));
+    }
+    return [{ args: [{ fixed: "-c" }, { joined: words.map((_, k) => at(k)), escaped: true }], ...as }];
+}
+function roleValue(e, kind, words, at) {
+    if (e.kind === "value" && e.role?.kind === kind)
+        return { at: at(e.at) };
+    if (e.kind === "option" && typeof e.reading === "object" && e.reading.role?.kind === kind)
+        return { at: at(e.at), from: words[e.at].length - e.reading.attached.length };
+    return undefined;
+}
+function userCommands(row, words, at) {
+    const out = [];
+    const valued = (e, kind) => roleValue(e, kind, words, at);
+    for (const view of implementationsOf(row)) {
+        const events = readArgRoles(view, words);
+        const operands = events.filter((e) => e.kind === "operand");
+        const user = (operands[0]?.dash !== undefined ? operands[1] : operands[0])?.at;
+        const end = user ?? words.length;
+        const stops = view.grammars[0]?.afterFirstOperand === "operands";
+        const own = stops ? events.filter((e) => e.at < end) : events;
+        const named = own.flatMap((e) => valued(e, "command") ?? []).at(-1);
+        const fromEnvironment = selectedOptions(view, stops ? words.slice(0, end) : words, "one-implementation").some((o) => o.mode === "names-program");
+        const program = named !== undefined ? { program: named } : fromEnvironment ? { program: { spelled: "\"$SHELL\"" } } : {};
+        const target = targetUserOf(view, stops ? words.slice(0, end) : words.filter((_, k) => k !== user), { name: user === undefined ? "root" : words[user], dash: operands[0]?.dash !== undefined });
+        const runs = { ...program, ...(target !== undefined ? { as: target } : {}) };
+        if (stops) {
+            out.push({ ...runs, args: user === undefined ? [] : words.slice(user + 1).map((_, k) => ({ at: at(user + 1 + k) })) });
+            continue;
+        }
+        const rest = operands.filter((e) => user !== undefined && e.at > user).map((e) => ({ at: at(e.at) }));
+        const texts = own.flatMap((e) => valued(e, "shell-text") ?? []);
+        if (texts.length === 0)
+            out.push({ ...runs, args: rest });
+        for (const text of texts)
+            out.push({ ...runs, args: [{ fixed: "-c" }, text, ...rest] });
+    }
+    return out;
+}
+export function launchedReadings(argv, command) {
+    const p = command.program;
+    if (p === undefined)
+        return { shell: "sh" };
+    const raw = (k, from = 0) => {
+        if (from === 0)
+            return argv[k].raw;
+        const literal = literalTextOf(argv[k].pieces);
+        return literal === undefined ? argv[k].folded.slice(from) : `'${literal.slice(from).replace(/'/g, "'\\''")}'`;
+    };
+    const line = [("at" in p ? raw(p.at, p.from) : p.spelled), ...command.args.map((a) => ("fixed" in a ? a.fixed : "at" in a ? raw(a.at, a.from) : a.joined.map((k) => raw(k)).join(" ")))].join(" ");
+    const literal = "at" in p ? literalTextOf(argv[p.at].pieces)?.slice(p.from ?? 0) : undefined;
+    if (literal === undefined)
+        return { shell: "sh", line };
+    const basename = programBasename(literal);
+    const reentry = programRow(basename)?.reentry;
+    return reentry?.kind === "shell" && reentry.text === "c-option" ? { shell: basename } : { line };
+}
+export function launchedInput(argv, pos, spell) {
+    const spelled = (word) => (args) => spellLaunched(argv, args, { word: (k, from) => word(k).slice(from), values: spell.values });
+    const asTexts = spelled(spell.text);
+    const asArgs = spelled(spell.folded);
+    const lines = new Set();
+    const programWords = [];
+    const shells = launchedCommands(argv, pos).flatMap((c) => {
+        const { shell, line } = launchedReadings(argv, c);
+        if (line !== undefined)
+            lines.add(line);
+        if (shell === undefined)
+            return [];
+        if (line === undefined && c.program !== undefined && "at" in c.program && c.program.from === undefined)
+            programWords.push(c.program.at);
+        const words = c.args.map((x) => ("at" in x && x.from === undefined ? x.at : undefined));
+        const args = asArgs(c.args);
+        return asTexts(c.args).map((texts, i) => ({ shell, texts, args: args[i], words, ...(c.as !== undefined ? { as: c.as } : {}) }));
+    });
+    return { shells, programWords, lines: [...lines] };
+}
+function sudoEscaped(field) {
+    return field.replace(/[^A-Za-z0-9_$-]/gu, (c) => `\\${c}`);
+}
+function launchedSpellingOf(v) {
+    return v.glob === true ? v.parts.map((p) => (p.pattern ? p.text : sudoEscaped(p.text))).join("") : sudoEscaped(v.spelled);
+}
+export function spellLaunched(argv, args, spell) {
+    const field = (k) => {
+        const literal = literalTextOf(argv[k].pieces);
+        if (literal !== undefined)
+            return sudoEscaped(literal);
+        const values = spell.values?.(k);
+        return values?.length === 1 ? launchedSpellingOf(values[0]) : argv[k].raw;
+    };
+    return [args.map((a) => ("fixed" in a ? a.fixed : "at" in a ? spell.word(a.at, a.from ?? 0) : a.joined.map((k) => (a.escaped === true ? field(k) : spell.word(k, 0))).join(" ")))];
+}
 export function scriptFileAt(basename, args) {
     const row = programRow(basename);
     return row?.reentry?.kind === "shell" && argvText(row, row.reentry.text, args) === undefined ? scriptSourceOf(row, args).file : undefined;
@@ -85,7 +203,7 @@ function scriptSourceOf(row, args) {
         return { stdin: true };
     return { file: first.at, stdin: options.some((e) => e.kind === "option" && e.reading === "speculative") };
 }
-export function stdinTextsOf(segment, piped) {
+export function stdinTextsOf(segment, fed) {
     const out = [];
     let replacesPipe = false;
     for (const t of segment.tokens) {
@@ -99,7 +217,7 @@ export function stdinTextsOf(segment, piped) {
             replacesPipe = true;
         }
     }
-    return piped === undefined || replacesPipe ? out : [piped, ...out];
+    return replacesPipe ? out : [...fed, ...out];
 }
 export function pipedTextOf(segment, argv) {
     const from = `${segment.text.trim()} |`;

package/dist/tools/monitor.d.ts

@@ -28,9 +28,9 @@
  * The handle is a first-class m* registry task: TaskOutput serves the re-readable spool, TaskStop stops the
  * watch (design/134 stoppedBy attribution applies automatically).
  *
- * Security posture: `command` is an arbitrary shell script ⇒ effect:"write", same as Bash, and prepare-task
- * folds Monitor into the SAME shellGate tighten (irreversibility tier + reversibility probe on the same
- * `command` arg) — Monitor is never a policy side-door around a gated Bash.
+ * Security posture: `command` is an arbitrary shell script ⇒ effect:"write", same as Bash; the catalog puts Monitor on the
+ * SHELL FACE, so the `Bash(<command>)` rules, the shell seat, the read station and the removal guard judge its `command`
+ * as they judge Bash's — Monitor is never a policy side-door around a gated Bash.
  *
  * 深对比残差 M17 CLOSED (2026-07-09 live-CC probe, docs/cc-probe-198/live-schema-monitor-worktree-2026-07-09.json):
  * the deep-dive bundle showed a `command? + ws?:{url,protocols}` dual-mode schema; the LIVE current-CC schema is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.46.0",
+  "version": "7.48.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",