@sema-agent/core 7.15.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/encoding.d.ts

@@ -1,25 +1,19 @@
 /**
- * 编码 parity 批(docs/CC-TOOL-PARITY-SWEEP-2026-07.md P0)— file encoding + line-ending detection
- * for the Read/Edit/Write band, ported from CC's `utils/fileRead.ts` mechanism and hardened where CC
- * is lossy:
+ * File encoding + line-ending detection for the Read/Edit/Write band, ported from CC's
+ * `utils/fileRead.ts` mechanism and hardened where CC is lossy:
  *
- *  - BOM detection: `FF FE` → utf16le, `EF BB BF` → utf8-with-BOM, else plain utf8. (CC 88→2.1.187
- *    dynamic-verified: detection is BOM-only; UTF-16BE / heuristic sniffing deliberately NOT done —
- *    a wrong guess silently corrupts, and the BOM-less case stays a refusal at the Read layer.)
+ *  - BOM detection: `FF FE` → utf16le, `EF BB BF` → utf8-with-BOM, else plain utf8. Detection is
+ *    BOM-only; UTF-16BE / heuristic sniffing is deliberately NOT done — a wrong guess silently
+ *    corrupts, and the BOM-less case stays a refusal at the Read layer.
  *  - The MODEL-FACING text is BOM-stripped and CRLF-normalized (what the model quotes in `old_string`
- *    must match what Read showed it).
- *    RB-285 (encoding LOW, 归因收窄 — CC 220 亲核): the blanket "(CC parity)" that used to sit on this
- *    line was half wrong, because CC has TWO read lanes and they disagree with each other.
- *      · CRLF-normalize — parity on both lanes (`Zr_` @276877 and `Mqe` @58197 both `replaceAll`).
- *      · BOM-strip — parity on CC's READ lane only (`Zr_` @276877: `charCodeAt(0) === 65279 → slice(1)`).
- *        CC's EDIT/WRITE lane (`Mqe`) does NOT strip: it hands the model text with the leading U+FEFF
- *        still in it, and only the staleness/hash coordinate (`X9` = `CTe` + CRLF, @365630-365635)
- *        strips. sema strips in ONE shared decoder for every lane, so the model-facing view and the
- *        hash coordinate cannot drift apart — an improvement over CC's split, recorded as such rather
- *        than claimed as parity.
- *  - Write-back re-encodes with the ORIGINAL encoding, PRESERVES the BOM (CC drops it on Write — its
- *    lossy face, dynamic-verified W1; we keep it, recorded as a deliberate improvement), and restores
- *    the file's dominant line endings for Edit (Write keeps the model's endings as-is, CC decision).
+ *    must match what Read showed it). CRLF-normalize is parity on both of CC's read lanes; BOM-strip
+ *    is parity on CC's READ lane only — CC's EDIT/WRITE lane hands the model text with the leading
+ *    U+FEFF still in it and strips only inside its staleness/hash coordinate. sema strips in ONE
+ *    shared decoder for every lane, so the model-facing view and the hash coordinate cannot drift
+ *    apart: a registered delta, not parity.
+ *  - Write-back re-encodes with the ORIGINAL encoding, PRESERVES the BOM (CC drops it on Write — a
+ *    registered deliberate improvement), and restores the file's dominant line endings for Edit
+ *    (Write keeps the model's endings as-is, CC decision).
  */
 /** Detected byte-level encoding of a text file (BOM-driven; utf8 is the no-BOM default). */
 export interface DetectedFileEncoding {
@@ -31,19 +25,17 @@ export interface DecodedTextFile {
     /** Model-facing text: BOM stripped, `\r\n` normalized to `\n`. The staleness-hash coordinate. */
     text: string;
     encoding: DetectedFileEncoding;
-    /** Dominant line ending of the ORIGINAL bytes (majority vote — CC `CKt` @58184 同算法).
+    /** Dominant line ending of the ORIGINAL bytes (majority vote; CC's counting rule).
      *  Deliberately NOT per-line lossless: a mixed-endings file is unified to the dominant ending on
-     *  the first edit (镜头1/2 LOW, accepted non-goal — CC behaves the same way).
-     *  RB-285 (encoding LOW): the COUNTING RULE is CC's; the SAMPLE is not. CC votes on the first 4096
-     *  characters only (`CKt(s.slice(0, 4096))` @58201) while {@link detectLineEndings} below votes on
-     *  the whole file — so a file whose first 4KB is LF and whose bulk is CRLF gets opposite verdicts.
-     *  sema's whole-file vote is kept on purpose: the verdict decides what an Edit WRITES BACK across
-     *  the entire file, so sampling a prefix is exactly the case where the cheap answer flips the
-     *  remaining 99% of the lines. Registered as a deliberate delta, not parity. */
+     *  the first edit (accepted non-goal — CC behaves the same way).
+     *  The SAMPLE is a registered delta: CC votes on the first 4096 characters only, while
+     *  {@link detectLineEndings} below votes on the whole file. The verdict decides what an Edit WRITES
+     *  BACK across the entire file, so sampling a prefix is exactly the case where the cheap answer
+     *  flips the remaining 99% of the lines. */
     endings: DetectedLineEndings;
-    /** 双镜头 MED: a utf16le body with an ODD byte count is TRUNCATED/corrupt — decoding would
-     *  silently drop the dangling byte and a later write-back would destroy it permanently. Flagged so
-     *  the tool layer fails closed instead of "repairing" the file. */
+    /** A utf16le body with an ODD byte count is TRUNCATED/corrupt — decoding would silently drop the
+     *  dangling byte and a later write-back would destroy it permanently. Flagged so the tool layer
+     *  fails closed instead of "repairing" the file. */
     malformed?: true;
 }
 /** BOM-only encoding detection (CC `detectEncodingForResolvedPath` parity — no content heuristics). */
@@ -56,8 +48,8 @@ export declare function decodeTextBytes(bytes: Uint8Array): DecodedTextFile;
  * @param text normalized (`\n`) text when `endings` is CRLF/LF (Edit path — restore the file's
  *   dominant endings); pass `endings:"preserve"` to write the text's OWN line endings untouched
  *   (Write path — CC decision: the model sent explicit endings in `content` and meant them).
- * @returns a plain string for the no-BOM utf8 + LF-or-preserve fast path (byte-compatible with the
- *   pre-batch writer), else the exact bytes (BOM + encoded body).
+ * @returns a plain string for the no-BOM utf8 + LF-or-preserve fast path, else the exact bytes
+ *   (BOM + encoded body).
  */
 export declare function encodeTextForFile(text: string, encoding: DetectedFileEncoding, endings: DetectedLineEndings | "preserve"): string | Uint8Array;
 /** Normalize model-supplied match/replacement text the same way the file text was normalized
@@ -65,16 +57,15 @@ export declare function encodeTextForFile(text: string, encoding: DetectedFileEn
  *  Deliberately does NOT strip a leading U+FEFF: an `old_string` starting with one may be quoting
  *  genuine file content — use {@link normalizeFileText} only where the string stands for a whole file. */
 export declare function normalizeEditText(s: string): string;
-/** RB-222 — split a leading U+FEFF off MODEL-SUPPLIED whole-file text (CC `CTe` parity,
- *  220 @365630). The BOM is a file-level byte marker, not text: decodeTextBytes strips it on the way
- *  in, so it can never live in the normalized coordinate. Only for strings that stand for a WHOLE
- *  file (Write `content`, readFileState seeding) — a decoded file text's leading U+FEFF is genuine
- *  content and must stay. */
+/** Split a leading U+FEFF off MODEL-SUPPLIED whole-file text (CC parity). The BOM is a file-level
+ *  byte marker, not text: decodeTextBytes strips it on the way in, so it can never live in the
+ *  normalized coordinate. Only for strings that stand for a WHOLE file (Write `content`,
+ *  readFileState seeding) — a decoded file text's leading U+FEFF is genuine content and must stay. */
 export declare function splitLeadingBom(text: string): {
     hadBom: boolean;
     text: string;
 };
-/** RB-222 — CC `X9` parity (220 @365635 = BOM-strip + CRLF-normalize): THE coordinate
- *  every readFileState hash lives in (Read/Edit/Write staleness all hash `decodeTextBytes(...).text`).
- *  A hash taken on raw model content with a leading U+FEFF can never agree with any later re-read. */
+/** CC parity (BOM-strip + CRLF-normalize): THE coordinate every readFileState hash lives in
+ *  (Read/Edit/Write staleness all hash `decodeTextBytes(...).text`). A hash taken on raw model content
+ *  with a leading U+FEFF can never agree with any later re-read. */
 export declare function normalizeFileText(s: string): string;