@sema-agent/core 7.24.4 → 7.25.1

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

@@ -0,0 +1,231 @@
+/**
+ * The shell read JUDGE and its DECISION TABLE — the one place a shell command's read candidates become a
+ * verdict, for every shell face (the full `Bash`, the read-only `Bash`, `Monitor`) and both moments (the
+ * gate station before approval, the rewrite re-judge after it).
+ *
+ *  · `judgeRead` judges ONE established candidate: the deny half first, over every view the candidate has
+ *    (its canonical target, its folded spelling, the kernel spelling of a `..` operand, the folded spelling
+ *    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.
+ *  · `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
+ *    "refuse / mandated ask / ordinary ask / vouch" for a shell read. A seat is a TRUST POLICY word, not a
+ *    tool name: the four seats differ on one row (`declined`) and nowhere else.
+ *
+ * The floor this module is (`shell.read_boundary.friction_floor`) is stated on {@link judgeRead}.
+ */
+import type { BashReadonlyRootBoundary } from "./bash-readonly-classifier.js";
+import type { ReadCandidate, ShellReadPlan, ShellReadSegment } from "./shell-read-plan.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"];
+export type ShellReadFinding = (typeof SHELL_READ_FINDINGS)[number];
+/** WHO is asking — the trust-policy seats the decision table is keyed on. `bash_off` covers the `off` and
+ *  `always` doctrines (and a bypass mode); `bash_classify` the `classify` doctrine; `readonly` the read-only
+ *  shell face (`handsReadOnly`); `rejudge` the post-approval re-judgment of rewritten bytes and the
+ *  pre-spawn identity re-check. */
+export declare const SHELL_READ_SEATS: readonly ["bash_off", "bash_classify", "readonly", "rejudge"];
+export type ShellReadSeat = (typeof SHELL_READ_SEATS)[number];
+/** The fold priority: a command's finding is the highest-ranked finding of any candidate in it. */
+export declare const SHELL_READ_FINDING_RANK: {
+    readonly identity_changed: 6;
+    readonly deny_hit: 5;
+    readonly outside_roots: 4;
+    readonly unestablishable: 3;
+    readonly declined: 2;
+    readonly none: 0;
+};
+/** Compile-time fence: `never` while every finding has a rank. */
+export type RankTableCoversEveryFinding = AssertAllKeysHandled<Exclude<ShellReadFinding, keyof typeof SHELL_READ_FINDING_RANK>>;
+/** What a seat does with a finding. `refuse` = a deny at the station (or a veto after a person's yes);
+ *  `mandated` = an ask no automatic lane may clear; `ordinary` = an ask any answerer may clear (a person,
+ *  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";
+/**
+ * THE decision table — total over findings × seats; no cell is n/a. Row by row:
+ *  · `deny_hit` — refused on every seat: a deny row is a floor no root grant and no approval moves.
+ *  · `outside_roots` — asked where a person can be asked (the two full-shell seats), refused where none
+ *    can (the read-only face has no approval channel; a rewrite that leaves the roots after approval was
+ *    seen by nobody).
+ *  · `unestablishable` — the same shape: the floor could not say where the command reads, so it is not
+ *    vouched anywhere; a person may still answer it on the full shell.
+ *  · `declined` — the one row the seats disagree on, and the one deliberate fail-open of this table: the
+ *    scan could not read the program bash will run or the operands arrive on a stream. The `off` doctrine
+ *    mounts nothing else that could ask, so it mandates; the `classify` doctrine composes a shape classifier
+ *    beside this station and the ruled trade is an ORDINARY ask there — an answerer may settle it, and an
+ *    out-of-root read hidden inside such a command is then not asked again. The read-only face refuses:
+ *    its allowlist is a deployment knob, so this cell is reachable and must not be n/a.
+ *  · `identity_changed` — a candidate established at approval time resolves elsewhere at spawn time:
+ *    refused everywhere (it is only ever produced on the `rejudge` seat).
+ *  · `none` — vouched: the station has no question (the classify seat's shape classifier may still ask).
+ */
+export declare const SHELL_READ_DECISION: {
+    readonly deny_hit: {
+        readonly bash_off: "refuse";
+        readonly bash_classify: "refuse";
+        readonly readonly: "refuse";
+        readonly rejudge: "refuse";
+    };
+    readonly outside_roots: {
+        readonly bash_off: "mandated";
+        readonly bash_classify: "mandated";
+        readonly readonly: "refuse";
+        readonly rejudge: "refuse";
+    };
+    readonly unestablishable: {
+        readonly bash_off: "mandated";
+        readonly bash_classify: "mandated";
+        readonly readonly: "refuse";
+        readonly rejudge: "refuse";
+    };
+    readonly declined: {
+        readonly bash_off: "mandated";
+        readonly bash_classify: "ordinary";
+        readonly readonly: "refuse";
+        readonly rejudge: "refuse";
+    };
+    readonly identity_changed: {
+        readonly bash_off: "refuse";
+        readonly bash_classify: "refuse";
+        readonly readonly: "refuse";
+        readonly rejudge: "refuse";
+    };
+    readonly none: {
+        readonly bash_off: "vouch";
+        readonly bash_classify: "vouch";
+        readonly readonly: "vouch";
+        readonly rejudge: "vouch";
+    };
+};
+/** Compile-time fence: `never` while every finding has a row. */
+export type DecisionTableCoversEveryFinding = AssertAllKeysHandled<Exclude<ShellReadFinding, keyof typeof SHELL_READ_DECISION>>;
+/** Compile-time fence: `never` while every seat has a cell on the `none` row (the `satisfies` above holds
+ *  every other row to the same shape). */
+export type DecisionTableCoversEverySeat = AssertAllKeysHandled<Exclude<ShellReadSeat, keyof (typeof SHELL_READ_DECISION)["none"]>>;
+/** The disposition of one command-level finding on one seat — the table, read. */
+export declare function decideShellRead(finding: ShellReadFinding, seat: ShellReadSeat): 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),
+ * the containment face, and — for the read-only face — the engine's own overflow-spool fence as one more
+ * member of "inside" (`alsoInside`), asked once per target that landed outside the roots.
+ */
+export interface ShellReadBoundary extends BashReadonlyRootBoundary {
+    readonly alsoInside?: (canonicalTarget: string) => Promise<boolean>;
+}
+/** 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
+ *  environment resolved it; `expansion` = one path a pattern expanded to or a traversal enumerated;
+ *  `unestablishable` = the floor could not say where it lands (`cause` says why). */
+export type ReadEstablishment = "lexical" | "canonical" | "expansion" | "unestablishable";
+export interface EstablishedRead {
+    readonly candidate: ReadCandidate;
+    readonly established: ReadEstablishment;
+    /** The judged target: an absolute path (canonical where established so, the folded spelling otherwise).
+     *  Absent exactly when `established === "unestablishable"`. */
+    readonly target?: string;
+    /** Every spelling the deny judge sees BESIDE the target: the folded spelling, the kernel spelling of a
+     *  `..` operand, the pattern an expansion came from, the placeholder-carrying fold of a substitution. */
+    readonly spellings: readonly string[];
+    /** The pattern or traversal root an `expansion` came from, as folded. */
+    readonly origin?: string;
+    /** Why the candidate could not be established. */
+    readonly cause?: string;
+}
+/** What the judge found about ONE candidate. `kind` is one of the four candidate-level findings
+ *  (`declined` is a segment fact, `identity_changed` a re-establishment fact — neither is a candidate's). */
+export interface ReadFinding {
+    readonly read: EstablishedRead;
+    readonly kind: Extract<ShellReadFinding, "deny_hit" | "outside_roots" | "unestablishable" | "none">;
+    /** The deny row that matched and the view it matched on. */
+    readonly deny?: {
+        readonly pattern: string;
+        readonly matchedView: string;
+    };
+    readonly containment: "inside" | "outside" | "open" | "unknown";
+}
+/**
+ * Judge ONE established candidate. Deny first, over every view (a hit on any view decides — a symlink whose
+ * SPELLING names a guarded path is refused even when its target is elsewhere, and a substitution's folded
+ * spelling is judged although the candidate could not be established); containment over the canonical
+ * target alone, and only where the boundary's face closes it.
+ *
+ * @contract shell.read_boundary.friction_floor — what this judge answers is a question about TEXT and the
+ * FILESYSTEM the command will run in: which files the words of a command may name, resolved against the
+ * declared roots, the declared home and the observed working directory, and — where the environment can
+ * answer — where those spellings really land (symlinks resolved, patterns expanded, traversal roots
+ * enumerated, each within a bound). It is not a question about what the process will open. A deployment's
+ * containment for what a shell may reach is the `ExecutionEnv` the command runs in (a sandbox, a
+ * container, a remote adapter); everything here is the friction floor under that containment. Under an
+ * isolated sandbox the floor is lexical (the sandbox is the boundary and its filesystem is not this
+ * process's to resolve). A deny-listed read is REFUSED on every seat; an out-of-root read asks where a
+ * person can be asked and is refused where none can; a read the floor cannot establish (an expansion it
+ * cannot finish, a spelling the shell rewrites, a working directory it cannot place) is asked or refused
+ * the same way — never vouched. Containment judges what a READ program opens: a program path is executed,
+ * not disclosed, and a leading environment word's value reaches the program through its environment, so
+ * neither is a containment candidate — both still meet the deny judge, on every spelling.
+ */
+export declare function judgeRead(read: EstablishedRead, boundary: ShellReadBoundary): ReadFinding;
+/** One segment's judged reads and declines, with its nested plans judged the same way. */
+export interface JudgedSegment {
+    readonly segment: ShellReadSegment;
+    readonly findings: readonly ReadFinding[];
+    readonly nested: readonly JudgedPlan[];
+}
+export interface JudgedPlan {
+    readonly plan: ShellReadPlan;
+    readonly segments: readonly JudgedSegment[];
+}
+/** 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 {
+    readonly finding: ShellReadFinding;
+    readonly witness?: ReadFinding;
+    readonly declined?: ShellReadSegment;
+}
+/**
+ * Fold a judged plan to ONE finding by {@link SHELL_READ_FINDING_RANK}, over every segment and every nested
+ * plan. 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
+ *    least `unestablishable` — what runs is text the shell parses, not this plan — and its nested plan may
+ *    only RAISE that to `deny_hit`: the nested text's deny hits count (a refusal is a refusal whatever runs
+ *    it), its containment and its silence do not (an inner `cat inside.txt` vouches nothing about the
+ *    outer text). A substitution body (`$(…)`, a backtick, `<(…)`) is nested WITHOUT re-entry and folds
+ *    in full.
+ */
+export declare function foldShellReadFindings(judged: JudgedPlan): ShellReadFold;
+/** Judge every established read of a plan, in place. `establish` runs per segment so a caller can bound it. */
+export declare function judgeEstablishedPlan(plan: ShellReadPlan, established: ReadonlyMap<ShellReadSegment, readonly EstablishedRead[]>, boundary: ShellReadBoundary, nestedOf: (plan: ShellReadPlan) => JudgedPlan): JudgedPlan;
+/** Every finding of a judged plan, flattened (segments and nested plans alike). */
+export declare function allFindings(judged: JudgedPlan): ReadFinding[];
+/**
+ * The deepest directory containing both, or `undefined` when they share none (two path families).
+ *
+ * LINEAR, and that is the point: both paths are already folded, so the answer is their common prefix cut
+ * at a separator. Climbing one directory at a time re-folds the whole remaining path each step — the same
+ * answer at quadratic cost, measured at 4.9 s of synchronous work for one 32 KB command naming a
+ * 16 000-segment operand. The family-aware comparator keeps the last word: a prefix it cannot confirm
+ * contains both paths yields no candidate.
+ */
+export declare function deepestCommonDir(a: string, b: string): string | undefined;
+/**
+ * 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
+ * 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.
+ */
+export declare function readRootGrantCandidateOf(judged: JudgedPlan, boundary: ShellReadBoundary): {
+    readonly dir: string;
+    readonly covers?: "exact";
+} | 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;

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

@@ -0,0 +1,170 @@
+import { hasWin32AliasedComponent, normalizeAbsPathLexically, withinAnyRoot } from "./safety.js";
+export const SHELL_READ_FINDINGS = ["deny_hit", "outside_roots", "unestablishable", "declined", "identity_changed", "none"];
+export const SHELL_READ_SEATS = ["bash_off", "bash_classify", "readonly", "rejudge"];
+export const SHELL_READ_FINDING_RANK = {
+    identity_changed: 6,
+    deny_hit: 5,
+    outside_roots: 4,
+    unestablishable: 3,
+    declined: 2,
+    none: 0,
+};
+export const SHELL_READ_DECISION = {
+    deny_hit: { bash_off: "refuse", bash_classify: "refuse", readonly: "refuse", rejudge: "refuse" },
+    outside_roots: { bash_off: "mandated", bash_classify: "mandated", readonly: "refuse", rejudge: "refuse" },
+    unestablishable: { bash_off: "mandated", bash_classify: "mandated", readonly: "refuse", rejudge: "refuse" },
+    declined: { bash_off: "mandated", bash_classify: "ordinary", readonly: "refuse", rejudge: "refuse" },
+    identity_changed: { bash_off: "refuse", bash_classify: "refuse", readonly: "refuse", rejudge: "refuse" },
+    none: { bash_off: "vouch", bash_classify: "vouch", readonly: "vouch", rejudge: "vouch" },
+};
+export function decideShellRead(finding, seat) {
+    return SHELL_READ_DECISION[finding][seat];
+}
+export function judgeRead(read, boundary) {
+    const deny = boundary.denyMatch;
+    if (deny !== undefined) {
+        const views = [...(read.target !== undefined ? [read.target] : []), ...read.spellings];
+        for (const view of views) {
+            const folded = normalizeAbsPathLexically(view);
+            const pattern = deny(folded);
+            if (pattern !== null)
+                return { read, kind: "deny_hit", deny: { pattern, matchedView: folded }, containment: containmentOf(read, boundary) };
+        }
+    }
+    const containment = containmentOf(read, boundary);
+    const provenance = read.candidate.provenance;
+    if (provenance === "env_assignment" || (provenance === "program_path" && read.candidate.expands !== "unresolvable"))
+        return { read, kind: "none", containment };
+    if (read.established === "unestablishable")
+        return { read, kind: "unestablishable", containment };
+    return { read, kind: containment === "outside" ? "outside_roots" : "none", containment };
+}
+function containmentOf(read, boundary) {
+    if (boundary.face === "open")
+        return "open";
+    if (read.target === undefined)
+        return "unknown";
+    return withinAnyRoot(boundary.roots, read.target) ? "inside" : "outside";
+}
+export function foldShellReadFindings(judged) {
+    let best = { finding: "none" };
+    const raise = (next) => {
+        if (SHELL_READ_FINDING_RANK[next.finding] > SHELL_READ_FINDING_RANK[best.finding])
+            best = next;
+    };
+    const walk = (j, denyOnly) => {
+        if (j.plan.unreadable !== undefined && !denyOnly)
+            raise({ finding: "unestablishable" });
+        for (const s of j.segments) {
+            for (const f of s.findings) {
+                if (denyOnly && f.kind !== "deny_hit")
+                    continue;
+                if (f.kind !== "none")
+                    raise({ finding: f.kind, witness: f });
+            }
+            if (!denyOnly) {
+                if (s.segment.declines.length > 0)
+                    raise({ finding: "declined", declined: s.segment });
+                if (s.segment.reentry === "shell")
+                    raise({ finding: "unestablishable", declined: s.segment });
+                if (s.segment.unreadProgramText !== undefined)
+                    raise({ finding: "unestablishable", declined: s.segment });
+                const move = s.segment.baseMove;
+                if (move !== undefined && (typeof move.target === "string" || move.target.expands !== false))
+                    raise({ finding: "unestablishable", declined: s.segment });
+            }
+            const nestedDenyOnly = denyOnly || s.segment.reentry === "shell";
+            for (const n of s.nested)
+                walk(n, nestedDenyOnly);
+        }
+    };
+    walk(judged, false);
+    return best;
+}
+export function judgeEstablishedPlan(plan, established, boundary, nestedOf) {
+    return {
+        plan,
+        segments: plan.segments.map((segment) => ({
+            segment,
+            findings: (established.get(segment) ?? []).map((r) => judgeRead(r, boundary)),
+            nested: segment.nested.map(nestedOf),
+        })),
+    };
+}
+export function allFindings(judged) {
+    const out = [];
+    const walk = (j) => {
+        for (const s of j.segments) {
+            out.push(...s.findings);
+            for (const n of s.nested)
+                walk(n);
+        }
+    };
+    walk(judged);
+    return out;
+}
+function parentDirLexically(p) {
+    return normalizeAbsPathLexically(`${p}/..`);
+}
+export function deepestCommonDir(a, b) {
+    if (a === b)
+        return a;
+    const shorter = Math.min(a.length, b.length);
+    let end = 0;
+    let i = 0;
+    while (i < shorter && a[i] === b[i]) {
+        if (a[i] === "/" || a[i] === "\\")
+            end = i;
+        i++;
+    }
+    if (i === shorter && (a[shorter] === "/" || a[shorter] === "\\" || b[shorter] === "/" || b[shorter] === "\\"))
+        end = shorter;
+    const cut = a.slice(0, end);
+    const candidate = cut.includes("/") || cut.includes("\\") ? cut : a.slice(0, end + 1);
+    if (candidate.length === 0 || !withinAnyRoot([candidate], a) || !withinAnyRoot([candidate], b))
+        return undefined;
+    return candidate;
+}
+export function readRootGrantCandidateOf(judged, boundary) {
+    const outside = allFindings(judged).filter((f) => f.kind === "outside_roots");
+    if (outside.length === 0)
+        return undefined;
+    const targets = [...new Set(outside.map((f) => f.read.target))];
+    const paths = targets.filter((p) => !targets.some((q) => q !== p && withinAnyRoot([p], q)));
+    if (outside.some((f) => f.read.candidate.spelled.split(/[\\/]/).includes("..")))
+        return undefined;
+    if (paths.some(hasWin32AliasedComponent))
+        return undefined;
+    const readsDirectory = new Set(outside.filter((f) => f.read.candidate.provenance === "traversal_root" || f.read.candidate.provenance === "cd_target").map((f) => f.read.target));
+    const dirOf = (path) => (readsDirectory.has(path) ? path : parentDirLexically(path));
+    let candidate = dirOf(paths[0]);
+    for (const path of paths.slice(1)) {
+        if (candidate === undefined)
+            return undefined;
+        const d = dirOf(path);
+        if (d === undefined)
+            return undefined;
+        candidate = deepestCommonDir(candidate, d);
+    }
+    if (candidate === undefined)
+        return undefined;
+    const tooWide = parentDirLexically(candidate) === candidate ||
+        (boundary.homeDir !== undefined && withinAnyRoot([candidate], boundary.homeDir)) ||
+        boundary.roots.some((root) => withinAnyRoot([candidate], root));
+    const proposed = tooWide ? (paths.length === 1 ? { dir: paths[0], covers: "exact" } : undefined) : { dir: candidate };
+    if (proposed === undefined)
+        return undefined;
+    const widened = { ...boundary, roots: [...boundary.roots, proposed.dir] };
+    const replay = rejudge(judged, widened);
+    return foldShellReadFindings(replay).finding === "none" ? proposed : undefined;
+}
+export function rejudge(judged, boundary) {
+    return {
+        plan: judged.plan,
+        segments: judged.segments.map((s) => ({
+            segment: s.segment,
+            findings: s.findings.map((f) => judgeRead(f.read, boundary)),
+            nested: s.nested.map((n) => rejudge(n, boundary)),
+        })),
+    };
+}

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

@@ -85,6 +85,9 @@ export interface ShellReadSegment {
     /** `shell` = the program runs its argument as shell text; `argv` = its operands arrive on a stream;
      *  `interpreter` = it runs an inline program in a language this parser does not read (a shape fact only). */
     readonly reentry?: "shell" | "argv" | "interpreter";
+    /** Program text the station READS as a rule (a `sed` script names the files it opens) but could not read here —
+     *  supplied from a file, or not parseable to its end. What such a segment reads is then not established. */
+    readonly unreadProgramText?: string;
     readonly declines: readonly ShellScanDecline[];
     readonly reads: readonly ReadCandidate[];
     readonly redirects: readonly ShellReadRedirect[];