@sema-agent/core 7.52.0 → 7.54.0

package/dist/core/{shell-lexer.d.ts → shell-run-candidates.d.ts}

@@ -1,23 +1,47 @@
-/** One argv word as the lexer read it. */
+/**
+ * The TIGHTENING reader's view of a command line — "which programs could this command line run, and can the text
+ * even be read?" — for the deny/ask direction of the permission-rule lane (`permission-rule-model.ts`
+ * `programRunReachOf`) and the read-only allow member (`read-only-shell.ts`). It reads the ONE shell lexer's result
+ * (`shell/lex.ts`) and adds only this reader's own domain: which pieces of a line are run candidates, the leading
+ * keyword of a control structure, and the additive peel. A segment that carries a command/process substitution
+ * anywhere (an argument, a redirection operand, an unquoted heredoc body) is one whose program runs are not fully
+ * known — the reader answers `unreadable` for every rule such a segment does not otherwise reach, never silence; the
+ * leading assignments and the wrapper programs of {@link SHELL_WRAPPER_TABLE} are peeled ADDITIVELY — a segment keeps
+ * its spelled argv as one run candidate and gains one per peeled layer, so `sudo env X=1 nohup rm -r x` is a run of
+ * `sudo …`, of `env …`, of `nohup …` and of `rm -r x`, and a deny on any of them reaches.
+ *
+ * What it answers is deliberately THREE-valued per segment: the argv words it could read, each marked literal or
+ * expansion-bearing, or an `unreadable` reason where the program runs cannot be known from the text (a command the
+ * lexer cannot delimit, a syntax error, a control structure whose commands need a syntax tree, a wrapper handed its
+ * command as one string or an option of unknown arity). The reader above turns "unreadable" into a fail-closed ask
+ * rather than into silence — reading it as "no match" is how a deny went blind on `rm -r x; echo "$HOME"`. Where the
+ * lexer cannot delimit the text, the segments it read before it stopped stay candidates (bash runs every complete line
+ * before the one it cannot parse) and the segment it stopped in is the unreadable one.
+ *
+ * The ALLOW direction's rule lane never reads this module: a standing yes covers the exact spelling a person read
+ * (`ruleAdmitsCommand`), and its whole-string refusal of every shell construct stays where it is.
+ */
+import { type LexedWord } from "../shell/lex.js";
+/** One argv word as the reader projects it. */
 export interface ShellWord {
     /** The word's value with quotes and escapes removed — meaningful only when `expands` is `false`. */
     readonly text: string;
     /** The unquoted source spelling (assignment and wrapper-flag tests read this, never `text`). */
     readonly raw: string;
     /** `false`: a literal word. `"one"`: carries an expansion but yields exactly ONE word (it was double-quoted).
-     *  `"many"`: an unquoted expansion, glob or brace pattern, or a quoted `"$@"` / array expansion — may
-     *  yield zero, one or several words. */
+     *  `"many"`: an unquoted expansion, glob or brace pattern, an ANSI-C quote, or a quoted `"$@"` / array expansion —
+     *  may yield zero, one or several words. */
     readonly expands: false | "one" | "many";
 }
-/** One redirection of a segment, as read: the operator and its operand word (a heredoc's operand is its
- *  delimiter; the IO number or `{name}` before the operator is folded into the operator's meaning and not
- *  kept). The tightening reader never reads these — a rule speaks about program runs; the read-only
- *  reader does (an output redirection is a write). */
+/** One redirection of a segment, as read: the operator and its operand word (a heredoc's operand is its delimiter;
+ *  a descriptor duplication's is the descriptor; the IO number or `{name}` before the operator is folded into the
+ *  operator's meaning and not kept). The tightening reader never reads these — a rule speaks about program runs; the
+ *  read-only reader does (an output redirection is a write). */
 export interface ShellRedirection {
     readonly op: string;
     readonly target: ShellWord;
 }
-/** One program run the lexer found, after keyword stripping. */
+/** One program run the reader found, after keyword stripping. */
 export interface ShellSegment {
     /** The run as SPELLED (a leading keyword removed): the first candidate a rule is compared against. */
     readonly argv: readonly ShellWord[];
@@ -32,7 +56,7 @@ export interface ShellSegment {
     /** Present when the segment's program runs are NOT fully known although its candidates could be read:
      *  a peel that stopped before the wrapped program could be named (its options carry an expansion, a
      *  command string, an option of unknown arity), or a command/process substitution anywhere in the
-     *  segment (it runs a program the lexer does not read). The candidates stand — a rule they reach is
+     *  segment (it runs a program the reader does not read). The candidates stand — a rule they reach is
      *  reached — and every other rule reads `unreadable`. */
     readonly peelUnreadable?: string;
 }
@@ -54,10 +78,10 @@ export interface ShellCommandShape {
     readonly strayRedirection: boolean;
 }
 export { SHELL_WRAPPER_TABLE, type ShellWrapperName } from "./shell-wrapper-table.js";
-/** Longer than this and the command is not read at all (one unreadable segment): every pass is linear,
- *  but a substitution nested inside quoting re-enters the quote reader once per nesting level, and the
- *  cap is what bounds that on model-supplied text. Upstream's own reader stops at the same size. */
+/** Longer than this and the command is not read at all (one unreadable segment). Upstream's own reader stops at the
+ *  same size. */
 export declare const MAX_SHELL_READ_CHARS = 10000;
+export declare function lexedWordOf(w: ShellWord): LexedWord | undefined;
 /** Read `source` as the tightening reader must: every program run the text could perform, or why it cannot be read. */
 export declare function readShellCommand(source: string): ShellCommandShape;
 /** Every program run of `shape` can be NAMED from the text: no segment is unreadable, no peel stopped,

package/dist/core/{shell-lexer.js → shell-run-candidates.js}

@@ -1,62 +1,74 @@
+import { arithmeticTextIsPlain, compoundValueHidesRun, expansionHidesRun, heredocBodyHidesRun, lexShell, namesRedirectDescriptor, PARSE_FAILURE_SENTENCE, } from "../shell/lex.js";
 import { shellWordsOf } from "../shell/shell-words.js";
+import { isLauncherAssignmentOperand } from "../tools/fs/bash-program-position.js";
+import { extglobOpenerIn } from "../tools/fs/bash-readonly-classifier.js";
 import { evaluatesOperand, SHELL_WRAPPER_TABLE } from "./shell-wrapper-table.js";
-import { arithmeticHidesRun, carriesSubstitution, freshWord, matchOp, readDoubleQuoted, readExpansion, skipBalanced, skipHeredocBodies } from "./shell-scan.js";
 export { SHELL_WRAPPER_TABLE } from "./shell-wrapper-table.js";
 const WRAPPERS = new Map(Object.entries(SHELL_WRAPPER_TABLE));
 const PREFIX_KEYWORDS = shellWordsOf("stripped_prefix");
 const CLOSING_KEYWORDS = shellWordsOf("stripped_standalone");
 const OPAQUE_KEYWORDS = shellWordsOf("opaque");
-const ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*\])?\+?=/;
+const CONTROL_PREFIXES = shellWordsOf("control_prefix");
 const DURATION_RE = /^\d+(?:\.\d+)?[smhd]?$/;
-const REDIRECT_OPS = ["<<<", "<<-", "<<", "<>", "<&", "<", ">>", ">|", ">&", "&>>", "&>", ">"];
-const CONNECTOR_OPS = ["&&", "||", "|&", "|", ";;&", ";&", ";;", ";", "&"];
-const ALL_OPS = [...CONNECTOR_OPS, ...REDIRECT_OPS];
 export const MAX_SHELL_READ_CHARS = 10_000;
+const LEXED_WORDS = new WeakMap();
+export function lexedWordOf(w) {
+    return LEXED_WORDS.get(w);
+}
+function wordOf(w) {
+    let expands = false;
+    const widen = (to) => { if (expands !== "many")
+        expands = to; };
+    let text = "";
+    for (const p of w.pieces) {
+        const e = p.expansion;
+        if (p.quotedBy === "$'" || (e === undefined && p.literal === undefined)) {
+            widen("many");
+            continue;
+        }
+        if (e === undefined) {
+            text += p.literal ?? "";
+            continue;
+        }
+        if (e.kind === "tilde") {
+            if (p === w.pieces[0])
+                widen(e.yields);
+            text += e.body ?? "";
+        }
+        else if (e.kind === "brace") {
+            widen("many");
+            text += `{${e.body ?? ""}}`;
+        }
+        else {
+            widen(e.yields);
+            text += e.pattern?.folded ?? "";
+        }
+    }
+    const out = { text, raw: w.raw, expands };
+    LEXED_WORDS.set(out, w);
+    return out;
+}
+const literalIn = (w, set) => w !== undefined && w.expands === false && set.has(w.text);
+const bareAssignment = (w) => lexedWordOf(w)?.assignment?.bare === true;
+const hidesRun = (w) => w.expansions.some((p) => p.expansion !== undefined && expansionHidesRun(p.expansion)) || (w.assignment?.subscript !== undefined && !arithmeticTextIsPlain(w.assignment.subscript.raw)) || compoundValueHidesRun(w);
+const CASE_ARM_UNREAD = "a `case` arm terminator outside a `case` this lane reads";
+const EXTGLOB_UNREAD = "an extended pattern (`?(…)` `*(…)` `+(…)` `@(…)` `!(…)`) is one this reader does not expand";
 export function readShellCommand(source) {
     if (source.length > MAX_SHELL_READ_CHARS)
         return { segments: [{ argv: [], redirections: [], peeled: [], unreadable: `the command is longer than ${MAX_SHELL_READ_CHARS} characters — not read` }], connectors: [], grouped: false, backgrounded: false, strayRedirection: false };
+    const lexed = lexShell(source);
+    const failed = "parseFailure" in lexed ? lexed : undefined;
+    const read = "parseFailure" in lexed ? lexed.readBefore : lexed.segments;
     const segments = [];
     const connectors = [];
     let grouped = false;
     let backgrounded = false;
     let strayRedirection = false;
     let seg = { words: [], redirections: [] };
-    let word = freshWord();
-    let pendingRedirect;
-    let heredocs = [];
-    let badDelimiter = false;
     let afterBoundary = true;
     let lastConnector;
-    let tail;
-    const n = source.length;
-    let i = 0;
-    const endWord = () => {
-        if (!word.started)
-            return;
-        if (word.braceExpands)
-            word.expands = "many";
-        if (word.substitution)
-            seg.substitution = true;
-        if (pendingRedirect !== undefined) {
-            if (pendingRedirect === "<<" || pendingRedirect === "<<-") {
-                if (word.expands !== false)
-                    badDelimiter = true;
-                heredocs.push({ delimiter: word.text, quoted: word.raw !== word.text, dash: pendingRedirect === "<<-" });
-            }
-            seg.redirections.push({ op: pendingRedirect, target: publicWord(word) });
-            pendingRedirect = undefined;
-        }
-        else {
-            seg.words.push(word);
-        }
-        word = freshWord();
-    };
+    let arithmetic;
     const finishSegment = (connector) => {
-        endWord();
-        if (pendingRedirect !== undefined) {
-            seg.unreadable ??= `the redirection \`${pendingRedirect}\` has no operand — a syntax error`;
-            pendingRedirect = undefined;
-        }
         let built = buildSegment(seg);
         if (built === "keyworded")
             grouped = true;
@@ -86,214 +98,121 @@ export function readShellCommand(source) {
         afterBoundary = false;
     };
     const boundary = () => { finishSegment(undefined); grouped = true; afterBoundary = true; lastConnector = undefined; };
-    while (i < n && tail === undefined) {
-        const ch = source[i];
-        if (ch === " " || ch === "\t") {
-            endWord();
-            i++;
-            continue;
-        }
-        if (ch === "\n") {
-            endWord();
-            if (badDelimiter) {
-                tail = "a here-document delimiter spelled with an expansion";
-                break;
-            }
-            if (heredocs.length === 0) {
-                finishSegment("\n");
-                i++;
-                continue;
-            }
-            const skipped = skipHeredocBodies(source, i + 1, heredocs);
-            heredocs = [];
-            if (skipped === undefined) {
-                tail = "a here-document body never reaches its delimiter";
-                break;
+    const word = (w) => { if (hidesRun(w))
+        seg.substitution = true; return wordOf(w); };
+    const readTokens = (s) => {
+        const tokens = s.tokens;
+        const shown = tokens.flatMap((t) => (t.kind === "word" ? t.expansions : t.kind === "redirect" ? t.target?.expansions ?? [] : [])).filter((p) => p.expansion?.kind === "command" || p.expansion?.kind === "process" || p.expansion?.kind === "arithmetic").length;
+        if (s.substitutions.length > shown)
+            seg.substitution = true;
+        let definitionClose = false;
+        tokens.forEach((t, i) => {
+            if (arithmetic !== undefined) {
+                if (t.kind === "group") {
+                    arithmetic.depth += t.op === "(" ? 1 : -1;
+                    if (arithmetic.depth === 0)
+                        arithmetic = undefined;
+                    return;
+                }
+                const w = t.kind === "word" ? t : t.kind === "redirect" ? t.target : undefined;
+                if (w === undefined || hidesRun(w) || !arithmeticTextIsPlain(w.raw) || t.kind === "heredoc")
+                    seg.substitution = true;
+                if (t.kind === "redirect" && t.dup !== undefined && !arithmeticTextIsPlain(t.dup))
+                    seg.substitution = true;
+                return;
             }
-            if (skipped.substitution)
-                seg.substitution = true;
-            finishSegment("\n");
-            i = skipped.end;
-            continue;
-        }
-        if (ch === "#" && !word.started) {
-            while (i < n && source[i] !== "\n")
-                i++;
-            continue;
-        }
-        if (ch === "\\") {
-            if (i + 1 >= n) {
-                tail = "a trailing backslash — the line never ends";
-                break;
+            if (t.kind === "word") {
+                if (!namesRedirectDescriptor(t, tokens[i + 1]))
+                    seg.words.push(word(t));
+                return;
             }
-            if (source[i + 1] === "\n") {
-                i += 2;
-                continue;
+            if (t.kind === "redirect") {
+                const target = t.target !== undefined ? word(t.target) : { text: t.dup ?? "", raw: t.dup ?? "", expands: false };
+                seg.redirections.push({ op: t.op, target });
+                return;
             }
-            word.started = true;
-            word.text += source[i + 1];
-            word.raw += source.slice(i, i + 2);
-            i += 2;
-            continue;
-        }
-        if (ch === "'") {
-            const close = source.indexOf("'", i + 1);
-            if (close < 0) {
-                tail = "an unterminated single quote";
-                break;
+            if (t.kind === "heredoc") {
+                seg.redirections.push({ op: "<<", target: { text: t.delimiter, raw: t.delimiter, expands: false } });
+                if (!t.quoted && heredocBodyHidesRun(t.body))
+                    seg.substitution = true;
+                return;
             }
-            word.started = true;
-            word.text += source.slice(i + 1, close);
-            word.raw += source.slice(i, close + 1);
-            i = close + 1;
-            continue;
-        }
-        let dq = i + 1;
-        if (ch === "$")
-            while (source[dq] === "\\" && source[dq + 1] === "\n")
-                dq += 2;
-        if (ch === '"' || (ch === "$" && source[dq] === '"')) {
-            const open = ch === "$" ? dq + 1 : i + 1;
-            const end = readDoubleQuoted(source, open, word);
-            if (end === undefined) {
-                tail = "an unterminated double quote";
-                break;
+            const next = tokens[i + 1];
+            if (definitionClose) {
+                definitionClose = false;
+                return;
             }
-            word.raw += source.slice(i, end);
-            i = end;
-            continue;
-        }
-        if (ch === "$" || ch === "`" || ((ch === "<" || ch === ">") && source[i + 1] === "(")) {
-            const end = readExpansion(source, i, word);
-            if (end === undefined) {
-                tail = "an unterminated substitution";
-                break;
+            if (t.op === "(" && next?.kind === "group" && next.op === "(" && seg.redirections.length === 0 && seg.words.every((w) => literalIn(w, CONTROL_PREFIXES) || literalIn(w, CLOSING_KEYWORDS) || (w.expands === false && w.text === "-p"))) {
+                arithmetic = { depth: 1 };
+                return;
             }
-            if (end === i + 1) {
-                word.started = true;
-                word.text += ch;
-                word.raw += ch;
-                i = end;
-                continue;
+            if (t.op === "(" && next?.kind === "group" && next.op === ")" && seg.words.length === 1 && seg.words[0].expands === false && seg.redirections.length === 0) {
+                seg.words.pop();
+                definitionClose = true;
             }
-            word.started = true;
-            word.expands = ch === "$" || ch === "`" ? "many" : word.expands || "one";
-            word.raw += source.slice(i, end);
-            i = end;
-            continue;
-        }
-        if (ch === "~" && !word.started)
-            word.expands = "one";
-        const op = matchOp(source, i, ALL_OPS);
-        if (op !== undefined) {
-            if (CONNECTOR_OPS.includes(op)) {
-                if (op === ";;" || op === ";&" || op === ";;&") {
-                    endWord();
-                    seg.unreadable ??= "a `case` arm terminator outside a `case` this lane reads";
-                    i += op.length;
-                    continue;
-                }
-                if (op === "&")
-                    backgrounded = true;
-                finishSegment(op);
-                i += op.length;
+            boundary();
+        });
+    };
+    for (let k = 0; k < read.length; k++) {
+        const s = read[k];
+        if (k > 0) {
+            const armEnd = caseArmEnd(read, k);
+            if (armEnd !== undefined) {
+                seg.unreadable ??= CASE_ARM_UNREAD;
+                k = armEnd;
+                readTokens(read[k]);
                 continue;
             }
-            if (word.started && word.raw === word.text && (/^\d+$/.test(word.text) || /^\{[A-Za-z_][A-Za-z0-9_]*\}$/.test(word.text)))
-                word = freshWord();
-            else
-                endWord();
-            if (pendingRedirect !== undefined)
-                seg.unreadable ??= `the redirection \`${pendingRedirect}\` has no operand — a syntax error`;
-            pendingRedirect = op;
-            i += op.length;
-            continue;
-        }
-        if (ch === "(" && word.started && "@?*+!".includes(word.raw.slice(-1)) && word.raw !== "!") {
-            const end = skipBalanced(source, i, "(", ")");
-            if (end === undefined) {
-                tail = "an unterminated extended pattern (`@(…)`)";
-                break;
-            }
-            if (carriesSubstitution(source.slice(i + 1, end - 1)))
-                word.substitution = true;
-            word.expands = "many";
-            word.text += source.slice(i, end);
-            word.raw += source.slice(i, end);
-            i = end;
-            continue;
-        }
-        if (ch === "(" && source[i + 1] === "(" && (!word.started || word.raw === "!") && pendingRedirect === undefined && seg.words.every((w) => w.expands === false && (shellWordsOf("control_prefix").has(w.text) || CLOSING_KEYWORDS.has(w.text) || w.text === "-p"))) {
-            endWord();
-            const end = skipBalanced(source, i, "(", ")");
-            if (end === undefined) {
-                tail = "an unterminated arithmetic command";
-                break;
+            const connector = s.pipesStderr === true ? "|&" : s.connector;
+            if (arithmetic !== undefined) {
+                if (connector === ";")
+                    seg.substitution = true;
             }
-            if (arithmeticHidesRun(source.slice(i + 2, end - 1)))
-                seg.substitution = true;
-            i = end;
-            continue;
-        }
-        if (ch === "(" || ch === ")") {
-            if (ch === "(" && word.started && !word.expands && seg.words.length === 0 && pendingRedirect === undefined) {
-                let j = i + 1;
-                while (j < n && (source[j] === " " || source[j] === "\t"))
-                    j++;
-                if (source[j] === ")") {
-                    word = freshWord();
-                    boundary();
-                    i = j + 1;
-                    continue;
-                }
+            else {
+                if (connector === "&")
+                    backgrounded = true;
+                finishSegment(connector);
             }
-            boundary();
-            i++;
-            continue;
         }
-        if (ch === "*" || ch === "?" || (ch === "]" && word.bracketOpen))
-            word.expands = "many";
-        if (ch === "[")
-            word.bracketOpen = true;
-        if (ch === "{")
-            word.braceOpen = true;
-        if (word.braceOpen && (ch === "," || (ch === "." && source[i + 1] === ".")))
-            word.braceExpands = true;
-        if (ch === "}" && !word.braceExpands)
-            word.braceOpen = false;
-        word.started = true;
-        word.text += ch;
-        word.raw += ch;
-        i++;
+        readTokens(s);
     }
-    if (tail !== undefined) {
-        endWord();
-        seg.unreadable ??= tail;
-        finishSegment(undefined);
+    if (failed !== undefined) {
+        seg.unreadable ??= PARSE_FAILURE_SENTENCE[failed.parseFailure.reason];
+    }
+    else if (arithmetic !== undefined) {
+        seg.unreadable ??= "an unterminated arithmetic command";
     }
     else {
-        if (heredocs.length > 0)
-            seg.unreadable ??= "a here-document with no body";
-        const dangling = seg.words.length === 0 && !word.started && lastConnector !== undefined && lastConnector !== ";" && lastConnector !== "&" && lastConnector !== "\n";
+        const dangling = seg.words.length === 0 && seg.redirections.length === 0 && lastConnector !== undefined && lastConnector !== ";" && lastConnector !== "&" && lastConnector !== "\n";
         if (dangling)
             seg.unreadable ??= `the connector \`${lastConnector}\` has no command after it — a syntax error`;
-        finishSegment(undefined);
     }
+    finishSegment(undefined);
+    if (failed === undefined && "segments" in lexed && extglobOpenerIn(lexed, source))
+        return { segments: segments.map((s) => (s.unreadable !== undefined ? s : { ...s, peelUnreadable: s.peelUnreadable ?? EXTGLOB_UNREAD })), connectors, grouped, backgrounded, strayRedirection };
     return { segments, connectors, grouped, backgrounded, strayRedirection };
 }
-const publicWord = ({ text, raw, expands }) => ({ text, raw, expands });
+function caseArmEnd(read, k) {
+    const arm = (j) => read[j].connector === ";" && read[j].text === "" && read[j].tokens.length === 0;
+    const next = read[k + 1];
+    if (!arm(k) || next === undefined || (next.connector !== ";" && next.connector !== "&"))
+        return undefined;
+    const third = read[k + 2];
+    return next.connector === ";" && arm(k + 1) && third?.connector === "&" ? k + 2 : k + 1;
+}
 const SUBSTITUTION_UNREAD = "a command substitution runs a program this reader does not read";
 const MAX_WRAPPER_LAYERS = 8;
 export function isFullyReadable(shape) {
     return shape.segments.every((s) => s.unreadable === undefined && s.peelUnreadable === undefined && [s.argv, ...s.peeled].every((argv) => argv[0]?.expands === false));
 }
+const operandsOf = (run) => run.map((w) => ({ text: w.text, raw: w.raw, assignment: lexedWordOf(w)?.assignment }));
 function buildSegment(seg) {
     if (seg.unreadable !== undefined)
-        return { argv: seg.words.map(publicWord), redirections: seg.redirections, peeled: [], unreadable: seg.unreadable };
+        return { argv: seg.words, redirections: seg.redirections, peeled: [], unreadable: seg.unreadable };
     const carried = () => (seg.substitution === true ? { argv: [], redirections: seg.redirections, peeled: [], peelUnreadable: SUBSTITUTION_UNREAD } : keyworded ? "keyworded" : "empty");
     let keyworded = false;
     let k0 = 0;
-    while (k0 < seg.words.length && seg.words[k0].expands === false && (PREFIX_KEYWORDS.has(seg.words[k0].text) || CLOSING_KEYWORDS.has(seg.words[k0].text))) {
+    while (k0 < seg.words.length && (literalIn(seg.words[k0], PREFIX_KEYWORDS) || literalIn(seg.words[k0], CLOSING_KEYWORDS))) {
         k0++;
         keyworded = true;
     }
@@ -301,24 +220,24 @@ function buildSegment(seg) {
     const head = words[0];
     if (head === undefined)
         return carried();
-    if (evaluatesOperand(words))
+    if (evaluatesOperand(operandsOf(words)))
         seg.substitution = true;
     if (head.expands === false && (head.text === "[[" || head.text === "["))
         return carried();
-    if (head.expands === false && OPAQUE_KEYWORDS.has(head.text))
-        return { argv: words.map(publicWord), redirections: seg.redirections, peeled: [], unreadable: `a \`${head.text}\` control structure — its commands need a syntax tree` };
-    const argv = words.map(publicWord);
+    if (literalIn(head, OPAQUE_KEYWORDS))
+        return { argv: words, redirections: seg.redirections, peeled: [], unreadable: `a \`${head.text}\` control structure — its commands need a syntax tree` };
+    const argv = words;
     const peeled = [];
     let peelUnreadable;
     let k = 0;
-    while (k < argv.length && ASSIGNMENT_RE.test(argv[k].raw))
+    while (k < argv.length && bareAssignment(argv[k]))
         k++;
     let run = argv.slice(k);
     if (k > 0 && run.length > 0)
         peeled.push(run);
     for (let layer = 0; run.length > 0; layer++) {
         let j = 0;
-        while (j < run.length && ((run[j].text === "!" && run[j].expands === false) || ASSIGNMENT_RE.test(run[j].raw)))
+        while (j < run.length && ((run[j].text === "!" && run[j].expands === false) || bareAssignment(run[j])))
             j++;
         if (j > 0) {
             run = run.slice(j);
@@ -344,7 +263,7 @@ function buildSegment(seg) {
         run = next;
         peeled.push(run);
     }
-    if (seg.substitution === true || [argv, ...peeled].some((c) => c[0]?.expands === false && evaluatesOperand(c)))
+    if (seg.substitution === true || [argv, ...peeled].some((c) => c[0]?.expands === false && evaluatesOperand(operandsOf(c))))
         peelUnreadable ??= SUBSTITUTION_UNREAD;
     return { argv, redirections: seg.redirections, peeled, ...(peelUnreadable !== undefined ? { peelUnreadable } : {}) };
 }
@@ -364,6 +283,7 @@ function unwrap(words) {
     const flags = new Set(row.flags);
     const attached = new Set(row.attached ?? []);
     const commandString = new Set(row.commandString);
+    const assignmentOperand = (w) => row.assignments === true && w.expands === false && isLauncherAssignmentOperand(w.text);
     let positionalTaken = row.positional === undefined;
     let durationTaken = row.duration !== true;
     let replaceToken;
@@ -405,7 +325,7 @@ function unwrap(words) {
                     return r;
                 i++;
             }
-            while (row.assignments === true && i < words.length && words[i].expands === false && ASSIGNMENT_RE.test(words[i].text))
+            while (i < words.length && assignmentOperand(words[i]))
                 i++;
             break;
         }
@@ -464,7 +384,7 @@ function unwrap(words) {
             i++;
             continue;
         }
-        if (row.assignments === true && ASSIGNMENT_RE.test(t)) {
+        if (assignmentOperand(w)) {
             i++;
             continue;
         }

package/dist/core/shell-wrapper-table.d.ts

@@ -1,5 +1,6 @@
+import type { AssignmentFact } from "../shell/lex.js";
 /**
- * The wrapper programs the tightening reader ({@link import("./shell-lexer.js").readShellCommand}) peels to
+ * The wrapper programs the tightening reader ({@link import("./shell-run-candidates.js").readShellCommand}) peels to
  * reach the program they run — upstream's three tables (its light strip on every arm, its full strip on
  * the deny/ask arms, and its `xargs` clause inlined in the matcher) as ONE closed table. Peeling is
  * ADDITIVE on the reading side: the segment keeps its spelled argv as one run candidate and adds one
@@ -395,13 +396,14 @@ export interface ShellWrapperRow {
  *  subscript (`arr[a]`, quoted, bare, attached `-varr[a]`, or `arr[a]=1`) is evaluated as arithmetic —
  *  recursively, like `$((a))` — when the builtin reads or writes it (`printf -v 'arr[a]' …`, `unset arr[a]`,
  *  `declare arr[a]=1`, `read arr[a]`, `[[ -v arr[a] ]]`, `test -v arr[a]`), and so is the value of an
- *  INTEGER-attribute assignment (`declare -i x=a`). The lexer marks such a run's hidden run at every peel
+ *  INTEGER-attribute assignment (`declare -i x=a`). The tightening reader marks such a run's hidden run at every peel
  *  candidate (`command printf -v …`). An operand that is WHOLLY an expansion is not judged here (`unset "$X"`
  *  — one more indirection; the price of reading it would be a prompt on every `export FOO="$BAR"`), nor is
  *  an arithmetic comparison's operand (`[[ $n -gt 0 ]]` evaluates `$n` — the same price). */
 export declare const VARIABLE_OPERAND_BUILTINS: ReadonlySet<string>;
-/** Does this run of a variable-operand builtin evaluate an operand arithmetically? Linear in the words. */
+/** Does this run of a variable-operand builtin evaluate an operand arithmetically? `assignment`: the lexer's fact on the word. */
 export declare function evaluatesOperand(run: readonly {
     readonly text: string;
     readonly raw: string;
+    readonly assignment?: AssignmentFact | undefined;
 }[]): boolean;

package/dist/core/shell-wrapper-table.js

@@ -67,7 +67,7 @@ export function evaluatesOperand(run) {
     if (!VARIABLE_OPERAND_BUILTINS.has(run[0]?.text ?? ""))
         return false;
     const integer = run.some((w) => /^-[A-Za-z]*i/.test(w.text));
-    return run.some((w) => namesArrayElement(w.text) || namesArrayElement(w.raw) || (integer && /^[A-Za-z_][A-Za-z0-9_]*\+?=.*[A-Za-z_$]/.test(w.text)));
+    return run.some((w) => namesArrayElement(w.text) || namesArrayElement(w.raw) || (integer && w.assignment !== undefined && /[A-Za-z_$]/.test(w.assignment.value.folded)));
 }
 function namesArrayElement(word) {
     for (let open = word.indexOf("["); open > 0; open = word.indexOf("[", open + 1)) {

package/dist/core/store-contracts/checkpoint-store-contract.js

@@ -308,7 +308,7 @@ export async function checkpointStoreContract(make, runAssertion) {
         const stored = (await store.get(bitless.token)).pendingAction;
         assert.equal("hasBidiControls" in stored, false, "projection backfill must not write back to the row");
     });
-    run("design/388 B18 × B6 identity + face group: a row's eight optional members (capabilityId/contractId/shapeDigest/implementationRevision/rosterDigest + family/pathTarget/names) survive the round-trip verbatim; an absent group stays absent", async () => {
+    run("the approval object's members: a row's identity + face group and its targets (capabilityId/contractId/shapeDigest/implementationRevision + family/pathTarget/names + targets) survive the round-trip verbatim; an absent group stays absent", async () => {
         const store = make();
         const carried = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-carried" });
         const group = {
@@ -316,10 +316,10 @@ export async function checkpointStoreContract(make, runAssertion) {
             contractId: "acme.write@2",
             shapeDigest: "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
             implementationRevision: "r7",
-            rosterDigest: "sha256:fedcba9876543210fedcba9876543210fedcba9876543210fedcba9876543210",
             family: "file-write",
             pathTarget: { param: "destination", aliases: ["path"], access: "create", skillScopeEligible: true },
             names: ["AcmeWrite", "acme_write"],
+            targets: { protective: "/srv/work/out.txt", declared: "/srv/work/out.txt" },
         };
         Object.assign(carried.pendingAction, group);
         const bare = createCheckpointFixture({ token: mintCheckpointToken(), sessionId: "id-bare" });

package/dist/core/store-contracts/mailbox-store-contract.js

@@ -1,6 +1,8 @@
 import { strict as assert } from "node:assert";
 import { MAILBOX_INVALID_PEER_META_CODE, MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
 import { beginContract } from "./contract-harness.js";
+import { PRINCIPAL_INBOX_HANDLE } from "../../agents/cross-session-ref.js";
+import { mintCrossPrincipalRecord } from "../../agents/org-delivery-gate.js";
 export const MAILBOX_CONTRACT_SCOPE = "default";
 const msg = (content, sentAt = 1000) => ({ content, sentAt });
 async function withStores(mk, fn) {
@@ -259,6 +261,17 @@ export async function mailboxBundledOnlyContract(mk, runAssertion) {
         await s.drop("tenant-b", "shared-handle");
         assert.equal(await s.peekCount("tenant-b", "shared-handle"), 0);
     });
+    run("第四条消费链(principal 收件箱):投递门铸的信落收件人 scope 的 principal.inbox,两只信任锚逐字节回读,发信方 scope 零残留", async (make) => {
+        const s = make();
+        const letter = mintCrossPrincipalRecord({ from: { scope: "principal-a", name: "alice" }, body: { content: "letter" }, receiptId: "gr-1", sentAt: 10_000, consumer: { kind: "terminals" } });
+        assert.equal(await s.append("principal-b", PRINCIPAL_INBOX_HANDLE, letter), 1);
+        assert.equal(await s.peekCount("principal-a", PRINCIPAL_INBOX_HANDLE), 0, "发信方 scope 的同名箱不得出现这封信");
+        const lease = await s.claimLease("principal-b", PRINCIPAL_INBOX_HANDLE, "drain:r1", 60_000, 10_000);
+        assert.deepEqual(lease.messages.map((m) => m.peerMeta), [{ kind: "peer_message", fromScope: "principal-a", gateReceiptId: "gr-1" }]);
+        assert.equal(lease.messages[0].from, "alice");
+        assert.deepEqual(await s.ack("principal-b", PRINCIPAL_INBOX_HANDLE, "drain:r1", lease.maxSeq), { acked: true });
+        assert.equal(await s.peekCount("principal-b", PRINCIPAL_INBOX_HANDLE), 0);
+    });
     await settle();
 }
 export async function mailboxCrossProcessContract(hooks) {