@aragon-agent/cli 0.5.12 → 0.6.1

package/dist/exec/options.js

@@ -0,0 +1,221 @@
+/**
+ * `aragon exec` option resolution (cli-integration-surface section 4.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * PURE. Every branch here is a decision about the FLAGS, never about the world:
+ * no file is read, no session is resolved, no stdin is consumed. Prompt
+ * resolution and file reads live in `exec/index.ts`, which is the module allowed
+ * to touch the process.
+ *
+ * A USAGE ERROR IS EXIT 2 AND NOTHING ON STDOUT. That is the whole reason this
+ * module returns a discriminated union instead of throwing: `--output-format
+ * json` promises exactly one JSON object on stdout, and a stack trace or a
+ * half-written event would corrupt every consumer. The caller writes the message
+ * to stderr and exits.
+ */
+import { HOST_TOOL_NAMES } from '../tools/index.js';
+import { isValidSessionId } from '../session/store.js';
+const OUTPUT_FORMATS = ['text', 'json', 'stream-json'];
+const INPUT_FORMATS = ['text', 'stream-json'];
+const PERMISSION_MODES = ['auto', 'plan', 'strict'];
+/**
+ * Registered nowhere in a headless session, yet real names (P2-2).
+ *
+ * `planTools` is empty under `exec`, so `--allow-tool ask_user` validates and
+ * then does nothing. REJECTING IT WOULD BE WRONG - `HOST_TOOL_NAMES` answers
+ * "can this declaration ever take effect?", and the answer for these two is yes,
+ * just not here - so exec accepts it and says one line on stderr.
+ */
+const NEVER_REGISTERED_HEADLESS = ['ask_user', 'submit_plan'];
+/**
+ * Flags that need to observe or interrupt the stream `runHeadless` owns, and are
+ * therefore REFUSED under `--output-format text` (D-1).
+ *
+ * The refusal is explicit and names both the flag and the format, never a silent
+ * no-op: text mode delegates to `runHeadless` VERBATIM, which is what makes
+ * "the human CLI is unchanged" a fact anyone can check rather than an argument
+ * someone has to trust. Session flags are absent from this list on purpose -
+ * save and resume happen OUTSIDE the run, so they work in every format.
+ */
+const TEXT_MODE_REFUSED = [
+    { flag: '--max-turns', test: (o) => o.maxTurns !== undefined },
+    {
+        flag: '--max-duration',
+        test: (o) => o.maxDuration !== undefined || o.timeout !== undefined,
+    },
+    { flag: '--input-format stream-json', test: (o) => o.inputFormat === 'stream-json' },
+    { flag: '--partial-messages', test: (o) => o.partialMessages === true },
+    { flag: '--include-thinking', test: (o) => o.includeThinking === true },
+];
+function usage(code, message) {
+    return { ok: false, code, message };
+}
+/** Accept both `--allow-tool a --allow-tool b` and `--allow-tool a,b`. */
+function splitNames(values) {
+    if (!values)
+        return [];
+    const out = [];
+    for (const value of values) {
+        for (const part of value.split(',')) {
+            const name = part.trim();
+            if (name.length > 0 && !out.includes(name))
+                out.push(name);
+        }
+    }
+    return out;
+}
+function parsePositiveInt(raw) {
+    if (!/^\d+$/.test(raw.trim()))
+        return null;
+    const n = Number.parseInt(raw.trim(), 10);
+    return Number.isSafeInteger(n) ? n : null;
+}
+export function resolveExecOptions(raw) {
+    if (raw.print) {
+        return usage('print_not_supported', '`aragon exec` is already the headless face; `-p/--print` is not accepted here. ' +
+            'Use `aragon exec --output-format text` for the same stdout as `aragon -p`.');
+    }
+    const outputFormat = (raw.outputFormat ?? 'text').trim();
+    if (!OUTPUT_FORMATS.includes(outputFormat)) {
+        return usage('invalid_output_format', `Unknown --output-format "${outputFormat}". Choose: ${OUTPUT_FORMATS.join(', ')}.`);
+    }
+    const inputFormat = (raw.inputFormat ?? 'text').trim();
+    if (!INPUT_FORMATS.includes(inputFormat)) {
+        return usage('invalid_input_format', `Unknown --input-format "${inputFormat}". Choose: ${INPUT_FORMATS.join(', ')}.`);
+    }
+    if (inputFormat === 'stream-json' && outputFormat !== 'stream-json') {
+        return usage('input_format_requires_stream_json', '--input-format stream-json requires --output-format stream-json.');
+    }
+    const formatError = checkFormatCompatibility(raw, outputFormat);
+    if (formatError)
+        return formatError;
+    const permissionMode = (raw.permissionMode ?? 'auto').trim();
+    if (!PERMISSION_MODES.includes(permissionMode)) {
+        return usage('invalid_permission_mode', `Unknown --permission-mode "${permissionMode}". Choose: ${PERMISSION_MODES.join(', ')}.`);
+    }
+    const budgets = resolveBudgets(raw);
+    if (!budgets.ok)
+        return budgets.error;
+    const sessionError = checkSessionFlags(raw);
+    if (sessionError)
+        return sessionError;
+    const allowTools = splitNames(raw.allowTool);
+    const denyTools = splitNames(raw.denyTool);
+    const toolError = checkToolNames([...allowTools, ...denyTools]);
+    if (toolError)
+        return toolError;
+    const warnings = [];
+    for (const name of allowTools) {
+        if (NEVER_REGISTERED_HEADLESS.includes(name)) {
+            warnings.push(`--allow-tool ${name}: that tool is never registered in a headless run, so allowing it has no effect.`);
+        }
+    }
+    return {
+        ok: true,
+        options: {
+            outputFormat: outputFormat,
+            inputFormat: inputFormat,
+            partialMessages: raw.partialMessages === true,
+            includeThinking: raw.includeThinking === true,
+            ...(raw.promptFile ? { promptFile: raw.promptFile } : {}),
+            ...(raw.sessionId ? { sessionId: raw.sessionId.trim() } : {}),
+            ...(raw.resume ? { resume: raw.resume.trim() } : {}),
+            continueSession: raw.continue === true,
+            // `--no-save-session` is the only way this becomes `false`; commander
+            // leaves it `undefined` when the flag is absent.
+            saveSession: raw.saveSession !== false,
+            ...(budgets.maxTurns !== undefined ? { maxTurns: budgets.maxTurns } : {}),
+            ...(budgets.maxDurationMs !== undefined ? { maxDurationMs: budgets.maxDurationMs } : {}),
+            permissionMode: permissionMode,
+            allowTools,
+            denyTools,
+            ...(raw.appendSystemPrompt ? { appendSystemPrompt: raw.appendSystemPrompt } : {}),
+            ...(raw.appendSystemPromptFile
+                ? { appendSystemPromptFile: raw.appendSystemPromptFile }
+                : {}),
+            quiet: raw.quiet === true,
+            warnings,
+        },
+    };
+}
+/** Split out so `resolveExecOptions` stays under this package's size ceiling. */
+function checkFormatCompatibility(raw, outputFormat) {
+    if (outputFormat === 'text') {
+        for (const { flag, test } of TEXT_MODE_REFUSED) {
+            if (!test(raw))
+                continue;
+            return usage('unsupported_in_text_mode', `${flag} is not supported with --output-format text (text mode delegates to the ` +
+                'same renderer as `aragon -p`). Use --output-format json or stream-json.');
+        }
+        return null;
+    }
+    if (outputFormat === 'json') {
+        if (raw.partialMessages === true) {
+            return usage('stream_only_flag', '--partial-messages requires --output-format stream-json.');
+        }
+        if (raw.includeThinking === true) {
+            return usage('stream_only_flag', '--include-thinking requires --output-format stream-json.');
+        }
+    }
+    return null;
+}
+function resolveBudgets(raw) {
+    let maxTurns;
+    if (raw.maxTurns !== undefined) {
+        const parsed = parsePositiveInt(raw.maxTurns);
+        if (parsed === null || parsed < 1) {
+            return { ok: false, error: usage('invalid_max_turns', '--max-turns must be an integer >= 1.') };
+        }
+        maxTurns = parsed;
+    }
+    let maxDurationMs;
+    // `--max-duration` wins over the hidden `--timeout` alias when a caller passes
+    // both; the alias exists so a guess is not punished, not so it can disagree.
+    const durationRaw = raw.maxDuration ?? raw.timeout;
+    if (durationRaw !== undefined) {
+        const parsed = parsePositiveInt(durationRaw);
+        if (parsed === null || parsed < 1000) {
+            return {
+                ok: false,
+                error: usage('invalid_max_duration', '--max-duration must be an integer >= 1000 (milliseconds).'),
+            };
+        }
+        maxDurationMs = parsed;
+    }
+    return {
+        ok: true,
+        ...(maxTurns !== undefined ? { maxTurns } : {}),
+        ...(maxDurationMs !== undefined ? { maxDurationMs } : {}),
+    };
+}
+function checkSessionFlags(raw) {
+    if (raw.sessionId !== undefined) {
+        const id = raw.sessionId.trim();
+        if (!isValidSessionId(id)) {
+            return usage('invalid_session_id', `Invalid --session-id "${raw.sessionId}". Use 1-64 characters matching ` +
+                '[A-Za-z0-9][A-Za-z0-9._-]* (no "/", "\\", ".." or a leading dot).');
+        }
+    }
+    const chosen = [
+        raw.sessionId !== undefined ? '--session-id' : null,
+        raw.resume !== undefined ? '--resume' : null,
+        raw.continue === true ? '--continue' : null,
+    ].filter((flag) => flag !== null);
+    if (chosen.length > 1) {
+        return usage('session_flag_conflict', `Pass only one of ${chosen.join(', ')}: they are three different answers to ` +
+            '"which session is this".');
+    }
+    return null;
+}
+function checkToolNames(names) {
+    const known = new Set(HOST_TOOL_NAMES);
+    for (const name of names) {
+        if (known.has(name))
+            continue;
+        // A typo that silently allows nothing is exactly the failure this feature
+        // exists to prevent, so the valid set is printed rather than hinted at.
+        return usage('unknown_tool', `Unknown tool "${name}". Valid names: ${[...HOST_TOOL_NAMES].join(', ')}.`);
+    }
+    return null;
+}

package/dist/exec/permission.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The non-interactive tool-permission policy (cli-integration-surface section
+ * 4.2 / 5.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * PURE. No I/O, no process access. The only import is the comm-tool name set,
+ * for the reason invariant 4 records below.
+ *
+ * TWO ORTHOGONAL CONTROLS, EACH WITH EXACTLY ONE MEANING:
+ *
+ *   `--permission-mode`  selects the BASELINE  (`auto` everything, `plan`
+ *                        everything, `strict` nothing)
+ *   `--allow-tool`       ADDS to the baseline
+ *   `--deny-tool`        REMOVES, and wins over allow
+ *
+ * `plan` CONTRIBUTES NOTHING TO THE FILTER, and getting that wrong was P0-2.
+ * `--plan` does not unregister the five in `PLAN_MODE_BLOCKED_TOOLS`:
+ * `tools/index.ts::withPlanModeGate` wraps every tool and returns
+ * `planRefusal(name)` for those five AT CALL TIME, so they stay in
+ * `listTools()`. Unregistering them here instead would (a) make AC-15
+ * unsatisfiable - it compares the registered set against `-p --plan` name by
+ * name, (b) make `system/init.tools` disagree between two spellings of one mode,
+ * and (c) cost the model the refusal text that steers it to `submit_plan`. In
+ * plan mode the point is that the model KNOWS the write exists and is being
+ * deferred; for a deny list the point is the opposite (D-4).
+ */
+export type PermissionMode = 'auto' | 'plan' | 'strict';
+export interface ToolPermission {
+    mode: PermissionMode;
+    allow: ReadonlySet<string>;
+    deny: ReadonlySet<string>;
+    /** Resolved per tool array; the only method the tool factory calls. */
+    isAllowed(tool: string): boolean;
+}
+export interface ResolvePermissionInput {
+    mode: PermissionMode;
+    allow: readonly string[];
+    deny: readonly string[];
+}
+/**
+ * The whole policy as a pure set operation over a REGISTERED list.
+ *
+ * Exported for the unit test and for anything that wants to describe the policy
+ * without building tools. The runtime path goes through `isAllowed` instead,
+ * because `createBuiltinTools` filters the array it is in the middle of
+ * assembling and has no "registered list" to hand over.
+ */
+export declare function resolveToolAllowList(registered: readonly string[], mode: PermissionMode, allow: readonly string[], deny: readonly string[]): ReadonlySet<string>;
+/**
+ * Build the object the tool factory receives, or `undefined` when the policy is
+ * a no-op.
+ *
+ * RETURNING `undefined` IS WHAT MAKES SECTION 4.2 INVARIANT 2 HOLD BY
+ * CONSTRUCTION RATHER THAN BY CARE (P1-2). With no `permission` key in the
+ * options bag, `createBuiltinTools` never enters its filter branch and returns
+ * the same tool OBJECTS it does today - which is what AC-28 asserts by identity,
+ * the discipline `AC-G17` already applies to `--no-skills`.
+ *
+ * `strict` always produces an object, even with empty lists: an empty allow list
+ * under `strict` means "no tools at all", which is a real posture and not an
+ * absence of one. `auto` and `plan` with no lists produce nothing, and that
+ * covers every existing path plus the documented `--permission-mode plan`
+ * alias of `-p --plan`.
+ */
+export declare function resolvePermission(input: ResolvePermissionInput): ToolPermission | undefined;

package/dist/exec/permission.js

@@ -0,0 +1,96 @@
+/**
+ * The non-interactive tool-permission policy (cli-integration-surface section
+ * 4.2 / 5.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * PURE. No I/O, no process access. The only import is the comm-tool name set,
+ * for the reason invariant 4 records below.
+ *
+ * TWO ORTHOGONAL CONTROLS, EACH WITH EXACTLY ONE MEANING:
+ *
+ *   `--permission-mode`  selects the BASELINE  (`auto` everything, `plan`
+ *                        everything, `strict` nothing)
+ *   `--allow-tool`       ADDS to the baseline
+ *   `--deny-tool`        REMOVES, and wins over allow
+ *
+ * `plan` CONTRIBUTES NOTHING TO THE FILTER, and getting that wrong was P0-2.
+ * `--plan` does not unregister the five in `PLAN_MODE_BLOCKED_TOOLS`:
+ * `tools/index.ts::withPlanModeGate` wraps every tool and returns
+ * `planRefusal(name)` for those five AT CALL TIME, so they stay in
+ * `listTools()`. Unregistering them here instead would (a) make AC-15
+ * unsatisfiable - it compares the registered set against `-p --plan` name by
+ * name, (b) make `system/init.tools` disagree between two spellings of one mode,
+ * and (c) cost the model the refusal text that steers it to `submit_plan`. In
+ * plan mode the point is that the model KNOWS the write exists and is being
+ * deferred; for a deny list the point is the opposite (D-4).
+ */
+import { TEAM_SUBAGENT_TOOL_NAMES } from '../team/limits.js';
+/**
+ * Whether a single name survives the policy.
+ *
+ * `TEAM_SUBAGENT_TOOL_NAMES` IS ALWAYS ALLOWED (invariant 4 / P1-3).
+ * `team_send` / `team_wait` are registered only on CHILDREN and are the
+ * mechanism children use to coordinate; filtering them out of a `strict` run
+ * would break subagent messaging in a way that reads as a hang - a child waiting
+ * for mail that can never arrive.
+ *
+ * The set is IMPORTED, not restated. v1 proposed a new `EXEC_POLICY_EXEMPT`
+ * beside `SKILL_TOOL_FLOOR`; that would be a second list of the same two names
+ * (the drift `tools/index.ts` keeps its two sets adjacent to avoid) AND a third
+ * meaning for one word, since `policyExempt` already means "skips the CEILING
+ * wrapper only, never the plan gate, never confirmation".
+ */
+function decide(input, tool) {
+    if (TEAM_SUBAGENT_TOOL_NAMES.has(tool))
+        return true;
+    // Deny wins, unconditionally and first. A caller who names one tool in both
+    // lists gets the safe reading, and a wrapper that concatenates two config
+    // fragments cannot accidentally re-enable something the outer one removed.
+    if (input.deny.includes(tool))
+        return false;
+    if (input.mode === 'strict')
+        return input.allow.includes(tool);
+    return true;
+}
+/**
+ * The whole policy as a pure set operation over a REGISTERED list.
+ *
+ * Exported for the unit test and for anything that wants to describe the policy
+ * without building tools. The runtime path goes through `isAllowed` instead,
+ * because `createBuiltinTools` filters the array it is in the middle of
+ * assembling and has no "registered list" to hand over.
+ */
+export function resolveToolAllowList(registered, mode, allow, deny) {
+    const input = { mode, allow, deny };
+    return new Set(registered.filter((name) => decide(input, name)));
+}
+/**
+ * Build the object the tool factory receives, or `undefined` when the policy is
+ * a no-op.
+ *
+ * RETURNING `undefined` IS WHAT MAKES SECTION 4.2 INVARIANT 2 HOLD BY
+ * CONSTRUCTION RATHER THAN BY CARE (P1-2). With no `permission` key in the
+ * options bag, `createBuiltinTools` never enters its filter branch and returns
+ * the same tool OBJECTS it does today - which is what AC-28 asserts by identity,
+ * the discipline `AC-G17` already applies to `--no-skills`.
+ *
+ * `strict` always produces an object, even with empty lists: an empty allow list
+ * under `strict` means "no tools at all", which is a real posture and not an
+ * absence of one. `auto` and `plan` with no lists produce nothing, and that
+ * covers every existing path plus the documented `--permission-mode plan`
+ * alias of `-p --plan`.
+ */
+export function resolvePermission(input) {
+    if (input.mode !== 'strict' && input.allow.length === 0 && input.deny.length === 0) {
+        return undefined;
+    }
+    const allow = new Set(input.allow);
+    const deny = new Set(input.deny);
+    return {
+        mode: input.mode,
+        allow,
+        deny,
+        isAllowed: (tool) => decide(input, tool),
+    };
+}

package/dist/exec/runner.d.ts

@@ -0,0 +1,204 @@
+/**
+ * Stream translation, budgets and interrupts for `aragon exec`
+ * (cli-integration-surface section 3.3 / 3.5 / 3.6).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * IT NEVER TOUCHES STDOUT. Everything it wants to say goes through the
+ * `ExecEmitter` it was handed, which is the only object in this feature that
+ * holds a stdout stream (R-2). The one exception is `stderr`, used for the
+ * caller-facing notices `-p` already writes there.
+ *
+ * IT DOES NOT EMIT `result` EITHER, and that is deliberate (D-2). `run()`
+ * RETURNS the parameters; `exec/index.ts` persists the session first and emits
+ * second, because a caller that reads `result` and immediately respawns with the
+ * same `--session-id` must not race the writer of the file it is about to read.
+ */
+import type { TokenUsage } from '@aragon-agent/core';
+import type { HeadlessController } from '../agent/headless.js';
+import { type FollowThroughMode } from '../todo/follow-through.js';
+import type { ExecEmitter } from './emitter.js';
+import type { ExecStopReason } from './events.js';
+/**
+ * The controller surface the runner needs.
+ *
+ * IT EXTENDS `HeadlessController` RATHER THAN NAMING `AgentController`, for the
+ * reason that interface records about itself: it is deliberately minimal so a
+ * test can satisfy it with an OBJECT LITERAL. `abort` is required here and not
+ * there because a budget with no way to stop the run is not a budget.
+ */
+export interface ExecRunnerController extends HeadlessController {
+    abort(): void;
+    /** `cost.known` (P2-3). Optional so a stub need not model pricing. */
+    isPricedModel?(ref: {
+        providerId: string;
+        modelId: string;
+    }): boolean;
+}
+/** Where the caller's messages come from. One turn, or an NDJSON stdin stream. */
+export interface ExecPromptSource {
+    /** The next caller message, or `null` when the caller is done. */
+    next(): Promise<string | null>;
+}
+export declare function singlePrompt(text: string): ExecPromptSource;
+/** Replaceable so a unit test can assert the mechanism, not just the outcome. */
+export interface ExecSignalPort {
+    setTerminator(fn: (signo: number) => void): void;
+    exit(code: number): void;
+}
+export interface ExecRunnerOptions {
+    emitter: ExecEmitter;
+    sessionId: string;
+    maxTurns?: number;
+    maxDurationMs?: number;
+    partialMessages?: boolean;
+    includeThinking?: boolean;
+    followThrough?: FollowThroughMode;
+    quiet?: boolean;
+    stderr?: NodeJS.WritableStream;
+    now?: () => number;
+    signals?: ExecSignalPort;
+    /** Turns already spent by earlier invocations of a resumed session. */
+    priorTurns?: number;
+}
+export interface ExecRunStats {
+    turns: number;
+    usage: TokenUsage;
+    lastAssistantText: string;
+    errored: boolean;
+    stopReason: ExecStopReason;
+    errorCode: string | null;
+    errorMessage: string | null;
+    signalNumber: number | null;
+}
+export declare class ExecRunner {
+    private readonly emitter;
+    private readonly sessionId;
+    private readonly opts;
+    private readonly signals;
+    private readonly now;
+    private controller;
+    private unsubscribers;
+    private turns;
+    private readonly usage;
+    private lastAssistantText;
+    private errored;
+    private sawTurnEnd;
+    private stopReason;
+    private errorCode;
+    private errorMessage;
+    private signalNumber;
+    private thinkingBuffer;
+    private budgetTimer;
+    private timerStarted;
+    private detached;
+    private lastSignalAt;
+    constructor(options: ExecRunnerOptions);
+    /**
+     * Subscribe to all four streams.
+     *
+     * TEXT MODE CALLS THIS TOO, WITH A `TextEmitter` THAT WRITES NOTHING (section
+     * 3.2). The listener is what counts `turn_end` and accumulates usage for
+     * `SessionMeta`; byte-equality with `runHeadless` is a property of what is
+     * WRITTEN, not of how many listeners exist, and `runHeadless` already tolerates
+     * multiple subscribers.
+     */
+    attach(controller: ExecRunnerController): void;
+    /**
+     * Drop the subscriptions and the timer.
+     *
+     * IDEMPOTENT, and it clears the wall-clock timer even though that timer is
+     * `unref`d: `unref` only stops it holding the event loop open, it does not stop
+     * it firing and calling `abort()` on a controller the caller has since
+     * disposed (R-10).
+     */
+    detach(): void;
+    stats(): ExecRunStats;
+    /**
+     * `0` success | `1` agent error | `3` budget | `128 + signo` for a signal.
+     *
+     * `3` IS ITS OWN CODE RATHER THAN `0` OR `1` (D-6). Both alternatives lose
+     * information a shell script needs and cannot recover without parsing JSON:
+     * `0` claims a complete answer that does not exist, `1` claims a malfunction
+     * that did not happen.
+     */
+    exitCode(): number;
+    /**
+     * Drive the conversation until the source is exhausted or a budget fires.
+     *
+     * The inner loop is the todo follow-through continuation of `runHeadless`,
+     * with the IDENTICAL policy - both call `decideFollowThrough`, which is why
+     * the two faces cannot drift about what "unfinished" means.
+     */
+    run(source: ExecPromptSource): Promise<void>;
+    /** One caller message plus every auto-continuation it produces. */
+    private runFollowThroughChain;
+    /**
+     * The wall clock starts at the FIRST `prompt()`, not at process start: the
+     * caller is bounding the run, and config resolution plus a skills scan are not
+     * part of what they asked to bound.
+     */
+    private startBudgetTimer;
+    private turnBudgetExhausted;
+    /**
+     * Enforced at `turn_start`, NOT at `turn_end` (implementation finding IF-3).
+     *
+     * The design said "count `turn_end`; on reaching `n`, abort", and the counting
+     * half is right - `turns` is exactly that count. Acting on it at `turn_end` is
+     * not: a run that COMPLETES in exactly `n` turns would trip the budget it
+     * never exceeded and report `stopReason: "max_turns"` with exit 3, so a CI
+     * script running `aragon exec --max-turns 20 ... || fail` would fail on a
+     * successful twenty-turn run. That is the single most likely way to make a
+     * safety ceiling unusable as a safety ceiling.
+     *
+     * A turn that is STARTING when the count already sits at `n` is, by contrast,
+     * unambiguous: the model asked for turn `n + 1` and the caller said no. AC-16
+     * is satisfied either way - "a model that would take five turns" with
+     * `--max-turns 2` still exits 3 with the partial answer in `result.result`.
+     */
+    private checkTurnBudget;
+    /**
+     * EXEC REPLACES THE TERMINATOR; IT DOES NOT ADD A LISTENER.
+     *
+     * `logging/install.ts` registers the `SIGINT` / `SIGTERM` / `SIGHUP` listeners
+     * once, for EVERY invocation, and its default terminator exits. A listener
+     * added here would be later in EventEmitter order and would never run - the
+     * process is already gone - so the run would vanish with no `result` line,
+     * which is precisely the "the wrapper has to time out to learn the run ended"
+     * outcome this whole section exists to prevent (P0-1 / R-15).
+     *
+     * FIRST SIGNAL: abort, record the reason, and RETURN WITHOUT EXITING. The run
+     * settles through the normal path - session persisted, `result` emitted,
+     * `process.exitCode = 128 + signo`.
+     *
+     * SECOND SIGNAL WITHIN 2s: exit immediately. That escape is what makes
+     * returning safe: a wedged settle is always one more Ctrl-C away from ending.
+     *
+     * AFTER `detach()`: exit immediately as well, because from that moment there
+     * is nothing left to settle and the caller's Ctrl-C must not become "nothing
+     * happens".
+     *
+     * `detach()` DOES NOT RESTORE THE PREVIOUS TERMINATOR, AND THAT IS THE POINT
+     * OF THE BRANCH ABOVE (implementation finding IF-7). The design asked for a
+     * restore in `finally`; `setSignalTerminator` returns `void` and there is no
+     * getter, so a literal restore would mean changing `logging/install.ts`, which
+     * the change plan holds to a doc-comment-only edit. The `detached` branch is
+     * what makes that safe rather than merely convenient: once detached this
+     * terminator does `exit(128 + signo)`, which is byte for byte what the default
+     * terminator does, so a left-behind one is INDISTINGUISHABLE from a restored
+     * one. Anything that ever gives this process a terminator worth returning to -
+     * the full-screen one that restores the terminal, or a second `runExec` in one
+     * process under the programmatic API section 2.2 hedges for - must revisit
+     * this and add the getter.
+     */
+    private installTerminator;
+    private emit;
+    /** Caller-facing prose. STDERR ALWAYS - stdout carries nothing but the schema. */
+    private note;
+    private onAgentEvent;
+    private onStreamEvent;
+    private onTurnEnd;
+    private flushThinking;
+    private recordError;
+    private emitTeam;
+}