@sema-agent/core 7.33.8 → 7.34.0

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

@@ -11,6 +11,7 @@ export * from "./fs-search-tools.js";
 export * from "./bash-readonly-classifier.js";
 export * from "./fs-bash.js";
 export * from "./read-deny.js";
+export { readDenyHomesOf } from "./read-deny-home.js";
 import type { ShellReadAdmission } from "./shell-read-check.js";
 export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
 import { type ReadDenyEntry } from "./read-deny.js";
@@ -55,6 +56,10 @@ export interface HandsToolkitOptions {
      *  consumer mounting the read-only band outside the Runner must run `runToolGate` with a station of its own
      *  (`createShellReadStation`). */
     shellReadAdmission?: ShellReadAdmission;
+    /** The gate's file read station's ADMISSION (`FileReadStation.admitted`, file-read-check.ts), handed to Read / Grep /
+     *  Glob: an out-of-root target the gate put to a question and then let through is read once, on the canonical key the
+     *  station judged. ABSENT ⇒ no station (a library-direct toolkit): the tools refuse every out-of-root target. */
+    readAdmission?: (toolCallId: string | undefined, canonicalKey: string) => boolean;
     /** Commit-message attribution trailer for the `bash` git protocol. Default NONE — attribution is a
      *  deployment identity asset, so the branded deployment sets it; pass `"Name <email>"` to advertise
      *  one, `false` (≡ unset) for no trailer section. */
@@ -167,11 +172,10 @@ export interface HandsToolkitOptions {
      *  time. The write faces are untouched (their guard is createSensitivePathPolicy). */
     readDenyPatterns?: readonly ReadDenyEntry[];
     /** The deployment's built-in-table TIER selection ({@link import("./read-deny.js").ReadDenyBuiltinConfig}
-     *  `tiers` key) — the ON/OFF switch for the built-in table, OFF unless this seat says otherwise:
+     *  `tiers` key) — the switch for the built-in table:
      *  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}), which is EMPTY — an unconfigured
-     *  mount activates no built-in row.
+     *  ({@link import("./read-deny.js").READ_DENY_DEFAULT_TIERS}: `credentials` and the home-anchored `agent-config`).
      *  Composes with {@link readDenyBuiltinExclude} (tier selection first, then row removal) and never
      *  touches the additions seats. Unknown tier names throw at wiring time. Deployment seat ONLY —
      *  deliberately not a TaskSpec key, so no task can widen below its deployment. */
@@ -181,6 +185,22 @@ export interface HandsToolkitOptions {
      *  of an inactive tier is a satisfied intent (no-op); a name matching NO table row throws at wiring
      *  time (never silently ignored). Deployment seat ONLY, same clamp argument as the tiers key. */
     readDenyBuiltinExclude?: readonly string[];
+    /** The spellings of the execution environment's home a home-anchored deny row (`~/…`) is placed under
+     *  ({@link import("./read-deny-home.js").readDenyHomesOf}: the declared home and its canonical spelling). Absolute path
+     *  strings only — any other shape throws at wiring time, naming the seat. The Runner passes the spellings its own judge
+     *  was compiled with. */
+    readDenyHomes?: readonly string[];
+    /** Where each home-anchored row's literal head leads beyond the home's spellings
+     *  ({@link import("./read-deny-home.js").readDenyHomeLinksOf}, keyed by the row's pattern) — the Runner passes the
+     *  locations its own judge was compiled with, so the band and the gate judge one placement.
+     *  Unless a mount carries both, the band resolves the placement itself the way the Runner does (the homes it carries
+     *  are used as given; {@link import("./read-deny-home.js").placeReadDenyAtHome}), and its read tools (Read / Grep /
+     *  Glob / RepoMap) wait for that placement before they judge anything. A placement that fails leaves the home-anchored
+     *  rows held anywhere. */
+    readDenyHomeLinks?: ReadonlyMap<string, readonly string[]>;
+    /** The permission-rule rows of the deny table ({@link import("./read-deny.js").PathRuleDenyRow}, `ToolPolicy.pathDenyRules`):
+     *  the read-face rows join the structured read faces' judge beside the segment rows. The Runner passes the leg's own. */
+    pathDenyRules?: readonly import("./read-deny.js").PathRuleDenyRow[];
     /** The READ-face containment state for the structured read faces
      *  ({@link import("./containment-face.js").ContainmentFace}; resolved through the SAME
      *  {@link import("./containment-face.js").resolveContainmentFace} order prepare-task uses). Absent ⇒ the
@@ -202,6 +222,10 @@ export interface HandsToolkitOptions {
      *  wins the same way the read seat's does (that mount carries no write faces at all), announced as
      *  `config.write_face_deployment_clamped`. Never affects the read faces. */
     writeFace?: ContainmentFace;
+    /** A runner's LIVE write face — its resolution, which reads the permission mode's face on every call. Present ⇒
+     *  the write tools read it per call and {@link writeFace} is not consulted (the runner resolved and screened the
+     *  seats itself); absent ⇒ the toolkit's own resolution of {@link writeFace}, fixed at creation. */
+    writeFaceLive?: () => ContainmentFace;
     /** The session's reminder provenance mark: the band's engine-minted
      *  `<system-reminder>` open tags (the Read cyber/dedup/offset/empty reminders and the gh
      *  rate-limit hint) carry it as `mark="…"`, matching the system-prompt declaration the Runner
@@ -224,6 +248,18 @@ export interface HandsToolkitOptions {
  *  predicate {@link createHandsToolkit} branches on and prepare-task plans by (the memory phase must know, before the
  *  band exists, whether the instruction-taught write channel will be there). `readOnly` is the verifier boundary. */
 export declare function handsWriteHalfMounts(opts: Pick<HandsToolkitOptions, "readOnly">): boolean;
+/** The engine's background-output read exemption over one toolkit's seats: the exact registered output file of a
+ *  background command, visible to the caller's own owner / scope / session, on THIS execution env — the file the
+ *  launch receipt tells the model to Read. Shared by the Read tool's fence and the file read station, so the station
+ *  puts no question where the fence would admit. */
+export declare function backgroundOutputReadExemption(registry: TaskRegistry | undefined, seat: {
+    readonly taskOwner?: string;
+    readonly taskScope?: string;
+    readonly sessionId?: string;
+}, env: ExecutionEnv): ((canonicalKey: string, c?: {
+    taskId?: string;
+    principal?: string;
+}) => boolean) | undefined;
 /**
  * Build the per-task hand tool band over an injected env + fresh per-task read state.
  * `rootCanonical` is the already-canonicalized containment root (prepare-task resolves it once). Normal

package/dist/tools/fs/index.js

@@ -11,9 +11,12 @@ export * from "./fs-search-tools.js";
 export * from "./bash-readonly-classifier.js";
 export * from "./fs-bash.js";
 export * from "./read-deny.js";
+export { readDenyHomesOf } from "./read-deny-home.js";
 import { BASH_READONLY_DEFAULT_ALLOW } from "./bash-readonly-classifier.js";
 export { BASH_CLASSIFY_EXTRA_ALLOW, bashClassifyDefaultAllow } from "./bash-readonly-classifier.js";
-import { compileReadDeny } from "./read-deny.js";
+import { checkedReadDenyHomes, compileReadDeny, compileWriteDeny, readDenyBuiltinConfigOf, readDenyPatternRun } from "./read-deny.js";
+import { withGateTimeout } from "../../core/gate-bounded-await.js";
+import { placeReadDenyAtHome, readDenyPlacedLater } from "./read-deny-home.js";
 import { deploymentFaceClampNotice, resolveContainmentFace } from "./containment-face.js";
 export * from "./containment-face.js";
 import {} from "./fs-shared.js";
@@ -24,22 +27,41 @@ import { createBashTool, createBashReadonlyTool, createEnvTaskOutputTool, create
 export function handsWriteHalfMounts(opts) {
     return opts.readOnly !== true;
 }
+export function backgroundOutputReadExemption(registry, seat, env) {
+    if (registry === undefined)
+        return undefined;
+    return (canonicalKey, c) => registry.isBackgroundOutputFile(canonicalKey, { owner: c?.taskId ?? seat.taskOwner, scope: c?.principal ?? seat.taskScope, ...(seat.sessionId !== undefined ? { sessionId: seat.sessionId } : {}) }, env);
+}
 export function createHandsToolkit(env, readFileState, rootCanonical, opts = {}) {
     const { includeShell = false, readOnly = false, bashReadonlyAllow, commitCoAuthor = false, mountBackgroundTaskTools = true, additionalRoots, additionalReadRoots, } = opts;
     const readFaceRoots = additionalReadRoots === undefined ? additionalRoots : () => (additionalReadRoots.length === 0 ? additionalRoots : [...(additionalRoots ?? []), ...additionalReadRoots]);
     const cwdRef = opts.cwdRef ?? { current: rootCanonical };
-    const bgReadRegistry = opts.taskRegistry;
-    const bgOutputReadExemption = bgReadRegistry === undefined
+    const bgOutput = backgroundOutputReadExemption(opts.taskRegistry, opts, env);
+    const readAdmission = opts.readAdmission;
+    const bgOutputReadExemption = bgOutput === undefined && readAdmission === undefined
         ? undefined
-        : (canonicalKey, c) => bgReadRegistry.isBackgroundOutputFile(canonicalKey, {
-            owner: c.taskId ?? opts.taskOwner,
-            scope: c.principal ?? opts.taskScope,
-            ...(opts.sessionId !== undefined ? { sessionId: opts.sessionId } : {}),
-        }, env);
-    const readDeny = compileReadDeny(opts.readDenyPatterns ?? [], "HandsToolkitOptions.readDenyPatterns", {
-        ...(opts.readDenyBuiltinTiers !== undefined ? { tiers: opts.readDenyBuiltinTiers } : {}),
-        ...(opts.readDenyBuiltinExclude !== undefined ? { exclude: opts.readDenyBuiltinExclude } : {}),
-    });
+        : (canonicalKey, c) => readAdmission?.(c.toolCallId, canonicalKey) === true || (bgOutput?.(canonicalKey, c) ?? false);
+    const readDenyAdditions = (opts.readDenyPatterns ?? []).map((e) => (typeof e === "object" && e !== null ? { ...e } : e));
+    const readDenyRules = opts.pathDenyRules === undefined ? undefined : [...opts.pathDenyRules];
+    const readDenyBuiltinCfg = readDenyBuiltinConfigOf({ tiers: opts.readDenyBuiltinTiers, exclude: opts.readDenyBuiltinExclude });
+    const readDenyHomes = opts.readDenyHomes === undefined ? undefined : [...checkedReadDenyHomes(opts.readDenyHomes)];
+    const compileAt = (homes, linked) => compileReadDeny(readDenyAdditions, "HandsToolkitOptions.readDenyPatterns", readDenyBuiltinCfg, readDenyRules, homes, linked);
+    const unplaced = compileAt([]);
+    const carried = readDenyHomes !== undefined && opts.readDenyHomeLinks !== undefined;
+    const placesNothing = !unplaced.entries.some((e) => readDenyPatternRun(e.pattern).homeAnchored);
+    const late = carried || placesNothing ? undefined : readDenyPlacedLater(unplaced, () => placeReadDenyAtHome(env, compileAt, readDenyHomes));
+    const readDeny = late?.matcher ?? (carried ? compileAt(readDenyHomes, opts.readDenyHomeLinks) : unplaced);
+    const afterPlacement = (tool) => late === undefined
+        ? tool
+        : {
+            ...tool,
+            execute: async (...args) => {
+                await withGateTimeout(late.ready(), undefined, args[2], "readDenyPlacement").catch(() => undefined);
+                return await tool.execute(...args);
+            },
+        };
+    const writeDenyCompiled = compileWriteDeny(readDenyRules);
+    const writeDeny = writeDenyCompiled.ruleRows.length > 0 ? writeDenyCompiled : undefined;
     const readFace = resolveContainmentFace({
         kind: "read",
         depsFace: opts.readFace,
@@ -56,13 +78,14 @@ export function createHandsToolkit(env, readFileState, rootCanonical, opts = {})
         fullShellReachable: includeShell && !readOnly,
         onDeploymentClamp: () => deliverEngineNotice(opts.onNotice, deploymentFaceClampNotice("write")),
     });
+    const writeFaceOf = opts.writeFaceLive ?? (() => writeFace);
     const tools = [
-        createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts),
+        afterPlacement(createReadFileTool(env, readFileState, rootCanonical, readOnly ? undefined : cwdRef, readFaceRoots, opts.readImageDownsampler, opts.pdfModelCapabilities, bgOutputReadExemption, opts.readCyberReminder, readDeny, readFace, opts.reminderMark, opts.reminderDisclosureCounts)),
     ];
     if (handsWriteHalfMounts({ readOnly })) {
-        tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFace), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFace), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFace));
+        tools.push(createEditFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFaceOf, writeDeny), createWriteFileTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFaceOf, writeDeny), createNotebookEditTool(env, readFileState, rootCanonical, cwdRef, additionalRoots, opts.beforeWrite, opts.trackFileEdit, opts.onFileEdited, writeFaceOf, writeDeny));
     }
-    tools.push(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef), createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef), createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace));
+    tools.push(afterPlacement(createGrepTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)), afterPlacement(createGlobTool(env, rootCanonical, readFaceRoots, readDeny, readFace, cwdRef, readAdmission)), afterPlacement(createRepoMapTool(env, rootCanonical, readFaceRoots, readDeny, readFace)));
     if (includeShell) {
         tools.push(readOnly
             ? createBashReadonlyTool(env, rootCanonical, new Set(bashReadonlyAllow ?? BASH_READONLY_DEFAULT_ALLOW), {

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

@@ -0,0 +1,93 @@
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+import { type PathFamily } from "./safety.js";
+import { type ReadDenyMatcher } from "./read-deny.js";
+/** The environment's DECLARED home as an anchor list: `[homeDir]` when it declares an absolute one, else `[]` (no
+ *  home — a home-anchored row then holds its run anywhere, see `compileReadDeny`). */
+export declare function declaredReadDenyHomes(env: Pick<ExecutionEnv, "homeDir">): string[];
+/** The declared home and, where the environment's canonical spelling of it differs (a home reached through a
+ *  symlink), that spelling too: the faces judge canonical keys beside the spelled views, so a row placed only at
+ *  the spelled home would never meet a canonical key. A home the environment cannot resolve keeps its spelling. */
+export declare function readDenyHomesOf(env: Pick<ExecutionEnv, "homeDir" | "canonicalPath">, signal?: AbortSignal): Promise<string[]>;
+/**
+ * Where the home-anchored rows of a table LEAD beyond the home's own spellings, keyed by the row's pattern — the
+ * `linked` argument of `compileReadDeny`. For each row, its LITERAL HEAD (`readDenyRunHead`: the run's segments before
+ * the first one carrying `*`) is spelled under each home and resolved the way the read faces mint their keys
+ * (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined); a location that differs from every
+ * home's own spelling of the head is where one of the head's segments is a link, and the row is placed there too.
+ *  · a head that resolves to its own spelling under a home adds nothing (the row is already placed there);
+ *  · a head that cannot be resolved (an unanswered or refused probe, a probe that throws) adds nothing, and the answer
+ *    is not WHOLE (`whole: false`): the row stays placed at the home's spellings until the mount places again;
+ *  · a row whose head is empty (`~/.sema.*`) has no location to resolve and adds nothing;
+ *  · the heads are resolved together, so one placement waits at most one probe bound;
+ *  · read per placement — a link created afterwards is followed from the next placement on.
+ */
+export declare function readDenyHomeLinksOf(env: ExecutionEnv, entries: readonly {
+    readonly pattern: string;
+    readonly caseSensitive?: boolean;
+}[], homes: readonly string[], signal?: AbortSignal): Promise<{
+    readonly linked: Map<string, string[]>;
+    readonly whole: boolean;
+}>;
+/** Where an absolute location LEADS in one environment — resolved the way the read and write faces mint their keys
+ *  (`canonicalizeTarget`: the longest existing prefix resolved, the rest rejoined). `undefined` when the environment
+ *  does not answer (a refused or failed probe, one that throws). The one resolution a deny row's placement reads: a
+ *  home-anchored row's head ({@link readDenyHomeLinksOf}) and a rule row's head ({@link whereItsAnsweredPrefixLeads}). */
+export declare function whereItLeads(env: ExecutionEnv, at: string, family?: PathFamily, signal?: AbortSignal): Promise<string | undefined>;
+/** {@link whereItLeads} with a floor: where the environment does not answer for `at` (a probe that fails), the longest
+ *  prefix it does answer for is resolved and the rest rejoined — a rule row's head below a base that resolves is never
+ *  placed narrower than that base's own canonical spelling. The whole walk waits at most one bounded-await deadline.
+ *  `undefined` when no prefix answers in time. */
+export declare function whereItsAnsweredPrefixLeads(env: ExecutionEnv, at: string, family?: PathFamily, signal?: AbortSignal): Promise<string | undefined>;
+/** One mount's read-deny judge with its home-anchored rows placed: at the home's spellings (`homes` when the mount
+ *  carries them, else {@link readDenyHomesOf}, under the tree's bounded-await deadline — an environment that cannot
+ *  answer rejects the placement instead of holding it open) and where their heads lead ({@link readDenyHomeLinksOf}).
+ *  `whole` says whether the home and every head answered. A home the environment did not answer for places nothing:
+ *  the rows are held anywhere (`compile([])`, the rule for a row that cannot be placed) rather than at a spelling that
+ *  may miss the home's canonical one. `compile` is the mount's own compile over the two; the rows' patterns are read
+ *  off its compile at the homes alone. */
+export declare function placeReadDenyAtHome(env: ExecutionEnv, compile: (homes: readonly string[], linked?: ReadonlyMap<string, readonly string[]>) => ReadDenyMatcher, homes?: readonly string[], signal?: AbortSignal): Promise<{
+    readonly matcher: ReadDenyMatcher;
+    readonly homes: readonly string[];
+    readonly linked: ReadonlyMap<string, readonly string[]>;
+    readonly whole: boolean;
+}>;
+/**
+ * A judge for a mount that is built before its placement settles (the hands band is built synchronously): the table as
+ * `unplaced` compiles it — home-anchored rows held anywhere, the rule for a row that cannot be placed — until a
+ * placement settles, then the placed table. `place` starts at once; `ready()` settles when the latest placement has
+ * (either way) and, while no placement has come back WHOLE (a failed one, or one with a head that did not answer),
+ * places again first — an unanswered lookup is never kept as the answer. A failed placement leaves the table it
+ * replaced (the rows held anywhere, or an earlier placement), never unplaced-and-narrow. The mount holds its read faces
+ * until `ready()`.
+ */
+export declare function readDenyPlacedLater(unplaced: ReadDenyMatcher, place: () => Promise<{
+    readonly matcher: ReadDenyMatcher;
+    readonly whole: boolean;
+}>): {
+    readonly matcher: ReadDenyMatcher;
+    readonly ready: () => Promise<void>;
+};
+/** The environment surface a home view reads. */
+export type HomeViewEnv = Pick<ExecutionEnv, "homeDir" | "canonicalPath" | "fileIdentity">;
+/**
+ * A path's HOME VIEW — the one reader every face that judges a deny row by location uses (the structured read and
+ * write tools' target judgment, the shell station's establishment, the search walker, the ripgrep leg's output check
+ * and its scope choice). The view of a path is the path itself when it IS a directory on the home's chain (the
+ * canonical home and each of its ancestors, matched by {@link ExecutionEnv.fileIdentity}) — that directory's
+ * canonical spelling — and otherwise its parent's view with its own name rejoined. `of` answers the view only where
+ * it differs from the path as spelled; `undefined` otherwise, and wherever it cannot be read:
+ *  · the environment declares no home, no `fileIdentity`, or its home does not resolve ⇒ no view (the spelling form);
+ *    a home, or a level of its chain, that could not be read is asked again by the next judgment — an unanswered
+ *    lookup is never kept as the answer;
+ *  · a level that does not exist (a write's missing tail) has no identity of its own and takes its parent's view;
+ *  · any other failure at a level stops the view there: the path is judged as spelled, never wider.
+ * `leaf: "file"` skips the path's own identity (a file is never a directory on the chain).
+ */
+export interface HomeViews {
+    of(path: string, opts?: {
+        readonly leaf?: "file";
+    }): Promise<string | undefined>;
+}
+/** The home views of one judgment (a tool call, a command's establishment, one search): a view per directory is read
+ *  once and shared by every path below it. */
+export declare function homeViewsOf(env: HomeViewEnv, signal?: AbortSignal): HomeViews;

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;
+        },
+    };
+}