@sema-agent/core 7.47.0 → 7.49.0

package/dist/tools/fs/read-deny.js

@@ -1,6 +1,8 @@
 import { sliceHeadSafe, sliceTailSafe } from "../../core/surrogate-safe-slice.js";
-import { isAbsolutePathForm, normalizeAbsPathLexically, pathFamilyOf, pathIdentityOf, spellingOfIdentity } from "./safety.js";
+import { isAbsoluteForFamily, normalizeAbsPathLexically, pathFamilyOf, pathIdentityOf, spellingOfIdentity } from "./safety.js";
 import { PROBE_REASON_MAX } from "../../core/untrusted-text.js";
+import { validatePath } from "../../core/effective-path-target.js";
+import { judgePathRows } from "../../core/path-guard-rows.js";
 export const READ_DENY_HOME_WORD = "~";
 export function readDenyPatternRun(pattern) {
     const segments = pattern.split("/").filter(Boolean);
@@ -15,28 +17,12 @@ export const DENY_FACES = Object.freeze(["read", "write"]);
 const REACHED = { reach: "reached" };
 const NOT_REACHED = { reach: "not_reached" };
 const reachOf = (row, spelled) => row.reach?.(spelled) ?? (row.reaches(spelled) ? REACHED : NOT_REACHED);
-export function pathRowsReach(rows, views, direction) {
-    if (direction === "allow") {
-        if (views.unreadable !== undefined || views.spellings.length === 0)
-            return undefined;
-        for (const row of rows)
-            if (views.spellings.every((v) => reachOf(row, v).reach === "reached"))
-                return { row };
-        return undefined;
-    }
-    let held;
-    for (const row of rows) {
-        if (views.unreadable !== undefined)
-            held ??= { row, unreadable: views.unreadable };
-        for (const view of views.spellings) {
-            const r = reachOf(row, view);
-            if (r.reach === "reached")
-                return { row, view };
-            if (r.reach === "unreadable")
-                held ??= { row, unreadable: r.reason };
-        }
-    }
-    return held;
+export function judgeRuleRows(rows, views, direction) {
+    const hit = judgePathRows(rows.map(ruleGuard), views, direction);
+    return hit === undefined ? undefined : { ...hit, row: hit.row.rule };
+}
+function ruleGuard(rule) {
+    return { rule, reach: (view) => reachOf(rule, view.path) };
 }
 export function ruleHeadParts(rows) {
     const out = new Set();
@@ -130,34 +116,42 @@ function rowLedTo(row, head, at) {
             : {}),
     };
 }
-function ruleRowsHit(rows, face, spellings) {
-    const onFace = rows.filter((r) => r.faces.includes(face));
-    return onFace.length === 0 ? undefined : pathRowsReach(onFace, { spellings }, "tighten");
+export function ruleGuardRow(rule) {
+    return { rule, name: rule.rule, grammar: { kind: "rule", rule: rule.rule }, polarity: "deny", faces: rule.faces, placement: "anywhere", fold: "exact", exemptible: false, origin: "rule", reach: (view) => reachOf(rule, view.path) };
+}
+export function segmentGuardRow(pat, columns) {
+    const placement = pat.anchors === undefined ? "anywhere" : pat.rootedOnly !== true ? "home" : pat.anchors.length === 1 && pat.anchors[0].length === 0 ? "rooted" : { below: `/${(pat.anchors[0] ?? []).join("/")}` };
+    return {
+        name: pat.raw,
+        grammar: { kind: "segment-glob", run: pat.raw },
+        placement,
+        ...columns,
+        reach: (view) => (segmentRowMeets(pat, segmentReadingsOf(view.path, view.aliasResolved === true)) ? REACHED : NOT_REACHED),
+    };
+}
+function denyTableHit(rows, views) {
+    const hit = judgePathRows(rows, views, "tighten");
+    if (hit === undefined)
+        return null;
+    const view = hit.view ?? views.views[0]?.path;
+    return { pattern: hit.row.name, ...(view !== undefined ? { matchedView: view } : {}) };
+}
+function denyTargetViews(canonicalKey, lexicalView, opts) {
+    const views = [{ path: canonicalKey, kind: "canonical", ...(opts?.aliasResolved === true ? { aliasResolved: true } : {}) }];
+    if (lexicalView !== undefined)
+        views.push({ path: lexicalView, kind: "lexical" });
+    for (const hop of opts?.hops ?? [])
+        views.push({ path: hop, kind: "hop" });
+    return { views };
 }
 export function compileWriteDeny(rules = []) {
     const ruleRows = rules.filter((r) => r.faces.includes("write"));
+    const rows = ruleRows.map(ruleGuardRow);
     const matchPath = (path) => {
-        const hit = ruleRowsHit(ruleRows, "write", [path]);
-        return hit === undefined ? null : { pattern: hit.row.rule };
+        const hit = denyTableHit(rows, { views: [{ path, kind: "lexical" }] });
+        return hit === null ? null : { pattern: hit.pattern };
     };
-    return { face: "write", ruleRows, matchPath, matchTarget: (canonicalKey, lexicalView, opts) => matchTargetOver(() => null, ruleRows, "write", canonicalKey, lexicalView, opts) };
-}
-function matchTargetOver(segmentPath, ruleRows, face, canonicalKey, lexicalView, opts) {
-    const canonical = segmentPath(canonicalKey, opts);
-    if (canonical !== null)
-        return { ...canonical, matchedView: canonicalKey };
-    if (lexicalView !== undefined) {
-        const lexical = segmentPath(lexicalView);
-        if (lexical !== null)
-            return { ...lexical, matchedView: lexicalView };
-    }
-    for (const hop of opts?.hops ?? []) {
-        const viaHop = segmentPath(hop);
-        if (viaHop !== null)
-            return { ...viaHop, matchedView: hop };
-    }
-    const hit = ruleRowsHit(ruleRows, face, [canonicalKey, ...(lexicalView !== undefined ? [lexicalView] : []), ...(opts?.hops ?? [])]);
-    return hit === undefined ? null : { pattern: hit.row.rule, matchedView: hit.view ?? canonicalKey };
+    return { face: "write", ruleRows, matchPath, matchTarget: (canonicalKey, lexicalView, opts) => denyTableHit(rows, denyTargetViews(canonicalKey, lexicalView, opts)) };
 }
 export function readDenySeat(matcher) {
     const entries = [...(matcher?.entries ?? []).map((e) => e.pattern), ...(matcher?.ruleRows ?? []).map((r) => r.rule)];
@@ -320,28 +314,43 @@ export function compileSegmentPattern(raw, fold) {
     return { raw, segments, foldAscii: fold === "ascii" };
 }
 export function matchSegmentPatterns(path, compiled, opts) {
-    const views = segmentViewsOf(path, opts);
-    const rooted = isAbsolutePathForm(path);
-    const lowered = new Map();
-    for (const pat of compiled) {
-        for (const view of views) {
-            const segs = pat.foldAscii ? (lowered.get(view) ?? lowered.set(view, view.map(asciiLower)).get(view)) : view;
-            const n = pat.segments.length;
-            const runAt = (i) => i + n <= segs.length && pat.segments.every((re, j) => re.test(segs[i + j] ?? ""));
-            if (pat.anchors !== undefined && rooted) {
-                for (const anchor of pat.anchors)
-                    if (anchor.every((a, j) => segs[j] === a) && runAt(anchor.length))
-                        return pat.raw;
-                continue;
-            }
-            if (pat.rootedOnly === true)
-                continue;
-            for (let i = 0; i + n <= segs.length; i++)
-                if (runAt(i))
-                    return pat.raw;
+    const readings = segmentReadingsOf(path, opts?.aliasResolved === true);
+    for (const pat of compiled)
+        if (segmentRowMeets(pat, readings))
+            return pat.raw;
+    return null;
+}
+const SEGMENT_READINGS = new Map();
+function segmentReadingsOf(path, aliasResolved) {
+    const key = `${aliasResolved ? "1" : "0"}${path}`;
+    const known = SEGMENT_READINGS.get(key);
+    if (known !== undefined)
+        return known;
+    const views = segmentViewsOf(path, aliasResolved ? { aliasResolved } : undefined);
+    const readings = { views, lowered: views.map((v) => v.map(asciiLower)), rooted: isAbsoluteForFamily("own", path) };
+    if (SEGMENT_READINGS.size >= 512)
+        SEGMENT_READINGS.clear();
+    SEGMENT_READINGS.set(key, readings);
+    return readings;
+}
+function segmentRowMeets(pat, readings) {
+    const n = pat.segments.length;
+    const views = pat.foldAscii ? readings.lowered : readings.views;
+    for (const segs of views) {
+        const runAt = (i) => i + n <= segs.length && pat.segments.every((re, j) => re.test(segs[i + j] ?? ""));
+        if (pat.anchors !== undefined && readings.rooted) {
+            for (const anchor of pat.anchors)
+                if (anchor.every((a, j) => segs[j] === a) && runAt(anchor.length))
+                    return true;
+            continue;
         }
+        if (pat.rootedOnly === true)
+            continue;
+        for (let i = 0; i + n <= segs.length; i++)
+            if (runAt(i))
+                return true;
     }
-    return null;
+    return false;
 }
 function segmentViewsOf(path, opts) {
     const literalSegs = path.split(/[\\/]/).filter(Boolean);
@@ -386,7 +395,7 @@ function rowMeetsPath(pat, segs, rooted) {
     return false;
 }
 function rowAtOrBelowOf(rows, path) {
-    const rooted = isAbsolutePathForm(path);
+    const rooted = isAbsoluteForFamily("own", path);
     const views = segmentViewsOf(path);
     for (const pat of rows) {
         for (const view of views)
@@ -401,6 +410,15 @@ function homeAnchorSegments(home) {
 function rgGlobEscape(pattern) {
     return pattern.replace(/[?[\]{}]/g, (c) => `[${c}]`);
 }
+export function readDenyEntryProblem(entry, layer) {
+    try {
+        normalizeEntry(entry, layer);
+        return undefined;
+    }
+    catch (e) {
+        return e.message;
+    }
+}
 function normalizeEntry(entry, layer) {
     const shape = typeof entry === "string" ? { pattern: entry, caseSensitive: false } : entry;
     if (typeof shape !== "object" || shape === null || typeof shape.pattern !== "string") {
@@ -418,7 +436,14 @@ function normalizeEntry(entry, layer) {
         throw new Error(`readDenyPatterns (${layer}): pattern ${JSON.stringify(shape.pattern)} contains no path segments${homeAnchored ? " below the home word" : ""} and would ${homeAnchored ? "name the whole home directory" : "deny nothing"}. ` +
             `Patterns are "/"-separated runs of path SEGMENTS (e.g. ".ssh", ".config/gcloud", "id_rsa*", "~/.sema/settings.json"); remove the entry or spell the segments.`);
     }
-    return { pattern: segments.join("/"), caseSensitive: shape.caseSensitive === true };
+    return { pattern: canonicalReadDenyPattern(shape.pattern), caseSensitive: shape.caseSensitive === true };
+}
+function canonicalReadDenyPattern(pattern) {
+    const joined = pattern.split("/").filter(Boolean).join("/");
+    return pattern.startsWith("/") && !readDenyPatternRun(joined).homeAnchored ? `/${joined}` : joined;
+}
+export function isRootedReadDenyPattern(canonical) {
+    return canonical.startsWith("/");
 }
 export function persistedReadDenyEntryProblem(e) {
     if (typeof e !== "object" || e === null)
@@ -434,12 +459,12 @@ export function persistedReadDenyEntryProblem(e) {
     const segments = pattern.split("/").filter(Boolean);
     if (readDenyPatternRun(segments.join("/")).run.length === 0)
         return "pattern has no path segments";
-    if (segments.join("/") !== pattern)
+    if (canonicalReadDenyPattern(pattern) !== pattern)
         return "pattern is not in canonical a/b form";
     return null;
 }
 export function checkedReadDenyHomes(homes, seat = "readDenyHomes") {
-    if (!Array.isArray(homes) || !homes.every((h) => typeof h === "string" && isAbsolutePathForm(h))) {
+    if (!Array.isArray(homes) || !homes.every((h) => validatePath(h, { intent: "validate-coordinate" }) !== undefined)) {
         let shown;
         try {
             shown = JSON.stringify(homes) ?? String(homes);
@@ -462,10 +487,19 @@ export function compileReadDeny(additions = [], layer = "additions", builtin, ru
         seen.add(key);
         normalized.push(e);
     };
-    for (const row of resolveReadDenyBuiltins(builtin))
-        push(normalizeEntry(row.pattern, "built-in"));
-    for (const entry of additions)
-        push(normalizeEntry(entry, layer));
+    const columns = new Map();
+    for (const row of resolveReadDenyBuiltins(builtin)) {
+        const e = normalizeEntry(row.pattern, "built-in");
+        push(e);
+        if (!columns.has(e.pattern))
+            columns.set(e.pattern, { origin: "builtin", tier: row.tier });
+    }
+    for (const entry of additions) {
+        const e = normalizeEntry(entry, layer);
+        push(e);
+        if (!columns.has(e.pattern))
+            columns.set(e.pattern, { origin: "addition" });
+    }
     const homeSegments = [...new Set(checkedReadDenyHomes(homes))].map(homeAnchorSegments);
     const compiled = normalized.map((e) => {
         const { homeAnchored, run } = readDenyPatternRun(e.pattern);
@@ -473,6 +507,8 @@ export function compileReadDeny(additions = [], layer = "additions", builtin, ru
         const c = compileSegmentPattern(run, fold);
         if (c === null)
             throw new Error(`readDenyPatterns: pattern ${JSON.stringify(e.pattern)} compiled to zero segments.`);
+        if (isRootedReadDenyPattern(e.pattern))
+            return { ...c, raw: e.pattern, anchors: [[]], rootedOnly: true };
         if (!homeAnchored || homeSegments.length === 0)
             return { ...c, raw: e.pattern };
         return { ...c, raw: e.pattern, anchors: homeSegments.map((segs) => (fold === "ascii" ? segs.map(asciiLower) : segs)) };
@@ -483,7 +519,7 @@ export function compileReadDeny(additions = [], layer = "additions", builtin, ru
     normalized.forEach((e, i) => {
         const locations = linked.get(e.pattern);
         const { homeAnchored, run } = readDenyPatternRun(e.pattern);
-        if (locations === undefined || !homeAnchored)
+        if (locations === undefined || !(homeAnchored || isRootedReadDenyPattern(e.pattern)))
             return;
         const c = compiled[i];
         const rest = c.segments.slice(readDenyRunHead(run));
@@ -493,40 +529,38 @@ export function compileReadDeny(additions = [], layer = "additions", builtin, ru
         }
     });
     const judged = linkedPlacements.length === 0 ? compiled : [...compiled, ...linkedPlacements];
+    const segmentRows = judged.map((c) => {
+        const col = columns.get(c.raw);
+        return segmentGuardRow(c, { faces: ["read"], polarity: "deny", exemptible: false, fold: c.foldAscii ? "ascii" : "exact", origin: col?.origin ?? "addition", ...(col?.tier !== undefined ? { tier: col.tier } : {}) });
+    });
+    const tableRows = [...segmentRows, ...ruleRows.map(ruleGuardRow)];
     const rgExclusionGlobs = [];
     const rgProbeGlobs = [];
-    normalized.forEach((e, i) => {
-        if (compiled[i].anchors !== undefined)
-            return;
-        const flag = e.caseSensitive ? "--glob" : "--iglob";
-        const g = rgGlobEscape(readDenyPatternRun(e.pattern).run);
+    for (const row of segmentRows) {
+        if (row.placement !== "anywhere" || !row.faces.includes("read") || row.grammar.kind !== "segment-glob")
+            continue;
+        const flag = row.fold === "exact" ? "--glob" : "--iglob";
+        const g = rgGlobEscape(readDenyPatternRun(row.grammar.run).run);
         rgExclusionGlobs.push({ flag, glob: `!**/${g}` }, { flag, glob: `!**/${g}/**` });
         rgProbeGlobs.push({ flag, glob: `**/${g}` }, { flag, glob: `**/${g}/**` });
-    });
+    }
     const placed = judged.filter((c) => c.anchors !== undefined);
-    const unexcludableUnder = (scope) => placed.length > 0 && (!isAbsolutePathForm(scope) || rowAtOrBelowOf(placed, normalizeAbsPathLexically(scope)) !== null);
+    const unexcludableUnder = (scope) => placed.length > 0 && (!isAbsoluteForFamily("own", scope) || rowAtOrBelowOf(placed, normalizeAbsPathLexically(scope)) !== null);
     const rowAtOrBelow = (path) => {
         const hit = rowAtOrBelowOf(judged, path);
         if (hit !== null)
             return { pattern: hit };
         return ruleRows.length === 0 ? null : { pattern: ruleRows[0].rule };
     };
-    const segmentPath = (path, opts) => {
-        const hit = matchSegmentPatterns(path, judged, opts);
-        return hit === null ? null : { pattern: hit };
-    };
     const matchPath = (path, opts) => {
-        const hit = segmentPath(path, opts);
-        if (hit !== null)
-            return hit;
-        const rule = ruleRows.length === 0 || opts?.walked === true ? undefined : ruleRowsHit(ruleRows, "read", [path]);
-        return rule === undefined ? null : { pattern: rule.row.rule };
+        const hit = denyTableHit(opts?.walked === true ? segmentRows : tableRows, { views: [{ path, kind: "lexical", ...(opts?.aliasResolved === true ? { aliasResolved: true } : {}) }] });
+        return hit === null ? null : { pattern: hit.pattern };
     };
     return {
         entries: normalized,
         ...(ruleRows.length > 0 ? { ruleRows } : {}),
         matchPath,
-        matchTarget: (canonicalKey, lexicalView, opts) => matchTargetOver(segmentPath, ruleRows, "read", canonicalKey, lexicalView, opts),
+        matchTarget: (canonicalKey, lexicalView, opts) => denyTableHit(tableRows, denyTargetViews(canonicalKey, lexicalView, opts)),
         rgExclusionGlobs,
         rgProbeGlobs,
         unexcludableUnder,

package/dist/tools/fs/removal-targets.d.ts

@@ -5,17 +5,15 @@ import type { ToolCallRequest } from "../../core/tool-policy.js";
  *  recursive option (removing an empty home or the task root is still removing it). */
 export declare const SHELL_REMOVAL_COMMANDS: readonly ["rm", "rmdir"];
 export type ShellRemovalCommand = (typeof SHELL_REMOVAL_COMMANDS)[number];
-/** What makes a removal target dangerous, in the order a card names it. `runtime_script`: a shell's script text is built
- *  only when the command runs, and what it may run includes a removal nobody can read before it does. */
-export type DangerousRemovalKind = "filesystem_root" | "home" | "workspace" | "top_level" | "runtime_script";
+/** What makes a removal target dangerous, in the order a card names it. */
+export type DangerousRemovalKind = "filesystem_root" | "home" | "workspace" | "top_level";
 /** The protected locations a removal is judged against. `homes`: the environment's declared home and every other spelling
  *  of it (its canonical one); `workspace`: the task root, the working directory, the additional working directories. */
 export interface RemovalSeat {
     readonly homes: readonly string[];
     readonly workspace: readonly string[];
 }
-/** One dangerous removal a command makes: the program (the removal program, or the shell a runtime-built script is handed
- *  to), the operand as written, the target as established (the script word as written, for `runtime_script`). */
+/** One dangerous removal a command makes: the removal program, the operand as written, the target as established. */
 export interface DangerousRemoval {
     readonly kind: DangerousRemovalKind;
     readonly program: string;
@@ -30,33 +28,64 @@ export interface DangerousRemoval {
  * directory (one segment below the root). `undefined` for a relative path or any other target.
  */
 export declare function dangerousRemovalOf(path: string, seat: RemovalSeat): DangerousRemovalKind | undefined;
-/** What one removal finding asks: a protected location (`dangerous_delete`), or a target the command builds from a value
- *  of its own that the guard cannot read (`unverifiable_delete`). */
+/** What one removal finding asks: a protected location (`dangerous_delete`; `untrackedFrom` — the segment the working
+ *  directory stops being tracked at, where the target is relative and was judged where the text stood then); a recursive
+ *  forced removal whose target the
+ *  guard cannot verify (`unverifiable_delete`) — an operand the shell rewrites from a value the plan does not settle
+ *  (`rewritten`), the operands of a removal its argv stream fills in (`stream`), or an operand relative to the directory a
+ *  launcher option moved the removal into (`relocated`); or a shell handed text the engine cannot read
+ *  (`unverifiable_shell_text`) — a text a program produces (`produced`: what a pipe or a `<(…)` carries, an argv a stream
+ *  fills in, a substitution), or a text nobody read (`unread`: one the lexer could not read at all, {@link unreadPlan}, or a
+ *  segment whose program the walk could not name, {@link programUnread}). */
 export type RemovalFinding = (DangerousRemoval & {
     readonly guard: "dangerous_delete";
+    readonly untrackedFrom?: string;
 }) | {
     readonly guard: "unverifiable_delete";
     readonly program: string;
     readonly operand: string;
-    readonly name: string;
+    readonly source: "rewritten" | "stream" | "relocated";
+} | {
+    readonly guard: "unverifiable_shell_text";
+    readonly program: string;
+    readonly text: string;
+    readonly source: "produced" | "unread";
 };
+/**
+ * The names a removal target may be built on and still be verified: a root the SHELL provides, never one a command's
+ * output fed — `rm -rf "$TMPDIR"/<literal path below it>` is not asked about. `TMPDIR` is the reference's carve-out (its
+ * rule exempts "a well-known-safe temp pattern"); `HOME` is sema's (a registered divergence, looser than the reference,
+ * whose rule names `$HOME` as the blast radius: it is a root the shell provides too). A declared home is read by the
+ * value table itself — `$HOME` is then its value, and the target is judged where it lands; `PWD` is no root of this kind:
+ * its value is where the working-directory thread says the command stands.
+ */
+export declare const KNOWN_SAFE_ROOTS: readonly string[];
 /**
  * The removal findings of an established plan — ONE walk, nested plans included (a `bash -c` / `sh -c` text, a substitution
  * body), two words. For every `rm` / `rmdir` segment, each of its OPERANDS (every write target that is not one of its
  * option words: a word some implementation's reading of the program's row writes, {@link writeReadings}) as the plan
  * established it on the WRITE face (the entry the program unlinks, and the deny-floor shadow of a home word the plan did
- * not place) is judged by {@link dangerousRemovalOf}; an operand the plan could not place that expands a name the command
- * itself binds is judged in every spelling those bindings give it ({@link boundSpellingsOf}), and one with a binding this
- * reading cannot read is an unverifiable target (a recursive forced removal, {@link recursiveForce}). A shell handed a
- * script built only when the command runs is a dangerous removal of its own ({@link runtimeScriptOf}). The read-face copy
- * of an operand is not judged: it follows a link the removal does not follow.
+ * not place) is judged by {@link dangerousRemovalOf}. In a recursive forced removal ({@link recursiveForce}), an operand
+ * the shell rewrites from a value the plan's table does not settle — a name with no value here or one set in a form the
+ * table cannot read, a substitution, a parameter operator, a positional parameter — is an unverifiable target, save a
+ * literal path below a known-safe root the shell still provides there ({@link belowKnownSafeRoot}); so are the operands
+ * of a removal its argv stream fills in (`… | xargs rm -rf`), and an operand the plan cannot place — in a removal a
+ * launcher moved into another base, or in text such a removal hands a shell (`env -C <dir> rm -rf build`). A relative
+ * operand past a directory move the working-directory thread cannot follow is judged where the text stood when it lost
+ * track (the reference resolves it against the original working directory: KL-1403-b), and a card it earns says so. A `read` fills its name from the input: a value
+ * the table does not settle (stricter than the reference, whose rule counts `read VAR` as an in-window assignment). A
+ * name the table settles is its value, so `D=./build; rm -rf "$D/../build"` is judged
+ * where it lands, as `rm -rf ./build` is. A shell handed a text the engine cannot read — one a program produces
+ * ({@link runtimeScriptOf}), or one nobody read ({@link unreadPlan}, {@link programUnread}) — is an unreadable text of its
+ * own. The read-face copy of an operand is not judged: it follows a link the removal does not follow.
  */
-export declare function removalFindingsOf(established: EstablishedPlan, seat: RemovalSeat): RemovalFinding[];
-/** Does any segment of this plan (nested plans included) run a removal program, or hand a shell a script built when it
- *  runs? The guard establishes nothing for a command that does neither. */
+export declare function removalFindingsOf(established: EstablishedPlan, seat: RemovalSeat, safeRoots?: readonly string[], enclosingRelocated?: boolean): RemovalFinding[];
+/** Does this plan (nested plans included) run a removal program, hand a shell a script built when it runs, or hold text
+ *  nobody could read ({@link unreadPlan}, {@link programUnread})? The guard establishes nothing for a command that does none. */
 export declare function planRunsRemoval(plan: EstablishedPlan["plan"]): boolean;
 /** What the removal guard asks for one command: the guard word and its sentence's account — the first protected location
- *  (the program, the location, the target), else the first bound value the guard cannot read; `undefined` when neither. */
+ *  (the program, the location, the target), else the first target the guard cannot verify, else the first shell text the
+ *  engine cannot read; `undefined` when none. */
 export interface RemovalVerdict {
     readonly guard: RemovalFinding["guard"];
     readonly text: string;
@@ -72,12 +101,16 @@ export interface RemovalGuardSeat {
     readonly additionalRoots?: () => readonly string[];
 }
 /**
- * The dangerous-removal READING of one command — undefined when no segment of it (nested shell text included) runs a
- * removal program, so a command that removes nothing costs the gate no suspension. Otherwise `judge` establishes the plan
- * the read station plans (the same planner, the same write-target reading) lexically against the request's `cwd` and the
- * seat's home, and — where an environment is seated — through its resolver too, and returns what either establishment
- * finds ({@link removalFindingsOf}: the protected-location word first, then the unverifiable one).
+ * The removal guard's READING of one command — undefined when no segment of it (nested shell text included) runs a
+ * removal program or hands a shell a script built when it runs, and every text in it was read, so a command that removes
+ * nothing costs the gate no suspension (a text the lexer could not read is not one: bash may run the lines before its
+ * syntax error, and the guard reads no prefix of it). Otherwise `judge` establishes the plan the read
+ * station plans (the same planner, the same value table, the same write-target reading) lexically against the request's
+ * `cwd` and the seat's home, and — where an environment is seated — through its resolver too, and returns what either
+ * establishment finds ({@link removalFindingsOf}: the protected-location word first, then the unverifiable target, then the
+ * unreadable text).
+ * `safeRoots`: the known-safe roots ({@link KNOWN_SAFE_ROOTS}, with a deployment's own added by the policy).
  */
-export declare function removalReadingOf(command: string, req: Pick<ToolCallRequest, "cwd" | "root">, seat: RemovalGuardSeat | undefined): {
+export declare function removalReadingOf(command: string, req: Pick<ToolCallRequest, "cwd" | "root">, seat: RemovalGuardSeat | undefined, safeRoots?: readonly string[]): {
     judge(signal?: AbortSignal): Promise<RemovalVerdict | undefined>;
 } | undefined;