@sema-agent/core 7.48.0 → 7.49.1

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

@@ -8,7 +8,8 @@
  *    of a candidate that could not be established), then containment over the canonical target alone. The
  *    deny judge is the boundary's own `denyMatch` closure (`readDenySeat`, read-deny.ts) — the same function
  *    object every read face mounts; nothing here compiles a pattern or re-derives a view set. The containment
- *    judge is `withinAnyRoot` over the roots the boundary declares.
+ *    judge is `withinAnyRoot` over the roots the boundary declares — a WRITE target's over the write roots, at the
+ *    seat it is written, under the write face in force ({@link judgeWrite}).
  *  · `foldShellReadFindings` folds a command's findings — every segment, every nested plan — to ONE word by
  *    the priority `identity_changed > deny_hit > outside_roots > unestablishable > declined > none`.
  *  · `SHELL_READ_DECISION` is the total table (finding × seat → disposition) that is the ONLY source of
@@ -22,6 +23,7 @@
 import type { BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
 import type { ReadCandidate, ShellReadPlan, ShellReadSegment } from "./shell-read-plan.js";
 import type { WriteSeat } from "./shell-read-write-targets.js";
+import { type ContainmentFace } from "./containment-face.js";
 import type { AssertAllKeysHandled } from "../../core/ask-origin.js";
 /** WHAT the judge found about a command — a closed set, registered in `docs/CLOSED-SETS.md`. */
 export declare const SHELL_READ_FINDINGS: readonly ["deny_hit", "outside_roots", "unestablishable", "declined", "identity_changed", "none"];
@@ -108,6 +110,9 @@ export type DecisionTableCoversEverySeat = AssertAllKeysHandled<Exclude<ShellRea
  *  {@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): ShellReadDisposition;
+/** {@link decideShellRead} for a command whose containment findings are all output redirections (`redirectsOnly`) or not — the
+ *  cell {@link SHELL_REDIRECT_DECISION} states where it states one, else the table's. */
+export declare function decideShellReadForRedirects(finding: ShellReadFinding, seat: ShellReadSeat, redirectsOnly: boolean): ShellReadDisposition;
 /**
  * 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),
@@ -122,21 +127,27 @@ export interface ShellReadBoundary extends BashReadonlyRootBoundary {
     /** The read table's rows AT or BELOW a path (`readDenySeat`'s `denyAtOrBelow`, read-deny.ts): read by the station's
      *  `writesPlaced` fact only, through {@link denyRowAtOrBelow}. */
     readonly denyAtOrBelow?: (resolvedPath: string) => string | null;
-    /** The WRITE roots (canonical) — where a write may land without a question under a mode that accepts file commands
-     *  (the task root and every additional working directory; never a read-only grant). Read for the station's
-     *  `writesPlaced` fact only; the read judgment never reads it. Absent ⇒ no write is placed. */
+    /** The WRITE roots (canonical) — the task root and every additional working directory, never a read-only grant: where a
+     *  command's write targets must land ({@link judgeRead}'s write face: a target written outside them is an
+     *  `outside_roots` finding), and so where a mode that accepts file commands may place them. Absent ⇒ where a write may
+     *  land is unknown: a written target is `unestablishable` and nothing is placed. */
     readonly writeRoots?: readonly string[];
-    /** The write-protection TABLE's judge — the one a write tool's target meets (its spelling, its real target and every hop
-     *  of its symlink chain): `true` ⇔ a row covers this ABSOLUTE write target; `canonical` ⇔ the path is a key the station
-     *  established (judged as a key, never as a spelling). Read by the station's write facts only: a covered target is not
-     *  placed, and the verdict says it was found ({@link import("./shell-read-check.js").ShellReadVerdict.writeProtected}). */
-    readonly writeProtectionJudge?: (target: string, opts?: {
+    /** The WRITE face in force — the same seat the structured write tools read (the run's resolved write face, read once per
+     *  judgment where the boundary is built): `"open"` skips the write roots' containment for a finding, as it skips the
+     *  structured tools' root fence ({@link skipsRootsContainment}; absent ⇒ roots). Placement still reads the write roots:
+     *  a mode accepting file commands accepts them inside its own directories, whatever the face. */
+    readonly writeFace?: ContainmentFace;
+    /** The leg's ONE write judgment of an ABSOLUTE write target — the one a write tool's target meets (its spelling, its real
+     *  target and every hop of its symlink chain, under the leg's one exempt root), over the write-protection TABLE and the
+     *  deployment's guarded write rows (`ToolPolicy.writeGuardRows`, every policy of the leg's chain) together; `canonical` ⇔
+     *  the path is a key the station established (judged as a key, never as a spelling). `"protected"`: the table covers it —
+     *  the target is not placed and the verdict says so ({@link import("./shell-read-check.js").ShellReadVerdict.writeProtected});
+     *  `"guarded"`: a deployment row covers it — the target is not placed; `undefined`: nothing covers it. Read by the
+     *  station's write facts only. A judgment that throws fails the station's answer (the caller's fail-closed arm). */
+    readonly writeTargetJudge?: (target: string, opts?: {
         readonly signal?: AbortSignal;
         readonly canonical?: true;
-    }) => Promise<boolean>;
-    /** The deployment's write-target guard (`ToolPolicy.writeTargetGuard`, every policy of the leg's chain): `true` ⇔ a
-     *  policy guards this ABSOLUTE write target. Read by the station's `writesPlaced` fact only: a guarded target is not placed. */
-    readonly writeTargetGuard?: (target: string, signal?: AbortSignal) => Promise<boolean>;
+    }) => Promise<"protected" | "guarded" | undefined>;
 }
 /** How far one candidate got before it was judged. `lexical` = the folded spelling is the judged target
  *  (an isolated sandbox, or a resolver that declares no authority and did not answer); `canonical` = the
@@ -163,6 +174,11 @@ export interface EstablishedRead {
     readonly walked?: true;
     /** Why the candidate could not be established. */
     readonly cause?: string;
+    /** The candidate's spelling WAS placed and the environment could not resolve where it leads (the whole chain unanswered by
+     *  a resolver that declares itself authoritative, or a component it could not follow) — the reading's
+     *  `target_unresolved` fact, as opposed to a text the station cannot read (a rewritten word, an unsettled working
+     *  directory). Present only on an `unestablishable` read. */
+    readonly unresolved?: true;
     /** WHERE the command's program writes this target — present only on a write target the program itself writes, at the
      *  seat this read was established at (`landing`: through the path's links; `entry`: the directory entry, a link there
      *  not followed). Absent on a read, and on a write-face target the program only names (a copy's source). `child`: the
@@ -235,16 +251,30 @@ export interface JudgedSegment {
 export interface JudgedPlan {
     readonly plan: ShellReadPlan;
     readonly segments: readonly JudgedSegment[];
-    /** {@link stationGuards} of the boundary the plan was judged against. */
+    /** {@link stationGuards} of the boundary the plan was judged against — what a READ finding folds by. */
     readonly guards: boolean;
+    /** {@link writeFaceGuards} of the same boundary — what a WRITE target's finding folds by. */
+    readonly writeGuards: boolean;
 }
 /**
  * Does the station GUARD anything for this boundary — a closed face (roots: containment is what it guards; an absent
  * face reads as roots, as {@link containmentOf} does), or a deny table with rows (`denyMatch` is present exactly then)?
  * Where it guards nothing (an open face, no deny row), a read it could not establish has nothing to be confirmed
- * against: no finding. The deny judgment itself is untouched (with no row there is nothing to hit).
+ * against: no finding. The deny judgment itself is untouched (with no row there is nothing to hit). The READ face's
+ * question only: a write target folds by {@link writeFaceGuards}.
  */
 export declare function stationGuards(boundary: Pick<ShellReadBoundary, "face" | "denyMatch">): boolean;
+/**
+ * Does the station guard anything on the WRITE face — the same shape for the write seats: the write face in force runs
+ * the roots-containment step ({@link skipsRootsContainment}, the structured write tools' reading; absent ⇒ roots), or
+ * the write deny table has rows. Where it guards nothing (an open write face, no write row), a write target the station
+ * could not establish has nothing to be confirmed against — as a structured write under that face is not fenced.
+ */
+export declare function writeFaceGuards(boundary: Pick<ShellReadBoundary, "writeFace" | "writeDenyMatch">): boolean;
+/** Does the station guard anything on EITHER face? What a finding about the text's own structure folds by — a text the
+ *  lexer could not read, a program it cannot name, program text it does not read, a working directory it lost, a text the
+ *  shell re-enters — since what such a text reads AND what it writes are both unknown. */
+export declare function anyFaceGuards(boundary: Pick<ShellReadBoundary, "face" | "denyMatch" | "writeFace" | "writeDenyMatch">): boolean;
 /** The command-level fold and the finding that produced it. `witness` is absent for `none`; for `declined`
  *  the segment that declined stands in for a candidate. */
 export interface ShellReadFold {
@@ -256,8 +286,10 @@ export interface ShellReadFold {
 }
 /**
  * Fold a judged plan to ONE finding by {@link SHELL_READ_FINDING_RANK}, over every segment and every nested
- * plan. Where the station guards nothing ({@link JudgedPlan.guards}) an `unestablishable` or `declined` finding is no
- * finding: there is nothing to confirm the read against. Two structural rules ride the fold:
+ * plan. Where the station guards nothing an `unestablishable` or `declined` finding is no finding: there is nothing to
+ * confirm it against. Which guard is asked is the face the finding is about — a read candidate's by the read face's
+ * ({@link JudgedPlan.guards}), a write target's by the write face's ({@link JudgedPlan.writeGuards}), and a finding about
+ * the text's own structure (no candidate stands in for it) by either ({@link anyFaceGuards}). Two structural rules ride the fold:
  *  · a plan the lexer refused (`unreadable`) is `unestablishable`, unconditionally — a quote-blind re-read
  *    yields more words, never zero, so an unreadable text is never "no candidates";
  *  · a SHELL re-entry segment (`sh -c S`, `eval S`, `env -S 'S'`, a launcher handing text to a shell) is at
@@ -289,7 +321,8 @@ export declare function deepestCommonDir(a: string, b: string): string | undefin
  * The ONE directory whose addition to the declared roots would answer every `outside_roots` finding of a
  * command — offered only when re-judging the same established reads with that root added leaves no
  * finding at all (MEASURED, not argued: a deny row or an unestablishable candidate beside the out-of-root
- * one leaves the ask standing whatever root is granted, and then nothing is offered). `exact` ⇒ the value
+ * one leaves the ask standing whatever root is granted, and then nothing is offered; so does a target written outside
+ * the WRITE roots, which no read root answers — a read grant grants no write). `exact` ⇒ the value
  * is the one path the command NAMED, offered verbatim, because the containing directory would hand out the
  * home or a root. A `..` spelling gets no offer: the folded and the kernel reading of it can disagree about
  * whether the target is back inside, which no replay of the text settles.

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

@@ -1,6 +1,7 @@
 import { hasWin32AliasedComponent, normalizeAbsPathLexically, withinAnyRoot } from "./safety.js";
 import { globInWord } from "./bash-readonly-classifier.js";
 import { readOfText } from "./shell-read-word.js";
+import { skipsRootsContainment } from "./containment-face.js";
 export const SHELL_READ_FINDINGS = Object.freeze(["deny_hit", "outside_roots", "unestablishable", "declined", "identity_changed", "none"]);
 export const SHELL_READ_SEATS = Object.freeze(["full_shell", "readonly", "rejudge"]);
 export const SHELL_READ_FINDING_RANK = {
@@ -27,6 +28,13 @@ export function decideShellRead(finding, seat) {
     }
     return disposition;
 }
+const SHELL_REDIRECT_DECISION = {
+    outside_roots: { full_shell: "ordinary" },
+};
+export function decideShellReadForRedirects(finding, seat, redirectsOnly) {
+    const cell = redirectsOnly && Object.hasOwn(SHELL_REDIRECT_DECISION, finding) ? SHELL_REDIRECT_DECISION[finding]?.[seat] : undefined;
+    return cell ?? decideShellRead(finding, seat);
+}
 export function judgeRead(read, boundary) {
     const writeTarget = read.candidate.face === "write";
     const deny = writeTarget ? boundary.writeDenyMatch : boundary.denyMatch;
@@ -37,11 +45,11 @@ export function judgeRead(read, boundary) {
             const folded = normalizeAbsPathLexically(view);
             const pattern = writeTarget ? boundary.writeDenyMatch(folded) : boundary.denyMatch(folded, walked);
             if (pattern !== null)
-                return { read, kind: "deny_hit", deny: { pattern, matchedView: folded, ...(writeTarget ? { face: "write" } : {}) }, containment: containmentOf(read, boundary) };
+                return { read, kind: "deny_hit", deny: { pattern, matchedView: folded, ...(writeTarget ? { face: "write" } : {}) }, containment: writeTarget ? writeContainmentOf(read, boundary) : containmentOf(read, boundary) };
         }
     }
     if (writeTarget)
-        return { read, kind: "none", containment: containmentOf(read, boundary) };
+        return judgeWrite(read, boundary);
     const containment = containmentOf(read, boundary);
     if (read.candidate.denyOnly === true)
         return { read, kind: "none", containment };
@@ -72,19 +80,45 @@ function containmentOf(read, boundary) {
         return "unknown";
     return withinAnyRoot(boundary.roots, read.target) ? "inside" : "outside";
 }
+const NULL_DEVICE = "/dev/null";
+function writeContainmentOf(read, boundary) {
+    const device = read.written?.seat === "landing" && read.candidate.expands === false && read.candidate.spelled === NULL_DEVICE;
+    if (read.written === undefined || read.candidate.denyOnly === true || device)
+        return "open";
+    const roots = boundary.writeRoots;
+    if (roots === undefined || read.target === undefined)
+        return "unknown";
+    return withinAnyRoot(roots, read.target) ? "inside" : "outside";
+}
+function judgeWrite(read, boundary) {
+    const containment = writeContainmentOf(read, boundary);
+    if (containment === "open")
+        return { read, kind: "none", containment };
+    if (read.established === "unestablishable" || boundary.writeRoots === undefined)
+        return { read, kind: "unestablishable", containment };
+    return { read, kind: containment === "outside" && !skipsRootsContainment(boundary.writeFace) ? "outside_roots" : "none", containment };
+}
 export function stationGuards(boundary) {
     return boundary.face !== "open" || boundary.denyMatch !== undefined;
 }
+export function writeFaceGuards(boundary) {
+    return !skipsRootsContainment(boundary.writeFace) || boundary.writeDenyMatch !== undefined;
+}
+export function anyFaceGuards(boundary) {
+    return stationGuards(boundary) || writeFaceGuards(boundary);
+}
 export function foldShellReadFindings(judged) {
     let best = { finding: "none" };
     let unestablished = false;
     const raise = (next) => {
         if (next.finding === "unestablishable" || next.finding === "declined") {
-            if (!judged.guards)
+            const face = next.witness?.read.candidate.face;
+            if (!(next.witness === undefined ? judged.guards || judged.writeGuards : face === "write" ? judged.writeGuards : judged.guards))
                 return;
             unestablished = true;
         }
-        if (SHELL_READ_FINDING_RANK[next.finding] > SHELL_READ_FINDING_RANK[best.finding])
+        const rank = SHELL_READ_FINDING_RANK[next.finding] - SHELL_READ_FINDING_RANK[best.finding];
+        if (rank > 0 || (rank === 0 && next.witness?.read.candidate.face === "write" && best.witness?.read.candidate.face !== "write"))
             best = next;
     };
     const walk = (j, denyOnly) => {
@@ -125,6 +159,7 @@ export function judgeEstablishedPlan(plan, established, boundary, nestedOf) {
             nested: segment.nested.map(nestedOf),
         })),
         guards: stationGuards(boundary),
+        writeGuards: writeFaceGuards(boundary),
     };
 }
 export function allFindings(judged) {
@@ -208,5 +243,6 @@ export function rejudge(judged, boundary) {
             nested: s.nested.map((n) => rejudge(n, boundary)),
         })),
         guards: stationGuards(boundary),
+        writeGuards: writeFaceGuards(boundary),
     };
 }

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

@@ -24,9 +24,9 @@
  *    and here-strings are data (an UNQUOTED here-document body's substitutions are nested plans) — except to a shell
  *    whose argv names no script: what arrives on its standard input is its script, a nested plan where the text spells it;
  *  · `$(…)`, backticks and `<(…)` bodies are nested plans; a word carrying one cannot be resolved from the text;
- *  · `cd` moves the base the LATER segments resolve against, as a candidate SET (`&&` proves a move, nothing
- *    else does); `pushd`/`popd` lose the base; a loop body with a base move is replayed per LITERAL beat and
- *    otherwise loses the base for what follows.
+ *  · the working-directory thread (`shell-read-workdir.ts`) moves the base the LATER segments resolve against, as a
+ *    candidate SET (`&&` proves a move, nothing else does), and gives `PWD` / `OLDPWD` their values; a loop body with
+ *    a base move is replayed per LITERAL beat and otherwise loses the base for what follows.
  * Every ambiguity resolves toward MORE candidates, never fewer.
  */
 import { type LenientConnector, type LexedRedirect, type LexedWord } from "../../shell/lex.js";
@@ -47,6 +47,9 @@ export interface ShellReadDeclarations {
     readonly cwd: string;
     readonly roots: readonly string[];
     readonly face?: "open" | "roots";
+    /** The `CDPATH` the shell starts with (the environment's declared one, `ExecutionEnv.cdPath`; a bare relative `cd` is
+     *  searched through it): absent ⇒ none declared, read as unset; `unknown` ⇒ the text cannot know it. */
+    readonly cdPath?: readonly string[] | "unknown";
 }
 export interface ReadCandidate {
     /** The folded word (quotes removed, a literal leading tilde spelled `./~`) — a pattern's name where nothing matches. */
@@ -70,10 +73,10 @@ export interface ReadCandidate {
     /** A home word the plan does not place (the text may rebind `HOME`, it sits in a value, or it is a literal tilde the
      *  program may expand itself): spelled with the DECLARED home. The judge reads it for deny rows ONLY. */
     readonly floorSpelled?: string;
-    /** A deny-floor shadow of a `floorSpelled` spelling, established as a read and judged for deny rows only. */
+    /** Deny rows only (never containment): a `floorSpelled` shadow, or the read copy of a word the program only writes. */
     readonly denyOnly?: true;
-    /** A WRITE target of the command (a `>`-family redirection, a `sed` `w` file, the operands of a file-writing command):
-     *  established like a read and judged against the deny table's WRITE face only — never for containment, never a read. */
+    /** A WRITE target (a `>`-family redirection, a `sed` `w` file, a file-writing command's operand): established like a
+     *  read, judged on the WRITE face — the write deny rows, then the write roots where written — never as a read. */
     readonly face?: "write";
     /** A reading the station takes where no row says the program opens the word — a word of a program with no row, a
      *  role only another implementation reads — so the filesystem decides it: `containment` = the spelling always meets
@@ -129,6 +132,9 @@ export interface ShellReadSegment {
     /** Substitution bodies, unquoted here-document substitutions, and re-entered shell text, each its own plan. */
     readonly nested: readonly ShellReadPlan[];
     readonly reach: SegmentReach;
+    /** The names a change that can reach this segment touched (`BindingTable.rebound`): any other name still holds what the
+     *  shell provides here. `all`: any name may have changed. */
+    readonly rebound: ReadonlySet<string> | "all";
 }
 export interface ShellReadPlan {
     readonly segments: readonly ShellReadSegment[];