@sema-agent/core 7.38.0 → 7.38.2

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

@@ -1,12 +1,18 @@
 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`). */
+/** The one bound every probe of an AUXILIARY home shares within one placement (see the module head): long enough for a
+ *  local directory's canonical spelling, its chain of identities and its rows' heads, short enough that a hung home
+ *  costs a placement seconds, not the gate's bound. */
+export declare const AUXILIARY_HOME_PROBE_MS = 2000;
+/** {@link declaredReadDenyHomesAnswered}'s anchor list. */
 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. */
+/** The declared home and the account home ({@link declaredReadDenyHomes}) and, where the environment's canonical
+ *  spelling of one 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 — the account home's probe waits at most {@link AUXILIARY_HOME_PROBE_MS}.
+ *  `[]` — the rows hold their run at every location — where the environment declares no home, where the account lookup
+ *  gave no answer, or where the declared home's own probe did not answer (ask again later). */
 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
@@ -15,16 +21,20 @@ export declare function readDenyHomesOf(env: Pick<ExecutionEnv, "homeDir" | "can
  * (`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 head under a spelling that is no directory (a segment of it is a file, a symlink to a file, a device node or a
+ *    socket — the environment answers `not_directory` for the head) has nothing below it: an answer that adds nothing;
+ *  · any other head that cannot be resolved (an unanswered or refused probe — a directory the probe may not enter — 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;
+ *  · the heads are resolved together, so one placement waits at most one probe bound — or, with `deadline` (an absolute
+ *    time), each head until then: a head still unresolved at the deadline is a head that did not answer;
  *  · 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<{
+}[], homes: readonly string[], signal?: AbortSignal, deadline?: number): Promise<{
     readonly linked: Map<string, string[]>;
     readonly whole: boolean;
 }>;
@@ -38,15 +48,81 @@ export declare function whereItLeads(env: ExecutionEnv, at: string, family?: Pat
  *  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. */
+/** The environment surface a home view reads. */
+export type HomeViewEnv = Pick<ExecutionEnv, "homeDir" | "canonicalPath" | "fileIdentity">;
+/**
+ * The HOME VIEWS of one placement — 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). A judge carries the source its placement made ({@link HomeViewsCarrier}); a judgment
+ * takes one {@link HomeViews} from it ({@link homeViewsOf}).
+ *
+ * The view of a path is the path itself when it IS a directory on a home's chain (each home's canonical spelling 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. One identity keeps ONE spelling, and a row is placed at a
+ * HOME's spelling: a directory that IS a home (its own identity answered) keeps the home's own spelling over an
+ * ancestor's (a declared home below a mount of the account home meets the account home's identity at an ancestor); a
+ * home whose own identity did not answer has no directory to claim. Homes in order: the declared home, then the
+ * auxiliary homes. The homes are the placement's:
+ *  · the DECLARED home (`env.homeDir`, no lookup) is always among them — whatever the account lookup answered — and its
+ *    chain is read by the first judgment that asks, kept once every level answered, and asked again by the next
+ *    judgment otherwise (a home that does not exist yet is read once it does);
+ *  · each AUXILIARY home's chain is the one its placement read, once ({@link AUXILIARY_HOME_PROBE_MS}); a chain that did
+ *    not answer stays unanswered for that placement.
+ */
+export interface HomeViewSource {
+    /** 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. */
+    views(signal?: AbortSignal): HomeViews;
+}
+/** A judgment's views. `of` answers the view only where it differs from the path as spelled; `undefined` otherwise, and
+ *  wherever it cannot be read: no `fileIdentity` seat, no home, a level of the path whose identity fails (the path is
+ *  judged as spelled, never wider). A level that does not exist (a write's missing tail) takes its parent's view.
+ *  `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>;
+}
+/** A judge that carries the home views of the placement its rows were compiled at. */
+export interface HomeViewsCarrier {
+    readonly homeViews?: HomeViewSource;
+}
+/** A read deny judge with its placement's home views. */
+export type PlacedReadDenyMatcher = ReadDenyMatcher & {
+    readonly homeViews: HomeViewSource;
+};
+/** The views of the placement that returned `homes` — the very list object, as the engine hands it on (the Runner's
+ *  tool band). `undefined` for any other list: a copy, or a host's own. A mount that was handed the engine's placement
+ *  and cannot find its views has lost it: an engine defect, which the mount names ({@link sayPlacementLost}) and answers
+ *  by holding its home-anchored rows at every location — never by reading the homes a second time. */
+export declare function placementViewsOf(homes: readonly string[]): HomeViewSource | undefined;
+/** The line a mount says when the engine handed it a home list that is not its placement's (an engine defect, said every
+ *  time: no latch). */
+export declare function sayPlacementLost(): void;
+/** The home views over a home list fixed now — a mount that places nothing itself (a toolkit handed its placement, or
+ *  one whose table has no home-anchored row) and the public shell judgment: the declared home, and every entry of
+ *  `homes` that is not the declared home as an auxiliary home, read once, at once. */
+export declare function homeViewsAt(env: HomeViewEnv, homes: readonly string[]): HomeViewSource;
+/** The home views of one judgment, off the judge it judges with: the views of the judge's placement. A judge that
+ *  carries none (one built outside a mount) reads the declared home alone. */
+export declare function homeViewsOf(env: HomeViewEnv, judge: HomeViewsCarrier | undefined, signal?: AbortSignal): HomeViews;
+/** A judge with the home views `source` gives it. */
+export declare function carryHomeViews<T extends object>(judge: T, source: HomeViewSource): T & {
+    readonly homeViews: HomeViewSource;
+};
+/** One mount's read-deny judge with its home-anchored rows placed, and the home views of that placement:
+ *  · the HOME SET — `homes` when the mount carries a list (the account is not asked and no home is added), else the
+ *    declared home and the account lookup's answer ({@link declaredReadDenyHomes}); every home of the set is anchored at
+ *    its spelling and, where the environment answered one, its canonical spelling — one rule for both forms;
+ *  · the DECLARED home's canonical spelling under the tree's gate bound, and its rows' heads ({@link readDenyHomeLinksOf}):
+ *    a declared home, or a head under it, that did not answer leaves the placement not WHOLE — and an account lookup
+ *    with no answer, or a declared home that did not answer, places nothing: the rows are held anywhere (`compile([])`)
+ *    rather than at a spelling that may miss the home's canonical one;
+ *  · each AUXILIARY home (see the module head) read once under {@link AUXILIARY_HOME_PROBE_MS} — its spellings, its
+ *    chain, its rows' heads — at the same time; whatever of it did not answer costs that home alone and never `whole`.
+ *  `compile` is the mount's own compile; the rows' patterns are read off its compile at no home. */
 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 matcher: PlacedReadDenyMatcher;
     readonly homes: readonly string[];
     readonly linked: ReadonlyMap<string, readonly string[]>;
     readonly whole: boolean;
@@ -58,36 +134,13 @@ export declare function placeReadDenyAtHome(env: ExecutionEnv, compile: (homes:
  * (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()`.
+ * until `ready()`. The judge's home views are the latest settled placement's: a judgment that asks for one waits for the
+ * placement in flight (it never starts one).
  */
-export declare function readDenyPlacedLater(unplaced: ReadDenyMatcher, place: () => Promise<{
-    readonly matcher: ReadDenyMatcher;
+export declare function readDenyPlacedLater(unplaced: PlacedReadDenyMatcher, place: () => Promise<{
+    readonly matcher: PlacedReadDenyMatcher;
     readonly whole: boolean;
 }>): {
-    readonly matcher: ReadDenyMatcher;
+    readonly matcher: PlacedReadDenyMatcher;
     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

@@ -1,23 +1,106 @@
+import { userInfo } from "node:os";
 import { canonicalizeTarget, isAbsolutePathForm, joinForFamily, normalizeAbsPathLexically, pathFamilyOf } from "./safety.js";
 import { DEFAULT_GATE_AWAIT_TIMEOUT_MS, withGateTimeout } from "../../core/gate-bounded-await.js";
+import { thrownText } from "../../core/thrown-value.js";
 import { readDenyPatternRun, readDenyRunHead } from "./read-deny.js";
-export function declaredReadDenyHomes(env) {
-    const home = env.homeDir;
-    return home !== undefined && isAbsolutePathForm(home) ? [home] : [];
+export const AUXILIARY_HOME_PROBE_MS = 2_000;
+const said = new Set();
+function sayOnce(kind, line) {
+    if (said.has(kind))
+        return;
+    said.add(kind);
+    try {
+        console.warn(line);
+    }
+    catch {
+    }
 }
-export async function readDenyHomesOf(env, signal) {
-    return (await readDenyHomesAnswered(env, signal)).homes;
+function isNoAccountRow(e) {
+    try {
+        const info = typeof e === "object" && e !== null ? e.info : undefined;
+        return typeof info === "object" && info !== null && info.code === "ENOENT";
+    }
+    catch {
+        return false;
+    }
 }
-async function readDenyHomesAnswered(env, signal) {
-    const home = declaredReadDenyHomes(env)[0];
+function valueText(v) {
+    try {
+        return JSON.stringify(v) ?? String(v);
+    }
+    catch {
+        return typeof v;
+    }
+}
+function accountHomeOf() {
+    try {
+        const home = userInfo().homedir;
+        if (typeof home === "string" && isAbsolutePathForm(home))
+            return { state: "home", home };
+        sayOnce("bad_value", `read-deny homes: the account home lookup answered ${valueText(home)}, not an absolute path — home-anchored read-deny rows are placed under the environment's declared home only.`);
+        return { state: "none" };
+    }
+    catch (e) {
+        if (isNoAccountRow(e))
+            return { state: "none" };
+        sayOnce("unanswered", `read-deny homes: the account home could not be read (${thrownText(e)}) — home-anchored read-deny rows hold their run at every location until the lookup answers.`);
+        return { state: "unanswered" };
+    }
+}
+function declaredHomeOf(env) {
+    const home = env.homeDir;
+    return home !== undefined && isAbsolutePathForm(home) ? home : undefined;
+}
+function declaredReadDenyHomesAnswered(env) {
+    const home = declaredHomeOf(env);
     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" };
+    const account = accountHomeOf();
+    if (account.state === "unanswered")
+        return { homes: [], whole: false };
+    if (account.state === "none" || normalizeAbsPathLexically(account.home) === normalizeAbsPathLexically(home))
+        return { homes: [home], whole: true };
+    return { homes: [home, account.home], whole: true };
+}
+export function declaredReadDenyHomes(env) {
+    return declaredReadDenyHomesAnswered(env).homes;
+}
+function isDeclared(declared, home) {
+    return declared !== undefined && normalizeAbsPathLexically(home) === normalizeAbsPathLexically(declared);
 }
-export async function readDenyHomeLinksOf(env, entries, homes, signal) {
+async function homeSpellingsOf(env, home, signal) {
+    try {
+        const canonical = await env.canonicalPath(home, signal);
+        if (canonical.ok)
+            return { spellings: canonical.value !== home ? [home, canonical.value] : [home], canonical: canonical.value, answered: true };
+        return { spellings: [home], answered: canonical.error.code === "not_found" || canonical.error.code === "not_directory" };
+    }
+    catch {
+        return { spellings: [home], answered: false };
+    }
+}
+export async function readDenyHomesOf(env, signal) {
+    const listed = declaredReadDenyHomesAnswered(env);
+    const [declared, ...auxiliary] = listed.homes;
+    if (!listed.whole || declared === undefined)
+        return [];
+    const [own, ...others] = await Promise.all([
+        homeSpellingsOf(env, declared, signal),
+        ...auxiliary.map((home) => until(homeSpellingsOf(env, home, signal), Date.now() + AUXILIARY_HOME_PROBE_MS, signal).then((r) => r ?? { spellings: [home], answered: false })),
+    ]);
+    if (!own.answered)
+        return [];
+    if (others.some((r) => !r.answered))
+        sayAuxiliary("its path probe did not answer");
+    return [...new Set([...own.spellings, ...others.flatMap((r) => r.spellings)])];
+}
+async function until(work, deadline, signal) {
+    return await withGateTimeout(work, Math.max(0, deadline - Date.now()), signal, "auxiliaryHome").catch(() => undefined);
+}
+function sayAuxiliary(what) {
+    sayOnce("auxiliary", `read-deny homes: a home beside the environment's declared home did not answer its probes within ${AUXILIARY_HOME_PROBE_MS} ms (${what}) — its home-anchored read-deny rows sit at its spelling only, and a path through an alias of it is judged as spelled, until the next placement.`);
+}
+export async function readDenyHomeLinksOf(env, entries, homes, signal, deadline) {
     const rows = [];
     const familyOf = new Map();
     for (const { pattern, caseSensitive } of entries) {
@@ -35,7 +118,8 @@ export async function readDenyHomeLinksOf(env, entries, homes, signal) {
         });
         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 leadOf = async (at, family) => (await whereItLeads(env, at, family, signal)) ?? ((await holdsNothingBelow(env, at, signal)) ? at : undefined);
+    const resolved = new Map(await Promise.all([...familyOf].map(async ([at, family]) => [at, deadline === undefined ? await leadOf(at, family) : await until(leadOf(at, family), deadline, signal)])));
     const out = new Map();
     const whole = [...resolved.values()].every((location) => location !== undefined);
     for (const { pattern, caseSensitive, spelled } of rows) {
@@ -52,6 +136,10 @@ export async function readDenyHomeLinksOf(env, entries, homes, signal) {
     }
     return { linked: out, whole };
 }
+async function holdsNothingBelow(env, at, signal) {
+    const probe = await withGateTimeout(Promise.resolve().then(() => env.canonicalPath(at, signal)), DEFAULT_GATE_AWAIT_TIMEOUT_MS, signal, "readDenyHead").catch(() => undefined);
+    return probe !== undefined && !probe.ok && probe.error.code === "not_directory";
+}
 export async function whereItLeads(env, at, family = pathFamilyOf({ root: at }), signal) {
     try {
         const key = await canonicalizeTarget(env, at, signal, family);
@@ -77,17 +165,189 @@ export async function whereItsAnsweredPrefixLeads(env, at, family = pathFamilyOf
     };
     return await withGateTimeout(walk(), DEFAULT_GATE_AWAIT_TIMEOUT_MS, signal, "ruleRowHead").catch(() => undefined);
 }
+const NO_CHAIN = { ancestors: [], whole: false };
+async function chainAbove(env, identity, canonical, signal, deadline) {
+    let own;
+    const ancestors = [];
+    let whole = true;
+    for (let dir = normalizeAbsPathLexically(canonical), first = true;; first = false) {
+        const id = deadline === undefined ? await identityOf(env, identity, dir, signal) : await until(identityOf(env, identity, dir, signal), deadline, signal);
+        if (id === undefined && deadline !== undefined && Date.now() >= deadline) {
+            whole = false;
+            break;
+        }
+        if (id?.ok !== true)
+            whole = false;
+        else if (first)
+            own = { dir, id: id.value };
+        else
+            ancestors.push({ dir, id: id.value });
+        const parent = normalizeAbsPathLexically(`${dir}/..`);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return { ...(own !== undefined ? { own } : {}), ancestors, whole };
+}
+async function identityOf(env, identity, path, signal) {
+    try {
+        return await identity.call(env, path, signal);
+    }
+    catch {
+        return undefined;
+    }
+}
+async function readAuxiliaryHome(env, home, opts, signal) {
+    const deadline = Date.now() + AUXILIARY_HOME_PROBE_MS;
+    const spelled = await until(homeSpellingsOf(env, home, signal), deadline, signal);
+    let reading;
+    if (spelled?.canonical === undefined) {
+        const answered = spelled?.answered === true;
+        reading = { place: [home], chain: answered ? { ancestors: [], whole: true } : NO_CHAIN, linked: new Map(), answered };
+    }
+    else {
+        const place = spelled.spellings;
+        const identity = env.fileIdentity;
+        const [chain, heads] = await Promise.all([
+            typeof identity === "function" ? chainAbove(env, identity, spelled.canonical, signal, deadline) : Promise.resolve({ ancestors: [], whole: true }),
+            opts.entries !== undefined ? readDenyHomeLinksOf(env, opts.entries, place, signal, deadline) : Promise.resolve({ linked: new Map(), whole: true }),
+        ]);
+        reading = { place, chain, linked: heads.linked, answered: chain.whole && heads.whole };
+    }
+    if (!reading.answered)
+        sayAuxiliary("a probe did not answer");
+    return reading;
+}
+function homeViewSourceOver(env, auxiliary) {
+    const declared = declaredHomeOf(env);
+    const identity = env.fileIdentity;
+    let declaredChain;
+    const readDeclared = () => {
+        if (declared === undefined || typeof identity !== "function")
+            return Promise.resolve(NO_CHAIN);
+        if (declaredChain === undefined) {
+            const reading = withGateTimeout((async () => {
+                const spelled = await homeSpellingsOf(env, declared);
+                return spelled.canonical === undefined ? NO_CHAIN : await chainAbove(env, identity, spelled.canonical);
+            })(), DEFAULT_GATE_AWAIT_TIMEOUT_MS, undefined, "homeChain").catch(() => NO_CHAIN);
+            declaredChain = reading;
+            void reading.then((c) => {
+                if (!c.whole && declaredChain === reading)
+                    declaredChain = undefined;
+            });
+        }
+        return declaredChain;
+    };
+    return {
+        views(signal) {
+            let index;
+            const indexOf = () => (index ??= (async () => {
+                const chains = [await readDeclared(), ...(await Promise.all(auxiliary)).map((a) => a.chain)];
+                const out = new Map();
+                for (const { own } of chains)
+                    if (own !== undefined && !out.has(own.id))
+                        out.set(own.id, own.dir);
+                for (const { ancestors } of chains)
+                    for (const { dir, id } of ancestors)
+                        if (!out.has(id))
+                            out.set(id, dir);
+                return out.size > 0 ? out : undefined;
+            })());
+            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 indexOf();
+                        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 (typeof identity !== "function" || (declared === undefined && auxiliary.length === 0) || !isAbsolutePathForm(path))
+                        return undefined;
+                    const spelled = normalizeAbsPathLexically(path);
+                    const view = await viewOf(spelled, opts?.leaf === "file");
+                    return view === undefined || view === spelled ? undefined : view;
+                },
+            };
+        },
+    };
+}
+const PLACEMENT_VIEWS = new WeakMap();
+function placementOf(matcher, homes, linked, whole) {
+    const list = Object.freeze([...homes]);
+    PLACEMENT_VIEWS.set(list, matcher.homeViews);
+    return { matcher, homes: list, linked, whole };
+}
+export function placementViewsOf(homes) {
+    return PLACEMENT_VIEWS.get(homes);
+}
+export function sayPlacementLost() {
+    try {
+        console.warn("read-deny homes: this tool band was handed a home list that is not the placement's own (an engine defect) — its home-anchored read-deny rows hold their run at every location, and only the declared home's views are read.");
+    }
+    catch {
+    }
+}
+export function homeViewsAt(env, homes) {
+    const declared = declaredHomeOf(env);
+    const auxiliary = [...new Set(homes.filter((h) => isAbsolutePathForm(h) && !isDeclared(declared, h)))];
+    return homeViewSourceOver(env, auxiliary.map((home) => readAuxiliaryHome(env, home, {})));
+}
+export function homeViewsOf(env, judge, signal) {
+    return (judge?.homeViews ?? homeViewsAt(env, [])).views(signal);
+}
+export function carryHomeViews(judge, source) {
+    return { ...judge, homeViews: source };
+}
 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 entries = compile([]).entries;
+    const declared = declaredHomeOf(env);
+    const heldAnywhere = (whole) => placementOf(carryHomeViews(compile([]), homeViewSourceOver(env, [])), [], new Map(), whole);
+    const listed = homes === undefined ? declaredReadDenyHomesAnswered(env) : { homes, whole: true };
+    if (!listed.whole)
+        return heldAnywhere(false);
+    const own = listed.homes.filter((h) => isDeclared(declared, h));
+    let declaredAt = [];
+    if (own.length > 0) {
+        const ownSpellings = await withGateTimeout(homeSpellingsOf(env, own[0], signal), DEFAULT_GATE_AWAIT_TIMEOUT_MS, signal, "readDenyHomes");
+        if (!ownSpellings.answered)
+            return heldAnywhere(false);
+        declaredAt = [...new Set([...own, ...ownSpellings.spellings])];
+    }
+    const auxiliary = listed.homes.filter((h) => !isDeclared(declared, h)).map((home) => readAuxiliaryHome(env, home, { entries }, signal));
+    const [heads, readings] = await Promise.all([readDenyHomeLinksOf(env, entries, declaredAt, signal), Promise.all(auxiliary)]);
+    const at = [...new Set([...declaredAt, ...readings.flatMap((r) => r.place)])];
+    const linked = new Map();
+    for (const map of [heads.linked, ...readings.map((r) => r.linked)]) {
+        for (const [pattern, locations] of map)
+            linked.set(pattern, [...new Set([...(linked.get(pattern) ?? []), ...locations])]);
     }
-    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 };
+    const matcher = linked.size === 0 ? compile(at) : compile(at, linked);
+    return placementOf(carryHomeViews(matcher, homeViewSourceOver(env, auxiliary)), at, linked, heads.whole);
 }
 export function readDenyPlacedLater(unplaced, place) {
     let current = unplaced;
@@ -108,6 +368,17 @@ export function readDenyPlacedLater(unplaced, place) {
         if (!whole)
             await again();
     };
+    const settled = async () => {
+        if (pending !== undefined)
+            await pending;
+        return current;
+    };
+    const homeViews = {
+        views(signal) {
+            let views;
+            return { of: async (path, opts) => await (await (views ??= settled().then((m) => m.homeViews.views(signal)))).of(path, opts) };
+        },
+    };
     const matcher = {
         get entries() {
             return current.entries;
@@ -125,101 +396,7 @@ export function readDenyPlacedLater(unplaced, place) {
         },
         unexcludableUnder: (scope) => current.unexcludableUnder?.(scope) ?? false,
         rowAtOrBelow: (path) => current.rowAtOrBelow?.(path) ?? null,
+        homeViews,
     };
     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

@@ -392,8 +392,8 @@ export declare function checkedReadDenyHomes(homes: unknown, seat?: string): rea
  * 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
+ * ({@link READ_DENY_HOME_WORD}) is placed under: the declared home, the account home and, where the environment's
+ * canonical spelling of one 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.
  *