@sema-agent/core 7.24.2 → 7.24.3

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

@@ -0,0 +1,127 @@
+/**
+ * ESTABLISHMENT — the filesystem-resolving half of the shell read boundary, as one value both shell
+ * faces hold. The lexical pass (`bash-readonly-classifier.ts`) decides WHICH words a command may read;
+ * this module decides WHERE those words land once the filesystem has answered: canonical targets, glob
+ * expansions, and the fail-closed arm for what could not be established. It is the seam the read
+ * judgment pipeline's `establish` step is built on; the candidate contract it will be fed from lives in
+ * `shell-read-plan.ts`.
+ *
+ * Extracted verbatim from `fs-bash.ts` (the `createCanonicalReadBoundary` family and its glob matcher):
+ * behaviour is byte-for-byte the tool's own, and every property stated below is the property the tool
+ * always held. Zero imports from `fs-bash.ts` (a leaf the shell faces import, never the reverse).
+ */
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+import type { ReadDenySeat } from "./read-deny.js";
+/**
+ * How many directories one glob operand may enumerate, and how many names it may match, before
+ * the leg gives up and refuses.
+ *
+ * Sized so the everyday shapes never hit them: 256 directories covers a two-level pattern over a source
+ * tree's top level, and 8192 names covers `ls *` in a dependency directory an order of magnitude larger than a
+ * normal one. Past those the answer is a REFUSAL naming the bound, never a silent allow — an operand
+ * this leg could not finish enumerating is exactly an operand whose expansion it cannot vouch for.
+ */
+export declare const MAX_GLOB_DIRS = 256;
+export declare const MAX_GLOB_MATCHES = 8192;
+/**
+ * The SYMLINK-RESOLVING half of the `bash_readonly` read boundary.
+ *
+ * {@link classifySimpleCommandReadBoundary} is synchronous and pure, so its containment is lexical: it
+ * judges the written spelling, while the kernel opens the symlink-resolved target. The two diverge in
+ * both directions, and both are closed here — this is the caller that holds an {@link ExecutionEnv}:
+ *   · LEAK — a symlink inside a root pointing out of it (`<root>/vendor` → `/etc`) has an in-root
+ *     prefix, so `cat vendor/passwd` was auto-allowed and really read `/etc/passwd`. Every candidate
+ *     the lexical pass accepted ({@link CompoundReadonlyVerdict.checkedPaths}) is canonicalized and
+ *     re-compared; one that leaves the roots is refused.
+ *   · FALSE REFUSAL — a non-canonical spelling of an in-root path (a symlinked `/tmp` → `/private/tmp`
+ *     prefix, or any aliased root) does not textually match the canonical roots. A refusal whose paths
+ *     ALL canonicalize back inside is dropped.
+ *
+ * Three properties this deliberately keeps:
+ *  1. A NON-EXISTENT target must not become a boundary refusal — `cat nope.txt` has to keep producing
+ *     the shell's own "No such file", or the boundary would break ordinary use. The deepest EXISTING
+ *     ancestor is canonicalized and the missing tail rejoined (the rule safety.ts's `canonicalizeNewPath`
+ *     already uses for the structured tools), so a symlinked PARENT still cannot carry across the target out.
+ *  2. Nothing here can manufacture a refusal out of an unanswerable filesystem: a path whose whole
+ *     ancestor chain fails to canonicalize degrades to the lexical verdict. (`/` resolves on any sane
+ *     env, so this is a defensive arm, not a routine one.)
+ *  3. An ISOLATED env stays lexical, disclosed rather than silently degraded: the sandbox itself is the
+ *     containment there, and `canonicalPath` is an RPC into a filesystem that is not this host's. The
+ *     split is the DECLARED {@link isIsolated} capability, never the remote interface's SHAPE — an
+ *     adapter driving the operator's own machine (a host lane, an SSH host) implements that same
+ *     interface and declares no containment, so the resolving pass runs there, on the env's own paths.
+ *
+ * NOT cached deliberately: a per-run memo keyed on the lexical spelling would answer from a snapshot of
+ * where a symlink pointed EARLIER in the run, which is the one thing this check exists to observe. The
+ * cost it would save is a `realpath` on a local env. The residual it cannot remove either way is the
+ * classic one — the link can be re-pointed between this check and the shell's own open.
+ *
+ * The GLOB half of the same seam, added here for the same reason (this is where the filesystem
+ * is). A candidate carrying `*`/`?`/`[…]` is a path that does NOT exist as spelled, so property 1's
+ * deepest-existing-ancestor rule resolved `<root>/*` to the root itself and pronounced it inside — after
+ * which the real shell expanded the pattern and handed the command every matching entry, including one
+ * that is a symlink out of the root. `cat vendor/secret.txt` was refused while `cat *` over the same
+ * link was not. Such a candidate is now expanded against the filesystem FIRST (`expandGlobCandidate`,
+ * shell-semantics matcher over `env.listDir`) and each expansion resolved individually. Its own
+ * properties, on top of the three above:
+ *  4. NO MATCH is not a refusal. The shell hands an unmatched pattern to the command verbatim, which then
+ *     reports its own "No such file" — so an empty expansion falls back to judging the literal spelling,
+ *     i.e. the literal-spelling answer (which also covers a file literally named `nomatch*`).
+ *  5. What it could not enumerate, it REFUSES (`unverifiable`), never silently allows: an unreadable
+ *     directory, a pattern construct the matcher does not model, or an expansion past
+ *     {@link MAX_GLOB_DIRS}/{@link MAX_GLOB_MATCHES}. This face has no approval channel to degrade to
+ *     (see `createBashReadonlyTool`'s own note), so fail-closed is the only honest direction.
+ *  6. Cost is paid only by candidates that actually carry a metacharacter, and only past the roots'
+ *     own spelling (a root literally containing `[` must not be re-globbed). A plain path takes the
+ *     same single `resolve` it always took. Inside one enumerated directory only the SYMLINK entries
+ *     need their own `realpath` — the directory is canonicalized once and a non-symlink child of a
+ *     canonical in-root directory is in-root by construction.
+ */
+export declare function createCanonicalReadBoundary(env: ExecutionEnv, readRoots: readonly string[]): {
+    /** What the read boundary objects to once the filesystem has answered: canonical targets OUTSIDE the roots,
+     *  the fail-closed arm (`unverifiable` — a candidate this leg could not establish, property 5), and
+     *  `denied`, the first path the wired deny judge matched. All empty/absent ⇒ no objection.
+     *
+     *  The two input lists are NOT interchangeable, and the split is the lexical pass's answer, never a
+     *  re-reading of the text: `patterns` are the operands the shell will expand
+     *  ({@link CompoundReadonlyVerdict.undecidedPaths}), `literal` the ones it will not. Quoting separates them
+     *  and lives only in the RAW token, which these resolved paths no longer carry — `cat "link*"` reads a file
+     *  literally named `link*` and must not be re-globbed here. */
+    escapesAfterResolution: (paths: {
+        literal: readonly string[];
+        patterns: readonly string[];
+    }, ask: BoundaryQuestions, signal?: AbortSignal) => Promise<{
+        escaping: readonly string[];
+        unverifiable?: string;
+        denied?: {
+            path: string;
+            pattern: string;
+        };
+    }>;
+    /** Do ALL of `paths` canonicalize back INSIDE the roots? (false for an empty list, and where the sandbox is the containment.) */
+    allResolveInside: (paths: readonly string[], signal?: AbortSignal) => Promise<boolean>;
+    /** Where one spelling really lands, for a caller deciding a GRANT on something other than the roots.
+     *  `undefined` where the sandbox is the containment or the chain is unanswerable, and the
+     *  caller then judges the written spelling — what it had before. */
+    canonicalOf: (path: string, signal?: AbortSignal) => Promise<string | undefined>;
+};
+/** The symlink-resolving second pass, as one value both shell faces hold. */
+export type CanonicalReadBoundary = ReturnType<typeof createCanonicalReadBoundary>;
+/** WHICH of the boundary's two halves still has a question once the filesystem can answer. Not a mode and not
+ *  a face: the face DECIDES these two, separately. Containment is structurally satisfied under the OPEN read
+ *  face (an out-of-roots operand rides `checkedPaths` there as an ACCEPTED candidate); the deny half judges in
+ *  BOTH faces by its seat's own contract, so a face-level exit takes it along with the other half. */
+export interface BoundaryQuestions {
+    readonly deny: ReadDenySeat["denyMatch"];
+    readonly containment: boolean;
+    /** Per HALF, the paths this face must NOT re-judge, because the approver was asked THAT question about
+     *  THAT path and said yes. Two sets, not one, and the difference is a leak: "release this deny row" is
+     *  not "release wherever it lands" (a deny-listed name that is a symlink OUT of the roots ran, and
+     *  ADDING the deny row is what turned the refusal off), and "read outside the roots" says nothing about
+     *  the deny table the target is on. Keyed on the folded spelling the card named; empty = nothing
+     *  answered. */
+    readonly denyAnswered: ReadonlySet<string>;
+    readonly containmentAnswered: ReadonlySet<string>;
+}
+/** The empty half-answer, for a face with no approval channel to have been answered through. */
+export declare const NOTHING_ANSWERED: ReadonlySet<string>;

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

@@ -0,0 +1,326 @@
+import { normalizeAbsPathLexically, withinAnyRoot } from "./safety.js";
+import { boundaryIsTheSandbox, canonicalPathIsAuthoritative } from "../../core/remote-env.js";
+const GLOB_METACHAR_RE = /[*?[]/;
+export const MAX_GLOB_DIRS = 256;
+export const MAX_GLOB_MATCHES = 8192;
+function compileGlobSegment(pattern) {
+    if (pattern.includes("\\"))
+        return undefined;
+    let src = "";
+    for (let i = 0; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            src += "[^/]*";
+        }
+        else if (ch === "?") {
+            src += "[^/]";
+        }
+        else if (ch === "[") {
+            const cls = parseBracketExpression(pattern, i);
+            if (cls === undefined)
+                src += "\\[";
+            else {
+                src += cls.source;
+                i = cls.end;
+            }
+        }
+        else {
+            src += ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        }
+    }
+    try {
+        return new RegExp(`^${src}$`, "s");
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseBracketExpression(pattern, start) {
+    let i = start + 1;
+    let negate = false;
+    if (pattern[i] === "!" || pattern[i] === "^") {
+        negate = true;
+        i++;
+    }
+    const contentStart = i;
+    let body = "";
+    let anyChar = false;
+    for (; i < pattern.length; i++) {
+        const ch = pattern[i];
+        if (ch === "]" && i > contentStart) {
+            if (body.length === 0 && !anyChar)
+                return undefined;
+            return { source: anyChar ? "[^/]" : `[${negate ? "^" : ""}${body}]`, end: i };
+        }
+        if (ch === "[" && (pattern[i + 1] === ":" || pattern[i + 1] === "." || pattern[i + 1] === "=")) {
+            const close = pattern.indexOf(`${pattern[i + 1]}]`, i + 2);
+            if (close < 0)
+                return undefined;
+            anyChar = true;
+            i = close + 1;
+            continue;
+        }
+        body += ch === "-" ? "-" : ch.replace(/[\]\\^]/g, "\\$&");
+    }
+    return undefined;
+}
+function globSegmentMatches(re, pattern, name) {
+    if (name.startsWith(".") && !pattern.startsWith("."))
+        return false;
+    return re.test(name);
+}
+function joinCandidate(dir, name) {
+    return `${dir.replace(/[\\/]+$/, "")}/${name}`;
+}
+function pathSegmentsFrom(p, from) {
+    const segs = [];
+    let scan = from;
+    while (scan < p.length) {
+        while (scan < p.length && (p[scan] === "/" || p[scan] === "\\"))
+            scan++;
+        const s = scan;
+        while (scan < p.length && p[scan] !== "/" && p[scan] !== "\\")
+            scan++;
+        if (scan > s)
+            segs.push({ text: p.slice(s, scan), start: s });
+    }
+    return segs;
+}
+export function createCanonicalReadBoundary(env, readRoots) {
+    const lexicalOnly = boundaryIsTheSandbox(env);
+    const resolverIsAuthoritative = canonicalPathIsAuthoritative(env);
+    let rootsOnce;
+    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) => {
+        const parts = p.split(/[\\/]/);
+        const tail = [];
+        let allAbsent = true;
+        while (parts.length > 0) {
+            const canon = await env.canonicalPath(parts.join("/") || "/", signal);
+            if (canon.ok) {
+                if (tail.length === 0)
+                    return { value: canon.value, exact: true };
+                return { value: [canon.value.replace(/[\\/]+$/, ""), ...[...tail].reverse()].join("/"), exact: false, missing: allAbsent };
+            }
+            if (canon.error.code !== "not_found" && canon.error.code !== "not_directory")
+                allAbsent = false;
+            tail.push(parts.pop());
+        }
+        return undefined;
+    };
+    const parentOf = (canonical) => normalizeAbsPathLexically(`${canonical}/..`);
+    const resolve = async (p, signal) => {
+        const parts = p.split(/[\\/]/);
+        const first = parts.findIndex((seg) => seg === "..");
+        if (first < 0)
+            return await resolveWithoutParentSteps(p, signal);
+        const headEnd = parts.slice(0, first).reduce((n, seg) => n + seg.length + 1, 0);
+        let head = await resolveWithoutParentSteps(p.slice(0, headEnd) || "/", signal);
+        if (head === undefined)
+            return undefined;
+        let pending = [];
+        const flush = async () => {
+            if (pending.length === 0)
+                return true;
+            const next = await resolveWithoutParentSteps([head.value.replace(/[\\/]+$/, ""), ...pending].join("/"), signal);
+            pending = [];
+            if (next === undefined)
+                return false;
+            head = next;
+            return true;
+        };
+        for (let i = first; i < parts.length; i++) {
+            const seg = parts[i];
+            if (seg === "" || seg === ".")
+                continue;
+            if (seg !== "..") {
+                pending.push(seg);
+                continue;
+            }
+            if (!(await flush()))
+                return undefined;
+            if (!head.exact)
+                return head;
+            head = { value: parentOf(head.value), exact: true };
+        }
+        return (await flush()) ? head : undefined;
+    };
+    const literalRootHead = (p, roots) => {
+        let best;
+        for (const r of [...readRoots, ...roots]) {
+            if (!r)
+                continue;
+            const withSep = r.endsWith("/") || r.endsWith("\\") ? r : `${r}/`;
+            if (p !== r && !p.startsWith(withSep))
+                continue;
+            if (best === undefined || r.length > best.length)
+                best = r;
+        }
+        return best;
+    };
+    const expandGlobCandidate = async (p, roots, signal) => {
+        const head = literalRootHead(p, roots);
+        let segs = pathSegmentsFrom(p, head?.length ?? 0);
+        let first = segs.findIndex((s) => GLOB_METACHAR_RE.test(s.text));
+        if (first < 0 && head !== undefined && GLOB_METACHAR_RE.test(head)) {
+            segs = pathSegmentsFrom(p, 0);
+            first = segs.findIndex((s) => GLOB_METACHAR_RE.test(s.text));
+        }
+        if (first < 0)
+            return undefined;
+        let frontier = [p.slice(0, segs[first].start).replace(/[\\/]+$/, "") || "/"];
+        let dirsUsed = 0;
+        let matches = 0;
+        const canonicalOfMatch = new Map();
+        for (let j = first; j < segs.length; j++) {
+            const seg = segs[j].text;
+            if (!GLOB_METACHAR_RE.test(seg)) {
+                frontier = frontier.map((d) => joinCandidate(d, seg));
+                continue;
+            }
+            const re = compileGlobSegment(seg);
+            if (re === undefined) {
+                return { unverifiable: `the pattern "${seg}" cannot be expanded to verify what it would read` };
+            }
+            const isLast = j === segs.length - 1;
+            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` };
+                }
+                const canonDir = await resolve(dir, signal);
+                if (canonDir !== undefined && canonDir.missing === true)
+                    continue;
+                if (canonDir !== undefined && !canonDir.exact) {
+                    return { unverifiable: `"${dir}" cannot be resolved to verify what "${seg}" would expand to` };
+                }
+                const listed = await env.listDir(canonDir?.value ?? dir, signal);
+                if (!listed.ok) {
+                    if (listed.error.code === "not_found" || listed.error.code === "not_directory")
+                        continue;
+                    return { unverifiable: `"${dir}" cannot be enumerated to verify what "${seg}" would expand to (${listed.error.code})` };
+                }
+                if (seg.startsWith(".")) {
+                    for (const dot of [".", ".."])
+                        if (re.test(dot))
+                            next.push(joinCandidate(dir, dot));
+                }
+                const canonDirHere = isLast ? canonDir?.value : undefined;
+                for (const entry of listed.value) {
+                    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` };
+                    }
+                    const candidate = joinCandidate(dir, entry.name);
+                    if (canonDirHere !== undefined && entry.kind !== "symlink")
+                        canonicalOfMatch.set(candidate, joinCandidate(canonDirHere, entry.name));
+                    next.push(candidate);
+                }
+            }
+            frontier = next;
+            if (frontier.length === 0)
+                return { paths: [], canonical: canonicalOfMatch };
+        }
+        return { paths: frontier, canonical: canonicalOfMatch };
+    };
+    return {
+        escapesAfterResolution: async (paths, ask, signal) => {
+            const deny = ask.deny;
+            if (lexicalOnly || (paths.literal.length === 0 && paths.patterns.length === 0))
+                return { escaping: [] };
+            const roots = await canonicalRoots(signal);
+            const escaping = [];
+            let unresolvable;
+            let denied;
+            const denyHit = (p) => {
+                if (deny === undefined || denied !== undefined)
+                    return false;
+                const folded = normalizeAbsPathLexically(p);
+                if (ask.denyAnswered.has(folded))
+                    return false;
+                const pattern = deny(folded);
+                if (pattern === null)
+                    return false;
+                denied = { path: folded, pattern };
+                return true;
+            };
+            const judge = async (p, canonicalKnown, origin) => {
+                if (denyHit(p))
+                    return;
+                const real = canonicalKnown !== undefined ? { value: canonicalKnown, exact: true } : await resolve(p, signal);
+                if (real === undefined) {
+                    if (resolverIsAuthoritative)
+                        unresolvable ??= `"${p}" cannot be resolved to verify where it reads`;
+                    return;
+                }
+                if (!real.exact && real.missing !== true) {
+                    unresolvable ??= `"${p}" cannot be resolved to verify where it reads`;
+                    return;
+                }
+                if (denyHit(real.value))
+                    return;
+                if (ask.containmentAnswered.has(normalizeAbsPathLexically(origin ?? p)))
+                    return;
+                if (ask.containment && !withinAnyRoot(roots, real.value) && !escaping.includes(real.value))
+                    escaping.push(real.value);
+            };
+            for (const p of paths.literal) {
+                if (denied !== undefined)
+                    break;
+                await judge(p);
+            }
+            for (const p of paths.patterns) {
+                if (denied !== undefined)
+                    break;
+                const expanded = await expandGlobCandidate(p, roots, signal);
+                if (expanded !== undefined && "unverifiable" in expanded) {
+                    unresolvable ??= expanded.unverifiable;
+                    continue;
+                }
+                if (expanded !== undefined && expanded.paths.length > 0) {
+                    for (const t of expanded.paths) {
+                        if (denied !== undefined)
+                            break;
+                        await judge(t, expanded.canonical.get(t), p);
+                    }
+                }
+                else
+                    await judge(p);
+            }
+            if (denied !== undefined)
+                return { escaping, denied };
+            return unresolvable === undefined ? { escaping } : { escaping, unverifiable: unresolvable };
+        },
+        canonicalOf: async (path, signal) => {
+            if (lexicalOnly)
+                return undefined;
+            const real = await resolve(path, signal);
+            return real === undefined || (!real.exact && real.missing !== true) ? undefined : real.value;
+        },
+        allResolveInside: async (paths, signal) => {
+            if (lexicalOnly || paths.length === 0)
+                return false;
+            const roots = await canonicalRoots(signal);
+            for (const p of paths) {
+                const real = await resolve(p, signal);
+                if (real === undefined || (!real.exact && real.missing !== true))
+                    return false;
+                if (!withinAnyRoot(roots, real.value))
+                    return false;
+            }
+            return true;
+        },
+    };
+}
+export const NOTHING_ANSWERED = new Set();

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

@@ -0,0 +1,113 @@
+/**
+ * `planShellReads` — ONE parse of a shell command into the read candidates every shell face judges from.
+ *
+ * The read boundary today re-derives "which words may be read" at several sites (the compound walk, the
+ * containment-only gate, the refused-command whitelist, the execute-time recheck), each with its own idea
+ * of launchers, option slots, redirections and re-entry. This module is the single extraction those sites
+ * are to consume: a pure, zero-I/O function over the lenient lexer (`bash-lexer.ts`) and the program-position
+ * reader (`bash-program-position.ts`), returning every path word a command MAY read, each tagged with its
+ * PROVENANCE (why it is a candidate) and the working-directory candidates it is relative to. Establishment
+ * (`shell-read-establish.ts`) and judgment are downstream; nothing here decides allow/ask/deny.
+ *
+ * Contract, in one sentence per rule:
+ *  · a LISTED reader hands its positional operands and the declared option-value slots (the verb tables of
+ *    `bash-readonly-classifier.ts`, read here through their exported readers, never copied);
+ *  · an UNLISTED program hands every word of its argv (a program declared to open no path operand hands none);
+ *  · a LAUNCHER chain is peeled to its program and the chain's own words are never candidates; a launcher
+ *    option the row cannot read is recorded as a decline and every word after it is handed over;
+ *  · a SHELL re-entry (`sh -c S`, `eval S`, a launcher handing text to a shell, `env -S S`) carries its text as a
+ *    NESTED plan; an argv re-entry (`xargs`) is a decline unless the target opens nothing it is handed;
+ *  · an INTERPRETER's inline program is a shape fact (`reentry:"interpreter"`), never parsed, never a finding;
+ *  · `<` targets are read candidates, `>`-family targets are write targets (tagged, not read), here-documents
+ *    and here-strings are data (an UNQUOTED here-document body's substitutions are nested plans);
+ *  · `$(…)`, 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.
+ * Every ambiguity resolves toward MORE candidates, never fewer.
+ */
+import { type LenientConnector, type LexedRedirect, type LexedWord } from "./bash-lexer.js";
+import { type ShellScanDecline } from "./bash-program-position.js";
+/** WHY a word is a read candidate — a closed set, registered in `docs/CLOSED-SETS.md`. */
+export declare const READ_CANDIDATE_PROVENANCES: readonly ["operand", "option_value", "stdin_redirect", "write_redirect_target", "env_assignment", "unlisted_word", "traversal_root", "cd_target", "program_path", "script_slot_file"];
+export type ReadCandidateProvenance = (typeof READ_CANDIDATE_PROVENANCES)[number];
+/** What the caller declares about the deployment: the listed readers and the boundary the bases start from. */
+export interface ShellReadDeclarations {
+    /** The listed read verbs. They decide whether a segment is read by verb slots or word by word, never whether it hands candidates. */
+    readonly readers: ReadonlySet<string>;
+    /** Substituted for `$HOME` / `${HOME}` word spellings before lexing; `~` itself is left to establishment. */
+    readonly homeDir?: string;
+    /** The working directory the first segment's relative words resolve against. */
+    readonly cwd: string;
+    readonly roots: readonly string[];
+    readonly face?: "open" | "roots";
+}
+export interface ReadCandidate {
+    /** The folded word (quotes removed, a literal leading tilde spelled `./~`). */
+    readonly spelled: string;
+    /** The raw spelling, quotes retained — where "is this metacharacter quoted" is still answerable. */
+    readonly raw: string;
+    readonly provenance: ReadCandidateProvenance;
+    /** `"glob"` = an unquoted pathname-expansion character; `"unresolvable"` = the shell rewrites the word
+     *  (brace/variable/command substitution) so its text is not the path. */
+    readonly expands: false | "glob" | "unresolvable";
+    /** The working directories this word may be relative to (a candidate SET where a `cd` could not be proven);
+     *  EMPTY for an absolute or home-rooted spelling; `"unmodelled"` for a relative word in a segment whose base the
+     *  text does not settle (an unfollowable move before it, a loop this parser cannot count) — it cannot be placed. */
+    readonly bases: readonly string[] | "unmodelled";
+}
+/** How the shell reached one segment — what the base-candidate walk needs from the connectors. */
+export interface SegmentReach {
+    /** Reached from the previous emitted segment through `&&` only: everything before it exited zero. */
+    readonly andJoined: boolean;
+    /** The crossing that broke the `&&` run carried a `||`. */
+    readonly orBroken: boolean;
+    /** A directory change here, once proven to have run, moves the base the later segments see. */
+    readonly moveProvable: boolean;
+}
+export interface ShellReadRedirect {
+    readonly op: LexedRedirect["op"];
+    readonly direction: "in" | "out" | "dup";
+    readonly target?: ReadCandidate;
+}
+export interface ShellReadSegment {
+    readonly text: string;
+    readonly connector: LenientConnector;
+    /** Every argv word (structure removed); the shape consumers' input. The read judgment reads `reads` only. */
+    readonly argv: readonly LexedWord[];
+    /** The launcher chain in front of the program (`env`, `nice`, …) — never candidates. */
+    readonly launcherChain: readonly string[];
+    readonly verb?: {
+        readonly name: string;
+        readonly basename: string;
+        readonly listed: boolean;
+    };
+    /** `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";
+    readonly declines: readonly ShellScanDecline[];
+    readonly reads: readonly ReadCandidate[];
+    readonly redirects: readonly ShellReadRedirect[];
+    readonly baseMove?: {
+        readonly target: ReadCandidate | "home" | "previous" | "unmodelled";
+    };
+    /** The working directories this segment may be standing in (what every relative candidate's `bases` is), or
+     *  `"unmodelled"` when the text does not settle it. */
+    readonly bases: readonly string[] | "unmodelled";
+    /** Substitution bodies, unquoted here-document substitutions, and re-entered shell text, each its own plan. */
+    readonly nested: readonly ShellReadPlan[];
+    readonly reach: SegmentReach;
+}
+export interface ShellReadPlan {
+    readonly segments: readonly ShellReadSegment[];
+    /** The lexer refused the whole text (an unterminated construct, nesting past the bound). UNCONDITIONAL
+     *  fail-closed for the consumer: a quote-blind re-read yields more words, never zero, so this is not "no candidates". */
+    readonly unreadable?: string;
+    /** Shape facts the same lex produced, for the shape consumers; the read judgment does not read them. */
+    readonly shape: {
+        readonly grouped: boolean;
+        readonly backgrounded: boolean;
+        readonly strayRedirection: boolean;
+    };
+}
+export declare function planShellReads(command: string, decl: ShellReadDeclarations, depth?: number): ShellReadPlan;