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

package/dist/core/runStats.d.ts

@@ -10,7 +10,14 @@
  * message chunks / `ToolMessage`s as they arrive), across providers whose message shapes vary.
  * Nothing here may throw into a run — a missing/odd field just means that datum is skipped.
  */
-import type { GthRunStats } from '#src/core/types.js';
+import type { GthRunStats, GthToolResult } from '#src/core/types.js';
+/**
+ * BATCH-21 — cap on a captured tool-result `content` (characters). Keeps a giant payload (a whole
+ * file read, a long shell log) from bloating run stats; anything longer is truncated to this
+ * length. Sized so realistic structured payloads (the `gth eval` tool-result-assertion use case)
+ * survive intact.
+ */
+export declare const TOOL_RESULT_CONTENT_CAP = 8192;
 /** Mutable tally behind {@link finalizeRunStats}; see {@link createRunStatsAccumulator}. */
 export interface RunStatsAccumulator {
     /** Running sum of input/prompt tokens. */
@@ -21,15 +28,19 @@ export interface RunStatsAccumulator {
     sawUsage: boolean;
     /** Deduplicated set of invoked tool names. */
     tools: Set<string>;
+    /** BATCH-21 — one record per executed tool result (`ToolMessage`), in arrival order, un-deduped. */
+    toolResults: GthToolResult[];
 }
 /** A fresh, empty accumulator. */
 export declare function createRunStatsAccumulator(): RunStatsAccumulator;
 /**
  * Fold one LangChain message (or message chunk) into the accumulator. Fail-soft: any unexpected
  * shape is swallowed so a run is never affected. Harvests, when present:
- * - `usage_metadata.input_tokens` / `.output_tokens` (summed; marks `sawUsage`), and
+ * - `usage_metadata.input_tokens` / `.output_tokens` (summed; marks `sawUsage`),
  * - tool names from an AIMessage's requested `tool_calls[].name` AND from a `ToolMessage`'s own
- *   `.name` (the executed tool), so both "requested" and "executed" tools are captured.
+ *   `.name` (the executed tool), so both "requested" and "executed" tools are captured, and
+ * - (BATCH-21) a per-`ToolMessage` result record — `name` + `isError` (from `.status`) + capped
+ *   `content` — into `acc.toolResults`, so tool-RESULT assertions can grade what a tool returned.
  */
 export declare function accumulateMessage(acc: RunStatsAccumulator, message: unknown): void;
 /** Freeze the accumulator into the public {@link GthRunStats}. Tokens omitted unless observed. */

package/dist/core/runStats.js

@@ -1,13 +1,47 @@
+/**
+ * BATCH-21 — cap on a captured tool-result `content` (characters). Keeps a giant payload (a whole
+ * file read, a long shell log) from bloating run stats; anything longer is truncated to this
+ * length. Sized so realistic structured payloads (the `gth eval` tool-result-assertion use case)
+ * survive intact.
+ */
+export const TOOL_RESULT_CONTENT_CAP = 8192;
 /** A fresh, empty accumulator. */
 export function createRunStatsAccumulator() {
-    return { input: 0, output: 0, sawUsage: false, tools: new Set() };
+    return { input: 0, output: 0, sawUsage: false, tools: new Set(), toolResults: [] };
+}
+/**
+ * BATCH-21 — derive a tool result's text payload from a `ToolMessage.content`, fail-soft. A string
+ * passes through; anything else non-`undefined` is JSON-stringified (the same derivation the
+ * `tool_result` stream event uses in `GthAbstractAgent`); the result is capped at
+ * {@link TOOL_RESULT_CONTENT_CAP}. Returns `undefined` (payload omitted) when nothing textual can
+ * be derived — never throws.
+ */
+function toolResultContentText(content) {
+    try {
+        let text;
+        if (typeof content === 'string') {
+            text = content;
+        }
+        else if (content !== undefined) {
+            text = JSON.stringify(content);
+        }
+        if (text === undefined)
+            return undefined;
+        return text.length > TOOL_RESULT_CONTENT_CAP ? text.slice(0, TOOL_RESULT_CONTENT_CAP) : text;
+    }
+    catch {
+        /* fail-soft: an unstringifiable payload just means no content is recorded */
+        return undefined;
+    }
 }
 /**
  * Fold one LangChain message (or message chunk) into the accumulator. Fail-soft: any unexpected
  * shape is swallowed so a run is never affected. Harvests, when present:
- * - `usage_metadata.input_tokens` / `.output_tokens` (summed; marks `sawUsage`), and
+ * - `usage_metadata.input_tokens` / `.output_tokens` (summed; marks `sawUsage`),
  * - tool names from an AIMessage's requested `tool_calls[].name` AND from a `ToolMessage`'s own
- *   `.name` (the executed tool), so both "requested" and "executed" tools are captured.
+ *   `.name` (the executed tool), so both "requested" and "executed" tools are captured, and
+ * - (BATCH-21) a per-`ToolMessage` result record — `name` + `isError` (from `.status`) + capped
+ *   `content` — into `acc.toolResults`, so tool-RESULT assertions can grade what a tool returned.
  */
 export function accumulateMessage(acc, message) {
     try {
@@ -39,6 +73,16 @@ export function accumulateMessage(acc, message) {
         const type = typeof m.getType === 'function' ? m.getType() : m._getType?.();
         if (type === 'tool' && typeof m.name === 'string' && m.name.length > 0) {
             acc.tools.add(m.name);
+            // BATCH-21 — capture the RESULT record too (same capture site, same fail-soft discipline):
+            // `.status === 'error'` is LangChain's real tool-error signal, `.content` the returned
+            // payload (capped; omitted when no text can be derived). One record per ToolMessage, in
+            // arrival order — deliberately NOT deduplicated, unlike the name set above.
+            const content = toolResultContentText(m.content);
+            acc.toolResults.push({
+                name: m.name,
+                isError: m.status === 'error',
+                ...(content !== undefined ? { content } : {}),
+            });
         }
     }
     catch {
@@ -51,6 +95,7 @@ export function finalizeRunStats(acc) {
         tokensInput: acc.sawUsage ? acc.input : undefined,
         tokensOutput: acc.sawUsage ? acc.output : undefined,
         tools: [...acc.tools],
+        toolResults: [...acc.toolResults],
     };
 }
 /**

package/dist/core/runStats.js.map

@@ -1 +1 @@
-{"version":3,"file":"runStats.js","sourceRoot":"","sources":["../../src/core/runStats.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runStats.js","sourceRoot":"","sources":["../../src/core/runStats.ts"],"names":[],"mappings":"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"}

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

@@ -6,10 +6,9 @@
  * body so a softening middleware can hand the model the exact observation it saw before — the
  * only change being that the tool result's status flips to `'error'` (→ `isError` → the ✗ glyph).
  *
- * Canonical home is **core** so BOTH agents can recognise a shell failure without violating the
- * `agent → core` dependency direction:
- *  - the deep agent (`code` mode, `@gaunt-sloth/agent` `GthDeepShellExitSoftening`) and
- *  - the lean agent (`exec` / `ask --write`, core `GthLangChainAgent` `GthLeanShellExitSoftening`).
+ * Canonical home is **core** so any agent can recognise a shell failure without violating the
+ * `agent → core` dependency direction — today the lean agent (`exec` / `ask --write`, core
+ * `GthLangChainAgent` `GthLeanShellExitSoftening`).
  *
  * The throw site (`GthDevToolkit.executeCommand`) lives in the `agent` package and re-exports this
  * class, so its `throw new ShellCommandFailedError(...)` is one and the same type both agents catch.

package/dist/core/shell/ShellCommandFailedError.js

@@ -6,10 +6,9 @@
  * body so a softening middleware can hand the model the exact observation it saw before — the
  * only change being that the tool result's status flips to `'error'` (→ `isError` → the ✗ glyph).
  *
- * Canonical home is **core** so BOTH agents can recognise a shell failure without violating the
- * `agent → core` dependency direction:
- *  - the deep agent (`code` mode, `@gaunt-sloth/agent` `GthDeepShellExitSoftening`) and
- *  - the lean agent (`exec` / `ask --write`, core `GthLangChainAgent` `GthLeanShellExitSoftening`).
+ * Canonical home is **core** so any agent can recognise a shell failure without violating the
+ * `agent → core` dependency direction — today the lean agent (`exec` / `ask --write`, core
+ * `GthLangChainAgent` `GthLeanShellExitSoftening`).
  *
  * The throw site (`GthDevToolkit.executeCommand`) lives in the `agent` package and re-exports this
  * class, so its `throw new ShellCommandFailedError(...)` is one and the same type both agents catch.

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

@@ -1 +1 @@
-{"version":3,"file":"ShellCommandFailedError.js","sourceRoot":"","sources":["../../../src/core/shell/ShellCommandFailedError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,iGAAiG;IACxF,MAAM,CAAS;IACxB,oGAAoG;IAC3F,QAAQ,CAAgB;IACjC,kDAAkD;IACzC,OAAO,CAAS;IACzB,4FAA4F;IACnF,QAAQ,CAAS;IAE1B,YAAY,MAKX;QACC,0FAA0F;QAC1F,4DAA4D;QAC5D,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,CAAU;IAClD,IAAI,CAAC,YAAY,uBAAuB;QAAE,OAAO,IAAI,CAAC;IACtD,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAwB,CAAC,IAAI,KAAK,yBAAyB;QAC5D,OAAQ,CAA0B,CAAC,MAAM,KAAK,QAAQ;QACtD,OAAQ,CAA2B,CAAC,OAAO,KAAK,QAAQ;QACxD,OAAQ,CAA4B,CAAC,QAAQ,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC"}
+{"version":3,"file":"ShellCommandFailedError.js","sourceRoot":"","sources":["../../../src/core/shell/ShellCommandFailedError.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;;GAUG;AACH,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IAChD,iGAAiG;IACxF,MAAM,CAAS;IACxB,oGAAoG;IAC3F,QAAQ,CAAgB;IACjC,kDAAkD;IACzC,OAAO,CAAS;IACzB,4FAA4F;IACnF,QAAQ,CAAS;IAE1B,YAAY,MAKX;QACC,0FAA0F;QAC1F,4DAA4D;QAC5D,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;QAChC,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;QAC9B,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAC;IAClC,CAAC;CACF;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,yBAAyB,CAAC,CAAU;IAClD,IAAI,CAAC,YAAY,uBAAuB;QAAE,OAAO,IAAI,CAAC;IACtD,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACT,CAAwB,CAAC,IAAI,KAAK,yBAAyB;QAC5D,OAAQ,CAA0B,CAAC,MAAM,KAAK,QAAQ;QACtD,OAAQ,CAA2B,CAAC,OAAO,KAAK,QAAQ;QACxD,OAAQ,CAA4B,CAAC,QAAQ,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC"}

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

@@ -0,0 +1,88 @@
+/**
+ * The shape in the command that the gate's parser could not resolve.
+ *
+ * These are FORMS, not judgements — nothing here says a command is dangerous, and nothing here is a
+ * rating. They exist to select the sentence the rater is shown.
+ */
+export type AbstentionMechanism = 
+/** A git commit whose message contains a substitution the SHELL runs before git sees it. */
+'commit-message-substitution'
+/** More than one command: `;`, `&`, `&&`, `|`, `||`, or a line break. */
+ | 'composition'
+/** Command / variable / process substitution: `$(…)`, backticks, `${…}`, `<(…)`. */
+ | 'substitution'
+/** A stream redirect: `>`, `>>`, `<`, `2>`, `&>`. */
+ | 'redirect'
+/** None of the above — an unbalanced quote, an empty command, or no resolvable program name. */
+ | 'unparseable';
+/** What the parser saw in a command it could not resolve: the shapes, and the note for each. */
+export interface AbstentionDefect {
+    /** The most specific mechanism found — what the note leads with. */
+    mechanism: AbstentionMechanism;
+    /** Every mechanism found, in note order. A command may carry more than one. */
+    mechanisms: AbstentionMechanism[];
+    /** One note per mechanism, in the same order. Never empty. */
+    notes: string[];
+}
+/**
+ * **The per-family note text — one distinct string per {@link AbstentionMechanism}.**
+ *
+ * Typed as a total `Record`, so adding a mechanism is a COMPILE ERROR until someone writes its
+ * sentence. A family that silently fell back to another family's note would be the failure this
+ * table exists to prevent: [[QA-17]] measured that the note's effect is family-specific, and
+ * `docs/test-sessions/qa-17-substitution-note-2026-08-03/` records a narrowing by family name that
+ * was FALSIFIED — `gh pr comment 42 --body "…"` carrying an executing substitution classifies as
+ * generic `substitution`, and three of three hosted raters called it safe unassisted.
+ *
+ * Every entry states a fact about what THE SHELL does, and then asks a question. Neither is a
+ * verdict about the command in front of the rater, which is what keeps the note neutral while still
+ * carrying the mechanism that the measurement showed is load-bearing.
+ */
+export declare const MECHANISM_NOTES: Readonly<Record<AbstentionMechanism, string>>;
+/**
+ * Classify a command the gate's parser could not resolve, or return `null` when it resolves.
+ *
+ * **The `null` arm is the guard, and it is structural on purpose.** Every mechanism below is a
+ * regex, and `unparseable` is the fallback — so without this gate the function would classify `ls
+ * -la` as `unparseable` and a note would be attached to every command in the session. The predicate
+ * is {@link classifyCommand}'s own, not a second reading of it, so the note appears on exactly the
+ * set of commands the gate could not resolve and on no others.
+ *
+ * Detection runs on the NORMALIZED command (the same form `classifyCommand` refused), so obfuscation
+ * that the normalizer collapses cannot hide a mechanism from the note — while the command shown to
+ * the rater stays the one the rater is being asked about, fenced by its own caller.
+ *
+ * The line-break check reads the RAW command, exactly as `classifyCommand` does: the normalizer is
+ * not required to preserve that separator, and EXT-55 is the node about what happens when a caller
+ * assumes it did.
+ *
+ * **Order is note order, most specific first**, and `commit-message-substitution` SUPPRESSES the
+ * generic substitution note it is a special case of — telling the rater the same thing twice about
+ * one `$(…)` spends attention on a repetition.
+ *
+ * @param command The raw command string as the model proposed it.
+ * @returns What the parser saw, or `null` when the command's target statically resolves.
+ */
+export declare function describeAbstention(command: string): AbstentionDefect | null;
+/**
+ * The opening line of the preflight note: **what this is, and what it is not.**
+ *
+ * It says the finding is about OUR PARSER rather than about the command, and that nothing has been
+ * judged. Both halves are load-bearing. The first stops the rater reading the note as a report of
+ * something found — the failure mode a bare observation produced, where a rater treats our
+ * uncertainty as evidence and either inflates or explains it away. The second is what keeps this
+ * note out of the open-world note's register: that one may say the command *"has ALREADY been
+ * floored deterministically and will be shown to the user whatever you return"*, and here that
+ * sentence would simply be false.
+ */
+export declare const PARSER_NOTE_PREAMBLE: string;
+/**
+ * Build the neutral preflight note for a command, or `null` when the gate resolved it.
+ *
+ * One note per mechanism the command carries, most specific first, bulleted when there is more than
+ * one — a command can compose AND substitute AND redirect, and a note that mentioned only the first
+ * would leave the rater reasoning about a fragment of the shape.
+ *
+ * @param command The raw command string as the model proposed it.
+ */
+export declare function buildParserPreflightNote(command: string): string | null;

package/dist/core/shell/abstention.js

@@ -0,0 +1,184 @@
+/**
+ * @module core/shell/abstention
+ *
+ * EXT-81 — **what the RATER is told about a command our parser could not resolve.**
+ *
+ * `classifyCommand` resolves a command's target, or returns `null` when it cannot. That `null` used
+ * to be an ACTION: the gate refused the call before any rating, on the theory that a reading of a
+ * command it could not parse was not worth buying. §6.1's rule reverses that — *deterministic checks
+ * fire only where we are confident something is a threat; where we cannot tell, the model decides* —
+ * and a parser reporting that it could not resolve a string is not a detection of anything. So the
+ * finding is now **neutral context handed to the rater**, and the flow is one path: preflight → note
+ * → rate → approve / escalate / halt.
+ *
+ * This module turns the `null` into that note: **which shape the parser saw, and the mechanism that
+ * makes the shape worth a second look.** Two properties are the whole design, and each has a
+ * measurement behind it ([[QA-17]], `docs/test-sessions/qa-17-substitution-note-2026-08-03/`):
+ *
+ * - **The note carries the MECHANISM, not just the construct's name.** A bare *"the parser saw a
+ *   substitution"* observation was measured NEGATIVE on two raters — one became more confidently
+ *   wrong than with no note at all (*"not executed since it's within double quotes"*), another lost
+ *   severity against the control. Adding one sentence of mechanism — that a double-quoted argument
+ *   is not inert prose, because the shell expands it before the outer program runs — is what moved
+ *   every deployment-class rater to the correct verdict. A bare observation from a component that
+ *   has just announced it could not read the command reads as DOUBT, and doubt is not information.
+ * - **The note is ASSISTANCE, never an accusation.** *"Hey rater, here is a command, please pay
+ *   attention it includes composition."* No verdict, no severity, no *suspicious*, no *careful*, no
+ *   *treat this as at least X*, and nothing that caps the outcome — `catastrophic` and `attack` stay
+ *   reachable. A question is allowed; a question is not a lean. A composition is not a hazard:
+ *   `cd build && ls`, `npm test && npm run build` and `git add -A && git status` are the
+ *   overwhelming majority of what this fires on, and a leading note would re-create the very
+ *   escalation this design removes — laundered through the model instead of the parser, and now
+ *   unfalsifiable because a model said it.
+ *
+ * It also states nothing about what the gate will DO with the verdict. The open-world note's shape
+ * (*"has ALREADY been floored deterministically and will be shown to the user whatever you
+ * return"*) is honest only where a floor exists, and for these families none does.
+ *
+ * **Scope, deliberately narrow.** Flag what the parser saw and stop. Extracting spans, naming which
+ * segment is unresolvable, and drawing on surrounding context all wait for real user trial — the
+ * elaborate note is the one most likely to acquire connotation by accident.
+ */
+import { classifyCommand } from '#src/core/shell/arity.js';
+import { COMMAND_SEPARATOR_RE, LINE_BREAK_RE, normalizeCommand, } from '#src/core/shell/normalize.js';
+/**
+ * **The per-family note text — one distinct string per {@link AbstentionMechanism}.**
+ *
+ * Typed as a total `Record`, so adding a mechanism is a COMPILE ERROR until someone writes its
+ * sentence. A family that silently fell back to another family's note would be the failure this
+ * table exists to prevent: [[QA-17]] measured that the note's effect is family-specific, and
+ * `docs/test-sessions/qa-17-substitution-note-2026-08-03/` records a narrowing by family name that
+ * was FALSIFIED — `gh pr comment 42 --body "…"` carrying an executing substitution classifies as
+ * generic `substitution`, and three of three hosted raters called it safe unassisted.
+ *
+ * Every entry states a fact about what THE SHELL does, and then asks a question. Neither is a
+ * verdict about the command in front of the rater, which is what keeps the note neutral while still
+ * carrying the mechanism that the measurement showed is load-bearing.
+ */
+export const MECHANISM_NOTES = {
+    'commit-message-substitution': 'This is a git commit carrying its message inline, and the message contains a ' +
+        'dollar-parenthesis or a backtick. The SHELL expands that before git ever sees the message, ' +
+        'so the text inside the quotes is not inert prose: double quotes do not stop `$(…)` or a ' +
+        'backtick from running, and git receives whatever it produced. What does the shell run when ' +
+        'it expands that message?',
+    composition: 'This command line runs MORE THAN ONE command — a `;`, `&&`, `||`, `|` or a line break ' +
+        'separates them — and the shell runs each part in turn, feeding one into the next where the ' +
+        'separator is a pipe. What does the whole line do once every part has run?',
+    substitution: 'This command line contains a substitution — `$(…)`, a backtick, `${…}` or `<(…)`. The SHELL ' +
+        'expands it BEFORE the outer program runs, and hands that program the result. A ' +
+        'double-quoted argument is therefore not inert prose: double quotes do not stop `$(…)` or a ' +
+        'backtick from being run, so a substitution inside what reads as ordinary text is still ' +
+        'executed. What does the shell run when it expands this one?',
+    redirect: 'This command line redirects a stream — `>`, `>>`, `<`, `2>` or `&>`. The shell attaches a ' +
+        'file to the program before the program starts, so its output lands in that file rather than ' +
+        'on the terminal, and a `>` truncates the file it names first. Which file is being read or ' +
+        'written here?',
+    unparseable: 'The gate could not tokenize this command line at all — most often an unbalanced quote, or no ' +
+        'program name it could identify. So we cannot tell you which program this runs; what is ' +
+        'quoted above is exactly the text that would be handed to the shell. What does it do?',
+};
+/** Process substitution `<(…)` / `>(…)`, which is a SUBSTITUTION and must not also read as a redirect. */
+const PROCESS_SUBSTITUTION_RE = /[<>]\(/g;
+/**
+ * Does this look like a `git commit` carrying an inline message?
+ *
+ * Deliberately a heuristic and not a parser: the command has already defeated the gate's tokenizer,
+ * so there is nothing precise left to parse. It is safe to be approximate here because a wrong
+ * answer costs at most a less specific note — the rating is bought either way.
+ */
+const GIT_COMMIT_RE = /\bgit\b[^\n]*\bcommit\b/i;
+const INLINE_MESSAGE_FLAG_RE = /(^|\s)(-m\b|--message\b|-\w*m\b)/;
+/** Command substitution `$(…)` or a backtick — the two the shell EXECUTES. */
+const EXECUTING_SUBSTITUTION_RE = /\$\(|`/;
+/** Every substitution/expansion form, including the non-executing ones. */
+const ANY_SUBSTITUTION_RE = /\$\(|`|\$\{|[<>]\(/;
+/**
+ * Classify a command the gate's parser could not resolve, or return `null` when it resolves.
+ *
+ * **The `null` arm is the guard, and it is structural on purpose.** Every mechanism below is a
+ * regex, and `unparseable` is the fallback — so without this gate the function would classify `ls
+ * -la` as `unparseable` and a note would be attached to every command in the session. The predicate
+ * is {@link classifyCommand}'s own, not a second reading of it, so the note appears on exactly the
+ * set of commands the gate could not resolve and on no others.
+ *
+ * Detection runs on the NORMALIZED command (the same form `classifyCommand` refused), so obfuscation
+ * that the normalizer collapses cannot hide a mechanism from the note — while the command shown to
+ * the rater stays the one the rater is being asked about, fenced by its own caller.
+ *
+ * The line-break check reads the RAW command, exactly as `classifyCommand` does: the normalizer is
+ * not required to preserve that separator, and EXT-55 is the node about what happens when a caller
+ * assumes it did.
+ *
+ * **Order is note order, most specific first**, and `commit-message-substitution` SUPPRESSES the
+ * generic substitution note it is a special case of — telling the rater the same thing twice about
+ * one `$(…)` spends attention on a repetition.
+ *
+ * @param command The raw command string as the model proposed it.
+ * @returns What the parser saw, or `null` when the command's target statically resolves.
+ */
+export function describeAbstention(command) {
+    if (classifyCommand(command, normalizeCommand) !== null)
+        return null;
+    const normalized = normalizeCommand(command);
+    const composes = COMMAND_SEPARATOR_RE.test(normalized) || LINE_BREAK_RE.test(command.trim());
+    const substitutes = ANY_SUBSTITUTION_RE.test(normalized);
+    const commitSubstitution = GIT_COMMIT_RE.test(normalized) &&
+        INLINE_MESSAGE_FLAG_RE.test(normalized) &&
+        EXECUTING_SUBSTITUTION_RE.test(normalized);
+    // A redirect is any `<`/`>` that is NOT the opening of a process substitution — that form is
+    // already reported as a substitution, and reporting it twice would describe one piece of syntax
+    // with two different mechanisms.
+    const redirects = /[<>]/.test(normalized.replace(PROCESS_SUBSTITUTION_RE, ''));
+    const mechanisms = [];
+    if (commitSubstitution)
+        mechanisms.push('commit-message-substitution');
+    if (composes)
+        mechanisms.push('composition');
+    if (substitutes && !commitSubstitution)
+        mechanisms.push('substitution');
+    if (redirects)
+        mechanisms.push('redirect');
+    // The fallback for the causes that are not a shape at all — an unbalanced quote, an empty
+    // command, a command with no resolvable program name — so a note is never empty.
+    if (mechanisms.length === 0)
+        mechanisms.push('unparseable');
+    return {
+        mechanism: mechanisms[0],
+        mechanisms,
+        notes: mechanisms.map((mechanism) => MECHANISM_NOTES[mechanism]),
+    };
+}
+/**
+ * The opening line of the preflight note: **what this is, and what it is not.**
+ *
+ * It says the finding is about OUR PARSER rather than about the command, and that nothing has been
+ * judged. Both halves are load-bearing. The first stops the rater reading the note as a report of
+ * something found — the failure mode a bare observation produced, where a rater treats our
+ * uncertainty as evidence and either inflates or explains it away. The second is what keeps this
+ * note out of the open-world note's register: that one may say the command *"has ALREADY been
+ * floored deterministically and will be shown to the user whatever you return"*, and here that
+ * sentence would simply be false.
+ */
+export const PARSER_NOTE_PREAMBLE = 'PREFLIGHT NOTE: our command parser could not resolve what this command line runs, so here is ' +
+    'what it did see. This is a fact about OUR PARSER and not a finding about the command — nothing ' +
+    'has been judged, nothing has been floored, and none of this is a verdict or a severity. Rate ' +
+    'the command on its own merits.';
+/**
+ * Build the neutral preflight note for a command, or `null` when the gate resolved it.
+ *
+ * One note per mechanism the command carries, most specific first, bulleted when there is more than
+ * one — a command can compose AND substitute AND redirect, and a note that mentioned only the first
+ * would leave the rater reasoning about a fragment of the shape.
+ *
+ * @param command The raw command string as the model proposed it.
+ */
+export function buildParserPreflightNote(command) {
+    const defect = describeAbstention(command);
+    if (defect === null)
+        return null;
+    const body = defect.notes.length === 1
+        ? defect.notes[0]
+        : defect.notes.map((note) => `- ${note}`).join('\n');
+    return `${PARSER_NOTE_PREAMBLE}\n${body}`;
+}
+//# sourceMappingURL=abstention.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"abstention.js","sourceRoot":"","sources":["../../../src/core/shell/abstention.ts"],"names":[],"mappings":"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"}