@sema-agent/core 5.31.0 → 5.33.0

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

@@ -95,9 +95,15 @@ export interface BashReadonlyRootBoundary {
      *  demotes the command (ask, never auto-allow), independently of the roots — in-root operands are
      *  judged too. Returns the matched pattern, or null. TWO named residuals, both inherited from this
      *  classifier's declared purity (synchronous, zero I/O — RB-448/RB-451 state the same scope for the
-     *  containment half): ① operand TARGET matching only — no ancestor intersection, so `grep -r x ~/`
-     *  whose operand is `~` itself does not demote here (§3.4; the recursive reach residual belongs to
-     *  the full-bash lane's honest scope note); ② LEXICAL only — an in-root symlink whose target is a
+     *  containment half): ① operand TARGET matching only — no ancestor intersection: the judge sees
+     *  the operand's own resolved spelling, never its subtree. The RECURSIVE-reach half of that
+     *  residual has since been narrowed (backlog #222): a listed recursive/expanding verb's path
+     *  operand under this wired seat rides {@link CompoundReadonlyVerdict.recursiveReadPaths}
+     *  (⊂ undecidedPaths), so `grep -r x ~/` no longer auto-allows — it demotes to ask through the
+     *  undecided contract. What REMAINS of ① is the form table's stated open set (see the KNOWN OPEN
+     *  SET note at {@link RECURSIVE_READ_FORMS}: a traversal verb absent there that a deployment
+     *  allowlists classifies by its ordinary form and can auto-run a traversal unjudged);
+     *  ② LEXICAL only — an in-root symlink whose target is a
      *  guarded path reads as its innocent spelling here, exactly as it does for the containment half
      *  (the enforcing/canonicalizing recheck is the bash_readonly leg's job via checkedPaths; the
      *  classify auto-allow lane has no I/O seat by contract). The structured read faces judge BOTH

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

@@ -109,6 +109,7 @@ function foldQuoteRemovalToken(tok) {
     }
     return out;
 }
+const POLL_LOOP_CAUSE_MAX_PATHS = 3;
 export function formatOutOfRootReadApprovalOption(directory) {
     const trimmed = directory.replace(/[/\\]+$/, "");
     const cut = Math.max(trimmed.lastIndexOf("/"), trimmed.lastIndexOf("\\"));
@@ -843,7 +844,9 @@ export function classifyBoundedReadonlyPollLoop(command, allow, boundary) {
     if (verdict.reason !== undefined)
         return verdict.reason;
     if (verdict.recursiveReadPaths !== undefined) {
-        return `the loop body reads recursively from ${verdict.recursiveReadPaths.join(", ")} — the traversal's reach is not covered by this lexical check, so it is not auto-allowed`;
+        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` : ""}`;
     }
     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`;

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

@@ -1,6 +1,7 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type CwdRef } from "./fs-shared.js";
+import type { ReversibilityVerdict } from "../../core/types.js";
 import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
 /**
  * design/80 D-2 (part-1): a parsed-command classifier for the `bash` tool, exposed as a
@@ -36,10 +37,25 @@ import { type BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
  * allowlisted readers + literal `sleep`, the same read boundary, everything else banned; the full
  * safety argument lives on that function). Additive by construction: the plain verdict is tried
  * first and is never overridden.
+ *
+ * backlog #239 — the RECURSIVE-READ demotion returns a STRUCTURED cause alongside the verdict. That
+ * demotion is the one arm whose reason is genuinely unrecoverable downstream: a recursive read is
+ * refused for what the traversal REACHES, and the reached set is by definition not in the command text
+ * an approval card shows. The cause is minted from the SAME classification pass that produced the
+ * verdict, so nothing re-parses the command to recover it.
+ *
+ * It is a `cause` (code + operand arrays), not a `reason` sentence, and that is a correction rather than
+ * a preference: every sentence tried here was true of one call and false of another — "a recursive read
+ * of X" is false for the zero-operand over-fire, "operand the check treated as a root" is false when the
+ * check SYNTHESIZES the root, and any of them, flattened into one length-capped string, silently dropped
+ * whichever family sorted last. The consumer now writes the sentence, from a code that cannot go stale
+ * and arrays that cannot be truncated into a lie.
+ *
+ * The other non-reversible arms stay bare on purpose — their cause is legible in the command itself (a
+ * write verb, a pipe, an unlisted name), and manufacturing an account for them would put text on a card
+ * that adds nothing the reader cannot already see.
  */
-export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => {
-    reversible: boolean;
-};
+export declare function bashReversibilityProbe(allow?: readonly string[], boundary?: BashReadonlyRootBoundary | (() => BashReadonlyRootBoundary | undefined)): (args: unknown) => ReversibilityVerdict;
 /**
  * design/199 D-6 — the FULL shell's contract id, single-sourced: both shell faces share the wire
  * name "Bash", so this id is the ONE structural discriminator between the write-capable shell and

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

@@ -10,7 +10,18 @@ import { imageMagicMatches, withinAnyRoot } from "./safety.js";
 import { isRemoteExecutionEnv, hasDestroy, isIsolated } from "../../core/remote-env.js";
 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 } from "../../core/checkpoint-store.js";
+import { inlineUntrusted } from "../../core/untrusted-text.js";
 import { BASH_READONLY_DEFAULT_ALLOW, coarseReadonlyCheck, classifyBoundedReadonlyPollLoop, classifyCompoundReadonlyDetailed, classifySimpleCommandReadBoundary, NOT_AUTO_ALLOWED, } from "./bash-readonly-classifier.js";
+const RECURSIVE_CAUSE_MAX_PATHS = 3;
+const RECURSIVE_READ_CAUSE_CODE = "shell.recursive_read_unbounded";
+function operandFamily(paths) {
+    const enc = (s) => s.replace(/%/g, "%25").replace(/;/g, "%3B").replace(/:/g, "%3A");
+    return {
+        shown: paths.slice(0, RECURSIVE_CAUSE_MAX_PATHS).map((p) => enc(inlineUntrusted(p, PROBE_CAUSE_PATH_MAX))),
+        total: paths.length,
+    };
+}
 export function bashReversibilityProbe(allow, boundary) {
     const allowSet = new Set(allow ?? BASH_READONLY_DEFAULT_ALLOW);
     return (args) => {
@@ -23,8 +34,22 @@ export function bashReversibilityProbe(allow, boundary) {
         const resolved = typeof boundary === "function" ? boundary() : boundary;
         const detailed = classifyCompoundReadonlyDetailed(command, allowSet, resolved);
         if (detailed.reason === undefined) {
-            if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0)
+            if (detailed.undecidedPaths !== undefined && detailed.undecidedPaths.length > 0) {
+                const recursive = detailed.recursiveReadPaths;
+                if (recursive !== undefined && recursive.length > 0) {
+                    const recursiveSet = new Set(recursive);
+                    const others = detailed.undecidedPaths.filter((p) => !recursiveSet.has(p));
+                    return {
+                        reversible: false,
+                        cause: {
+                            code: RECURSIVE_READ_CAUSE_CODE,
+                            roots: operandFamily(recursive),
+                            ...(others.length > 0 ? { further: operandFamily(others) } : {}),
+                        },
+                    };
+                }
                 return { reversible: false };
+            }
             return { reversible: true };
         }
         return { reversible: classifyBoundedReadonlyPollLoop(command, allowSet, resolved) === undefined };

package/dist/tools/fs/index.d.ts

@@ -1,5 +1,5 @@
 import type { AgentTool, ExecutionEnv } from "../../internal/harness-types.js";
-import type { BeforeWriteHook } from "../../core/types.js";
+import { type BeforeWriteHook } from "../../core/types.js";
 import { type TaskRegistry } from "../../core/task-registry.js";
 import { type ReadFileState } from "./safety.js";
 import type { PdfModelCapabilities } from "./pdf.js";
@@ -120,18 +120,38 @@ export interface HandsToolkitOptions {
     monitorToolActive?: boolean;
     /** design/199 件B — ADDITIONS to the built-in sensitive-path READ deny set
      *  ({@link import("./read-deny.js").READ_FACE_DEFAULT_DENY_ENTRIES}), judged by the structured read
-     *  faces (Read/Grep/Glob/RepoMap and their traversals) in BOTH containment modes. Add-only at every
-     *  layer (D-4 zero-shrink ruling): the built-ins are always in force, `[]` ≡ absent (union
-     *  identity), and there is no replacement escape hatch. Bad entry shapes throw at wiring time
-     *  (#123). The write faces are untouched (their guard is createSensitivePathPolicy). */
+     *  faces (Read/Grep/Glob/RepoMap and their traversals) in BOTH containment modes. Add-only:
+     *  additions union with the active built-ins, `[]` ≡ absent (union identity), and additions can
+     *  never remove a built-in — the one removal channel is the deployment's built-in configuration
+     *  ({@link readDenyBuiltinTiers} / {@link readDenyBuiltinExclude}, #245 revision of D-4). Bad entry
+     *  shapes throw at wiring time (#123). The write faces are untouched (their guard is
+     *  createSensitivePathPolicy). */
     readDenyPatterns?: readonly ReadDenyEntry[];
+    /** #245 — the deployment's built-in-table TIER selection ({@link import("./read-deny.js").ReadDenyBuiltinConfig}
+     *  `tiers` key): EXACTLY the listed tiers of {@link import("./read-deny.js").READ_FACE_BUILTIN_DENY_TABLE}
+     *  are active (`[]` = none — explicit and legal); absent = the default selection
+     *  ({@link import("./read-deny.js").READ_DENY_DEFAULT_TIERS} — every tier except `shell-history`).
+     *  Composes with {@link readDenyBuiltinExclude} (tier selection first, then row removal) and never
+     *  touches the additions seats. Unknown tier names throw at wiring time (#123). Deployment seat
+     *  ONLY — deliberately not a TaskSpec key, so no task can widen below its deployment. */
+    readDenyBuiltinTiers?: readonly string[];
+    /** #245 — per-row removal from the built-in table by STABLE NAME (= the row's canonical pattern
+     *  text, e.g. `".ssh"`, `".config/gcloud"`), applied after {@link readDenyBuiltinTiers} selection.
+     *  Naming a row of an inactive tier is a satisfied intent (no-op); a name matching NO table row
+     *  throws at wiring time (#123 — never silently ignored). Deployment seat ONLY, same clamp
+     *  argument as the tiers key. */
+    readDenyBuiltinExclude?: readonly string[];
     /** design/199 件A — the READ-face containment state for the structured read faces
      *  ({@link import("./read-face.js").ReadFace}; resolved through the SAME
      *  {@link import("./read-face.js").resolveReadFace} order prepare-task uses). Absent ⇒ the
      *  resolution order's default = "roots" (D-1b: the engine never opens implicitly). "open" skips
      *  ONLY the roots containment judgment — the deny set, the UNC out-of-set refusal and the
-     *  special-file type gates run in both faces (§2.0). Refused loudly beside `readOnly: true`
-     *  (the verifier mount's containment is load-bearing). Never affects the write faces. */
+     *  special-file type gates run in both faces (§2.0). Beside `readOnly: true` the mount wins:
+     *  this seat is deps-shaped (a deployment default, not a per-call assertion), so its "open"
+     *  CLAMPS to "roots" and the clamp is ANNOUNCED (`config.read_face_deployment_clamped`, through
+     *  `onNotice` / `console.warn`) — the loud refusal belongs to the TASK seat (`TaskSpec.readFace`),
+     *  which is the one genuine per-call contradiction (#237; stale "refused loudly" wording here
+     *  predated the 96ef89d seat distinction). Never affects the write faces. */
     readFace?: "open" | "roots";
 }
 /**

package/dist/tools/fs/index.js

@@ -1,3 +1,4 @@
+import { deliverEngineNotice } from "../../core/types.js";
 import { createTaskOutputTool, createTaskStopTool } from "../../core/task-registry.js";
 import { hasBackgroundShell } from "../../core/background-shell.js";
 import {} from "./safety.js";
@@ -12,7 +13,7 @@ export * from "./fs-bash.js";
 export * from "./read-deny.js";
 import { BASH_READONLY_DEFAULT_ALLOW, } from "./bash-readonly-classifier.js";
 import { compileReadDeny } from "./read-deny.js";
-import { resolveReadFace } from "./read-face.js";
+import { deploymentReadFaceClampNotice, resolveReadFace } from "./read-face.js";
 export * from "./read-face.js";
 import {} from "./fs-shared.js";
 import { createReadFileTool } from "./fs-read.js";
@@ -33,12 +34,16 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
             scope: c.principal ?? opts.taskScope,
             ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
         }, env);
-    const readDeny = compileReadDeny(opts.readDenyPatterns ?? [], "HandsToolkitOptions.readDenyPatterns");
+    const readDeny = compileReadDeny(opts.readDenyPatterns ?? [], "HandsToolkitOptions.readDenyPatterns", {
+        ...(opts.readDenyBuiltinTiers !== undefined ? { tiers: opts.readDenyBuiltinTiers } : {}),
+        ...(opts.readDenyBuiltinExclude !== undefined ? { exclude: opts.readDenyBuiltinExclude } : {}),
+    });
     const readFace = resolveReadFace({
         depsReadFace: opts.readFace,
         readOnlyMount: readOnly,
         orgGoverned: false,
         fullShellReachable: includeShell && !readOnly,
+        onDeploymentClamp: () => deliverEngineNotice(opts.onNotice, deploymentReadFaceClampNotice()),
     });
     const tools = [
         createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace),

package/dist/tools/fs/read-deny.d.ts

@@ -52,9 +52,30 @@ export interface ReadDenyMatcher {
     readonly rgProbeGlobs: readonly ReadDenyRgGlob[];
 }
 /**
- * READ_FACE_DEFAULT_DENY_ENTRIES — the built-in table (D-4 ruling: ONE tier, credential-class path
- * families; the design's `outside_workspace` tier was ruled OUT, and the dotenv family is deliberately
- * NOT here — workspace `.env` files are working material for the tasks this engine runs).
+ * The closed set of built-in tiers (#245). A tier is the deployment's selection unit
+ * ({@link ReadDenyBuiltinConfig.tiers}); every {@link READ_FACE_BUILTIN_DENY_TABLE} row belongs to
+ * exactly one. Unknown tier names refuse loudly (#123) — this array is the validation source and the
+ * admin-face vocabulary, never re-spelled downstream.
+ */
+export declare const READ_DENY_BUILTIN_TIERS: readonly ["credentials", "shell-history", "browser", "wallet"];
+/** One member of {@link READ_DENY_BUILTIN_TIERS}. */
+export type ReadDenyBuiltinTier = (typeof READ_DENY_BUILTIN_TIERS)[number];
+/**
+ * One row of the built-in table: the canonical deny pattern (also the row's STABLE NAME — the
+ * `readDenyBuiltinExclude` key; renaming a pattern is a semantic change and deliberately invalidates
+ * configs naming the old spelling, loudly) and the tier it belongs to.
+ */
+export interface ReadDenyBuiltinRow {
+    readonly pattern: string;
+    readonly tier: ReadDenyBuiltinTier;
+}
+/**
+ * READ_FACE_BUILTIN_DENY_TABLE — the FULL built-in table with tier metadata (#245: the material
+ * basis of the deployment admin face — what an org administrator "sees" before selecting tiers /
+ * excluding rows). Activation is a separate fact: the default face is the table under
+ * {@link READ_DENY_DEFAULT_TIERS} (shell-history rows exist here but are OFF by default).
+ * The dotenv family is deliberately NOT here — workspace `.env` files are working material for the
+ * tasks this engine runs (the design's `outside_workspace` tier was also ruled OUT).
  *
  * Each row states its tradeoff. Rows are matched as segment runs anywhere in the path, so a repo
  * fixture spelled `fixtures/.ssh/id_rsa` is refused too — deliberate: the refusal names the pattern,
@@ -67,6 +88,39 @@ export interface ReadDenyMatcher {
  * `.mcp.json` (agent config is routinely read for debugging); the engine's own data root
  * (transcript integrity policy owns it with an ask on the write face).
  */
+export declare const READ_FACE_BUILTIN_DENY_TABLE: readonly ReadDenyBuiltinRow[];
+/**
+ * The DEFAULT tier selection (#245 ruling ②): every tier EXCEPT `shell-history` — history files are
+ * unrestricted unless a deployment opts the tier in. Derived, not re-listed: a future tier added to
+ * the closed set is default-ON unless this expression is deliberately revisited.
+ */
+export declare const READ_DENY_DEFAULT_TIERS: readonly ReadDenyBuiltinTier[];
+/**
+ * The deployment's built-in-table configuration (#245 — deployment seat ONLY: RunnerDeps /
+ * HandsToolkitOptions; deliberately NOT a TaskSpec key and NOT in the governed workflow whitelist,
+ * so no task or governed script can widen below its deployment).
+ *  - `tiers` — EXACTLY-these tier selection: listed tiers are active, unlisted ones are not
+ *    (`[]` = no built-in tiers at all — an explicit, legal posture; absent = {@link READ_DENY_DEFAULT_TIERS}).
+ *  - `exclude` — per-row removal by canonical pattern name, applied AFTER tier selection.
+ * Unknown tier names / unknown row names refuse loudly (#123) — never silently ignored.
+ */
+export interface ReadDenyBuiltinConfig {
+    tiers?: readonly string[];
+    exclude?: readonly string[];
+}
+/**
+ * Resolve the ACTIVE built-in rows under a deployment configuration (validated, loud — #123's three
+ * bad-value states all throw: garbage shapes, unknown tier names, unknown row names). The one
+ * resolution used by {@link compileReadDeny}; exported so an admin face can preview the effective
+ * table under a candidate configuration with the engine's own rules.
+ */
+export declare function resolveReadDenyBuiltins(config?: ReadDenyBuiltinConfig): readonly ReadDenyBuiltinRow[];
+/**
+ * READ_FACE_DEFAULT_DENY_ENTRIES — the DEFAULT-ACTIVE built-in set: {@link READ_FACE_BUILTIN_DENY_TABLE}
+ * under {@link READ_DENY_DEFAULT_TIERS} (#245: shell-history rows are in the table, not in this face).
+ * Kept as the historical name for consumers rendering "what does an unconfigured deployment refuse";
+ * the tier-annotated table is the admin-face export.
+ */
 export declare const READ_FACE_DEFAULT_DENY_ENTRIES: readonly ReadDenyEntry[];
 /** A compiled segment-run pattern (shared engine — the write guard delegates here too). */
 export interface CompiledSegmentPattern {
@@ -102,9 +156,13 @@ export declare function matchSegmentPatterns(path: string, compiled: readonly Co
  */
 export declare function persistedReadDenyEntryProblem(e: unknown): string | null;
 /**
- * Compile the read-face deny judge: built-in table ∪ additions (add-only at every layer — D-4
- * zero-shrink; `[]` additions ≡ absent, deliberately a no-op rather than a refusal: an array API
- * cannot observe a "replace" intent, and union-with-empty is the identity, not a silent fallback).
- * Bad entry shapes / zero-segment patterns throw loudly, naming the layer (#123).
+ * Compile the read-face deny judge: ACTIVE built-in rows ∪ additions. Additions are add-only at every
+ * task layer (`[]` additions ≡ absent, deliberately a no-op rather than a refusal: an array API
+ * cannot observe a "replace" intent, and union-with-empty is the identity, not a silent fallback);
+ * the built-in half is selected by the DEPLOYMENT's `builtin` config (#245 — absent = the default
+ * tier selection, see {@link resolveReadDenyBuiltins}). A deployment that turned a tier off can still
+ * re-add single patterns through the additions seats — they then ride as ordinary additions.
+ * Bad entry shapes / zero-segment patterns / unknown tier or row names throw loudly, naming the
+ * layer or knob (#123).
  */
-export declare function compileReadDeny(additions?: readonly ReadDenyEntry[], layer?: string): ReadDenyMatcher;
+export declare function compileReadDeny(additions?: readonly ReadDenyEntry[], layer?: string, builtin?: ReadDenyBuiltinConfig): ReadDenyMatcher;

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

@@ -1,40 +1,76 @@
-export const READ_FACE_DEFAULT_DENY_ENTRIES = [
-    ".ssh",
-    "id_rsa*",
-    "id_ed25519*",
-    "id_ecdsa*",
-    ".gnupg",
-    ".aws",
-    ".config/gcloud",
-    ".azure",
-    ".kube",
-    ".netrc",
-    "_netrc",
-    ".git-credentials",
-    ".docker/config.json",
-    ".config/gh",
-    ".npmrc",
-    ".pypirc",
-    ".local/share/keyrings",
-    "Library/Keychains",
-    ".bash_history",
-    ".zsh_history",
-    "Library/Application Support/Google/Chrome",
-    "Library/Application Support/Firefox",
-    "Library/Safari",
-    ".config/google-chrome",
-    ".config/chromium",
-    ".mozilla/firefox",
-    "AppData/Local/Google/Chrome/User Data",
-    "AppData/Local/Microsoft/Edge/User Data",
-    "AppData/Roaming/Mozilla/Firefox",
-    ".bitcoin",
-    ".ethereum",
-    ".electrum",
-    "Library/Application Support/Exodus",
-    "Library/Application Support/Ledger Live",
-    "wallet.dat",
+export const READ_DENY_BUILTIN_TIERS = ["credentials", "shell-history", "browser", "wallet"];
+export const READ_FACE_BUILTIN_DENY_TABLE = [
+    { pattern: ".ssh", tier: "credentials" },
+    { pattern: "id_rsa*", tier: "credentials" },
+    { pattern: "id_ed25519*", tier: "credentials" },
+    { pattern: "id_ecdsa*", tier: "credentials" },
+    { pattern: ".gnupg", tier: "credentials" },
+    { pattern: ".aws", tier: "credentials" },
+    { pattern: ".config/gcloud", tier: "credentials" },
+    { pattern: ".azure", tier: "credentials" },
+    { pattern: ".kube", tier: "credentials" },
+    { pattern: ".netrc", tier: "credentials" },
+    { pattern: "_netrc", tier: "credentials" },
+    { pattern: ".git-credentials", tier: "credentials" },
+    { pattern: ".docker/config.json", tier: "credentials" },
+    { pattern: ".config/gh", tier: "credentials" },
+    { pattern: ".npmrc", tier: "credentials" },
+    { pattern: ".pypirc", tier: "credentials" },
+    { pattern: ".local/share/keyrings", tier: "credentials" },
+    { pattern: "Library/Keychains", tier: "credentials" },
+    { pattern: ".bash_history", tier: "shell-history" },
+    { pattern: ".zsh_history", tier: "shell-history" },
+    { pattern: "Library/Application Support/Google/Chrome", tier: "browser" },
+    { pattern: "Library/Application Support/Firefox", tier: "browser" },
+    { pattern: "Library/Safari", tier: "browser" },
+    { pattern: ".config/google-chrome", tier: "browser" },
+    { pattern: ".config/chromium", tier: "browser" },
+    { pattern: ".mozilla/firefox", tier: "browser" },
+    { pattern: "AppData/Local/Google/Chrome/User Data", tier: "browser" },
+    { pattern: "AppData/Local/Microsoft/Edge/User Data", tier: "browser" },
+    { pattern: "AppData/Roaming/Mozilla/Firefox", tier: "browser" },
+    { pattern: ".bitcoin", tier: "wallet" },
+    { pattern: ".ethereum", tier: "wallet" },
+    { pattern: ".electrum", tier: "wallet" },
+    { pattern: "Library/Application Support/Exodus", tier: "wallet" },
+    { pattern: "Library/Application Support/Ledger Live", tier: "wallet" },
+    { pattern: "wallet.dat", tier: "wallet" },
 ];
+export const READ_DENY_DEFAULT_TIERS = READ_DENY_BUILTIN_TIERS.filter((t) => t !== "shell-history");
+export function resolveReadDenyBuiltins(config) {
+    let activeTiers;
+    if (config?.tiers === undefined) {
+        activeTiers = new Set(READ_DENY_DEFAULT_TIERS);
+    }
+    else {
+        if (!Array.isArray(config.tiers)) {
+            throw new Error(`readDenyBuiltinTiers: expected an array of tier names, got ${JSON.stringify(config.tiers)}.`);
+        }
+        for (const t of config.tiers) {
+            if (typeof t !== "string" || !READ_DENY_BUILTIN_TIERS.includes(t)) {
+                throw new Error(`readDenyBuiltinTiers: unknown tier ${JSON.stringify(t)} — known tiers: ${READ_DENY_BUILTIN_TIERS.join(", ")}.`);
+            }
+        }
+        activeTiers = new Set(config.tiers);
+    }
+    let excluded;
+    if (config?.exclude === undefined) {
+        excluded = new Set();
+    }
+    else {
+        if (!Array.isArray(config.exclude)) {
+            throw new Error(`readDenyBuiltinExclude: expected an array of built-in row names (canonical pattern texts), got ${JSON.stringify(config.exclude)}.`);
+        }
+        for (const name of config.exclude) {
+            if (typeof name !== "string" || !READ_FACE_BUILTIN_DENY_TABLE.some((r) => r.pattern === name)) {
+                throw new Error(`readDenyBuiltinExclude: ${JSON.stringify(name)} names no built-in row — row names are the canonical pattern texts of READ_FACE_BUILTIN_DENY_TABLE (e.g. ".ssh", ".config/gcloud").`);
+            }
+        }
+        excluded = new Set(config.exclude);
+    }
+    return READ_FACE_BUILTIN_DENY_TABLE.filter((r) => activeTiers.has(r.tier) && !excluded.has(r.pattern));
+}
+export const READ_FACE_DEFAULT_DENY_ENTRIES = resolveReadDenyBuiltins().map((r) => r.pattern);
 function asciiLower(s) {
     let out = "";
     for (let i = 0; i < s.length; i++) {
@@ -107,7 +143,7 @@ export function persistedReadDenyEntryProblem(e) {
         return "pattern is not in canonical a/b form";
     return null;
 }
-export function compileReadDeny(additions = [], layer = "additions") {
+export function compileReadDeny(additions = [], layer = "additions", builtin) {
     const normalized = [];
     const seen = new Set();
     const push = (e) => {
@@ -117,8 +153,8 @@ export function compileReadDeny(additions = [], layer = "additions") {
         seen.add(key);
         normalized.push(e);
     };
-    for (const entry of READ_FACE_DEFAULT_DENY_ENTRIES)
-        push(normalizeEntry(entry, "built-in"));
+    for (const row of resolveReadDenyBuiltins(builtin))
+        push(normalizeEntry(row.pattern, "built-in"));
     for (const entry of additions)
         push(normalizeEntry(entry, layer));
     const compiled = normalized.map((e) => {

package/dist/tools/fs/read-face.d.ts

@@ -5,8 +5,9 @@ export type ReadFace = "open" | "roots";
 /** Loud value gate (#123): a `readFace` seat carries exactly "open" | "roots" — anything else
  *  (case variants, truthy garbage) refuses at wiring time, never folds to a default. Exported
  *  module-internally (not on the package surface) so prepare's unconditional config-guard leg can
- *  screen the seats on runs that never mount hands — the resolver only runs beside a mount, and a
- *  garbage value must not become silently legal on the hands-less path (5.30 re-review). */
+ *  screen the seats on runs that never mount hands early and unconditionally (since #242 the
+ *  resolver itself ALSO runs on every hands-less leg; this screen still fires first, so a garbage
+ *  value refuses before any leg-shape branching). */
 export declare function assertReadFaceValue(v: unknown, seat: string): ReadFace | undefined;
 /** Inputs to {@link resolveReadFace} — all structural/declaration facts, never permission modes
  *  (a deliberate axis separation: this shape carries facts, not verdicts). */
@@ -29,6 +30,13 @@ export interface ReadFaceInputs {
      *  "open"… no — see the resolution order: an EXPLICIT open still wins (row 4 is a default, not a
      *  clamp); what it changes is that NOTHING implicit opens a bash-less mount. */
     fullShellReachable: boolean;
+    /** #237 — observation hook for the ONE silent branch of the order: row 1's deployment-seat clamp
+     *  (readOnly mount + deps "open" + NO task seat). Fired exactly when the deps declaration was the
+     *  deciding seat and the mount overrode it — not when a task-level "roots" pinned the same value
+     *  anyway (the mount changed nothing there, and announcing it would claim a false cause), and
+     *  never on the throw rows (those are already loud). The resolver stays the single owner of the
+     *  clamp predicate; stations own delivery/dedup ({@link deploymentReadFaceClampNotice}). */
+    onDeploymentClamp?: () => void;
 }
 /**
  * The ONE resolution order (§2.2), first hit wins. prepare-task AND createHandsToolkit both call
@@ -47,3 +55,17 @@ export interface ReadFaceInputs {
  *  5. default: ROOTS (D-1b — the engine never opens implicitly).
  */
 export declare function resolveReadFace(i: ReadFaceInputs): ReadFace;
+/**
+ * #237 — the ONE text of the deployment-clamp announcement (`config.read_face_deployment_clamped`).
+ * Both stations deliver THIS object through their own `deliverEngineNotice` call (prepare-task with
+ * the `RunnerDeps.onNotice` seat, once per notice sink — the sink, not the deps object, because the
+ * Runner rebuilds its deps; `createHandsToolkit` with its band-local `HandsToolkitOptions.onNotice`
+ * seat — toolkit creation is itself the one-per-mount boot moment, and an absent seat prints the
+ * same line via `console.warn`). Built here, import-free, so the message can never fork between
+ * the stations.
+ */
+export declare function deploymentReadFaceClampNotice(): {
+    code: string;
+    message: string;
+    detail: Record<string, unknown>;
+};

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

@@ -16,6 +16,8 @@ export function resolveReadFace(i) {
             e.code = "config.read_face_readonly_conflict";
             throw e;
         }
+        if (deps === "open" && spec === undefined)
+            i.onDeploymentClamp?.();
         return "roots";
     }
     if (i.orgGoverned) {
@@ -36,3 +38,10 @@ export function resolveReadFace(i) {
         return "roots";
     return "roots";
 }
+export function deploymentReadFaceClampNotice() {
+    return {
+        code: "config.read_face_deployment_clamped",
+        message: `readFace (deployment seat): the deployment-wide "open" declaration is not in force on this read-only (verifier) mount — clamped to "roots" (stricter-wins: the mount's containment is load-bearing and never openable). Other mounts still honor "open".`,
+        detail: { seat: "readFace (deployment seat)", declared: "open", inForce: "roots", cause: "read_only_mount" },
+    };
+}

package/dist/tools/fs/search.js

@@ -1147,6 +1147,8 @@ async function rgDenyExistenceProbe(env, root, deny, target, signal) {
             return { kind: "probe_failed" };
         const first = res.value.stdout.split("\n").find((l) => l.trim().length > 0);
         if (first !== undefined) {
+            if (/^__RG_PROBE_EXIT_\d+$/.test(first.trim()))
+                return { kind: "probe_failed" };
             const hit = deny.matchPath(first.trim());
             return { kind: "existence", ...(hit !== null ? { patterns: [hit.pattern] } : {}) };
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "5.31.0",
+  "version": "5.33.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",