@sema-agent/core 7.18.0 → 7.20.0

package/dist/tools/fs/bash-readonly-classifier.d.ts

@@ -35,7 +35,7 @@ export { NOT_AUTO_ALLOWED } from "./bash-program-position.js";
 export type { ShellSegmentConnector } from "./bash-lexer.js";
 export declare const BASH_READONLY_DEFAULT_ALLOW: readonly string[];
 /**
- * The CLASSIFY face's default allow set: the shared list PLUS the verbs that are
+ * The verbs the CLASSIFY face admits ON TOP of the shared list ({@link bashClassifyDefaultAllow}) —
  * admissible only where the compound classifier's per-verb judgment runs, and NOT on the shared list's
  * other consumer faces:
  *  · `find` — read-only only when no CC `aCy` dangerous predicate token is present (guard arm);
@@ -54,7 +54,18 @@ export declare const BASH_READONLY_DEFAULT_ALLOW: readonly string[];
  * poll-loop face inherits the guard arms for free: its body vetting delegates to the same compound
  * classifier.
  */
-export declare const BASH_CLASSIFY_DEFAULT_ALLOW: readonly string[];
+export declare const BASH_CLASSIFY_EXTRA_ALLOW: readonly string[];
+/** A verb only the classify face admits. */
+export type BashClassifyExtraVerb = (typeof BASH_CLASSIFY_EXTRA_ALLOW)[number];
+/**
+ * @contract shell.classify_allow.one_union_point — the classify face's default allow set is the union of
+ * two SPELLED-OUT tables ({@link BASH_READONLY_DEFAULT_ALLOW} ∪ {@link BASH_CLASSIFY_EXTRA_ALLOW}) and
+ * this function is its only assembly point; no call site composes its own. Both halves stay arrays of
+ * string literals so a static reader can enumerate them: a vocabulary derived in place
+ * (`[...TABLE, "extra"]`) is invisible to the release's wire-change manifest, so a verb added to or
+ * dropped from this security-relevant set would move nothing a downstream reader could see.
+ */
+export declare function bashClassifyDefaultAllow(): readonly string[];
 /**
  * G2 — options for {@link parseLeadingCommandName}. Omitting them keeps the parser byte-identical to
  * what every existing caller (the `bash_readonly` declaration face, the coarse command-name policy, the
@@ -413,6 +424,21 @@ export interface CompoundReadonlyVerdict {
      * path is unchanged.
      */
     recursiveReadPaths?: readonly string[];
+    /**
+     * The ONE directory whose addition to the declared roots would make every objection this walk raised go
+     * away. It rides the SAME arm as the containment sentence and is dropped wherever that sentence is (a
+     * SHAPE refusal takes both — `tail -f <out-of-root>` stays refused after any grant), and on that arm the
+     * claim is MEASURED, not argued: the walk runs again with the proposed root in place and the directory is
+     * offered only if that walk has no objection left. `..`-traversing spellings are excluded on their own
+     * account ({@link outOfRootSpellings}): that is a disagreement between the folded text and the kernel,
+     * which no replay of the text can settle. VALUE: the deepest directory PROPERLY
+     * containing every {@link outOfRootPaths} entry, folded lexically — zero I/O, so a path that is itself a
+     * directory contributes its PARENT (`ls /etc/ssl` ⇒ `/etc`) where the reference implementation narrows
+     * with a stat; refused rather than widened when the result would be a family root or would contain the
+     * declared home or a declared {@link BashReadonlyRootBoundary.roots} entry. Meaning and spelling
+     * contract: {@link import("../../core/tool-spec.js").ReadRootGrantCandidate}.
+     */
+    outOfRootGrantCandidate?: string;
 }
 /**
  * The single minting point for the out-of-root-read approval option text, so a gate rendering
@@ -425,6 +451,18 @@ export interface CompoundReadonlyVerdict {
  * uses the host's native separator.
  */
 export declare function formatOutOfRootReadApprovalOption(directory: string): string;
+/**
+ * The deepest directory containing both, or `undefined` when they share none (two path families).
+ *
+ * LINEAR, and that is the point: both paths are already folded, so the answer is their common prefix cut
+ * at a separator. Climbing one directory at a time re-folds the whole remaining path each step — the same
+ * answer at quadratic cost, measured at 4.9 s of synchronous work for one 32 KB command naming a
+ * 16 000-segment operand, on a walk that runs BEFORE the gate arms its probe deadline. The family-aware
+ * comparator keeps the last word: a prefix it cannot confirm contains both paths yields no candidate.
+ * Exported for its unit tests — the family confirmation is reachable from a command only through shapes
+ * the compound grammar refuses first, so a command-level pin cannot tell a live guard from an absent one.
+ */
+export declare function deepestCommonDir(a: string, b: string): string | undefined;
 /** Resolve one operand against the boundary's base, WITHOUT touching the filesystem. Returns undefined
  *  when the token cannot be resolved statically — the fail-closed direction, reported as its own
  *  demotion rather than silently treated as in-root.

package/dist/tools/fs/bash-readonly-classifier.js

@@ -1,4 +1,4 @@
-import { isAbsoluteForFamily, isAbsolutePathForm, isBlockedDevicePath, isShellRootedSpellingUnmapped, joinForFamily, nativeUncSpellingOf, normalizeAbsPathLexically, win32NamespaceScreen, pathFamilyOf, withinAnyRoot } from "./safety.js";
+import { hasWin32AliasedComponent, isAbsoluteForFamily, isAbsolutePathForm, isBlockedDevicePath, isShellRootedSpellingUnmapped, joinForFamily, nativeUncSpellingOf, normalizeAbsPathLexically, win32NamespaceScreen, pathFamilyOf, withinAnyRoot } from "./safety.js";
 import { lexShellText, literalTildeSpelling, quoteMask, substitutionsInHeredocBody, SUBSTITUTION_PLACEHOLDER, wordsOf, } from "./bash-lexer.js";
 import { ASSIGNMENT_WORD, COMMAND_LAUNCHERS, NOT_AUTO_ALLOWED, SHELL_BLOCK_WORDS, argvReentryUnjudged, isBareControlWord, programBasename, programPositionRefusalSentence, readProgramPosition, } from "./bash-program-position.js";
 export { NOT_AUTO_ALLOWED } from "./bash-program-position.js";
@@ -8,7 +8,10 @@ export const BASH_READONLY_DEFAULT_ALLOW = [
     "cal", "uptime", "id", "groups", "nproc", "locale", "free", "realpath", "readlink",
     "true", "false", "seq", "expr", "type", "sleep", "diff", "cmp", "comm",
 ];
-export const BASH_CLASSIFY_DEFAULT_ALLOW = [...BASH_READONLY_DEFAULT_ALLOW, "find", "sed", "cd"];
+export const BASH_CLASSIFY_EXTRA_ALLOW = ["find", "sed", "cd"];
+export function bashClassifyDefaultAllow() {
+    return [...BASH_READONLY_DEFAULT_ALLOW, ...BASH_CLASSIFY_EXTRA_ALLOW];
+}
 const SHELL_OPERATORS = /[;&|<>$()`\n\r\\]/;
 function hasBareShellOperator(s, quotedOperatorsAreText) {
     if (!quotedOperatorsAreText)
@@ -135,6 +138,49 @@ export function formatOutOfRootReadApprovalOption(directory) {
     const leaf = cut >= 0 ? trimmed.slice(cut + 1) : trimmed;
     return `Yes, allow reading from ${leaf || directory}/ from this project`;
 }
+function parentDirLexically(p) {
+    return normalizeAbsPathLexically(`${p}/..`);
+}
+export function deepestCommonDir(a, b) {
+    if (a === b)
+        return a;
+    const shorter = Math.min(a.length, b.length);
+    let end = 0;
+    let i = 0;
+    while (i < shorter && a[i] === b[i]) {
+        if (a[i] === "/" || a[i] === "\\")
+            end = i;
+        i++;
+    }
+    if (i === shorter && (a[shorter] === "/" || a[shorter] === "\\" || b[shorter] === "/" || b[shorter] === "\\"))
+        end = shorter;
+    const cut = a.slice(0, end);
+    const candidate = cut.includes("/") || cut.includes("\\") ? cut : a.slice(0, end + 1);
+    if (candidate.length === 0 || !withinAnyRoot([candidate], a) || !withinAnyRoot([candidate], b))
+        return undefined;
+    return candidate;
+}
+function outOfRootGrantCandidateOf(paths, boundary) {
+    if (paths.length === 0)
+        return undefined;
+    if (paths.some(hasWin32AliasedComponent))
+        return undefined;
+    let candidate = parentDirLexically(paths[0]);
+    for (const path of paths.slice(1)) {
+        if (candidate === undefined)
+            return undefined;
+        candidate = deepestCommonDir(candidate, parentDirLexically(path));
+    }
+    if (candidate === undefined)
+        return undefined;
+    if (parentDirLexically(candidate) === candidate)
+        return undefined;
+    if (boundary.homeDir !== undefined && withinAnyRoot([candidate], boundary.homeDir))
+        return undefined;
+    if (boundary.roots.some((root) => withinAnyRoot([candidate], root)))
+        return undefined;
+    return candidate;
+}
 const NO_PATH_OPERAND_COMMANDS = new Set([
     "pwd", "echo", "whoami", "uname", "which", "tr", "basename", "dirname",
     "cal", "uptime", "id", "groups", "nproc", "locale", "free", "true", "false", "seq", "expr", "type", "sleep",
@@ -403,18 +449,6 @@ function isGrepPatternFlagToken(tok) {
     }
     return /^-[A-Za-z0-9]*[ef]/.test(tok);
 }
-function isGrepPatternPayloadLongOption(tok) {
-    if (!tok.includes("="))
-        return false;
-    const name = longOptionNameOf(tok);
-    return name !== undefined && isLongOptionAbbrevOf(name, "regexp");
-}
-function isCutDelimiterPayloadLongOption(tok) {
-    if (!tok.includes("="))
-        return false;
-    const name = longOptionNameOf(tok);
-    return name !== undefined && (isLongOptionAbbrevOf(name, "delimiter") || isLongOptionAbbrevOf(name, "output-delimiter"));
-}
 function isGrepClusterFileStdin(tok) {
     if (tok.startsWith("--") || !/^-[A-Za-z0-9]/.test(tok))
         return false;
@@ -429,6 +463,283 @@ function isGrepClusterFileStdin(tok) {
     }
     return false;
 }
+function valueNamesAFile(kind) {
+    return kind === "path" || kind === "indirect" || kind === "form" || kind === "header" || kind === "url";
+}
+function widestValueKind(kinds) {
+    if (kinds.has("indirect"))
+        return "indirect";
+    if (kinds.has("path"))
+        return "path";
+    if (kinds.has("form"))
+        return "form";
+    if (kinds.has("header"))
+        return "header";
+    if (kinds.has("url"))
+        return "url";
+    return [...kinds][0];
+}
+const VERB_OPTION_SLOTS = {
+    head: {
+        shortValue: { c: "count", n: "count" },
+        shortPlain: "qvz",
+        longValue: { bytes: "count", lines: "count" },
+        longOptionalValue: {},
+        longPlain: ["help", "quiet", "silent", "verbose", "version", "zero-terminated"],
+    },
+    tail: {
+        shortValue: { b: "count", c: "count", n: "count", s: "count" },
+        shortPlain: "fFqvz",
+        longValue: { bytes: "count", lines: "count", "max-unchanged-stats": "count", pid: "count", "sleep-interval": "count" },
+        longOptionalValue: { follow: "label" },
+        longPlain: ["help", "quiet", "retry", "silent", "verbose", "version", "zero-terminated"],
+    },
+    cut: {
+        shortValue: { b: "count", c: "count", d: "delimiter", f: "count" },
+        shortPlain: "nsz",
+        longValue: { bytes: "count", characters: "count", delimiter: "delimiter", fields: "count", "output-delimiter": "delimiter" },
+        longOptionalValue: {},
+        longPlain: ["complement", "help", "only-delimited", "version", "zero-terminated"],
+    },
+    grep: {
+        shortValue: { A: "count", B: "count", C: "count", D: "label", d: "label", e: "pattern", f: "path", m: "count" },
+        shortPlain: "0123456789abcEFGhHiIlLnoPqrRsUvVwxyzZ",
+        longValue: {
+            "after-context": "count",
+            "before-context": "count",
+            "binary-files": "label",
+            devices: "label",
+            directories: "label",
+            exclude: "name-pattern",
+            "exclude-dir": "name-pattern",
+            "exclude-from": "path",
+            file: "path",
+            "group-separator": "label",
+            include: "name-pattern",
+            label: "label",
+            "max-count": "count",
+            regexp: "pattern",
+        },
+        longOptionalValue: { color: "label", colour: "label", context: "count" },
+        longPlain: [
+            "basic-regexp", "byte-offset", "count", "dereference-recursive", "extended-regexp",
+            "files-with-matches", "files-without-match", "fixed-strings", "help", "ignore-case", "initial-tab",
+            "invert-match", "line-buffered", "line-number", "line-regexp", "no-filename", "no-group-separator",
+            "no-messages", "null", "null-data", "only-matching", "perl-regexp", "quiet", "recursive", "silent",
+            "text", "version", "with-filename", "word-regexp",
+        ],
+    },
+    diff: {
+        shortValue: { C: "count", D: "label", F: "pattern", I: "pattern", L: "label", S: "path", U: "count", W: "count", X: "path", x: "name-pattern" },
+        shortPlain: "abBcdeEHilnNpqrstTuvwyZ",
+        longValue: {
+            exclude: "name-pattern",
+            "exclude-from": "path",
+            "from-file": "path",
+            "horizon-lines": "count",
+            ifdef: "label",
+            "ignore-matching-lines": "pattern",
+            label: "label",
+            "show-function-line": "pattern",
+            "starting-file": "path",
+            tabsize: "count",
+            "to-file": "path",
+            width: "count",
+        },
+        longOptionalValue: { color: "label", context: "count", unified: "count" },
+        longPlain: [
+            "brief", "ed", "expand-tabs", "help", "ignore-all-space", "ignore-blank-lines", "ignore-case",
+            "ignore-space-change", "ignore-tab-expansion", "ignore-trailing-space", "initial-tab", "minimal",
+            "new-file", "normal", "paginate", "recursive", "report-identical-files", "rcs", "show-c-function",
+            "side-by-side", "speed-large-files", "suppress-blank-empty", "text", "version",
+        ],
+    },
+    cmp: {
+        shortValue: { i: "count", n: "count" },
+        shortPlain: "blsv",
+        longValue: { bytes: "count", "ignore-initial": "count" },
+        longOptionalValue: {},
+        longPlain: ["help", "print-bytes", "quiet", "silent", "verbose", "version"],
+    },
+    sed: {
+        shortValue: { e: "script", f: "path" },
+        shortPlain: "nrEszu",
+        longValue: { expression: "script", file: "path", "line-length": "count" },
+        longOptionalValue: { "in-place": "label" },
+        longPlain: [
+            "debug", "follow-symlinks", "help", "null-data", "posix", "quiet", "regexp-extended", "sandbox",
+            "separate", "silent", "unbuffered", "version", "zero-terminated",
+        ],
+    },
+    date: {
+        shortValue: { d: "count", f: "path", r: "path", s: "count" },
+        shortPlain: "uR",
+        longValue: { date: "count", file: "path", reference: "path", "rfc-3339": "count", set: "count" },
+        longOptionalValue: { "iso-8601": "label" },
+        longPlain: ["debug", "help", "rfc-822", "rfc-email", "universal", "utc", "version"],
+    },
+    tar: {
+        shortValue: { b: "count", C: "path", f: "path", T: "path", X: "path" },
+        shortPlain: "acdhjJkmOpPrStuvwWxzZ",
+        longValue: {
+            "blocking-factor": "count",
+            directory: "path",
+            exclude: "name-pattern",
+            "exclude-from": "path",
+            file: "path",
+            "files-from": "path",
+            "strip-components": "count",
+        },
+        longOptionalValue: {},
+        longPlain: [
+            "absolute-names", "append", "create", "dereference", "extract", "get", "help", "interactive",
+            "keep-old-files", "list", "preserve-permissions", "sparse", "to-stdout", "touch", "update",
+            "verbose", "verify", "version",
+        ],
+    },
+    curl: {
+        shortValue: {
+            A: "label", b: "indirect", C: "count", c: "path", D: "path", d: "indirect", E: "path", e: "label",
+            F: "form", H: "header", K: "path", m: "count", o: "path", P: "label", Q: "label", r: "count",
+            T: "path", t: "label", U: "label", u: "label", w: "indirect", X: "label", x: "label", Y: "count",
+            y: "count", z: "path",
+        },
+        shortPlain: "#0123456aBfgGhiIjJklLMnNOpqRsSvVZ",
+        longValue: {
+            cacert: "path",
+            capath: "path",
+            cert: "path",
+            config: "path",
+            "connect-timeout": "count",
+            cookie: "indirect",
+            "cookie-jar": "path",
+            data: "indirect",
+            "data-ascii": "indirect",
+            "data-binary": "indirect",
+            "data-raw": "label",
+            "data-urlencode": "form",
+            "dump-header": "path",
+            form: "form",
+            "form-string": "label",
+            header: "header",
+            key: "path",
+            "max-time": "count",
+            "netrc-file": "path",
+            output: "path",
+            proxy: "label",
+            range: "count",
+            referer: "label",
+            request: "label",
+            resolve: "label",
+            trace: "path",
+            "time-cond": "path",
+            "trace-ascii": "path",
+            "upload-file": "path",
+            url: "url",
+            user: "label",
+            "user-agent": "label",
+            "write-out": "indirect",
+        },
+        longOptionalValue: {},
+        longPlain: [
+            "append", "compressed", "disable", "fail", "get", "globoff", "head", "help", "include", "insecure",
+            "junk-session-cookies", "list-only", "location", "manual", "netrc", "next", "no-buffer", "parallel",
+            "proxytunnel", "remote-header-name", "remote-name", "remote-time", "show-error", "silent",
+            "use-ascii", "verbose", "version",
+        ],
+    },
+};
+function readVerbOptionSlot(name, tok) {
+    const row = VERB_OPTION_SLOTS[name];
+    if (row === undefined)
+        return undefined;
+    if (!tok.startsWith("-") || tok === "-" || tok === "--")
+        return { form: "unexplained" };
+    if (tok.startsWith("--")) {
+        const long = longOptionNameOf(tok);
+        if (long === undefined)
+            return { form: "unexplained" };
+        const eq = tok.indexOf("=");
+        const attached = eq >= 0 ? tok.slice(eq + 1) : undefined;
+        const withValue = (kind) => attached !== undefined ? { form: "attached", value: attached, kind } : { form: "separated", kind };
+        const exact = row.longValue[long];
+        if (exact !== undefined)
+            return withValue(exact);
+        const exactOptional = row.longOptionalValue[long];
+        if (exactOptional !== undefined)
+            return attached !== undefined ? { form: "attached", value: attached, kind: exactOptional } : { form: "no-value" };
+        if (row.longPlain.includes(long))
+            return attached === undefined ? { form: "no-value" } : { form: "unexplained" };
+        const valueNames = [
+            ...Object.keys(row.longValue),
+            ...(attached !== undefined ? Object.keys(row.longOptionalValue) : []),
+        ].filter((full) => isLongOptionAbbrevOf(long, full));
+        const plainNames = [
+            ...row.longPlain,
+            ...(attached === undefined ? Object.keys(row.longOptionalValue) : []),
+        ].filter((full) => isLongOptionAbbrevOf(long, full));
+        if (valueNames.length === 0)
+            return plainNames.length > 0 && attached === undefined ? { form: "no-value" } : { form: "unexplained" };
+        const kinds = new Set(valueNames.map((full) => (row.longValue[full] ?? row.longOptionalValue[full])));
+        if (attached !== undefined)
+            return { form: "attached", value: attached, kind: widestValueKind(kinds) };
+        if (plainNames.length > 0 || kinds.size !== 1)
+            return { form: "unexplained" };
+        return withValue([...kinds][0]);
+    }
+    for (let i = 1; i < tok.length; i++) {
+        const ch = tok[i];
+        const kind = row.shortValue[ch];
+        if (kind !== undefined) {
+            const rest = tok.slice(i + 1);
+            return rest !== "" ? { form: "attached", value: rest, kind } : { form: "separated", kind };
+        }
+        if (!row.shortPlain.includes(ch))
+            return { form: "unexplained" };
+    }
+    return { form: "no-value" };
+}
+function localFileUrlPath(value) {
+    const m = /^file:(?:\/\/[^/?#]*)?(\/[^?#]*)/i.exec(value.trim());
+    if (m === null)
+        return undefined;
+    const raw = m[1];
+    try {
+        return decodeURIComponent(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+function formSpecFileNames(value) {
+    const out = [];
+    const after = (s) => {
+        const at = s.search(/[@<]/);
+        if (at !== -1 && at < s.length - 1)
+            out.push(s.slice(at + 1));
+    };
+    after(value);
+    for (const part of value.split(/[;,]/))
+        after(part);
+    return [...new Set(out)];
+}
+function slotValueCandidates(value, kind) {
+    if (!valueNamesAFile(kind))
+        return [];
+    if (kind === "url") {
+        const local = localFileUrlPath(value);
+        return local !== undefined ? [local] : [];
+    }
+    if (kind === "form")
+        return formSpecFileNames(value).map(literalTildeSpelling);
+    const named = value.startsWith("@") && value.length > 1 ? literalTildeSpelling(value.slice(1)) : undefined;
+    if (kind === "header")
+        return named !== undefined ? [value, named] : [];
+    const out = [value];
+    if (kind === "indirect" && named !== undefined)
+        out.push(named);
+    return out;
+}
 const SEPARATED_VALUE_OPTIONS = {
     head: { short: "cn", long: ["bytes", "lines"] },
     tail: { short: "cns", long: ["bytes", "lines", "sleep-interval", "pid", "max-unchanged-stats"] },
@@ -1205,17 +1516,6 @@ function isGrepFileStdinLongOption(tok) {
     return name !== undefined && isLongOptionAbbrevOf(name, "file");
 }
 const CLUSTER_OPTION_CHAR = /[A-Za-z0-9]/;
-function grepClusterValueOwner(tok) {
-    if (!tok.startsWith("-") || tok.startsWith("--") || !CLUSTER_OPTION_CHAR.test(tok[1] ?? ""))
-        return undefined;
-    for (const ch of tok.slice(1)) {
-        if (ch === "e" || ch === "f")
-            return ch;
-        if (!CLUSTER_OPTION_CHAR.test(ch))
-            return undefined;
-    }
-    return undefined;
-}
 function attachedOptionPayloads(tok) {
     const literal = literalTildeSpelling;
     const out = [];
@@ -1239,6 +1539,7 @@ function attachedOptionPayloads(tok) {
 }
 function collectSegmentBoundaryFindings(tokens, boundary) {
     const name = tokens.folded[0];
+    const slotVerb = tokens.slotVerb ?? name;
     if (NO_PATH_OPERAND_COMMANDS.has(name))
         return [];
     const args = tokens.folded.slice(1);
@@ -1285,6 +1586,8 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
         const eoo = args.indexOf("--");
         const patternSuppliedByFlag = name === "grep" && (eoo === -1 ? args : args.slice(0, eoo)).some(isGrepPatternFlagToken);
         let sawOperand = false;
+        const argvOperandsStartAt = tokens.slotVerb !== undefined ? 1 : 0;
+        let sawArgvOperand = false;
         let endOfOptions = false;
         for (let k = 0; k < args.length; k++) {
             const t = args[k];
@@ -1295,15 +1598,35 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
                     endOfOptions = true;
                     continue;
                 }
-                if (name === "cut" && (t === "-d" || t === "--delimiter" || t === "--output-delimiter")) {
-                    k++;
-                    continue;
-                }
-                if (name === "cut" && (/^-d./.test(t) || isCutDelimiterPayloadLongOption(t)))
-                    continue;
-                if (name === "grep" && (grepClusterValueOwner(t) === "e" || isGrepPatternPayloadLongOption(t)))
-                    continue;
                 if (t.startsWith("-") && t !== "-") {
+                    const slot = readVerbOptionSlot(slotVerb, t);
+                    if (sawArgvOperand) {
+                        judgeOperand(t, argGlobs(k));
+                        if (slot !== undefined && slot.form === "separated") {
+                            const ahead = args[k + 1];
+                            if (ahead !== undefined && !expandingArgs.has(k + 1)) {
+                                for (const c of slotValueCandidates(ahead, slot.kind))
+                                    judgeOperand(c, argGlobs(k + 1));
+                            }
+                        }
+                    }
+                    if (slot !== undefined && slot.form !== "unexplained" && !(slot.form === "separated" && sawArgvOperand)) {
+                        if (slot.form === "attached") {
+                            for (const c of slotValueCandidates(literalTildeSpelling(slot.value), slot.kind))
+                                judgeOperand(c, argGlobs(k));
+                        }
+                        else if (slot.form === "separated") {
+                            const value = args[++k];
+                            if (value !== undefined && !expandingArgs.has(k)) {
+                                const named = slotValueCandidates(value, slot.kind);
+                                for (const c of named)
+                                    judgeOperand(c, argGlobs(k));
+                                if (named.length > 0)
+                                    positionalOperands.push(value);
+                            }
+                        }
+                        continue;
+                    }
                     for (const payload of attachedOptionPayloads(t))
                         judgeOperand(payload, argGlobs(k));
                     continue;
@@ -1311,6 +1634,8 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
             }
             const isGrepPatternSlot = name === "grep" && !patternSuppliedByFlag && !sawOperand;
             sawOperand = true;
+            if (k >= argvOperandsStartAt)
+                sawArgvOperand = true;
             if (t === "-") {
                 if (isGrepPatternSlot)
                     continue;
@@ -1541,7 +1866,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
             const unlisted = tokenizeSegment(segments[si]);
             if (unlisted.folded.length === 0)
                 continue;
-            foldedSegments.push({ folded: [LAUNCHER_SCAN_HEAD, ...unlisted.folded], raw: [LAUNCHER_SCAN_HEAD, ...unlisted.raw] });
+            foldedSegments.push({ folded: [LAUNCHER_SCAN_HEAD, ...unlisted.folded], raw: [LAUNCHER_SCAN_HEAD, ...unlisted.raw], slotVerb: programBasename(unlisted.folded[0]) });
             pushReach();
             continue;
         }
@@ -1632,10 +1957,10 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
             shapeRefusal ??= `multiple directory changes in one command require approval for clarity ${NOT_AUTO_ALLOWED}`;
     }
     if (boundary !== undefined) {
-        const walk = evaluateReadBoundary(foldedSegments, boundary, foldedReach);
+        const walk = evaluateReadBoundary(foldedSegments, boundary, true, foldedReach);
         if (shapeRefusal === undefined)
             return walk;
-        const { reason: _walkSentence, ...structure } = walk;
+        const { reason: _walkSentence, outOfRootGrantCandidate: _walkGrantCandidate, ...structure } = walk;
         return { ...structure, reason: shapeRefusal };
     }
     if (shapeRefusal !== undefined)
@@ -1646,7 +1971,7 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     return {};
 }
 const BASE_CANDIDATE_MAX = 256;
-function evaluateReadBoundary(foldedSegments, boundary, reach) {
+function evaluateReadBoundary(foldedSegments, boundary, mintGrantCandidate, reach) {
     const seen = { outside: new Set(), inside: new Set(), undecided: new Set(), recursive: new Set(), unresolved: new Set(), checkedSpelled: new Set(), undecidedSpelled: new Set(), outsideSpelled: new Set() };
     const outside = [];
     const inside = [];
@@ -1691,7 +2016,7 @@ function evaluateReadBoundary(foldedSegments, boundary, reach) {
         if (si > 0 && reach?.[si]?.andJoined !== true)
             andRunStart = reach?.[si]?.orBroken === true ? si + 1 : si;
         const reachable = candidates.filter((c) => c.skippedCd < andRunStart);
-        const row = findingsRowFor(JSON.stringify([toks.folded, toks.raw]));
+        const row = findingsRowFor(JSON.stringify([toks.folded, toks.raw, toks.slotVerb]));
         for (const { base: currentBase } of reachable) {
             for (const finding of findingsFor(row, toks, currentBase)) {
                 if (finding.kind === "unresolvable") {
@@ -1804,10 +2129,20 @@ function evaluateReadBoundary(foldedSegments, boundary, reach) {
         return { ...checkedField, ...undecidedField };
     const paths = outside.map((o) => `"${o.path}"`).join(", ");
     const allowed = boundary.roots.length > 0 ? boundary.roots.join(", ") : "(none)";
+    const grantCandidate = (() => {
+        if (!mintGrantCandidate || outOfRootSpellings.length > 0)
+            return undefined;
+        const proposed = outOfRootGrantCandidateOf(outside.map((o) => o.path), boundary);
+        if (proposed === undefined)
+            return undefined;
+        const replay = evaluateReadBoundary(foldedSegments, { ...boundary, roots: [...boundary.roots, proposed] }, false, reach);
+        return replay.reason === undefined && (replay.undecidedPaths ?? []).length === 0 ? proposed : undefined;
+    })();
     return {
         reason: `"${outside[0].command}" reads ${paths}, outside the allowed directories for this session: ${allowed} ${NOT_AUTO_ALLOWED}`,
         outOfRootRead: true,
         outOfRootPaths: outside.map((o) => o.path),
+        ...(grantCandidate !== undefined ? { outOfRootGrantCandidate: grantCandidate } : {}),
         ...outsideField,
         ...checkedField,
         ...undecidedField,
@@ -1825,7 +2160,7 @@ export function classifySimpleCommandReadBoundary(command, boundary) {
         if (familyRefusal !== undefined)
             return { reason: familyRefusal, refusedWhole: true };
     }
-    return evaluateReadBoundary([toks], boundary);
+    return evaluateReadBoundary([toks], boundary, true);
 }
 const NOT_GATED = { gated: false, paths: [] };
 const UNREADABLE_WHITELIST_WORD = /[$`()*?[\]{}~]/;
@@ -1876,7 +2211,7 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
             if (UNMODELLED_BASE_MOVERS.has(name))
                 baseMoved = true;
             if (!allow.has(name) && name !== "cd") {
-                pushReader({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)] });
+                pushReader({ folded: [LAUNCHER_SCAN_HEAD, ...toks.folded.slice(i)], raw: [LAUNCHER_SCAN_HEAD, ...toks.raw.slice(i)], slotVerb: name });
                 continue;
             }
             pushReader(i === 0 && name === written ? toks : { folded: [name, ...toks.folded.slice(i + 1)], raw: [toks.raw[i] ?? name, ...toks.raw.slice(i + 1)] });
@@ -1885,7 +2220,7 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
             return NOT_GATED;
         if (baseMoved)
             return { gated: true, paths: [] };
-        const verdict = evaluateReadBoundary(readers, containmentOnly, readerReach);
+        const verdict = evaluateReadBoundary(readers, containmentOnly, false, readerReach);
         return verdict.outOfRootRead === true ? { gated: true, paths: verdict.outOfRootPaths ?? [] } : NOT_GATED;
     };
     const direct = judge(command);

package/dist/tools/fs/fs-bash.d.ts

@@ -100,7 +100,7 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  * add a mandate to an ask, never originate one). The poll-loop face's structured verdict
  * ({@link classifyBoundedReadonlyPollLoopDetailed}) is read the same three ways as the compound face's.
  *
- * The reader set is the engine's classify set ({@link BASH_CLASSIFY_DEFAULT_ALLOW}) — here it is NOT an
+ * The reader set is the engine's classify set ({@link bashClassifyDefaultAllow}) — here it is NOT an
  * auto-allow list but the set of programs whose operands the faces read; a wider set means more reads are
  * judged, never that more runs are vouched.
  *