@sema-agent/core 7.8.0 → 7.9.1

package/dist/core/shell-scan.js

@@ -0,0 +1,183 @@
+const SPECIAL_PARAMS = "?$!#@*-0123456789";
+const SUBSTITUTION_RE = /\$\(|`|<\(|>\(|\$\[/;
+export const arithmeticHidesRun = (expr) => /[^\s\d+\-*/%&|^~!<>=?:,()]/.test(expr);
+const SUBSCRIPT_RE = /\$\{[!#]?[A-Za-z_][A-Za-z0-9_]*(?:\[[^\]]*[A-Za-z_$]|(?:\[[^\]]*\])?:(?![-=+?])[^}]*[A-Za-z_$])/;
+export const carriesSubstitution = (text) => { const t = text.replace(/\\\n/g, ""); return SUBSTITUTION_RE.test(t) || SUBSCRIPT_RE.test(t); };
+const PER_ELEMENT_RE = /^\$@$|^\$\{!?@|\[@\]|^\$\{![^}]*@\}$/;
+export const freshWord = () => ({ text: "", raw: "", expands: false, started: false, braceOpen: false, braceExpands: false, bracketOpen: false, substitution: false });
+export function readDoubleQuoted(s, i, word) {
+    word.started = true;
+    while (i < s.length) {
+        const ch = s[i];
+        if (ch === '"')
+            return i + 1;
+        if (ch === "\\") {
+            const next = s[i + 1];
+            if (next === undefined)
+                return undefined;
+            if (next === "\n") {
+                i += 2;
+                continue;
+            }
+            if ('$`"\\'.includes(next)) {
+                word.text += next;
+                i += 2;
+                continue;
+            }
+            word.text += ch;
+            i++;
+            continue;
+        }
+        if (ch === "$" || ch === "`") {
+            const end = readExpansion(s, i, word, true);
+            if (end === undefined)
+                return undefined;
+            if (end === i + 1) {
+                word.text += ch;
+                i = end;
+                continue;
+            }
+            if (PER_ELEMENT_RE.test(s.slice(i, end).replace(/\\\n/g, "")))
+                word.expands = "many";
+            else if (word.expands === false)
+                word.expands = "one";
+            i = end;
+            continue;
+        }
+        word.text += ch;
+        i++;
+    }
+    return undefined;
+}
+export function readExpansion(s, i, word, inDoubleQuotes = false) {
+    if (s[i] === "`") {
+        word.substitution = true;
+        for (let j = i + 1; j < s.length; j += s[j] === "\\" ? 2 : 1)
+            if (s[j] === "`")
+                return j + 1;
+        return undefined;
+    }
+    let o = i + 1;
+    while (s[o] === "\\" && s[o + 1] === "\n")
+        o += 2;
+    const next = s[o];
+    if (next === undefined)
+        return i + 1;
+    if (next === "(") {
+        const end = skipBalanced(s, o, "(", ")");
+        if (end === undefined)
+            return undefined;
+        if (s[i] !== "$" || s[o + 1] !== "(" || arithmeticHidesRun(s.slice(o + 2, end - 2)))
+            word.substitution = true;
+        return end;
+    }
+    if (next === "[") {
+        const end = s.indexOf("]", o);
+        word.substitution = true;
+        return end < 0 ? undefined : end + 1;
+    }
+    if (next === "{") {
+        const end = skipBalanced(s, o, "{", "}");
+        if (end !== undefined && carriesSubstitution(s.slice(i, end)))
+            word.substitution = true;
+        return end;
+    }
+    if (next === "'" && !inDoubleQuotes) {
+        let j = o + 1;
+        while (j < s.length && s[j] !== "'")
+            j += s[j] === "\\" ? 2 : 1;
+        return j < s.length ? j + 1 : undefined;
+    }
+    if (/[A-Za-z_]/.test(next)) {
+        let j = o + 1;
+        while (j < s.length && /[A-Za-z0-9_]/.test(s[j]))
+            j++;
+        return j;
+    }
+    return SPECIAL_PARAMS.includes(next) ? o + 1 : i + 1;
+}
+export function skipBalanced(s, i, open, close) {
+    const stack = [];
+    for (let j = i; j < s.length; j++) {
+        const ch = s[j];
+        const top = stack[stack.length - 1];
+        if (ch === "\\") {
+            j++;
+            continue;
+        }
+        if (top?.quote === true) {
+            if (ch === '"')
+                top.quote = false;
+            else if (ch === "$" && (s[j + 1] === "(" || s[j + 1] === "{")) {
+                stack.push({ closer: s[j + 1] === "(" ? ")" : "}", quote: false });
+                j++;
+            }
+            else if (ch === "`") {
+                const k = s.indexOf("`", j + 1);
+                if (k < 0)
+                    return undefined;
+                j = k;
+            }
+            continue;
+        }
+        if (ch === "'") {
+            const k = s.indexOf("'", j + 1);
+            if (k < 0)
+                return undefined;
+            j = k;
+            continue;
+        }
+        if (ch === '"') {
+            if (top !== undefined)
+                top.quote = true;
+            continue;
+        }
+        if (ch === "`") {
+            const k = s.indexOf("`", j + 1);
+            if (k < 0)
+                return undefined;
+            j = k;
+            continue;
+        }
+        if (ch === open || ch === "(" || ch === "{") {
+            stack.push({ closer: ch === "(" ? ")" : "}", quote: false });
+            continue;
+        }
+        if (ch === close || ch === ")" || ch === "}") {
+            if (stack.pop()?.closer !== ch)
+                return undefined;
+            if (stack.length === 0)
+                return j + 1;
+        }
+    }
+    return undefined;
+}
+export function skipHeredocBodies(s, i, docs) {
+    let substitution = false;
+    for (const { delimiter, quoted, dash } of docs) {
+        for (;;) {
+            if (i >= s.length)
+                return undefined;
+            let eol = s.indexOf("\n", i);
+            let line = s.slice(i, eol < 0 ? s.length : eol);
+            while (!quoted && eol >= 0 && (/\\+$/.exec(line)?.[0].length ?? 0) % 2 === 1) {
+                const next = s.indexOf("\n", eol + 1);
+                line = line.slice(0, -1) + s.slice(eol + 1, next < 0 ? s.length : next);
+                eol = next;
+            }
+            i = eol < 0 ? s.length : eol + 1;
+            if ((dash ? line.replace(/^\t+/, "") : line) === delimiter)
+                break;
+            if (!quoted && carriesSubstitution(line))
+                substitution = true;
+        }
+    }
+    return { end: i, substitution };
+}
+export function matchOp(s, i, ops) {
+    let best;
+    for (const op of ops)
+        if (s.startsWith(op, i) && (best === undefined || op.length > best.length))
+            best = op;
+    return best;
+}

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

@@ -0,0 +1,297 @@
+/**
+ * The wrapper programs the tightening reader ({@link import("./shell-lexer.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
+ * candidate per peeled layer, so a deny on the wrapper itself (`Bash(sudo:*)`) and a deny on the wrapped
+ * program both reach.
+ *
+ * The option grammar of every row is CLOSED, and that is the whole safety argument of the peel: a
+ * wrapper option the row does not name — short or long — stops the peel with an `unreadable` word (the
+ * caller asks a person) instead of guessing its arity, because a wrong guess names the option's VALUE
+ * or an operand as the program — a phantom run no deny matches. Three adversarial rounds found exactly
+ * that shape behind every "unknown is value-less" reading; the closed sets end the family rather than
+ * the instance. Growing a row is a data edit with upstream's manual page as its source.
+ *
+ * Per row: `valueFlags` — options whose value is the NEXT word (`-u root`; the attached `-uroot` and
+ * `--user=root` spellings are one word and need no row); `flags` — value-less options, including those
+ * whose value may only be ATTACHED (`--default-signal[=SIG]`, `xargs -i[R]`: bare, they take nothing);
+ * `attached` — short options whose OPTIONAL value may only be attached (`xargs -i[R]`: the rest of the cluster
+ * is the value, the next word never is); `commandString` — options whose value is a whole COMMAND STRING (`env -S 'rm -r x'`), unreadable here;
+ * `positional` — an operand that must precede the command (a priority, a cpu mask, a lock file; a word
+ * that does not match is unreadable, never the program); `duration` — `timeout`'s duration word;
+ * `bareDash` — `env -` (the obsolete spelling of `-i`); `assignments` — the wrapper takes `NAME=value`
+ * operands before its command (`env`, `sudo`; read dequoted, `env 'FOO=1' cmd`); `viaShell` — the program EVALUATES its
+ * operands as shell input (a command string, a script file, an expression: `watch`, `script`, `eval`,
+ * `source`, `bash -c`, `trap`, `let`), so the program behind it is never readable from the words — the
+ * string is not split and judged (upstream splits on whitespace; this reader takes the strict word);
+ * `executes` — a program that is NOT a wrapper but runs a command named after one of these words ANYWHERE
+ * in its argv (`find … -exec rm -r {} +`): such a word, or any expansion among its arguments (it could
+ * expand to that word), makes the program behind it unreadable; the program's own run is still read.
+ */
+export declare const SHELL_WRAPPER_TABLE: {
+    readonly command: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly ["-p"];
+        readonly commandString: readonly [];
+    };
+    readonly builtin: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly noglob: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly nocorrect: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly exec: {
+        readonly valueFlags: readonly ["-a"];
+        readonly flags: readonly ["-c", "-l"];
+        readonly commandString: readonly [];
+    };
+    readonly env: {
+        readonly valueFlags: readonly ["-u", "-C", "-a", "-P", "--unset", "--chdir", "--argv0"];
+        readonly flags: readonly ["-i", "-0", "-v", "--ignore-environment", "--null", "--debug", "--list-signal-handling", "--default-signal", "--ignore-signal", "--block-signal", "--help", "--version"];
+        readonly commandString: readonly ["-S", "--split-string"];
+        readonly bareDash: true;
+        readonly assignments: true;
+    };
+    readonly sudo: {
+        readonly valueFlags: readonly ["-u", "-g", "-U", "-C", "-D", "-h", "-p", "-r", "-R", "-t", "-T", "--user", "--group", "--other-user", "--close-from", "--chdir", "--host", "--prompt", "--role", "--chroot", "--type", "--command-timeout", "-a", "--auth-type"];
+        readonly flags: readonly ["-A", "-b", "-E", "-H", "-i", "-K", "-k", "-l", "-n", "-P", "-S", "-s", "-V", "-v", "--askpass", "--background", "--preserve-env", "--set-home", "--login", "--remove-timestamp", "--reset-timestamp", "--list", "--non-interactive", "--preserve-groups", "--stdin", "--shell", "--version", "--validate", "--bell", "--help"];
+        readonly commandString: readonly [];
+        readonly assignments: true;
+    };
+    readonly doas: {
+        readonly valueFlags: readonly ["-a", "-u", "-C"];
+        readonly flags: readonly ["-L", "-n", "-s"];
+        readonly commandString: readonly [];
+    };
+    readonly pkexec: {
+        readonly valueFlags: readonly ["--user"];
+        readonly flags: readonly ["--disable-internal-agent", "--keep-cwd", "--version", "--help"];
+        readonly commandString: readonly [];
+    };
+    readonly nohup: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly ["--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly time: {
+        readonly valueFlags: readonly ["-o", "--output", "-f", "--format"];
+        readonly flags: readonly ["-p", "-a", "-v", "-q", "--append", "--portability", "--verbose", "--quiet", "--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly nice: {
+        readonly valueFlags: readonly ["-n", "--adjustment"];
+        readonly flags: readonly ["--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly timeout: {
+        readonly valueFlags: readonly ["-k", "-s", "--kill-after", "--signal"];
+        readonly flags: readonly ["-v", "--foreground", "--preserve-status", "--verbose", "--help", "--version"];
+        readonly commandString: readonly [];
+        readonly duration: true;
+    };
+    readonly stdbuf: {
+        readonly valueFlags: readonly ["-i", "-o", "-e", "--input", "--output", "--error"];
+        readonly flags: readonly ["--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly xargs: {
+        readonly valueFlags: readonly ["-n", "-L", "-P", "-I", "-d", "-s", "-a", "-E", "--max-args", "--max-procs", "--delimiter", "--max-chars", "--arg-file", "--process-slot-var"];
+        readonly flags: readonly ["-0", "-r", "-t", "-x", "-p", "-o", "--null", "--no-run-if-empty", "--verbose", "--exit", "--interactive", "--open-tty", "--show-limits", "--help", "--version", "--replace", "--eof", "--max-lines"];
+        readonly attached: readonly ["-i", "-l"];
+        readonly commandString: readonly [];
+    };
+    readonly watch: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly ionice: {
+        readonly valueFlags: readonly ["-c", "-n", "-p", "-P", "-u", "--class", "--classdata", "--pid", "--pgid", "--uid"];
+        readonly flags: readonly ["-t", "--ignore", "-h", "--help", "-V", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly setsid: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly ["-c", "-f", "-w", "--ctty", "--fork", "--wait", "--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly taskset: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly ["-a", "-p", "-c", "--all-tasks", "--pid", "--cpu-list", "--help", "--version"];
+        readonly commandString: readonly [];
+        readonly positional: RegExp;
+    };
+    readonly chrt: {
+        readonly valueFlags: readonly ["-p", "--pid", "-T", "-P", "-D", "--sched-runtime", "--sched-period", "--sched-deadline"];
+        readonly flags: readonly ["-b", "-f", "-i", "-o", "-r", "-d", "-m", "-a", "-R", "-v", "--batch", "--fifo", "--idle", "--other", "--rr", "--deadline", "--max", "--all-tasks", "--reset-on-fork", "--verbose", "--help", "--version"];
+        readonly commandString: readonly [];
+        readonly positional: RegExp;
+    };
+    readonly strace: {
+        readonly valueFlags: readonly ["-e", "-o", "-p", "-s", "-E", "-P", "-S", "-a", "-b", "-I", "-u", "-X", "-O", "-U", "--output", "--trace", "--expr", "--attach", "--string-limit", "--env", "--trace-path", "--columns", "--user", "--interruptible", "--detach-on", "--const-print-style", "--summary-sort-by", "--summary-syscall-overhead", "--summary-columns"];
+        readonly flags: readonly ["-f", "-ff", "-c", "-C", "-d", "-D", "-h", "-i", "-k", "-q", "-qq", "-r", "-t", "-tt", "-ttt", "-T", "-v", "-V", "-w", "-x", "-xx", "-y", "-yy", "-z", "-Z", "-F", "--follow-forks", "--summary-only", "--summary", "--debug", "--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly ltrace: {
+        readonly valueFlags: readonly ["-a", "-A", "-e", "-l", "-n", "-o", "-p", "-s", "-u", "-x", "-D", "-F", "--align", "--config", "--debug", "--indent", "--library", "--output", "--string-max", "-w", "--where"];
+        readonly flags: readonly ["-c", "-C", "-f", "-i", "-L", "-r", "-S", "-t", "-tt", "-ttt", "-T", "-V", "--demangle", "--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly flock: {
+        readonly valueFlags: readonly ["-w", "-E", "--timeout", "--wait", "--conflict-exit-code"];
+        readonly flags: readonly ["-s", "-x", "-u", "-n", "-o", "-F", "--shared", "--exclusive", "--unlock", "--nonblock", "--nb", "--close", "--no-fork", "--verbose", "--help", "--version"];
+        readonly commandString: readonly ["-c", "--command"];
+        readonly positional: RegExp;
+    };
+    readonly script: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly ["-c", "--command"];
+        readonly viaShell: true;
+    };
+    readonly unshare: {
+        readonly valueFlags: readonly ["-R", "-w", "-S", "-G", "--setuid", "--setgid", "--root", "--wd", "--propagation", "--setgroups", "--monotonic", "--boottime", "--map-user", "--map-group"];
+        readonly flags: readonly ["-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"];
+        readonly commandString: readonly [];
+    };
+    readonly nsenter: {
+        readonly valueFlags: readonly ["-t", "-S", "-G", "--target", "--setuid", "--setgid"];
+        readonly flags: readonly ["-a", "-m", "-u", "-i", "-n", "-p", "-U", "-C", "-T", "-r", "-w", "-F", "-Z", "--all", "--mount", "--uts", "--ipc", "--net", "--pid", "--user", "--cgroup", "--time", "--root", "--wd", "--no-fork", "--preserve-credentials", "--help", "--version"];
+        readonly commandString: readonly [];
+    };
+    readonly eval: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly source: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly ".": {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly trap: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly let: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly sh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly bash: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly zsh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly dash: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly ksh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly fish: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly csh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly tcsh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly find: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly executes: readonly ["-exec", "-execdir", "-ok", "-okdir"];
+    };
+    readonly compgen: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly executes: readonly ["-C", "-F"];
+    };
+    readonly complete: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly executes: readonly ["-C", "-F"];
+    };
+};
+export type ShellWrapperName = keyof typeof SHELL_WRAPPER_TABLE;
+/** The shape of one row (see the table's contract). */
+export interface ShellWrapperRow {
+    readonly valueFlags: readonly string[];
+    readonly flags: readonly string[];
+    readonly attached?: readonly string[];
+    readonly commandString: readonly string[];
+    readonly positional?: RegExp;
+    readonly duration?: true;
+    readonly bareDash?: true;
+    readonly assignments?: true;
+    readonly viaShell?: true;
+    readonly executes?: readonly string[];
+}
+/** Builtins whose OPERANDS name variables: an operand spelling an array element with a non-numeric
+ *  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
+ *  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. */
+export declare function evaluatesOperand(run: readonly {
+    readonly text: string;
+    readonly raw: string;
+}[]): boolean;

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

@@ -0,0 +1,58 @@
+export const SHELL_WRAPPER_TABLE = {
+    command: { valueFlags: [], flags: ["-p"], commandString: [] },
+    builtin: { valueFlags: [], flags: [], commandString: [] },
+    noglob: { valueFlags: [], flags: [], commandString: [] },
+    nocorrect: { valueFlags: [], flags: [], commandString: [] },
+    exec: { valueFlags: ["-a"], flags: ["-c", "-l"], commandString: [] },
+    env: { valueFlags: ["-u", "-C", "-a", "-P", "--unset", "--chdir", "--argv0"], flags: ["-i", "-0", "-v", "--ignore-environment", "--null", "--debug", "--list-signal-handling", "--default-signal", "--ignore-signal", "--block-signal", "--help", "--version"], commandString: ["-S", "--split-string"], bareDash: true, assignments: true },
+    sudo: { valueFlags: ["-u", "-g", "-U", "-C", "-D", "-h", "-p", "-r", "-R", "-t", "-T", "--user", "--group", "--other-user", "--close-from", "--chdir", "--host", "--prompt", "--role", "--chroot", "--type", "--command-timeout", "-a", "--auth-type"], flags: ["-A", "-b", "-E", "-H", "-i", "-K", "-k", "-l", "-n", "-P", "-S", "-s", "-V", "-v", "--askpass", "--background", "--preserve-env", "--set-home", "--login", "--remove-timestamp", "--reset-timestamp", "--list", "--non-interactive", "--preserve-groups", "--stdin", "--shell", "--version", "--validate", "--bell", "--help"], commandString: [], assignments: true },
+    doas: { valueFlags: ["-a", "-u", "-C"], flags: ["-L", "-n", "-s"], commandString: [] },
+    pkexec: { valueFlags: ["--user"], flags: ["--disable-internal-agent", "--keep-cwd", "--version", "--help"], commandString: [] },
+    nohup: { valueFlags: [], flags: ["--help", "--version"], commandString: [] },
+    time: { valueFlags: ["-o", "--output", "-f", "--format"], flags: ["-p", "-a", "-v", "-q", "--append", "--portability", "--verbose", "--quiet", "--help", "--version"], commandString: [] },
+    nice: { valueFlags: ["-n", "--adjustment"], flags: ["--help", "--version"], commandString: [] },
+    timeout: { valueFlags: ["-k", "-s", "--kill-after", "--signal"], flags: ["-v", "--foreground", "--preserve-status", "--verbose", "--help", "--version"], commandString: [], duration: true },
+    stdbuf: { valueFlags: ["-i", "-o", "-e", "--input", "--output", "--error"], flags: ["--help", "--version"], commandString: [] },
+    xargs: { valueFlags: ["-n", "-L", "-P", "-I", "-d", "-s", "-a", "-E", "--max-args", "--max-procs", "--delimiter", "--max-chars", "--arg-file", "--process-slot-var"], flags: ["-0", "-r", "-t", "-x", "-p", "-o", "--null", "--no-run-if-empty", "--verbose", "--exit", "--interactive", "--open-tty", "--show-limits", "--help", "--version", "--replace", "--eof", "--max-lines"], attached: ["-i", "-l"], commandString: [] },
+    watch: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    ionice: { valueFlags: ["-c", "-n", "-p", "-P", "-u", "--class", "--classdata", "--pid", "--pgid", "--uid"], flags: ["-t", "--ignore", "-h", "--help", "-V", "--version"], commandString: [] },
+    setsid: { valueFlags: [], flags: ["-c", "-f", "-w", "--ctty", "--fork", "--wait", "--help", "--version"], commandString: [] },
+    taskset: { valueFlags: [], flags: ["-a", "-p", "-c", "--all-tasks", "--pid", "--cpu-list", "--help", "--version"], commandString: [], positional: /^(?:0x)?[\da-f]+$|^[\d,:-]+$/i },
+    chrt: { valueFlags: ["-p", "--pid", "-T", "-P", "-D", "--sched-runtime", "--sched-period", "--sched-deadline"], flags: ["-b", "-f", "-i", "-o", "-r", "-d", "-m", "-a", "-R", "-v", "--batch", "--fifo", "--idle", "--other", "--rr", "--deadline", "--max", "--all-tasks", "--reset-on-fork", "--verbose", "--help", "--version"], commandString: [], positional: /^\d+$/ },
+    strace: { valueFlags: ["-e", "-o", "-p", "-s", "-E", "-P", "-S", "-a", "-b", "-I", "-u", "-X", "-O", "-U", "--output", "--trace", "--expr", "--attach", "--string-limit", "--env", "--trace-path", "--columns", "--user", "--interruptible", "--detach-on", "--const-print-style", "--summary-sort-by", "--summary-syscall-overhead", "--summary-columns"], flags: ["-f", "-ff", "-c", "-C", "-d", "-D", "-h", "-i", "-k", "-q", "-qq", "-r", "-t", "-tt", "-ttt", "-T", "-v", "-V", "-w", "-x", "-xx", "-y", "-yy", "-z", "-Z", "-F", "--follow-forks", "--summary-only", "--summary", "--debug", "--help", "--version"], commandString: [] },
+    ltrace: { valueFlags: ["-a", "-A", "-e", "-l", "-n", "-o", "-p", "-s", "-u", "-x", "-D", "-F", "--align", "--config", "--debug", "--indent", "--library", "--output", "--string-max", "-w", "--where"], flags: ["-c", "-C", "-f", "-i", "-L", "-r", "-S", "-t", "-tt", "-ttt", "-T", "-V", "--demangle", "--help", "--version"], commandString: [] },
+    flock: { valueFlags: ["-w", "-E", "--timeout", "--wait", "--conflict-exit-code"], flags: ["-s", "-x", "-u", "-n", "-o", "-F", "--shared", "--exclusive", "--unlock", "--nonblock", "--nb", "--close", "--no-fork", "--verbose", "--help", "--version"], commandString: ["-c", "--command"], positional: /^/ },
+    script: { valueFlags: [], flags: [], commandString: ["-c", "--command"], viaShell: true },
+    unshare: { valueFlags: ["-R", "-w", "-S", "-G", "--setuid", "--setgid", "--root", "--wd", "--propagation", "--setgroups", "--monotonic", "--boottime", "--map-user", "--map-group"], flags: ["-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"], commandString: [] },
+    nsenter: { valueFlags: ["-t", "-S", "-G", "--target", "--setuid", "--setgid"], flags: ["-a", "-m", "-u", "-i", "-n", "-p", "-U", "-C", "-T", "-r", "-w", "-F", "-Z", "--all", "--mount", "--uts", "--ipc", "--net", "--pid", "--user", "--cgroup", "--time", "--root", "--wd", "--no-fork", "--preserve-credentials", "--help", "--version"], commandString: [] },
+    eval: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    source: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    ".": { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    trap: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    let: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    sh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    bash: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    zsh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    dash: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    ksh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    fish: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    csh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    tcsh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    find: { valueFlags: [], flags: [], commandString: [], executes: ["-exec", "-execdir", "-ok", "-okdir"] },
+    compgen: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
+    complete: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
+};
+export const VARIABLE_OPERAND_BUILTINS = new Set(["printf", "unset", "read", "mapfile", "readarray", "declare", "typeset", "local", "export", "readonly", "test", "[", "[["]);
+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)));
+}
+function namesArrayElement(word) {
+    const open = word.indexOf("[");
+    if (open <= 0 || !/[A-Za-z0-9_]/.test(word[open - 1]))
+        return false;
+    const close = word.indexOf("]", open);
+    return close > 0 && /[A-Za-z_$]/.test(word.slice(open + 1, close));
+}

package/dist/core/store-contracts/permission-rule-sync-contract.js

@@ -5,14 +5,15 @@ const GLOBAL = { kind: "global" };
 function add(actor, counter, origin = "user") {
     return { dot: { actor, counter }, origin, createdAt: "2026-01-01T00:00:00.000Z" };
 }
-function rule(text, adds, scope = GLOBAL) {
+function rule(text, adds, scope = GLOBAL, behavior = "allow") {
     const m = /^Bash\((.+?)(:\*)?\)$/.exec(text);
     if (m === null || m[1] === undefined)
         throw new Error(`contract fixture rule "${text}" is not a Bash(...) form`);
-    return { rule: text, tool: "Bash", match: m[2] !== undefined ? "prefix" : "exact", command: m[1], scope, adds };
+    return { behavior, rule: text, tool: "Bash", match: m[2] !== undefined ? "prefix" : "exact", command: m[1], scope, adds };
 }
-function tomb(text, removed, deletedBy, scope = GLOBAL) {
+function tomb(text, removed, deletedBy, scope = GLOBAL, behavior = "allow") {
     return {
+        behavior,
         rule: text,
         scope,
         removedDots: removed.map(([actor, counter]) => ({ actor, counter })),
@@ -25,10 +26,10 @@ function state(rules = [], tombstones = []) {
 function liveDots(s) {
     const out = new Set();
     for (const r of s.rules) {
-        const removed = s.tombstones.filter((t) => t.rule === r.rule && sameScope(t.scope, r.scope)).flatMap((t) => t.removedDots);
+        const removed = s.tombstones.filter((t) => t.behavior === r.behavior && t.rule === r.rule && sameScope(t.scope, r.scope)).flatMap((t) => t.removedDots);
         for (const a of r.adds) {
             if (!removed.some((d) => d.actor === a.dot.actor && d.counter === a.dot.counter))
-                out.add(`${r.rule}|${a.dot.actor}#${a.dot.counter}`);
+                out.add(`${r.behavior === "allow" ? "" : r.behavior + ":"}${r.rule}|${a.dot.actor}#${a.dot.counter}`);
         }
     }
     return out;
@@ -41,7 +42,7 @@ function sameScope(a, b) {
     return b.kind === "project" && a.root === b.root;
 }
 function allDots(s) {
-    return new Set(s.rules.flatMap((r) => r.adds.map((a) => `${r.rule}|${a.dot.actor}#${a.dot.counter}`)));
+    return new Set(s.rules.flatMap((r) => r.adds.map((a) => `${r.behavior === "allow" ? "" : r.behavior + ":"}${r.rule}|${a.dot.actor}#${a.dot.counter}`)));
 }
 export async function permissionRuleSyncContract(hooks = {}) {
     const join = hooks.join ?? joinRuleStates;
@@ -141,8 +142,24 @@ export async function permissionRuleSyncContract(hooks = {}) {
         assert.deepStrictEqual(new Set(ab.tombstones[0]?.removedDots.map((d) => `${d.actor}#${d.counter}`)), new Set(["a#1", "a#2"]), "the union — a one-sided pick can drop an observed removal");
         assert.deepStrictEqual(ab, join(b, a));
     });
+    run("behavior is an identity member: the same text as an allow and as a deny are two rows, each with its own adds and its own tombstone", async () => {
+        const both = state([rule("Bash(ls)", [add("a", 1)]), rule("Bash(ls)", [add("a", 2)], GLOBAL, "deny")], [tomb("Bash(ls)", [["a", 1]], ["a", 3])]);
+        const merged = join(both, state());
+        assert.strictEqual(merged.rules.length, 2, "one text, two behaviors — two identity groups, never folded");
+        assert.deepStrictEqual(liveDots(merged), new Set(["deny:Bash(ls)|a#2"]), "the allow tombstone must not reach the deny's add");
+        assert.deepStrictEqual(join(state(), both), merged, "commutative across the behavior axis");
+        const badWord = state([rule("Bash(pwd)", [add("b", 1)])], [Object.assign(tomb("Bash(pwd)", [["b", 1]], ["b", 2]), { behavior: "maybe" })]);
+        const screened = join(badWord, state());
+        assert.strictEqual(screened.tombstones.length, 0, "an unreadable behavior word on a tombstone must not land");
+        assert.ok(liveDots(screened).has("Bash(pwd)|b#1"), "…and must not cover anything");
+    });
+    run("closed-set identity: a row carrying a behavior word outside the closed set is refused like invalid text", async () => {
+        const forgedWord = Object.assign(rule("Bash(ls)", [add("z", 1)]), { behavior: "sometimes" });
+        const merged = join(state([forgedWord]), state());
+        assert.strictEqual(allDots(merged).size, 0, "a behavior this engine cannot read must not become an allow (or a deny) by falling through");
+    });
     run("metadata re-projection (r2-F2): a record whose stored fields contradict its rule text is refused, both orders", async () => {
-        const forged = { rule: "Bash(ls)", tool: "Bash", match: "prefix", command: "rm -rf /", scope: GLOBAL, adds: [add("z", 1)] };
+        const forged = { behavior: "allow", rule: "Bash(ls)", tool: "Bash", match: "prefix", command: "rm -rf /", scope: GLOBAL, adds: [add("z", 1)] };
         const clean = state([rule("Bash(git status)", [add("a", 1)])]);
         const ab = join(state([forged]), clean);
         const ba = join(clean, state([forged]));
@@ -150,9 +167,11 @@ export async function permissionRuleSyncContract(hooks = {}) {
         assert.deepStrictEqual(ab, ba, "refusal must preserve commutativity");
         assert.ok(allDots(ab).has("Bash(git status)|a#1"), "refusing one record must not disturb the rest");
     });
-    run("single-validator door: an illegal rule shape (bare-interpreter prefix) cannot ride a join", async () => {
+    run("single-validator door: an illegal ALLOW shape (bare-interpreter prefix) cannot ride a join — while the same text as a DENY is a legitimate wide tightening and lands", async () => {
         const merged = join(state([rule("Bash(node:*)", [add("z", 1)])]), state());
         assert.strictEqual(allDots(merged).size, 0, "Bash(node:*) must be refused by the shared validator inside the join");
+        const denied = join(state([rule("Bash(node:*)", [add("z", 1)], GLOBAL, "deny")]), state());
+        assert.deepStrictEqual(allDots(denied), new Set(["deny:Bash(node:*)|z#1"]), "the tightening floor admits the interpreter-headed prefix");
     });
     run("durable two-member face (design/382 §4.3): a session-scope row or tombstone never survives a join, and never poisons the round", async () => {
         const sessionScope = { kind: "session", sessionId: "sess-1" };
@@ -168,8 +187,8 @@ export async function permissionRuleSyncContract(hooks = {}) {
         const scopeA = { kind: "project", root: "/x" };
         const scopeB = { kind: "project", root: "/x a" };
         const s = state([rule("Bash(ls)", [add("v", 1)], scopeA), rule("Bash(ls)", [add("w", 1)], scopeB)], [
-            { rule: "Bash(ls)", scope: scopeA, removedDots: [{ actor: "v", counter: 1 }], deletedBy: { actor: "a 1", counter: 2 } },
-            { rule: "Bash(ls)", scope: scopeB, removedDots: [{ actor: "w", counter: 1 }], deletedBy: { actor: "1", counter: 2 } },
+            { behavior: "allow", rule: "Bash(ls)", scope: scopeA, removedDots: [{ actor: "v", counter: 1 }], deletedBy: { actor: "a 1", counter: 2 } },
+            { behavior: "allow", rule: "Bash(ls)", scope: scopeB, removedDots: [{ actor: "w", counter: 1 }], deletedBy: { actor: "1", counter: 2 } },
         ]);
         const merged = join(s, state());
         assert.strictEqual(merged.tombstones.length, 2, "two distinct delete intents must both survive — a colliding key folds one away");