@sema-agent/core 7.16.0 → 7.17.0

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, 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,33 @@ 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 (isAbsoluteForFamily(family, raw))
+        return normalizeAbsPathLexically(nativeUncSpellingOf(family, raw));
+    if (base === undefined || family === undefined || !isAbsoluteForFamily(family, base))
         return undefined;
-    return normalizeAbsPathLexically(`${base.replace(/[/\\]+$/, "")}/${raw}`);
+    if (isShellRootedSpellingUnmapped(family, raw))
+        return undefined;
+    return normalizeAbsPathLexically(joinForFamily(family, base, raw));
 }
 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 +593,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 +606,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 +619,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 +658,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 +687,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 +704,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 +714,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 +734,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 +742,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,7 +801,7 @@ 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 };
     const { segments, pipeFed } = split;
@@ -764,6 +840,7 @@ 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;
     for (let si = 0; si < segments.length; si++) {
         const segmentTokens = tokenizeSegment(segments[si]);
         const toks = segmentTokens.folded;
@@ -772,8 +849,10 @@ export function classifyCompoundReadonlyDetailed(command, allow, boundary, opts)
         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 +894,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 +915,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) {
+        const walk = evaluateReadBoundary(foldedSegments, boundary);
+        if (shapeRefusal === undefined)
+            return walk;
+        const { reason: _walkSentence, ...structure } = walk;
+        return { ...structure, reason: shapeRefusal };
     }
-    if (boundary !== undefined)
-        return evaluateReadBoundary(foldedSegments, boundary);
+    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 +943,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 +992,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 +1006,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 +1056,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,53 +1136,56 @@ 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);
@@ -1083,14 +1194,14 @@ export function classifyBoundedReadonlyPollLoop(command, allow, boundary) {
     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

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

@@ -11,7 +11,7 @@ import { isRemoteExecutionEnv, hasDestroy, isIsolated } from "../../core/remote-
 import { ghRateLimitHint } from "./gh-rate-limit.js";
 import { resolveBashTimeoutCaps, bashTimeoutCapsSec, bashTimeoutArgRefusal, bashTimeoutParamDescription, envErrorDetail, bashMaxOutputChars, clipShellOutput, writeShellOverflowFile, createShellOverflowSpoolFence, shellRecoveryHint, CWD_SENTINEL, BASH_READONLY_CONFINEMENT_NOTE, } from "./fs-shared.js";
 import { PROBE_CAUSE_PATH_MAX, inlineUntrusted } from "../../core/untrusted-text.js";
-import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
+import { BASH_CLASSIFY_DEFAULT_ALLOW, BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoopDetailed, classifyCompoundReadonlyDetailed, classifyOutOfRootReadGate, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 const RECURSIVE_CAUSE_MAX_PATHS = 3;
 const RECURSIVE_READ_CAUSE_CODE = "shell.recursive_read_unbounded";
@@ -36,7 +36,7 @@ export function bashReversibilityProbe(allow, boundary) {
         if (backgrounded)
             return { reversible: false, ...boundaryGate(detailed) };
         if (detailed.reason === undefined) {
-            if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0) {
+            if (boundaryUnread(detailed)) {
                 const cause = recursiveReadCause(detailed);
                 if (cause !== undefined)
                     return { reversible: false, ...boundaryGate(detailed), cause };
@@ -44,23 +44,16 @@ export function bashReversibilityProbe(allow, boundary) {
             }
             return { reversible: true };
         }
-        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
-        if (loopRefusal === undefined)
+        const loop = classifyBoundedReadonlyPollLoopDetailed(command, allowSet, resolved);
+        if (loop.reason === undefined)
             return { reversible: true };
-        return { reversible: false, ...(pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal) === "declared" ? { mandated: true } : boundaryGate(detailed)) };
+        if (boundaryDeclared(loop))
+            return { reversible: false, mandated: true };
+        return { reversible: false, ...boundaryGate(detailed) };
     };
 }
-function attributeRefusal(face, resolved, fullRefusal) {
-    if (resolved === undefined)
-        return "shape";
-    const { denyMatch: _deny, ...withoutDenyJudge } = resolved;
-    const opened = face({ ...withoutDenyJudge, face: "open" });
-    if (opened === undefined || opened !== fullRefusal)
-        return "declared";
-    return face(undefined) === opened ? "shape" : "unread";
-}
-function pollLoopBoundaryVerdict(command, allowSet, resolved, fullRefusal) {
-    return attributeRefusal((b) => classifyBoundedReadonlyPollLoop(command, allowSet, b), resolved, fullRefusal);
+function boundaryUnread(verdict) {
+    return (verdict.undecidedPaths !== undefined && verdict.undecidedPaths.length > 0) || (verdict.unresolvedOperands !== undefined && verdict.unresolvedOperands.length > 0);
 }
 function boundaryDeclared(verdict) {
     return denyJudgeSpoke(verdict) || verdict.outOfRootRead === true;
@@ -106,19 +99,18 @@ export function bashReadBoundaryProbe(boundary) {
             const cause = recursiveReadCause(detailed);
             return { reversible: false, mandated: true, ...(cause !== undefined ? { cause } : {}) };
         }
-        if (detailed.reason === undefined) {
-            return detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0 ? { reversible: false } : { reversible: true };
-        }
-        const compound = attributeRefusal((b) => classifyCompoundReadonlyDetailed(command, allowSet, b).reason, resolved, detailed.reason);
-        if (compound === "declared")
-            return { reversible: false, mandated: true };
-        if (compound === "unread")
+        if (boundaryUnread(detailed))
             return { reversible: false };
-        const loopRefusal = classifyBoundedReadonlyPollLoop(command, allowSet, resolved);
-        if (loopRefusal === undefined)
+        if (detailed.reason === undefined)
+            return { reversible: true };
+        const loop = classifyBoundedReadonlyPollLoopDetailed(command, allowSet, resolved);
+        if (loop.reason === undefined)
             return { reversible: true };
-        const loop = pollLoopBoundaryVerdict(command, allowSet, resolved, loopRefusal);
-        return loop === "shape" ? { reversible: true } : loop === "declared" ? { reversible: false, mandated: true } : { reversible: false };
+        if (boundaryDeclared(loop))
+            return { reversible: false, mandated: true };
+        if (boundaryUnread(loop))
+            return { reversible: false };
+        return { reversible: true };
     };
 }
 export { FULL_SHELL_CONTRACT_ID } from "../../core/tool-catalog-entries.js";

package/dist/tools/fs/fs-search-tools.js

@@ -1,6 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../../core/tools.js";
-import { resolveKey, violationText, violationDetails } from "./safety.js";
+import { clipSpelling, pathFamilyOf, resolveKey, violationText, violationDetails, WIN32_NAMESPACE_REFUSAL_TEXT } from "./safety.js";
 import { runGrepDetailed, runGlobDetailed, invalidGlobTokens } from "./search.js";
 import { toolFace } from "../../core/tool-catalog-entries.js";
 import { pathTargetBaseOf, splitAbsoluteGlobPattern } from "../../core/effective-path-target.js";
@@ -205,7 +205,10 @@ export function createGlobTool(env, rootCanonical, additionalRoots, readDeny, re
             let path = declaredTarget === undefined ? undefined : pathTargetValue(args, declaredTarget);
             const { max_results } = args;
             if (path === undefined) {
-                const split = splitAbsoluteGlobPattern(pattern);
+                const split = splitAbsoluteGlobPattern(pattern, pathFamilyOf({ root: rootCanonical }));
+                if (split !== undefined && "refused" in split) {
+                    return errorResult(`Error (Glob): pattern "${clipSpelling(pattern)}" ${WIN32_NAMESPACE_REFUSAL_TEXT[split.refused]}; refused (${split.refused}).`);
+                }
                 if (split) {
                     path = split.baseDir;
                     pattern = split.relativePattern;

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

@@ -273,6 +273,8 @@ export declare function bashTimeoutCapsSec(caps: {
     defaultSec: number;
     maxSec: number;
 };
+/** Read per call (a deployment steers it without a restart); the one shared resolver holds the grammar,
+ *  the `[OUTPUT_BUDGET_MIN_CHARS, ceiling]` range and the loud outlet for a value it could not honor. */
 export declare function bashMaxOutputChars(): number;
 export declare const FILE_PATH_PARAMS: {
     file_path: Type.TString;