@gaunt-sloth/core 2.0.0-alpha.4 → 2.0.0-alpha.40

package/dist/core/runStats.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @packageDocumentation
+ * GS2-16 — pure, fail-soft helpers that harvest per-run analytics (token usage + invoked tool
+ * names) from LangChain messages, so the opt-in history recorder can populate `gth insights`
+ * with real numbers instead of zeros.
+ *
+ * The extraction is deliberately structural and defensive (duck-typed reads guarded by a
+ * try/catch) rather than `instanceof`-based: the same accumulator serves both the non-streaming
+ * `invoke` path (a full `messages[]` from graph state) and the streaming paths (individual
+ * 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, 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. */
+    input: number;
+    /** Running sum of output/completion tokens. */
+    output: number;
+    /** Whether ANY message reported `usage_metadata` — gates whether tokens are recorded at all. */
+    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`),
+ * - 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, 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. */
+export declare function finalizeRunStats(acc: RunStatsAccumulator): GthRunStats;
+/**
+ * One-shot convenience for the non-streaming path: fold a full `messages[]` (e.g. the final graph
+ * state) into a fresh accumulator and finalize. Fail-soft (a non-iterable input yields empties).
+ */
+export declare function extractRunStats(messages: unknown): GthRunStats;

package/dist/core/runStats.js

@@ -0,0 +1,118 @@
+/**
+ * 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(), 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`),
+ * - 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, 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 {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const m = message;
+        if (!m || typeof m !== 'object')
+            return;
+        const usage = m.usage_metadata;
+        if (usage && typeof usage === 'object') {
+            acc.sawUsage = true;
+            if (typeof usage.input_tokens === 'number' && Number.isFinite(usage.input_tokens)) {
+                acc.input += usage.input_tokens;
+            }
+            if (typeof usage.output_tokens === 'number' && Number.isFinite(usage.output_tokens)) {
+                acc.output += usage.output_tokens;
+            }
+        }
+        // Requested tool calls (AIMessage / AIMessageChunk). Continuation chunks in a streamed
+        // tool call carry an empty name, so guard on a non-empty string; the Set dedupes repeats.
+        const toolCalls = m.tool_calls;
+        if (Array.isArray(toolCalls)) {
+            for (const tc of toolCalls) {
+                const name = tc?.name;
+                if (typeof name === 'string' && name.length > 0)
+                    acc.tools.add(name);
+            }
+        }
+        // Executed tool result (ToolMessage). Its `.name` is the tool that produced the result.
+        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 {
+        /* fail-soft: never let stats capture affect a run */
+    }
+}
+/** Freeze the accumulator into the public {@link GthRunStats}. Tokens omitted unless observed. */
+export function finalizeRunStats(acc) {
+    return {
+        tokensInput: acc.sawUsage ? acc.input : undefined,
+        tokensOutput: acc.sawUsage ? acc.output : undefined,
+        tools: [...acc.tools],
+        toolResults: [...acc.toolResults],
+    };
+}
+/**
+ * One-shot convenience for the non-streaming path: fold a full `messages[]` (e.g. the final graph
+ * state) into a fresh accumulator and finalize. Fail-soft (a non-iterable input yields empties).
+ */
+export function extractRunStats(messages) {
+    const acc = createRunStatsAccumulator();
+    try {
+        if (Array.isArray(messages)) {
+            for (const m of messages)
+                accumulateMessage(acc, m);
+        }
+    }
+    catch {
+        /* fail-soft */
+    }
+    return finalizeRunStats(acc);
+}
+//# sourceMappingURL=runStats.js.map

package/dist/core/runStats.js.map

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

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

@@ -0,0 +1,53 @@
+/**
+ * @module core/shell/ShellCommandFailedError
+ *
+ * The typed error a `run_*` shell/dev tool throws when a command did NOT exit cleanly
+ * (non-zero exit code, or killed for exceeding the timeout). It carries the FULL model-facing
+ * 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 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.
+ */
+/**
+ * A `run_*` command that did NOT exit cleanly (non-zero exit code, or was killed for exceeding the
+ * timeout). Carries the FULL model-facing body text ({@link output}) so a softening middleware can
+ * hand the model the exact same observation it saw before — the only change is the tool result's
+ * status flips to `'error'`, which drives the ✗ (`isError`) glyph.
+ *
+ * `executeCommand` previously `resolve()`d on a non-zero exit, so the LangChain `ToolMessage` stayed
+ * `status: 'success'` and every failure rendered a ✓. Throwing this typed error instead lets each
+ * agent's softening middleware convert it into an error `ToolMessage`. A clean exit (`code === 0`)
+ * still `resolve()`s; a spawn-level `child.on('error')` still rejects with a plain `Error`.
+ */
+export declare class ShellCommandFailedError extends Error {
+    /** The full model-facing body (command echo + `<COMMAND_OUTPUT>` + the failure/timeout tail). */
+    readonly output: string;
+    /** The process exit code; `null` when the command was killed (timeout) and never exited cleanly. */
+    readonly exitCode: number | null;
+    /** The exact command string that was executed. */
+    readonly command: string;
+    /** The run_* tool name that invoked the command (e.g. `run_tests`, `run_shell_command`). */
+    readonly toolName: string;
+    constructor(params: {
+        output: string;
+        exitCode: number | null;
+        command: string;
+        toolName: string;
+    });
+}
+/**
+ * Recognise a {@link ShellCommandFailedError} for the softening middleware in either agent.
+ *
+ * Prefers a plain `instanceof` (both agents share this one core module, so the class identity is
+ * the same), but falls back to a STRUCTURAL check keyed on `name === 'ShellCommandFailedError'`
+ * plus the carried fields. The structural arm is deliberate defence against a dual-package /
+ * realm-boundary hazard: if the error ever crossed a module boundary that broke `instanceof`, we
+ * would otherwise silently rethrow a real shell failure and regress the ✗ signal. Every field the
+ * softener reads (`output`) is asserted so a narrowed value is safe to use.
+ */
+export declare function isShellCommandFailedError(e: unknown): e is ShellCommandFailedError;

package/dist/core/shell/ShellCommandFailedError.js

@@ -0,0 +1,67 @@
+/**
+ * @module core/shell/ShellCommandFailedError
+ *
+ * The typed error a `run_*` shell/dev tool throws when a command did NOT exit cleanly
+ * (non-zero exit code, or killed for exceeding the timeout). It carries the FULL model-facing
+ * 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 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.
+ */
+/**
+ * A `run_*` command that did NOT exit cleanly (non-zero exit code, or was killed for exceeding the
+ * timeout). Carries the FULL model-facing body text ({@link output}) so a softening middleware can
+ * hand the model the exact same observation it saw before — the only change is the tool result's
+ * status flips to `'error'`, which drives the ✗ (`isError`) glyph.
+ *
+ * `executeCommand` previously `resolve()`d on a non-zero exit, so the LangChain `ToolMessage` stayed
+ * `status: 'success'` and every failure rendered a ✓. Throwing this typed error instead lets each
+ * agent's softening middleware convert it into an error `ToolMessage`. A clean exit (`code === 0`)
+ * still `resolve()`s; a spawn-level `child.on('error')` still rejects with a plain `Error`.
+ */
+export class ShellCommandFailedError extends Error {
+    /** The full model-facing body (command echo + `<COMMAND_OUTPUT>` + the failure/timeout tail). */
+    output;
+    /** The process exit code; `null` when the command was killed (timeout) and never exited cleanly. */
+    exitCode;
+    /** The exact command string that was executed. */
+    command;
+    /** The run_* tool name that invoked the command (e.g. `run_tests`, `run_shell_command`). */
+    toolName;
+    constructor(params) {
+        // Use the full body as the Error message so any generic logger/handler still surfaces the
+        // real command output rather than an opaque wrapper string.
+        super(params.output);
+        this.name = 'ShellCommandFailedError';
+        this.output = params.output;
+        this.exitCode = params.exitCode;
+        this.command = params.command;
+        this.toolName = params.toolName;
+    }
+}
+/**
+ * Recognise a {@link ShellCommandFailedError} for the softening middleware in either agent.
+ *
+ * Prefers a plain `instanceof` (both agents share this one core module, so the class identity is
+ * the same), but falls back to a STRUCTURAL check keyed on `name === 'ShellCommandFailedError'`
+ * plus the carried fields. The structural arm is deliberate defence against a dual-package /
+ * realm-boundary hazard: if the error ever crossed a module boundary that broke `instanceof`, we
+ * would otherwise silently rethrow a real shell failure and regress the ✗ signal. Every field the
+ * softener reads (`output`) is asserted so a narrowed value is safe to use.
+ */
+export function isShellCommandFailedError(e) {
+    if (e instanceof ShellCommandFailedError)
+        return true;
+    return (typeof e === 'object' &&
+        e !== null &&
+        e.name === 'ShellCommandFailedError' &&
+        typeof e.output === 'string' &&
+        typeof e.command === 'string' &&
+        typeof e.toolName === 'string');
+}
+//# sourceMappingURL=ShellCommandFailedError.js.map

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

@@ -0,0 +1 @@
+{"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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"}