@sema-agent/core 7.17.7 → 7.19.0

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

@@ -1,5 +1,7 @@
-import { isAbsoluteForFamily, isAbsolutePathForm, isBlockedDevicePath, isShellRootedSpellingUnmapped, joinForFamily, nativeUncSpellingOf, normalizeAbsPathLexically, win32NamespaceScreen, pathFamilyOf, withinAnyRoot } from "./safety.js";
-export const NOT_AUTO_ALLOWED = "— not auto-allowed";
+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";
 export const BASH_READONLY_DEFAULT_ALLOW = [
     "ls", "cat", "head", "tail", "wc", "pwd", "echo", "whoami", "uname",
     "grep", "cut", "tr", "basename", "dirname", "stat", "du", "df", "which",
@@ -8,24 +10,6 @@ export const BASH_READONLY_DEFAULT_ALLOW = [
 ];
 export const BASH_CLASSIFY_DEFAULT_ALLOW = [...BASH_READONLY_DEFAULT_ALLOW, "find", "sed", "cd"];
 const SHELL_OPERATORS = /[;&|<>$()`\n\r\\]/;
-function quoteMask(s) {
-    const quoted = new Array(s.length).fill(false);
-    let open;
-    for (let i = 0; i < s.length; i++) {
-        const ch = s[i];
-        if (open === undefined && (ch === '"' || ch === "'")) {
-            open = ch;
-            quoted[i] = true;
-            continue;
-        }
-        if (open !== undefined) {
-            quoted[i] = true;
-            if (open === ch)
-                open = undefined;
-        }
-    }
-    return { quoted, balanced: open === undefined };
-}
 function hasBareShellOperator(s, quotedOperatorsAreText) {
     if (!quotedOperatorsAreText)
         return SHELL_OPERATORS.test(s);
@@ -108,48 +92,11 @@ export function splitShellCompoundSegments(source, options) {
         return { reject: "redirection, command/variable substitution, subshells, escapes, and line breaks are not allowed" };
     }
     const scanned = options?.trailingTerminator !== "keep" ? source.replace(/;\s*$/, "") : source;
-    const segments = [];
-    const connectors = ["start"];
-    const mask = quoteMask(scanned);
-    const quoted = (i) => mask.balanced && mask.quoted[i] === true;
-    let cur = "";
-    for (let i = 0; i < scanned.length; i++) {
-        const c = scanned[i];
-        if (quoted(i)) {
-            cur += c;
-        }
-        else if (c === "&") {
-            if (scanned[i + 1] === "&") {
-                segments.push(cur);
-                cur = "";
-                connectors.push("&&");
-                i++;
-            }
-            else
-                return { reject: "`&` backgrounding is not allowed — a backgrounded process outlives the command" };
-        }
-        else if (c === "|") {
-            if (scanned[i + 1] === "|") {
-                segments.push(cur);
-                cur = "";
-                connectors.push("||");
-                i++;
-            }
-            else {
-                segments.push(cur);
-                cur = "";
-                connectors.push("|");
-            }
-        }
-        else if (c === ";") {
-            segments.push(cur);
-            cur = "";
-            connectors.push(";");
-        }
-        else
-            cur += c;
-    }
-    segments.push(cur);
+    const lexed = lexShellText(scanned, { mode: "strict" });
+    if ("reject" in lexed)
+        return lexed;
+    const segments = lexed.segments.map((s) => s.text);
+    const connectors = lexed.segments.map((s) => s.connector);
     return { segments, pipeFed: connectors.map((k) => k === "|"), connectors };
 }
 const EXEMPT_REDIRECTION = /^(?:2>\/dev\/null|[12]?>&[12])$/;
@@ -181,24 +128,6 @@ function stripExemptRedirections(command) {
     flush();
     return out;
 }
-function foldQuoteRemovalToken(tok) {
-    if (!tok.includes('"') && !tok.includes("'"))
-        return tok;
-    let out = "";
-    let open;
-    for (const ch of tok) {
-        if (open === undefined && (ch === '"' || ch === "'")) {
-            open = ch;
-            continue;
-        }
-        if (open === ch) {
-            open = undefined;
-            continue;
-        }
-        out += ch;
-    }
-    return out;
-}
 const POLL_LOOP_CAUSE_MAX_PATHS = 3;
 export function formatOutOfRootReadApprovalOption(directory) {
     const trimmed = directory.replace(/[/\\]+$/, "");
@@ -206,6 +135,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",
@@ -245,36 +217,25 @@ function spellingsOf(absolute) {
 function reheadSegment(toks, head, from = 0) {
     return { folded: [head, ...toks.folded.slice(from + 1)], raw: [head, ...toks.raw.slice(from + 1)] };
 }
-const SHELL_CONTROL_PREFIXES = new Set(["!", "if", "then", "elif", "else", "while", "until", "do", "time"]);
-const SHELL_BLOCK_WORDS = new Set(["for", "select", "case", "esac", "fi", "done", "function", "coproc", "[[", "]]", "in"]);
-function isBareControlWord(toks, i, words) {
-    const word = toks.folded[i];
-    return word !== undefined && toks.raw[i] === word && words.has(word);
-}
-function tokensMoveBase(toks, allow) {
-    let from = 0;
-    while (from < toks.folded.length && isBareControlWord(toks, from, SHELL_CONTROL_PREFIXES)) {
-        const controlWord = programBasename(toks.folded[from] ?? "");
-        from++;
-        for (let span = launcherOptionSpan(controlWord, toks.folded, from); span > 0; span = launcherOptionSpan(controlWord, toks.folded, from))
-            from += span;
-    }
-    const head = toks.folded[from];
-    if (head === undefined)
+function tokensMoveBase(toks) {
+    const pos = readProgramPosition(toks);
+    if (pos.written === undefined)
         return false;
-    if (toks.raw[from] !== head)
-        return true;
-    if (head.startsWith("-") && head !== "-")
+    const written = toks.folded[pos.written];
+    if (toks.raw[pos.written] !== written)
         return true;
-    if (head === "cd")
-        return true;
-    if (!COMMAND_LAUNCHERS.has(head))
+    if (pos.assignments.length > 0)
         return false;
-    const unwrapped = unwrapLauncher(toks.folded.slice(from), allow);
-    return unwrapped.kind === "refused" || (unwrapped.kind === "reader" && unwrapped.head === "cd");
+    if (pos.launchers.length === 0) {
+        if (written.startsWith("-") && written !== "-")
+            return true;
+        return written === "cd";
+    }
+    if (!COMMAND_LAUNCHERS.has(written))
+        return false;
+    return pos.refusal !== undefined || pos.program?.basename === "cd";
 }
 const SHELL_REENTRY_PROGRAM_RE = /^(?:(?:ba|z|da|k|fi|a|mk|ya|pdk|c|tc)?sh|eval|source|\.|parallel)$/;
-const ARGV_REENTRY_PROGRAM_RE = /^xargs$/;
 export function refusedCommandMayRead(command, allow, boundary) {
     return !refusedCommandExempt(command, allow, boundary, 0);
 }
@@ -282,249 +243,49 @@ const STDIN_ONLY_READER_FLAGS = new Map([
     ["cat", /^-[AbeEnstTuv]+$/],
     ["wc", /^-[clmwL]+$/],
 ]);
-const SUBSTITUTION_PLACEHOLDER = "\u0000subst";
-function withoutHeredocBodies(text) {
-    const lines = text.split("\n");
-    const out = [];
-    const expandedBodies = [];
-    let terminator;
-    let expanded = false;
-    let body = [];
-    for (const line of lines) {
-        if (terminator !== undefined) {
-            if (line.trim() === terminator) {
-                if (expanded)
-                    expandedBodies.push(body.join("\n"));
-                terminator = undefined;
-                body = [];
-            }
-            else
-                body.push(line);
-            continue;
-        }
-        out.push(line);
-        const header = heredocHeaderOf(line);
-        if (header === null)
-            return undefined;
-        if (header !== undefined) {
-            terminator = header.word;
-            expanded = !header.quoted;
-        }
-    }
-    return terminator === undefined ? { outer: out.join("\n"), expandedBodies } : undefined;
-}
-function heredocHeaderOf(line) {
-    let inSingle = false;
-    let inDouble = false;
-    for (let i = 0; i < line.length; i++) {
-        const ch = line[i];
-        if (ch === "\\" && !inSingle) {
-            i++;
-            continue;
-        }
-        if (ch === "'" && !inDouble) {
-            inSingle = !inSingle;
-            continue;
-        }
-        if (ch === '"' && !inSingle) {
-            inDouble = !inDouble;
-            continue;
-        }
-        if (inSingle || inDouble)
-            continue;
-        if (ch === "#")
-            return undefined;
-        if (ch === "<" && line[i + 1] === "<") {
-            if (line[i + 2] === "<") {
-                i += 2;
-                continue;
-            }
-            const m = /^<<-?\s*([^\s;|&<>()]+)/.exec(line.slice(i));
-            if (m === null)
-                return null;
-            const word = m[1];
-            if (/[$`]/.test(word))
-                return null;
-            const delimiter = word.replace(/\\(.)/g, "$1").replace(/["']/g, "");
-            if (delimiter === "")
-                return null;
-            return { word: delimiter, quoted: /["'\\]/.test(word) };
-        }
-    }
-    return undefined;
-}
-function splitSubstitutions(text, quotesAreLiteral = false) {
-    let outer = "";
-    const bodies = [];
-    let i = 0;
-    let inSingle = false;
-    let inDouble = false;
-    while (i < text.length) {
-        const ch = text[i];
-        if (ch === "\\" && !inSingle) {
-            outer += text.slice(i, i + 2);
-            i += 2;
-            continue;
-        }
-        if (ch === "'" && !inDouble && !quotesAreLiteral) {
-            inSingle = !inSingle;
-            outer += ch;
-            i++;
-            continue;
-        }
-        if (ch === '"' && !inSingle && !quotesAreLiteral) {
-            inDouble = !inDouble;
-            outer += ch;
-            i++;
-            continue;
-        }
-        if (inSingle) {
-            outer += ch;
-            i++;
-            continue;
-        }
-        if (ch === "`") {
-            const close = text.indexOf("`", i + 1);
-            if (close < 0)
-                return undefined;
-            bodies.push(text.slice(i + 1, close));
-            outer += SUBSTITUTION_PLACEHOLDER;
-            i = close + 1;
-            continue;
-        }
-        if ((ch === "$" || ch === "<" || ch === ">") && text[i + 1] === "(") {
-            let depth = 0;
-            let j = i + 1;
-            let quoted;
-            for (; j < text.length; j++) {
-                const c = text[j];
-                if (quoted !== undefined) {
-                    if (c === "\\" && quoted === '"')
-                        j++;
-                    else if (c === quoted)
-                        quoted = undefined;
-                    continue;
-                }
-                if (c === "'" || c === '"') {
-                    quoted = c;
-                    continue;
-                }
-                if (c === "(")
-                    depth++;
-                else if (c === ")") {
-                    depth--;
-                    if (depth === 0)
-                        break;
-                }
-            }
-            if (j >= text.length)
-                return undefined;
-            bodies.push(text.slice(i + 2, j));
-            outer += SUBSTITUTION_PLACEHOLDER;
-            i = j + 1;
-            continue;
-        }
-        outer += ch;
-        i++;
-    }
-    if (inSingle)
-        return undefined;
-    return { outer, bodies };
+function whitelistSegment(segment) {
+    const tokens = [...segment.tokens];
+    for (let k = 0; k + 2 < tokens.length; k++) {
+        const [a, b, c] = [tokens[k], tokens[k + 1], tokens[k + 2]];
+        if (a.kind === "word" && b.kind === "group" && b.op === "(" && c.kind === "group" && c.op === ")" && /^[A-Za-z_][A-Za-z0-9_]*$/.test(a.folded))
+            tokens.splice(k, 3);
+    }
+    const words = tokens.filter((t) => t.kind === "word" && !(t.raw === t.folded && (t.folded === "{" || t.folded === "}")));
+    let from = 0;
+    while (from < words.length && SHELL_BLOCK_WORDS.has(words[from].folded))
+        from++;
+    return {
+        words: { folded: words.slice(from).map((w) => w.folded), raw: words.slice(from).map((w) => w.raw) },
+        redirects: tokens.filter((t) => t.kind === "redirect"),
+    };
 }
 function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside = false) {
     if (depth > 4)
         return false;
-    const stripped = withoutHeredocBodies(command);
-    if (stripped === undefined)
-        return false;
-    if (!whitelistReadsTheSameWords(command, stripped.outer))
-        return false;
-    const split = splitSubstitutions(stripped.outer);
-    if (split === undefined)
+    const lexed = lexShellText(command, { mode: "lenient" });
+    if ("reject" in lexed)
         return false;
-    const bodies = [...split.bodies];
-    for (const expandedBody of stripped.expandedBodies) {
-        const inner = splitSubstitutions(expandedBody, true);
-        if (inner === undefined)
-            return false;
-        bodies.push(...inner.bodies);
-    }
-    const fold = (w) => w.replace(/\\(.)/g, "$1").replace(/["']/g, "");
-    const programOf = (w) => {
-        const inner = fold(w);
-        return inner.includes("/") ? inner.slice(inner.lastIndexOf("/") + 1) : inner;
-    };
-    const segments = split.outer.split(/\n|;|&&|\|\||\||(?<![>&\d])&(?![>&])/).map((segment) => {
-        const toks = [];
-        for (const word of segment.trim().split(/\s+/)) {
-            let rest = word;
-            while (rest !== "") {
-                const m = /^(\d*(?:<<<|<<|<|>>|>)(?:&\d*)?|&>>?)(.*)$/.exec(rest);
-                if (m !== null) {
-                    toks.push(m[1].replace(/^\d+/, ""));
-                    rest = m[2];
-                    continue;
-                }
-                const at = rest.search(/\d*(?:<<<|<<|<|>>|>)|&>/);
-                if (at <= 0) {
-                    toks.push(rest);
-                    break;
-                }
-                toks.push(rest.slice(0, at));
-                rest = rest.slice(at);
-            }
-        }
-        const commentAt = toks.findIndex((t) => t.startsWith("#"));
-        return (commentAt >= 0 ? toks.slice(0, commentAt) : toks)
-            .map((t) => (/^[A-Za-z_][A-Za-z0-9_]*\(\)$/.test(t) ? "{" : t.replace(/^[({]+|[)}]+$/g, "")))
-            .filter((t) => t !== "");
-    });
-    const headIndex = (toks) => {
-        const folded = toks.map(fold);
-        let i = 0;
-        while (i < toks.length) {
-            const w = folded[i];
-            if (ASSIGNMENT_WORD.test(w) || SHELL_CONTROL_PREFIXES.has(w) || SHELL_BLOCK_WORDS.has(w) || /^[{}]$/.test(w)) {
-                i++;
-                const controlWord = programBasename(w);
-                for (let span = launcherOptionSpan(controlWord, folded, i); span > 0; span = launcherOptionSpan(controlWord, folded, i))
-                    i += span;
-                continue;
-            }
-            if (/^(?:<<<|<<|<|>>?|&>>?)$/.test(w)) {
-                i += 2;
-                continue;
-            }
-            if (/^(?:>>?|<)&\d*$/.test(w)) {
-                i++;
+    const bodies = [...lexed.substitutions];
+    const segments = [];
+    for (const segment of lexed.segments) {
+        for (const t of segment.tokens) {
+            if (t.kind !== "heredoc" || t.quoted)
                 continue;
-            }
-            break;
+            const inner = substitutionsInHeredocBody(t.body);
+            if (inner === undefined)
+                return false;
+            for (const body of inner)
+                bodies.push(body);
         }
-        return i;
-    };
-    const runProgramOf = (toks, i) => {
-        let head = programOf(toks[i] ?? "");
-        let guard = 0;
-        while (COMMAND_LAUNCHERS.has(head) && guard++ < 8) {
-            let j = i + 1;
-            while (j < toks.length && (ASSIGNMENT_WORD.test(fold(toks[j])) || /^\d+[smhd]?$/.test(fold(toks[j]))))
-                j++;
-            const next = toks[j];
-            if (next === undefined || fold(next).startsWith("-"))
-                return undefined;
-            i = j;
-            head = programOf(next);
-        }
-        return head;
-    };
+        segments.push(whitelistSegment(segment));
+    }
     const baseMoved = baseMovedOutside ||
-        segments.some((toks) => {
-            const i = headIndex(toks);
-            if (i >= toks.length)
-                return false;
-            const head = runProgramOf(toks, i);
-            return head === undefined || head === "cd" || UNMODELLED_BASE_MOVERS.has(head);
+        segments.some(({ words }) => {
+            const pos = readProgramPosition(words);
+            if (pos.refusal !== undefined)
+                return true;
+            const runs = pos.program?.basename;
+            return runs === "cd" || (runs !== undefined && UNMODELLED_BASE_MOVERS.has(runs));
         });
     for (const body of bodies) {
         const walked = classifyCompoundReadonlyDetailed(body, allow, boundary);
@@ -535,33 +296,22 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
         if (!refusedCommandExempt(body, allow, boundary, depth + 1, baseMoved))
             return false;
     }
-    const stdinFileJudgedInside = (raw) => {
-        if (raw === undefined || raw === "" || raw.includes(SUBSTITUTION_PLACEHOLDER) || UNREADABLE_WHITELIST_WORD.test(raw))
+    const stdinFileJudgedInside = (word) => {
+        if (word === undefined || word === "" || word.includes(SUBSTITUTION_PLACEHOLDER) || UNREADABLE_WHITELIST_WORD.test(word))
             return false;
         if (boundary === undefined || baseMoved)
             return false;
-        const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], fold(raw), boundary.homeDir);
+        const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], word, boundary.homeDir);
         if (resolved === undefined || boundary.denyMatch?.(resolved) != null)
             return false;
         return withinAnyRoot(boundary.roots, resolved);
     };
-    const unlistedSegmentJudgedInside = (toks, from) => {
+    const unlistedSegmentJudgedInside = (words, from) => {
         if (boundary === undefined)
             return true;
         let endOfOptions = false;
-        for (let j = from; j < toks.length; j++) {
-            const t = toks[j];
-            if (t === "<<<" || t === "<<" || t === "<") {
-                j++;
-                continue;
-            }
-            if (/^(?:>>?|&>>?)$/.test(t)) {
-                j++;
-                continue;
-            }
-            if (/^(?:>>?|<)&\d*$/.test(t))
-                continue;
-            const word = fold(t);
+        for (let j = from; j < words.folded.length; j++) {
+            const word = words.folded[j];
             if (j > from && !endOfOptions && word === "--") {
                 endOfOptions = true;
                 continue;
@@ -580,47 +330,49 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
         }
         return true;
     };
-    for (const toks of segments) {
-        for (let j = 0; j < toks.length; j++)
-            if (toks[j] === "<" && !stdinFileJudgedInside(toks[j + 1]))
+    for (const { words, redirects } of segments) {
+        for (const r of redirects)
+            if (r.op === "<" && !stdinFileJudgedInside(r.target?.folded))
                 return false;
-        let i = headIndex(toks);
-        if (i >= toks.length)
-            continue;
-        const headWord = fold(toks[i]);
-        if (headWord.includes(SUBSTITUTION_PLACEHOLDER) || /[$`]/.test(headWord))
+        const pos = readProgramPosition(words);
+        if (pos.refusal !== undefined)
             return false;
-        if (headWord.startsWith("-") && headWord !== "-")
+        for (const k of words.folded.keys()) {
+            const word = words.folded[k];
+            if (ASSIGNMENT_WORD.test(word) && /\$\(|`/.test(word) && (pos.assignments.includes(k) || pos.launchers.some((l) => l.index < k)))
+                return false;
+        }
+        const program = pos.program;
+        const listed = (name) => allow.has(name) || name === "cd";
+        if (program === undefined) {
+            if (pos.launchers.length === 0)
+                continue;
+            if (argvReentryUnjudged(pos, NO_PATH_OPERAND_COMMANDS))
+                return false;
+            if (!unlistedSegmentJudgedInside(words, pos.launchers[0].index))
+                return false;
+            continue;
+        }
+        if (program.name.includes(SUBSTITUTION_PLACEHOLDER) || /[$`]/.test(program.name))
             return false;
-        let head = programOf(headWord);
-        const launcherUnwrap = COMMAND_LAUNCHERS.has(head) ? unwrapLauncher(toks.slice(i).map(fold), allow) : undefined;
-        if (launcherUnwrap?.kind === "refused")
+        if (argumentAsProgramRefusal(program.basename, program.basename, words.folded.slice(program.index + 1)) !== undefined)
             return false;
-        const runs = launcherUnwrap === undefined ? { head, index: 0 } : { head: launcherUnwrap.head, index: launcherUnwrap.index };
-        if (runs.head !== undefined && runs.index !== undefined &&
-            argumentAsProgramRefusal(runs.head, runs.head, toks.slice(i + runs.index + 1).map(fold)) !== undefined)
+        if (SHELL_REENTRY_PROGRAM_RE.test(program.basename))
             return false;
-        if (launcherUnwrap !== undefined) {
-            const wrapped = runProgramOf(toks, i);
-            if (wrapped === undefined || /[$`]/.test(wrapped) || SHELL_REENTRY_PROGRAM_RE.test(wrapped))
+        if (pos.launchers.length > 0) {
+            if (argvReentryUnjudged(pos, NO_PATH_OPERAND_COMMANDS))
                 return false;
-            const unwrapped = launcherUnwrap;
-            if (argvReentryUnjudged(unwrapped))
-                return false;
-            if (unwrapped.kind === "unlisted") {
-                if (!unlistedSegmentJudgedInside(toks, i))
+            if (!listed(program.basename)) {
+                if (!unlistedSegmentJudgedInside(words, pos.launchers[0].index))
                     return false;
                 continue;
             }
-            head = unwrapped.head;
-            i += unwrapped.index;
         }
-        if (SHELL_REENTRY_PROGRAM_RE.test(head))
-            return false;
+        const head = program.basename;
         if (head === "cd" || UNMODELLED_BASE_MOVERS.has(head))
             continue;
         if (!allow.has(head)) {
-            if (!unlistedSegmentJudgedInside(toks, i))
+            if (!unlistedSegmentJudgedInside(words, program.index))
                 return false;
             continue;
         }
@@ -629,110 +381,18 @@ function refusedCommandExempt(command, allow, boundary, depth, baseMovedOutside
         const flags = STDIN_ONLY_READER_FLAGS.get(head);
         if (flags === undefined)
             return false;
-        for (let j = i + 1; j < toks.length; j++) {
-            const t = toks[j];
-            if (t === "<<<" || t === "<<" || t === "<") {
-                j++;
-                continue;
-            }
-            if (/^(?:>>?|&>>?)$/.test(t)) {
-                j++;
-                continue;
-            }
-            if (/^(?:>>?|<)&\d*$/.test(t))
-                continue;
-            if (flags.test(fold(t)))
-                continue;
-            return false;
+        for (let j = program.index + 1; j < words.folded.length; j++) {
+            if (!flags.test(words.folded[j]))
+                return false;
         }
     }
     return true;
 }
-function unwrapLauncher(folded, allow) {
-    let argvFromStdin = ARGV_REENTRY_PROGRAM_RE.test(programBasename(folded[0] ?? ""));
-    let lastReentry = argvFromStdin ? 0 : -1;
-    for (let i = 1; i < folded.length; i++) {
-        const t = folded[i];
-        if (ASSIGNMENT_WORD.test(t) || /^\d+[smhd]?$/.test(t))
-            continue;
-        const wordBasename = programBasename(t);
-        if (ARGV_REENTRY_PROGRAM_RE.test(wordBasename)) {
-            argvFromStdin = true;
-            lastReentry = i;
-            continue;
-        }
-        if (COMMAND_LAUNCHERS.has(wordBasename))
-            continue;
-        if (t.startsWith("-"))
-            return { kind: "refused", reason: `"${folded[0]}" is given an option before the program it runs — which program runs is not readable without the launcher's option table ${NOT_AUTO_ALLOWED}` };
-        const head = wordBasename;
-        if (SHELL_CONTROL_PREFIXES.has(head) || SHELL_BLOCK_WORDS.has(head))
-            return { kind: "refused", reason: `"${folded[0]}" is given shell control syntax ("${head}") where the program it runs would be ${NOT_AUTO_ALLOWED}` };
-        return allow.has(head) || head === "cd" ? { kind: "reader", index: i, head, argvFromStdin } : { kind: "unlisted", head, index: i, argvFromStdin };
-    }
-    return { kind: "unlisted", argvFromStdin, runsDefaultProgram: lastReentry === folded.length - 1 };
-}
-const LAUNCHER_OPTION_GRAMMAR = new Map([
-    ["time", {
-            plain: new Set(["-p", "-a", "-v", "-q", "--portability", "--append", "--verbose", "--quiet", "--help", "--version"]),
-            valued: new Set(["-f", "-o", "--format", "--output"]),
-        }],
-]);
-function launcherOptionSpan(launcher, folded, i) {
-    const row = launcher === undefined ? undefined : LAUNCHER_OPTION_GRAMMAR.get(launcher);
-    const tok = folded[i];
-    if (row === undefined || tok === undefined)
-        return 0;
-    if (row.plain.has(tok))
-        return 1;
-    return row.valued.has(tok) && folded[i + 1] !== undefined ? 2 : 0;
-}
-const ARGV_REENTRY_DEFAULT_PROGRAM = "echo";
-function argvReentryUnjudged(unwrapped) {
-    if (!unwrapped.argvFromStdin)
-        return false;
-    const runs = unwrapped.head ?? (unwrapped.runsDefaultProgram === true ? ARGV_REENTRY_DEFAULT_PROGRAM : undefined);
-    return runs === undefined || !NO_PATH_OPERAND_COMMANDS.has(runs);
-}
 function tokenizeSegment(segment) {
-    const raw = splitWordsQuoteAware(segment);
-    return { folded: raw.map((r) => { const f = foldQuoteRemovalToken(r); return tildeIsLiteral(r) ? literalTildeSpelling(f) : f; }), raw };
-}
-function literalTildeSpelling(word) {
-    return word.startsWith("~") ? `./${word}` : word;
-}
-function tildeIsLiteral(raw) {
-    if (!raw.startsWith("~"))
-        return true;
-    for (let i = 1; i < raw.length; i++) {
-        const ch = raw[i];
-        if (ch === '"' || ch === "'")
-            return true;
-        if (ch === "/")
-            return false;
-    }
-    return false;
-}
-function splitWordsQuoteAware(segment) {
-    const s = segment.trim();
-    const mask = quoteMask(s);
-    if (!mask.balanced)
-        return s.split(/\s+/).filter((t) => t.length > 0);
-    const out = [];
-    let cur = "";
-    for (let i = 0; i < s.length; i++) {
-        const ch = s[i];
-        if (!mask.quoted[i] && /\s/.test(ch)) {
-            if (cur.length > 0)
-                out.push(cur);
-            cur = "";
-            continue;
-        }
-        cur += ch;
-    }
-    if (cur.length > 0)
-        out.push(cur);
-    return out;
+    const lexed = lexShellText(segment, { mode: "strict", connectors: "text" });
+    if ("reject" in lexed)
+        return { folded: [], raw: [] };
+    return wordsOf(lexed.segments[0]);
 }
 function hasUnquotedExpansionMetachar(rawToken) {
     let open;
@@ -1304,20 +964,6 @@ const INTERPRETER_INLINE_PROGRAMS = new Map([
 function interpreterKey(name) {
     return name.replace(/\d+(?:\.\d+)*$/, "");
 }
-function withoutRedirectionWords(args) {
-    const out = [];
-    for (let i = 0; i < args.length; i++) {
-        const t = args[i];
-        if (/^(?:<<<|<<|<|>>?|&>>?)$/.test(t)) {
-            i++;
-            continue;
-        }
-        if (/^(?:>>?|<)&\d*$/.test(t))
-            continue;
-        out.push(t);
-    }
-    return out;
-}
 function inlineProgramClause(model, args) {
     let endOfOptions = false;
     let banner = false;
@@ -1441,7 +1087,7 @@ function argumentAsProgramRefusal(written, name, args) {
     const interpreter = INTERPRETER_INLINE_PROGRAMS.get(interpreterKey(name));
     if (interpreter === undefined)
         return undefined;
-    const clause = inlineProgramClause(interpreter, withoutRedirectionWords(args));
+    const clause = inlineProgramClause(interpreter, args);
     return clause === undefined ? undefined : unjudgedProgramTextRefusal(written, clause);
 }
 function guardedVerbFormReason(name, toks, raw) {
@@ -1834,13 +1480,8 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     for (let si = 0; si < segments.length; si++) {
         const toks = tokenizeSegment(segments[si]);
         const folded = toks.folded;
-        let from = 0;
-        while (from < folded.length && isBareControlWord(toks, from, SHELL_CONTROL_PREFIXES)) {
-            const controlWord = programBasename(folded[from] ?? "");
-            from++;
-            for (let span = launcherOptionSpan(controlWord, folded, from); span > 0; span = launcherOptionSpan(controlWord, folded, from))
-                from += span;
-        }
+        const pos = readProgramPosition(toks);
+        const from = pos.written ?? folded.length;
         const written = folded[from];
         if (written === undefined)
             return { reason: "empty command" };
@@ -1858,15 +1499,11 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
         const name = pathPrefixed ? parsed.name.slice(parsed.name.lastIndexOf("/") + 1) : parsed.name;
         if (pathPrefixed)
             nameRefusal ??= "the command must be a bare name resolved via PATH (no path prefix)";
-        if (name.startsWith("-") && name !== "-") {
-            return { reason: `"${folded[0]}" is given an option where the program it runs would be — which program runs is not readable without its option table ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
-        }
-        const launcherUnwrap = COMMAND_LAUNCHERS.has(name) ? unwrapLauncher(folded.slice(from), allow) : undefined;
-        if (launcherUnwrap?.kind === "refused")
-            return { reason: launcherUnwrap.reason, refusedWhole: true };
-        const runs = launcherUnwrap === undefined ? { head: name, index: 0 } : { head: launcherUnwrap.head, index: launcherUnwrap.index };
-        if (runs?.head !== undefined && runs.index !== undefined) {
-            const familyRefusal = argumentAsProgramRefusal(runs.head, runs.head, folded.slice(from + runs.index + 1));
+        if (pos.refusal !== undefined)
+            return { reason: programPositionRefusalSentence(pos.refusal), refusedWhole: true };
+        const program = pos.program;
+        if (program !== undefined) {
+            const familyRefusal = argumentAsProgramRefusal(program.basename, program.basename, folded.slice(program.index + 1));
             if (familyRefusal !== undefined)
                 return { reason: familyRefusal, refusedWhole: true };
         }
@@ -1880,20 +1517,18 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
         nameRefusal ??= `command "${parsed.name}" is not in the read-only allowlist`;
         if (SHELL_REENTRY_PROGRAM_RE.test(name))
             return { reason: unjudgedProgramTextRefusal(parsed.name, "runs its argument as shell text"), refusedWhole: true };
-        if (COMMAND_LAUNCHERS.has(name)) {
-            const unwrapped = launcherUnwrap ?? unwrapLauncher(folded.slice(from), allow);
-            if (unwrapped.kind === "refused")
-                return { reason: unwrapped.reason, refusedWhole: true };
-            if (unwrapped.kind === "unlisted" && unwrapped.head !== undefined && SHELL_REENTRY_PROGRAM_RE.test(unwrapped.head)) {
-                return { reason: `"${written}" runs "${unwrapped.head}", which runs its argument as shell text this walk does not judge ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
+        if (pos.launchers.length > 0) {
+            const listed = program !== undefined && (allow.has(program.basename) || program.basename === "cd");
+            if (program !== undefined && !listed && SHELL_REENTRY_PROGRAM_RE.test(program.basename)) {
+                return { reason: `"${written}" runs "${program.basename}", which runs its argument as shell text this walk does not judge ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
             }
-            if (argvReentryUnjudged(unwrapped)) {
+            if (argvReentryUnjudged(pos, NO_PATH_OPERAND_COMMANDS)) {
                 return { reason: `"${written}" takes the operands of the program it runs from its standard input, which this walk does not judge ${NOT_AUTO_ALLOWED}`, refusedWhole: true };
             }
-            if (unwrapped.kind === "unlisted")
+            if (!listed || program === undefined)
                 unlistedSegments.add(si);
             else
-                reheaded.set(si, { from: from + unwrapped.index, head: unwrapped.head });
+                reheaded.set(si, { from: program.index, head: program.basename });
             continue;
         }
         unlistedSegments.add(si);
@@ -2040,10 +1675,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)
@@ -2054,7 +1689,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 = [];
@@ -2212,10 +1847,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,
@@ -2225,44 +1870,21 @@ export function classifySimpleCommandReadBoundary(command, boundary) {
     const toks = tokenizeSegment(command);
     if (toks.folded.length === 0)
         return {};
-    const head = programBasename(toks.folded[0]);
-    let past = 0;
-    for (let span = launcherOptionSpan(head, toks.folded, past + 1); span > 0; span = launcherOptionSpan(head, toks.folded, past + 1))
-        past += span;
-    const chain = past === 0 ? toks.folded : [toks.folded[0], ...toks.folded.slice(past + 1)];
-    const runs = COMMAND_LAUNCHERS.has(head) ? unwrapLauncher(chain, new Set()) : { kind: "reader", head, index: 0 };
-    if (runs.kind === "refused")
-        return { reason: runs.reason, refusedWhole: true };
-    if (runs.head !== undefined && runs.index !== undefined) {
-        const familyRefusal = argumentAsProgramRefusal(runs.head, runs.head, toks.folded.slice(runs.index + past + 1));
+    const pos = readProgramPosition(toks);
+    if (pos.refusal !== undefined)
+        return { reason: programPositionRefusalSentence(pos.refusal), refusedWhole: true };
+    if (pos.program !== undefined) {
+        const familyRefusal = argumentAsProgramRefusal(pos.program.basename, pos.program.basename, toks.folded.slice(pos.program.index + 1));
         if (familyRefusal !== undefined)
             return { reason: familyRefusal, refusedWhole: true };
     }
-    return evaluateReadBoundary([toks], boundary);
+    return evaluateReadBoundary([toks], boundary, true);
 }
 const NOT_GATED = { gated: false, paths: [] };
-const ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
 const UNREADABLE_WHITELIST_WORD = /[$`()*?[\]{}~]/;
-function whitelistReadsTheSameWords(command, outsideHeredocBodies) {
-    if (/\\\r?\n/.test(command))
-        return false;
-    if (/\\[<>&|;()]/.test(outsideHeredocBodies))
-        return false;
-    return !(outsideHeredocBodies.includes("#") && /["']/.test(outsideHeredocBodies));
-}
 const UNMODELLED_BASE_MOVERS = new Set(["pushd", "popd"]);
-const COMMAND_LAUNCHERS = new Set([
-    "env", "command", "builtin", "exec", "noglob", "xargs", "busybox",
-    "sudo", "doas", "pkexec", "su", "runuser", "chroot", "setpriv",
-    "nohup", "nice", "ionice", "chrt", "taskset", "stdbuf", "timeout", "time", "watch",
-    "setsid", "flock", "unshare", "nsenter", "script", "numactl", "prlimit", "systemd-run",
-    "strace", "ltrace", "valgrind", "firejail", "bwrap",
-]);
 export const COMMAND_LAUNCHERS_FOR_TEST = COMMAND_LAUNCHERS;
 const LAUNCHER_SCAN_HEAD = "cat";
-function programBasename(word) {
-    return word.includes("/") ? (word.split("/").pop() ?? word) : word;
-}
 export function classifyOutOfRootReadGate(command, allow, boundary) {
     const containmentOnly = {
         roots: boundary.roots,
@@ -2316,7 +1938,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);
@@ -2417,7 +2039,7 @@ export function classifyBoundedReadonlyPollLoopDetailed(command, allow, boundary
     if (readSegments.length === 0) {
         return { reason: "the loop body has no read command — a sleep-only loop observes nothing and is not auto-allowed" };
     }
-    const bodyHasCd = readSegments.some((seg) => tokensMoveBase(tokenizeSegment(seg), allow));
+    const bodyHasCd = readSegments.some((seg) => tokensMoveBase(tokenizeSegment(seg)));
     const modelled = bodyHasCd ? Array.from({ length: beats }, () => readSegments.join("; ")).join("; ") : readSegments.join("; ");
     const verdict = classifyCompoundReadonlyDetailed(modelled, allow, boundary, { iterated: bodyHasCd });
     if (verdict.reason !== undefined)