@aragon-agent/cli 0.6.37 → 0.6.39

package/dist/exec/index.js

@@ -17,6 +17,7 @@
  * happen.
  */
 import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
 import { randomUUID } from 'node:crypto';
 import process from 'node:process';
 import { runHeadless } from '../agent/headless.js';
@@ -28,6 +29,20 @@ import { resolveExecOptions } from './options.js';
 import { resolvePermission } from './permission.js';
 import { ExecRunner, singlePrompt } from './runner.js';
 import { createStdinPromptSource, prefixSource } from './stdin-stream.js';
+import { getLogger } from '../logging/logger.js';
+import { LEAD_SCOPE } from './bridge/protocol.js';
+import { createBridgeWriter } from './bridge/writer.js';
+import { createBridgeServer } from './bridge/server.js';
+import { createBridgePromptSource } from './bridge/source.js';
+import { createCallerTools } from './bridge/caller-tools.js';
+import { createCallerApprovalGate, createCallerHumanInputGate, createCallerToolGate, } from './bridge/decisions.js';
+import { RESULT_LIMITS } from './result/limits.js';
+import { parseResultSchema } from './result/schema.js';
+import { createResultSink } from './result/sink.js';
+import { createSubmitResultTool, SUBMIT_RESULT_TOOL } from './result/tool.js';
+import { buildStructuredResultBlock } from './result/prompt.js';
+import { createHookRuntime } from './hooks/index.js';
+import { executeThreads } from './threads/execute-threads.js';
 /**
  * Run one `aragon exec` invocation and resolve with the process exit code.
  *
@@ -43,7 +58,14 @@ export async function runExec(flags, raw, promptArg, ctx) {
     const out = ctx.stdout ?? process.stdout;
     const err = ctx.stderr ?? process.stderr;
     const now = ctx.now ?? Date.now;
-    const resolved = resolveExecOptions(raw);
+    // THE ONE FACT FROM CONFIG THAT CHANGES A FLAG'S LEGALITY, READ ONCE. `--confirm`
+    // is `config.confirmTools` (D-6), and without it `ask` plus that setting would
+    // arm two approval layers over the same three tools - an invocation whose
+    // visible failure is "it never asks". `loadConfig` is read here rather than
+    // below because this is the first consumer, and `options.ts` stays a pure
+    // flag parser: it is told the fact, it does not go looking for it.
+    const config = loadConfig(flags);
+    const resolved = resolveExecOptions(raw, { confirmTools: config.confirmTools });
     if (!resolved.ok) {
         err.write(`${resolved.message}\n`);
         return 2;
@@ -54,10 +76,63 @@ export async function runExec(flags, raw, promptArg, ctx) {
     const appended = readOptionalText(options.appendSystemPrompt, options.appendSystemPromptFile, err, '--append-system-prompt-file');
     if (appended === null)
         return 2;
-    const cwd = loadConfig(flags).cwd;
+    // THE CALLER'S SCHEMA, READ AND VALIDATED BEFORE ANYTHING ELSE HAPPENS.
+    //
+    // EXIT 2 WITH NOTHING ON STDOUT on every failure path, which is the same contract
+    // options, prompt and session errors already follow: a run that never started must
+    // not emit a `result` line, because `system/init` being first is what lets a wrapper
+    // tell "failed to start" from "started and failed".
+    //
+    // THE SINK IS CREATED HERE, before the controller, for the same reason the interrupt
+    // box is: the tool factory needs it, the tool is passed to the controller factory,
+    // and the runner only ever reads it.
+    const resultSpec = readResultSchema(options, err);
+    if (resultSpec === 'failed')
+        return 2;
+    const resultSink = resultSpec === null ? null : createResultSink({ now });
+    const cwd = config.cwd;
     const plan = planSession(options, cwd, err);
     if (!plan)
         return 2;
+    // THREAD MODE TAKES ITS OWN PATH, AND IT TAKES IT HERE (section 2.6 row 6).
+    //
+    // BEFORE ANY PROMPT SOURCE EXISTS, because a source would have started reading stdin. This
+    // is the ONE branch the feature adds to this file: everything below - the interrupt box,
+    // the bridge runtime, the prompt source, the single-runner assembly - belongs to the
+    // single-conversation path and is untouched when `--threads` is on.
+    if (options.threads) {
+        // A THREAD RUN OWNS STDIN (I-T12). A pre-built source would be a second splitter on the
+        // same bytes, and the frames would be split between them - so the combination is refused
+        // outright rather than diagnosed later from mysterious lost prompts.
+        // A POSITIONAL PROMPT CANNOT BE HONOURED HERE, WHATEVER STDIN IS DOING: thread mode has
+        // no single conversation to send it to, and dropping it silently would look like a model
+        // that ignored the request. Refused for every caller, not just the ones without a stdin.
+        if (promptArg !== undefined) {
+            err.write('threads_flag_conflict: --threads takes its prompts from stdin frames; drop the [prompt] argument.\n');
+            return 2;
+        }
+        return executeThreads({
+            flags,
+            options,
+            plan: { id: plan.id, saving: plan.saving, cwd },
+            ctx,
+            out,
+            err,
+            now,
+            version: ctx.version,
+            resultSpec: resultSpec,
+            stdin: ctx.stdin ?? process.stdin,
+            persist: (input) => persistThreadSession({
+                sessionId: input.sessionId,
+                controller: input.controller,
+                turns: input.turns,
+                usage: input.usage,
+                at: input.at,
+                cli: ctx.version,
+                cwd,
+            }),
+        });
+    }
     /**
      * Late-bound interrupt hook (see `resolvePromptSource` and `execute`).
      *
@@ -69,7 +144,43 @@ export async function runExec(flags, raw, promptArg, ctx) {
      * `execute` for why "does nothing" beats "does half of it".
      */
     const interrupt = { fire: () => { } };
-    const prompts = resolvePromptSource(options, promptArg, ctx, err, interrupt);
+    // THE BRIDGE EXISTS BEFORE THE PROMPT SOURCE, because the source routes control
+    // frames to it and the source is what starts reading stdin. It also exists before
+    // the controller, which is why the server reaches the controller through
+    // `bindController` rather than a constructor argument.
+    //
+    // THE HOOK RUNTIME EXISTS BEFORE BOTH (headless-threads-and-lifecycle-hooks section
+    // 2.4.9): the tool array is built once, inside `makeController`, so the wrapper has to be
+    // available then - even though `hook_register` cannot arrive until later. It is created for
+    // EVERY bridge run, and with no hook registered it emits nothing and changes nothing.
+    const controllerBox = { controller: null };
+    /**
+     * The writer, in a box because the hook runtime needs it before the bridge exists.
+     *
+     * ONE WRITER, ONE `seq` (I-C3). The hook runtime is constructed first only because the
+     * controller is; the object it writes through is the same one the server uses, reached
+     * through this box instead of being duplicated.
+     */
+    const bridgeWriterBox = {};
+    const hooks = options.inputFormat === 'bridge'
+        ? createHookRuntime({
+            sessionId: plan.id,
+            write: (event) => bridgeWriterBox.writer?.write(event),
+            knownTools: () => {
+                const names = new Set((controllerBox.controller?.listTools() ?? []).map((tool) => tool.name));
+                for (const name of controllerBox.controller?.callerToolNames() ?? [])
+                    names.add(name);
+                return names;
+            },
+            timeoutMs: options.hookTimeoutMs,
+            policy: () => options.onHookTimeout,
+            now,
+        })
+        : undefined;
+    const bridge = options.inputFormat === 'bridge'
+        ? createBridgeRuntime({ out, sessionId: plan.id, options, hooks, writerBox: bridgeWriterBox })
+        : null;
+    const prompts = resolvePromptSource(options, promptArg, ctx, err, interrupt, bridge);
     if (!prompts)
         return 2;
     const lock = plan.saving ? tryAcquireSessionLock(plan.id) : null;
@@ -79,12 +190,207 @@ export async function runExec(flags, raw, promptArg, ctx) {
         return 2;
     }
     try {
-        return await execute({ flags, options, plan, prompts, ctx, out, err, now, appended, interrupt });
+        return await execute({
+            flags,
+            options,
+            plan,
+            prompts,
+            ctx,
+            out,
+            err,
+            now,
+            appended,
+            interrupt,
+            bridge,
+            ...(hooks ? { hooks } : {}),
+            controllerBox,
+            bridgeWriterBox,
+            resultSpec: resultSpec,
+            resultSink,
+        });
     }
     finally {
+        // A SECOND CLOSE, AND THE ONLY ONE ON THE EARLY-EXIT PATHS. The real one runs
+        // inside `execute()` before `persist()` and before `result` (see there);
+        // `close()` is idempotent, so this call covers a run that never reached that
+        // point - a throw, or a usage error after the channel existed. It cannot settle
+        // anything into a stream whose `result` has already gone out, because
+        // `execute()` sealed the writer.
+        await bridge?.server.close('run_finished');
+        // AFTER the protocol is closed, never before: releasing stdin first would drop
+        // the frames a caller is still entitled to send while the run finishes
+        // (`decision`, `tool_result`). Once the server is closed, nothing more can be
+        // answered - and the listener that would keep this process alive is exactly
+        // what `close()` removes.
+        toBridgeSource(prompts)?.close();
         lock?.release();
     }
 }
+/**
+ * Read and preflight `--result-schema`.
+ *
+ * THREE OUTCOMES, and the third one is not a schema: `null` means "no schema was
+ * asked for", `'failed'` means "one was asked for and it is unusable". The caller
+ * turns the second into exit 2 with nothing on stdout, which is the contract every
+ * other preflight failure in this file already follows.
+ */
+function readResultSchema(options, err) {
+    if (options.resultSchemaPath === undefined)
+        return null;
+    let text;
+    try {
+        text = readFileSync(options.resultSchemaPath, 'utf-8');
+    }
+    catch (e) {
+        reportUsageError(err, 'result_schema_unreadable', `--result-schema: could not read ${options.resultSchemaPath} (${e.message}).`);
+        return 'failed';
+    }
+    const parsed = parseResultSchema(text, basename(options.resultSchemaPath));
+    if (!parsed.ok) {
+        reportUsageError(err, parsed.code, parsed.message);
+        return 'failed';
+    }
+    return parsed.spec;
+}
+/** One line on stderr, prefixed with the stable code so a caller can grep for it. */
+function reportUsageError(err, code, message) {
+    err.write(`${code}: ${message}\n`);
+}
+/**
+ * Build the writer and the server.
+ *
+ * ORDER INSIDE HERE IS NOT COSMETIC: the writer is what the `caller_not_reading`
+ * escalation needs, the server is what the three gates and the prompt source
+ * need, and the controller - which the server's ports call - is bound later by
+ * `bindController`. Every port below is therefore written as `bound?.`-style
+ * access rather than closing over a controller that does not exist yet.
+ */
+function createBridgeRuntime(args) {
+    let bound = null;
+    /**
+     * A `tool_register` CAN ARRIVE BEFORE THE CONTROLLER EXISTS.
+     *
+     * The prompt source starts reading stdin in `runExec`, and the controller is
+     * built a few statements later in `execute`. A caller whose first write is its
+     * tool declaration - which is the natural order, and the one the README shows -
+     * would otherwise be acknowledged and then silently dropped, and the model would
+     * never see the tool with nothing anywhere reporting why. So the set is parked
+     * here and applied by `bindController`.
+     */
+    let parkedSpecs = null;
+    const hardLimit = { fired: false };
+    const writer = createBridgeWriter({
+        out: args.out,
+        sessionId: args.sessionId,
+        onHardLimit: () => {
+            // ONE WAY OUT, and it is the existing abort: the run settles through the
+            // normal path (persist, then `result`), and `execute` turns the flag into
+            // exit 1. Exiting from inside a write would skip both.
+            hardLimit.fired = true;
+            bound?.abort();
+        },
+    });
+    const box = { server: null };
+    const server = createBridgeServer({
+        writer,
+        sessionId: args.sessionId,
+        decisionTimeoutMs: args.options.decisionTimeoutMs,
+        callerToolTimeoutMs: args.options.callerToolTimeoutMs,
+        ports: {
+            applyCallerTools: (specs) => {
+                const target = box.server;
+                if (!target || !bound) {
+                    parkedSpecs = specs;
+                    return;
+                }
+                bound.applyCallerTools(createCallerTools(specs, target, args.options.callerToolTimeoutMs));
+            },
+            isTurnActive: () => bound?.isRunning() === true,
+            callerToolNames: () => bound?.callerToolNames() ?? [],
+            getAgentMode: () => bound?.getAgentMode() ?? 'build',
+        },
+        // THE AUDIT TRAIL IS THE LOG FILE (section 2.5). Not a second in-memory ledger: the
+        // pending table already detects duplicates, and a ring buffer with no reader
+        // is state that can only drift.
+        onAudit: (record) => getLogger().info('bridge', 'decision', { ...record }),
+        // THE HOOK CHANNEL (headless-threads-and-lifecycle-hooks section 2.4.2). Present on
+        // every bridge run, because a hook may be registered at any moment; with none
+        // registered these two callbacks are never entered.
+        ...(args.hooks
+            ? {
+                hookPorts: {
+                    register: (frame) => {
+                        const ack = args.hooks?.register(frame);
+                        if (!ack)
+                            return;
+                        writer.write({
+                            type: 'ack',
+                            ...(frame.id ? { id: frame.id } : {}),
+                            accepted: ack.accepted,
+                            ...(ack.code ? { code: ack.code } : {}),
+                            ...(ack.message ? { message: ack.message } : {}),
+                            ...(ack.hooks ? { hooks: ack.hooks } : {}),
+                            ...(ack.warnings ? { warnings: ack.warnings } : {}),
+                        });
+                    },
+                    answer: (frame) => args.hooks?.answer(frame) ?? false,
+                },
+            }
+            : {}),
+    });
+    box.server = server;
+    // THE BOX, filled the moment the writer exists (section 2.4.9): the hook runtime is built
+    // before this function runs, and it must write through THIS writer so `seq` stays global.
+    if (args.writerBox)
+        args.writerBox.writer = writer;
+    return {
+        writer,
+        server,
+        sessionId: args.sessionId,
+        hardLimit,
+        bindController: (controller) => {
+            bound = controller;
+            if (!parkedSpecs)
+                return;
+            const specs = parkedSpecs;
+            parkedSpecs = null;
+            const target = box.server;
+            if (!target)
+                return;
+            controller.applyCallerTools(createCallerTools(specs, target, args.options.callerToolTimeoutMs));
+        },
+    };
+}
+/**
+ * The three gates, or nothing at all.
+ *
+ * `{}` IS THE WHOLE COMPATIBILITY GUARANTEE: with no bridge, `makeController`
+ * receives exactly the deps object it receives today, so `createBuiltinTools`
+ * builds today's array and every `AC-G17`-style identity assertion still holds.
+ */
+function bridgeGates(bridge, options) {
+    const allow = new Set(options.allowTools);
+    const gateFor = (scope) => createCallerToolGate({
+        server: bridge.server,
+        mode: options.permissionMode,
+        allow,
+        scope,
+        decisionTimeoutMs: options.decisionTimeoutMs,
+    });
+    return {
+        toolGate: gateFor(LEAD_SCOPE),
+        // ONE TABLE, ONE SET OF IDS, ONE CAPACITY - a fan-out of three is still three
+        // outstanding decisions, not three independent budgets.
+        toolGateForChild: (label) => gateFor({ id: label, label, depth: 1 }),
+        approval: createCallerApprovalGate(bridge.server),
+        humanInput: createCallerHumanInputGate(bridge.server),
+        decisionBudgetMs: options.decisionTimeoutMs,
+    };
+}
+/** `ExecPromptSource` -> the bridge source's narrower type, or `undefined`. */
+function toBridgeSource(source) {
+    return 'cancelQueued' in source ? source : undefined;
+}
 async function execute(input) {
     const { options, plan, ctx, out, err, now, interrupt } = input;
     const startedAt = now();
@@ -93,22 +399,101 @@ async function execute(input) {
         allow: options.allowTools,
         deny: options.denyTools,
     });
+    const bridge = input.bridge;
+    const gates = bridge ? bridgeGates(bridge, options) : {};
+    // THE TWO INJECTION POINTS OF R3 (section 2.6 rows 11 and 17), both SPREAD
+    // CONDITIONALLY: with no schema neither key exists, so every other path builds the
+    // controller it builds today and I-S2 stays provable by construction.
+    //
+    // BOTH OR NEITHER IS THE RULE, and the tool is what the prompt block is about: a
+    // block without the tool asks the model for something it cannot do, and a tool
+    // without the block leaves it undiscovered (the R1 mitigation in section 7 is
+    // exactly this pair).
+    const resultTool = input.resultSpec && input.resultSink
+        ? createSubmitResultTool({ spec: input.resultSpec, sink: input.resultSink })
+        : undefined;
+    const structuredResultBlock = input.resultSpec
+        ? buildStructuredResultBlock({
+            toolName: SUBMIT_RESULT_TOOL,
+            hasDefinitions: input.resultSpec.hasDefinitions,
+            repairTurns: options.resultRepairTurns ?? RESULT_LIMITS.defaultRepairTurns,
+        })
+        : '';
     const controller = ctx.makeController(withPermissionMode(input.flags, options.permissionMode), {
         ...(permission ? { permission } : {}),
         ...(input.appended ? { appendSystemPrompt: input.appended } : {}),
+        ...(resultTool ? { resultTool } : {}),
+        ...(structuredResultBlock ? { structuredResultBlock } : {}),
+        // THE HOOK RUNNER, SPREAD CONDITIONALLY AND NEXT TO ITS SIBLINGS (D-12): the tool array
+        // is built inside this factory, so a dep that is not forwarded here is dropped in
+        // silence and the caller's hooks never fire.
+        ...(input.hooks ? { hookRunner: input.hooks.toolRunner } : {}),
+        ...gates,
     });
-    const emitter = createEmitter(options.outputFormat, out);
+    // THE BOX, so the hook runtime's tool whitelist can see the union this controller owns -
+    // including any `tool_register` that lands later.
+    if (input.controllerBox)
+        input.controllerBox.controller = controller;
+    // THE ONE ASSIGNMENT THAT CLOSES THE ORDERING HOLE: the server was built before
+    // the controller (the stdin source needs it) and needs the controller for the
+    // three host-side ports. Nothing else in the run may bind it.
+    bridge?.bindController(controller);
+    const emitter = createEmitter(options.outputFormat, out, bridge?.writer);
     const runner = new ExecRunner({
         emitter,
         sessionId: plan.id,
         ...(options.maxTurns !== undefined ? { maxTurns: options.maxTurns } : {}),
         ...(options.maxDurationMs !== undefined ? { maxDurationMs: options.maxDurationMs } : {}),
+        // THE REQUEST-LEVEL BUDGETS AND THE RESULT BOX. Every one of them is conditional, so
+        // a run without the flags constructs exactly the runner it constructs today and the
+        // request counters inside it are never consulted (I-C1).
+        ...(input.resultSink
+            ? {
+                resultSink: input.resultSink,
+                ...(input.resultSpec ? { resultSchemaName: input.resultSpec.name } : {}),
+                resultRepairTurns: options.resultRepairTurns ?? RESULT_LIMITS.defaultRepairTurns,
+                onResultUnsatisfied: options.onResultUnsatisfied ?? 'error',
+            }
+            : {}),
+        ...(options.requestMaxTurns !== undefined
+            ? { requestMaxTurns: options.requestMaxTurns }
+            : {}),
+        ...(options.requestMaxDurationMs !== undefined
+            ? { requestMaxDurationMs: options.requestMaxDurationMs }
+            : {}),
+        // THE ONE COST AUTHORITY, CLOSED OVER HERE. `buildCost` needs the controller's price
+        // table, and the runner needs it to answer "what did THIS request cost" - the same
+        // function read twice and differenced by the scope, which is what makes a request's
+        // `cost` equal to running it alone (AC-38).
+        cost: (usage, compaction) => buildCost(controller, usage, compaction),
         partialMessages: options.partialMessages,
         includeThinking: options.includeThinking,
         followThrough: controller.getTodoConfig().followThrough,
         quiet: options.quiet,
         stderr: err,
         now,
+        // THE TWO HOOK POINTS THAT LIVE IN THE RUNNER (section 2.4.6 / 2.4.7). Spread
+        // conditionally, so a run without a hook channel builds exactly today's runner.
+        ...(input.hooks
+            ? {
+                hookPort: {
+                    promptPre: (probe) => input.hooks
+                        ? input.hooks.promptPre({
+                            text: probe.text,
+                            queued: probe.queued,
+                            requestId: probe.requestId,
+                        })
+                        : Promise.resolve({ action: 'allow' }),
+                },
+                beforeTurn: (info) => input.hooks
+                    ? input.hooks.beforeTurn({
+                        turn: info.turn,
+                        source: info.source,
+                        requestId: info.requestId,
+                    })
+                    : Promise.resolve(undefined),
+            }
+            : {}),
     });
     if (plan.saved) {
         controller.replaceMessages(plan.saved.messages, plan.saved.compactionIdentity);
@@ -126,8 +511,19 @@ async function execute(input) {
             baseUrl: config.baseUrl ?? null,
         },
         permissionMode: options.permissionMode,
+        // `listTools()` IS THE UNION, so a caller tool registered before `init` (which
+        // the writer queues behind this very line) is already listed here. Reporting
+        // only the host's own set would make `init.tools` disagree with the model.
         tools: controller.listTools().map((t) => t.name),
         resumed: plan.saved !== null,
+        ...(bridge ? { bridge: true } : {}),
+        // THE HOOK CHANNEL IS A BRIDGE CAPABILITY, NOT A THREAD ONE (section 9.9): a single
+        // conversation with one redactor is the commonest embedding shape, and tying hooks to
+        // threads would force it to sign a multi-tenant contract it does not use.
+        ...(bridge ? { hooks: true } : {}),
+        // THE CAPABILITY IS A FACT ABOUT THIS RUN, NOT ABOUT THE BUILD (P0-4). Stamped from
+        // the preflighted schema, which is the only thing that can answer it.
+        ...(input.resultSpec ? { structuredResult: true } : {}),
         // W2 - where this run's conversation lives, so a wrapper can check on disk
         // whether it is still resumable rather than re-deriving the sessions dir.
         //
@@ -143,6 +539,12 @@ async function execute(input) {
         sessionFile: plan.saving ? sessionPathFor(plan.id) : null,
     });
     runner.attach(controller);
+    // AFTER `attach`, and before the first prompt: the turn ports reach the
+    // controller, and `steer` / `interrupt` must be answerable from the very first
+    // frame the caller can send.
+    if (bridge) {
+        runner.attachBridge(bridge.server, toBridgeSource(input.prompts));
+    }
     // AFTER `attach`, never before. The terminator closure ends on
     // `this.controller?.abort()`, so before `attach` the controller is still
     // `undefined` and that last statement is a silent no-op - while the SAME
@@ -165,8 +567,22 @@ async function execute(input) {
     }
     finally {
         runner.detach();
+        // NOTHING IS SETTLED HERE: the protocol is closed a few lines below, while
+        // `result` is still ahead. Disposing the controller first would tear down the
+        // tool that is still waiting for its answer.
         controller.dispose();
     }
+    // A CALLER THAT STOPPED READING FAILED THE RUN. `caller_not_reading` already
+    // went out as a fatal `error` event; exit 1 is the part a shell script reads.
+    if (bridge?.hardLimit.fired)
+        exitCode = exitCode === 0 ? 1 : exitCode;
+    // CLOSE THE PROTOCOL HERE, WHILE `result` IS STILL AHEAD OF US. Closing it any
+    // later (in `runExec`'s `finally`) would be after `result` had already gone out,
+    // so an unanswered decision settled by `closeAll` would emit its
+    // `decision_resolved` on a stream whose last line is supposed to be `result`
+    // (AC-5). Doing it before `persist()` costs nothing: every answer that could
+    // still have arrived has been awaited already.
+    await bridge?.server.close('run_finished');
     // PERSIST FIRST, ANNOUNCE SECOND (D-2). 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.
@@ -174,12 +590,41 @@ async function execute(input) {
     if (plan.saving)
         persist(plan, controller, stats.turns, stats.usage, ctx.version, now());
     const todo = controller.getTodoSnapshot?.() ?? null;
+    // EVERYTHING QUEUED BEHIND `result` GOES OUT FIRST. `result` is the last line by
+    // contract, so a `decision_resolved` still sitting in the writer would either be
+    // dropped (the emitter refuses to write after `result`) or arrive out of order.
+    await bridge?.writer.flush();
+    // THE STRUCTURED ANSWER, IF ANY. `result.result` is REPLACED by the canonical JSON
+    // text on success, because under a schema the answer IS that object - the README's
+    // `| jq -r .result` idiom has to keep meaning "the answer" - and the prose moves to
+    // `result.text` instead of being lost (section 2.3.7, rule 2).
+    const structured = stats.lastStructured;
+    const structuredValue = structured
+        ? JSON.stringify(structured.value)
+        : stats.lastAssistantText;
     emitter.result({
         sessionId: plan.id,
-        isError: exitCode === 1,
-        stopReason: stats.stopReason,
+        isError: exitCode === 1 || bridge?.hardLimit.fired === true || stats.resultUnsatisfied,
+        stopReason: bridge?.hardLimit.fired ? 'error' : stats.stopReason,
         exitCode,
-        result: stats.lastAssistantText,
+        result: structuredValue,
+        ...(input.resultSpec
+            ? {
+                // EXPLICIT `null` ON FAILURE, NOT A MISSING KEY (section 2.3.7, rule 1): a
+                // caller that passed `--result-schema` must be able to read one field and
+                // know, and "absent" would be indistinguishable from "an old build".
+                structured: structured
+                    ? {
+                        value: structured.value,
+                        schemaName: input.resultSpec.name,
+                        schemaBytes: input.resultSpec.bytes,
+                        attempts: structured.attempts,
+                        acceptedAt: now(),
+                    }
+                    : null,
+                text: stats.lastAssistantText,
+            }
+            : {}),
         turns: stats.turns,
         durationMs: now() - startedAt,
         usage: {
@@ -202,8 +647,24 @@ async function execute(input) {
             ? { code: stats.errorCode, message: stats.errorMessage }
             : null,
     });
+    // THE SEAL, AFTER `result` AND NEVER BEFORE. It is `result` that must be last, so
+    // the writer stays open until that line is out; closing it afterwards makes the
+    // contract an enforced one - a frame a late continuation still tries to write is
+    // dropped instead of landing behind the final line.
+    await bridge?.writer.close();
     return exitCode;
 }
+/**
+ * Persist one thread's session, for thread mode.
+ *
+ * A THIN WRAPPER OVER `persist()`, and deliberately not a second implementation: the file
+ * shape, the cumulative counters and the "a failed write is not a failed run" rule are one
+ * set of decisions. Threads never resume (section 1.4), so there is no previous metadata to
+ * accumulate onto; `--resume` stays a process-level, default-thread feature.
+ */
+export function persistThreadSession(input) {
+    persist({ id: input.sessionId, saved: null, saving: true, cwd: input.cwd }, input.controller, input.turns, input.usage, input.cli, input.at);
+}
 /**
  * `text` DELEGATES TO `runHeadless` VERBATIM (D-1 / AC-1).
  *
@@ -309,10 +770,22 @@ function failedResult(sessionId, config, message, code, durationMs) {
  * Returns `null` after writing the reason to stderr, so the caller can exit 2
  * without a second error vocabulary.
  */
-function resolvePromptSource(options, promptArg, ctx, err, interrupt) {
+function resolvePromptSource(options, promptArg, ctx, err, interrupt, bridge) {
     const stdin = ctx.stdin ?? process.stdin;
-    const opening = [];
     const positional = promptArg?.trim();
+    // THE GUARD RUNS BEFORE ANY FILE IS READ, and before `opening` exists.
+    //
+    // WHY IT HAS TO EXIST AT ALL: `prefixSource` turns a positional argument into a
+    // turn that runs BEFORE the first `prompt` frame, so a caller that passed both
+    // would see one prompt answered twice - and only the second would carry a
+    // `requestId`. A warning would leave that trap armed; a usage error costs one
+    // rerun. The message names both offenders so the fix is obvious.
+    if (bridge && (positional || options.promptFile)) {
+        err.write('--input-format bridge takes its prompts on stdin. ' +
+            'Drop the [prompt] argument and --prompt-file.\n');
+        return null;
+    }
+    const opening = [];
     if (positional)
         opening.push(positional);
     else if (options.promptFile) {
@@ -322,6 +795,24 @@ function resolvePromptSource(options, promptArg, ctx, err, interrupt) {
         if (text.trim().length > 0)
             opening.push(text);
     }
+    if (bridge) {
+        return createBridgePromptSource({
+            input: stdin,
+            server: bridge.server,
+            // A BAD FRAME IS AN `error` EVENT, NOT A STDERR LINE (this is the mode that
+            // has an event for it). Written through the writer rather than the emitter
+            // because the emitter does not exist yet - and the writer queues anything
+            // that arrives before `system/init`, which is exactly the guarantee I-11
+            // needs for a caller whose first write is already malformed.
+            onBadLine: (code, message) => bridge.writer.write({
+                type: 'error',
+                sessionId: bridge.sessionId,
+                fatal: false,
+                code,
+                message,
+            }),
+        });
+    }
     if (options.inputFormat === 'stream-json') {
         return prefixSource(opening, createStdinPromptSource({
             input: stdin,