@sema-agent/core 7.49.1 → 7.49.2

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

@@ -199,13 +199,18 @@ 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 };
+const NO_CHAIN = { ancestors: [], whole: false, unread: [] };
+const unreadChain = (at) => ({ ancestors: [], whole: false, unread: [at] });
+const identityUnread = (id) => id === undefined || (!id.ok && id.error.code !== "not_found" && id.error.code !== "not_directory" && id.error.code !== "not_supported");
 async function chainAbove(env, identity, canonical, signal, deadline) {
     let own;
     const ancestors = [];
+    const unread = [];
     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 (identityUnread(id))
+            unread.push(dir);
         if (id === undefined && deadline !== undefined && Date.now() >= deadline) {
             whole = false;
             break;
@@ -221,7 +226,7 @@ async function chainAbove(env, identity, canonical, signal, deadline) {
             break;
         dir = parent;
     }
-    return { ...(own !== undefined ? { own } : {}), ancestors, whole };
+    return { ...(own !== undefined ? { own } : {}), ancestors, whole, unread };
 }
 async function identityOf(env, identity, path, signal) {
     try {
@@ -238,13 +243,13 @@ async function readAuxiliaryHome(env, home, opts, signal) {
     if (spelled?.canonical === undefined) {
         const answered = spelled?.answered === true;
         const linked = opts.configRoot === true && opts.entries !== undefined ? configRootSpelledLinks(opts.entries, [home]) : new Map();
-        reading = { place: [home], chain: answered ? { ancestors: [], whole: true } : NO_CHAIN, linked, answered };
+        reading = { place: [home], chain: answered ? { ancestors: [], whole: true, unread: [] } : unreadChain(home), linked, 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 }),
+            typeof identity === "function" ? chainAbove(env, identity, spelled.canonical, signal, deadline) : Promise.resolve({ ancestors: [], whole: true, unread: [] }),
             opts.entries === undefined
                 ? Promise.resolve({ linked: new Map(), whole: true })
                 : readDenyLinksOf(env, opts.entries, opts.configRoot === true ? { at: "unanchored", roots: place } : { at: "home", homes: place }, signal, deadline),
@@ -257,16 +262,16 @@ async function readAuxiliaryHome(env, home, opts, signal) {
 }
 function homeViewSourceOver(env, auxiliary) {
     const declared = declaredHomeOf(env);
-    const identity = env.fileIdentity;
     let declaredChain;
-    const readDeclared = () => {
+    const readDeclared = (at) => {
+        const identity = at.fileIdentity;
         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);
+                const spelled = await homeSpellingsOf(at, declared);
+                return spelled.canonical === undefined ? (spelled.answered ? NO_CHAIN : unreadChain(declared)) : await chainAbove(at, identity, spelled.canonical);
+            })(), DEFAULT_GATE_AWAIT_TIMEOUT_MS, undefined, "homeChain").catch(() => unreadChain(declared));
             declaredChain = reading;
             void reading.then((c) => {
                 if (!c.whole && declaredChain === reading)
@@ -276,10 +281,16 @@ function homeViewSourceOver(env, auxiliary) {
         return declaredChain;
     };
     return {
-        views(signal) {
+        views(signal, judgmentEnv) {
+            const at = judgmentEnv ?? env;
+            const identity = at.fileIdentity;
             let index;
+            const unread = [];
             const indexOf = () => (index ??= (async () => {
-                const chains = [await readDeclared(), ...(await Promise.all(auxiliary)).map((a) => a.chain)];
+                const chains = [await readDeclared(at), ...(await Promise.all(auxiliary)).map((a) => a.chain)];
+                for (const at of chains.flatMap((c) => c.unread))
+                    if (!unread.includes(at))
+                        unread.push(at);
                 const out = new Map();
                 for (const { own } of chains)
                     if (own !== undefined && !out.has(own.id))
@@ -300,15 +311,15 @@ function homeViewSourceOver(env, auxiliary) {
                         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 id = await identityOf(at, identity, path, signal);
+                            if (identityUnread(id))
+                                return void unread.push(path);
+                            if (id?.ok === true) {
                                 const at = index.get(id.value);
                                 if (at !== undefined)
                                     return at;
                             }
-                            else if (id.error.code !== "not_found" && id.error.code !== "not_directory")
+                            else if (id?.error.code === "not_supported")
                                 return undefined;
                         }
                         const parent = normalizeAbsPathLexically(`${path}/..`);
@@ -329,6 +340,7 @@ function homeViewSourceOver(env, auxiliary) {
                     const view = await viewOf(spelled, opts?.leaf === "file");
                     return view === undefined || view === spelled ? undefined : view;
                 },
+                unread,
             };
         },
     };
@@ -357,7 +369,7 @@ export function homeViewsAt(env, homes) {
     return homeViewSourceOver(env, readAuxiliaryHomes(env, homes, {}));
 }
 export function homeViewsOf(env, judge, signal) {
-    return (judge?.homeViews ?? homeViewsAt(env, [])).views(signal);
+    return (judge?.homeViews ?? homeViewsAt(env, [])).views(signal, env);
 }
 export function carryHomeViews(judge, source) {
     return { ...judge, homeViews: source };
@@ -421,9 +433,18 @@ export function readDenyPlacedLater(unplaced, place) {
         return current;
     };
     const homeViews = {
-        views(signal) {
+        views(signal, judgmentEnv) {
             let views;
-            return { of: async (path, opts) => await (await (views ??= settled().then((m) => m.homeViews.views(signal)))).of(path, opts) };
+            const unread = [];
+            return {
+                of: async (path, opts) => {
+                    const inner = await (views ??= settled().then((m) => m.homeViews.views(signal, judgmentEnv)));
+                    const view = await inner.of(path, opts);
+                    unread.splice(0, unread.length, ...inner.unread);
+                    return view;
+                },
+                unread,
+            };
         },
     };
     const matcher = {

package/dist/tools/fs/shell-read-check.d.ts

@@ -225,7 +225,7 @@ export interface ShellReadJudgment {
  * gate FOLD's policy on the gate's one deadline seat; the station has never held one on either entry, and a
  * second default here would decide the same number twice and turn a slow-but-correct filesystem's true
  * answer into a fail-closed one unasked. A consumer wanting that posture races its own deadline and reads
- * the row the fold reads: `SHELL_READ_DECISION.unestablishable[seat]`.
+ * the row the gate's fallback reads: `SHELL_READ_DECISION.unanswered[seat]`.
  */
 export declare function judgeShellRead(input: ShellReadJudgeInput): Promise<ShellReadJudgment>;
 /**

package/dist/tools/fs/shell-read-check.js

@@ -1,3 +1,4 @@
+import { observeEnvironment } from "./shell-read-environment.js";
 import { errorResult } from "../../core/tools.js";
 import { BASH_READONLY_CONFINEMENT_NOTE } from "./fs-shared.js";
 import { isAbsoluteForFamily, normalizeAbsPathLexically, pathFamilyOf, violationDetails, withinAnyRoot } from "./safety.js";
@@ -9,7 +10,7 @@ import { createShellReadEstablisher, establishShellReadsLexically } from "./shel
 import { declaredReadDenyHomes, homeViewsAt } from "./read-deny-home.js";
 import { programArgs } from "./shell-read-write-targets.js";
 import { programRow, selectedOptions } from "./program-read-model.js";
-import { allFindings, anyFaceGuards, decideShellRead, decideShellReadForRedirects, denyRowAtOrBelow, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, stationGuards, writeFaceGuards, } from "./shell-read-judge.js";
+import { allFindings, anyFaceGuards, decideShellRead, denyRowAtOrBelow, foldShellReadFindings, judgeEstablishedPlan, readRootGrantCandidateOf, stationGuards, writeFaceGuards, } from "./shell-read-judge.js";
 import { seatOf } from "../../core/tool-name-readings.js";
 import { normalizeReadRootCandidate } from "../../core/read-root-candidate.js";
 import { argvOf, lexShellText } from "../../shell/lex.js";
@@ -21,7 +22,7 @@ function unestablishedDetails() {
     return { type: "read_unestablished", code: "read_unestablished" };
 }
 function findingDetails(finding, paths) {
-    return finding === "unestablishable" || finding === "declined" ? unestablishedDetails() : containmentDetails(paths);
+    return finding === "unestablishable" || finding === "declined" || finding === "unanswered" ? unestablishedDetails() : containmentDetails(paths);
 }
 const REMOVAL_COMMANDS = new Set(["rm", "rmdir"]);
 const WRITES_BENEATH = {
@@ -155,7 +156,7 @@ async function writeGuardsOf(judged, boundary, env, signal) {
         const dir = fold(parentOf(view));
         return writtenBy.some((paths, i) => i !== at && (i < at || concurrent) && paths.some((w) => withinAnyRoot([fold(w)], dir) || withinAnyRoot([dir], fold(w))));
     };
-    const answer = async (view, key) => (await judge(view, { ...(signal !== undefined ? { signal } : {}), ...(key ? { canonical: true } : {}) })) ?? "clear";
+    const answer = async (view, key) => (await judge(view, { fs: env, ...(signal !== undefined ? { signal } : {}), ...(key ? { canonical: true } : {}) })) ?? "clear";
     const asked = [...[...asKey].map(([view, v]) => [view, v, true]), ...[...asSpelling].filter(([view]) => !landingKeys.has(view)).map(([view, v]) => [view, v, false])];
     let unplaced = false;
     let writeProtected = false;
@@ -207,12 +208,15 @@ function findingAccount(fold, boundary) {
         case "outside_roots":
             return `${writes ? "writes" : "reads"} outside the allowed directories for this session: "${fitMiddle(w?.read.target ?? "?", ACCOUNT_PART_MAX)}" is not under ${allowed} ${NOT_AUTO_ALLOWED}`;
         case "unestablishable":
+        case "unanswered":
             if (writes && boundary.writeRoots === undefined)
                 return `this command writes "${fitMiddle(w.read.target ?? w.read.candidate.spelled, ACCOUNT_PART_MAX)}", and this session declares no directories it may write ${NOT_AUTO_ALLOWED}`;
             if (writes)
                 return `where this command writes could not be established${w.read.cause !== undefined ? `: ${fitCause(w.read.cause)}` : ""}, so it cannot be confirmed to write only inside the allowed directories for this session (${allowed}) ${NOT_AUTO_ALLOWED}`;
             if (w?.read.cause !== undefined)
                 return `where this command reads could not be established: ${fitCause(w.read.cause)}, so it cannot be confirmed ${boundary.face === "open" ? "not to read a path the deny list names" : `to read only inside the allowed directories for this session (${allowed})`} ${NOT_AUTO_ALLOWED}`;
+            if (fold.cause !== undefined)
+                return `where this command reads could not be established: ${fitCause(fold.cause)}, so it cannot be confirmed ${boundary.face === "open" ? "not to read a path the deny list names" : `to read only inside the allowed directories for this session (${allowed})`} ${NOT_AUTO_ALLOWED}`;
             if (fold.declined?.baseMove !== undefined)
                 return `"${fitMiddle(fold.declined.text.trim(), ACCOUNT_PART_MAX)}" moves the working directory somewhere this command's text does not settle ${NOT_AUTO_ALLOWED}`;
             if (fold.declined?.unreadProgramText !== undefined)
@@ -276,7 +280,7 @@ const DENY_REFUSAL_NOTE = "The read boundary judges the paths this command names
     "own pattern) reaches into the tree a recursive read walks.";
 function verdictOf(tool, seat, fold, judged, boundary) {
     const redirectsOnly = fold.finding === "outside_roots" && fold.unestablished !== true && outsideFindingsAreRedirections(judged);
-    const disposition = decideShellReadForRedirects(fold.finding, seat, redirectsOnly);
+    const disposition = decideShellRead(fold.finding, seat, { redirectsOnly, narrowedReadFace: fold.unplacedRead === true && boundary.face !== "open" });
     if (disposition === "vouch")
         return { disposition, finding: fold.finding };
     const paths = outsidePathsOf(judged);
@@ -287,14 +291,14 @@ function verdictOf(tool, seat, fold, judged, boundary) {
         return { disposition, finding: fold.finding, ...writes, sentence: r.sentence, ...(r.details !== undefined ? { details: r.details } : {}) };
     }
     const grant = fold.finding === "outside_roots" ? readRootGrantCandidateOf(judged, boundary) : undefined;
-    const containment = fold.finding === "outside_roots" || fold.finding === "unestablishable";
+    const containment = fold.finding === "outside_roots" || fold.finding === "unestablishable" || fold.finding === "unanswered";
     return {
         disposition,
         finding: fold.finding,
         ...writes,
         ...unestablished,
         sentence: findingAccount(fold, boundary),
-        ...(disposition === "mandated" && containment ? { details: findingDetails(fold.finding, paths) } : {}),
+        ...((disposition === "mandated" && containment) || (disposition === "ordinary" && fold.finding === "unestablishable") ? { details: findingDetails(fold.finding, paths) } : {}),
         ...(grant !== undefined ? { readRootCandidate: { dir: grant.dir, ...(grant.covers !== undefined ? { covers: grant.covers } : {}), clearsThisAsk: true } } : {}),
     };
 }
@@ -325,6 +329,7 @@ async function applyAlsoInside(judged, boundary) {
         plan: j.plan,
         guards: j.guards,
         writeGuards: j.writeGuards,
+        ...(j.incomplete !== undefined ? { incomplete: j.incomplete } : {}),
         segments: j.segments.map((s) => ({
             segment: s.segment,
             findings: s.findings.map((f) => (outsideRead(f) && rescued.has(f.read.target) ? { ...f, kind: "none", containment: "inside" } : f)),
@@ -335,13 +340,23 @@ async function applyAlsoInside(judged, boundary) {
 }
 async function runShellReadStation(tool, command, declared, seat, readers, establisher, env, signal) {
     const plan = planShellReads(command, declarationsOf(declared, readers, env.cdPath));
-    const established = await establisher.establish(plan, declared, signal);
+    const door = observeEnvironment(env);
+    const established = await establisher.establish(plan, declared, signal, door);
     const boundary = { ...declared, roots: established.roots };
-    const judged = await applyAlsoInside(judgePlan(plan, established, boundary), boundary);
-    const judgedVerdict = verdictOf(tool, seat, foldShellReadFindings(judged), judged, boundary);
+    const onPlan = await applyAlsoInside(judgePlan(plan, established, boundary), boundary);
+    const judgedNow = () => {
+        const unfinished = door.settled();
+        return unfinished.length > 0 ? { ...onPlan, incomplete: unfinished } : onPlan;
+    };
+    let judged = judgedNow();
+    let judgedVerdict = verdictOf(tool, seat, foldShellReadFindings(judged), judged, boundary);
+    const probesFrom = door.mark();
+    const guarded = judgedVerdict.disposition === "refuse" ? { unplaced: false, writeProtected: false } : await writeGuardsOf(judged, boundary, door.fs, signal);
+    door.silence(probesFrom);
+    judged = judgedNow();
+    judgedVerdict = verdictOf(tool, seat, foldShellReadFindings(judged), judged, boundary);
     const unplaced = unplacedOptionsOf(judged);
-    const placed = writesPlacedOf(judged, boundary);
-    const guarded = judgedVerdict.disposition === "refuse" ? { unplaced: false, writeProtected: false } : await writeGuardsOf(judged, boundary, env, signal);
+    const placed = judgedVerdict.finding !== "unanswered" && writesPlacedOf(judged, boundary);
     const unresolved = judgedVerdict.disposition !== "refuse" && runOrderOf(judged).runs.some((s) => s.findings.some((f) => f.read.written !== undefined && f.read.unresolved === true));
     const facts = { ...judgedVerdict, ...(guarded.writeProtected ? { writeProtected: true } : {}), ...(unresolved ? { targetUnresolved: true } : {}) };
     const verdict = placed && !guarded.unplaced ? { ...facts, writesPlaced: true } : unplaced !== undefined ? { ...facts, unplacedOptions: unplaced } : facts;
@@ -415,13 +430,12 @@ export function createShellReadStation(opts) {
             const boundary = opts.boundaryOf(member, undefined);
             if (boundary === undefined || !(anyFaceGuards(boundary) || boundary.writeTargetJudge !== undefined))
                 return { disposition: "vouch", finding: "none" };
-            const fold = { finding: "unestablishable" };
-            const disposition = decideShellRead("unestablishable", seat);
+            const disposition = decideShellRead("unanswered", seat);
             const account = `${cause}, so where this command reads could not be established ${NOT_AUTO_ALLOWED}`;
             const details = unestablishedDetails();
             if (disposition === "refuse")
-                return { disposition, finding: "unestablishable", sentence: `Error (${toolName}): ${account}. ${BASH_READONLY_CONFINEMENT_NOTE}`, details };
-            return { disposition, finding: fold.finding, sentence: account, ...(disposition === "mandated" ? { details } : {}) };
+                return { disposition, finding: "unanswered", sentence: `Error (${toolName}): ${account}. ${BASH_READONLY_CONFINEMENT_NOTE}`, details };
+            return { disposition, finding: "unanswered", sentence: account, details };
         },
     };
     const admit = async (toolName, toolCallId, command, signal) => {

package/dist/tools/fs/shell-read-environment.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The ONE door between the shell read station's establisher and the execution environment's filesystem.
+ *
+ * The establisher answers "where does each word of this command land" by asking the environment (a resolution, a
+ * directory listing, a stat, a link read). An environment that does not give an answer — an error that is not a
+ * conclusive "not there", a lookup that came back inconclusive — and a bound the station itself stops at are the same
+ * fact for the verdict: the judge did not finish checking the command against the deny rows, so it cannot vouch for it. That
+ * fact is recorded HERE, at the door, once per judgment, not by each producer that happens to remember to mark it: the
+ * establisher and the write guards are handed an {@link ObservedFilesystem}, never the environment, so a lookup they make
+ * cannot escape the record.
+ *
+ * What is NOT a failure: a conclusive absence (`not_found`, `not_directory` — the answer is "nothing there") and an adapter
+ * that declares no filesystem surface (`not_supported` — it keeps the lexical reading). Everything else is.
+ *
+ * ONE decision, taken once per command: a resolver that did not declare its answers authoritative and answered NOTHING AT ALL,
+ * in the whole command, is read as an absence (the lexical reading every such adapter has had). It is a statement about the
+ * command, not about a word or a station: the walks and probes that found the resolver silent are marked
+ * ({@link ObservedEnvironment.silence}), and {@link ObservedEnvironment.settled} — read by whoever made the door, after EVERY
+ * lookup the command makes (the establishment, the write guards) has asked — takes the marked records back only when no lookup
+ * was ever answered. A resolver that answered once has shown it can; a silence after that is a failure, wherever it falls. A
+ * resolver that declared its answers authoritative is never read as an absence.
+ */
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+/** One thing the station could not finish: an environment lookup that gave no answer, or a bound the station stopped at. */
+export interface Incomplete {
+    /** The lookup (`canonicalPath`, `listDir`, `fileInfo`, `readLink`, `fileIdentity`) or `bound`. */
+    readonly op: string;
+    /** The sentence the card discloses ("… cannot be resolved (permission_denied)"). */
+    readonly detail: string;
+}
+/** Only {@link observeEnvironment} mints the brand: a bare environment is not assignable where a door is asked for. */
+declare const OBSERVED: unique symbol;
+/** The environment as the station's paths may use it: every path lookup the engine's resolvers make (`canonicalPath`,
+ *  `listDir`, `fileInfo`, `readLink`, `exists`, `absolutePath`, `canonicalChain`, `fileIdentity`) goes through the door and is
+ *  recorded when it gives no answer; everything else is the environment's own. It IS an `ExecutionEnv` to the resolvers
+ *  (`canonicalizeTarget`, the home views, a deployment's guarded-row provider) — so none of them has to be narrowed — and
+ *  nominal to the station: the establisher, the write guards, the write judgment and the home views are typed over it, so
+ *  none of them can be handed the bare environment, nor a captured one. */
+export type ObservedFilesystem = ExecutionEnv & {
+    readonly [OBSERVED]: true;
+};
+/** The observed door for one command. */
+export interface ObservedEnvironment {
+    readonly fs: ObservedFilesystem;
+    /** Whether the environment DECLARES its `canonicalPath` the authority on where a path lands: its silence is then a failure
+     *  that nothing takes back ({@link silence} does nothing). */
+    readonly authoritative: boolean;
+    /** What the door recorded, in the order it happened, as the command stands on it NOW — the one decision about what a
+     *  silence means, taken on everything asked so far; call it after the last lookup of the command. */
+    settled(): Incomplete[];
+    /** The station stopped at its own bound (more directories or names than it enumerates, a link chain past its hop bound). */
+    bound(detail: string): void;
+    /** Records that came from outside the door and stand as they are: the declared roots' own lookup (`answered`: it was
+     *  answered, which counts as the resolver's answer) and the home views a read could not be placed against. */
+    adopt(records: readonly Incomplete[], answered?: boolean): void;
+    /** Whether the resolver answered a path question (a path, or a conclusive "nothing there") at least once. */
+    answered(): boolean;
+    /** Where a walk's (or a probe's) records start: pass it to {@link silence} once the lookups are done. */
+    mark(): number;
+    /** The lookups since `from` found the resolver silent: their records are taken back by {@link settled} only when the
+     *  resolver never answered anything in the command (and never where it is {@link authoritative}). */
+    silence(from: number): void;
+}
+/** The declared roots, canonicalized ONCE per establisher (through the same door), with what that lookup could not finish —
+ *  merged into every establishment. `known`: the caller already holds them as canonical identities and they are used verbatim
+ *  (re-resolving one that was since swapped for a link would substitute the link's target for the root that was approved). */
+export declare function canonicalRootsOnce(env: ExecutionEnv, readRoots: readonly string[], known: boolean): (signal?: AbortSignal) => Promise<{
+    readonly roots: readonly string[];
+    readonly incomplete: readonly Incomplete[];
+    readonly answered: boolean;
+}>;
+/** Wrap `env` so every lookup that fails inconclusively is recorded; the result a caller sees is the environment's own. */
+export declare function observeEnvironment(env: ExecutionEnv): ObservedEnvironment;
+export {};

package/dist/tools/fs/shell-read-environment.js

@@ -0,0 +1,71 @@
+import { canonicalPathIsAuthoritative } from "../../core/remote-env.js";
+const OBSERVED = Symbol("observedFilesystem");
+const CONCLUSIVE = new Set(["not_found", "not_directory", "not_supported"]);
+const ABSENCES = new Set(["not_found", "not_directory"]);
+export function canonicalRootsOnce(env, readRoots, known) {
+    let once = known ? Promise.resolve({ roots: readRoots, incomplete: [], answered: false }) : undefined;
+    return (signal) => (once ??= (async () => {
+        const seen = observeEnvironment(env);
+        const roots = [];
+        for (const r of readRoots) {
+            const c = await seen.fs.canonicalPath(r, signal);
+            roots.push(c.ok ? c.value : r);
+        }
+        const result = { roots, incomplete: seen.settled(), answered: seen.answered() };
+        if (result.incomplete.length > 0)
+            once = undefined;
+        return result;
+    })());
+}
+export function observeEnvironment(env) {
+    const authoritative = canonicalPathIsAuthoritative(env);
+    const records = [];
+    let answers = 0;
+    const note = (op, path, what, code) => void records.push({ op, detail: `"${path}" ${what} (${code})`, silent: false });
+    const watch = (op, path, what, ask) => new Promise((resolve) => resolve(ask())).then((r) => {
+        if (op === "canonicalPath" && (r.ok || ABSENCES.has(r.error.code)))
+            answers += 1;
+        if (!r.ok && !CONCLUSIVE.has(r.error.code))
+            note(op, path, what, r.error.code);
+        return r;
+    }, (e) => {
+        note(op, path, what, e instanceof Error ? e.name : "threw");
+        throw e;
+    });
+    const look = (op, what, member) => member === undefined ? {} : { [op]: (path, signal) => watch(op, path, what, () => member.call(env, path, signal)) };
+    const overlay = {
+        ...look("canonicalPath", "cannot be resolved", env.canonicalPath),
+        ...look("listDir", "cannot be enumerated", env.listDir),
+        ...look("fileInfo", "cannot be inspected", env.fileInfo),
+        ...look("readLink", "cannot be read as a link", env.readLink),
+        ...look("exists", "cannot be checked", env.exists),
+        ...look("absolutePath", "cannot be made absolute", env.absolutePath),
+        ...look("canonicalChain", "its link chain cannot be read", env.canonicalChain),
+        ...look("fileIdentity", "cannot be identified", env.fileIdentity),
+        [OBSERVED]: true,
+    };
+    const fs = new Proxy(env, {
+        get: (target, prop) => {
+            if (Object.prototype.hasOwnProperty.call(overlay, prop))
+                return overlay[prop];
+            const value = Reflect.get(target, prop, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+        has: (target, prop) => Object.prototype.hasOwnProperty.call(overlay, prop) || Reflect.has(target, prop),
+    });
+    return {
+        fs,
+        authoritative,
+        settled: () => records.filter((r) => answers > 0 || !r.silent).map(({ op, detail }) => ({ op, detail })),
+        bound: (detail) => void records.push({ op: "bound", detail, silent: false }),
+        adopt: (adopted, answered = false) => {
+            for (const r of adopted)
+                records.push({ ...r, silent: false });
+            if (answered)
+                answers += 1;
+        },
+        mark: () => records.length,
+        silence: (from) => (authoritative ? undefined : void records.slice(from).forEach((r) => void (r.silent = true))),
+        answered: () => answers > 0,
+    };
+}

package/dist/tools/fs/shell-read-establish.d.ts

@@ -17,8 +17,8 @@
  *     target, so the target is established where the link lands (read one hop at a time, bounded) — or not at
  *     all when the environment cannot read the link.
  *  2. An unanswerable filesystem manufactures no refusal on its own: a chain no ancestor answered degrades
- *     to the lexical spelling on an environment that declares no authority for its resolver, and is
- *     `unestablishable` on one that does (`canonicalPathIsAuthoritative`).
+ *     to the lexical spelling on an environment that declares no authority for its resolver AND answered nothing
+ *     in the whole command, and is `unestablishable` on one that does (`canonicalPathIsAuthoritative`).
  *  3. An ISOLATED environment stays lexical, disclosed rather than silently degraded: the sandbox is the
  *     containment there and `canonicalPath` is an RPC into a filesystem that is not this host's
  *     (`boundaryIsTheSandbox`). The split is the DECLARED isolation capability, never the remote interface's
@@ -38,6 +38,7 @@
  * call.
  */
 import type { ExecutionEnv } from "../../internal/harness-types.js";
+import { type ObservedEnvironment } from "./shell-read-environment.js";
 import type { ShellReadPlan, ShellReadSegment } from "./shell-read-plan.js";
 import type { EstablishedRead, ShellReadBoundary } from "./shell-read-judge.js";
 import type { HomeViewSource } from "./read-deny-home.js";
@@ -64,8 +65,10 @@ export interface EstablishedPlan {
 export interface ShellReadEstablisher {
     /** Whether this environment is judged lexically (an isolated sandbox — property 3). */
     readonly lexicalOnly: boolean;
-    /** Establish every read candidate of `plan` (nested plans included) against `boundary`'s roots. */
-    establish(plan: ShellReadPlan, boundary: ShellReadBoundary, signal?: AbortSignal): Promise<EstablishedPlan>;
+    /** Establish every read candidate of `plan` (nested plans included) against `boundary`'s roots. Every lookup goes through
+     *  `door` (a fresh one when the caller does not keep it): what the establishment could not finish is recorded THERE, and the
+     *  caller that made the door reads it once, after everything else the command asks of the environment (the write guards) has asked. */
+    establish(plan: ShellReadPlan, boundary: ShellReadBoundary, signal?: AbortSignal, door?: ObservedEnvironment): Promise<EstablishedPlan>;
     /** Establish the same plan again and report every candidate whose canonical target moved — the pre-spawn
      *  identity re-check. Candidates that were lexical or unestablishable are not compared: nothing was
      *  established to move. */
@@ -84,6 +87,7 @@ export declare function establishShellReadsLexically(plan: ShellReadPlan, bounda
  * as declared (canonical by contract); they are resolved once more per instance because the comparison is
  * against `realpath` output on both sides — an aliased root would otherwise refuse every read under itself.
  * `homeViews`: the home views of the placement the deny seats were compiled at (read-deny-home.ts); absent, the declared home's.
+ * Each establishment asks the environment through ONE observed door ({@link observeEnvironment}), the caller's when it keeps one.
  */
 export declare function createShellReadEstablisher(env: ExecutionEnv, readRoots: readonly string[], opts?: {
     readonly rootsCanonical?: boolean;

package/dist/tools/fs/shell-read-establish.js

@@ -1,5 +1,6 @@
+import { canonicalRootsOnce, observeEnvironment } from "./shell-read-environment.js";
 import { anchorSpelling, normalizeAbsPathLexically, pathFamilyOf } from "./safety.js";
-import { boundaryIsTheSandbox, canonicalPathIsAuthoritative } from "../../core/remote-env.js";
+import { boundaryIsTheSandbox } from "../../core/remote-env.js";
 import { resolveOperandSpellings } from "./bash-readonly-classifier.js";
 import { judgedCandidatesOf, sedBackupNames } from "./shell-read-write-targets.js";
 import { movedReads, withHomeViews } from "./shell-read-identity.js";
@@ -196,33 +197,44 @@ export function establishShellReadsLexically(plan, boundary) {
 }
 export function createShellReadEstablisher(env, readRoots, opts) {
     const lexicalOnly = boundaryIsTheSandbox(env);
-    const resolverIsAuthoritative = canonicalPathIsAuthoritative(env);
+    const canonicalRoots = canonicalRootsOnce(env, readRoots, opts?.rootsCanonical === true);
+    const legOver = (seen) => establishLegOver(seen, readRoots);
+    return {
+        lexicalOnly,
+        establish: async (plan, boundary, signal, door = observeEnvironment(env)) => {
+            if (lexicalOnly)
+                return establishShellReadsLexically(plan, boundary);
+            const { roots, incomplete, answered } = await canonicalRoots(signal);
+            door.adopt(incomplete, answered);
+            return await withHomeViews(door, opts, await legOver(door)(plan, { ...boundary, roots }, roots, signal), signal);
+        },
+        reestablish: async (previous, boundary, signal) => {
+            if (lexicalOnly)
+                return { changed: [] };
+            const again = await legOver(observeEnvironment(env))(previous.plan, { ...boundary, roots: previous.roots }, previous.roots, signal);
+            return { changed: movedReads(previous, again) };
+        },
+    };
+}
+function establishLegOver(seen, readRoots) {
+    const env = seen.fs;
+    const resolverIsAuthoritative = seen.authoritative;
+    const bounded = (detail) => (seen.bound(detail), { unverifiable: detail });
     const family = pathFamilyOf({ root: readRoots[0] ?? "/" });
     const SEP = family === "posix" ? /\// : /[\\/]/;
     const TRAILING_SEP = family === "posix" ? /\/+$/ : /[\\/]+$/;
     const joinUnder = (dir, name) => `${dir.replace(TRAILING_SEP, "")}/${name}`;
-    let rootsOnce = opts?.rootsCanonical === true ? Promise.resolve(readRoots) : undefined;
-    const canonicalRoots = async (signal) => {
-        rootsOnce ??= (async () => {
-            const out = [];
-            for (const r of readRoots) {
-                const c = await env.canonicalPath(r, signal);
-                out.push(c.ok ? c.value : r);
-            }
-            return out;
-        })();
-        return await rootsOnce;
-    };
     const resolveWithoutParentSteps = async (p, signal, writeTarget = false, linkHops = WRITE_LINK_HOPS) => {
         const parts = p.split(SEP);
         const tail = [];
         let allAbsent = true;
+        const began = seen.mark();
         while (parts.length > 0) {
             const at = parts.join("/") || "/";
             const canon = await env.canonicalPath(at, signal);
             if (!canon.ok && canon.error.code === "not_found" && writeTarget && allAbsent) {
                 const entry = await env.fileInfo(at, signal);
-                const link = entry.ok && entry.value.kind === "symlink" && linkHops > 0 ? await env.readLink?.(at, signal) : undefined;
+                const link = entry.ok && entry.value.kind === "symlink" ? (linkHops > 0 ? await env.readLink?.(at, signal) : void bounded(`"${at}" is a link chain of more than ${WRITE_LINK_HOPS} links, too many to follow to verify where it lands`)) : undefined;
                 if (link?.ok === true) {
                     const landing = anchorSpelling(family, parts.slice(0, -1).join("/") || "/", link.value);
                     return await resolve([landing, ...[...tail].reverse()].join("/"), signal, true, linkHops - 1);
@@ -239,7 +251,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
                 allAbsent = false;
             tail.push(parts.pop());
         }
-        return undefined;
+        return void seen.silence(began);
     };
     const parentOf = (canonical) => normalizeAbsPathLexically(`${canonical}/..`);
     const resolve = async (p, signal, writeTarget = false, linkHops = WRITE_LINK_HOPS) => {
@@ -318,7 +330,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
             const next = [];
             for (const dir of frontier) {
                 if (++dirsUsed > MAX_GLOB_DIRS)
-                    return { unverifiable: `"${p}" expands over more than ${MAX_GLOB_DIRS} directories, too many to enumerate to verify` };
+                    return bounded(`"${p}" expands over more than ${MAX_GLOB_DIRS} directories, too many to enumerate to verify`);
                 const canonDir = await resolve(dir, signal);
                 if (canonDir !== undefined && canonDir.missing === true)
                     continue;
@@ -340,7 +352,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
                     if (!globSegmentMatches(re, seg, entry.name))
                         continue;
                     if (++matches > MAX_GLOB_MATCHES)
-                        return { unverifiable: `"${p}" expands to more than ${MAX_GLOB_MATCHES} names, too many to enumerate to verify` };
+                        return bounded(`"${p}" expands to more than ${MAX_GLOB_MATCHES} names, too many to enumerate to verify`);
                     const candidate = joinUnder(dir, entry.name);
                     if (canonDirHere !== undefined && entry.kind !== "symlink")
                         canonicalOfMatch.set(candidate, joinUnder(canonDirHere, entry.name));
@@ -363,7 +375,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         while (stack.length > 0) {
             const { dir, spell } = stack.pop();
             if (++dirsUsed > MAX_GLOB_DIRS)
-                return { unverifiable: `"${rootCanonical}" holds more than ${MAX_GLOB_DIRS} directories, too many to enumerate to verify what a recursive read would open` };
+                return bounded(`"${rootCanonical}" holds more than ${MAX_GLOB_DIRS} directories, too many to enumerate to verify what a recursive read would open`);
             const listed = await env.listDir(dir, signal);
             if (!listed.ok) {
                 if (dir === rootCanonical && listed.error.code === "not_directory")
@@ -377,7 +389,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
                 root = "directory";
             for (const entry of listed.value) {
                 if (found.length >= MAX_GLOB_MATCHES)
-                    return { unverifiable: `"${rootCanonical}" holds more than ${MAX_GLOB_MATCHES} entries, too many to enumerate to verify what a recursive read would open` };
+                    return bounded(`"${rootCanonical}" holds more than ${MAX_GLOB_MATCHES} entries, too many to enumerate to verify what a recursive read would open`);
                 const path = joinUnder(spell, entry.name);
                 const canonicalPath = joinUnder(dir, entry.name);
                 if (entry.kind === "symlink") {
@@ -453,7 +465,7 @@ export function createShellReadEstablisher(env, readRoots, opts) {
             const dir = name.slice(0, name.search(/[^/]*$/));
             name = dir === "" ? link.value : anchorSpelling(family, dir, link.value);
         }
-        return undefined;
+        return void bounded(`"${spelled}" is a link chain of more than ${WRITE_LINK_HOPS} links, too many to follow to verify where its backup is written`);
     };
     const followedBackupReads = async (j, boundary, signal) => {
         const { operand, suffix } = j.followed;
@@ -601,19 +613,5 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         }
         return { plan, reads, nested, roots };
     };
-    return {
-        lexicalOnly,
-        establish: async (plan, boundary, signal) => {
-            if (lexicalOnly)
-                return establishShellReadsLexically(plan, boundary);
-            const roots = await canonicalRoots(signal);
-            return await withHomeViews(env, opts, await establishPlan(plan, { ...boundary, roots }, roots, signal), signal);
-        },
-        reestablish: async (previous, boundary, signal) => {
-            if (lexicalOnly)
-                return { changed: [] };
-            const again = await establishPlan(previous.plan, { ...boundary, roots: previous.roots }, previous.roots, signal);
-            return { changed: movedReads(previous, again) };
-        },
-    };
+    return establishPlan;
 }

package/dist/tools/fs/shell-read-identity.d.ts

@@ -8,8 +8,9 @@
  * matched, or onto a home shadow's target, left the pool unchanged and the call was admitted unjudged.
  */
 import type { EstablishedPlan } from "./shell-read-establish.js";
+import type { ObservedEnvironment } from "./shell-read-environment.js";
 import type { EstablishedRead } from "./shell-read-judge.js";
-import { type HomeViewEnv, type HomeViewsCarrier } from "./read-deny-home.js";
+import { type HomeViewsCarrier } from "./read-deny-home.js";
 /** Every read of either establishment whose candidate's settled target set differs between the two. */
 export declare function movedReads(previous: EstablishedPlan, again: EstablishedPlan): EstablishedRead[];
 /**
@@ -18,4 +19,4 @@ export declare function movedReads(previous: EstablishedPlan, again: Established
  * spelled through. The views are `placed`'s — the home views of the placement the boundary's deny seats were compiled
  * at. A read that did not land (lexical, unestablishable) is left as it is.
  */
-export declare function withHomeViews(env: HomeViewEnv, placed: HomeViewsCarrier | undefined, established: EstablishedPlan, signal?: AbortSignal): Promise<EstablishedPlan>;
+export declare function withHomeViews(door: Pick<ObservedEnvironment, "fs" | "adopt">, placed: HomeViewsCarrier | undefined, established: EstablishedPlan, signal?: AbortSignal): Promise<EstablishedPlan>;