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

package/dist/core/shell/approvalStop.js

@@ -0,0 +1,269 @@
+/**
+ * @module core/shell/approvalStop
+ *
+ * CFG-27 — the two ways the approvals gate **ends a run** rather than answering a tool call.
+ * Both are thrown from `GthAgentRunner.decideToolApproval`, both carry the command and the reason
+ * a person needs to see, and both are re-thrown UNCHANGED by `processMessages` (which otherwise
+ * wraps failures as `Agent processing failed: …`) so the explanation reaches the user intact.
+ *
+ * They are errors rather than {@link ../types.js ToolApprovalDecision}s on purpose. A decision is
+ * something the model observes as a `ToolMessage` and can respond to; these two are precisely the
+ * cases where the spec says the model gets no move at all:
+ *
+ * - **{@link AttackHaltError}** (§4.2) — an `attack` outcome *halts the run*. "A halt ends the
+ *   agent loop. It is not a rejection the model can respond to, and no rung except `bypass` can
+ *   turn it into anything else."
+ * - **{@link NonInteractiveEscalationError}** (§6.2) — where no human can answer, *every*
+ *   escalation is an immediate non-zero exit carrying the command, the rating and its reason.
+ *   There is no prompt, no waiting, and never a timeout into approval. Teams that need specific
+ *   commands to run unattended declare them in `approvals.allow` (§3), which is consulted before
+ *   the rater and therefore never escalates.
+ *
+ * Exit code: neither class sets one. The single-shot runtime (`runSingleShot`) already reports a
+ * thrown run as `ok: false`, and each command entry point turns that into `setExitCode(1)` — so
+ * "immediate non-zero exit carrying the explanation" is what a caller already gets, without a new
+ * exit path that could diverge from the existing one.
+ *
+ * ## [[TUI-C71]] — a stop message is UNTRUSTED TEXT, and it is made safe in two places
+ *
+ * Every string a stop carries except this module's own sentences is written by something other
+ * than the user: the command the agent proposed, the rater's outcome and reason, the
+ * `approvals.escalate` entry that matched, and the whole §5 negotiation. On an `attack` verdict
+ * that is the *worst* text in the system by construction — the rater judged the command's own
+ * structure to evidence deception or obfuscation — so a stop is the one message most likely to
+ * carry a payload crafted to forge terminal output, and the last one that may be printed raw.
+ *
+ * The defence [[TUI-C26]] built has two halves, and they belong at different times:
+ *
+ * 1. **Neutralisation is done HERE, at construction, unconditionally.** It needs no width and no
+ *    screen, it is idempotent, and it is the half every consumer needs — a thrown stop reaches the
+ *    Ink transcript, `--no-tui` stderr, a session log, the approvals archive (`record.error`), an
+ *    eval turn record, AG-UI and a CI job's output, and only some of those are terminals. Doing it
+ *    at each render site would mean every present and future consumer had to remember; doing it
+ *    once here means none of them can forget. After it, `{@link message}` contains no control or
+ *    format character at all: a carriage return is the five printable characters `\x0d`, and —
+ *    because LF is a control character too — untrusted text cannot even open a new line, let alone
+ *    reach column 0 on one.
+ * 2. **The gutter and the width bound are done at RENDER, by the surface** ({@link
+ *    approvalStopRows} for the plain surfaces, `<ApprovalStopMessage>` for the Ink TUI). They
+ *    cannot be done here: framing is arithmetic against a terminal width, an `Error.message` has
+ *    no width, and a block wrapped for an 80-column terminal is wrong for every other one. What
+ *    they buy over neutralisation alone is the last case it cannot close — one very long
+ *    neutralised line that the *terminal* wraps, whose continuation starts at column 0 carrying
+ *    whatever the attacker chose to put at that offset. That route is measured, not theorised: on
+ *    a 120-column terminal the neutralised `Command:` line of a hostile command is ~164 columns.
+ *
+ * **Because half of it is the surface's job, the surfaces are enumerated rather than assumed.**
+ * Every place that catches an `ApprovalStopError` and prints it calls {@link approvalStopRows} (or
+ * the Ink component): `runtime/singleShot.ts`, `runtime/conversation.ts`,
+ * `agent/modules/interactiveSessionModule.ts` (both its per-turn catch and its outermost one, which
+ * is where the `-m` path lands), `review/modules/reviewModule.ts`, `app/commands/prCommand.ts`
+ * (which catches what the PR-discovery agent throws) and `app/tui/components/App.tsx`.
+ * **Adding a surface that catches a stop means adding it to that list.**
+ *
+ * **That list is over the ERROR, and the error is not the only way a stop reaches a screen.** Some
+ * consumers take {@link message} and hand the *string* onward, at which point no `instanceof` can
+ * find it again: `runConversation` records it as a turn's `error`, and `evalRunner` folds that into
+ * an eval case's `reasons`, which `batch/reporters/textReporter.ts` prints — a terminal, reached
+ * without any of its code ever seeing this class. That one frames the text itself. So the honest
+ * statement is not "every other consumer is a non-terminal" but: **a consumer that prints to a
+ * terminal frames what it prints, whether it holds the error or only its text**, and the ones that
+ * legitimately do neither are the file and protocol sinks (the approvals archive, the JUnit/JSON
+ * reports, the AG-UI event) plus `reviewModule`'s `displayDebug` of the raw error, which is a debug
+ * channel. All of them still inherit the neutralisation, which is what keeps the worst case a
+ * wrapped line rather than a repainted screen.
+ *
+ * **The structured fields stay RAW; only the message is neutralised.** That is what answers the
+ * obvious objection to construction-time work — that it stops the error being a faithful record of
+ * what was proposed. `{@link ApprovalStopError.command}`, `reason`, `outcome`, `escalatedBy` and
+ * `negotiation` are the command as the agent wrote it, byte for byte, for any consumer that needs
+ * the truth rather than a screen; the message is the *presentation*, and a presentation that can
+ * repaint the terminal is not one. The render path frames from those raw fields, so its gutter
+ * numbers the command's real lines rather than one escaped line.
+ *
+ * **One parts list, two renderings** ({@link ApprovalStopPart}). The message string and the framed
+ * block are both derived from {@link ApprovalStopError.parts}, so they cannot come to describe one
+ * stop two ways — the same argument `renderNegotiationTranscript` makes for its own two surfaces.
+ * A part is tagged with *who wrote it*, which is the only distinction any of this rests on: the
+ * gate's own prose can be painted as it is because nothing can forge it, and everything else goes
+ * through the shared renderer.
+ */
+import { frameUntrustedCommand, frameUntrustedText, frameWidthFor, narrowTerminalNotice, neutralizeUntrustedText, } from '#src/core/shell/framing.js';
+/**
+ * The parts as the one string an `Error.message` has to be, with every untrusted part neutralised.
+ *
+ * A `block` is neutralised **line by line**, so the renderer-owned breaks that carry its meaning
+ * survive while its content still cannot introduce one. Everything else is neutralised whole,
+ * which — LF being a control character — is what collapses an untrusted value onto the single line
+ * its label put it on.
+ */
+function composeMessage(parts) {
+    return parts.map(messageLineFor).join('\n');
+}
+function messageLineFor(part) {
+    switch (part.kind) {
+        case 'own':
+            return part.text;
+        case 'block':
+            return part.text.split('\n').map(neutralizeUntrustedText).join('\n');
+        default:
+            return `  ${part.label}: ${neutralizeUntrustedText(part.text)}`;
+    }
+}
+/**
+ * The stop as terminal rows, for a surface that paints lines rather than components.
+ *
+ * Every row is painted **verbatim, one row per line, and never re-wrapped** — that is the
+ * condition `core/shell/framing` states its column-0 guarantee over, and a caller that joins these
+ * and hands them to something that wraps has undone the whole point.
+ *
+ * `columns` is what the surface reports (`stdout.columns`), not a frame width: it is resolved
+ * through {@link frameWidthFor} here so the plain surfaces, the Ink TUI and the approval dialog
+ * cannot come to disagree about how much of a command a human was shown. When it is below core's
+ * floor the frame is wider than the terminal and the guarantee lapses — {@link narrowTerminalNotice}
+ * leads the block in that case, so it lapses out loud.
+ */
+export function approvalStopRows(parts, options) {
+    const width = frameWidthFor(options?.columns);
+    const rows = [];
+    const tooNarrow = narrowTerminalNotice(options?.columns);
+    if (tooNarrow)
+        rows.push(tooNarrow);
+    for (const part of parts) {
+        if (part.kind === 'own') {
+            rows.push(part.text);
+            continue;
+        }
+        // The label is the gate's OWN word for what follows, and it stays on the gate's own row rather
+        // than being prefixed to the first framed row — a label sharing a row with untrusted text is a
+        // row a reader cannot tell apart from one the model wrote all of.
+        if (part.kind !== 'block')
+            rows.push(`  ${part.label}:`);
+        const framed = part.kind === 'command'
+            ? frameUntrustedCommand(part.text, { width })
+            : frameUntrustedText(part.text, { width });
+        rows.push(...framed.notices, ...framed.lines);
+    }
+    return rows;
+}
+/**
+ * Base class for the two run-ending approvals outcomes, so a caller that wants to present them as
+ * an ending rather than a crash can catch both with one `instanceof`.
+ *
+ * A surface that can frame should render {@link parts} (see {@link approvalStopRows}); one that
+ * cannot shows {@link message}, which is already neutralised and is already the whole explanation.
+ */
+export class ApprovalStopError extends Error {
+    /** The command that ended the run, exactly as the agent proposed it. */
+    command;
+    /** The message's pieces, tagged with who wrote each — see {@link ApprovalStopPart}. */
+    parts;
+    constructor(parts, command) {
+        super(composeMessage(parts));
+        this.command = command;
+        this.parts = parts;
+        // Restore the prototype chain across the ES5 `extends Error` downlevel, so `instanceof` works.
+        Object.setPrototypeOf(this, new.target.prototype);
+        this.name = new.target.name;
+    }
+}
+/**
+ * §4.2 — an `attack` outcome: the command's own **structure** evidenced compromise (§4.1.1 —
+ * credential targeting, privilege escalation, persistence, deception, obfuscation). Ends the agent
+ * loop; the model is told nothing and offered nothing.
+ *
+ * **This is what reaches a surface that cannot ask.** An interactive surface is offered [[TUI-C68]]
+ * §6.1's red banner first — `GthAgentRunner.setAttackHaltCallback`, where typing `run anyway` runs
+ * this one command and everything else stops the run — and this error is thrown when no banner is
+ * wired, or when the banner is answered with anything but that phrase. A non-interactive session
+ * wires nothing and so gets this message directly (§6.2).
+ *
+ * The recovery this message names is deliberately the **allow-list**, not `bypass`. §4.2 makes
+ * `approvals.allow` the supported way to run such a command unattended (it is consulted before the
+ * rater, so it never reaches a halt at all); `bypass` also works and is far blunter — it turns off
+ * the rater, the escalation and the halt together, for every command, for the whole run. It is a
+ * last resort, not the answer, and the wording says so in that order.
+ */
+export class AttackHaltError extends ApprovalStopError {
+    /** The rater's explanation of what the command's structure showed. */
+    reason;
+    constructor(command, reason) {
+        super([
+            {
+                kind: 'own',
+                text: 'Run halted: the auto-rater rated this command as an attack, which ends the run.',
+            },
+            { kind: 'command', label: 'Command', text: command },
+            { kind: 'value', label: 'Reason', text: reason },
+            {
+                kind: 'own',
+                text: `This is not negotiable. If this command is legitimate and you need it to run, declare ` +
+                    `it in approvals.allow — that list is consulted before the auto-rater, so it never ` +
+                    `reaches a halt. Dropping to approvals "bypass" also works, but it turns off the rater, ` +
+                    `the prompts and the halt for every command in the run.`,
+            },
+        ], command);
+        this.reason = reason;
+    }
+}
+/**
+ * §6.2 — an escalation with nobody to ask (CI, one-shot runs, servers). Fails the build loudly,
+ * with everything a person needs in order to see why.
+ */
+export class NonInteractiveEscalationError extends ApprovalStopError {
+    /** The rater's outcome, when a rating existed (the unrated rungs have none). */
+    outcome;
+    /** The rater's explanation, when a rating existed. */
+    reason;
+    /**
+     * EXT-71 §3.2 — the declared `approvals.escalate` entry that sent this call to a human, when one
+     * did. It changes the recovery the message names: pointing someone at `approvals.allow` when they
+     * themselves wrote an escalate entry sends them to a list that cannot win, since a match on
+     * `escalate` outranks a match on `allow`.
+     */
+    escalatedBy;
+    /**
+     * [[EXT-29]] §6 — the §5 negotiation that preceded this escalation, rendered, when there was one.
+     *
+     * §6.2's message is the ONLY thing a person sees on this path — there is no prompt to attach a
+     * transcript to — so an unattended run that ended after three rejections would otherwise report
+     * the last command and give no hint that the agent had already been told twice what to fix.
+     */
+    negotiation;
+    constructor(command, outcome, reason, escalatedBy, negotiation) {
+        const parts = [
+            { kind: 'own', text: 'Approval required, but this session has no one to ask.' },
+            { kind: 'command', label: 'Command', text: command },
+        ];
+        if (outcome)
+            parts.push({ kind: 'value', label: 'Rating', text: outcome });
+        if (reason)
+            parts.push({ kind: 'value', label: 'Reason', text: reason });
+        if (negotiation)
+            parts.push({ kind: 'block', text: negotiation });
+        if (escalatedBy) {
+            parts.push({ kind: 'value', label: 'Matched approvals.escalate', text: escalatedBy });
+            parts.push({
+                kind: 'own',
+                text: `An escalate entry always asks a human, whatever the rung would have done, so no ` +
+                    `entry in approvals.allow can answer it. Remove the escalate entry if this command ` +
+                    `should run unattended.`,
+            });
+        }
+        else {
+            parts.push({
+                kind: 'own',
+                text: `Declare the commands this run is allowed to execute in approvals.allow — write each ` +
+                    `one as an explicit entry, for example { "type": "shell", "matcher": "exact", ` +
+                    `"pattern": "npm test" }. That list is consulted before the auto-rater and never ` +
+                    `escalates.`,
+            });
+        }
+        super(parts, command);
+        this.outcome = outcome;
+        this.reason = reason;
+        this.escalatedBy = escalatedBy;
+        this.negotiation = negotiation;
+    }
+}
+//# sourceMappingURL=approvalStop.js.map

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

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

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

@@ -18,6 +18,12 @@
  * redirections. Such commands NEVER auto-match an allow-list entry — they always go to
  * fresh human approval. This is what stops `git checkout x; rm -rf /` from matching an
  * approved `git checkout *`.
+ *
+ * EXT-55: "newlines" in that list was aspirational until this node. `normalizeCommand` folded
+ * a line break to a SPACE, so the check below never saw one and `ls -la\nrm -rf /` classified
+ * as the single command `ls`. The separator set now lives in ONE place
+ * ({@link import('./normalize.js').COMMAND_SEPARATOR_CLASS}) and a line break survives
+ * normalization, so a multi-line command is categorically ambiguous — exactly like `;`.
  */
 /**
  * Result of classifying a command for allow-list matching.

package/dist/core/shell/arity.js

@@ -18,7 +18,14 @@
  * redirections. Such commands NEVER auto-match an allow-list entry — they always go to
  * fresh human approval. This is what stops `git checkout x; rm -rf /` from matching an
  * approved `git checkout *`.
+ *
+ * EXT-55: "newlines" in that list was aspirational until this node. `normalizeCommand` folded
+ * a line break to a SPACE, so the check below never saw one and `ls -la\nrm -rf /` classified
+ * as the single command `ls`. The separator set now lives in ONE place
+ * ({@link import('./normalize.js').COMMAND_SEPARATOR_CLASS}) and a line break survives
+ * normalization, so a multi-line command is categorically ambiguous — exactly like `;`.
  */
+import { COMMAND_SEPARATOR_RE, LINE_BREAK_RE } from '#src/core/shell/normalize.js';
 /**
  * Arity table: command-prefix string → number of leading tokens (binary + subcommands,
  * flags excluded) that define the "human-understandable command". Longest matching
@@ -181,11 +188,9 @@ const ARITY = {
  * Note: `&&`/`||`/`|` are covered by the bare `&`/`|` character scan; listed conceptually.
  */
 function hasUnsafeComposition(normalized) {
-    // Newlines are folded by normalizeCommand, but guard anyway in case a raw string is passed.
-    if (/[\n\r]/.test(normalized))
-        return true;
-    // Shell control / separator operators and background.
-    if (/[;|&]/.test(normalized))
+    // Shell control / separator operators, background, AND line breaks — one shared definition of
+    // "a new command begins here" (EXT-55), so this can never drift from the hardline floor's.
+    if (COMMAND_SEPARATOR_RE.test(normalized))
         return true;
     // Command substitution: $(...) or `...`.
     if (/\$\(/.test(normalized))
@@ -235,7 +240,9 @@ export function tokenize(command) {
             inToken = true;
             continue;
         }
-        if (ch === ' ' || ch === '\t') {
+        // EXT-55: line breaks are whitespace here too, so a token can never be glued across a line
+        // (`ls\n-o` must tokenize as `ls` + `-o`, or a caller inspecting the argv would miss the flag).
+        if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') {
             if (inToken) {
                 tokens.push(current);
                 current = '';
@@ -294,6 +301,13 @@ export function meaningfulPrefixTokens(argv) {
  * @param normalize Normalizer to apply for the detection form (inject normalizeCommand).
  */
 export function classifyCommand(command, normalize) {
+    // EXT-55 — the boundary question is answered HERE, not delegated to the injected normalizer.
+    // `normalize` is a parameter, so this function cannot assume it preserved the command
+    // separators (folding them away is exactly the bug this node fixed). A line break anywhere
+    // INSIDE the command means more than one command → never classifiable. `.trim()` first: a
+    // purely leading/trailing break separates nothing, and models routinely emit `"npm test\n"`.
+    if (LINE_BREAK_RE.test(command.trim()))
+        return null;
     const normalized = normalize(command);
     if (!normalized)
         return null;

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

@@ -1 +1 @@
-{"version":3,"file":"arity.js","sourceRoot":"","sources":["../../../src/core/shell/arity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH;;;;;;;;;GASG;AACH,MAAM,KAAK,GAAqC;IAC9C,qFAAqF;IACrF,GAAG,EAAE,CAAC;IACN,EAAE,EAAE,CAAC;IACL,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,EAAE,EAAE,CAAC;IACL,IAAI,EAAE,CAAC;IACP,GAAG,EAAE,CAAC;IACN,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,OAAO,EAAE,CAAC;IACV,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,KAAK,EAAE,CAAC;IACR,EAAE,EAAE,CAAC;IACL,EAAE,EAAE,CAAC;IACL,GAAG,EAAE,CAAC;IACN,EAAE,EAAE,CAAC;IACL,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,sBAAsB;IACtB,GAAG,EAAE,CAAC;IACN,EAAE,EAAE,CAAC;IACL,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,GAAG,EAAE,CAAC;IACN,SAAS,EAAE,CAAC;IACZ,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,CAAC;IACd,WAAW,EAAE,CAAC;IACd,GAAG,EAAE,CAAC;IACN,EAAE,EAAE,CAAC;IACL,KAAK,EAAE,CAAC;IACR,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,CAAC;IACT,WAAW,EAAE,CAAC;IACd,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;IACP,WAAW,EAAE,CAAC;IACd,KAAK,EAAE,CAAC;IACR,MAAM,EAAE,CAAC;IACT,gBAAgB,EAAE,CAAC;IACnB,gBAAgB,EAAE,CAAC;IACnB,kBAAkB,EAAE,CAAC;IACrB,cAAc,EAAE,CAAC;IACjB,gBAAgB,EAAE,CAAC;IACnB,eAAe,EAAE,CAAC;IAClB,MAAM,EAAE,CAAC;IACT,eAAe,EAAE,CAAC;IAClB,QAAQ,EAAE,CAAC;IACX,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,EAAE,EAAE,CAAC;IACL,GAAG,EAAE,CAAC;IACN,YAAY,EAAE,CAAC;IACf,YAAY,EAAE,CAAC;IACf,WAAW,EAAE,CAAC;IACd,EAAE,EAAE,CAAC;IACL,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;IACP,EAAE,EAAE,CAAC;IACL,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,CAAC;IACb,IAAI,EAAE,CAAC;IACP,aAAa,EAAE,CAAC;IAChB,OAAO,EAAE,CAAC;IACV,mBAAmB,EAAE,CAAC;IACtB,iBAAiB,EAAE,CAAC;IACpB,SAAS,EAAE,CAAC;IACZ,IAAI,EAAE,CAAC;IACP,EAAE,EAAE,CAAC;IACL,UAAU,EAAE,CAAC;IACb,QAAQ,EAAE,CAAC;IACX,OAAO,EAAE,CAAC;IACV,KAAK,EAAE,CAAC;IACR,GAAG,EAAE,CAAC;IACN,EAAE,EAAE,CAAC;IACL,GAAG,EAAE,CAAC;IACN,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,CAAC;IACb,SAAS,EAAE,CAAC;IACZ,UAAU,EAAE,CAAC;IACb,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,EAAE,EAAE,CAAC;IACL,OAAO,EAAE,CAAC;IACV,aAAa,EAAE,CAAC;IAChB,cAAc,EAAE,CAAC;IACjB,GAAG,EAAE,CAAC;IACN,MAAM,EAAE,CAAC;IACT,IAAI,EAAE,CAAC;IACP,UAAU,EAAE,CAAC;IACb,WAAW,EAAE,CAAC;IACd,UAAU,EAAE,CAAC;IACb,MAAM,EAAE,CAAC;IACT,MAAM,EAAE,CAAC;IACT,kBAAkB,EAAE,CAAC;IACrB,cAAc,EAAE,CAAC;IACjB,IAAI,EAAE,CAAC;IACP,MAAM,EAAE,CAAC;IACT,cAAc,EAAE,CAAC;IACjB,KAAK,EAAE,CAAC;IACR,MAAM,EAAE,CAAC;IACT,OAAO,EAAE,CAAC;IACV,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,WAAW,EAAE,CAAC;IACd,MAAM,EAAE,CAAC;IACT,UAAU,EAAE,CAAC;IACb,IAAI,EAAE,CAAC;IACP,QAAQ,EAAE,CAAC;IACX,GAAG,EAAE,CAAC;IACN,GAAG,EAAE,CAAC;IACN,KAAK,EAAE,CAAC;IACR,SAAS,EAAE,CAAC;IACZ,SAAS,EAAE,CAAC;IACZ,qBAAqB,EAAE,CAAC;IACxB,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;IACR,GAAG,EAAE,CAAC;IACN,KAAK,EAAE,CAAC;IACR,YAAY,EAAE,CAAC;IACf,UAAU,EAAE,CAAC;IACb,MAAM,EAAE,CAAC;IACT,KAAK,EAAE,CAAC;IACR,EAAE,EAAE,CAAC;IACL,IAAI,EAAE,CAAC;IACP,UAAU,EAAE,CAAC;IACb,UAAU,EAAE,CAAC;CACd,CAAC;AAqBF;;;;;;GAMG;AACH,SAAS,oBAAoB,CAAC,UAAkB;IAC9C,4FAA4F;IAC5F,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,sDAAsD;IACtD,IAAI,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC1C,yCAAyC;IACzC,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,GAAG,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACtC,mEAAmE;IACnE,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,0CAA0C;IAC1C,IAAI,QAAQ,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAC3C,0FAA0F;IAC1F,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,QAAQ,CAAC,OAAe;IACtC,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,IAAI,OAAO,GAAG,EAAE,CAAC;IACjB,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,KAAK,GAAqB,IAAI,CAAC;IAEnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACxC,MAAM,EAAE,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,KAAK,EAAE,CAAC;YACV,IAAI,EAAE,KAAK,KAAK,EAAE,CAAC;gBACjB,KAAK,GAAG,IAAI,CAAC;YACf,CAAC;iBAAM,CAAC;gBACN,OAAO,IAAI,EAAE,CAAC;YAChB,CAAC;YACD,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YAC7B,KAAK,GAAG,EAAE,CAAC;YACX,OAAO,GAAG,IAAI,CAAC;YACf,SAAS;QACX,CAAC;QACD,IAAI,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;YAC9B,IAAI,OAAO,EAAE,CAAC;gBACZ,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACrB,OAAO,GAAG,EAAE,CAAC;gBACb,OAAO,GAAG,KAAK,CAAC;YAClB,CAAC;YACD,SAAS;QACX,CAAC;QACD,OAAO,IAAI,EAAE,CAAC;QACd,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,IAAI,KAAK;QAAE,OAAO,IAAI,CAAC,CAAC,mBAAmB;IAC3C,IAAI,OAAO;QAAE,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAc;IACnD,qFAAqF;IACrF,oFAAoF;IACpF,8DAA8D;IAC9D,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;IACvD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEpC,mDAAmD;IACnD,KAAK,IAAI,GAAG,GAAG,OAAO,CAAC,MAAM,EAAE,GAAG,GAAG,CAAC,EAAE,GAAG,EAAE,EAAE,CAAC;QAC9C,MAAM,SAAS,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAClD,MAAM,KAAK,GAAG,KAAK,CAAC,SAAS,CAAC,CAAC;QAC/B,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;YACxB,0EAA0E;YAC1E,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,KAAK,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAC3D,CAAC;IACH,CAAC;IACD,sDAAsD;IACtD,OAAO,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAe,EACf,SAAkC;IAElC,MAAM,UAAU,GAAG,SAAS,CAAC,OAAO,CAAC,CAAC;IACtC,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAE7B,sFAAsF;IACtF,iEAAiE;IACjE,IAAI,oBAAoB,CAAC,UAAU,CAAC;QAAE,OAAO,IAAI,CAAC;IAElD,MAAM,IAAI,GAAG,QAAQ,CAAC,UAAU,CAAC,CAAC;IAClC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE5C,MAAM,YAAY,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAClD,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAE3C,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACtC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,IAAI,EAAE,CAAC;AAC5C,CAAC"}
+{"version":3,"file":"arity.js","sourceRoot":"","sources":["../../../src/core/shell/arity.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,11 @@
+/**
+ * Split a raw command into the segments a shell would run, normalized and **case preserved**.
+ *
+ * Substitution bodies are segments in their own right: `echo $(npm publish)` runs `npm publish`,
+ * so a deny entry for `npm publish` must see it. Splitting on `$(`, `` ` `` and `)` yields the
+ * body as its own segment (and leaves harmless empty fragments, which are dropped).
+ *
+ * Case is preserved because the matcher folds it per list and per matcher — a `regexp` entry is
+ * compiled exactly as the user wrote it, and folding here would decide that for it.
+ */
+export declare function commandSegments(command: string): string[];

package/dist/core/shell/denylist.js

@@ -0,0 +1,37 @@
+/**
+ * @module core/shell/denylist
+ *
+ * **Command segmentation** — splitting a command into every command a shell would actually run.
+ *
+ * This is what lets a restrictive rule (`deny`, `escalate`) see inside a compound command. The
+ * asymmetry it serves lives in `core/approvals/matcher.ts`, which is the one comparison engine:
+ *
+ * - **No allow entry matches a command that does not statically resolve.** Composition,
+ *   substitution and redirection are a non-match for every allow entry, so a grant can never be
+ *   extended with a `; rm -rf /`.
+ * - **A deny or escalate entry MAY match one**, and is compared against every segment as well as
+ *   the whole string, because a prohibition that catches something unresolvable errs in the
+ *   direction that costs nothing. Without that, `git push --force; ls` would sail straight past a
+ *   declared deny entry for `git push --force` — a prohibition any trailing `; ls` defeats is not a
+ *   prohibition.
+ */
+import { COMMAND_SEPARATOR_CLASS, normalizeCommand } from '#src/core/shell/normalize.js';
+/** Splits the normalized command at every point where a shell would begin a NEW command. */
+const SEGMENT_SPLIT_RE = new RegExp(`[${COMMAND_SEPARATOR_CLASS}]|\\$\\(|\\)|\``, 'g');
+/**
+ * Split a raw command into the segments a shell would run, normalized and **case preserved**.
+ *
+ * Substitution bodies are segments in their own right: `echo $(npm publish)` runs `npm publish`,
+ * so a deny entry for `npm publish` must see it. Splitting on `$(`, `` ` `` and `)` yields the
+ * body as its own segment (and leaves harmless empty fragments, which are dropped).
+ *
+ * Case is preserved because the matcher folds it per list and per matcher — a `regexp` entry is
+ * compiled exactly as the user wrote it, and folding here would decide that for it.
+ */
+export function commandSegments(command) {
+    return normalizeCommand(command)
+        .split(SEGMENT_SPLIT_RE)
+        .map((segment) => segment.trim())
+        .filter((segment) => segment.length > 0);
+}
+//# sourceMappingURL=denylist.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"denylist.js","sourceRoot":"","sources":["../../../src/core/shell/denylist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,OAAO,EAAE,uBAAuB,EAAE,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AAEzF,4FAA4F;AAC5F,MAAM,gBAAgB,GAAG,IAAI,MAAM,CAAC,IAAI,uBAAuB,iBAAiB,EAAE,GAAG,CAAC,CAAC;AAEvF;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,OAAe;IAC7C,OAAO,gBAAgB,CAAC,OAAO,CAAC;SAC7B,KAAK,CAAC,gBAAgB,CAAC;SACvB,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;SAChC,MAAM,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;AAC7C,CAAC"}

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

@@ -0,0 +1,141 @@
+/**
+ * @module core/shell/escalationSeverity
+ *
+ * [[TUI-C26]] (spec §6) — **how severe the escalation is, said in words.**
+ *
+ * Every escalation used to look identical: the same yellow line, the same
+ * `⚠ Auto-rater (<outcome>):`, on both surfaces. So `npm install lodash` and a typosquatted
+ * `curl | bash` produced the same dialog, and a dialog that looks the same for everything trains
+ * the reader to answer it the same way — which costs more than having no dialog at all.
+ *
+ * ## Why the words carry it, not the colour
+ *
+ * Colour is not reliably available. `NO_COLOR` is set on plenty of machines, output gets piped, a
+ * monochrome or high-contrast terminal renders every tone identically, and a reader may simply not
+ * be looking at hue. So each outcome carries **three** independent signals — a glyph, a tone and a
+ * sentence — and the sentence is the one that always arrives. A change that makes two outcomes read
+ * the same in words has removed the signal even if the colours still differ.
+ *
+ * **What the sentence says is the consequence, not the severity word again.** `catastrophic` is
+ * defined by needing something from *outside* the session to undo (rescue media, a backup, a
+ * re-provision), and that — not the adjective — is what a person can act on.
+ *
+ * ## The map is total, and `attack` is in it
+ *
+ * A `Record<RaterOutcome, …>` rather than a lookup with a default: an outcome added to
+ * {@link RATER_OUTCOMES} must be given words here, and cannot silently inherit another outcome's.
+ *
+ * `attack` is present for that totality and **not because the approval prompt renders it**. An
+ * `attack` verdict halts the run (`AttackHaltError`) on both rating paths, so it never reaches an
+ * approval dialog: it is answered at [[TUI-C68]]'s §6.1 banner, whose copy is
+ * {@link attackBannerCopy} — here, beside the heading it reuses, so the two cannot come to describe
+ * one verdict two ways.
+ *
+ * `attack` shares the `danger` tone and glyph with `catastrophic` deliberately: the two are not
+ * ranked against each other (they answer different questions — *can this be undone?* versus *is
+ * something hostile acting here?*), so distinguishing them by loudness would assert an ordering the
+ * rater's own schema refuses. They are distinguished where it matters, in what they say.
+ */
+import type { RaterOutcome } from '#src/core/shell/rater.js';
+/**
+ * How loud a surface should be about an outcome. A surface maps this to its own vocabulary — Ink
+ * colours on the TUI, a `DialogTone` on the readline prompt — so neither has to hold its own
+ * opinion about which outcome is worse than which.
+ */
+export type EscalationTone = 'notice' | 'warn' | 'danger';
+/** Everything a surface needs to render one outcome, so no surface invents its own wording. */
+export interface RaterOutcomeDisplay {
+    /**
+     * The heading a surface paints above the rater's reason, glyph and sentence included.
+     *
+     * It keeps the `Auto-rater (<outcome>):` opening the dialog has always had — that is the
+     * attribution, and the reason underneath it is the rater's, not the gate's — and adds the
+     * consequence after it.
+     */
+    heading: string;
+    /** The tone the heading and the framed reason are painted in. */
+    tone: EscalationTone;
+}
+/**
+ * The label above the framed reason.
+ *
+ * The heading now carries a sentence of the gate's own, so without this the model-authored prose
+ * beneath it could be read as a continuation of what the gate said. §6 wants the opposite: the
+ * reason is the rater's, quoted, and it is framed exactly like the command for the same reason.
+ */
+export declare const RATER_REASON_LABEL = "    the rater's own words:";
+/** How to render {@link RaterOutcome} on an approval dialog. */
+export declare function describeRaterOutcome(outcome: RaterOutcome): RaterOutcomeDisplay;
+/**
+ * [[TUI-C68]] §6.1 — **the phrase that runs an `attack`-rated command anyway.** The only string on
+ * the banner that is not a refusal.
+ *
+ * A typed phrase rather than a key, because an irreversible decision must not be reachable by the
+ * muscle memory built answering routine prompts. A key merely *disjoint from today's menu* stops
+ * being disjoint the moment someone binds one; a phrase is immune to any future binding. `run`
+ * alone was considered and rejected as the leading token of half of what anyone types into a
+ * terminal.
+ *
+ * The label is never `bypass`: that is a rung (§2.5) and a far broader thing — it turns off the
+ * rater, the escalation and the halt together, for every command, for the whole run — and a user
+ * must never read this banner as switching to it.
+ */
+export declare const RUN_ANYWAY_PHRASE = "run anyway";
+/**
+ * §6.1 — does what the human typed grant this one command?
+ *
+ * **The whole matching rule, in one place both surfaces call**, so what the banner *says* is
+ * answerable and what a surface *accepts* cannot drift. Trimmed, lower-cased, compared whole:
+ * `RUN ANYWAY` and a phrase with surrounding spaces grant; `run`, `runanyway`, `run anyway please`
+ * and the phrase with a doubled inner space do not. No prefix, no initial, no `y`, no alias.
+ *
+ * **Everything that is not the phrase is a refusal, and that is the property the banner rests on.**
+ * An approval prompt grants only on an offered key and treats every other keystroke as a rejection;
+ * a text buffer inverts that by accumulating keystrokes instead of rejecting them, and a matcher
+ * this narrow is what puts it back — the buffer may hold anything at all, and only one value of it
+ * runs the command.
+ *
+ * Deliberately NOT whitespace-normalising the middle: a rule that repairs what the user typed is a
+ * rule that grants on something they did not type, and retyping a phrase costs nothing next to
+ * running this command by accident.
+ */
+export declare function grantsRunAnyway(typed: string): boolean;
+/**
+ * §6.1 — the banner's own words, shared so no surface invents its own.
+ *
+ * It carries what every surface must say and nothing about how any one of them is driven: the
+ * readline prompt reads a line in cooked mode and has no `q` or `Esc` to bind, so a keyboard line
+ * here would be false on one of the two surfaces. A surface adds its own keys beside these.
+ */
+export interface AttackBannerCopy {
+    /** The banner's title row — what happened, above everything else. */
+    title: string;
+    /** The `attack` heading from {@link describeRaterOutcome}, glyph and consequence included. */
+    heading: string;
+    /**
+     * **The irreversibility line, and it is UNCONDITIONAL** — on every attack banner, whatever the
+     * rating said, and not only where the command was also rated `catastrophic`.
+     *
+     * The banner is rare by construction (§4.1.1 forbids `attack` firing on ordinary work), so the
+     * line cannot become noise; and a static string cannot fail the way a model's explanation can. It
+     * is the last thing between a human and an action nothing else will stop.
+     */
+    irreversible: string;
+    /** What each control does, in the phrase's own words. */
+    controls: readonly string[];
+    /** The label a surface puts in front of the buffer the human types into. */
+    prompt: string;
+    /**
+     * What a surface says once the phrase has been accepted.
+     *
+     * It states the scope of what was just granted, because that is the half a user cannot observe:
+     * the command running is visible, and *only this one running* is not. Shared so neither surface
+     * can promise a persistence the runner does not perform.
+     */
+    granted: string;
+}
+/**
+ * §6.1 — the banner copy. A function rather than an exported object so one surface cannot mutate
+ * the strings another is about to paint.
+ */
+export declare function attackBannerCopy(): AttackBannerCopy;