@sema-agent/core 7.45.0 → 7.46.0

package/dist/core/sensitive-path-policy.js

@@ -2,6 +2,7 @@ import { homedir } from "node:os";
 import { isAbsolute, join, resolve } from "node:path";
 import { canonicalizeTarget, expandHomeTilde, isAbsoluteForFamily, isWinFormPath, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
 import { compileSegmentPattern, matchSegmentPatterns, READ_FACE_BUILTIN_DENY_TABLE, readDenyPatternRun } from "../tools/fs/read-deny.js";
+import { agentConfigDirSegments, agentConfigDirTail, checkedAgentConfigDir } from "./agent-config-dir.js";
 import { isProtectedWrite, protectivePathTargetOf } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
 import { symlinkChainHops } from "./path-identity.js";
@@ -32,6 +33,7 @@ export const RECOMMENDED_SENSITIVE_PATTERNS = [
     ".mcp.json",
     ".ai-agent/.env",
     ".sema/engine-data/.env",
+    ".sema/config-lkg-*.json",
     ".codex/config.toml",
     ".cursor/mcp.json",
     ".continue/config.json",
@@ -115,6 +117,19 @@ function matchSensitive(canonicalKey, compiled, aliasResolved) {
 }
 export function createSensitivePathPolicy(opts) {
     const compiled = compilePatterns(opts.patterns);
+    const configRoot = checkedAgentConfigDir(opts.agentConfigDir, "createSensitivePathPolicy agentConfigDir");
+    const configRows = configRoot === undefined ? [] : opts.patterns.flatMap((raw) => {
+        const tail = agentConfigDirTail(raw, !CASE_INSENSITIVE_FS);
+        return tail === undefined ? [] : [{ raw, tail }];
+    });
+    const configTwins = async (signal) => {
+        if (configRoot === undefined || configRows.length === 0)
+            return [];
+        const fold = CASE_INSENSITIVE_FS ? "ascii" : "none";
+        const lower = (segs) => (CASE_INSENSITIVE_FS ? segs.map((seg) => seg.replace(/[A-Z]/g, (c) => c.toLowerCase())) : segs);
+        const anchors = [configRoot, ...(await canonicalDataRootKeys(opts.env, [configRoot], signal))].map((root) => lower(agentConfigDirSegments(root)));
+        return configRows.map(({ raw, tail }) => ({ ...(compileSegmentPattern(tail, fold) ?? { raw, segments: [], foldAscii: CASE_INSENSITIVE_FS }), raw, anchors, rootedOnly: true }));
+    };
     const dataRootPaths = dataRootSpellings(opts.dataRoot);
     const guardedByName = opts.tools !== undefined ? new Set(opts.tools) : undefined;
     const family = (cwd) => pathFamilyOf({ root: opts.rootPath, cwd: cwd ?? opts.env.cwd });
@@ -130,12 +145,13 @@ export function createSensitivePathPolicy(opts) {
         }
         if (relative === "")
             return { kind: "clear" };
-        const hit = matchSensitive(relative ?? canon.key, compiled, canon.aliasResolved === true);
+        const twins = await configTwins(signal);
+        const hit = matchSensitive(relative ?? canon.key, [...compiled, ...twins], canon.aliasResolved === true);
         if (hit)
             return { kind: "hit", pattern: hit, via: "target" };
         if (relative === null) {
             for (const hop of await symlinkChainHops(opts.env, path, signal, fam, base)) {
-                const viaHop = matchSensitive(hop, compiled, false);
+                const viaHop = matchSensitive(hop, [...compiled, ...twins], false);
                 if (viaHop)
                     return { kind: "hit", pattern: viaHop, via: "chain" };
             }

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

@@ -0,0 +1,11 @@
+import type { ShellWrapperRow } from "./shell-wrapper-table.js";
+/**
+ * The PROJECTION {@link import("./shell-wrapper-table.js").SHELL_WRAPPER_TABLE} is: the second lexer's view of the program read model's rows (`program-read-model.ts`
+ * — one table of program facts, read through the binary gate). A launcher row's options by arity (a value word, a
+ * switch or an attached-only value, a command string), its required operand (a duration, or the spelling it must have),
+ * its bare-dash switch and its `NAME=value` operands; a row that runs its operands, or a code body, as shell input
+ * (`viaShell`); an option that runs a command (`executes`). The table is this projection written out (its
+ * literal type is the export's), and `test/shell-wrapper-table-projection.test.ts` pins it equal — a launcher fact is
+ * edited in its row, never here.
+ */
+export declare function shellWrapperProjection(): Record<string, ShellWrapperRow>;

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

@@ -0,0 +1,56 @@
+import { programRows } from "../tools/fs/program-read-model.js";
+import { DURATION_SPELLING } from "../tools/fs/program-read-model.rows.js";
+export function shellWrapperProjection() {
+    const out = {};
+    for (const row of programRows()) {
+        const projected = projectRow(row);
+        if (projected !== undefined)
+            out[row.key] = projected;
+    }
+    return out;
+}
+function spellings(row) {
+    const out = new Map();
+    for (const g of row.grammars) {
+        const add = (spelling, spec) => {
+            const e = out.get(spelling) ?? { spec, arities: new Set() };
+            e.arities.add(spec.arity);
+            out.set(spelling, e);
+        };
+        for (const [l, spec] of Object.entries(g.short))
+            add(`-${l}`, spec);
+        for (const [n, spec] of Object.entries(g.long))
+            add(`--${n}`, spec);
+        for (const [n, spec] of Object.entries(g.dashWords ?? {}))
+            add(`-${n}`, spec);
+    }
+    return [...out].map(([spelling, e]) => ({ spelling, spec: e.spec, arity: e.arities.size === 1 ? [...e.arities][0] : "disputed" }));
+}
+const runsCommand = (spec) => spec.effect === "executes" || spec.value?.kind === "shell-text" || spec.value?.kind === "command";
+function projectRow(row) {
+    const sorted = (xs) => [...new Set(xs)].sort();
+    const all = spellings(row);
+    const viaShell = row.reentry?.kind === "shell" || row.launcher?.shellText === true || row.body === "first-operand" || row.body === "assignment-values" || (row.operands?.rest?.kind === "program-text" && row.operands.rest.language === "arithmetic");
+    if (row.launcher === undefined) {
+        if (viaShell)
+            return { valueFlags: [], flags: [], commandString: [], viaShell: true };
+        const executes = sorted(all.filter((o) => runsCommand(o.spec)).map((o) => o.spelling));
+        return executes.length > 0 ? { valueFlags: [], flags: [], commandString: [], executes } : undefined;
+    }
+    const commandString = sorted(all.filter((o) => o.spec.value?.kind === "shell-text").map((o) => o.spelling));
+    const values = all.filter((o) => o.spec.value?.kind !== "shell-text");
+    const attached = sorted(values.filter((o) => o.arity === "attached" && !o.spelling.startsWith("--")).map((o) => o.spelling));
+    const required = row.launcher.requiredOperands ?? 0;
+    const duration = required > 0 && row.launcher.requiredOperandSpelling === DURATION_SPELLING;
+    return {
+        valueFlags: sorted(values.filter((o) => o.arity === 1).map((o) => o.spelling)),
+        flags: sorted(values.filter((o) => o.arity === 0 || (o.arity === "attached" && o.spelling.startsWith("--"))).map((o) => o.spelling)),
+        ...(attached.length > 0 ? { attached } : {}),
+        commandString,
+        ...(required > 0 && !duration ? { positional: row.launcher.requiredOperandSpelling ?? /^/ } : {}),
+        ...(duration ? { duration: true } : {}),
+        ...(row.launcher.bareDash === true ? { bareDash: true } : {}),
+        ...(row.launcher.assignmentOperands === true ? { assignments: true } : {}),
+        ...(viaShell ? { viaShell: true } : {}),
+    };
+}

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

@@ -11,7 +11,10 @@
  * 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.
+ * the instance. The table is the PROJECTION of the program read model's rows
+ * ({@link import("./shell-wrapper-projection.js").shellWrapperProjection}) written
+ * out with its literal type: a launcher fact is edited in its row (one table of program facts, read by the binary gate
+ * and by the read station alike), and `test/shell-wrapper-table-projection.test.ts` keeps the two equal.
  *
  * 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
@@ -56,26 +59,26 @@ export declare const SHELL_WRAPPER_TABLE: {
         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 valueFlags: readonly ["--argv0", "--chdir", "--unset", "-C", "-P", "-a", "-u"];
+        readonly flags: readonly ["--debug", "--default-signal", "--help", "--ignore-environment", "--ignore-signal", "--list-signal-handling", "--version", "-i", "-v"];
+        readonly commandString: readonly ["--split-string", "-S"];
         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 valueFlags: readonly ["--auth-type", "--chdir", "--chroot", "--close-from", "--command-timeout", "--group", "--host", "--other-user", "--prompt", "--role", "--type", "--user", "-C", "-D", "-R", "-T", "-U", "-a", "-g", "-h", "-p", "-r", "-t", "-u"];
+        readonly flags: readonly ["--askpass", "--background", "--bell", "--help", "--list", "--login", "--non-interactive", "--preserve-env", "--preserve-groups", "--remove-timestamp", "--reset-timestamp", "--set-home", "--shell", "--stdin", "--validate", "--version", "-A", "-E", "-H", "-K", "-P", "-S", "-V", "-b", "-i", "-k", "-l", "-n", "-s", "-v"];
         readonly commandString: readonly [];
         readonly assignments: true;
     };
     readonly doas: {
-        readonly valueFlags: readonly ["-a", "-u", "-C"];
+        readonly valueFlags: readonly ["-C", "-a", "-u"];
         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 flags: readonly ["--disable-internal-agent", "--help", "--keep-cwd", "--version"];
         readonly commandString: readonly [];
     };
     readonly nohup: {
@@ -84,29 +87,29 @@ export declare const SHELL_WRAPPER_TABLE: {
         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 valueFlags: readonly ["--format", "--output", "-f", "-o"];
+        readonly flags: readonly ["--append", "--help", "--portability", "--quiet", "--verbose", "--version", "-a", "-p", "-q", "-v"];
         readonly commandString: readonly [];
     };
     readonly nice: {
-        readonly valueFlags: readonly ["-n", "--adjustment"];
+        readonly valueFlags: readonly ["--adjustment", "-n"];
         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 valueFlags: readonly ["--kill-after", "--signal", "-k", "-s"];
+        readonly flags: readonly ["--foreground", "--help", "--preserve-status", "--verbose", "--version", "-v"];
         readonly commandString: readonly [];
         readonly duration: true;
     };
     readonly stdbuf: {
-        readonly valueFlags: readonly ["-i", "-o", "-e", "--input", "--output", "--error"];
+        readonly valueFlags: readonly ["--error", "--input", "--output", "-e", "-i", "-o"];
         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 valueFlags: readonly ["--arg-file", "--delimiter", "--max-args", "--max-chars", "--max-procs", "--process-slot-var", "-E", "-I", "-L", "-P", "-a", "-d", "-n", "-s"];
+        readonly flags: readonly ["--eof", "--exit", "--help", "--interactive", "--max-lines", "--no-run-if-empty", "--null", "--open-tty", "--replace", "--show-limits", "--verbose", "--version", "-0", "-o", "-p", "-r", "-t", "-x"];
         readonly attached: readonly ["-i", "-l"];
         readonly commandString: readonly [];
     };
@@ -117,57 +120,58 @@ export declare const SHELL_WRAPPER_TABLE: {
         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 valueFlags: readonly ["--class", "--classdata", "--pgid", "--pid", "--uid", "-P", "-c", "-n", "-p", "-u"];
+        readonly flags: readonly ["--help", "--ignore", "--version", "-V", "-h", "-t"];
         readonly commandString: readonly [];
     };
     readonly setsid: {
         readonly valueFlags: readonly [];
-        readonly flags: readonly ["-c", "-f", "-w", "--ctty", "--fork", "--wait", "--help", "--version"];
+        readonly flags: readonly ["--ctty", "--fork", "--help", "--version", "--wait", "-c", "-f", "-w"];
         readonly commandString: readonly [];
     };
     readonly taskset: {
         readonly valueFlags: readonly [];
-        readonly flags: readonly ["-a", "-p", "-c", "--all-tasks", "--pid", "--cpu-list", "--help", "--version"];
+        readonly flags: readonly ["--all-tasks", "--cpu-list", "--help", "--pid", "--version", "-a", "-c", "-p"];
         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 valueFlags: readonly ["--pid", "--sched-deadline", "--sched-period", "--sched-runtime", "-D", "-P", "-T", "-p"];
+        readonly flags: readonly ["--all-tasks", "--batch", "--deadline", "--fifo", "--help", "--idle", "--max", "--other", "--reset-on-fork", "--rr", "--verbose", "--version", "-R", "-a", "-b", "-d", "-f", "-i", "-m", "-o", "-r", "-v"];
         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 valueFlags: readonly ["--attach", "--columns", "--const-print-style", "--detach-on", "--env", "--expr", "--interruptible", "--output", "--string-limit", "--summary-columns", "--summary-sort-by", "--summary-syscall-overhead", "--trace", "--trace-path", "--user", "-E", "-I", "-O", "-P", "-S", "-U", "-X", "-a", "-b", "-e", "-o", "-p", "-s", "-u"];
+        readonly flags: readonly ["--debug", "--follow-forks", "--help", "--summary", "--summary-only", "--version", "-C", "-D", "-F", "-T", "-V", "-Z", "-c", "-d", "-f", "-h", "-i", "-k", "-q", "-r", "-t", "-v", "-w", "-x", "-y", "-z"];
         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 valueFlags: readonly ["--align", "--config", "--debug", "--indent", "--library", "--output", "--string-max", "--where", "-A", "-D", "-F", "-a", "-e", "-l", "-n", "-o", "-p", "-s", "-u", "-w", "-x"];
+        readonly flags: readonly ["--demangle", "--help", "--version", "-C", "-L", "-S", "-T", "-V", "-c", "-f", "-i", "-r", "-t"];
         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 valueFlags: readonly ["--conflict-exit-code", "--timeout", "--wait", "-E", "-w"];
+        readonly flags: readonly ["--close", "--exclusive", "--help", "--nb", "--no-fork", "--nonblock", "--shared", "--unlock", "--verbose", "--version", "-F", "-n", "-o", "-s", "-u", "-x"];
+        readonly commandString: readonly ["--command", "-c"];
         readonly positional: RegExp;
     };
     readonly script: {
         readonly valueFlags: readonly [];
         readonly flags: readonly [];
-        readonly commandString: readonly ["-c", "--command"];
+        readonly commandString: readonly ["--command", "-c"];
         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 valueFlags: readonly ["--boottime", "--map-group", "--map-user", "--monotonic", "--propagation", "--root", "--setgid", "--setgroups", "--setuid", "--wd", "-G", "-R", "-S", "-w"];
+        readonly flags: readonly ["--cgroup", "--fork", "--help", "--ipc", "--keep-caps", "--kill-child", "--map-current-user", "--map-root-user", "--mount", "--mount-proc", "--net", "--pid", "--time", "--user", "--uts", "--version", "-C", "-T", "-U", "-c", "-f", "-i", "-m", "-n", "-p", "-r", "-u"];
         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 valueFlags: readonly ["--setgid", "--setuid", "--target", "-G", "-S", "-t"];
+        readonly flags: readonly ["--all", "--cgroup", "--help", "--ipc", "--mount", "--net", "--no-fork", "--pid", "--preserve-credentials", "--root", "--time", "--user", "--uts", "--version", "--wd", "-C", "-F", "-T", "-U", "-Z", "-a", "-i", "-m", "-n", "-p", "-u"];
+        readonly attached: readonly ["-r", "-w"];
         readonly commandString: readonly [];
     };
     readonly eval: {
@@ -266,6 +270,112 @@ export declare const SHELL_WRAPPER_TABLE: {
         readonly commandString: readonly [];
         readonly executes: readonly ["-C", "-F"];
     };
+    readonly busybox: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly su: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly runuser: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly chroot: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly positional: RegExp;
+    };
+    readonly setpriv: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly numactl: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly prlimit: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly "systemd-run": {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly valgrind: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly firejail: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly bwrap: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+    };
+    readonly ash: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly mksh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly yash: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly pdksh: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly parallel: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly alias: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly viaShell: true;
+    };
+    readonly mapfile: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly executes: readonly ["-C"];
+    };
+    readonly readarray: {
+        readonly valueFlags: readonly [];
+        readonly flags: readonly [];
+        readonly commandString: readonly [];
+        readonly executes: readonly ["-C"];
+    };
 };
 export type ShellWrapperName = keyof typeof SHELL_WRAPPER_TABLE;
 /** The shape of one row (see the table's contract). */

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

@@ -1,30 +1,31 @@
+import { declaresOption, programRows } from "../tools/fs/program-read-model.js";
 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: [] },
+    env: { valueFlags: ["--argv0", "--chdir", "--unset", "-C", "-P", "-a", "-u"], flags: ["--debug", "--default-signal", "--help", "--ignore-environment", "--ignore-signal", "--list-signal-handling", "--version", "-i", "-v"], commandString: ["--split-string", "-S"], bareDash: true, assignments: true },
+    sudo: { valueFlags: ["--auth-type", "--chdir", "--chroot", "--close-from", "--command-timeout", "--group", "--host", "--other-user", "--prompt", "--role", "--type", "--user", "-C", "-D", "-R", "-T", "-U", "-a", "-g", "-h", "-p", "-r", "-t", "-u"], flags: ["--askpass", "--background", "--bell", "--help", "--list", "--login", "--non-interactive", "--preserve-env", "--preserve-groups", "--remove-timestamp", "--reset-timestamp", "--set-home", "--shell", "--stdin", "--validate", "--version", "-A", "-E", "-H", "-K", "-P", "-S", "-V", "-b", "-i", "-k", "-l", "-n", "-s", "-v"], commandString: [], assignments: true },
+    doas: { valueFlags: ["-C", "-a", "-u"], flags: ["-L", "-n", "-s"], commandString: [] },
+    pkexec: { valueFlags: ["--user"], flags: ["--disable-internal-agent", "--help", "--keep-cwd", "--version"], 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: [] },
+    time: { valueFlags: ["--format", "--output", "-f", "-o"], flags: ["--append", "--help", "--portability", "--quiet", "--verbose", "--version", "-a", "-p", "-q", "-v"], commandString: [] },
+    nice: { valueFlags: ["--adjustment", "-n"], flags: ["--help", "--version"], commandString: [] },
+    timeout: { valueFlags: ["--kill-after", "--signal", "-k", "-s"], flags: ["--foreground", "--help", "--preserve-status", "--verbose", "--version", "-v"], commandString: [], duration: true },
+    stdbuf: { valueFlags: ["--error", "--input", "--output", "-e", "-i", "-o"], flags: ["--help", "--version"], commandString: [] },
+    xargs: { valueFlags: ["--arg-file", "--delimiter", "--max-args", "--max-chars", "--max-procs", "--process-slot-var", "-E", "-I", "-L", "-P", "-a", "-d", "-n", "-s"], flags: ["--eof", "--exit", "--help", "--interactive", "--max-lines", "--no-run-if-empty", "--null", "--open-tty", "--replace", "--show-limits", "--verbose", "--version", "-0", "-o", "-p", "-r", "-t", "-x"], 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: [] },
+    ionice: { valueFlags: ["--class", "--classdata", "--pgid", "--pid", "--uid", "-P", "-c", "-n", "-p", "-u"], flags: ["--help", "--ignore", "--version", "-V", "-h", "-t"], commandString: [] },
+    setsid: { valueFlags: [], flags: ["--ctty", "--fork", "--help", "--version", "--wait", "-c", "-f", "-w"], commandString: [] },
+    taskset: { valueFlags: [], flags: ["--all-tasks", "--cpu-list", "--help", "--pid", "--version", "-a", "-c", "-p"], commandString: [], positional: /^(?:0x)?[\da-f]+$|^[\d,:-]+$/i },
+    chrt: { valueFlags: ["--pid", "--sched-deadline", "--sched-period", "--sched-runtime", "-D", "-P", "-T", "-p"], flags: ["--all-tasks", "--batch", "--deadline", "--fifo", "--help", "--idle", "--max", "--other", "--reset-on-fork", "--rr", "--verbose", "--version", "-R", "-a", "-b", "-d", "-f", "-i", "-m", "-o", "-r", "-v"], commandString: [], positional: /^\d+$/ },
+    strace: { valueFlags: ["--attach", "--columns", "--const-print-style", "--detach-on", "--env", "--expr", "--interruptible", "--output", "--string-limit", "--summary-columns", "--summary-sort-by", "--summary-syscall-overhead", "--trace", "--trace-path", "--user", "-E", "-I", "-O", "-P", "-S", "-U", "-X", "-a", "-b", "-e", "-o", "-p", "-s", "-u"], flags: ["--debug", "--follow-forks", "--help", "--summary", "--summary-only", "--version", "-C", "-D", "-F", "-T", "-V", "-Z", "-c", "-d", "-f", "-h", "-i", "-k", "-q", "-r", "-t", "-v", "-w", "-x", "-y", "-z"], commandString: [] },
+    ltrace: { valueFlags: ["--align", "--config", "--debug", "--indent", "--library", "--output", "--string-max", "--where", "-A", "-D", "-F", "-a", "-e", "-l", "-n", "-o", "-p", "-s", "-u", "-w", "-x"], flags: ["--demangle", "--help", "--version", "-C", "-L", "-S", "-T", "-V", "-c", "-f", "-i", "-r", "-t"], commandString: [] },
+    flock: { valueFlags: ["--conflict-exit-code", "--timeout", "--wait", "-E", "-w"], flags: ["--close", "--exclusive", "--help", "--nb", "--no-fork", "--nonblock", "--shared", "--unlock", "--verbose", "--version", "-F", "-n", "-o", "-s", "-u", "-x"], commandString: ["--command", "-c"], positional: /^/ },
+    script: { valueFlags: [], flags: [], commandString: ["--command", "-c"], viaShell: true },
+    unshare: { valueFlags: ["--boottime", "--map-group", "--map-user", "--monotonic", "--propagation", "--root", "--setgid", "--setgroups", "--setuid", "--wd", "-G", "-R", "-S", "-w"], flags: ["--cgroup", "--fork", "--help", "--ipc", "--keep-caps", "--kill-child", "--map-current-user", "--map-root-user", "--mount", "--mount-proc", "--net", "--pid", "--time", "--user", "--uts", "--version", "-C", "-T", "-U", "-c", "-f", "-i", "-m", "-n", "-p", "-r", "-u"], commandString: [] },
+    nsenter: { valueFlags: ["--setgid", "--setuid", "--target", "-G", "-S", "-t"], flags: ["--all", "--cgroup", "--help", "--ipc", "--mount", "--net", "--no-fork", "--pid", "--preserve-credentials", "--root", "--time", "--user", "--uts", "--version", "--wd", "-C", "-F", "-T", "-U", "-Z", "-a", "-i", "-m", "-n", "-p", "-u"], attached: ["-r", "-w"], commandString: [] },
     eval: { valueFlags: [], flags: [], commandString: [], viaShell: true },
     source: { valueFlags: [], flags: [], commandString: [], viaShell: true },
     ".": { valueFlags: [], flags: [], commandString: [], viaShell: true },
@@ -41,8 +42,27 @@ export const SHELL_WRAPPER_TABLE = {
     find: { valueFlags: [], flags: [], commandString: [], executes: ["-exec", "-execdir", "-ok", "-okdir"] },
     compgen: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
     complete: { valueFlags: [], flags: [], commandString: [], executes: ["-C", "-F"] },
+    busybox: { valueFlags: [], flags: [], commandString: [] },
+    su: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    runuser: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    chroot: { valueFlags: [], flags: [], commandString: [], positional: /^/ },
+    setpriv: { valueFlags: [], flags: [], commandString: [] },
+    numactl: { valueFlags: [], flags: [], commandString: [] },
+    prlimit: { valueFlags: [], flags: [], commandString: [] },
+    "systemd-run": { valueFlags: [], flags: [], commandString: [] },
+    valgrind: { valueFlags: [], flags: [], commandString: [] },
+    firejail: { valueFlags: [], flags: [], commandString: [] },
+    bwrap: { valueFlags: [], flags: [], commandString: [] },
+    ash: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    mksh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    yash: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    pdksh: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    parallel: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    alias: { valueFlags: [], flags: [], commandString: [], viaShell: true },
+    mapfile: { valueFlags: [], flags: [], commandString: [], executes: ["-C"] },
+    readarray: { valueFlags: [], flags: [], commandString: [], executes: ["-C"] },
 };
-export const VARIABLE_OPERAND_BUILTINS = new Set(["printf", "unset", "read", "mapfile", "readarray", "declare", "typeset", "local", "export", "readonly", "test", "[", "[["]);
+export const VARIABLE_OPERAND_BUILTINS = new Set(programRows().filter((row) => row.operands?.rest?.kind === "binds-name" || declaresOption(row, (spec) => spec.value?.kind === "binds-name")).map((row) => row.key));
 export function evaluatesOperand(run) {
     if (!VARIABLE_OPERAND_BUILTINS.has(run[0]?.text ?? ""))
         return false;

package/dist/core/synthetic-read-verdict.d.ts

@@ -50,6 +50,7 @@
  * visibility probe from a model's call.
  */
 import type { ToolCallRequest, ToolCallFace, ToolPolicy } from "./tool-policy.js";
+import type { CallTargetStamp } from "./effective-path-target.js";
 import { type SkillGrantLane } from "./skill-grant.js";
 import type { OrgGateVerdict, PersistedRuleAnswer } from "./hooks.js";
 /** The layers the judge consults, as named in its verdicts. */
@@ -81,6 +82,8 @@ export interface SyntheticReadLayers {
     orgRuleLane?: {
         adjudicate: (req: ToolCallRequest) => Promise<OrgGateVerdict>;
     };
+    /** The leg's target-reading stamp: the probe's request carries a reading of its target, as the live gate's does. */
+    stampCallTarget?: CallTargetStamp;
     /** The run's signal, for the engine's own layers. */
     signal?: AbortSignal;
 }

package/dist/core/synthetic-read-verdict.js

@@ -15,13 +15,15 @@ export function createSyntheticReadJudge(layers) {
     return async (call, face, budget) => {
         const deadlineAt = budget?.deadlineAt ?? Date.now() + ORG_ADJUDICATION_TIMEOUT_MS;
         const left = () => Math.max(0, Math.min(ORG_ADJUDICATION_TIMEOUT_MS, deadlineAt - Date.now()));
-        const req = {
+        const probe = {
             toolName: "Read",
             args: { file_path: call.file_path, ...(call.offset !== undefined ? { offset: call.offset } : {}), ...(call.limit !== undefined ? { limit: call.limit } : {}) },
             toolCallId: syntheticReadProbeId(face),
             ...(call.cwd !== undefined ? { cwd: call.cwd } : {}),
             ...(call.face !== undefined ? { face: call.face } : {}),
         };
+        const stamped = layers.stampCallTarget?.(probe, layers.signal);
+        const req = stamped !== undefined ? await stamped : probe;
         let unanswered;
         const cannot = (layer, cause, reason) => {
             unanswered ??= { verdict: "unanswerable", layer, cause, reason };