@crewhaus/tool-executor 0.7.0 → 0.8.0

package/dist/permission-subject.js

@@ -0,0 +1,1688 @@
+import { climbsAfterName, holdsUnexpanded, linesRunBy, normalizePathLexically, programWords, readsShellOnInput, shellProgramWords, withShellPwd, } from "@crewhaus/tool-permission-matcher";
+import { validateToolInput } from "@crewhaus/tool-validate";
+const kindsAgree = true;
+void kindsAgree;
+/**
+ * Parse `rawInput` with the tool's schema and read its operative values. The
+ * input passed here must be exactly the one that will be handed to
+ * `executeTool`, so the rule and the tool see the same call.
+ */
+export function preparePermissionSubject(tool, rawInput, opts = {}) {
+    const validation = validateToolInput(tool, rawInput);
+    if (!validation.ok)
+        return { ok: false, reason: validation.error.message };
+    const operativeValues = operativeValuesFor(tool, validation.value, opts);
+    return {
+        ok: true,
+        input: validation.value,
+        ...(operativeValues !== undefined ? { operativeValues } : {}),
+    };
+}
+/**
+ * The canonical operative values of an ALREADY PARSED input, or `undefined`
+ * when the tool declares no `operativeArgs`, or declares `[]` (the matcher
+ * then falls back to the input's string values).
+ */
+export function operativeValuesFor(tool, parsedInput, opts = {}) {
+    return valuesOf(tool.operativeArgs, parsedInput, opts, serviceDefaultsOf(tool, parsedInput, opts.toolConfig));
+}
+/**
+ * {@link operativeValuesFor} from a declaration alone — for a caller that has
+ * a tool's `operativeArgs` as data (the builtin manifest) but not the tool.
+ * The values are read the same way, except that a call naming no API in a
+ * `service` field is read without an origin: which API it goes to is the
+ * tool's to say. The caller is responsible for passing an input the tool's
+ * schema has parsed, when it can.
+ */
+export function operativeValuesOf(operativeArgs, parsedInput, opts = {}) {
+    return valuesOf(operativeArgs, parsedInput, opts, undefined);
+}
+/** A service the tool could not name: nothing an allow could grant. */
+const UNPLACEABLE_SERVICE = { url: "", otherOrigins: [], hosts: [] };
+function serviceDefaultsOf(tool, parsedInput, toolConfig) {
+    const { serviceDefaults } = tool;
+    if (serviceDefaults === undefined)
+        return undefined;
+    let read;
+    try {
+        read = serviceDefaults(parsedInput, toolConfig);
+    }
+    catch {
+        // The tool cannot say where the call goes (a config it cannot read,
+        // which fails the call too): read as a place no allow names.
+        return { unnamed: UNPLACEABLE_SERVICE };
+    }
+    if (read === undefined)
+        return undefined;
+    const home = serviceOf(read.home).origin;
+    return { unnamed: serviceOf(read.unnamed), ...(home !== undefined ? { home } : {}) };
+}
+function valuesOf(operativeArgs, parsedInput, opts, services) {
+    if (operativeArgs === undefined || operativeArgs.length === 0)
+        return undefined;
+    const canonicalizePath = opts.canonicalizePath ?? lexicalPathValues;
+    const values = [];
+    // The defaults of relocating fields the call left out. Whether an allow
+    // reads them depends on what else the call carries, so they are placed
+    // last (see `relocates` on OperativeArg).
+    const relocated = [];
+    for (const arg of operativeArgs) {
+        const from = values.length;
+        for (const { value: raw, words, runsIn, env, stdin, dir, leavesDir, unqualified, every, anyAfter, defaulted, anyQualifier, prefixOf, service, overlay, } of readField(parsedInput, arg, services)) {
+            if (arg.relocates === true && defaulted === true) {
+                if (arg.kind === "url")
+                    relocated.push(canonicalUrl(raw));
+                else {
+                    // A store the tool reads whole, whatever record the call names
+                    // (DatasetMine's sessions directory), is read with what is in it.
+                    const { beneath } = arg;
+                    const read = canonicalizePath(raw);
+                    relocated.push(...(beneath !== undefined ? read.map((v) => withBeneath(v, beneath)) : read), ...openedValues(raw, arg, canonicalizePath));
+                }
+                continue;
+            }
+            switch (arg.kind) {
+                case "path": {
+                    if (every === true) {
+                        values.push(...everyPathValues(dir ?? ".", canonicalizePath));
+                        break;
+                    }
+                    if (leavesDir !== undefined) {
+                        values.push(leavingValue(raw, leavesDir.written));
+                        break;
+                    }
+                    const read = canonicalizePath(raw);
+                    const { beneath } = arg;
+                    if (arg.glob === true) {
+                        // A pattern the tool lists the paths of: the matcher reads it as
+                        // every path it can list.
+                        values.push(...read.map((v) => (v.outsideWorkspace === true ? v : { ...v, globPattern: true })));
+                        break;
+                    }
+                    // A walk that skips hidden names opens them too when the call sets
+                    // the switch its declaration names (Tree's `includeHidden`). A tool
+                    // that acts beneath the path only when the call sets a switch
+                    // (TempDir's `clear`) otherwise acts on the path alone.
+                    const walk = arg.beneathWhen !== undefined && !switchedOn(parsedInput, arg.beneathWhen)
+                        ? undefined
+                        : beneath === "visible" &&
+                            arg.hiddenWhen !== undefined &&
+                            switchedOn(parsedInput, arg.hiddenWhen)
+                            ? "all"
+                            : beneath;
+                    values.push(...(walk !== undefined ? read.map((v) => withBeneath(v, walk)) : read));
+                    values.push(...openedValues(raw, arg, canonicalizePath));
+                    break;
+                }
+                case "url":
+                    values.push(every === true
+                        ? { kind: "url", canonical: [ANY_VALUE], standsForAny: [""] }
+                        : service !== undefined
+                            ? apiRootValue(service)
+                            : canonicalUrl(raw));
+                    break;
+                case "command": {
+                    const dirValues = runsIn !== undefined ? canonicalizePath(runsIn) : undefined;
+                    const elsewhere = runsIn !== undefined && dirValues !== undefined && !namesWorkspaceRoot(dirValues);
+                    const setsEnv = env !== undefined && Object.keys(env).length > 0;
+                    const argv = words ?? raw.split(/\s+/).filter((w) => w !== "");
+                    // A shell parses a string it is handed; an argv reaches one only
+                    // when the program it names is a shell, an eval or an env -S.
+                    const shellLine = arg.shell === true && words === undefined;
+                    const shell = shellLine ? { shell: true } : {};
+                    // The lines an argv hands a shell: one it runs with `-c`, and the
+                    // text the call puts on the input of a shell given no script.
+                    const shellLines = words !== undefined
+                        ? [
+                            ...linesRunBy(words),
+                            ...(stdin !== undefined && readsShellOnInput(words) ? [stdin] : []),
+                        ]
+                        : [];
+                    const where = { runsIn, readProgramPath: opts.readProgramPath };
+                    const read = commandSpellings(argv, elsewhere ? runDirSpellings(runsIn, dirValues) : [], setsEnv ? env : undefined, canonicalizePath, where);
+                    // The words that name a file, read where the OS finds them: an
+                    // argv's own, and those of each command of a line a shell runs
+                    // (the Bash tool's, or one an argv hands to `sh -c`). A string that
+                    // is neither, and runs nowhere in particular, is code for a sandboxed
+                    // interpreter (`Python`'s `code`), not a command line.
+                    const found = programWords(argv);
+                    const own = shellLine
+                        ? readShellPrograms([raw], where)
+                        : words !== undefined || arg.within !== undefined
+                            ? readCommand(argv, found, [{ runsIn, prefix: "" }], where, {
+                                rewrite: true,
+                                shell: false,
+                            })
+                            : NOTHING_READ;
+                    // A line an argv hands a shell starts where the wrappers before
+                    // the shell moved to (`env -C dir sh -c …`).
+                    const handed = readShellPrograms(shellLines, where, chdirPrefix(found));
+                    // A word that lands elsewhere than it reads is put in its place for
+                    // an allow. A line an argv hands a shell cannot have it put in, so
+                    // no scoped allow grants the argv; one the Bash tool runs is
+                    // granted only by an allow that also names each command with it
+                    // put in (`placed`, below).
+                    const ungrantable = own.unplaceable ||
+                        own.ungrantable ||
+                        handed.unplaceable ||
+                        handed.moved ||
+                        handed.ungrantable;
+                    const unplaceable = read.unreadable || own.unplaceable || handed.unplaceable;
+                    const programSpellings = shellLine ? [] : own.spellings;
+                    if (elsewhere || setsEnv || ungrantable) {
+                        // Run in another directory, or with an environment the call set,
+                        // the same words may be another program: nothing canonical for an
+                        // allow to grant. A deny or ask reads what was written, and each
+                        // word also as the file it names there — `release.sh` run in
+                        // `scripts/` is `scripts/release.sh`, which a deny may name.
+                        values.push({
+                            kind: "command",
+                            canonical: [],
+                            spellings: [
+                                ...new Set([raw, ...(words ?? []), ...read.spellings, ...programSpellings]),
+                            ],
+                            ...shell,
+                            ...(unplaceable ? { outsideWorkspace: true } : {}),
+                            ...(every === true ? { standsForAny: [""] } : {}),
+                        });
+                    }
+                    else {
+                        // A program word that lands elsewhere than it reads is read where
+                        // it lands: `./scripts/../evil.sh` is `./evil.sh`, which
+                        // `RunCommand(./scripts/**)` does not grant.
+                        const canonical = own.rewritten?.join(" ") ?? raw;
+                        const spellings = [
+                            ...new Set([
+                                ...(canonical !== raw ? [raw] : []),
+                                ...(words ?? []),
+                                ...read.spellings,
+                                ...programSpellings,
+                            ]),
+                        ];
+                        values.push({
+                            kind: "command",
+                            canonical: [canonical],
+                            ...(spellings.length > 0 ? { spellings } : {}),
+                            ...shell,
+                            ...(anyAfter !== undefined ? { standsForAny: anyAfter } : {}),
+                        });
+                        // A word node would open elsewhere than the kernel walks to is
+                        // read in both places: `RunCommand(node safe/**)` does not grant
+                        // `node lnk/../x.mjs` (lnk → safe/sub), which runs `./x.mjs`.
+                        if (own.rewrittenAsText !== undefined) {
+                            values.push({ kind: "command", canonical: [own.rewrittenAsText.join(" ")] });
+                        }
+                        // A line a shell parses cannot have a word put in its place, so
+                        // an allow reads each command whose words moved, with them put
+                        // in, as well as the line: `Bash(./scripts/**)` does not grant
+                        // `./scripts/lnk/run.sh` (lnk → ../evil), and `Bash(node **)`
+                        // still grants a script through a linked package directory.
+                        for (const command of new Set(own.placed)) {
+                            values.push({ kind: "command", canonical: [command] });
+                        }
+                    }
+                    values.push(...shellLineValues(shellLines));
+                    // What a deny or ask reads of the program words in a line a shell
+                    // parses, as plain text: read as a line again, a word with its
+                    // quoting taken off could split into commands the line never runs.
+                    values.push(...programPlaceValues(shellLine ? [...own.spellings, ...handed.spellings] : handed.spellings, [...own.patterns, ...handed.patterns]));
+                    break;
+                }
+                default: {
+                    if (arg.secretRef === true) {
+                        values.push(...secretRefValues(raw, canonicalizePath));
+                        break;
+                    }
+                    const spellings = [...(words ?? []), ...(unqualified ?? [])];
+                    const read = {
+                        kind: arg.kind,
+                        canonical: [raw],
+                        ...(spellings.length > 0 ? { spellings } : {}),
+                        ...(HEX_ID.test(raw) ? { caseInsensitive: true } : {}),
+                        ...(anyAfter !== undefined ? { standsForAny: anyAfter } : {}),
+                        ...(anyQualifier === true ? { anyQualifier: true } : {}),
+                        // A prefix stands for every value that starts with it, and a
+                        // key may hold `/`: what follows is any run, not one segment.
+                        ...(prefixOf !== undefined ? { standsForAnyRun: true } : {}),
+                    };
+                    // An owner's own copy of the value (a tenant's overlay of a pin).
+                    const value = overlay !== undefined ? overlaidValue(read, overlay) : read;
+                    // A value on a service is that service's: an allow names its
+                    // origin, a deny also reads the URL as a URL.
+                    if (service !== undefined) {
+                        values.push(servedValue(value, service));
+                        if (service.url !== "") {
+                            values.push({ ...canonicalUrl(service.url), restrictOnly: true });
+                            // The tool drops one trailing slash from an API root before it
+                            // joins a request path, so `…/api/v3/` is the API `…/api/v3`:
+                            // a deny or ask written on that one meets it too.
+                            if (service.url.endsWith("/") && service.url.length > 1) {
+                                values.push({ ...canonicalUrl(service.url.slice(0, -1)), restrictOnly: true });
+                            }
+                        }
+                    }
+                    else
+                        values.push(value);
+                    // The prefix alone, for a deny or ask written without the
+                    // qualifier (`alwaysDeny KvGet(apikey)`, as for any `within`
+                    // field). Read one segment on: with a run, a deny naming another
+                    // namespace's key (`secrets/apikey`) would fire on every listing
+                    // with no prefix, whatever namespace it lists.
+                    if (prefixOf?.unqualified !== undefined) {
+                        values.push({
+                            kind: arg.kind,
+                            canonical: [],
+                            standsForAny: [prefixOf.unqualified],
+                            restrictOnly: true,
+                        });
+                    }
+                }
+            }
+        }
+        // Where the tool takes a value from, or a field it ignores because the
+        // call names another: a deny or ask reads it, an allow is about where
+        // the tool acts (`source` and `ignoredWhen` on OperativeArg).
+        if (arg.source === true ||
+            (arg.ignoredWhen !== undefined && qualifierOf(parsedInput, arg.ignoredWhen) !== undefined)) {
+            for (let i = from; i < values.length; i++) {
+                values[i] = { ...values[i], restrictOnly: true };
+            }
+        }
+    }
+    // A relocating field's default is a place the call did not name. When the
+    // call names a record there, an allow is about the record and skips the
+    // default; a deny or ask still reads it. With nothing else to read, the
+    // default is the call's only place, and every rule reads it.
+    if (values.length > 0) {
+        for (const v of relocated)
+            values.push({ ...v, restrictOnly: true });
+    }
+    else {
+        values.push(...relocated);
+    }
+    return values;
+}
+/**
+ * The lines an argv hands to a shell (`["sh", "-c", "…"]`), as values only a
+ * deny or ask reads: no allow is widened or narrowed by them, and a deny
+ * reads each simple command in them.
+ */
+function shellLineValues(lines) {
+    if (lines.length === 0)
+        return [];
+    return [
+        { kind: "command", canonical: [], spellings: [...lines], shell: true, restrictOnly: true },
+    ];
+}
+/**
+ * Where the words of a command that name code it runs land, as values only a
+ * deny or ask reads, never read as a shell line: see {@link readCommand}.
+ * A word the shell expands as a pattern is read as every path it can list.
+ */
+function programPlaceValues(spellings, patterns) {
+    const out = [];
+    if (spellings.length > 0) {
+        out.push({
+            kind: "command",
+            canonical: [],
+            spellings: [...new Set(spellings)],
+            restrictOnly: true,
+        });
+    }
+    if (patterns.length > 0) {
+        out.push({
+            kind: "command",
+            canonical: [],
+            spellings: [...new Set(patterns)],
+            globPattern: true,
+            restrictOnly: true,
+        });
+    }
+    return out;
+}
+/**
+ * A secret reference (`secretRef` on its OperativeArg), read the way
+ * `@crewhaus/tool-secrets`' `parseRef` reads it: with the whitespace around
+ * it trimmed, and its `file:` and `envfile:` forms naming a workspace file.
+ * Such a reference is matched with the file's canonical path in it — where
+ * it lands, `./`, `..` and links resolved — so `file:./secrets/token`,
+ * `file:pub/../secrets/token` and `file:pub/lnk/token` (a link to
+ * `../secrets`) are all `file:secrets/token`, which an allow must name and a
+ * deny on `file:secrets/**` names. The reference as written and trimmed is
+ * a spelling a deny or ask also reads, and the file is a path value only a
+ * deny or ask reads (`alwaysDeny *(secrets/**)`). A file outside the
+ * workspace is outside: every deny or ask fires, no allow grants it. Any
+ * other form (`env:NAME`, `keychain:…`, `op://…`) is an id. A bare NAME is
+ * an id an allow names as written; it is also looked up in the files of the
+ * local chain ({@link secretChain}), which a deny or ask reads as those
+ * references and those files, so `alwaysDeny *(.env)` fires on `API_KEY`.
+ * An `env:NAME` is an id an allow names as written too, but the environment
+ * it reads holds the chain's env files in every harness — the supervisor
+ * merges `.env.local` and `.env` into the environment it spawns a harness
+ * with, and Bun loads them from the directory it starts in — so a deny or ask
+ * reads those two the same way: `alwaysDeny *(.env)` fires on `env:API_KEY`.
+ */
+function secretRefValues(raw, canonicalizePath) {
+    const ref = raw.trim();
+    const place = secretRefPlace(ref);
+    if (place === undefined) {
+        const id = {
+            kind: "id",
+            canonical: [ref],
+            ...(ref !== raw ? { spellings: [raw] } : {}),
+            ...(HEX_ID.test(ref) ? { caseInsensitive: true } : {}),
+        };
+        const envName = ENV_SECRET_REF.exec(ref)?.[1];
+        const steps = BARE_SECRET_NAME.test(ref)
+            ? secretChain(ref)
+            : envName !== undefined
+                ? secretChain(envName).filter((step) => step.scheme === "envfile")
+                : [];
+        return [
+            id,
+            ...steps.flatMap((step) => placeValues(step, canonicalizePath).map((v) => ({ ...v, restrictOnly: true }))),
+        ];
+    }
+    // The reference as written and as trimmed are spellings a deny reads too.
+    return placeValues(place, canonicalizePath).map((v) => v.kind === "id" ? { ...v, spellings: [...new Set([raw, ref, ...(v.spellings ?? [])])] } : v);
+}
+/**
+ * The file one `file:` or `envfile:` reference opens, as the values a rule
+ * reads: the reference with the file's canonical path in it, which an allow
+ * names, and the file itself as a path only a deny or ask reads.
+ */
+function placeValues(place, canonicalizePath) {
+    const named = (path) => `${place.scheme}:${path}${place.key}`;
+    const out = [];
+    for (const file of canonicalizePath(place.path)) {
+        const spellings = [...new Set([named(place.path), ...(file.spellings ?? []).map(named)])];
+        out.push(file.outsideWorkspace === true
+            ? { kind: "id", canonical: [], spellings, outsideWorkspace: true }
+            : { kind: "id", canonical: file.canonical.map(named), spellings });
+        out.push({ ...file, restrictOnly: true });
+    }
+    return out;
+}
+/** A command none of whose words is read as a place. */
+const NOTHING_READ = {
+    moved: false,
+    unplaceable: false,
+    ungrantable: false,
+    spellings: [],
+    patterns: [],
+    placed: [],
+};
+/** The words a shell runs as `NAME=value`, which name no file. */
+const ASSIGNMENT_WORD = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/**
+ * A reference to a directory the shell itself sets, `PWD` or `OLDPWD`, in
+ * any spelling: `${PWD%/*}`, `$OLDPWD`, `$(dirname "$PWD")`. Only a plain
+ * `$PWD` or `${PWD}` at the start of a word is put in ({@link withShellPwd});
+ * any other is the text of a directory a `cd` went through, a link's name
+ * and all, which the gate cannot place.
+ */
+const SHELL_DIRECTORY_VARIABLE = /\$\{?[#!]?(?:OLD)?PWD(?![A-Za-z0-9_])/;
+/**
+ * Read the words of one command that name a file where the OS finds them,
+ * from each directory it may run in ({@link WordDir}):
+ *
+ * - its programs, through any wrappers, when written with a `/` — and a bare
+ *   one on each entry of a PATH a wrapper or the line sets (`env PATH=dir
+ *   x`, `PATH=dir x`), as an argv's `envSet` PATH is read;
+ * - each word an interpreter at the end is handed (its script, and what
+ *   else it loads);
+ * - and every other word with a `/`, or any word in a directory the command
+ *   moved to: an argument, which another program may still run (`caffeinate
+ *   x`, `find -exec x`). An argv's words are each a spelling a deny reads, so
+ *   where one lands is too; a shell line's are not, and are only bound to
+ *   where they land for an approval.
+ *
+ * Read through `readProgramPath`, each lands where the kernel takes it:
+ * every directory on the way followed and each `..` applied after the link
+ * before it. A program or script that lands elsewhere than it reads — a
+ * `..` after a name, or a symlinked directory on the way — is put in its
+ * place ({@link placeForms}), so an allow reads where it lands; a deny or ask
+ * also reads that place in each of its forms, and, when the word itself is a
+ * symlink, where it leads. A program named by an absolute path outside the
+ * workspace with no `..` after a name is not put in its place: the system's
+ * own links (`/bin → usr/bin`) are not the call's to move, and an allow
+ * written `/bin/sh` still reads `/bin/sh`.
+ *
+ * Not every program opens a word the way the kernel walks it. node, `bun
+ * run` and a script whose `#!` line names node fold its `..` as text first
+ * (`path.resolve`, then its links followed), so `node lnk/../x.mjs` with
+ * `lnk → safe/sub` runs `./x.mjs`, not the `safe/x.mjs` the kernel walks to.
+ * So a word with a `..` after a name is also read that way
+ * ({@link foldedAsText}), and where the two readings land apart a deny or
+ * ask reads both. An allow must name both too — the command with the word in
+ * each place — unless the word is the script of an interpreter measured to
+ * open it through the kernel (`kernelScript`: a shell, Python 3, Perl,
+ * Ruby). A program run by its path is always read both ways: the
+ * interpreter its `#!` line names may be node. A command with more than one
+ * word read apart may run them in any mix of places, and no scoped allow
+ * grants it. A word a shell started with `$PWD` that climbs out of it is
+ * folded against the text of `$PWD` (see the module doc).
+ *
+ * A word cannot be placed — every deny or ask fires, and only an allow
+ * naming every command grants it — when it has a `..` after a name and no
+ * reader can follow the links before it (the edge worker), or it is read
+ * from a directory that cannot be told; when a shell's word names its own
+ * directory in a spelling not put in ({@link SHELL_DIRECTORY_VARIABLE});
+ * when a script is a pattern with a wildcard before its last name; or when
+ * the reader cannot walk it. A word
+ * from a directory that cannot be told, or that a variable the line does
+ * not set or a `~` starts, is otherwise read as written.
+ */
+function readCommand(words, found, dirs, where, opts) {
+    const spellings = new Set();
+    const patterns = new Set();
+    const placed = new Set();
+    let rewritten;
+    let rewrittenAsText;
+    let moved = false;
+    let unplaceable = false;
+    let ungrantable = false;
+    const programs = new Set(found.programs);
+    const operands = new Set(found.operands);
+    // Collapsed as text, once: a deny written against the call's own words.
+    for (const i of [...found.programs, ...found.operands]) {
+        const word = opts.shell ? withShellPwd(words[i]) : words[i];
+        if (programs.has(i) && !/[\\/]/.test(word))
+            continue;
+        if (word.includes("://"))
+            continue;
+        for (const c of collapsedWords(word))
+            spellings.add(c);
+    }
+    for (const dir of dirs) {
+        // The words with every placed word in one of its forms, per form, and
+        // whether one of those is a pattern.
+        const lines = new Map();
+        const put = (slot, i, form, pattern) => {
+            let line = lines.get(slot);
+            if (line === undefined) {
+                line = { words: [...words], pattern: false };
+                lines.set(slot, line);
+            }
+            line.words[i] = form;
+            line.pattern ||= pattern;
+            (pattern ? patterns : spellings).add(form);
+        };
+        // The words with each one that moved put in its place, for an allow.
+        const inPlace = [...words];
+        let movedHere = false;
+        // A bare program found on a PATH entry that moved: one line each.
+        const lookups = [];
+        // Each word an allow reads in two places, with where it lands folded as
+        // text: the command with it there is one more an allow must name.
+        const apart = [];
+        /** Read one word, or one PATH candidate for word `i`; see above. */
+        const readWord = (i, word, role, lookup, fromPwd = false) => {
+            const runs = role === "program";
+            const pattern = opts.shell && opts.patterns?.has(i) === true && !lookup;
+            // The directory it is read from: the command's, then each wrapper's.
+            let prefix = dir?.prefix;
+            for (const { from, dir: to } of found.chdirs) {
+                if (from > i || prefix === undefined)
+                    continue;
+                const written = opts.shell ? withShellPwd(to) : to;
+                prefix = opts.shell && holdsUnexpanded(written) ? undefined : joinedDir(prefix, written);
+            }
+            const cut = Math.max(word.lastIndexOf("/"), word.lastIndexOf("\\")) + 1;
+            const ownDir = word.slice(0, cut);
+            const known = dir !== undefined &&
+                prefix !== undefined &&
+                !(opts.shell && holdsUnexpanded(ownDir)) &&
+                !(opts.shell && word.startsWith("~"));
+            const climbs = climbsAfterName(word);
+            const elsewhere = dir === undefined || dir.runsIn !== where.runsIn || prefix !== "";
+            // A bare argument names no directory of its own: on an argv, read it
+            // where a wrapper moved the command; in a shell line, where only an
+            // approval would be bound to it, not at all.
+            if (role === "argument" && !/[\\/]/.test(word) && (opts.shell || !elsewhere))
+                return;
+            if (!known) {
+                // With a `..` after a name, or under a directory the shell set
+                // (`cd lnk && node ${PWD%/*}/dl/x.mjs` runs dl/x.mjs from the root):
+                // it may land anywhere.
+                const shellDir = opts.shell && SHELL_DIRECTORY_VARIABLE.test(ownDir);
+                if (role !== "argument" && (climbs || shellDir))
+                    unplaceable = true;
+                return;
+            }
+            if (pattern && (/[*?[]/.test(ownDir) || climbs)) {
+                // A wildcard before its last name may match a symlinked directory.
+                if (role === "script")
+                    unplaceable = true;
+                return;
+            }
+            const absolute = isAbsolutePath(word);
+            if (where.readProgramPath === undefined) {
+                const anyDotDot = word.split(/[\\/]/).includes("..");
+                if (role !== "argument" && (climbs || (elsewhere && !absolute && anyDotDot))) {
+                    unplaceable = true;
+                }
+                return;
+            }
+            const readOpts = {
+                ...(role === "argument" || lookup ? { argument: true } : {}),
+                ...(prefix !== "" && !absolute ? { prefix } : {}),
+            };
+            const place = where.readProgramPath(word, dir.runsIn, readOpts);
+            // And with its `..` folded as text first, as node and `bun run` read
+            // it. `$PWD` is the text of where the shell runs, the name of each
+            // link a `cd` went through and all, so one that climbs out of it is
+            // folded against that text: after `cd lnk`, node runs `$PWD/../x.mjs`
+            // as `./x.mjs`. That text is the root and the `cd`s the shell joined;
+            // after a wrapper's or a `cd -P`'s move, or in a call's directory
+            // field, it cannot be told.
+            const asText = foldedAsText(word);
+            const abovePwd = fromPwd && (asText === ".." || asText.startsWith("../"));
+            const pwdKnown = where.runsIn === undefined && prefix === "";
+            const folded = abovePwd
+                ? pwdKnown
+                    ? where.readProgramPath(foldedAsText(joinedDir(dir.runsIn ?? "", word)), undefined, readOpts)
+                    : undefined
+                : climbs
+                    ? where.readProgramPath(asText, dir.runsIn, readOpts)
+                    : undefined;
+            const readsAsText = climbs || abovePwd;
+            if (place === undefined || (readsAsText && folded === undefined && role !== "argument")) {
+                if (role !== "argument")
+                    unplaceable = true;
+                return;
+            }
+            const forms = placeForms(place.at, place.inWorkspace, word, runs);
+            const system = absolute && place.inWorkspace === undefined && !place.writtenInWorkspace;
+            const lands = climbs || (place.at !== place.asWritten && !system);
+            const led = place.target !== undefined
+                ? placeForms(place.target.at, place.target.inWorkspace, word, runs)
+                : [];
+            // Where the two readings land apart, the folded one in its forms.
+            const split = folded !== undefined && folded.at !== place.at ? folded : undefined;
+            const textForms = split !== undefined ? placeForms(split.at, split.inWorkspace, word, runs) : undefined;
+            const asTextLed = split?.target !== undefined
+                ? placeForms(split.target.at, split.target.inWorkspace, word, runs)
+                : [];
+            // An allow names both unless the word is a script its interpreter
+            // opens through the kernel.
+            if (textForms !== undefined && role !== "argument" && (runs || i !== found.kernelScript)) {
+                if (lookup)
+                    lookups.push([i, textForms[0]]);
+                else
+                    apart.push([i, textForms[0]]);
+            }
+            if (role === "argument") {
+                // An argv's words are spellings a deny reads; where one lands is too.
+                if (opts.shell || !(lands || led.length > 0 || elsewhere))
+                    return;
+            }
+            else if (lands) {
+                moved = true;
+                movedHere = true;
+                if (lookup)
+                    lookups.push([i, forms[0]]);
+                else
+                    inPlace[i] = forms[0];
+                if (opts.rewrite) {
+                    // A word read where a wrapper moved the command, or found on a
+                    // PATH: one place in the argv cannot say so.
+                    if (prefix !== "" || lookup)
+                        ungrantable = true;
+                    else {
+                        rewritten ??= [...words];
+                        rewritten[i] = forms[0];
+                    }
+                }
+            }
+            forms.forEach((form, k) => put(k, i, form, pattern));
+            led.forEach((form, k) => put(2 + k, i, form, pattern));
+            textForms?.forEach((form, k) => put(4 + k, i, form, pattern));
+            asTextLed.forEach((form, k) => put(6 + k, i, form, pattern));
+        };
+        for (let i = 0; i < words.length; i++) {
+            const raw = words[i];
+            if (raw === "" || raw.includes("://"))
+                continue;
+            const word = opts.shell ? withShellPwd(raw) : raw;
+            const fromPwd = word !== raw;
+            if (programs.has(i)) {
+                if (/[\\/]/.test(word))
+                    readWord(i, word, "program", false, fromPwd);
+                else {
+                    const lookUp = (candidate) => readWord(i, candidate, "program", true);
+                    if (!readLookups(i, word, found, opts, lookUp))
+                        unplaceable = true;
+                }
+                continue;
+            }
+            if (operands.has(i)) {
+                readWord(i, word, "script", false, fromPwd);
+                continue;
+            }
+            if (word.startsWith("-") || ASSIGNMENT_WORD.test(word))
+                continue;
+            readWord(i, word, "argument", false, fromPwd);
+        }
+        for (const line of lines.values()) {
+            (line.pattern ? patterns : spellings).add(line.words.join(" "));
+        }
+        if (movedHere)
+            placed.add(inPlace.join(" "));
+        for (const [i, form] of [...lookups, ...apart.slice(0, 1)]) {
+            const line = [...inPlace];
+            line[i] = form;
+            placed.add(line.join(" "));
+        }
+        // Two words read apart may be read in any mix of their places, which no
+        // list of commands an allow must name can cover.
+        if (apart.length > 1)
+            ungrantable = true;
+        const [one] = apart;
+        if (one !== undefined && opts.rewrite && rewritten !== undefined) {
+            rewrittenAsText = [...rewritten];
+            rewrittenAsText[one[0]] = one[1];
+        }
+    }
+    return {
+        ...(rewritten !== undefined ? { rewritten } : {}),
+        ...(rewrittenAsText !== undefined ? { rewrittenAsText } : {}),
+        moved,
+        unplaceable,
+        ungrantable,
+        spellings: [...spellings],
+        patterns: [...patterns],
+        placed: opts.shell ? [...placed] : [],
+    };
+}
+/**
+ * A bare program looked up on the PATH a wrapper or the line set for it
+ * (the last one before it), entry by entry: `read` is handed each entry
+ * joined to the program. An entry that a variable the line does not set or
+ * a `~` starts is the harness's own PATH, looked up as before. False for a
+ * PATH of more than {@link MAX_ENV_WORDS} entries, which cannot be read.
+ */
+function readLookups(i, program, found, opts, read) {
+    const path = found.paths.findLast((p) => p.from <= i);
+    if (path === undefined)
+        return true;
+    const entries = path.path.split(":");
+    for (const raw of entries.slice(0, MAX_ENV_WORDS)) {
+        const trimmed = raw === "" ? "." : withoutTrailingSeparators(raw) || "/";
+        const entry = opts.shell ? withShellPwd(trimmed) : trimmed;
+        if (opts.shell && holdsUnexpanded(entry))
+            continue;
+        read(`${entry === "/" ? "" : entry}/${program}`);
+    }
+    return entries.length <= MAX_ENV_WORDS;
+}
+/** `word` joined after the directory `dir` (`""` for none), as text: an absolute `word` stands alone. */
+function joinedDir(dir, word) {
+    if (dir === "" || isAbsolutePath(word))
+        return word;
+    if (word === "")
+        return dir;
+    return /[\\/]$/.test(dir) ? `${dir}${word}` : `${dir}/${word}`;
+}
+/**
+ * The directories a command of a shell line may run in, as
+ * {@link readCommand} reads them: each of `dirs` (relative to where the
+ * line starts) from where it starts — the call's directory field, then
+ * `prefix`, walked, when an argv hands the line to a shell after a wrapper
+ * moved (`env -C dir sh -c …`). One that leaves where the line started by a
+ * leading `..` cannot be told when the shell starts somewhere other than the
+ * root: its PWD is then the physical directory, which the text of the
+ * directory field does not name.
+ */
+function wordDirsOf(dirs, where, prefix) {
+    if (dirs === undefined || prefix === undefined)
+        return [undefined];
+    return dirs.map((d) => {
+        if (prefix !== "" && !isAbsolutePath(d.logical)) {
+            // The shell's PWD is physical already: a `cd` is walked from it, but
+            // one whose `..` follows a name is folded as text by the shell.
+            if (climbsAfterName(d.logical))
+                return undefined;
+            return {
+                runsIn: where.runsIn,
+                prefix: joinedDir(joinedDir(prefix, d.logical), d.physical),
+            };
+        }
+        if (d.logical === "")
+            return { runsIn: where.runsIn, prefix: d.physical };
+        if (isAbsolutePath(d.logical))
+            return { runsIn: d.logical, prefix: d.physical };
+        if (where.runsIn !== undefined && normalizePathLexically(d.logical).escapes)
+            return undefined;
+        return {
+            runsIn: where.runsIn === undefined ? d.logical : joinedDir(where.runsIn, d.logical),
+            prefix: d.physical,
+        };
+    });
+}
+/**
+ * Where the wrappers of an argv moved before the shell at its end (`env -C
+ * dir sh -c …`): their directories joined, as text the kernel walks.
+ */
+function chdirPrefix(found) {
+    let prefix = "";
+    for (const { dir } of found.chdirs)
+        prefix = joinedDir(prefix, dir);
+    return prefix;
+}
+/**
+ * {@link readCommand} for each simple command of each line a shell parses,
+ * at every level a deny reads (`shellProgramWords`), with their quoting
+ * taken off, from each directory it may run in. `prefix` is where a wrapper
+ * moved the argv that hands the line to a shell (`""` for nowhere,
+ * `undefined` when that cannot be told).
+ */
+function readShellPrograms(lines, where, prefix = "") {
+    const spellings = [];
+    const patterns = [];
+    const placed = [];
+    let moved = false;
+    let unplaceable = false;
+    let ungrantable = false;
+    for (const line of lines) {
+        for (const command of shellProgramWords(line)) {
+            // A script an interpreter reads on its input (`sh < x.sh`) is read as
+            // the one it is handed, and the `<` kept in front of it. The shell that
+            // runs the line opens it, through the kernel, whatever reads it.
+            const words = command.stdinScript !== undefined
+                ? [...command.words, "<", command.stdinScript]
+                : command.words;
+            const found = command.stdinScript !== undefined
+                ? {
+                    ...command.programs,
+                    operands: [...command.programs.operands, words.length - 1],
+                    kernelScript: words.length - 1,
+                }
+                : command.programs;
+            const read = readCommand(words, found, wordDirsOf(command.dirs, where, prefix), where, {
+                rewrite: false,
+                shell: true,
+                patterns: new Set(command.patterns),
+            });
+            moved ||= read.moved;
+            unplaceable ||= read.unplaceable;
+            ungrantable ||= read.ungrantable;
+            spellings.push(...read.spellings);
+            patterns.push(...read.patterns);
+            placed.push(...read.placed);
+        }
+    }
+    return { moved, unplaceable, ungrantable, spellings, patterns, placed };
+}
+/**
+ * The forms a rule reads of a place a command word lands at: first the one
+ * written the way the call wrote the word — absolute when the word was, or
+ * when the place is outside the workspace; else relative to the workspace
+ * root, with `./` when the word had one, or when it is a program and the
+ * place has no `/` left (`deploy.sh` alone would be looked up on PATH) —
+ * then the place relative to the root. The workspace's own absolute path is
+ * not one of them unless the call wrote it: `RunCommand(**prod**)` does not
+ * fire on `sh x.sh` because the workspace lives in `prod-agent/`.
+ */
+function placeForms(at, inWorkspace, word, runs) {
+    if (inWorkspace === undefined)
+        return [at, at];
+    const dotted = startsWithDotSlash(word) || (runs && !inWorkspace.includes("/"));
+    const written = isAbsolutePath(word)
+        ? at
+        : dotted && inWorkspace !== "."
+            ? `./${inWorkspace}`
+            : inWorkspace;
+    return [written, inWorkspace];
+}
+/** `./` or `.\\` at the start: a word the call wrote relative to its directory. */
+function startsWithDotSlash(word) {
+    return word.startsWith("./") || word.startsWith(".\\");
+}
+/** A bare reference: an environment-variable name, which the local chain looks up. */
+const BARE_SECRET_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** An `env:NAME` reference, as `parseRef` accepts it; the name is group 1. */
+const ENV_SECRET_REF = /^env:([A-Za-z_][A-Za-z0-9_]*)$/;
+/**
+ * The files a bare NAME is looked up in after the environment, highest
+ * precedence first: `@crewhaus/tool-secrets`' `chainRefs` (the harness
+ * supervisor's `.env.local` and `.env`, then the secrets directory). That
+ * package's tests hold this list to its own.
+ */
+function secretChain(name) {
+    return [
+        { scheme: "envfile", path: ".env.local", key: `#${name}` },
+        { scheme: "envfile", path: ".env", key: `#${name}` },
+        { scheme: "file", path: `.crewhaus/secrets/${name}`, key: "" },
+    ];
+}
+/**
+ * The file a trimmed `file:<path>` or `envfile:<path>#KEY` reference opens,
+ * split as `parseRef` splits it (an `envfile:` at its LAST `#`), with the
+ * rest of the reference around it; `undefined` for any other form, and for
+ * one the tool refuses whole (an empty path, no `#KEY`, a newline or NUL).
+ */
+function secretRefPlace(ref) {
+    if (/[\0\n\r]/.test(ref))
+        return undefined;
+    if (ref.startsWith("file:")) {
+        const path = ref.slice("file:".length);
+        return path === "" ? undefined : { scheme: "file", path, key: "" };
+    }
+    if (ref.startsWith("envfile:")) {
+        const rest = ref.slice("envfile:".length);
+        const hash = rest.lastIndexOf("#");
+        return hash <= 0
+            ? undefined
+            : { scheme: "envfile", path: rest.slice(0, hash), key: rest.slice(hash) };
+    }
+    return undefined;
+}
+/** A value that ends in a `0x` (or `0X`) hex id, after any `<qualifier>/`. */
+const HEX_ID = /(?:^|\/)0[xX][0-9a-fA-F]+$/;
+/** Do these canonical values name the workspace root itself, and nothing else? */
+function namesWorkspaceRoot(values) {
+    return (values.length > 0 && values.every((v) => v.outsideWorkspace !== true && v.canonical[0] === "."));
+}
+/**
+ * Every value of one declared field. Dots descend into objects; an array
+ * anywhere on the way is walked element by element — except a `command`
+ * field that IS an array of strings, which is one argv and is joined. A
+ * field declared `within` another comes back as `<qualifier>/<value>` — a
+ * `..` path too, so a row shows the directory it climbs from — and an
+ * absolute path as it is.
+ */
+export function readOperativeField(input, arg) {
+    return readField(input, arg).map((r) => {
+        const value = r.overlay !== undefined ? `${r.overlay}/${r.value}` : r.value;
+        // A URL that is its own service is the API already.
+        if (isApiRoot(arg))
+            return value;
+        return r.service?.origin !== undefined ? `${r.service.origin}/${value}` : value;
+    });
+}
+/** A `url` declared as its own `service`: the API a call goes to, itself. */
+function isApiRoot(arg) {
+    return arg.kind === "url" && arg.service !== undefined && arg.service === arg.field;
+}
+/**
+ * {@link readValues}, with the API the call goes to for a `service` field:
+ * the one it names, else the one the tool's config sends it to — the same
+ * for every value of the field, since it is a top-level one.
+ */
+function readField(input, arg, services) {
+    const values = readValues(input, arg);
+    const owner = arg.overlay !== undefined ? qualifierOf(input, arg.overlay) : undefined;
+    const read = owner !== undefined ? values.map((r) => ({ ...r, overlay: owner })) : values;
+    if (arg.service === undefined)
+        return read;
+    const url = qualifierOf(input, arg.service);
+    const reading = url !== undefined ? serviceOf(url) : services?.unnamed;
+    if (reading === undefined)
+        return read;
+    const home = reading.origin !== undefined && reading.origin === services?.home;
+    const service = home ? { ...reading, home: true } : reading;
+    // The API itself, left out: the one the tool's config sends the call to
+    // stands in, so a rule on that host meets the call whichever field (or
+    // none) picked it.
+    if (isApiRoot(arg) && read.length === 0)
+        return [{ value: reading.url, service }];
+    return read.map((r) => ({ ...r, service }));
+}
+/** How a rule reads the service URL a call names: see {@link ServiceReading}. */
+function serviceOf(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return { url: raw, otherOrigins: [], hosts: [] };
+    }
+    if ((url.protocol !== "https:" && url.protocol !== "http:") ||
+        url.hostname === "" ||
+        url.username !== "" ||
+        url.password !== "") {
+        return { url: raw, otherOrigins: [], hosts: [] };
+    }
+    const names = new Set([url.hostname, withoutTrailingDots(url.hostname)]);
+    names.delete("");
+    const hosts = new Set();
+    for (const name of names) {
+        for (const port of new Set([url.port, ""]))
+            hosts.add(port !== "" ? `${name}:${port}` : name);
+    }
+    const schemes = url.protocol === "https:" ? ["https:", "http:"] : ["http:", "https:"];
+    const others = new Set();
+    for (const scheme of schemes) {
+        for (const host of hosts) {
+            const origin = `${scheme}//${host}`;
+            if (origin !== url.origin)
+                others.add(origin);
+        }
+    }
+    return { url: raw, origin: url.origin, otherOrigins: [...others], hosts: [...hosts] };
+}
+/** `host` without the root dots at its end, in one pass from the end. */
+function withoutTrailingDots(host) {
+    let end = host.length;
+    while (end > 0 && host.charCodeAt(end - 1) === 0x2e)
+        end--;
+    return host.slice(0, end);
+}
+/**
+ * A value of a field declared `overlay`, read for a call that names whose
+ * copy it acts on: matched with the owner in front, so an allow must name it;
+ * a deny or ask also reads the value without it (the shared copy's name) and
+ * the owner alone.
+ */
+function overlaidValue(value, owner) {
+    const at = (v) => `${owner}/${v}`;
+    const { standsForAny } = value;
+    return {
+        ...value,
+        canonical: value.canonical.map(at),
+        spellings: [...new Set([...value.canonical, ...(value.spellings ?? []), owner])],
+        ...(standsForAny !== undefined
+            ? { standsForAny: [...new Set([...standsForAny.map(at), ...standsForAny])] }
+            : {}),
+    };
+}
+/**
+ * A value of a field declared `service`, read for a call to that service:
+ * matched with the service's origin in front, so an allow must name it —
+ * unless the service is the tool's `home`, whose values are also matched
+ * without it, first. A deny or ask also reads the value without the origin
+ * and with the origin's other spellings. A URL that cannot be placed leaves
+ * nothing an allow could grant, and every deny or ask fires.
+ */
+function servedValue(value, service) {
+    const own = [...value.canonical, ...(value.spellings ?? [])];
+    const { origin } = service;
+    if (origin === undefined) {
+        return {
+            kind: value.kind,
+            canonical: [],
+            spellings: [...own, ...(service.url !== "" ? [service.url] : [])],
+            outsideWorkspace: true,
+        };
+    }
+    const at = (o, v) => `${o}/${v}`;
+    const others = [...service.otherOrigins, ...service.hosts];
+    const { standsForAny } = value;
+    return {
+        ...value,
+        canonical: [
+            ...(service.home === true ? value.canonical : []),
+            ...value.canonical.map((c) => at(origin, c)),
+        ],
+        spellings: [
+            ...new Set([...others.flatMap((o) => value.canonical.map((c) => at(o, c))), ...own]),
+        ],
+        ...(standsForAny !== undefined
+            ? {
+                standsForAny: [
+                    ...new Set([
+                        ...[origin, ...others].flatMap((o) => standsForAny.map((p) => at(o, p))),
+                        ...standsForAny,
+                    ]),
+                ],
+            }
+            : {}),
+    };
+}
+/**
+ * The API a call goes to, for a `url` declared as its own `service`
+ * (RateLimitStatus's `baseUrl`): the one the call names or the one its
+ * config sends it to, read the way the tool reaches it. The tool drops one
+ * trailing slash and appends each request path as text, so `…/api/v3`,
+ * `…/api/v3/`, `…/api/v3/.` and `…/api/v3/x/..` are one API, which is
+ * matched with or without a slash at the end (as `https://example.com` and
+ * `https://example.com/` are one URL). A deny or ask also reads it after the
+ * origin's other spellings (no root dot, no port, the other of http and
+ * https) and after the host alone (`ghe.example.com/api/v3`), as for a value
+ * on a service, as written, and with each run of slashes read as one, as
+ * many servers read a path: the tool reaches `…/api/v3//` as
+ * `…/api/v3//rate_limit`, which an allow on `…/api/v3` does not grant and a
+ * deny on it stops. A URL that cannot be placed, or that the tool refuses as
+ * a root because it carries a query or a fragment, leaves nothing an allow
+ * could grant, and every deny or ask fires.
+ */
+function apiRootValue(service) {
+    const { origin } = service;
+    const root = origin !== undefined ? joinedApiRoot(service.url, origin) : undefined;
+    if (origin === undefined || root === undefined) {
+        return {
+            kind: "url",
+            canonical: [],
+            spellings: service.url !== "" ? [service.url] : [],
+            outsideWorkspace: true,
+        };
+    }
+    const at = (path) => (o) => path === "" ? [`${o}/`, o] : [`${o}${path}`, `${o}${path}/`];
+    const others = [...service.otherOrigins, ...service.hosts];
+    const folded = root.replace(/\/{2,}/g, "/").replace(/\/$/, "");
+    return {
+        kind: "url",
+        canonical: at(root)(origin),
+        spellings: [
+            ...new Set([
+                service.url,
+                ...others.flatMap(at(root)),
+                ...(folded !== root ? [origin, ...others].flatMap(at(folded)) : []),
+            ]),
+        ],
+    };
+}
+/**
+ * The path of the API root at `raw` as a tool that drops one trailing slash
+ * and appends its request paths as text reaches it, without its last `/`:
+ * `/api/v3` for `https://h/api/v3/.`, `""` for the origin's own root.
+ * Undefined when a path appended to it would land in a query or a fragment,
+ * or on another origin.
+ */
+function joinedApiRoot(raw, origin) {
+    const text = raw.endsWith("/") ? raw.slice(0, -1) : raw;
+    let url;
+    try {
+        url = new URL(`${text}/`);
+    }
+    catch {
+        return undefined;
+    }
+    const { pathname } = url;
+    if (url.origin !== origin || url.search !== "" || url.hash !== "" || !pathname.endsWith("/")) {
+        return undefined;
+    }
+    return pathname.slice(0, -1);
+}
+function readValues(input, arg) {
+    const segments = arg.field.split(".");
+    const out = [];
+    const topQualifier = arg.within !== undefined ? qualifierOf(input, arg.within) : undefined;
+    // A command runs in its own object's directory field (a pipeline step's
+    // `cwd`), else the top-level one.
+    const runsInOf = (owner) => {
+        if (arg.kind !== "command" || arg.within === undefined)
+            return {};
+        const dir = qualifierOf(owner, arg.within) ?? topQualifier;
+        return dir !== undefined ? { runsIn: dir } : {};
+    };
+    // And with its own object's environment field, else the top-level one.
+    const topEnv = arg.env !== undefined ? envMapOf(input, arg.env) : undefined;
+    const envOf = (owner) => {
+        if (arg.kind !== "command" || arg.env === undefined)
+            return {};
+        const env = envMapOf(owner, arg.env) ?? topEnv;
+        return env !== undefined ? { env } : {};
+    };
+    // And with its own object's input text, else the top-level one.
+    const topStdin = arg.stdin !== undefined ? qualifierOf(input, arg.stdin) : undefined;
+    const stdinOf = (owner) => {
+        if (arg.kind !== "command" || arg.stdin === undefined)
+            return {};
+        const text = (owner !== input ? qualifierOf(owner, arg.stdin) : undefined) ?? topStdin;
+        return text !== undefined ? { stdin: text } : {};
+    };
+    const placed = (owner) => ({ ...runsInOf(owner), ...envOf(owner), ...stdinOf(owner) });
+    const walk = (value, i, depth, owner) => {
+        if (depth > 64)
+            return;
+        if (Array.isArray(value)) {
+            if (i === segments.length &&
+                arg.kind === "command" &&
+                value.length > 0 &&
+                value.every((v) => typeof v === "string")) {
+                out.push({ value: value.join(" "), words: value, ...placed(owner) });
+                return;
+            }
+            for (const element of value)
+                walk(element, i, depth + 1, owner);
+            return;
+        }
+        if (i === segments.length) {
+            if (typeof value === "string")
+                out.push({ value, ...placed(owner) });
+            else if (arg.kind === "id" && typeof value === "number" && Number.isFinite(value)) {
+                out.push({ value: String(value) });
+            }
+            return;
+        }
+        if (value === null || typeof value !== "object")
+            return;
+        const key = segments[i];
+        if (!Object.hasOwn(value, key))
+            return;
+        walk(value[key], i + 1, depth + 1, value);
+    };
+    walk(input, 0, 0, input);
+    if (arg.prefix === true && arg.kind !== "path" && arg.kind !== "url" && arg.kind !== "command") {
+        return prefixReadings(out, arg, topQualifier);
+    }
+    // A default of `*` is "every value": EvmGetLogs without an `address`
+    // reads every contract's logs.
+    const every = out.length === 0 && arg.default === ANY_VALUE;
+    if (out.length === 0 && arg.default !== undefined) {
+        out.push({ value: arg.default, ...placed(input), defaulted: true });
+    }
+    const anyValue = (rs) => every ? rs.map((r) => ({ ...r, every: true, anyAfter: [""] })) : rs;
+    // A command's `within` is where it runs, carried as `runsIn` above.
+    if (arg.kind === "command")
+        return anyValue(out);
+    // A path whose directory the call left out is relative to the one the
+    // tool uses then, when it declares one (TempDir's `.tmp`).
+    const qualifier = topQualifier ?? (arg.kind === "path" ? arg.withinDefault : undefined);
+    if (qualifier === undefined) {
+        // A path within a directory the call left out is relative to the root,
+        // and handed on as written all the same.
+        if (arg.kind === "path" && arg.within !== undefined && !every) {
+            return out.map((r) => leavesItsDirectory(r.value) ? { ...r, leavesDir: { written: r.value } } : r);
+        }
+        // The qualifier is left out as well: a code search with no owner reaches
+        // every repository, so the value stands for every `<owner>/<repo>` too.
+        const read = anyValue(out);
+        return every && arg.within !== undefined
+            ? read.map((r) => ({ ...r, anyQualifier: true }))
+            : read;
+    }
+    return out.map((r) => {
+        // A path relative to a directory field.
+        if (arg.kind === "path") {
+            if (every)
+                return { ...r, value: `${qualifier}/${r.value}`, dir: qualifier, every: true };
+            // A git command given no path acts on the whole repository, wherever
+            // it runs: its default is the workspace root, not the directory.
+            if (r.defaulted === true && arg.defaultAtRoot === true)
+                return r;
+            // One that leaves it is still shown joined to it — an approver needs to
+            // see what `..` climbs from — but not read that way (`leavingValue`).
+            if (leavesItsDirectory(r.value)) {
+                const value = isAbsolutePath(r.value) ? r.value : `${qualifier}/${r.value}`;
+                return { ...r, value, leavesDir: { written: r.value } };
+            }
+            return { ...r, value: `${qualifier}/${r.value}` };
+        }
+        return {
+            ...r,
+            value: `${qualifier}/${r.value}`,
+            unqualified: [r.value, qualifier],
+            ...(every ? { every: true, anyAfter: [`${qualifier}/`, ""] } : {}),
+        };
+    });
+}
+/** The declared default that stands for every value of its field. */
+const ANY_VALUE = "*";
+/**
+ * The readings of a field declared `prefix` (KvList's `prefix`): each value
+ * `p` stands for every value that starts with it, and one left out is the
+ * empty prefix — every value. Qualified, `<qualifier>/<p>` is followed by any
+ * run (a key may hold `/`), and `<p>` alone is kept for a deny written
+ * without the qualifier. With the qualifier left out too, the value stands
+ * for every `<qualifier>/<value>` there is: an allow must name every value.
+ */
+function prefixReadings(out, arg, qualifier) {
+    const prefixes = out.length > 0 ? out.map((r) => r.value) : [""];
+    return prefixes.map((p) => {
+        if (qualifier === undefined) {
+            const anyQualifier = arg.within !== undefined;
+            const start = anyQualifier ? "" : p;
+            return {
+                value: `${start}${ANY_VALUE}`,
+                every: true,
+                anyAfter: [start],
+                prefixOf: {},
+                ...(out.length === 0 ? { defaulted: true } : {}),
+            };
+        }
+        return {
+            value: `${qualifier}/${p}${ANY_VALUE}`,
+            unqualified: [`${p}${ANY_VALUE}`, qualifier],
+            every: true,
+            anyAfter: [`${qualifier}/${p}`],
+            prefixOf: { unqualified: p },
+            ...(out.length === 0 ? { defaulted: true } : {}),
+        };
+    });
+}
+/**
+ * Every path under `dir` — a path field left out whose default is `*` — as
+ * the values a rule reads: for each place `dir` resolves to, its spellings
+ * as prefixes (`sub/`, `./sub/`, `/abs/ws/sub/`; the workspace root is the
+ * empty prefix and `./`) and `<prefix>*` as the canonical spelling an allow
+ * must cover whole. A directory outside the workspace stays outside: every
+ * deny or ask fires on it, and no allow does.
+ */
+function everyPathValues(dir, canonicalizePath) {
+    const under = (p) => (p === "." ? "" : p.endsWith("/") ? p : `${p}/`);
+    return canonicalizePath(dir).map((v) => {
+        if (v.outsideWorkspace === true)
+            return v;
+        return {
+            kind: "path",
+            canonical: v.canonical.map((c) => `${under(c)}${ANY_VALUE}`),
+            standsForAny: underPrefixes([...v.canonical, ...(v.spellings ?? [])]),
+            ...(v.caseInsensitive === true ? { caseInsensitive: true } : {}),
+        };
+    });
+}
+/**
+ * Does a path declared `within` a directory leave it: is it absolute, or does
+ * it have a `..` segment? Where such a path lands cannot be read off the
+ * directory's values.
+ *
+ * - The tool hands the path on as written, to a program that runs in the
+ *   directory (git, a formatter, a test runner), and the OS follows each
+ *   symlink BEFORE it applies the `..` after it. Through a symlinked
+ *   directory (`cwd: "link"`, `link → secrets/deep`), `../x.ts` is
+ *   `secrets/x.ts`; through a link inside the path itself (`lnk/../x.ts`),
+ *   it climbs out of the link's target, which no join of the path to the
+ *   directory can see without a filesystem to ask. Read like every other
+ *   path, with `..` collapsed first, both were `x.ts`.
+ * - An absolute path ignores the directory for a program that resolves it,
+ *   but not for `path.join`, which a tool may check it with: the two name
+ *   different files.
+ *
+ * `\` counts as a separator too, as in tool-git's pathspec check: splitting
+ * at it can only flag more.
+ */
+function leavesItsDirectory(value) {
+    return isAbsolutePath(value) || value.split(/[\\/]/).includes("..");
+}
+/**
+ * The value of a path that leaves its directory ({@link leavesItsDirectory}):
+ * outside the workspace, so no allow rule names it and every deny or ask fires
+ * on it. Every builtin that declares such a field refuses the path itself;
+ * this keeps a rule about another place from granting it to a tool that does
+ * not. The spellings are the path as written, and joined to the directory as
+ * written (`joined`, the reading's value; the same string when the call gave
+ * no directory or the path is absolute).
+ */
+function leavingValue(joined, written) {
+    const spellings = joined === written ? [written] : [written, joined];
+    return { kind: "path", canonical: [], spellings, outsideWorkspace: true };
+}
+/**
+ * A path the tool walks when it names a directory (`beneath` on its
+ * OperativeArg): each of its spellings as a prefix a deny or ask reads with
+ * anything after it. A path the canonicaliser found to be an existing
+ * non-directory stands for itself alone, and one outside the workspace
+ * already fires every deny.
+ */
+function withBeneath(value, mode) {
+    if (value.outsideWorkspace === true || value.notDirectory === true)
+        return value;
+    return {
+        ...value,
+        beneath: underPrefixes([...value.canonical, ...(value.spellings ?? [])]),
+        ...(mode === "visible" ? { beneathSkipsHidden: true } : {}),
+    };
+}
+/**
+ * The prefixes what lies under each of these directory spellings starts
+ * with. The root — `.`, or the empty path a call may write for it — is the
+ * empty prefix, never `/`, which would read as the filesystem root. A
+ * relative prefix is also given its `./` spelling, as a direct path value
+ * carries one (`secrets/x` is also `./secrets/x`): without it a deny written
+ * `./secrets/**` fired on `Tree ./` but not on `Tree .`, `Tree {}` or
+ * `Tree src/..`, which walk the same place.
+ */
+function underPrefixes(spellings) {
+    const out = new Set();
+    for (const p of spellings) {
+        const under = p === "." || p === "" ? "" : p.endsWith("/") ? p : `${p}/`;
+        out.add(under);
+        if (!isAbsolutePath(under) && !under.startsWith("./"))
+            out.add(`./${under}`);
+    }
+    return [...out];
+}
+/**
+ * The fixed places a tool opens inside the directory a `path` names (`opens`
+ * on its OperativeArg — ApprovalStatus's ledger, PermissionsSuggest's
+ * session logs), as values only a deny or ask reads: each joined to the
+ * directory as the call wrote it and canonicalised like any path, so a link
+ * or a `..` on the way is followed, and read with what is beneath it when the
+ * tool reads it whole. An allow reads the directory alone.
+ */
+function openedValues(dir, arg, canonicalizePath) {
+    const out = [];
+    for (const opening of arg.opens ?? []) {
+        for (const v of canonicalizePath(joinBelow(dir, opening.path))) {
+            const read = opening.beneath !== undefined ? withBeneath(v, opening.beneath) : v;
+            out.push({ ...read, restrictOnly: true });
+        }
+    }
+    return out;
+}
+/** `rel` inside `dir`: the root (`.`, `./`, the empty path) adds nothing in front. */
+function joinBelow(dir, rel) {
+    const trimmed = withoutTrailingSeparators(dir);
+    if (trimmed === "")
+        return dir === "" ? rel : `/${rel}`;
+    return trimmed === "." ? rel : `${trimmed}/${rel}`;
+}
+/**
+ * The most variables, words in one value, and characters in one value, of an
+ * environment a command's call sets that a deny or ask reads one by one. A
+ * call past any of them is flagged `outsideWorkspace` instead: which program
+ * it runs could not be worked out, so every deny or ask fires on it.
+ */
+export const MAX_ENV_VARS = 64;
+export const MAX_ENV_WORDS = 64;
+export const MAX_ENV_VALUE_CHARS = 8192;
+/**
+ * The workspace-relative spellings of the directory a command runs in, and
+ * the one the call wrote, without trailing slashes: `scripts/` and
+ * `./scripts` as written, `scripts` as canonicalised, `lnk` for a symlink
+ * the canonicaliser followed to `scripts`. The canonicaliser's absolute
+ * spellings of the workspace root are left out — the call named none of
+ * them, and joining them put every word the workspace's own path holds
+ * (`prod-agent/…`, `/private/var/…`) in front of every command run in a
+ * subdirectory. Its `./sub` spellings are left out too: a word the call did
+ * not write with `./` is not read with one, so `RunCommand(./**)` does not
+ * fire on `git status` run in `sub/`.
+ */
+function runDirSpellings(runsIn, dirValues) {
+    const out = new Set();
+    const add = (d) => {
+        const trimmed = withoutTrailingSeparators(d);
+        if (trimmed !== "" && trimmed !== ".")
+            out.add(trimmed);
+    };
+    add(runsIn);
+    for (const v of dirValues) {
+        for (const d of [...v.canonical, ...(v.spellings ?? [])]) {
+            if (isAbsolutePath(d) || d.startsWith("./") || d === ".")
+                continue;
+            add(d);
+        }
+    }
+    return [...out];
+}
+/**
+ * `text` without its trailing `/` and `\`: what `text.replace(/[\\/]+$/, "")`
+ * returned, in one pass from the end. That pattern tries every start inside
+ * a run of separators that is not at the end and rescans the rest of the run
+ * from each, so it was quadratic in the run's length, and a directory or a
+ * PATH entry is whatever the call wrote.
+ */
+export function withoutTrailingSeparators(text) {
+    let end = text.length;
+    for (; end > 0; end--) {
+        const c = text.charCodeAt(end - 1);
+        if (c !== 0x2f && c !== 0x5c)
+            break;
+    }
+    return end === text.length ? text : text.slice(0, end);
+}
+/**
+ * `dir/word`, as written and with `.`, `..` and doubled `/` collapsed. A join
+ * that climbs out of the directory it starts in is kept only as written: its
+ * collapsed form would drop the climb.
+ */
+function joinedSpellings(dir, word) {
+    const written = `${dir}/${word}`;
+    const lexical = normalizePathLexically(written);
+    return lexical.escapes || lexical.path === written ? [written] : [written, lexical.path];
+}
+/**
+ * A word with separators, collapsed the way {@link joinedSpellings} does,
+ * when that changes it — and again with the `./` the call wrote kept, so
+ * `alwaysDeny RunCommand(./deploy.sh)` reads `./a/../deploy.sh` as well.
+ */
+function collapsedWords(word) {
+    if (!/[\\/]/.test(word))
+        return [];
+    const lexical = normalizePathLexically(word);
+    if (lexical.escapes || lexical.path === word || lexical.path === ".")
+        return [];
+    const dotted = startsWithDotSlash(word) ? `./${lexical.path}` : undefined;
+    return dotted !== undefined && dotted !== word ? [lexical.path, dotted] : [lexical.path];
+}
+/**
+ * A command word with its `.` and `..` folded as text, as `path.resolve`
+ * folds them before anything is opened — the way node and `bun run` read
+ * the script they are handed, and a `#!/usr/bin/env node` script the path it
+ * was run by. A `..` after a name takes the name off; one at the start of a
+ * relative word stays, climbing from the directory the command runs in; one
+ * at the root of an absolute word stays at the root. A relative result
+ * without a `/` keeps a `./`, so it still names a file in that directory,
+ * not a program to look up.
+ */
+export function foldedAsText(word) {
+    const drive = /^[A-Za-z]:[\\/]/.test(word) ? word.slice(0, 2) : "";
+    const absolute = drive !== "" || word.startsWith("/") || word.startsWith("\\");
+    const names = [];
+    for (const segment of word.slice(drive.length).split(/[\\/]/)) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment !== "..")
+            names.push(segment);
+        else if (names.length > 0 && names[names.length - 1] !== "..")
+            names.pop();
+        else if (!absolute)
+            names.push("..");
+    }
+    const joined = names.join("/");
+    if (absolute)
+        return `${drive}/${joined}`;
+    if (joined === "")
+        return ".";
+    return joined.includes("/") || joined === ".." ? joined : `./${joined}`;
+}
+/**
+ * The spellings a deny or ask reads for one command beyond the words as
+ * written. Every spelling only widens what a deny or ask catches; none is
+ * canonical, so no allow reads them.
+ *
+ * - Each word that names a file through `.`, `..` or a doubled `/`, with
+ *   them collapsed, and the command line with those words collapsed.
+ * - For a command run in a directory other than the root (`dirs`, its
+ *   relative spellings): each word that may name a file joined to the
+ *   directory — except a bare program name, which PATH finds, not the
+ *   directory — and the command line with those words joined, once per
+ *   directory. So `scripts/**` fires on `sh x` run in `scripts/`. The
+ *   directory on its own is not a spelling: `alwaysDeny RunCommand(rm*)` must
+ *   not fire on `ls` run in `rmtemp/`.
+ * - For a call that sets its child's environment (`env`): a bare program as
+ *   PATH finds it on each entry the call sets — a relative entry is looked
+ *   up from the workspace root and run from the child's directory (Bun's
+ *   spawn does both), so both are read, and an absolute entry inside the
+ *   workspace is read from the root — and every value the call sets, each of
+ *   its words that may name a file (split at spaces, `:`, `=` and `;`, so
+ *   `--require=./hook.js` and `a:b` are read) as written, collapsed, and
+ *   joined to the child's directory.
+ */
+function commandSpellings(argv, dirs, env, canonicalizePath, where) {
+    const out = new Set();
+    const program = argv[0] ?? "";
+    const bareProgram = program !== "" && !/[\\/]/.test(program);
+    // Words collapsed where the call wrote a separator: once as collapsed, and
+    // once with the `./` the call wrote kept.
+    const collapsed = argv.map((w) => (namesAFile(w) ? collapsedWords(w) : []));
+    if (collapsed.some((c) => c.length > 0)) {
+        for (const c of collapsed)
+            for (const form of c)
+                out.add(form);
+        for (const k of [0, 1]) {
+            out.add(argv.map((w, i) => collapsed[i]?.[k] ?? collapsed[i]?.[0] ?? w).join(" "));
+        }
+    }
+    // Words joined to the directory the command runs in.
+    for (const d of dirs) {
+        const line = argv.map((w, i) => {
+            if ((i === 0 && bareProgram) || !namesAFile(w))
+                return w;
+            const joined = joinedSpellings(d, w);
+            for (const j of joined)
+                out.add(j);
+            return joined[joined.length - 1];
+        });
+        out.add(line.join(" "));
+    }
+    if (env === undefined)
+        return { spellings: [...out], unreadable: false };
+    const entries = Object.entries(env);
+    let unreadable = entries.length > MAX_ENV_VARS;
+    // Where a relative path in a value resolves: the child's directory.
+    const places = dirs.length > 0 ? dirs : ["."];
+    for (const [name, value] of entries.slice(0, MAX_ENV_VARS)) {
+        if (value.length > MAX_ENV_VALUE_CHARS) {
+            unreadable = true;
+            continue;
+        }
+        if (value !== "")
+            out.add(value);
+        const words = value.split(/[\s:=;]+/).filter((w) => w !== "");
+        if (words.length > MAX_ENV_WORDS)
+            unreadable = true;
+        for (const w of words.slice(0, MAX_ENV_WORDS)) {
+            if (!namesAFile(w))
+                continue;
+            out.add(w);
+            for (const c of collapsedWords(w))
+                out.add(c);
+            for (const d of dirs)
+                for (const j of joinedSpellings(d, w))
+                    out.add(j);
+        }
+        if (name.toUpperCase() !== "PATH" || !bareProgram)
+            continue;
+        const pathEntries = value.split(":");
+        if (pathEntries.length > MAX_ENV_WORDS)
+            unreadable = true;
+        for (const raw of pathEntries.slice(0, MAX_ENV_WORDS)) {
+            const entry = raw === "" ? "." : withoutTrailingSeparators(raw) || "/";
+            const found = new Set();
+            if (isAbsolutePath(entry)) {
+                found.add(`${entry === "/" ? "" : entry}/${program}`);
+                for (const v of canonicalizePath(entry)) {
+                    if (v.outsideWorkspace === true)
+                        continue;
+                    for (const c of [...v.canonical, ...(v.spellings ?? [])]) {
+                        if (isAbsolutePath(c) || c.startsWith("./"))
+                            continue;
+                        found.add(c === "." ? program : `${c}/${program}`);
+                    }
+                }
+            }
+            else {
+                for (const j of joinedSpellings(entry, program))
+                    found.add(j);
+                for (const d of places) {
+                    for (const j of joinedSpellings(d === "." ? entry : `${d}/${entry}`, program))
+                        found.add(j);
+                }
+            }
+            // And where the kernel finds it there, each link followed before the
+            // `..` after it: `PATH=link/..` is the directory above link's target.
+            // A script found there whose `#!` line names node is opened again by
+            // node, with the `..` folded as text: read there too.
+            if (where.readProgramPath !== undefined) {
+                const candidate = `${entry === "/" ? "" : entry}/${program}`;
+                const from = isAbsolutePath(entry) ? [undefined] : [undefined, where.runsIn];
+                const asRead = climbsAfterName(candidate)
+                    ? [candidate, foldedAsText(candidate)]
+                    : [candidate];
+                for (const runsIn of new Set(from)) {
+                    for (const word of asRead) {
+                        const place = where.readProgramPath(word, runsIn);
+                        if (place === undefined)
+                            continue;
+                        for (const f of placeForms(place.at, place.inWorkspace, candidate, true))
+                            found.add(f);
+                        if (place.target === undefined)
+                            continue;
+                        const { at, inWorkspace } = place.target;
+                        for (const f of placeForms(at, inWorkspace, candidate, true))
+                            found.add(f);
+                    }
+                }
+            }
+            for (const f of found) {
+                out.add(f);
+                out.add([f, ...argv.slice(1)].join(" "));
+            }
+        }
+    }
+    return { spellings: [...out], unreadable };
+}
+/** The string-valued entries of the object at `field`, when the call carries one. */
+function envMapOf(input, field) {
+    if (input === null || typeof input !== "object" || !Object.hasOwn(input, field)) {
+        return undefined;
+    }
+    const value = input[field];
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return undefined;
+    const out = {};
+    for (const [name, v] of Object.entries(value))
+        if (typeof v === "string")
+            out[name] = v;
+    return out;
+}
+/**
+ * Could this argv word name a file relative to the working directory? Not a
+ * flag, not an absolute path, not a URL; anything else might be a program
+ * or a script (`release.sh`, `./eslint`, `bin/tool`).
+ */
+function namesAFile(word) {
+    return word !== "" && !word.startsWith("-") && !isAbsolutePath(word) && !word.includes("://");
+}
+function isAbsolutePath(value) {
+    return value.startsWith("/") || value.startsWith("\\") || /^[A-Za-z]:[\\/]/.test(value);
+}
+/** Does the call set the top-level boolean `field` to `true`? */
+function switchedOn(input, field) {
+    return (input !== null &&
+        typeof input === "object" &&
+        Object.hasOwn(input, field) &&
+        input[field] === true);
+}
+/** The top-level `within` field's value, when the call carries one. */
+function qualifierOf(input, field) {
+    if (input === null || typeof input !== "object" || !Object.hasOwn(input, field)) {
+        return undefined;
+    }
+    const value = input[field];
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" && Number.isFinite(value))
+        return String(value);
+    return undefined;
+}
+/**
+ * The filesystem-free reading of a path: `..` and `.` collapsed, nothing
+ * followed. A relative path that climbs above its start is flagged as
+ * outside. Used where there is no workspace to ask (the edge worker); the
+ * Node runtime passes a canonicaliser that also follows symlinks.
+ */
+export function lexicalPathValues(raw) {
+    const lexical = normalizePathLexically(raw);
+    if (lexical.escapes) {
+        return [
+            { kind: "path", canonical: [], spellings: [raw, lexical.path], outsideWorkspace: true },
+        ];
+    }
+    const p = lexical.path;
+    const canonical = p.startsWith("/") || p === "." ? [p] : [p, `./${p}`];
+    return [{ kind: "path", canonical, spellings: [raw] }];
+}
+function canonicalUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        // Not a URL the tool could fetch. Nothing canonical to grant against; a
+        // deny still reads what was written.
+        return { kind: "url", canonical: [], spellings: [raw] };
+    }
+    const href = url.href;
+    const canonical = [href];
+    // `https://example.com` parses to `https://example.com/`. Both spell the
+    // same request, so a rule written either way matches.
+    if (url.pathname === "/" && url.search === "" && url.hash === "" && href.endsWith("/")) {
+        canonical.push(href.slice(0, -1));
+    }
+    return { kind: "url", canonical, spellings: [raw] };
+}