@aragon-agent/cli 0.5.12 → 0.6.1

package/dist/exec/cli-commands.js

@@ -0,0 +1,63 @@
+/**
+ * `aragon exec` commander wiring (cli-integration-surface section 3.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE DECLARATIONS LIVE HERE, NOT IN `cli.tsx`, AND THAT IS A DELIBERATE
+ * DEPARTURE FROM THE EXISTING CONVENTION. `logs` / `history` / `skills` /
+ * `update` declare their options in `cli.tsx` and delegate to a `run*Command`.
+ * `cli.tsx` is already 1600 lines against this repository's 1000-line guideline,
+ * and four new subcommands carrying about twenty declarations between them is
+ * another 120 lines on a file that is 60% over budget. So `cli.tsx` gains four
+ * imports and four `register*Command(...)` call sites instead. This is a rule
+ * for the NEW code, not a refactor of the old (which is out of scope).
+ *
+ * NOT `src/commands/` EITHER: that directory is the SLASH-command tree
+ * (`/help`, `/model`, `/save`, `/resume`), and it already owns the two names
+ * exec's session work sits closest to.
+ */
+import { Option } from 'commander';
+import { runExec } from './index.js';
+export function registerExecCommand(program, toFlags, deps) {
+    const exec = program
+        .command('exec')
+        .description('Headless, machine-facing run: JSON events, sessions, tool permissions, budgets')
+        .argument('[prompt]', 'The prompt (or use --prompt-file, or pipe it on stdin)')
+        .option('--output-format <fmt>', 'text | json | stream-json (default: text)')
+        .option('--input-format <fmt>', 'text | stream-json (needs --output-format stream-json)')
+        .option('--partial-messages', 'Emit text_delta events (stream-json only)')
+        .option('--include-thinking', 'Emit thinking events (stream-json only)')
+        .option('--prompt-file <path>', 'Read the prompt from a file')
+        .option('--session-id <id>', 'Create or resume a session by id')
+        .option('--resume <id|path>', 'Resume an existing session; fail if it is absent')
+        .option('-c, --continue', 'Resume the newest session for this working directory')
+        .option('--no-save-session', 'Run statelessly: write nothing to the sessions directory')
+        .option('--max-turns <n>', 'Stop after n assistant turns (exit 3)')
+        .option('--max-duration <ms>', 'Stop after ms of wall clock (exit 3). --idle-timeout still applies to a silent ' +
+        'stretch inside the run, and --tool-timeout to a single tool call')
+        .option('--permission-mode <m>', 'auto | plan | strict (default: auto)')
+        .option('--allow-tool <names>', 'Add tools to the baseline (repeatable; comma-separated accepted)', collect)
+        .option('--deny-tool <names>', 'Remove tools; wins over --allow-tool (repeatable; comma-separated accepted)', collect)
+        .option('--append-system-prompt <text>', 'Append text to the builtin system prompt')
+        .option('--append-system-prompt-file <path>', 'Append the contents of a file')
+        // HIDDEN, AND KEPT ONLY SO A GUESS IS NOT PUNISHED (P2-1 / D-16). The root
+        // command already carries `--tool-timeout` (a single tool call) and
+        // `--idle-timeout` (the engine watchdog); a third option called plainly
+        // `--timeout` would be the most generic of the three names attached to the
+        // newest and least familiar of them.
+        .addOption(new Option('--timeout <ms>', 'Alias of --max-duration').hideHelp());
+    exec.action(async (prompt, opts) => {
+        const rootOpts = program.opts();
+        process.exitCode = await runExec(toFlags(program.opts()), {
+            ...opts,
+            // Hoisted from the root by commander, and read here because `exec` does
+            // not redeclare them. `--print` is REFUSED rather than ignored (P2-5).
+            ...(rootOpts.quiet !== undefined ? { quiet: rootOpts.quiet } : {}),
+            ...(rootOpts.print !== undefined ? { print: rootOpts.print } : {}),
+        }, prompt, { version: deps.version, makeController: deps.makeController });
+    });
+}
+/** Repeatable option accumulator. Comma splitting happens in `options.ts`. */
+function collect(value, previous = []) {
+    return [...previous, value];
+}

package/dist/exec/emitter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The three output faces of `aragon exec` (cli-integration-surface section 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE EMITTER IS THE ONLY OBJECT HANDED A STDOUT STREAM (R-2). Everything else
+ * on the exec path writes to stderr: migration notices, config-parse warnings,
+ * untrusted-skill notices, retry lines, `[usage]`, `[team]`, `[todo]` and every
+ * log record. One stray `process.stdout.write` corrupts every consumer, silently
+ * and only in the field, so the containment is structural rather than a rule
+ * anyone has to remember.
+ *
+ * `result()` IS IDEMPOTENT ON ALL THREE (AC-6). A `finally` and an error handler
+ * racing must not produce two `result` lines, and the second call being a no-op
+ * is what makes "exactly one, always last" true on every exit path including
+ * error, budget and signal - rather than true for the paths someone remembered.
+ */
+import type { ExecEvent, ExecInitParams, ExecResultEvent, ExecResultParams } from './events.js';
+export interface ExecEmitter {
+    init(params: ExecInitParams): void;
+    /** Every non-`result` event. Ignored wholesale by `text` and `json`. */
+    emit(event: ExecEvent): void;
+    /** Exactly once per run; the second call is a no-op. */
+    result(params: ExecResultParams): void;
+    /** What `result()` actually wrote, or `null`. For tests and for `runExec`. */
+    emitted(): ExecResultEvent | null;
+}
+/**
+ * `--output-format text`: WRITES NOTHING (D-1).
+ *
+ * Text mode delegates to `runHeadless` VERBATIM - same controller, same
+ * `quiet`, same `followThrough` - and this object exists only so `runExec` has
+ * one shape to talk to. Reimplementing text rendering here would make "the human
+ * CLI is unchanged" an argument someone has to trust instead of a fact anyone
+ * can check, and the two implementations would drift the first time a retry line
+ * changed. AC-1 asserts byte equality on BOTH streams; this class is what makes
+ * it true by construction.
+ */
+export declare class TextEmitter implements ExecEmitter {
+    private done;
+    init(_params: ExecInitParams): void;
+    emit(_event: ExecEvent): void;
+    result(params: ExecResultParams): void;
+    emitted(): ExecResultEvent | null;
+}
+/**
+ * `--output-format json`: the `result` object alone, pretty-printed, on stdout.
+ *
+ * `aragon exec --output-format json "..." | jq -r .result` is the intended
+ * one-liner, which is why the intermediate events are dropped rather than
+ * buffered into an array: a wrapper that wants the stream asks for the stream.
+ */
+export declare class JsonEmitter implements ExecEmitter {
+    private readonly out;
+    private done;
+    constructor(out: NodeJS.WritableStream);
+    init(_params: ExecInitParams): void;
+    emit(_event: ExecEvent): void;
+    result(params: ExecResultParams): void;
+    emitted(): ExecResultEvent | null;
+}
+/**
+ * `--output-format stream-json`: one JSON object per line, `\n`-terminated, no
+ * pretty-printing, UTF-8.
+ *
+ * EVENTS AFTER `result` ARE DROPPED, not appended. "Exactly one `result`, always
+ * last" is the property consumers build their read loop around, and a late
+ * `tool_result` arriving from a torn-down subscription would break it in the
+ * rarest and least reproducible circumstances there are.
+ */
+export declare class StreamJsonEmitter implements ExecEmitter {
+    private readonly out;
+    private done;
+    constructor(out: NodeJS.WritableStream);
+    init(params: ExecInitParams): void;
+    emit(event: ExecEvent): void;
+    result(params: ExecResultParams): void;
+    emitted(): ExecResultEvent | null;
+}
+export declare function createEmitter(format: 'text' | 'json' | 'stream-json', out: NodeJS.WritableStream): ExecEmitter;

package/dist/exec/emitter.js

@@ -0,0 +1,127 @@
+/**
+ * The three output faces of `aragon exec` (cli-integration-surface section 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE EMITTER IS THE ONLY OBJECT HANDED A STDOUT STREAM (R-2). Everything else
+ * on the exec path writes to stderr: migration notices, config-parse warnings,
+ * untrusted-skill notices, retry lines, `[usage]`, `[team]`, `[todo]` and every
+ * log record. One stray `process.stdout.write` corrupts every consumer, silently
+ * and only in the field, so the containment is structural rather than a rule
+ * anyone has to remember.
+ *
+ * `result()` IS IDEMPOTENT ON ALL THREE (AC-6). A `finally` and an error handler
+ * racing must not produce two `result` lines, and the second call being a no-op
+ * is what makes "exactly one, always last" true on every exit path including
+ * error, budget and signal - rather than true for the paths someone remembered.
+ */
+import { buildInitEvent, buildResultEvent, toNdjsonLine } from './events.js';
+/**
+ * `--output-format text`: WRITES NOTHING (D-1).
+ *
+ * Text mode delegates to `runHeadless` VERBATIM - same controller, same
+ * `quiet`, same `followThrough` - and this object exists only so `runExec` has
+ * one shape to talk to. Reimplementing text rendering here would make "the human
+ * CLI is unchanged" an argument someone has to trust instead of a fact anyone
+ * can check, and the two implementations would drift the first time a retry line
+ * changed. AC-1 asserts byte equality on BOTH streams; this class is what makes
+ * it true by construction.
+ */
+export class TextEmitter {
+    done = null;
+    // The parameters are DECLARED even though they are unused, so a caller
+    // holding a concrete `TextEmitter` can call it exactly as it calls the other
+    // two. A zero-arity method satisfies the interface and then makes the class
+    // unusable through its own type, which is the sort of asymmetry that turns
+    // into a cast at the call site.
+    init(_params) {
+        // Deliberately empty. `runHeadless` owns every byte of the text stream.
+    }
+    emit(_event) {
+        // Deliberately empty, same reason.
+    }
+    result(params) {
+        if (this.done)
+            return;
+        // RECORDED BUT NOT WRITTEN. `runExec` reads it for the exit code and the
+        // session bookkeeping; writing it would append a JSON line to prose that
+        // `aragon -p` does not produce.
+        this.done = buildResultEvent(params);
+    }
+    emitted() {
+        return this.done;
+    }
+}
+/**
+ * `--output-format json`: the `result` object alone, pretty-printed, on stdout.
+ *
+ * `aragon exec --output-format json "..." | jq -r .result` is the intended
+ * one-liner, which is why the intermediate events are dropped rather than
+ * buffered into an array: a wrapper that wants the stream asks for the stream.
+ */
+export class JsonEmitter {
+    out;
+    done = null;
+    constructor(out) {
+        this.out = out;
+    }
+    init(_params) {
+        // The init event is carried by `result.sessionId` / `result.model` for this
+        // format. Writing it here would put two objects on a stream documented to
+        // carry one.
+    }
+    emit(_event) {
+        // Dropped by design; see the class comment.
+    }
+    result(params) {
+        if (this.done)
+            return;
+        this.done = buildResultEvent(params);
+        this.out.write(`${JSON.stringify(this.done, null, 2)}\n`);
+    }
+    emitted() {
+        return this.done;
+    }
+}
+/**
+ * `--output-format stream-json`: one JSON object per line, `\n`-terminated, no
+ * pretty-printing, UTF-8.
+ *
+ * EVENTS AFTER `result` ARE DROPPED, not appended. "Exactly one `result`, always
+ * last" is the property consumers build their read loop around, and a late
+ * `tool_result` arriving from a torn-down subscription would break it in the
+ * rarest and least reproducible circumstances there are.
+ */
+export class StreamJsonEmitter {
+    out;
+    done = null;
+    constructor(out) {
+        this.out = out;
+    }
+    init(params) {
+        if (this.done)
+            return;
+        this.out.write(toNdjsonLine(buildInitEvent(params)));
+    }
+    emit(event) {
+        if (this.done)
+            return;
+        this.out.write(toNdjsonLine(event));
+    }
+    result(params) {
+        if (this.done)
+            return;
+        this.done = buildResultEvent(params);
+        this.out.write(toNdjsonLine(this.done));
+    }
+    emitted() {
+        return this.done;
+    }
+}
+export function createEmitter(format, out) {
+    if (format === 'json')
+        return new JsonEmitter(out);
+    if (format === 'stream-json')
+        return new StreamJsonEmitter(out);
+    return new TextEmitter();
+}

package/dist/exec/events.d.ts

@@ -0,0 +1,226 @@
+/**
+ * THE CONTRACT (cli-integration-surface section 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`, R-3 / AC-25). Every string here can reach a
+ * consumer's terminal through `--output-format text` fallbacks or a stderr
+ * warning, and the whole point of the scanner is that a legacy `cmd.exe` shows
+ * mojibake for anything else.
+ *
+ * PURE TYPES AND BUILDERS. No I/O, no process access, no imports outside
+ * `node:`-free type space, so a consumer of this module cannot accidentally
+ * evaluate the runner.
+ *
+ * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
+ * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
+ * That rule only holds if consumers keep their side of it, so the README states
+ * it in the same words: ignore event types you do not know, ignore fields you do
+ * not know. Without that contract the version would have to move for every
+ * additive change and every wrapper would pin an exact number forever.
+ */
+export declare const EXEC_SCHEMA_VERSION = 1;
+/** The three baselines of section 4.2. `plan` is a MODE, never a filter. */
+export type ExecPermissionMode = 'auto' | 'plan' | 'strict';
+export type ExecOutputFormat = 'text' | 'json' | 'stream-json';
+export type ExecInputFormat = 'text' | 'stream-json';
+/**
+ * Why the run ended.
+ *
+ * `interrupted` covers ALL THREE signals (section 3.6): which one arrived is an
+ * operating-system fact, not an agent outcome, and a wrapper that wants to know
+ * reads `exitCode` - which follows the CLI's existing `128 + signo` convention.
+ */
+export type ExecStopReason = 'end_turn' | 'max_turns' | 'timeout' | 'interrupted' | 'error';
+export interface ExecUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+export interface ExecCost {
+    amount: number;
+    currency: 'USD';
+    /**
+     * `controller.isPricedModel(...)` (P2-3) - the method the CLI already uses for
+     * this question, not a second price table. When it is `false`, `amount` is `0`:
+     * a feature that looks free while it is spending money is worse than one that
+     * admits it does not know.
+     */
+    known: boolean;
+}
+export interface ExecTodoCounts {
+    total: number;
+    done: number;
+}
+export interface ExecErrorInfo {
+    code: string;
+    message: string;
+}
+export interface ExecSystemInitEvent {
+    type: 'system';
+    subtype: 'init';
+    schemaVersion: number;
+    sessionId: string;
+    cli: string;
+    cwd: string;
+    startedAt: number;
+    model: {
+        provider: string;
+        id: string;
+        baseUrl: string | null;
+    };
+    permissionMode: ExecPermissionMode;
+    tools: string[];
+    resumed: boolean;
+}
+export interface ExecUserEvent {
+    type: 'user';
+    sessionId: string;
+    turn: number;
+    text: string;
+    /**
+     * `todo_continue` marks a message the CLI generated on the caller's behalf
+     * through the follow-through loop. A wrapper replaying a transcript has to be
+     * able to tell those apart from what it actually sent.
+     */
+    source: 'caller' | 'todo_continue';
+}
+export interface ExecTextDeltaEvent {
+    type: 'text_delta';
+    sessionId: string;
+    turn: number;
+    delta: string;
+}
+export interface ExecThinkingEvent {
+    type: 'thinking';
+    sessionId: string;
+    turn: number;
+    text: string;
+}
+export interface ExecAssistantEvent {
+    type: 'assistant';
+    sessionId: string;
+    turn: number;
+    text: string;
+}
+export interface ExecToolCallEvent {
+    type: 'tool_call';
+    sessionId: string;
+    turn: number;
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ExecToolResultEvent {
+    type: 'tool_result';
+    sessionId: string;
+    turn: number;
+    id: string;
+    name: string;
+    isError: boolean;
+    durationMs: number;
+    /**
+     * NOT TRUNCATED A SECOND TIME (AC-26). The core executor already clips at
+     * roughly 100 KB, and this event carries what the MODEL saw - the only
+     * faithful choice. A consumer therefore needs a line reader without a small
+     * buffer cap, and the README says so.
+     */
+    output: string;
+}
+export interface ExecTodoEvent {
+    type: 'todo';
+    sessionId: string;
+    total: number;
+    done: number;
+    activeIndex: number;
+    items: {
+        content: string;
+        status: 'pending' | 'in_progress' | 'completed';
+    }[];
+}
+export interface ExecTeamEvent {
+    type: 'team';
+    sessionId: string;
+    subtype: 'dispatch_start' | 'agent_update' | 'dispatch_end';
+    label?: string;
+    phase?: string;
+    description?: string;
+    durationMs?: number;
+    toolCalls?: number;
+    ok?: number;
+    total?: number;
+    aborted?: boolean;
+}
+export interface ExecFastReviewEvent {
+    type: 'fast_review';
+    sessionId: string;
+    turn: number;
+    model: string;
+    text: string;
+}
+export interface ExecRetryEvent {
+    type: 'retry';
+    sessionId: string;
+    attempt: number;
+    maxRetries: number;
+    errorType: string;
+    delayMs: number;
+}
+export interface ExecErrorEvent {
+    type: 'error';
+    sessionId: string;
+    /** `false` for a line the run recovered from (a malformed stdin line, say). */
+    fatal: boolean;
+    code: string;
+    message: string;
+}
+export interface ExecResultEvent {
+    type: 'result';
+    schemaVersion: number;
+    sessionId: string;
+    isError: boolean;
+    stopReason: ExecStopReason;
+    /**
+     * `0` success | `1` agent error | `2` usage/config | `3` budget |
+     * `128 + signo` for a signal (130 SIGINT, 143 SIGTERM, 129 SIGHUP).
+     *
+     * DELIBERATELY `number`, NOT A UNION (P1-11): `logging/install.ts` holds
+     * `SIGNAL_NUMBERS = { SIGINT: 2, SIGTERM: 15, SIGHUP: 1 }` and exits
+     * `128 + signo`, so the signal values are open-ended and a union that omitted
+     * 143 would make the honest value unrepresentable.
+     */
+    exitCode: number;
+    /** The final assistant text; `''` when there was none. */
+    result: string;
+    turns: number;
+    durationMs: number;
+    usage: ExecUsage;
+    cost: ExecCost;
+    model: {
+        provider: string;
+        id: string;
+    };
+    todos: ExecTodoCounts | null;
+    error: ExecErrorInfo | null;
+}
+export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecRetryEvent | ExecErrorEvent | ExecResultEvent;
+/** Everything `system/init` needs that the runner cannot derive for itself. */
+export interface ExecInitParams {
+    sessionId: string;
+    cli: string;
+    cwd: string;
+    startedAt: number;
+    model: {
+        provider: string;
+        id: string;
+        baseUrl: string | null;
+    };
+    permissionMode: ExecPermissionMode;
+    tools: string[];
+    resumed: boolean;
+}
+export declare function buildInitEvent(params: ExecInitParams): ExecSystemInitEvent;
+/** Everything `result` needs. `schemaVersion` is stamped here, never by a caller. */
+export type ExecResultParams = Omit<ExecResultEvent, 'type' | 'schemaVersion'>;
+export declare function buildResultEvent(params: ExecResultParams): ExecResultEvent;
+/** Serialize one event as an NDJSON line, terminator included. */
+export declare function toNdjsonLine(event: ExecEvent): string;

package/dist/exec/events.js

@@ -0,0 +1,43 @@
+/**
+ * THE CONTRACT (cli-integration-surface section 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`, R-3 / AC-25). Every string here can reach a
+ * consumer's terminal through `--output-format text` fallbacks or a stderr
+ * warning, and the whole point of the scanner is that a legacy `cmd.exe` shows
+ * mojibake for anything else.
+ *
+ * PURE TYPES AND BUILDERS. No I/O, no process access, no imports outside
+ * `node:`-free type space, so a consumer of this module cannot accidentally
+ * evaluate the runner.
+ *
+ * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
+ * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
+ * That rule only holds if consumers keep their side of it, so the README states
+ * it in the same words: ignore event types you do not know, ignore fields you do
+ * not know. Without that contract the version would have to move for every
+ * additive change and every wrapper would pin an exact number forever.
+ */
+export const EXEC_SCHEMA_VERSION = 1;
+export function buildInitEvent(params) {
+    return {
+        type: 'system',
+        subtype: 'init',
+        schemaVersion: EXEC_SCHEMA_VERSION,
+        sessionId: params.sessionId,
+        cli: params.cli,
+        cwd: params.cwd,
+        startedAt: params.startedAt,
+        model: params.model,
+        permissionMode: params.permissionMode,
+        tools: params.tools,
+        resumed: params.resumed,
+    };
+}
+export function buildResultEvent(params) {
+    return { type: 'result', schemaVersion: EXEC_SCHEMA_VERSION, ...params };
+}
+/** Serialize one event as an NDJSON line, terminator included. */
+export function toNdjsonLine(event) {
+    return `${JSON.stringify(event)}\n`;
+}

package/dist/exec/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `aragon exec` - wiring only (cli-integration-surface section 3.3 / 6.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * NO PROCESS-GLOBAL STATE, AND THAT IS A RULE RATHER THAN A HABIT (section 2.2).
+ * A programmatic Node API is the deferral most likely to be asked for first, and
+ * the only thing that makes it cheap later is `runExec()` holding nothing the
+ * process owns: the controller arrives through a factory, both streams are
+ * parameters, and the exit code is RETURNED rather than assigned.
+ *
+ * THE CONTROLLER COMES FROM A FACTORY BECAUSE `makeController` LIVES IN
+ * `cli.tsx` (see the note on `ExecControllerFactory`). Reaching for it directly
+ * would make `cli.tsx -> exec/cli-commands.ts -> exec/index.ts -> cli.tsx` a
+ * cycle, and duplicating it here would give the headless approval gates a second
+ * definition - the one thing `makeController`'s own comment says must not
+ * happen.
+ */
+import type { AgentController } from '../agent/controller.js';
+import { type CliFlags } from '../config/load.js';
+import { type RawExecOptions } from './options.js';
+import { type ToolPermission } from './permission.js';
+/**
+ * How `runExec` obtains a controller.
+ *
+ * `cli.tsx` supplies `(flags, deps) => makeController(flags, { interactive:
+ * false, ...deps }).controller`, already wired for headless: the deny-all
+ * approval gate, the deny-all human-input gate, the log attachments and the
+ * untrusted-skill notices. Everything this module needs and nothing it should
+ * decide for itself.
+ */
+export type ExecControllerFactory = (flags: CliFlags, deps: {
+    permission?: ToolPermission;
+    appendSystemPrompt?: string;
+}) => AgentController;
+export interface RunExecContext {
+    version: string;
+    makeController: ExecControllerFactory;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    stdin?: NodeJS.ReadableStream;
+    /** Injected by tests so a run never touches the real clock. */
+    now?: () => number;
+}
+/**
+ * Run one `aragon exec` invocation and resolve with the process exit code.
+ *
+ * EXIT 2 MEANS THE RUN NEVER STARTED, AND STDOUT CARRIES NOTHING ON THAT PATH.
+ * Option errors, prompt errors and session errors are all reported on stderr
+ * alone: emitting a lone `result` line for them would break the guarantee
+ * `system/init` is the FIRST stream-json line (AC-5), and a wrapper that got a
+ * `result` without an `init` could not tell a run that failed to start from one
+ * that failed. A preflight failure is different - the format is settled and the
+ * schema has begun - so that one DOES emit a `result` with `exitCode: 2`.
+ */
+export declare function runExec(flags: CliFlags, raw: RawExecOptions, promptArg: string | undefined, ctx: RunExecContext): Promise<number>;