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

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

@@ -0,0 +1,271 @@
+/**
+ * @module core/shell/approvalCapture
+ *
+ * [[TUI-C27]] — **what the approvals gate DID, recorded while it was doing it**, for the
+ * `/debug-dump` archive.
+ *
+ * ## The two gaps this exists to close
+ *
+ * 1. **An approval used to leave no trace at all.** A rejection is legible in a dump only as a
+ *    byproduct of the negotiation — the protocol has to hand the reason back to the agent, so it
+ *    lands in the transcript. An approval relays nothing to anyone: the tool simply runs. So the
+ *    archive was at its most detailed about the decisions that STOPPED something and silent about
+ *    the one decision that let something happen, which is exactly backwards for an incident review.
+ *    Everything here is written on both branches.
+ * 2. **Every field anyone had was a rater OUTPUT; its INPUT was never recorded.** Rung, outcome,
+ *    reason, which preflight, whether the floor fired — all of them describe what the rater
+ *    *answered*, and none records what it was *shown*. The question that actually failed in the
+ *    field — *"were the user's messages in view on round 2?"* — needs the input of an approving
+ *    round, the one combination the dump had neither half of.
+ *
+ * ## The one rule that shapes the whole module: CAPTURE, NEVER RE-RENDER
+ *
+ * {@link RaterCallCapture.prompt} holds the exact `{system, user}` strings handed to the model, taken
+ * inside `rateShellCommand` at the send site — not rebuilt afterwards from the state that produced
+ * them. A dump that can disagree with what actually happened is worse than no dump: it invites a
+ * confident wrong conclusion from the only evidence there is, which is the failure mode this node
+ * was filed over. The same rule is why {@link RaterCallCapture.rawResponse} keeps the model's answer
+ * *before* it is mapped to an outcome — a malformed or surprising answer stays visible rather than
+ * being smoothed into a verdict.
+ *
+ * ## The records are pushed EARLY and mutated in place, deliberately
+ *
+ * {@link ApprovalCaptureLog.begin} appends the record the moment a gated call arrives, and the gate
+ * fills fields in as they are decided. The alternative — assemble the whole record, push it at the
+ * end — loses exactly the events worth keeping: an `attack` verdict throws `AttackHaltError` out of
+ * the decision, so a run that halted would carry no record of the rating that halted it. Pushing
+ * first makes survival a property of the structure rather than of someone remembering to write the
+ * record before each `throw`.
+ *
+ * ## Redaction
+ *
+ * Nothing is redacted here. The archive writer routes this artifact through the SAME
+ * [[GS2-47]]/[[GS2-54]] pass as `transcript.json` and `model-messages.json`
+ * (`renderStructured` → `redactText`, over the literal secret values `collectSecretValues`
+ * harvested from env + config). Redacting twice, in two places, is how two policies come to exist.
+ */
+import type { ApprovalRung } from '#src/config.js';
+import type { ToolApprovalScope } from '#src/core/types.js';
+import type { AbstentionDefect } from '#src/core/shell/abstention.js';
+import type { NegotiationCounters } from '#src/core/shell/negotiation.js';
+import type { FailClosedCause, PreflightFloorKind, RaterNegotiationContext, RaterNegotiationRound, ShellSafetyVerdict } from '#src/core/shell/rater.js';
+/**
+ * How many gated decisions one session keeps. A ring buffer for the same reason the debug-log one
+ * is: each record carries a full rating prompt (a few KB), and a long `auto` session makes a lot of
+ * them. The newest are the ones a bug report is about, so the oldest are evicted.
+ */
+export declare const APPROVAL_CAPTURE_MAX = 50;
+/**
+ * **Which layer of the gate decided this call.** The diagnostic value of the whole record is
+ * precisely here: a bug report that says "escalated" does not distinguish a rater verdict from a
+ * floor match from a timeout from a deny-list hit, and those need four different answers.
+ *
+ * The names follow the numbered steps of `GthAgentRunner.decideToolApprovalInner`:
+ *
+ * - `not-gated` — the rung in force does not gate this tool at all.
+ * - `deny-list` — a declared `approvals.deny` entry, or an *always reject* the human chose earlier.
+ * - `bypass` — the gate is off for the session.
+ * - `hardline-floor` — §8's deterministic floor matched, before any rating or prompt.
+ * - `escalate-entry` — a declared `approvals.escalate` entry; a human answers, with no rating call.
+ * - `allow-list` — an allow entry settled it with no rating (`rate: false`, or an unrated rung).
+ * - `allow-tripwire` — an allow entry that kept the rater involved (§3.2's `rate: true`).
+ * - `rater` — the ordinary rating path.
+ * - `tool-open-world-floor` — §4.7.3's floor on a non-shell call whose effective `openWorldHint`
+ *   is true. No rater sees it while §4.3's scope boundary stands.
+ * - `unrated-rung` — nothing but the rung itself: `manual` and `write` consult no model, so a call
+ *   no rule claimed goes to the human on the rung's say-so. It is its own value rather than an
+ *   absent one, because "the rung requires a person" is an answer and a blank field reads as the
+ *   recorder having failed.
+ */
+export type ApprovalDecidingStage = 'not-gated' | 'deny-list' | 'bypass' | 'hardline-floor' | 'escalate-entry' | 'allow-list' | 'allow-tripwire' | 'rater' | 'tool-open-world-floor' | 'unrated-rung';
+/**
+ * What became of the call, as the agent experienced it. `error` is its own value rather than an
+ * absence: a decision that threw something other than a halt is a fact about the gate, and a record
+ * left with no action at all would read as one that never finished being written.
+ */
+export type ApprovalCaptureAction = 'approve' | 'reject' | 'escalate' | 'halt' | 'error';
+/** How an escalation ended once it reached (or failed to reach) a person. */
+export type ApprovalHumanAnswer = 'approve' | 'reject' | 'no-human';
+/**
+ * §5.1's negotiation context **as it was handed to the prompt builder**, plus the one distinction a
+ * reader of the archive keeps needing and could never make.
+ *
+ * **`userMessagesPopulated` is the field the node exists for.** Round 1 is context-free *by design*
+ * (§5.1: *"round 1 sees the command alone"*), so an empty window is not a bug — and a reader with no
+ * access to the source cannot know that. {@link userMessagesNote} states which case this is in
+ * words, so the answer to *"were the user's messages in view on round N?"* is one field and one
+ * sentence rather than a source-reading exercise across three files.
+ */
+export interface RaterNegotiationCapture {
+    /** 1-based index of this rating within the current negotiation. */
+    round: number;
+    /** Whether this rating was a round-1 (context-free) rating. */
+    roundOne: boolean;
+    /** Whether a §5.1 context was supplied at all (it is not, at a rung that does not negotiate). */
+    contextSupplied: boolean;
+    /** The justification admitted into THIS rating. Withheld at round 1 by `contextFor`, by design. */
+    justification?: string;
+    /** `<negotiation_so_far>` as handed over: the completed rounds, oldest first. */
+    priorRounds: RaterNegotiationRound[];
+    /** `<user_messages>` as handed over, oldest first, before the builder's last-5 + truncation. */
+    userMessages: string[];
+    /** Whether that window carried anything. THE distinction this facility turns on. */
+    userMessagesPopulated: boolean;
+    /** Why the window looks the way it does, in words, for a reader who has never seen the spec. */
+    userMessagesNote: string;
+}
+/**
+ * One rating call: what the rater was SHOWN and what it ANSWERED, captured at the send site.
+ *
+ * Every field is filled by `rateShellCommand` itself. `prompt` is set before the call and the rest
+ * as the answer arrives, so a rater that never answers still leaves a record of what it was asked.
+ */
+export interface RaterCallCapture {
+    /** ISO timestamp of the moment the call was sent. */
+    at: string;
+    /** Wall-clock ms the call took, once it has returned (or timed out). */
+    durationMs?: number;
+    /** The rater model's own label — an id and a provider type, never the instance. */
+    model?: string;
+    /** `approvals.rater` — the identity profile the rater model came from, when one is configured. */
+    profile?: string;
+    /** The budget this call was raced against ([[EXT-66]]). */
+    timeoutMs: number;
+    /** §5.2 — whether a rejection would be handed back to the AGENT rather than to a person. */
+    negotiable: boolean;
+    /** **The exact strings sent.** Captured, never re-rendered. */
+    prompt: {
+        system: string;
+        user: string;
+    };
+    /** What the negotiation looked like at the moment of this call. */
+    negotiation: RaterNegotiationCapture;
+    /** The model's answer BEFORE it is parsed or mapped, so a malformed one stays visible. */
+    rawResponse?: unknown;
+    /** The verdict this call resolved to, including a fail-closed one. */
+    verdict?: ShellSafetyVerdict;
+    /** Set when the verdict is the gate failing closed rather than the model judging ([[EXT-66]]). */
+    failClosed?: FailClosedCause;
+}
+/** A declared entry or runtime grant that decided the call, rendered as the user would read it. */
+export interface ApprovalRuleMatchCapture {
+    action: 'allow' | 'deny' | 'escalate';
+    /** The entry in the words the menu and the notices use (`describeApprovalEntry`). */
+    entry: string;
+    /** §3.2 — whether an allow entry kept the rater involved as a tripwire. */
+    rate?: boolean;
+}
+/**
+ * §8's deterministic floor, when it matched.
+ *
+ * **This block NAMES THE MATCHED PATTERN, and that is a decision taken rather than an oversight.**
+ * §8.1 says the floor is never advertised, and [[CFG-31]] binds user-facing rung copy to that rule.
+ * The resolution taken for [[TUI-C27]] is that §8.1 governs **rung descriptions and promotional
+ * copy** — text that invites a user to feel safe — and not a diagnostic archive a user opens about
+ * their own session. "A floor matched" without saying which one leaves nobody able to act on it;
+ * the refusal the *user* sees ({@link import('./hardline.js').buildHardlineRefusal}) is unchanged
+ * and still names only the description.
+ */
+export interface HardlineFloorCapture {
+    /** The human-readable description, as the refusal message carries it. */
+    description: string;
+    /** The matched pattern's source, or the stable token of the non-pattern arm. */
+    pattern: string;
+}
+/** A deterministic preflight finding, and whether it actually rewrote the rater's outcome. */
+export interface PreflightFloorCapture {
+    kind: PreflightFloorKind;
+    reason: string;
+    /**
+     * Whether the floor changed the outcome. A preflight only ever RAISES, and only `safe` sits below
+     * the floor — so a finding on a `destructive` verdict is the floor AGREEING with the rater, not
+     * overriding it, and reporting those two the same way would misattribute the decision.
+     */
+    rewroteRating: boolean;
+}
+/** One gated tool call, from arrival to outcome. */
+export interface ApprovalDecisionCapture {
+    /** ISO timestamp of the moment the call arrived at the gate. */
+    at: string;
+    /** The tool that was called. */
+    tool: string;
+    /** The command, for a `run_shell_command` call whose argument was a readable string. */
+    command?: string;
+    /** The rung in force for THIS decision (`/approvals <rung>` moves it mid-session). */
+    rung: ApprovalRung;
+    /** The stage that decided. `undefined` only if the decision threw before reaching one. */
+    stage?: ApprovalDecidingStage;
+    /** What became of the call. Always set by the time the decision returns or throws. */
+    action?: ApprovalCaptureAction;
+    /** The scope an approval was granted at, when one was. */
+    scope?: ToolApprovalScope;
+    /** Whether a person was actually asked, and what they said. */
+    humanAnswer?: ApprovalHumanAnswer;
+    /** §8's floor, when it matched. */
+    hardline?: HardlineFloorCapture;
+    /** The declared entry or runtime grant that decided the call, when one did. */
+    ruleMatch?: ApprovalRuleMatchCapture;
+    /** The deterministic preflight finding on this command, when there was one. */
+    preflight?: PreflightFloorCapture;
+    /**
+     * [[EXT-81]] — whether the gate's own parser could not statically resolve the command, so the
+     * rating carried a neutral note about the shape it saw.
+     *
+     * **This is what remains of "was the call an ABSTAIN".** `abstain` was an ACTION of its own until
+     * [[EXT-81]] retired it: a parser reporting that it could not read a string has detected nothing,
+     * so it no longer earns an action, and the command is now rated like any other. The observable
+     * that survived is this shape report, and the budget position that used to accompany it is
+     * {@link budget}.
+     */
+    parserUnresolved?: AbstentionDefect;
+    /** Where this call sat in §5.3's consecutive bound and the reachability bound, on arrival. */
+    budget: NegotiationCounters;
+    /** The rating, when one was made. Absent for every stage that decided without a model. */
+    rating?: RaterCallCapture;
+    /** The error that ended the decision, when one did. */
+    error?: string;
+}
+/**
+ * The per-session log of gated decisions.
+ *
+ * **Instance-scoped, on the runner, and never a module singleton** — the same reason
+ * `ShellNegotiationState` and the grant stores are: a concurrent ACP / AG-UI session must not
+ * inherit another session's approvals history, and a dump taken in one must not describe the other.
+ */
+export declare class ApprovalCaptureLog {
+    private records;
+    /**
+     * Open a record for a gated call and return it LIVE, already in the buffer.
+     *
+     * The caller mutates the returned object as the decision is made. See the module docblock for why
+     * the push happens here rather than at the end: a halt throws out of the decision, and a record
+     * assembled at the end would be lost on exactly the calls most worth keeping.
+     */
+    begin(record: ApprovalDecisionCapture): ApprovalDecisionCapture;
+    /**
+     * The records so far, oldest first. A copy of the ARRAY: the records themselves are handed over
+     * live, because a decision still in flight is one the archive should show as it stands rather
+     * than not at all.
+     */
+    snapshot(): ApprovalDecisionCapture[];
+    /** Drop everything — the TUI's `/clear` rotates the thread. */
+    clear(): void;
+}
+/**
+ * A short, KEY-FREE label for the rater model: its id and its provider type, and nothing else.
+ *
+ * Deliberately not a param dump. A live `BaseChatModel` carries an `apiKey` and a client instance,
+ * and this string goes into an archive people attach to bug reports — so it reads a fixed handful of
+ * scalar fields through guards, exactly as `debugDump`'s own live-model descriptor does, rather than
+ * serialising anything of the instance.
+ */
+export declare function raterModelLabel(model: unknown): string | undefined;
+/**
+ * Describe the §5.1 context a rating is about to be made with — **as it was handed to the prompt
+ * builder**, so the record and the prompt cannot come to describe two different ratings.
+ *
+ * The note is the legibility half of the acceptance: an empty user-messages window means one thing
+ * at round 1 (by design) and something else entirely at round 3, and a reader of the archive has no
+ * way to tell them apart from a `[]`.
+ */
+export declare function describeRaterNegotiation(negotiation: RaterNegotiationContext | undefined): RaterNegotiationCapture;

package/dist/core/shell/approvalCapture.js

@@ -0,0 +1,108 @@
+/**
+ * How many gated decisions one session keeps. A ring buffer for the same reason the debug-log one
+ * is: each record carries a full rating prompt (a few KB), and a long `auto` session makes a lot of
+ * them. The newest are the ones a bug report is about, so the oldest are evicted.
+ */
+export const APPROVAL_CAPTURE_MAX = 50;
+/**
+ * The per-session log of gated decisions.
+ *
+ * **Instance-scoped, on the runner, and never a module singleton** — the same reason
+ * `ShellNegotiationState` and the grant stores are: a concurrent ACP / AG-UI session must not
+ * inherit another session's approvals history, and a dump taken in one must not describe the other.
+ */
+export class ApprovalCaptureLog {
+    records = [];
+    /**
+     * Open a record for a gated call and return it LIVE, already in the buffer.
+     *
+     * The caller mutates the returned object as the decision is made. See the module docblock for why
+     * the push happens here rather than at the end: a halt throws out of the decision, and a record
+     * assembled at the end would be lost on exactly the calls most worth keeping.
+     */
+    begin(record) {
+        this.records.push(record);
+        if (this.records.length > APPROVAL_CAPTURE_MAX)
+            this.records.shift();
+        return record;
+    }
+    /**
+     * The records so far, oldest first. A copy of the ARRAY: the records themselves are handed over
+     * live, because a decision still in flight is one the archive should show as it stands rather
+     * than not at all.
+     */
+    snapshot() {
+        return [...this.records];
+    }
+    /** Drop everything — the TUI's `/clear` rotates the thread. */
+    clear() {
+        this.records = [];
+    }
+}
+/**
+ * A short, KEY-FREE label for the rater model: its id and its provider type, and nothing else.
+ *
+ * Deliberately not a param dump. A live `BaseChatModel` carries an `apiKey` and a client instance,
+ * and this string goes into an archive people attach to bug reports — so it reads a fixed handful of
+ * scalar fields through guards, exactly as `debugDump`'s own live-model descriptor does, rather than
+ * serialising anything of the instance.
+ */
+export function raterModelLabel(model) {
+    if (!model || typeof model !== 'object')
+        return undefined;
+    const m = model;
+    let type;
+    try {
+        type = typeof m._llmType === 'function' ? m._llmType() : undefined;
+    }
+    catch {
+        type = undefined;
+    }
+    const id = [m.model, m.modelName, m.modelId].find((value) => typeof value === 'string');
+    if (id && type)
+        return `${type}/${id}`;
+    return id ?? type;
+}
+/**
+ * Describe the §5.1 context a rating is about to be made with — **as it was handed to the prompt
+ * builder**, so the record and the prompt cannot come to describe two different ratings.
+ *
+ * The note is the legibility half of the acceptance: an empty user-messages window means one thing
+ * at round 1 (by design) and something else entirely at round 3, and a reader of the archive has no
+ * way to tell them apart from a `[]`.
+ */
+export function describeRaterNegotiation(negotiation) {
+    const priorRounds = [...(negotiation?.priorRounds ?? [])];
+    const userMessages = [...(negotiation?.userMessages ?? [])];
+    const roundOne = priorRounds.length === 0;
+    const populated = userMessages.length > 0;
+    return {
+        round: priorRounds.length + 1,
+        roundOne,
+        contextSupplied: negotiation !== undefined,
+        ...(negotiation?.justification !== undefined
+            ? { justification: negotiation.justification }
+            : {}),
+        priorRounds,
+        userMessages,
+        userMessagesPopulated: populated,
+        userMessagesNote: userMessagesNote(negotiation !== undefined, roundOne, populated),
+    };
+}
+/** The sentence {@link describeRaterNegotiation} puts on the window, for a reader with no spec. */
+function userMessagesNote(contextSupplied, roundOne, populated) {
+    if (!contextSupplied) {
+        return ('No negotiation context was supplied for this rating (the rung does not negotiate, or this ' +
+            'was the allow-list tripwire), so the rater saw the command alone. An empty window here is ' +
+            'not a defect.');
+    }
+    if (roundOne) {
+        return ('Round 1: spec §5.1 admits no justification, no transcript and no user messages, so the ' +
+            'rater saw the command alone. An empty window here is BY DESIGN, not a defect.');
+    }
+    return populated
+        ? "Round 2 or later: the user's own recent messages WERE in the rater's view for this rating."
+        : 'Round 2 or later, and the window is still empty — the conversation had no non-blank user ' +
+            'message to admit. This one IS worth looking at.';
+}
+//# sourceMappingURL=approvalCapture.js.map

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

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

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

@@ -0,0 +1,123 @@
+/**
+ * One piece of a stop message, tagged with who wrote it.
+ *
+ * - `own` — this module's own sentence. Nothing outside it can influence the text, so a surface
+ *   may paint it as it is and let the terminal wrap it.
+ * - `command` — the command the agent proposed. Framed with the site extraction, because its
+ *   composition boundaries and substitutions are the decision-relevant positions in it.
+ * - `value` — one untrusted single value (the rater's outcome or reason, the matched
+ *   `approvals.escalate` entry). Framed as prose; there are no sites to point at.
+ * - `block` — an untrusted block whose LINE STRUCTURE is a renderer's, not the model's: the §5
+ *   negotiation transcript, whose rows `core/shell/negotiation` builds and whose leaves it has
+ *   already collapsed to one line each. Its breaks survive into the message where a `value`'s
+ *   would be escaped, because they are the thing that makes it readable at all.
+ *
+ * **A `block` is still neutralised line by line here, and that is deliberate defence in depth.**
+ * Its one production producer (`renderNegotiationTranscript`) has already cleaned every leaf, so
+ * on today's paths this arm changes nothing — but these constructors are public, and a caller
+ * handing one a raw multi-line string must not be the thing that decides whether a cursor can
+ * move. `approvalStop.spec.ts` builds exactly that string so the arm is falsifiable rather than
+ * merely reassuring.
+ *
+ * **The §5.4 VOICE distinction is deliberately not carried here**, and the trade is worth stating
+ * because `negotiation.ts` documents voice preservation as a rule: `renderNegotiationRows` tags
+ * each row `chrome`/`agent`/`rater` so a surface can colour the rater's turns apart from the
+ * agent's. A stop renders the transcript as one undifferentiated untrusted block instead. Framing
+ * a mixed-trust block wholly as untrusted is the safe direction (nothing in it is promoted to the
+ * gate's own voice), the row prefixes still name the speaker in text, and an `Error` carries no
+ * colour to any of the non-terminal consumers anyway. Colouring by voice here would mean
+ * re-deriving the tags from a string that no longer has them.
+ */
+export type ApprovalStopPart = {
+    kind: 'own';
+    text: string;
+} | {
+    kind: 'command';
+    label: string;
+    text: string;
+} | {
+    kind: 'value';
+    label: string;
+    text: string;
+} | {
+    kind: 'block';
+    text: string;
+};
+/**
+ * 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 declare function approvalStopRows(parts: readonly ApprovalStopPart[], options?: {
+    columns?: number;
+}): string[];
+/**
+ * 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 declare abstract class ApprovalStopError extends Error {
+    /** The command that ended the run, exactly as the agent proposed it. */
+    readonly command: string;
+    /** The message's pieces, tagged with who wrote each — see {@link ApprovalStopPart}. */
+    readonly parts: readonly ApprovalStopPart[];
+    protected constructor(parts: readonly ApprovalStopPart[], command: string);
+}
+/**
+ * §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 declare class AttackHaltError extends ApprovalStopError {
+    /** The rater's explanation of what the command's structure showed. */
+    readonly reason: string;
+    constructor(command: string, reason: string);
+}
+/**
+ * §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 declare class NonInteractiveEscalationError extends ApprovalStopError {
+    /** The rater's outcome, when a rating existed (the unrated rungs have none). */
+    readonly outcome: string | undefined;
+    /** The rater's explanation, when a rating existed. */
+    readonly reason: string | undefined;
+    /**
+     * 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`.
+     */
+    readonly escalatedBy: string | undefined;
+    /**
+     * [[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.
+     */
+    readonly negotiation: string | undefined;
+    constructor(command: string, outcome?: string, reason?: string, escalatedBy?: string, negotiation?: string);
+}