@sema-agent/core 7.50.2 → 7.51.0

package/dist/stores/file/session-policy-store.js

@@ -1,6 +1,6 @@
 import { readFileSync, readdirSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
-import { assertSessionRuleNamesCurrent, loosenReasons, normalizeRules, readMountedToolNames, stripRev, SessionPolicyError, } from "../../core/session-policy-store.js";
+import { judgeSessionRulesWrite, readMountedToolNames, readSessionRulesShape, SessionPolicyError, } from "../../core/session-policy-store.js";
 import { atomicWriteFile, ensureDir, sanitizeScope } from "./fs-atomic.js";
 import { guardCorruptSink } from "./corrupt-read-sink.js";
 import { assertAdoptionBootGate, readRootAdoptionFile } from "./adoption/marker.js";
@@ -52,13 +52,12 @@ export function judgeSessionPolicyRowShape(row) {
         return bad("rev is not a positive number");
     if (row.gen !== undefined && (typeof row.gen !== "number" || !Number.isInteger(row.gen) || row.gen < 0))
         return bad("gen is not a whole number");
-    const strArr = (x) => x === undefined || (Array.isArray(x) && x.every((e) => typeof e === "string"));
-    if (!strArr(row.toolAllow) || !strArr(row.toolDeny) || !strArr(row.commandAllow) || !strArr(row.commandDeny) || !strArr(row.allowDirs)) {
-        return bad("malformed rule field");
-    }
     const { __sid: _sid, __principal: _principal, ...clean } = row;
     void _sid;
     void _principal;
+    const shaped = readSessionRulesShape(clean);
+    if ("fault" in shaped)
+        return bad(shaped.sentence);
     return { rules: clean };
 }
 export function attributeSessionPolicyRow(dir, file, row) {
@@ -184,17 +183,7 @@ export class FileSessionPolicyStore {
     }
     async putRules(sessionId, principal, rules, opts) {
         const prior = this.read(sessionId, principal);
-        if (opts?.expectedRev !== undefined && (prior?.rev ?? 0) !== opts.expectedRev) {
-            throw new SessionPolicyError("conflict", `session rules rev mismatch (expected ${opts.expectedRev}, have ${prior?.rev ?? 0})`);
-        }
-        const clean = normalizeRules(stripRev(rules));
-        assertSessionRuleNamesCurrent(clean, this.mountedToolNames);
-        if (prior && opts?.operator !== true) {
-            const loosens = loosenReasons(prior, clean, this.mountedToolNames);
-            if (loosens.length > 0) {
-                throw new SessionPolicyError("loosen_forbidden", `a non-operator session-rule write may only tighten; refused: ${loosens.join("; ")}`);
-            }
-        }
+        const clean = judgeSessionRulesWrite(prior, rules, opts, this.mountedToolNames);
         const mark = this.readMark(sessionId, principal);
         if (mark?.__lineage === "lost") {
             throw new SessionPolicyError("corrupt", `session rules for ${JSON.stringify(sessionId)} have no lineage evidence (the erase left a lost-lineage mark) — refusing to restart the key's lineage by guessing; delete the mark to restart it`);

package/dist/tools/artifact/artifact-tool.js

@@ -5,6 +5,7 @@ import { Type } from "typebox";
 import { ARTIFACT_ACTION_CONCURRENCY_SAFE, ARTIFACT_COMMIT_THROW_OUTCOME, ARTIFACT_FAILURE_RESULT_CODE, ARTIFACT_HOST_ERROR_CODE, ARTIFACT_LIST_SCOPES, ARTIFACT_PLANE_CONTENT_ORIGIN, ARTIFACT_PUBLISH_CONTEXTS, } from "../../core/artifact-host.js";
 import { ARTIFACT_TOOL_NAME, toolFace } from "../../core/tool-catalog-entries.js";
 import { resolveAsk } from "../../core/tool-policy.js";
+import { NOT_BINDABLE } from "../../core/skill-grant-binding.js";
 import { approvalCardOf } from "../../core/tool-roster.js";
 import { errorResult } from "../../core/tools.js";
 import { inlineUntrusted } from "../../core/untrusted-text.js";
@@ -345,6 +346,7 @@ export function createArtifactTool(opts) {
                 message: `Read a shared artifact: ${inlineUntrusted(url, 300)}${title}${version} — an artifact another person shared with this user; approving covers re-reads of it for the rest of this run.`,
                 requiresRealApproval: true,
                 approvalCard: approvalCardOf({ toolName: ARTIFACT_TOOL_NAME }, toolFace("artifact").renderHints?.approvalCard),
+                ...NOT_BINDABLE,
             }, onAsk, ctx.signal);
             if (resolved.action !== "allow")
                 return { ok: false, reason: resolved.message ?? "not approved" };

package/dist/tools/fs/image-admission.d.ts

@@ -1,7 +1,7 @@
 /**
  * The ONE admission an image's bytes pass before they reach the model as an `ImageContent` block —
- * whether a file supplied them (the Read tool's image lane) or a caller did (`TaskSpec.images`' inline
- * arm). Four steps, in this order:
+ * whether a file supplied them (the Read tool's image lane), a caller did (`TaskSpec.images`' inline
+ * arm, a user attachment) or a tool returned them (the tool-result seat below). Four steps, in this order:
  *
  *   ① the claimed type is one the content API accepts (png / jpeg / gif / webp — the four
  *      {@link imageMagicMatches} can verify);
@@ -14,10 +14,19 @@
  *
  * The answer is structured; each carrier words its own refusal (the Read tool speaks to the model, the
  * task door to the caller). The block it admits is built from the bytes it checked — never from a
- * caller's string it did not decode.
+ * caller's string it did not decode. A document's bytes pass the same shape of admission
+ * ({@link admitDocumentBytes}: `application/pdf`, the whole-send cap, the `%PDF-` signature).
+ *
+ * THE TOOL-RESULT SEAT ({@link admitToolResultMedia}): every executed call's result passes the loop's one
+ * post-execution half (`finalizeToolOutcome`) — an engine tool's, an MCP tool's converted content, a host
+ * tool's own return, a resumed approved call's, and whatever a `tool_result` hook put in their place — so
+ * the media blocks of every supply are admitted there, once, after the last hand that can change them and
+ * before the frame and the transcript read them. A block whose bytes the admission refuses becomes a text
+ * block that names the tool, the refusal and the size — never the bytes, and never silently nothing.
  */
-import type { ImageContent } from "../../internal/llm.js";
+import type { DocumentContent, ImageContent } from "../../internal/llm.js";
 import { type ImageDimensions, type ImageDownsampler } from "../../core/mcp.js";
+import { type MediaBlock } from "../../core/media-byte-cap.js";
 /** The image types the content API accepts — the only ones a signature check can verify. */
 export declare const ADMITTED_IMAGE_MIME_TYPES: readonly ["image/png", "image/jpeg", "image/gif", "image/webp"];
 /** The raw-byte read cap for an image, with or without a downsampler. */
@@ -49,3 +58,47 @@ export type ImageAdmission = {
     base64: string;
 };
 export declare function admitImageBytes(bytes: Uint8Array, claimedMime: string, downsampler: ImageDownsampler | undefined): Promise<ImageAdmission>;
+/** The document types the content API accepts — the one a signature check can verify. */
+export declare const ADMITTED_DOCUMENT_MIME_TYPES: readonly ["application/pdf"];
+export type DocumentAdmission = {
+    ok: true;
+    block: DocumentContent;
+    originalSize: number;
+} | {
+    ok: false;
+    reason: "mime_unsupported" | "magic_mismatch";
+    rawBytes: number;
+} | {
+    ok: false;
+    reason: "raw_too_large";
+    rawBytes: number;
+    cap: number;
+};
+/** A document's bytes: the claimed type is `application/pdf`, the raw bytes are within the whole-send cap
+ *  ({@link PDF_TARGET_RAW_SIZE}, the Read tool's), and they start with `%PDF-`. */
+export declare function admitDocumentBytes(bytes: Uint8Array, claimedMime: string): DocumentAdmission;
+/** Why the tool-result seat refused a media block: the admissions' own words (an image's four — a document's are among
+ *  them), or `undecodable` — the block carried no base64 string to decode. */
+export type MediaRefusalReason = "undecodable" | "mime_unsupported" | "raw_too_large" | "magic_mismatch" | "base64_too_large";
+/** One media block the seat refused: its type, the refusal, its decoded size, the bound it exceeded (the raw-byte cap for
+ *  `raw_too_large`, the base64 length limit for `base64_too_large`), and its media type when it can be one. */
+export interface ToolResultMediaRefusal {
+    type: MediaBlock["type"];
+    reason: MediaRefusalReason;
+    bytes: number;
+    limit?: number;
+    mimeType?: string;
+}
+/** What the seat made of one result's content: every media block rebuilt from its checked bytes or replaced, in its slot,
+ *  by its placeholder; and the refusals. */
+export interface ToolResultMediaAdmission {
+    content: unknown[];
+    refused: ToolResultMediaRefusal[];
+}
+/**
+ * The tool-result seat's admission over one executed call's content: `undefined` when no block claims a media type (the
+ * content stands as it is, and nothing is awaited); otherwise every block is read once into a new array, each media
+ * block admitted — rebuilt from the bytes it checked, or replaced in its slot by a placeholder naming `toolName` and the
+ * refusal. Total: a content whose blocks cannot be read is not media this seat can admit or refuse, and is left as it is.
+ */
+export declare function admitToolResultMedia(content: unknown, toolName: string): Promise<ToolResultMediaAdmission> | undefined;

package/dist/tools/fs/image-admission.js

@@ -1,6 +1,9 @@
 import { MCP_IMAGE_MAX_BASE64 } from "../../core/mcp.js";
+import { claimedMediaType } from "../../core/media-byte-cap.js";
+import { readMember } from "../../core/thrown-value.js";
 import { imageMagicMatches } from "./safety.js";
 import { MAX_IMAGE_READ_BYTES, MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES } from "./fs-shared.js";
+import { PDF_TARGET_RAW_SIZE, pdfMagicMatches } from "./pdf.js";
 export const ADMITTED_IMAGE_MIME_TYPES = Object.freeze(["image/png", "image/jpeg", "image/gif", "image/webp"]);
 export function imageReadCap(downsampler) {
     return downsampler ? MAX_IMAGE_DOWNSAMPLE_INPUT_BYTES : MAX_IMAGE_READ_BYTES;
@@ -34,3 +37,85 @@ export async function admitImageBytes(bytes, claimedMime, downsampler) {
         (dimensions.originalWidth !== dimensions.displayWidth || dimensions.originalHeight !== dimensions.displayHeight);
     return { ok: true, block: { type: "image", data: base64, mimeType }, originalSize: rawBytes, ...(dimensions !== undefined ? { dimensions } : {}), resized };
 }
+export const ADMITTED_DOCUMENT_MIME_TYPES = Object.freeze(["application/pdf"]);
+export function admitDocumentBytes(bytes, claimedMime) {
+    const rawBytes = bytes.byteLength;
+    if (!ADMITTED_DOCUMENT_MIME_TYPES.includes(claimedMime))
+        return { ok: false, reason: "mime_unsupported", rawBytes };
+    if (rawBytes > PDF_TARGET_RAW_SIZE)
+        return { ok: false, reason: "raw_too_large", rawBytes, cap: PDF_TARGET_RAW_SIZE };
+    if (!pdfMagicMatches(bytes))
+        return { ok: false, reason: "magic_mismatch", rawBytes };
+    return { ok: true, block: { type: "document", data: Buffer.from(bytes).toString("base64"), mimeType: claimedMime }, originalSize: rawBytes };
+}
+const mediaTypeEcho = (mime) => typeof mime === "string" && /^[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}\/[A-Za-z0-9][A-Za-z0-9!#$&^_.+-]{0,126}$/.test(mime) ? mime : undefined;
+const ADMITTED_FOR = { image: ADMITTED_IMAGE_MIME_TYPES, document: ADMITTED_DOCUMENT_MIME_TYPES };
+const REFUSAL_CLAUSE = {
+    undecodable: () => "it carried no base64 payload",
+    mime_unsupported: (r) => `${r.mimeType ?? "its media type"} is not a ${r.type} type the model accepts (${ADMITTED_FOR[r.type].join(", ")})`,
+    raw_too_large: (r) => `its ${r.bytes} bytes exceed the ${r.limit}-byte cap`,
+    magic_mismatch: (r) => `its ${r.bytes} bytes do not carry the ${r.mimeType} signature`,
+    base64_too_large: (r) => `its base64 encoding exceeds the ${r.limit}-character provider limit (${r.bytes} bytes)`,
+};
+const placeholderOf = (toolName, r) => ({
+    type: "text",
+    text: `[${r.type} from the ${JSON.stringify(toolName)} tool not shown: ${REFUSAL_CLAUSE[r.reason](r)} (media admission: ${r.reason})]`,
+});
+const claimsMedia = (block) => claimedMediaType(block) !== undefined;
+async function admitBlock(block) {
+    const type = claimedMediaType(block);
+    if (type === undefined)
+        return { block };
+    const data = readMember(block, "data");
+    const mime = readMember(block, "mimeType");
+    const echo = mediaTypeEcho(mime);
+    const refusal = (reason, bytes, limit) => ({
+        refusal: { type, reason, bytes, ...(limit !== undefined ? { limit } : {}), ...(echo !== undefined ? { mimeType: echo } : {}) },
+    });
+    if (typeof data !== "string")
+        return refusal("undecodable", 0);
+    let a;
+    try {
+        const bytes = Buffer.from(data, "base64");
+        const claimed = typeof mime === "string" ? mime : "";
+        a = type === "image" ? await admitImageBytes(bytes, claimed, undefined) : admitDocumentBytes(bytes, claimed);
+    }
+    catch {
+        return refusal("undecodable", 0);
+    }
+    if (a.ok)
+        return { block: a.block };
+    if (a.reason === "raw_too_large")
+        return refusal(a.reason, a.rawBytes, a.cap);
+    if (a.reason === "base64_too_large")
+        return refusal(a.reason, a.rawBytes, MCP_IMAGE_MAX_BASE64);
+    return refusal(a.reason, a.rawBytes);
+}
+export function admitToolResultMedia(content, toolName) {
+    let blocks;
+    try {
+        if (!Array.isArray(content))
+            return undefined;
+        blocks = Array.from(content);
+        if (!blocks.some(claimsMedia))
+            return undefined;
+    }
+    catch {
+        return undefined;
+    }
+    return (async () => {
+        const refused = [];
+        const out = [];
+        for (const b of blocks) {
+            const r = await admitBlock(b);
+            if ("block" in r) {
+                out.push(r.block);
+            }
+            else {
+                refused.push(r.refusal);
+                out.push(placeholderOf(toolName, r.refusal));
+            }
+        }
+        return { content: out, refused };
+    })();
+}

package/dist/tools/fs/path-containment.d.ts

@@ -0,0 +1,2 @@
+/** Is `p` the root itself or inside it, both read physically? */
+export declare function isPhysicallyWithin(root: string, p: string): boolean;

package/dist/tools/fs/path-containment.js

@@ -0,0 +1,5 @@
+import { physicalPathOfExisting } from "../../core/physical-path.js";
+import { withinAnyRoot } from "./safety.js";
+export function isPhysicallyWithin(root, p) {
+    return withinAnyRoot([physicalPathOfExisting(root)], physicalPathOfExisting(p));
+}

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

@@ -40,9 +40,30 @@ declare function unestablishedDetails(): {
 /** The structured details a refusal or a mandated card carries: the deny card is the read faces' own (`violationDetails`,
  *  safety.ts), the containment and the unestablished cards are minted above. */
 export type ShellReadRefusalDetails = NonNullable<ReturnType<typeof violationDetails>> | ReturnType<typeof containmentDetails> | ReturnType<typeof unestablishedDetails>;
-/** What the station answers for ONE call. */
-export interface ShellReadVerdict {
-    readonly disposition: ShellReadDisposition;
+/**
+ * What the station answers for ONE call: a VOUCH — the finding `none`, nothing beside it but the facts — or a QUESTION, a
+ * disposition the decision table gives its finding ({@link import("./shell-read-judge.js").dispositionsOfRow}). A vouch carries no
+ * finding, no silence mark and no card: the table vouches on the `none` row alone
+ * ({@link import("./shell-read-judge.js").VouchOnlyOnTheNoneRow}), so a vouch beside anything else is a contradiction — one this
+ * type cannot spell, and one every reader of a station's answer refuses where an untyped station spells it anyway
+ * ({@link import("../../core/shell-read-silence.js").readStationAnswer}).
+ */
+export type ShellReadVerdict = ShellReadVouch | ShellReadQuestion;
+/** The station has no question about the call. */
+export interface ShellReadVouch extends ShellReadVerdictFacts {
+    readonly disposition: "vouch";
+    readonly finding: "none";
+    readonly environmentSilent?: never;
+    readonly rowsUnread?: never;
+    readonly face?: never;
+    readonly sentence?: never;
+    readonly details?: never;
+    readonly readRootCandidate?: never;
+    readonly unestablished?: never;
+}
+/** The station refuses the call or puts a question about it. */
+export interface ShellReadQuestion extends ShellReadVerdictFacts {
+    readonly disposition: Exclude<ShellReadDisposition, "vouch">;
     readonly finding: ShellReadFinding;
     /** The environment did not answer the judgment — a resolver, a listing or an identity lookup gave no answer, a bound was
      *  reached, the judge itself did not answer: present on the `unanswered` finding the fold or the fallback gives. The gate
@@ -66,6 +87,13 @@ export interface ShellReadVerdict {
     readonly details?: ShellReadRefusalDetails;
     /** `mandated` on an `outside_roots` finding: the directory whose grant would clear this ask. */
     readonly readRootCandidate?: ReadRootGrantCandidate;
+    /** A FACT beside the disposition: some read of the command could not be established (an `unestablishable` or `declined`
+     *  finding anywhere in it, whichever finding won). A mode that releases the call releases it past the read-deny table. */
+    readonly unestablished?: true;
+}
+/** The FACTS a station's answer may carry beside either disposition — about what the command writes, read by the modes that
+ *  answer file commands and by the write classes, never by the read table — and the admission the applying reader activates. */
+export interface ShellReadVerdictFacts {
     /** A FACT beside the disposition, for the mode that answers a file command itself: every write target this command
      *  names was established inside the boundary's WRITE roots at every seat the program writes it (the entry, where it
      *  lands, or both — `WriteSeat`, shell-read-write-targets.ts), off the write-protection table and off every deployment
@@ -91,9 +119,6 @@ export interface ShellReadVerdict {
     readonly unplacedOptions?: {
         readonly program: "cp" | "mv";
     };
-    /** A FACT beside the disposition: some read of the command could not be established (an `unestablishable` or `declined`
-     *  finding anywhere in it, whichever finding won). A mode that releases the call releases it past the read-deny table. */
-    readonly unestablished?: true;
     /** The station's admission of this call's judged target, activated only by the caller that APPLIES this verdict (the
      *  gate's fold, the resumed leg's belt): a verdict nobody received — a wait that elapsed, a judgment that threw —
      *  admits nothing, whenever it completes. */

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

@@ -288,7 +288,7 @@ function verdictOf(tool, seat, fold, judged, boundary) {
     const redirectsOnly = fold.finding === "outside_roots" && fold.unestablished !== true && outsideFindingsAreRedirections(judged);
     const disposition = decideShellRead(fold.finding, seat, { redirectsOnly, narrowedReadFace: fold.unplacedRead === true && boundary.face !== "open" });
     if (disposition === "vouch")
-        return { disposition, finding: fold.finding };
+        return { disposition, finding: "none" };
     const paths = outsidePathsOf(judged);
     const unestablished = fold.unestablished === true ? { unestablished: true } : {};
     const face = faceOf(fold);
@@ -354,14 +354,12 @@ async function runShellReadStation(tool, command, declared, seat, readers, estab
     const boundary = { ...declared, roots: established.roots };
     const onPlan = await applyAlsoInside(judgePlan(plan, established, boundary), boundary);
     const judgedNow = () => {
-        const unfinished = door.settled();
+        const unfinished = door.incomplete();
         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);

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

@@ -10,15 +10,10 @@
  * 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.
+ * that has no filesystem surface (`not_supported` — its answer that there is no file face: a chain it answers so keeps the
+ * lexical reading). Everything else is, and is recorded wherever it falls — a resolver that answered nothing at all in the
+ * command included: a lookup that failed (`permission_denied`, `timeout`, `unknown`, a throw) is a resolver failing, whose
+ * identity of the words cannot be judged, never an adapter without a file face.
  */
 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. */
@@ -42,24 +37,15 @@ export type ObservedFilesystem = ExecutionEnv & {
 /** 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). */
+    /** Whether the environment DECLARES its `canonicalPath` the authority on where a path lands: a chain it does not answer at all
+     *  is then not placed (the establishment's reading; the door records the lookups alike either way). */
     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[];
+    /** What the door recorded, in the order it happened; call it after the last lookup of the command. */
+    incomplete(): 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;
+    /** Records that came from outside the door: the declared roots' own lookup and the home views a read could not be placed against. */
+    adopt(records: readonly Incomplete[]): 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
@@ -67,7 +53,6 @@ export interface ObservedEnvironment {
 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;

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

@@ -1,9 +1,8 @@
 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;
+    let once = known ? Promise.resolve({ roots: readRoots, incomplete: [] }) : undefined;
     return (signal) => (once ??= (async () => {
         const seen = observeEnvironment(env);
         const roots = [];
@@ -11,7 +10,7 @@ export function canonicalRootsOnce(env, readRoots, known) {
             const c = await seen.fs.canonicalPath(r, signal);
             roots.push(c.ok ? c.value : r);
         }
-        const result = { roots, incomplete: seen.settled(), answered: seen.answered() };
+        const result = { roots, incomplete: seen.incomplete() };
         if (result.incomplete.length > 0)
             once = undefined;
         return result;
@@ -20,11 +19,8 @@ export function canonicalRootsOnce(env, readRoots, known) {
 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 note = (op, path, what, code) => void records.push({ op, detail: `"${path}" ${what} (${code})` });
     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;
@@ -56,16 +52,8 @@ export function observeEnvironment(env) {
     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,
+        incomplete: () => records.map(({ op, detail }) => ({ op, detail })),
+        bound: (detail) => void records.push({ op: "bound", detail }),
+        adopt: (adopted) => void records.push(...adopted.map(({ op, detail }) => ({ op, detail }))),
     };
 }

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

@@ -17,8 +17,9 @@
  *     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 answered nothing
- *     in the whole command, and is `unestablishable` on one that does (`canonicalPathIsAuthoritative`).
+ *     to the lexical spelling on an environment that declares no authority for its resolver, and is `unestablishable` on
+ *     one that does (`canonicalPathIsAuthoritative`); only `not_supported` (no file face) is no failure — any other non-answer
+ *     is recorded at the door and the command is `unanswered` (shell-read-environment.ts).
  *  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

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

@@ -174,7 +174,8 @@ function writtenByText(plan, boundary) {
 }
 function unfollowedBackupReads(j, boundary, cause) {
     const spellings = sedBackupNames(j.followed.operand.spelled, j.followed.suffix).flatMap((name) => lexicalReadsOf({ ...j.candidate, spelled: name }, boundary).flatMap((r) => [...(r.target !== undefined ? [r.target] : []), ...r.spellings]));
-    return [{ candidate: j.candidate, established: "unestablishable", spellings: [...new Set(spellings)], cause }];
+    const read = { candidate: j.candidate, established: "unestablishable", spellings: [...new Set(spellings)], cause };
+    return (j.seats ?? ["landing"]).map((seat) => writtenAt(read, j, seat));
 }
 function writtenAt(read, j, seat) {
     if (read.candidate.face !== "write" || !(j.written ?? j.seats ?? ["landing"]).includes(seat))
@@ -205,8 +206,8 @@ export function createShellReadEstablisher(env, readRoots, opts) {
         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);
+            const { roots, incomplete } = await canonicalRoots(signal);
+            door.adopt(incomplete);
             return await withHomeViews(door, opts, await legOver(door)(plan, { ...boundary, roots }, roots, signal), signal);
         },
         reestablish: async (previous, boundary, signal) => {
@@ -229,7 +230,6 @@ function establishLegOver(seen, readRoots) {
         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);
@@ -252,7 +252,7 @@ function establishLegOver(seen, readRoots) {
                 allAbsent = false;
             tail.push(parts.pop());
         }
-        return void seen.silence(began);
+        return undefined;
     };
     const parentOf = (canonical) => normalizeAbsPathLexically(`${canonical}/..`);
     const resolve = async (p, signal, writeTarget = false, linkHops = WRITE_LINK_HOPS) => {

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

@@ -52,14 +52,18 @@ export type RankTableCoversEveryFinding = AssertAllKeysHandled<Exclude<ShellRead
  *  the auto-mode classifier, a stored allow rule) but no answerless engine table may; `vouch` = the station
  *  has no question. */
 export type ShellReadDisposition = "refuse" | "mandated" | "ordinary" | "vouch";
-/** One cell of the decision table: a disposition, or — where the READ FACE the question was raised under decides it — the two
- *  readings, `narrowed` (the `roots` face: the fence the deployment narrowed, and the engine default) and `open`. */
+/** One cell of the decision table: a disposition, or — where the FORM of the question decides it — its readings: `narrowed` (raised
+ *  under the `roots` read face: the fence the deployment narrowed, and the engine default), `open` (under the open read face, or a
+ *  written target alone) and, where it differs, `redirect` (every containment finding is an output redirection outside the write
+ *  roots). */
 export type ShellReadCell = ShellReadDisposition | {
     readonly narrowed: ShellReadDisposition;
     readonly open: ShellReadDisposition;
+    readonly redirect?: ShellReadDisposition;
 };
-/** A cell, read for a question raised under a narrowed read face (`true`) or an open one (`false`). */
-export declare function dispositionOfCell(cell: ShellReadCell, narrowedReadFace: boolean): ShellReadDisposition;
+/** A cell, read for the form of the question ({@link ShellReadCellContext}): the redirect reading where the cell has one and every
+ *  containment finding is a redirection, otherwise the read face's (absent ⇒ narrowed, the engine default). */
+export declare function dispositionOfCell(cell: ShellReadCell, context?: ShellReadCellContext): ShellReadDisposition;
 /**
  * THE decision table — total over findings × seats; no cell is n/a. Row by row:
  *  · `deny_hit` — refused on every seat, for a spelling the station can establish: a deny row is a floor
@@ -67,7 +71,13 @@ export declare function dispositionOfCell(cell: ShellReadCell, narrowedReadFace:
  *    the `unestablishable` row) — the floor holds what it can place, and says so rather than guessing.
  *  · `outside_roots` — asked where a person can be asked (the full shell), refused where none can (the
  *    read-only face has no approval channel; a rewrite that leaves the roots after approval was seen by
- *    nobody).
+ *    nobody). The full shell's ask is MANDATED, except for a command whose every containment finding is an OUTPUT
+ *    REDIRECTION outside the write roots (the cell's `redirect` reading): the permission question a stored allow answers,
+ *    the ORDINARY ask. The reference implementation's redirection check (CC 2.1.296 `lvr` (cli296.js:249645) @18502854,
+ *    called @18508831) asks such a target as a plain permission ask that is not rule-overridable: a whole-tool `Bash` allow
+ *    (`$pn` @18717070) and bypass (`$pn` @18716980) release it, a prefix allow does not (`vX`'s ask returns before the allow
+ *    rules, @18567915). A command that also reads outside the roots, or writes a program operand there (`tee`, `cp`, …),
+ *    keeps the mandate.
  *  · `unestablishable` — the floor could not say where the command reads, so it is not vouched anywhere: asked
  *    where a person can be asked (the full shell), refused where none can be asked. The full shell's cell is read by the read face
  *    the question was raised under: on a NARROWED (`roots`) face — the engine default — the deployment asked to be asked, so the
@@ -101,7 +111,11 @@ export declare const SHELL_READ_DECISION: {
         readonly rejudge: "refuse";
     };
     readonly outside_roots: {
-        readonly full_shell: "mandated";
+        readonly full_shell: {
+            readonly narrowed: "mandated";
+            readonly open: "mandated";
+            readonly redirect: "ordinary";
+        };
         readonly readonly: "refuse";
         readonly rejudge: "refuse";
     };
@@ -142,15 +156,30 @@ export type DecisionTableCoversEverySeat = AssertAllKeysHandled<Exclude<ShellRea
 /** The disposition of one command-level finding on one seat — the table, read. A seat word outside
  *  {@link SHELL_READ_SEATS} (an untyped caller, or one still passing a retired word) is refused loudly: an
  *  absent disposition would read as "no verdict", which no caller can act on safely. */
-export declare function decideShellRead(finding: ShellReadFinding, seat: ShellReadSeat, context?: ShellReadCellContext): ShellReadDisposition;
+export declare function decideShellRead<F extends ShellReadFinding>(finding: F, seat: ShellReadSeat, context?: ShellReadCellContext): RowDisposition<F>;
+/** The dispositions the table's row for `F` holds — on any seat, under any form of the question (the table's own literal words). */
+export type RowDisposition<F extends ShellReadFinding> = CellWords<(typeof SHELL_READ_DECISION)[F][ShellReadSeat]>;
 /** What the table is read for beyond (finding, seat): the two facts of a judged command a cell can depend on. */
 export interface ShellReadCellContext {
-    /** Every containment finding is an output redirection outside the write roots ({@link SHELL_REDIRECT_DECISION}). Absent ⇒ no. */
+    /** Every containment finding is an output redirection outside the write roots (a cell's `redirect` reading). Absent ⇒ no. */
     readonly redirectsOnly?: boolean;
     /** The question was raised under a NARROWED (`roots`) read face — a read candidate or the text's own structure while the read
      *  face runs the roots containment; `false` for the open face and for a written target alone. Absent ⇒ narrowed, the engine default. */
     readonly narrowedReadFace?: boolean;
 }
+/** Every disposition the table gives `finding` — on any seat, under any form of the question; empty for a word outside
+ *  {@link SHELL_READ_FINDINGS}. A disposition outside it is no reading of the table: what a reader of a station's answer
+ *  checks the answer against. */
+export declare function dispositionsOfRow(finding: string): ReadonlySet<ShellReadDisposition>;
+/** The words a cell can read as. */
+type CellWords<C> = C extends string ? C : C[keyof C];
+/** The findings whose row the table vouches on, on any seat and under any form. */
+type FindingsTheTableVouches = {
+    [F in ShellReadFinding]: "vouch" extends RowDisposition<F> ? F : never;
+}[ShellReadFinding];
+/** Compile-time fence: `never` while `vouch` is a cell of the `none` row alone — what lets a vouch carry the finding `none` and
+ *  nothing else ({@link import("./shell-read-check.js").ShellReadVerdict}). */
+export type VouchOnlyOnTheNoneRow = AssertAllKeysHandled<Exclude<FindingsTheTableVouches, "none">>;
 /**
  * The boundary a shell read is judged against: the declared roots (canonical), the working directory and
  * home the plan's bases start from, the deny seat (the SAME `denyMatch` closure every read face mounts),
@@ -399,3 +428,4 @@ export declare function grantOfferFor(candidate: string, single: string | undefi
 } | undefined;
 /** The same judged plan under another boundary — the established reads are kept, only the judgment reruns. */
 export declare function rejudge(judged: JudgedPlan, boundary: ShellReadBoundary): JudgedPlan;
+export {};