@sema-agent/core 7.16.0 → 7.17.1

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

@@ -1,4 +1,4 @@
-import { isAbsolutePathForm, isBlockedDevicePath, normalizeAbsPathLexically, withinAnyRoot } from "./safety.js";
+import { isAbsoluteForFamily, isAbsolutePathForm, isBlockedDevicePath, isShellRootedSpellingUnmapped, joinForFamily, nativeUncSpellingOf, normalizeAbsPathLexically, win32NamespaceScreen, pathFamilyOf, withinAnyRoot } from "./safety.js";
 export const NOT_AUTO_ALLOWED = "— not auto-allowed";
 export const BASH_READONLY_DEFAULT_ALLOW = [
     "ls", "cat", "head", "tail", "wc", "pwd", "echo", "whoami", "uname",
@@ -213,7 +213,7 @@ const NO_PATH_OPERAND_COMMANDS = new Set([
 function isPathShapedToken(tok) {
     return tok.includes("/") || tok.startsWith("~") || tok === "." || tok === "..";
 }
-function resolveOperandLexically(base, operand, homeDir) {
+export function resolveOperandLexically(base, operand, homeDir) {
     let raw = operand;
     if (raw === "~" || raw.startsWith("~/")) {
         if (homeDir === undefined || !isAbsolutePathForm(homeDir))
@@ -223,15 +223,107 @@ function resolveOperandLexically(base, operand, homeDir) {
     else if (raw.startsWith("~")) {
         return undefined;
     }
-    if (isAbsolutePathForm(raw))
-        return normalizeAbsPathLexically(raw);
-    if (base === undefined || !isAbsolutePathForm(base))
+    const family = base === undefined ? undefined : pathFamilyOf({ root: base });
+    if (!win32NamespaceScreen(raw, family).ok)
         return undefined;
-    return normalizeAbsPathLexically(`${base.replace(/[/\\]+$/, "")}/${raw}`);
+    if (isAbsoluteForFamily(family, raw))
+        return normalizeAbsPathLexically(nativeUncSpellingOf(family, raw));
+    if (base === undefined || family === undefined || !isAbsoluteForFamily(family, base))
+        return undefined;
+    if (isShellRootedSpellingUnmapped(family, raw))
+        return undefined;
+    return normalizeAbsPathLexically(joinForFamily(family, base, raw));
+}
+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))
+        from++;
+    const head = toks.folded[from];
+    if (head === undefined)
+        return false;
+    if (toks.raw[from] !== head)
+        return true;
+    if (head === "cd")
+        return true;
+    if (!COMMAND_LAUNCHERS.has(head))
+        return false;
+    const unwrapped = unwrapLauncher(toks.folded.slice(from), allow);
+    return unwrapped.kind === "refused" || (unwrapped.kind === "reader" && unwrapped.head === "cd");
+}
+const SHELL_REENTRY_PROGRAM_RE = /^(?:(?:ba|z|da|k|fi)?sh|eval|source|\.)$/;
+export function refusedCommandMayRead(command, allow) {
+    for (const m of command.matchAll(/(?<![<>&\d])<(?![<&])\s*(\S*)/g)) {
+        const target = (m[1] ?? "").replace(/^["']+|["']+$/g, "");
+        if (target === "" || /^[$`(~]/.test(target))
+            return true;
+    }
+    const fold = (w) => w.replace(/\\(.)/g, "$1").replace(/["']/g, "");
+    const programOf = (w) => {
+        const inner = fold(w).replace(/^[$`(]+|[)`]+$/g, "");
+        return inner.includes("/") ? inner.slice(inner.lastIndexOf("/") + 1) : inner;
+    };
+    for (const word of command.split(/[\s<>|;&()]+/)) {
+        const base = programOf(word);
+        if (base === "")
+            continue;
+        if ((allow.has(base) && !NO_PATH_OPERAND_COMMANDS.has(base)) || SHELL_REENTRY_PROGRAM_RE.test(base))
+            return true;
+    }
+    for (const segment of command.split(/\n|;|&&|\|\||\||(?<![>&\d])&(?![>&])/)) {
+        for (const raw of segment.trim().split(/\s+/)) {
+            const word = fold(raw);
+            if (word === "")
+                continue;
+            if (/^[A-Za-z_][A-Za-z0-9_]*=/.test(word) || SHELL_CONTROL_PREFIXES.has(word) || SHELL_BLOCK_WORDS.has(word) || word === "{" || word === "}" || COMMAND_LAUNCHERS.has(programOf(word)) || word.startsWith("-"))
+                continue;
+            if (/^[$`(]/.test(word))
+                return true;
+            break;
+        }
+    }
+    return false;
+}
+function unwrapLauncher(folded, allow) {
+    for (let i = 1; i < folded.length; i++) {
+        const t = folded[i];
+        if (ASSIGNMENT_WORD.test(t) || /^\d+[smhd]?$/.test(t) || COMMAND_LAUNCHERS.has(t))
+            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 = t.includes("/") ? t.slice(t.lastIndexOf("/") + 1) : t;
+        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 } : { kind: "unlisted" };
+    }
+    return { kind: "unlisted" };
 }
 function tokenizeSegment(segment) {
     const raw = splitWordsQuoteAware(segment);
-    return { folded: raw.map(foldQuoteRemovalToken), raw };
+    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();
@@ -575,11 +667,12 @@ function grepClusterValueOwner(tok) {
     return undefined;
 }
 function attachedOptionPayloads(tok) {
+    const literal = literalTildeSpelling;
     const out = [];
     if (tok.startsWith("--")) {
         const eq = tok.indexOf("=");
         if (eq > 0 && eq + 1 < tok.length)
-            out.push(tok.slice(eq + 1));
+            out.push(literal(tok.slice(eq + 1)));
         return out;
     }
     for (let k = 1; k <= tok.length; k++) {
@@ -587,7 +680,7 @@ function attachedOptionPayloads(tok) {
             break;
         const payload = tok.slice(k);
         if (payload.length > 0)
-            out.push(payload);
+            out.push(literal(payload));
     }
     return out;
 }
@@ -600,31 +693,35 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
     const candidates = [];
     const bareWordOperands = [];
     const positionalOperands = [];
+    let stdinOperand = false;
     const argGlobs = (k) => {
         const raw = tokens.raw[k + 1];
         return raw !== undefined && hasUnquotedGlobMetachar(raw);
     };
-    for (const rawArg of tokens.raw.slice(1)) {
+    const expandingArgs = new Set();
+    tokens.raw.slice(1).forEach((rawArg, k) => {
         if (!hasUnquotedExpansionMetachar(rawArg))
-            continue;
-        return [
-            {
-                kind: "unresolvable",
-                reason: `"${name}" is given the argument "${rawArg}", which the shell expands (brace/variable/command expansion) before the command runs — the path it would actually read cannot be resolved statically, so it is not auto-allowed`,
-            },
-        ];
-    }
+            return;
+        expandingArgs.add(k);
+        findings.push({
+            kind: "unresolvable",
+            operand: rawArg,
+            reason: `"${name}" is given the argument "${rawArg}", which the shell expands (brace/variable/command expansion) before the command runs — the path it would actually read cannot be resolved statically, so it is not auto-allowed`,
+        });
+    });
+    if (name === "cd" && expandingArgs.size > 0)
+        return findings;
     if (name === "cd") {
         const targetIdx = args.findIndex((t) => !t.startsWith("-") || t === "-");
         const target = targetIdx === -1 ? undefined : args[targetIdx];
         if (target !== undefined && argGlobs(targetIdx)) {
-            return [{ kind: "unresolvable", reason: `\`cd\` is given the pattern "${target}", which the shell expands to a directory this check cannot know ${NOT_AUTO_ALLOWED}` }];
+            return [{ kind: "unresolvable", operand: target, reason: `\`cd\` is given the pattern "${target}", which the shell expands to a directory this check cannot know ${NOT_AUTO_ALLOWED}` }];
         }
         if (target === undefined) {
-            return [{ kind: "unresolvable", reason: '`cd` with no argument targets the home directory, which cannot be checked against the allowed directories ' + NOT_AUTO_ALLOWED }];
+            return [{ kind: "unresolvable", operand: "cd", reason: '`cd` with no argument targets the home directory, which cannot be checked against the allowed directories ' + NOT_AUTO_ALLOWED }];
         }
         if (target === "-") {
-            return [{ kind: "unresolvable", reason: '`cd -` targets the previous working directory, which cannot be resolved statically ' + NOT_AUTO_ALLOWED }];
+            return [{ kind: "unresolvable", operand: "-", reason: '`cd -` targets the previous working directory, which cannot be resolved statically ' + NOT_AUTO_ALLOWED }];
         }
         candidates.push({ text: target, globbed: false });
     }
@@ -635,6 +732,8 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
         let endOfOptions = false;
         for (let k = 0; k < args.length; k++) {
             const t = args[k];
+            if (expandingArgs.has(k))
+                continue;
             if (!endOfOptions) {
                 if (t === "--") {
                     endOfOptions = true;
@@ -662,8 +761,10 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
                 if (isGrepPatternSlot)
                     continue;
                 const m = RECURSIVE_READ_FORMS[name];
-                if (m === undefined || m.dashIsStdin === true)
+                if (m === undefined || m.dashIsStdin === true) {
+                    stdinOperand = true;
                     continue;
+                }
                 positionalOperands.push(t);
                 continue;
             }
@@ -677,7 +778,7 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
         }
     }
     for (let k = 0; k < args.length; k++) {
-        if (!argGlobs(k))
+        if (!argGlobs(k) || expandingArgs.has(k))
             continue;
         const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], args[k], boundary.homeDir);
         findings.push({ kind: "undecided", path: resolved ?? args[k] });
@@ -687,6 +788,7 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
         if (resolved === undefined) {
             findings.push({
                 kind: "unresolvable",
+                operand: candidate,
                 reason: `"${name}" names the path "${candidate}", which cannot be resolved statically ${NOT_AUTO_ALLOWED}`,
             });
             continue;
@@ -706,7 +808,7 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
             findings.push({ kind: "inside", path: resolved });
     }
     if (boundary.denyMatch !== undefined && segmentSelectsRecursiveRead(name, args)) {
-        const roots = positionalOperands.length > 0 ? positionalOperands : ["."];
+        const roots = positionalOperands.length > 0 ? positionalOperands : stdinOperand ? [] : ["."];
         for (const operand of roots) {
             const resolved = resolveOperandLexically(boundary.cwd ?? boundary.roots[0], operand, boundary.homeDir);
             findings.push({ kind: "recursive", path: resolved ?? operand });
@@ -714,8 +816,56 @@ function collectSegmentBoundaryFindings(tokens, boundary) {
     }
     return findings;
 }
-function segmentCompoundForReadonly(command) {
-    const trimmed = command.trim();
+export function foldHomeVariableSpelling(command, homeDir) {
+    if (homeDir === undefined || !command.includes("$") || /[\\`]/.test(command))
+        return command;
+    const unquotedIsExact = /^[A-Za-z0-9_./+@:%=,-]+$/.test(homeDir);
+    const quotedIsExact = !/["$`\\\n\r]/.test(homeDir);
+    const UNQUOTED_HOME_WORD = /^\$(?:HOME|\{HOME\})(?=[/\s;|&"]|$)/;
+    const DOUBLE_QUOTED_HOME_WORD = /^\$(?:HOME|\{HOME\})(?=[/"]|$)/;
+    let open;
+    let wordStart = true;
+    let quoteHadContent = false;
+    let out = "";
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        if (open === undefined && (ch === '"' || ch === "'")) {
+            open = ch;
+            quoteHadContent = false;
+            out += ch;
+            continue;
+        }
+        if (open !== undefined && open === ch) {
+            open = undefined;
+            wordStart = wordStart && !quoteHadContent;
+            out += ch;
+            continue;
+        }
+        if (open !== undefined)
+            quoteHadContent = true;
+        if (open === undefined && /[\s;|&]/.test(ch)) {
+            wordStart = true;
+            out += ch;
+            continue;
+        }
+        if (ch === "$" && wordStart && ((open === '"' && quotedIsExact) || (open === undefined && unquotedIsExact))) {
+            const m = (open === '"' ? DOUBLE_QUOTED_HOME_WORD : UNQUOTED_HOME_WORD).exec(command.slice(i));
+            if (m !== null) {
+                wordStart = false;
+                if (open === '"')
+                    quoteHadContent = true;
+                out += homeDir;
+                i += m[0].length - 1;
+                continue;
+            }
+        }
+        wordStart = false;
+        out += ch;
+    }
+    return open === undefined ? out : command;
+}
+function segmentCompoundForReadonly(command, homeDir) {
+    const trimmed = foldHomeVariableSpelling(command, homeDir).trim();
     if (!trimmed)
         return { reject: "empty command" };
     const redirectionStripped = stripExemptRedirections(trimmed);
@@ -725,14 +875,53 @@ function segmentCompoundForReadonly(command) {
     return splitShellCompoundSegments(terminatorStripped, { trailingTerminator: "keep" });
 }
 export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts) {
-    const split = segmentCompoundForReadonly(command);
+    const split = segmentCompoundForReadonly(command, boundary?.homeDir);
     if ("reject" in split)
-        return { reason: split.reject };
+        return { reason: split.reject, refusedWhole: true };
     const { segments, pipeFed } = split;
-    for (const segment of segments) {
-        const reason = coarseReadonlyCheck(segment, allow, { quotedOperatorsAreText: true });
-        if (reason !== undefined)
-            return { reason };
+    let nameRefusal;
+    const unlistedSegments = new Set();
+    const reheaded = new Map();
+    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))
+            from++;
+        const written = folded[from];
+        if (written === undefined)
+            return { reason: "empty command" };
+        if (isBareControlWord(toks, from, SHELL_BLOCK_WORDS)) {
+            unlistedSegments.add(si);
+            nameRefusal ??= `command "${written}" is not in the read-only allowlist`;
+            continue;
+        }
+        const parsed = parseLeadingCommandName(toks.raw.slice(from).join(" "), { quotedOperatorsAreText: true, pathPrefixedNameIsText: true });
+        if ("reject" in parsed)
+            return { reason: parsed.reject, refusedWhole: true };
+        const pathPrefixed = parsed.name.includes("/");
+        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 (allow.has(name)) {
+            if (pathPrefixed || from > 0)
+                reheaded.set(si, { from, head: name });
+            if (from > 0)
+                nameRefusal ??= `command "${folded[0]}" is not in the read-only allowlist`;
+            continue;
+        }
+        nameRefusal ??= `command "${parsed.name}" is not in the read-only allowlist`;
+        if (COMMAND_LAUNCHERS.has(name)) {
+            const unwrapped = unwrapLauncher(folded.slice(from), allow);
+            if (unwrapped.kind === "refused")
+                return { reason: unwrapped.reason, refusedWhole: true };
+            if (unwrapped.kind === "unlisted")
+                unlistedSegments.add(si);
+            else
+                reheaded.set(si, { from: from + unwrapped.index, head: unwrapped.head });
+            continue;
+        }
+        unlistedSegments.add(si);
     }
     const HEAD_AUTO_ALLOW_MAX = 1_000_000;
     const headBoundIsSmall = (name, toks) => {
@@ -764,16 +953,22 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
     };
     const STDIN_FILE_FLOOR = { cat: 1, grep: 2, head: 1, tail: 1, wc: 1, cut: 1, tr: Infinity, diff: 2, cmp: 2, comm: 2, sed: 2 };
     const foldedSegments = [];
+    let shapeRefusal = nameRefusal;
     for (let si = 0; si < segments.length; si++) {
-        const segmentTokens = tokenizeSegment(segments[si]);
+        if (unlistedSegments.has(si))
+            continue;
+        const rehead = reheaded.get(si);
+        const segmentTokens = rehead === undefined ? tokenizeSegment(segments[si]) : reheadSegment(tokenizeSegment(segments[si]), rehead.head, rehead.from);
         const toks = segmentTokens.folded;
         if (toks.length === 0)
             continue;
         foldedSegments.push(segmentTokens);
         const name = toks[0];
         const guardReason = guardedVerbFormReason(name, toks, segmentTokens.raw);
-        if (guardReason !== undefined)
-            return { reason: guardReason };
+        if (guardReason !== undefined) {
+            shapeRefusal ??= guardReason;
+            continue;
+        }
         if (!(pipeFed[si] ?? false)) {
             const floor = STDIN_FILE_FLOOR[name];
             const restArgs = toks.slice(1);
@@ -815,14 +1010,17 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
                 }
             }
             if (floor !== undefined && hasStdinDash) {
-                return { reason: `"${name}" reads stdin via an explicit "-" argument and would block until the tool timeout ${NOT_AUTO_ALLOWED}` };
+                shapeRefusal ??= `"${name}" reads stdin via an explicit "-" argument and would block until the tool timeout ${NOT_AUTO_ALLOWED}`;
+                continue;
             }
             if (floor !== undefined && operandCount < floor) {
-                return { reason: `"${name}" with no file argument reads stdin and would block until the tool timeout ${NOT_AUTO_ALLOWED}` };
+                shapeRefusal ??= `"${name}" with no file argument reads stdin and would block until the tool timeout ${NOT_AUTO_ALLOWED}`;
+                continue;
             }
         }
         if (name === "tail" && toks.slice(1).some((t) => t === "--follow" || t.startsWith("--follow=") || /^[-+][^\s]*[fF]/.test(t))) {
-            return { reason: "`tail` in follow mode never terminates " + NOT_AUTO_ALLOWED };
+            shapeRefusal ??= "`tail` in follow mode never terminates " + NOT_AUTO_ALLOWED;
+            continue;
         }
         const GENERATOR_DEVICES = new Set(["/dev/zero", "/dev/random", "/dev/urandom", "/dev/full"]);
         const deviceCandidates = [];
@@ -833,20 +1031,26 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
             }
             deviceCandidates.push(t);
         }
-        const deviceArgs = deviceCandidates.map(normalizeAbsPathLexically).filter(isBlockedDevicePath);
+        const deviceArgs = deviceCandidates.map((t) => resolveOperandLexically(undefined, t, boundary?.homeDir) ?? normalizeAbsPathLexically(t)).filter(isBlockedDevicePath);
         const rescuedByHead = headBoundIsSmall(name, toks) && deviceArgs.every((d) => GENERATOR_DEVICES.has(d));
         if (!rescuedByHead && deviceArgs.length > 0) {
-            return { reason: "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) " + NOT_AUTO_ALLOWED };
+            shapeRefusal ??= "reads a device/special file that is either unbounded (/dev/zero, /dev/stdin, /proc/<pid>/fd/0, … — blocks the pipeline until the tool timeout) or process-private (/proc/<pid>/environ, /proc/<pid>/mem, …) " + NOT_AUTO_ALLOWED;
         }
     }
     if (opts?.iterated !== true) {
         const cdSegments = foldedSegments.filter((st) => st.folded[0] === "cd");
-        if (cdSegments.length > 1) {
-            return { reason: `multiple directory changes in one command require approval for clarity ${NOT_AUTO_ALLOWED}` };
-        }
+        if (cdSegments.length > 1)
+            shapeRefusal ??= `multiple directory changes in one command require approval for clarity ${NOT_AUTO_ALLOWED}`;
     }
-    if (boundary !== undefined)
-        return evaluateReadBoundary(foldedSegments, boundary);
+    if (boundary !== undefined) {
+        const walk = evaluateReadBoundary(foldedSegments, boundary);
+        if (shapeRefusal === undefined)
+            return walk;
+        const { reason: _walkSentence, ...structure } = walk;
+        return { ...structure, reason: shapeRefusal };
+    }
+    if (shapeRefusal !== undefined)
+        return { reason: shapeRefusal };
     if (foldedSegments.some((st) => st.folded[0] === "cd")) {
         return { reason: `\`cd\` cannot be judged without a read boundary (no base to resolve the directory change against) ${NOT_AUTO_ALLOWED}` };
     }
@@ -855,14 +1059,25 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
 function evaluateReadBoundary(foldedSegments, boundary) {
     const outside = [];
     const inside = [];
+    let unresolvable;
+    const unresolved = [];
+    let baseLost = false;
     const undecided = [];
     const recursive = [];
     let currentBase = boundary.cwd ?? boundary.roots[0];
     for (const toks of foldedSegments) {
+        if (baseLost)
+            break;
         const segBoundary = currentBase === (boundary.cwd ?? boundary.roots[0]) ? boundary : { ...boundary, cwd: currentBase };
         for (const finding of collectSegmentBoundaryFindings(toks, segBoundary)) {
-            if (finding.kind === "unresolvable")
-                return { reason: finding.reason };
+            if (finding.kind === "unresolvable") {
+                unresolvable ??= finding.reason;
+                if (!unresolved.includes(finding.operand))
+                    unresolved.push(finding.operand);
+                if (toks.folded[0] === "cd")
+                    baseLost = true;
+                continue;
+            }
             const denied = boundary.denyMatch?.(finding.path);
             if (denied != null) {
                 return {
@@ -893,7 +1108,7 @@ function evaluateReadBoundary(foldedSegments, boundary) {
             if (!outside.some((o) => o.path === finding.path))
                 outside.push(finding);
         }
-        if (toks.folded[0] === "cd") {
+        if (!baseLost && toks.folded[0] === "cd") {
             const cdArgs = toks.folded.slice(1);
             const cdTargetIdx = cdArgs.findIndex((t) => !t.startsWith("-") || t === "-");
             const cdTarget = cdTargetIdx === -1 ? undefined : cdArgs[cdTargetIdx];
@@ -907,6 +1122,15 @@ function evaluateReadBoundary(foldedSegments, boundary) {
         ...(undecidedAll.length > 0 ? { undecidedPaths: undecidedAll } : {}),
         ...(recursive.length > 0 ? { recursiveReadPaths: recursive } : {}),
     };
+    if (unresolvable !== undefined) {
+        return {
+            reason: unresolvable,
+            unresolvedOperands: unresolved,
+            ...(outside.length > 0 ? { outOfRootRead: true, outOfRootPaths: outside.map((o) => o.path) } : {}),
+            ...(inside.length > 0 ? { checkedPaths: inside } : {}),
+            ...undecidedField,
+        };
+    }
     if (outside.length === 0)
         return inside.length > 0 ? { checkedPaths: inside, ...undecidedField } : { ...undecidedField };
     const paths = outside.map((o) => `"${o.path}"`).join(", ");
@@ -948,7 +1172,7 @@ export function classifyOutOfRootReadGate(command, allow, boundary) {
         ...(boundary.face !== undefined ? { face: boundary.face } : {}),
     };
     const judge = (text) => {
-        const split = segmentCompoundForReadonly(text);
+        const split = segmentCompoundForReadonly(text, containmentOnly.homeDir);
         if ("reject" in split)
             return NOT_GATED;
         const readers = [];
@@ -1028,69 +1252,69 @@ function pollLoopSleepReason(segment) {
     return undefined;
 }
 export function classifyBoundedReadonlyPollLoop(command, allow, boundary) {
+    return classifyBoundedReadonlyPollLoopDetailed(command, allow, boundary).reason;
+}
+export function classifyBoundedReadonlyPollLoopDetailed(command, allow, boundary) {
     if (NON_ASCII_WHITESPACE.test(command)) {
-        return "the command contains a non-ASCII or control whitespace character (only space and tab are allowed) — its word boundaries cannot be read the way bash would split them, so it is not auto-allowed";
+        return { reason: "the command contains a non-ASCII or control whitespace character (only space and tab are allowed) — its word boundaries cannot be read the way bash would split them, so it is not auto-allowed" };
     }
-    const trimmed = command.trim();
+    const trimmed = foldHomeVariableSpelling(command, boundary?.homeDir).trim();
     if (!trimmed)
-        return "empty command";
+        return { reason: "empty command" };
     if (!pollLoopQuotesBalanced(trimmed)) {
-        return "unbalanced quote — the command's structure cannot be read reliably, so it is not auto-allowed";
+        return { reason: "unbalanced quote — the command's structure cannot be read reliably, so it is not auto-allowed" };
     }
     const m = POLL_LOOP_SHAPE.exec(trimmed);
     if (m === null) {
-        return "not a bounded read-only poll loop (`for <v> in <literal bound>; do <read commands>; done` is the only accepted control structure)";
+        return { reason: "not a bounded read-only poll loop (`for <v> in <literal bound>; do <read commands>; done` is the only accepted control structure)" };
     }
     const varName = m[1];
     const iterable = m[2];
     const body = m[3];
     if (!/^[a-z]$/.test(varName)) {
-        return `the loop variable "${varName}" must be a single lowercase letter — a name like PATH/IFS/LD_PRELOAD would change how the body's commands resolve`;
+        return { reason: `the loop variable "${varName}" must be a single lowercase letter — a name like PATH/IFS/LD_PRELOAD would change how the body's commands resolve` };
     }
     const beats = pollLoopBeatsOf(iterable);
     if (beats === undefined) {
-        return `the loop bound "${iterable}" is not a recognized literal — only \`$(seq <int> <int>)\`, \`{<int>..<int>}\` (ascending) or a literal word list is accepted`;
+        return { reason: `the loop bound "${iterable}" is not a recognized literal — only \`$(seq <int> <int>)\`, \`{<int>..<int>}\` (ascending) or a literal word list is accepted` };
     }
     if (beats > POLL_LOOP_MAX_BEATS) {
-        return `the loop runs ${beats} iterations, above the ${POLL_LOOP_MAX_BEATS}-iteration cap for auto-allow`;
+        return { reason: `the loop runs ${beats} iterations, above the ${POLL_LOOP_MAX_BEATS}-iteration cap for auto-allow` };
     }
     if (POLL_BODY_HARD_REJECT.test(body)) {
-        return "the loop body may not contain redirection, pipes, backgrounding, substitution, subshells, braces, escapes, or line breaks";
+        return { reason: "the loop body may not contain redirection, pipes, backgrounding, substitution, subshells, braces, escapes, or line breaks" };
     }
     const readSegments = [];
     for (const rawSegment of body.split(";")) {
         const segment = rawSegment.trim();
         if (segment.length === 0)
-            return "empty command in the loop body";
+            return { reason: "empty command in the loop body" };
         const parsed = parseLeadingCommandName(segment);
         if ("reject" in parsed)
-            return parsed.reject;
+            return { reason: parsed.reject };
         if (parsed.name === "sleep") {
             const sleepReason = pollLoopSleepReason(segment);
             if (sleepReason !== undefined)
-                return sleepReason;
+                return { reason: sleepReason };
             continue;
         }
         readSegments.push(segment);
     }
     if (readSegments.length === 0) {
-        return "the loop body has no read command — a sleep-only loop observes nothing and is not auto-allowed";
+        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) => {
-        const p = parseLeadingCommandName(seg);
-        return "name" in p && p.name === "cd";
-    });
+    const bodyHasCd = readSegments.some((seg) => tokensMoveBase(tokenizeSegment(seg), allow));
     const modelled = bodyHasCd ? Array.from({ length: beats }, () => readSegments.join("; ")).join("; ") : readSegments.join("; ");
     const verdict = classifyCompoundReadonlyDetailed(modelled, allow, boundary, { iterated: bodyHasCd });
     if (verdict.reason !== undefined)
-        return verdict.reason;
+        return verdict;
     if (verdict.recursiveReadPaths !== undefined) {
         const roots = verdict.recursiveReadPaths;
         const shown = roots.slice(0, POLL_LOOP_CAUSE_MAX_PATHS);
-        return `this lexical check cannot bound what a recursive read form in the loop body traverses — ${roots.length} path(s) taken as traversal roots: ${shown.join(", ")}${roots.length > shown.length ? `, and ${roots.length - shown.length} more` : ""}`;
+        return { ...verdict, reason: `this lexical check cannot bound what a recursive read form in the loop body traverses — ${roots.length} path(s) taken as traversal roots: ${shown.join(", ")}${roots.length > shown.length ? `, and ${roots.length - shown.length} more` : ""}` };
     }
     if (verdict.undecidedPaths !== undefined) {
-        return `the loop body carries an unexpanded glob (${verdict.undecidedPaths.join(", ")}) — what a REPEATED read touches is decided at run time, so it is not auto-allowed`;
+        return { ...verdict, reason: `the loop body carries an unexpanded glob (${verdict.undecidedPaths.join(", ")}) — what a REPEATED read touches is decided at run time, so it is not auto-allowed` };
     }
-    return undefined;
+    return verdict;
 }

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

@@ -73,24 +73,28 @@ export declare function bashReversibilityProbe(allow?: readonly string[], bounda
  *  · the boundary DECLARED an objection — a deny-listed operand, a recursive walk under the deny judge, an
  *    operand outside the roots — ⇒ `{ reversible: false, mandated: true }` (+ the recursive-reach `cause`);
  *  · the boundary could NOT READ where the command reads — an unexpanded glob operand (the compound face
- *    reports it as undecided), a `~`-rooted operand with no home declared, a working-directory move the walk
- *    cannot model — ⇒ `{ reversible: false }` (fail-closed; a plain ask, which a stored allow rule may retire —
- *    the seat did not declare anything, it declined to guess);
+ *    reports it as undecided), a `~`-rooted operand under an adapter that declares no home, a working-directory
+ *    move the walk cannot model — ⇒ `{ reversible: false }` (fail-closed; a plain ask, which a stored allow rule
+ *    may retire — the seat did not declare anything, it declined to guess). The engine wires the environment's
+ *    declared home, so `~/x`, `$HOME/x` and `${HOME}/x` RESOLVE and are judged like the absolute spelling;
  *  · otherwise ⇒ `{ reversible: true }`. This includes every command whose SHAPE the read faces refuse whole
  *    (an unlisted program, a redirection, a substitution, a segment that is not a reader): those shapes carry
  *    no read-face verdict, so this seat has no question to ask — the residual is the doctrine's, and under
- *    `"off"` the doctrine asks nothing. `run_in_background` is likewise not this seat's question (it changes
- *    WHEN the command runs, never WHERE it reads).
+ *    `"off"` the doctrine asks nothing. A listed reader refused for a PER-SEGMENT shape (follow mode, a device,
+ *    a blocking stdin read) is different: the compound face still walks its operands and carries the boundary's
+ *    structural findings beside the sentence, so `tail -f <denied>` is the declared ask `cat <denied>` is.
+ *    `run_in_background` is likewise not this seat's question (it changes WHEN the command runs, never WHERE it
+ *    reads).
  *
  * Reach = the read faces' reach, and nothing wider: the compound face walks the operands of a command whose
  * every segment is a listed reader, and the bounded poll-loop face walks a loop body of listed readers. A
- * read hidden in a shape the faces refuse whole (`cat x | <unlisted>`, `$(cat x)`, `cat $DIR/x`, a launcher
- * `env cat x`, a path-prefixed `/bin/cat x`) is not seen here — deny-listed or out-of-root alike — exactly
+ * read hidden in a shape the faces refuse whole (`cat x | <unlisted>`, `$(cat x)`, `cat $DIR/x` — a variable other
+ * than the home's own deterministic spellings — a launcher `env cat x`, a path-prefixed `/bin/cat x`) is not
+ * seen here — deny-listed or out-of-root alike — exactly
  * the shapes the `"classify"` doctrine exists to ask about. The text-level containment gate the classify
  * seat consults on its demotion arms is deliberately not consulted here ({@link boundaryDeclared}: it may
- * add a mandate to an ask, never originate one). The poll-loop face reports its refusal as one sentence,
- * so the boundary's share of it is read by removing the boundary's judging seats
- * ({@link pollLoopBoundaryVerdict}).
+ * 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
  * auto-allow list but the set of programs whose operands the faces read; a wider set means more reads are