@sema-agent/core 7.33.7 → 7.34.0

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

@@ -0,0 +1,225 @@
+import { canonicalizeTarget, isAbsolutePathForm, joinForFamily, normalizeAbsPathLexically, pathFamilyOf } from "./safety.js";
+import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, withGateTimeout } from "../../core/gate-bounded-await.js";
+import { readDenyPatternRun, readDenyRunHead } from "./read-deny.js";
+export function declaredReadDenyHomes(env) {
+    const home = env.homeDir;
+    return home !== undefined && isAbsolutePathForm(home) ? [home] : [];
+}
+export async function readDenyHomesOf(env, signal) {
+    return (await readDenyHomesAnswered(env, signal)).homes;
+}
+async function readDenyHomesAnswered(env, signal) {
+    const home = declaredReadDenyHomes(env)[0];
+    if (home === undefined)
+        return { homes: [], whole: true };
+    const canonical = await env.canonicalPath(home, signal);
+    if (canonical.ok)
+        return { homes: canonical.value !== home ? [home, canonical.value] : [home], whole: true };
+    return { homes: [home], whole: canonical.error.code === "not_found" || canonical.error.code === "not_directory" };
+}
+export async function readDenyHomeLinksOf(env, entries, homes, signal) {
+    const rows = [];
+    const familyOf = new Map();
+    for (const { pattern, caseSensitive } of entries) {
+        const { homeAnchored, run } = readDenyPatternRun(pattern);
+        if (!homeAnchored)
+            continue;
+        const head = run.split("/").filter(Boolean).slice(0, readDenyRunHead(run)).join("/");
+        if (head.length === 0)
+            continue;
+        const spelled = homes.map((home) => {
+            const family = pathFamilyOf({ root: home });
+            const at = normalizeAbsPathLexically(joinForFamily(family, home, head));
+            familyOf.set(at, family);
+            return at;
+        });
+        rows.push({ pattern, caseSensitive: caseSensitive === true, spelled });
+    }
+    const resolved = new Map(await Promise.all([...familyOf].map(async ([at, family]) => [at, await whereItLeads(env, at, family, signal)])));
+    const out = new Map();
+    const whole = [...resolved.values()].every((location) => location !== undefined);
+    for (const { pattern, caseSensitive, spelled } of rows) {
+        const fold = (p) => (caseSensitive ? p : p.replace(/[A-Z]/g, (c) => c.toLowerCase()));
+        const own = new Set(spelled.map(fold));
+        const locations = [];
+        for (const at of spelled) {
+            const location = resolved.get(at);
+            if (location !== undefined && !own.has(fold(location)) && !locations.includes(location))
+                locations.push(location);
+        }
+        if (locations.length > 0)
+            out.set(pattern, locations);
+    }
+    return { linked: out, whole };
+}
+export async function whereItLeads(env, at, family = pathFamilyOf({ root: at }), signal) {
+    try {
+        const key = await canonicalizeTarget(env, at, signal, family);
+        return key.ok ? normalizeAbsPathLexically(key.key) : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export async function whereItsAnsweredPrefixLeads(env, at, family = pathFamilyOf({ root: at }), signal) {
+    const walk = async () => {
+        const rest = [];
+        for (let here = normalizeAbsPathLexically(at);;) {
+            const led = await whereItLeads(env, here, family, signal);
+            if (led !== undefined)
+                return rest.reduce((p, name) => joinForFamily(family, p, name), led);
+            const parent = normalizeAbsPathLexically(`${here}/..`);
+            if (parent === here)
+                return undefined;
+            rest.unshift(here.slice(parent.length).replace(/^[\\/]+/, ""));
+            here = parent;
+        }
+    };
+    return await withGateTimeout(walk(), DEFAULT_GATE_AWAIT_TIMEOUT_MS, signal, "ruleRowHead").catch(() => undefined);
+}
+export async function placeReadDenyAtHome(env, compile, homes, signal) {
+    let at = homes;
+    if (at === undefined) {
+        const answer = await withGateTimeout(readDenyHomesAnswered(env, signal), DEFAULT_GATE_AWAIT_TIMEOUT_MS, signal, "readDenyHomes");
+        if (!answer.whole)
+            return { matcher: compile([]), homes: [], linked: new Map(), whole: false };
+        at = answer.homes;
+    }
+    const atHomes = compile(at);
+    const { linked, whole } = await readDenyHomeLinksOf(env, atHomes.entries, at, signal);
+    return { matcher: linked.size === 0 ? atHomes : compile(at, linked), homes: at, linked, whole };
+}
+export function readDenyPlacedLater(unplaced, place) {
+    let current = unplaced;
+    let whole = false;
+    let pending;
+    const again = () => (pending ??= place()
+        .then((placed) => {
+        current = placed.matcher;
+        whole = placed.whole;
+    }, () => undefined)
+        .finally(() => {
+        pending = undefined;
+    }));
+    void again();
+    const ready = async () => {
+        if (pending !== undefined)
+            await pending;
+        if (!whole)
+            await again();
+    };
+    const matcher = {
+        get entries() {
+            return current.entries;
+        },
+        get ruleRows() {
+            return current.ruleRows;
+        },
+        matchPath: (path, opts) => current.matchPath(path, opts),
+        matchTarget: (canonicalKey, lexicalView, opts) => current.matchTarget(canonicalKey, lexicalView, opts),
+        get rgExclusionGlobs() {
+            return current.rgExclusionGlobs;
+        },
+        get rgProbeGlobs() {
+            return current.rgProbeGlobs;
+        },
+        unexcludableUnder: (scope) => current.unexcludableUnder?.(scope) ?? false,
+        rowAtOrBelow: (path) => current.rowAtOrBelow?.(path) ?? null,
+    };
+    return { matcher, ready };
+}
+const HOME_CHAINS = new WeakMap();
+function homeChainOf(env) {
+    const identity = env.fileIdentity;
+    const home = declaredReadDenyHomes(env)[0];
+    if (typeof identity !== "function" || home === undefined)
+        return undefined;
+    let perEnv = HOME_CHAINS.get(env);
+    if (perEnv === undefined)
+        HOME_CHAINS.set(env, (perEnv = new Map()));
+    const known = perEnv;
+    let chain = known.get(home);
+    if (chain === undefined) {
+        const reading = withGateTimeout((async () => {
+            const canonical = await env.canonicalPath(home);
+            if (!canonical.ok)
+                return { index: undefined, whole: false };
+            const out = new Map();
+            let whole = true;
+            for (let dir = normalizeAbsPathLexically(canonical.value);;) {
+                const id = await identityOf(env, identity, dir);
+                if (id?.ok === true) {
+                    if (!out.has(id.value))
+                        out.set(id.value, dir);
+                }
+                else
+                    whole = false;
+                const parent = normalizeAbsPathLexically(`${dir}/..`);
+                if (parent === dir)
+                    break;
+                dir = parent;
+            }
+            return { index: out.size > 0 ? out : undefined, whole };
+        })(), DEFAULT_GATE_AWAIT_TIMEOUT_MS, undefined, "homeChain").catch(() => ({ index: undefined, whole: false }));
+        chain = reading;
+        known.set(home, reading);
+        const drop = () => {
+            if (known.get(home) === reading)
+                known.delete(home);
+        };
+        void reading.then((c) => (c.whole ? undefined : drop()));
+    }
+    return chain.then((c) => c.index);
+}
+async function identityOf(env, identity, path, signal) {
+    try {
+        return await identity.call(env, path, signal);
+    }
+    catch {
+        return undefined;
+    }
+}
+export function homeViewsOf(env, signal) {
+    const chain = homeChainOf(env);
+    const identity = env.fileIdentity;
+    const views = new Map();
+    const viewOf = (path, leafIsFile) => {
+        const key = `${leafIsFile ? "f" : "d"}:${path}`;
+        let v = views.get(key);
+        if (v === undefined) {
+            v = (async () => {
+                const index = await chain;
+                if (index === undefined || typeof identity !== "function")
+                    return undefined;
+                if (!leafIsFile) {
+                    const id = await identityOf(env, identity, path, signal);
+                    if (id === undefined)
+                        return undefined;
+                    if (id.ok) {
+                        const at = index.get(id.value);
+                        if (at !== undefined)
+                            return at;
+                    }
+                    else if (id.error.code !== "not_found" && id.error.code !== "not_directory")
+                        return undefined;
+                }
+                const parent = normalizeAbsPathLexically(`${path}/..`);
+                if (parent === path)
+                    return undefined;
+                const up = await viewOf(parent, false);
+                return up === undefined ? undefined : joinForFamily(pathFamilyOf({ root: path }), up, path.slice(parent.length).replace(/^[\\/]+/, ""));
+            })();
+            views.set(key, v);
+        }
+        return v;
+    };
+    return {
+        async of(path, opts) {
+            if (chain === undefined || !isAbsolutePathForm(path))
+                return undefined;
+            const spelled = normalizeAbsPathLexically(path);
+            const view = await viewOf(spelled, opts?.leaf === "file");
+            return view === undefined || view === spelled ? undefined : view;
+        },
+    };
+}

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

@@ -1,7 +1,11 @@
 /**
  * One deny entry: a `/`-separated run of path SEGMENTS. `*` matches any run of non-separator
  * characters within one segment and is the ONLY metacharacter (everything else is literal). The run
- * may match ANYWHERE in the judged path (`.ssh` covers `~/.ssh/…` and any other `.ssh` directory).
+ * may match ANYWHERE in the judged path (`.ssh` covers `~/.ssh/…` and any other `.ssh` directory) —
+ * unless the pattern opens with the HOME word ({@link READ_DENY_HOME_WORD}): `~/<run>` matches only where
+ * the run starts right below the execution environment's home directory (`~/.sema/settings.json` is the
+ * home's file, never a project's `.sema/settings.json`). Only a FIRST segment that is exactly `~` is the
+ * word; `~user` and a `~` further along are literal segments.
  * String shorthand ≡ `{ pattern }`. Matching is ASCII-case-insensitive by default (a case-insensitive
  * filesystem serves `.SSH` and `.ssh` as the same directory); `caseSensitive: true` opts a single
  * entry out. Unicode normalization (NFC/NFD) and volume-level case semantics are NOT modeled (v1
@@ -12,6 +16,20 @@ export type ReadDenyEntry = string | {
     pattern: string;
     caseSensitive?: boolean;
 };
+/** The HOME word of the pattern grammar ({@link ReadDenyEntry}): a FIRST segment spelled exactly this anchors the run
+ *  right below the execution environment's home directory. */
+export declare const READ_DENY_HOME_WORD = "~";
+/** A pattern read as its anchor and its run: `~/a/b` ⇒ the run `a/b`, home-anchored; any other pattern ⇒ itself,
+ *  unanchored. The one reader of the home word — the compiler, the traversal globs, the classifier's rendering and the
+ *  write face's mirror all take the run from here. */
+export declare function readDenyPatternRun(pattern: string): {
+    readonly homeAnchored: boolean;
+    readonly run: string;
+};
+/** How many leading segments of a run are LITERAL — the run's head before the first segment carrying `*`. A home-anchored
+ *  row's head names one location below the home, which a mount resolves to where it really leads
+ *  ({@link compileReadDeny}'s `linked`); the segments after it are matched below that location as the run matches. */
+export declare function readDenyRunHead(run: string): number;
 /** The normalized (validated, defaulted) form of one entry. */
 export interface NormalizedReadDenyEntry {
     pattern: string;
@@ -26,6 +44,66 @@ export interface ReadDenyHit {
      *  sends the reader chasing a path the pattern does not match. */
     matchedView?: string;
 }
+/** The two faces of the deny table: what a READ must not reach, and what a WRITE must not reach. */
+export declare const DENY_FACES: readonly ["read", "write"];
+export type DenyFace = (typeof DENY_FACES)[number];
+/**
+ * A deny row in the rule DSL's PATH grammar — a `Read(<pattern>)` / `Edit(<pattern>)` deny rule, compiled by the
+ * rule compiler against its own bases (`createPermissionRulePolicy`). It joins the SAME table as the segment rows: one
+ * judge (`matchPath` / `matchTarget`), one refusal sentence, one classifier rendering — only the row's reach is the
+ * rule grammar's (the path it names and everything under a directory it names), not a segment run.
+ *  · `rule` — the rule as written, the row's name wherever a refusal or the classifier names it;
+ *  · `tool` / `pattern` — the rule's two parts, for a rendering that states the pattern inertly;
+ *  · `faces` — which faces the row guards (`Read` ⇒ read and write: a path whose reads are denied is not written
+ *    either; `Edit` ⇒ write);
+ *  · `reaches` — the rule compiler's own reach over an ABSOLUTE path.
+ */
+export interface PathRuleDenyRow {
+    readonly rule: string;
+    readonly tool: string;
+    readonly pattern: string;
+    readonly faces: readonly DenyFace[];
+    readonly reaches: (absolutePath: string) => boolean;
+    /** The row's HEAD — the absolute location its reach starts at (the rule model's `pathRuleHeadOf`: the pattern's
+     *  literal prefix under its base, a directory rule's directory), spelled so the execution environment can resolve it.
+     *  A leg judges the row where that location LEADS too ({@link withRuleRowsWhereTheyLead}). Absent on a hand-built
+     *  row, or one whose head cannot be read: it is judged as spelled. */
+    readonly head?: string;
+}
+/**
+ * The rule rows as a leg judges them: each row as spelled, and — for every location on the way to the row's HEAD (each
+ * leading part of it: the anchor's children down to the head itself) that the environment resolves to another spelling
+ * (a link or firmlink: `/tmp` → `/private/tmp`, `/var` → `/private/var`, a project root, a home entry or a directory
+ * inside the rule reached through a symlink) — the same row at that spelling: a path at or below the resolved location
+ * is judged as its spelling at or below that part. Every read and write face judges the CANONICAL key of a target beside
+ * its spelled view, so a row whose head is spelled through a link would otherwise never meet a target named by its real
+ * location — whether the row was written with the short spelling and the call with the long one, or the reverse. Every
+ * part, not the head alone: a link inside the rule's literal prefix that is re-pointed after the rows were placed still
+ * meets the row through the parts above it (`<real root>/alias/**` holds when `alias` moves). One rule for every row
+ * form (absolute, home, root, working directory, directory): the reference compiles the same "physical twin" of every
+ * deny / ask rule's literal prefix (cli280.js `ei` 9766583, compiled in `mt` 9767083). `leadsTo` is the leg's resolution,
+ * the one the faces mint their keys with (`undefined` = could not resolve: no twin there); each location is resolved
+ * once, and a part that only extends its parent's resolution adds no row.
+ */
+export declare function withRuleRowsWhereTheyLead(rows: readonly PathRuleDenyRow[], leadsTo: (head: string) => Promise<string | undefined>): Promise<PathRuleDenyRow[]>;
+/**
+ * The WRITE face of the deny table: the rule rows whose faces include `write` — the judge the shell station reads for a
+ * command's write targets (a redirection, `tee`, `sed -i`, `cp` / `mv` / `touch` / `mkdir` / `rm` operands). Same row
+ * type, same judgment (`ruleRowHit`) as the read face's rule rows; a hit names the row by its rule text.
+ */
+export interface WriteDenyMatcher {
+    /** Which face this judge is — the write tools' path resolution reads it to word and code the refusal as a write. */
+    readonly face: "write";
+    readonly ruleRows: readonly PathRuleDenyRow[];
+    matchPath(path: string): ReadDenyHit | null;
+    /** The target judgment the read face makes, on this face's rows: canonical key, lexical view, the leaf chain's hops. */
+    matchTarget(canonicalKey: string, lexicalView?: string, opts?: {
+        readonly aliasResolved?: boolean;
+        readonly hops?: readonly string[];
+    }): ReadDenyHit | null;
+}
+/** Compile the write face over the rule rows (the rows not on it are dropped here, once). */
+export declare function compileWriteDeny(rules?: readonly PathRuleDenyRow[]): WriteDenyMatcher;
 /** One compiled ripgrep glob flag for the traversal legs (`--iglob` = case-insensitive entry). */
 export interface ReadDenyRgGlob {
     flag: "--glob" | "--iglob";
@@ -40,12 +118,20 @@ export interface ReadDenyMatcher {
     /** Normalized entries (built-ins first, then additions; exact duplicates folded). The disclosure /
      *  persistence face. */
     readonly entries: readonly NormalizedReadDenyEntry[];
+    /** The rule-DSL rows on the READ face ({@link PathRuleDenyRow}), judged after the segment rows. Not persisted:
+     *  they are the caller policy's, which a resume re-supplies. Absent on a matcher compiled without rules. */
+    readonly ruleRows?: readonly PathRuleDenyRow[];
     /** Judge ONE path view (segment-window semantics). Returns the first matching entry, or null.
      *  `aliasResolved` = the key's MINTER reports the real filesystem already collapsed any win32
      *  component alias in it (canonicalizeTarget's realpath arm); unset ⇒ both readings are judged,
-     *  which is the fail-closed default. */
+     *  which is the fail-closed default. `walked` = the path is a MEMBER a traversal enumerated below a
+     *  root the command's text names, not a spelling of the command: the rule-DSL rows do not judge it (a
+     *  `Read(<pattern>)` deny reaches what the command SPELLS — the reference implementation's best-effort
+     *  reading of a rule against a command's arguments), while the segment rows (the built-in tiers, the
+     *  deployment's patterns) reach every path a read can open. Unset ⇒ every row, the fail-closed default. */
     matchPath(path: string, opts?: {
         readonly aliasResolved?: boolean;
+        readonly walked?: boolean;
     }): ReadDenyHit | null;
     /** §3.3 target judgment: canonical view + lexical view + every hop of the leaf symlink chain (`hops`,
      *  each an unresolved spelling some link wrote); ANY hit decides. `aliasResolved` applies to the
@@ -55,17 +141,32 @@ export interface ReadDenyMatcher {
         readonly hops?: readonly string[];
     }): ReadDenyHit | null;
     /** Traversal exclusions for the rg legs: `!`-polarity glob pairs — `!**\/<p>` plus `!**\/<p>/…`
-     *  (the entry itself and its descendants). */
+     *  (the entry itself and its descendants). An entry placed at a home carries none (a glob is relative to the
+     *  search root): `matchPath` judges it on the rg leg's output and in the walker. */
     readonly rgExclusionGlobs: readonly ReadDenyRgGlob[];
     /** Positive-polarity twins of the exclusions, for the bounded existence probe (first hit = entries
      *  matching the deny list exist under the scope and were excluded). */
     readonly rgProbeGlobs: readonly ReadDenyRgGlob[];
+    /** Whether an entry that carries NO traversal glob (one placed at a home) can match a path under `scope` (an absolute
+     *  directory): the rg leg cannot exclude such an entry, and a search that reads it and prunes afterwards answers
+     *  differently by whether the entry's content matched — so a search over such a scope takes the walker, which prunes
+     *  by path before reading. A scope that is not rooted answers true. */
+    unexcludableUnder?(scope: string): boolean;
+    /** A row that lies AT or BELOW `path` — the path is inside one of the row's matches, or a match would run on below the
+     *  path from its own segments ({@link rowMeetsPath}) — so moving, copying or removing the path changes what the row
+     *  covers. A rule row's reach below a path is not enumerable: any rule row answers. */
+    rowAtOrBelow?(path: string): ReadDenyHit | null;
 }
 /** The DENY HALF of a shell read boundary, in the shape `BashReadonlyRootBoundary` declares it (structural:
  *  this module is the leaf every face depends on). `denyMatch` judges one LEXICALLY RESOLVED operand,
  *  returning the matched pattern or null; PRESENT-IFF there is something to judge. */
 export interface ReadDenySeat {
-    denyMatch?: (resolvedPath: string) => string | null;
+    /** `walked` — the path is a traversal's enumerated member, not a spelling ({@link ReadDenyMatcher.matchPath}). */
+    denyMatch?: (resolvedPath: string, opts?: {
+        readonly walked?: boolean;
+    }) => string | null;
+    /** {@link ReadDenyMatcher.rowAtOrBelow} for one lexically resolved path; present exactly when `denyMatch` is. */
+    denyAtOrBelow?: (resolvedPath: string) => string | null;
     denyEntries: readonly string[];
 }
 /** The ONE adapter from a compiled matcher to that seat, so every face mounts it the SAME way and the "wire
@@ -86,9 +187,11 @@ export declare function readDenySeat(matcher: ReadDenyMatcher | undefined): Read
  *  which is approvable and so states the finding without claiming a refusal. NOT composers, each stating
  *  its own fact: the compaction lane's withheld-attachment HTML attribute, and the traversal notes'
  *  withheld-COUNT lines, which name the table and a pattern LIST. */
-export declare function sensitivePathDenyList(pattern: string | readonly string[]): string;
+export declare function sensitivePathDenyList(pattern: string | readonly string[], face?: DenyFace): string;
 /** The deny table's REACH: a deny row holds INSIDE the containment roots, so no root grant answers it. */
 export declare const SENSITIVE_PATH_DENY_SCOPE = "This list guards credential-class paths and applies regardless of the containment roots.";
+/** The write face's reach, in the same place of the sentence: a write deny row holds under every root and every mode. */
+export declare const WRITE_DENY_SCOPE = "A write deny row holds regardless of the containment roots and of the permission mode.";
 /**
  * THE deny refusal sentence — five segments, one mint, every read face: the ACTION, the ABSOLUTE target as the
  * caller spelled it (with its canonical target in parentheses when the two differ), the DISPOSITION (a deny row is
@@ -105,6 +208,8 @@ export declare function readDenySentence(finding: {
     readonly canonical?: string;
     readonly pattern: string;
     readonly matchedView?: string;
+    /** The table face that refused (default `read`): a write-face hit names the write list and its reach, and writes. */
+    readonly face?: DenyFace;
 }): string;
 /** The per-part budget of the deny sentence — the gate's own card-account cap, not a second number. */
 export declare const READ_DENY_SENTENCE_PART_MAX = 200;
@@ -135,15 +240,16 @@ export interface ReadDenyBuiltinRow {
 /**
  * READ_FACE_BUILTIN_DENY_TABLE — the FULL built-in table with tier metadata: the material basis of
  * the deployment admin face, what an org administrator "sees" before selecting tiers / excluding
- * rows. Activation is a SEPARATE fact and is OFF by default: every row here is inert until a
- * deployment names its tier ({@link READ_DENY_DEFAULT_TIERS} is empty), so this is the MENU, never
- * the active set. Rows stay curated regardless — the menu has to be worth switching on.
+ * rows. Activation is a SEPARATE fact: the tiers of {@link READ_DENY_DEFAULT_TIERS} are active unless the
+ * deployment selects otherwise, the rest are inert until a deployment names their tier — so this is the
+ * MENU, never the active set. Rows stay curated regardless — the menu has to be worth switching on.
  * The dotenv family is deliberately NOT here — workspace `.env` files are working material for the
  * tasks this engine runs; an `outside_workspace` tier is likewise deliberately absent.
  *
- * 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,
- * and a false refusal on a fixture is the cheap direction (deny errs strict).
+ * Each row states its tradeoff. An unanchored row is matched as a segment run anywhere in the path, so a
+ * repo fixture spelled `fixtures/.ssh/id_rsa` is refused too — deliberate: the refusal names the pattern,
+ * and a false refusal on a fixture is the cheap direction (deny errs strict). A home-anchored row
+ * (`~/…`, {@link READ_DENY_HOME_WORD}) is matched only below the home directory.
  *
  * NOT listed, deliberately: `.env`/`.env.*` (ruled out — workspace material; the WRITE guard still
  * covers them; the ENGINE's own `.env` under its data root is a different file and IS listed, see the
@@ -153,27 +259,31 @@ export interface ReadDenyBuiltinRow {
  * engine's own data root as a WHOLE (transcript integrity policy owns it with an ask on the write
  * face, and the memory library the model is told to read and edit lives under it).
  *
- * agent-config tier — the agent's OWN configuration files whose `env` / server blocks carry API keys
- * in cleartext (the shell's `settings.json` env block, a project `.mcp.json` server env, the engine
- * host's data-root `.env`). Unguarded, a structured read of one of these lands the key verbatim in
- * the tool result and therefore in the session record. Rows name FILES, not the config DIRECTORIES:
- * `.sema`/`.claude` also hold agents, skills, hooks and (under the shell's layout,
- * `~/.sema/engine-data`) the engine data root with the memory library — material the model reads
- * and edits as ordinary work, and a directory-wide row would need a data-root passthrough (one more
- * rule) to keep it readable. Token
+ * agent-config tier — the agent's OWN user-level configuration files whose `env` / server blocks carry API
+ * keys in cleartext (the shell's `settings.json` env block, an MCP server env, the engine host's data-root
+ * `.env`). Unguarded, a structured read of one of these lands the key verbatim in the tool result and
+ * therefore in the session record. Every row is HOME-ANCHORED: the user's own files under the home
+ * directory are refused, while a PROJECT's file of the same name (`./.sema/settings.json`, `./.mcp.json`,
+ * `./.claude/settings.json`) is working material the person edits with the model and reads normally — its
+ * writes are the write faces' business. Rows name FILES, not the config DIRECTORIES: `.sema`/`.claude` also
+ * hold agents, skills, hooks and (under the shell's layout, `~/.sema/engine-data`) the engine data root
+ * with the memory library — material the model reads and edits as ordinary work, and a directory-wide row
+ * would need a data-root passthrough (one more rule) to keep it readable. Token
  * STORES of the same tooling (`.credentials.json`, an agent CLI's `auth.json`, …) are credentials rows, not
  * agent-config rows: a deployment that switches this tier off to debug its agent configuration must
- * not also expose the OAuth stores beside it. These rows are ALSO the opt-in write deny set's
+ * not also expose the OAuth stores beside it. The rows' RUNS are ALSO the opt-in write deny set's
  * agent-configuration block ({@link import("../../core/sensitive-path-policy.js").agentConfigDenyPatterns},
  * which reads them from here; contract sentence there), so a row added here is judged by both faces.
  */
 export declare const READ_FACE_BUILTIN_DENY_TABLE: readonly ReadDenyBuiltinRow[];
 /**
- * The DEFAULT tier selection: EMPTY — an unconfigured deployment activates NO built-in row, so the
- * table above judges nothing until a deployment selects tiers. Activation is a deployment decision
- * with a visible seat, and the leg's wiring manifest reports which tiers it got.
+ * The DEFAULT tier selection — what an unconfigured deployment activates: the `credentials` tier (key
+ * material, cloud and registry credential files, token stores) and the `agent-config` tier (the agent's own
+ * user-level configuration files, home-anchored). The `shell-history`, `browser` and `wallet` tiers are a
+ * deployment's opt-in. Activation is a deployment decision with a visible seat, and the leg's wiring
+ * manifest reports which tiers it got.
  *
- * Still the NAMED default rather than nothing: `[]` and absence stay separately spellable on the
+ * The NAMED default rather than an inline literal: `[]` and absence stay separately spellable on the
  * seat, and a deployment profile wanting a different default changes THIS expression, not call sites.
  */
 export declare const READ_DENY_DEFAULT_TIERS: readonly ReadDenyBuiltinTier[];
@@ -182,8 +292,7 @@ export declare const READ_DENY_DEFAULT_TIERS: readonly ReadDenyBuiltinTier[];
  * 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},
- *    which is itself empty, so absent and `[]` resolve alike today and stay separately spellable).
+ *    (`[]` = 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 — never silently ignored.
  */
@@ -198,6 +307,17 @@ export interface ReadDenyBuiltinConfig {
  * table under a candidate configuration with the engine's own rules.
  */
 export declare function resolveReadDenyBuiltins(config?: ReadDenyBuiltinConfig): readonly ReadDenyBuiltinRow[];
+/**
+ * The deployment's built-in configuration as ONE validated snapshot, read off the seats' OWN values: each seat is an
+ * array of names or absent — any other value (a string, the empty string included) refuses loudly, naming the seat,
+ * before anything is spread or copied (a spread string reads as its characters, or as no names at all). The names are
+ * then judged by {@link resolveReadDenyBuiltins}. The snapshot holds copies: a caller mutating its arrays afterwards
+ * moves nothing, so every compile of one mount reads the same selection.
+ */
+export declare function readDenyBuiltinConfigOf(seats: {
+    readonly tiers?: unknown;
+    readonly exclude?: unknown;
+}): ReadDenyBuiltinConfig;
 /**
  * The tiers a deployment configuration ACTIVATES — the tier names of {@link resolveReadDenyBuiltins}'s
  * surviving rows, in {@link READ_DENY_BUILTIN_TIERS} order (the closed set is the ordering source, so
@@ -210,10 +330,9 @@ export declare function resolveReadDenyBuiltins(config?: ReadDenyBuiltinConfig):
 export declare function activeReadDenyBuiltinTiers(config?: ReadDenyBuiltinConfig): readonly ReadDenyBuiltinTier[];
 /**
  * READ_FACE_DEFAULT_DENY_ENTRIES — the DEFAULT-ACTIVE built-in set: {@link READ_FACE_BUILTIN_DENY_TABLE}
- * under {@link READ_DENY_DEFAULT_TIERS}. That selection is EMPTY, so this is an EMPTY list — the
- * honest answer to what it is asked ("what does an unconfigured deployment refuse": nothing, from
- * this table). Kept, and kept derived, so a consumer rendering that answer keeps reading it; the
- * tier-annotated table is where a consumer renders "what COULD be switched on".
+ * under {@link READ_DENY_DEFAULT_TIERS} — the answer to "what does an unconfigured deployment refuse, from
+ * this table". Derived, so it follows the default selection; the tier-annotated table is where a consumer
+ * renders "what COULD be switched on".
  */
 export declare const READ_FACE_DEFAULT_DENY_ENTRIES: readonly ReadDenyEntry[];
 /** A compiled segment-run pattern (shared engine — the write guard delegates here too). */
@@ -222,6 +341,12 @@ export interface CompiledSegmentPattern {
     segments: RegExp[];
     /** Fold BOTH sides through {@link asciiLower} before testing (compile lowered the pattern side). */
     foldAscii: boolean;
+    /** The segment lists of the directories the run is ANCHORED at (folded as the pattern folds): the run must start
+     *  right after one of them. Absent = the run matches anywhere. */
+    anchors?: readonly (readonly string[])[];
+    /** Judged in a ROOTED view only: an extra location of a home-anchored row (where its literal head leads). A view that
+     *  is not rooted cannot be placed and is covered by the row's own run, held anywhere. */
+    rootedOnly?: true;
 }
 /**
  * Compile one segment-glob pattern (shared engine). `fold`:
@@ -235,9 +360,10 @@ export interface CompiledSegmentPattern {
 export declare function compileSegmentPattern(raw: string, fold: "none" | "ascii" | "unicode"): CompiledSegmentPattern | null;
 /**
  * Does the path contain a compiled pattern as a CONTIGUOUS run of full path segments? (Shared engine:
- * `.git/hooks` matches `/repo/.git/hooks/pre-commit`; `.ssh` matches any `.ssh` segment.) Splits on
- * BOTH separator families — win32 canonical keys are backslash-form. Returns the matched raw pattern
- * or null.
+ * `.git/hooks` matches `/repo/.git/hooks/pre-commit`; `.ssh` matches any `.ssh` segment.) An ANCHORED pattern
+ * ({@link CompiledSegmentPattern.anchors}) matches only where the path's leading segments are one anchor's and
+ * the run starts right after them. Splits on BOTH separator families — win32 canonical keys are backslash-form.
+ * Returns the matched raw pattern or null.
  */
 export declare function matchSegmentPatterns(path: string, compiled: readonly CompiledSegmentPattern[], opts?: {
     readonly aliasResolved?: boolean;
@@ -251,6 +377,10 @@ export declare function matchSegmentPatterns(path: string, compiled: readonly Co
  * refusal reason, or null when the entry is valid.
  */
 export declare function persistedReadDenyEntryProblem(e: unknown): string | null;
+/** The home spellings a home-anchored row is placed under, judged as given: an array of absolute path strings, loud
+ *  otherwise and naming `readDenyHomes` — a relative or empty spelling places the row where no home is, and a bare
+ *  string would be read as its characters. */
+export declare function checkedReadDenyHomes(homes: unknown, seat?: string): readonly string[];
 /**
  * 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
@@ -260,5 +390,17 @@ export declare function persistedReadDenyEntryProblem(e: unknown): string | null
  * 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.
+ *
+ * `homes` — the spellings of the execution environment's home directory a home-anchored entry
+ * ({@link READ_DENY_HOME_WORD}) is placed under: the declared home and, where the environment's canonical
+ * spelling differs, that one too (the faces judge canonical keys beside the spelled views). Absolute
+ * spellings only — any other shape refuses loudly, naming `readDenyHomes`. EMPTY = the environment declares no
+ * home: a home-anchored entry then matches its run anywhere — a row that cannot be placed holds wider, never narrower.
+ *
+ * `linked` — where a home-anchored row's LITERAL HEAD ({@link readDenyRunHead}) really leads, keyed by the row's
+ * pattern: the canonical locations a mount resolved (`readDenyHomeLinksOf`, read-deny-home.ts) where one of the
+ * head's segments is a link (`~/.sema` linked into a dotfiles directory). The row is placed at each location too —
+ * the same row, the same name in every refusal — with the rest of its run matched below it. The read faces judge
+ * canonical keys, so every spelling that reaches the linked file meets the row there. Absolute locations only.
  */
-export declare function compileReadDeny(additions?: readonly ReadDenyEntry[], layer?: string, builtin?: ReadDenyBuiltinConfig): ReadDenyMatcher;
+export declare function compileReadDeny(additions?: readonly ReadDenyEntry[], layer?: string, builtin?: ReadDenyBuiltinConfig, rules?: readonly PathRuleDenyRow[], homes?: readonly string[], linked?: ReadonlyMap<string, readonly string[]>): ReadDenyMatcher;