@eir-labs/coltrane 0.8.0 → 0.9.0

package/dist/src/claude_invoker.js

@@ -8,8 +8,12 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { abortReasonText } from "./runtime.js";
-import { resolveAgentGrants } from "./tool_providers.js";
+import { resolveAgentGrants, ENGINE_MCP_SERVER } from "./tool_providers.js";
+import { venueEffectiveTools } from "./chart.js";
+import { CORE_TYPES } from "./core_types.js";
 const EMPTY_TOOL_REGISTRY = new Map();
+/** The tool name a chair's in-band `output_write` seal is advertised under in the spawn. */
+const OUTPUT_WRITE_TOOL = `mcp__${ENGINE_MCP_SERVER}__output_write`;
 // Per-tier model resolution (the old MODEL_TIER_MAP: economy/standard/premium →
 // haiku/sonnet/opus). An agent's model_tier picks the concrete spawn model; falls back to
 // the invoker's static default only when the agent declares no tier.
@@ -88,7 +92,7 @@ export function buildPrompt(ctx, outputSchema,
 // Per-type schemas for a MULTI-output agent (slug → schema). When the agent declares
 // more than one output type, the Task layer asks for a blob keyed by type rather than a
 // single object — the runtime then seals one record per key.
-outputSchemas) {
+outputSchemas, seal) {
     const a = ctx.agent;
     const layers = [];
     // 1. Disposition — the Belbin cognitive-role pairing, held in tension (how you think).
@@ -149,7 +153,26 @@ outputSchemas) {
     // chair is asked for only its promised subset, not its whole catalogue. Legacy ctx without it
     // falls back to the agent's full output_types.
     const sealTypes = ctx.output_types?.length ? ctx.output_types : a.output_types;
-    if (sealTypes.length > 1) {
+    if (seal) {
+        // IN-BAND WRITE-BOUNDARY SEAL. Each output is sealed by an `output_write` call whose payload
+        // the engine adjudicates against the FULL contract; a rejection returns in-band and the agent
+        // fixes `data` and calls again — its own single run self-corrects, no invoker re-prompt.
+        const perType = sealTypes
+            .map((t) => {
+            const s = outputSchemas?.[t] ?? (sealTypes.length === 1 ? outputSchema : undefined);
+            const core = seal.core_by_type[t] ?? "";
+            return (`- output_write({ "core_type": "${core}", "domain_type": "${t}", ` +
+                `"gig_id": "${seal.gig_id}", "phase": "${seal.phase}", "agent_slug": "${seal.agent_slug}", ` +
+                `"data": <object${s ? ` matching ${JSON.stringify(s)}` : ""}> })`);
+        })
+            .join("\n");
+        layers.push(`# Task\nSeal each of your output types by calling the \`output_write\` tool — one call per type:\n${perType}\n\n` +
+            `The tool validates your \`data\` against the complete output contract and returns ` +
+            `\`{ ok: false, error }\` if it does not pass. When that happens, read the error, correct the ` +
+            `\`data\`, and call \`output_write\` again — repeat until it returns \`ok: true\`. The successful ` +
+            `call IS the seal; do NOT print the output as text, and do not stop until every type is sealed.`);
+    }
+    else if (sealTypes.length > 1) {
         // multi-output: one JSON object keyed by each output-type slug; each value is that
         // type's data. The runtime seals one record per key (a SENSE+JUDGE agent yields its
         // Signal and its Judgment in one pass).
@@ -202,6 +225,28 @@ export class ModelOutputParseError extends Error {
             raw.length > EXCERPT_MAX_CHARS ? `${raw.slice(0, EXCERPT_MAX_CHARS)}…` : raw;
     }
 }
+/**
+ * A chair completed its run but sealed NONE of its promised outputs through `output_write`.
+ * Distinct from ModelOutputParseError (a text-seal chair that emitted no parseable answer): this
+ * is the output_write-seal path, where the boundary that adjudicates a payload against its full
+ * output contract is the chair's own in-band `output_write` call (validated by the engine's
+ * checkWritable, corrected in-band by the agent), NOT a re-prompt from this invoker. A chair that
+ * never gets a single write past that boundary produced nothing this invoker can hand back.
+ *
+ * The runtime's own floor check (executeChair, `missingRequired`) also catches a shortfall and is
+ * the authority on which promised types were merely optional; this error is the earlier, chair-
+ * local signal that the write boundary sealed nothing at all.
+ */
+export class ModelOutputContractError extends Error {
+    slug;
+    reason;
+    constructor(slug, reason) {
+        super(`chair "${slug}" sealed no output through its write boundary: ${reason}`);
+        this.name = "ModelOutputContractError";
+        this.slug = slug;
+        this.reason = reason;
+    }
+}
 /**
  * Walk forward from `start` (which must be a `{`) honouring JSON string literals and
  * backslash escapes, so only STRUCTURAL braces move the depth counter. Returns the index
@@ -387,6 +432,120 @@ export function extractOptionsForChair(sealTypes, schema) {
     const props = schemaPropertyNames(schema);
     return props.length > 0 ? { expectKeys: props } : { requireUnambiguous: true };
 }
+// ───────────────────── output_write capture (the write-boundary seal path) ─────────────────────
+//
+// A model chair on the output_write-seal path does NOT print a final-text answer — it SEALS each
+// output in-band by calling `output_write`, whose payload the engine adjudicates against the full
+// contract (validate-mode, returning the verdict in-band so the agent self-corrects). This reads
+// those calls back out of the child's stream-json stdout: the payload of each SUCCESSFUL
+// output_write call (a tool_use whose tool_result was not an error) is what the chair sealed, and
+// the runtime's own boundary seals it exactly once. Because the agent corrects a rejected write by
+// calling again, the LAST non-errored call per type is the one that passed.
+/** The name a chair's `output_write` grant is advertised under in the spawn (mcp__<server>__<tool>),
+ *  plus the bare slug for a legacy pass-through invoker. Matched by suffix so either resolves. */
+function isOutputWriteToolName(name) {
+    return name === "output_write" || name.endsWith("__output_write");
+}
+/**
+ * Extract the chair's sealed payloads from a stream-json stdout, keyed by the chair's seal types.
+ * Returns the blob shape the runtime already consumes (a key per domain_type, or the bare data for
+ * a lone single-output write), so executeChair seals it through its one boundary unchanged.
+ */
+/** A child that exited non-zero, carrying the stdout it produced before dying.
+ *
+ *  The stream is not incidental to the error — for a chair stopped by its tool budget it holds
+ *  validated payloads, and discarding it destroys work the engine had already adjudicated as good.
+ *  Exported because the injected-run seam (`opts.run`) is how tests reproduce a non-zero exit. */
+export class ChildExitError extends Error {
+    stdout;
+    constructor(message, stdout) {
+        super(message);
+        this.stdout = stdout;
+        this.name = "ChildExitError";
+    }
+}
+/** The result subtype the CLI reports when `--max-turns` cut the run off.
+ *
+ *  This is the ONE non-success subtype whose stream is still worth reading, and the distinction is
+ *  the whole of the policy: a budget stop says "the agent was interrupted", while every other error
+ *  subtype says "what the agent produced is unreliable". Writes survive the first and must not
+ *  survive the second. */
+const BUDGET_STOP_SUBTYPE = "error_max_turns";
+/** Rewrite `--max-turns` to the reserve. The continuation gets the EXTENSION as its whole budget,
+ *  not a second full allowance — otherwise the grant silently doubles the chair's cost ceiling. */
+function withMaxTurns(args, turns) {
+    const out = [...args];
+    const i = out.indexOf("--max-turns");
+    if (i >= 0 && i + 1 < out.length)
+        out[i + 1] = String(turns);
+    else
+        out.push("--max-turns", String(turns));
+    return out;
+}
+/** Swap the prompt a built arg list carries.
+ *
+ *  `-p` is a boolean flag with the prompt as a POSITIONAL that follows it — except on the
+ *  large-prompt path, where the positional is dropped and the text goes to stdin instead. A
+ *  continuation has to replace whichever form is in play, and the two are not interchangeable:
+ *  editing only the stdin text would re-send the ORIGINAL prompt to a small-prompt chair, which
+ *  reads as the engine ignoring its own grant. */
+function withPrompt(args, prompt) {
+    const out = [...args];
+    const i = out.indexOf("-p");
+    if (i < 0)
+        return out;
+    const positionalFollows = i + 1 < out.length && !out[i + 1].startsWith("-");
+    if (positionalFollows)
+        out[i + 1] = prompt;
+    return out;
+}
+export function captureOutputWrites(stdout, sealTypes) {
+    const writes = [];
+    const errored = new Set();
+    for (const raw of stdout.split("\n")) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        let e;
+        try {
+            e = JSON.parse(line);
+        }
+        catch {
+            continue;
+        }
+        const type = typeof e["type"] === "string" ? e["type"] : "";
+        const msg = e["message"];
+        if ((type === "assistant" || type === "user") && msg && typeof msg === "object") {
+            const content = msg.content ?? [];
+            for (const b of content) {
+                const bt = String(b["type"] ?? "");
+                if (bt === "tool_use" && isOutputWriteToolName(String(b["name"] ?? ""))) {
+                    const input = (b["input"] && typeof b["input"] === "object" ? b["input"] : {});
+                    writes.push({ id: String(b["id"] ?? ""), domain_type: String(input["domain_type"] ?? ""), data: input["data"] });
+                }
+                else if (bt === "tool_result" && b["is_error"] === true) {
+                    errored.add(String(b["tool_use_id"] ?? ""));
+                }
+            }
+        }
+    }
+    const passed = writes.filter((w) => !w.id || !errored.has(w.id));
+    const byType = new Map();
+    for (const w of passed)
+        byType.set(w.domain_type, w.data); // last non-errored write per type wins
+    const blob = {};
+    for (const t of sealTypes) {
+        if (byType.has(t))
+            blob[t] = byType.get(t);
+    }
+    // Single-output chairs may seal with an empty/other domain_type (buildPrompt names it, but a
+    // model can still omit it). If nothing matched by name and exactly one output was sealed, that
+    // lone payload IS the single output — key it under the promised type.
+    if (sealTypes.length === 1 && blob[sealTypes[0]] === undefined && passed.length > 0) {
+        blob[sealTypes[0]] = passed[passed.length - 1].data;
+    }
+    return blob;
+}
 // The wall-clock bound on one chair's spawn. A tool-granted child has no inherent
 // terminus (it can search/loop), and the gig runs the spawn synchronously — so without
 // this bound one wedged child wedges the whole server. SIGKILL, not SIGTERM: a
@@ -515,6 +674,24 @@ export function makeClaudeInvoker(opts = {}) {
     // running engine always resolves + fails closed.
     const resolutionEnabled = opts.toolProviders !== undefined || opts.mcpServerConfigs !== undefined;
     const abortGraceMs = opts.abort_grace_ms ?? DEFAULT_ABORT_GRACE_MS;
+    const sealViaOutputWrite = opts.sealVia === "output_write";
+    // A reserve is a grant, so an absent or nonsensical one grants nothing rather than defaulting to
+    // some house number — an extension the author did not ask for is spend they did not authorise.
+    // #turn-budget — resolved PER INVOCATION so the chair-scoped reserve (ctx.turn_reserve, the pool-
+    // capped offer the runtime threads) wins over the invoker-level default (opts.turn_reserve). Both
+    // pass through the identical > 0 floor. ctx.turn_reserve === 0 (a declared chair whose pool was
+    // dry) is a hard zero, NOT a fall-through to opts — 0 is not nullish, so `??` stops there.
+    const resolveReserveTurns = (ctxReserve) => {
+        const src = ctxReserve ?? opts.turn_reserve;
+        return Number.isFinite(src) && (src ?? 0) > 0 ? Math.floor(src) : 0;
+    };
+    // The core type each domain type extends — the `core_type` the agent must pass to output_write.
+    const coreTypeOf = (slug) => {
+        if (CORE_TYPES.includes(slug))
+            return slug;
+        const dt = opts.registry?.listTypes().find((t) => t.slug === slug);
+        return dt ? dt.extends : "";
+    };
     return async (ctx) => {
         // #250 — a chair whose gig is already cancelled spends nothing: no prompt, no mcp-config,
         // no spawn. This is the cheapest point on the whole cancellation chain.
@@ -546,6 +723,34 @@ export function makeClaudeInvoker(opts = {}) {
             resolvedMcpServers = resolved.mcpServers;
             effectiveAllowed = resolved.effectiveAllowed;
         }
+        // VENUE CONFINEMENT BY CONSTRUCTION. When the dispatch path resolved a room for this chair
+        // (ctx.realization + ctx.venue both threaded by runGig), the spawn reflects the realization:
+        //  - `--allowedTools` carries EXACTLY venueEffectiveTools(agent, venue) — the SAME shared oracle
+        //    the compose-time R10 check refuses against (src/chart.ts), never a re-inlined intersection
+        //    and never the un-intersected grant, so runtime enforcement and compose-time refusal cannot
+        //    drift.
+        //  - the child env is the realization's deny-by-default allowlist (SeatRealization.env, `{}` when
+        //    the surface admits nothing), so an undeclared ambient credential never reaches the child.
+        // Narrowed BEFORE the in-band-seal block below, so the engine's own output_write grant — engine
+        // mechanism, not an optional capability — is re-added on top of the room's ceiling. Absent on
+        // either field → the un-narrowed path above stands and no child env is constructed (INV10).
+        let childEnv;
+        if (ctx.realization && ctx.venue) {
+            effectiveAllowed = venueEffectiveTools(ctx.agent, ctx.venue);
+            const seat = ctx.realization.seats.find((s) => s.agent_slug === ctx.agent.slug);
+            childEnv = seat?.env ?? {};
+        }
+        // WIRE THE IN-BAND SEAL. A model chair on the output_write-seal path must be able to CALL
+        // output_write regardless of what it declared in allowed_tools — the seal is engine mechanism,
+        // not an optional capability. Bridge the engine's own MCP server into the spawn and add the
+        // output_write grant so the child can reach it. Gated on the engine server config being wired
+        // (bootstrapServerDeps always supplies it); a bare/test invoker without it captures from the
+        // injected stream instead of a real spawn, so it needs no grant.
+        const engineServerCfg = (opts.mcpServerConfigs ?? {})[ENGINE_MCP_SERVER];
+        if (sealViaOutputWrite && engineServerCfg !== undefined) {
+            resolvedMcpServers = { ...resolvedMcpServers, [ENGINE_MCP_SERVER]: engineServerCfg };
+            effectiveAllowed = [...new Set([...(effectiveAllowed ?? []), OUTPUT_WRITE_TOOL])];
+        }
         const schemaOf = (slug) => promptSchemaFor(opts.registry, slug);
         // #174 — schemas follow the chair's promised subset (ctx.output_types), not the agent's
         // whole catalogue; legacy ctx without it falls back to the agent's full output_types.
@@ -557,7 +762,18 @@ export function makeClaudeInvoker(opts = {}) {
         const outputSchemas = sealTypes.length > 1
             ? Object.fromEntries(sealTypes.map((t) => [t, schemaOf(t)]))
             : undefined;
-        const prompt = buildPrompt(ctx, schema, outputSchemas);
+        // The in-band seal directive: present only when this invoker seals via output_write AND the
+        // runtime threaded a gig_id (the write needs it). Absent → the legacy text-seal Task layer.
+        const seal = sealViaOutputWrite && ctx.gig_id
+            ? {
+                via: "output_write",
+                gig_id: ctx.gig_id,
+                agent_slug: ctx.agent.slug,
+                phase: ctx.phase,
+                core_by_type: Object.fromEntries(sealTypes.map((t) => [t, coreTypeOf(t)])),
+            }
+            : undefined;
+        const prompt = buildPrompt(ctx, schema, outputSchemas, seal);
         // #221 — the key signal for candidate selection, derived from what we just resolved.
         // Threaded into BOTH extract calls below; threading only the injected-run one would
         // leave every real chair unscored.
@@ -567,45 +783,131 @@ export function makeClaudeInvoker(opts = {}) {
         // the base map (opts.mcpServers) + the per-agent servers its grants resolved to (#185).
         const servers = { ...(opts.mcpServers ?? {}), ...resolvedMcpServers };
         const parent = opts.parent_session_id;
-        // Inject parent_session_id env into every named server so children seal lineage.
-        const enriched = parent
-            ? Object.fromEntries(Object.entries(servers).map(([name, def]) => {
-                const d = (def && typeof def === "object" ? def : {});
-                const env = (d["env"] && typeof d["env"] === "object" ? d["env"] : {});
-                return [name, { ...d, env: { ...env, COLTRANE_PARENT_SESSION_ID: parent } }];
-            }))
-            : servers;
+        // Per-server env additions: parent_session_id into every server (so children seal lineage), and
+        // COLTRANE_OUTPUT_WRITE_MODE=validate into the ENGINE server on the output_write-seal path — so
+        // the child's coltrane server ADJUDICATES the chair's in-band output_write calls against the
+        // full seal predicate and returns the verdict, without persisting (the runtime is the one
+        // sealer, so this is what keeps the output sealed exactly once).
+        const envFor = (name) => ({
+            ...(parent ? { COLTRANE_PARENT_SESSION_ID: parent } : {}),
+            ...(sealViaOutputWrite && name === ENGINE_MCP_SERVER ? { COLTRANE_OUTPUT_WRITE_MODE: "validate" } : {}),
+        });
+        const enriched = Object.fromEntries(Object.entries(servers).map(([name, def]) => {
+            const additions = envFor(name);
+            if (Object.keys(additions).length === 0)
+                return [name, def];
+            const d = (def && typeof def === "object" ? def : {});
+            const env = (d["env"] && typeof d["env"] === "object" ? d["env"] : {});
+            return [name, { ...d, env: { ...env, ...additions } }];
+        }));
         writeFileSync(cfgPath, JSON.stringify({ mcpServers: enriched }));
         try {
             const a = ctx.agent;
+            // #turn-budget — the reserve the invoker will grant on a budget stop, chair-scoped first.
+            const reserveTurns = resolveReserveTurns(ctx.turn_reserve);
             // #237 — a shallow run depth tightens the turn cap; it never widens the agent's own.
             const depthCap = ctx.depth ? DEPTH_MAX_TOOL_CALLS[ctx.depth] : undefined;
+            // #turn-budget — resolve chair > agent > engine default, THEN let a shallow depth cap tighten
+            // (never widen). `ctx.turn_budget === 0` is a deliberate hard floor and does NOT fall through
+            // (0 is not nullish); absent falls to the agent's own cap, then the CLI default (undefined →
+            // no --max-turns emitted at all).
+            const resolvedBudget = ctx.turn_budget ?? a.max_tool_calls;
             const maxToolCalls = depthCap === undefined
-                ? a.max_tool_calls
-                : Math.min(depthCap, a.max_tool_calls ?? depthCap);
+                ? resolvedBudget
+                : Math.min(depthCap, resolvedBudget ?? depthCap);
+            // Run ONE invocation and return the child's raw stdout. Custom run (tests): the returned
+            // string IS the transcript (a bare JSON blob on the text path, a stream-json transcript on
+            // the output_write path). Default: stream-json so the child's tool calls / reasoning are
+            // observable LIVE, teed to ctx.onEvent.
             const baseArgs = buildInvokerArgs(prompt, cfgPath, {
                 model: resolveModel(a.model_tier, opts.model),
                 allowed_tools: effectiveAllowed,
                 disallowed_tools: [...(a.disallowed_tools ?? []), ...codeToolDenials(a.code_tool_access)],
                 max_tool_calls: maxToolCalls,
             });
-            // Custom run (tests): plain mode, the returned string IS the JSON blob — no streaming.
-            if (customRun)
-                return extractJson(await customRun(bin, baseArgs, spawnBounds), extractOpts);
-            // Default: stream-json so the child's tool calls / reasoning are observable LIVE. Each
-            // event is forwarded to ctx.onEvent (the runtime tees it to the gig's per-chair log);
-            // the final result text is extracted from the stream and parsed into the typed output.
-            const args = [...baseArgs, "--output-format", "stream-json", "--verbose"];
-            // #250 level 3 — the cancellation signal and grace window reach the spawn, so an
-            // aborted gig actually kills its chair child (and never spawns one if already aborted).
-            const stdout = await spawnStreaming(bin, args, spawnBounds, ctx.onEvent, ctx.signal, abortGraceMs, promptViaStdin(prompt) ? prompt : undefined);
+            // ONE invocation only — on the output_write path the agent self-corrects a rejected write
+            // WITHIN this single run (each output_write rejection returns in-band and it calls again),
+            // and on the text path there is a single answer. Either way, the invoker never re-prompts.
+            // A chair stopped by its TOOL BUDGET is not a chair that failed. `--max-turns` cuts the run
+            // off mid-flight, and everything it had already written through the in-band boundary was
+            // adjudicated against the full seal predicate at the moment of writing — those are validated
+            // payloads, not the partial reasoning the error subtypes exist to catch. Discarding them
+            // destroyed real work and billed for it: one observed sweep landed nine sealed lineage-hits,
+            // satisfied its output_contract, and was reported as a failure with nothing kept.
+            //
+            // So the budget stop is caught HERE, and only here: the stream is recovered, and the decision
+            // about whether anything survives is left to the seal path below, which is the only place that
+            // knows what passed. Every other non-zero exit still propagates untouched.
+            const runOnce = async (args, text) => customRun
+                ? await customRun(bin, [...args], spawnBounds, childEnv)
+                : await spawnStreaming(bin, [...args, "--output-format", "stream-json", "--verbose"], spawnBounds, ctx.onEvent, ctx.signal, abortGraceMs, promptViaStdin(text) ? text : undefined, childEnv);
+            /** Run, and hand back the stream even when the child died on its turn cap. */
+            const runTolerantOfBudgetStop = async (args, text) => {
+                try {
+                    return { stdout: await runOnce(args, text), budgetStopped: false };
+                }
+                catch (e) {
+                    const recoverable = seal !== undefined &&
+                        e instanceof ChildExitError &&
+                        finalText(e.stdout).errorSubtype === BUDGET_STOP_SUBTYPE;
+                    if (!recoverable)
+                        throw e;
+                    return { stdout: e.stdout, budgetStopped: true };
+                }
+            };
+            let { stdout, budgetStopped } = await runTolerantOfBudgetStop(baseArgs, prompt);
+            // Every stream whose writes count toward the seal. Diverges from `stdout` only when a reserve
+            // was granted, which is the one case where a chair's output spans more than one invocation.
+            let sealStdout = stdout;
+            // THE RESERVE GRANT. The chair spent its declared budget; rather than losing whatever it was
+            // mid-way through, it is told where it stands and given a bounded extension to close out.
+            // Once. The continuation names what already sealed so the chair does not redo it, and says
+            // plainly that nothing follows — a chair that believes another extension is coming will spend
+            // this one reaching rather than landing.
+            if (budgetStopped && reserveTurns > 0 && seal !== undefined) {
+                const sealedSoFar = captureOutputWrites(stdout, sealTypes);
+                const already = Object.keys(sealedSoFar);
+                ctx.onEvent?.({
+                    type: "budget_reserve_granted",
+                    raw: { agent: a.slug, reserve_turns: reserveTurns, sealed_before_grant: already },
+                });
+                const continuation = `You reached your turn budget and were stopped mid-run. You are now in RESERVE: ` +
+                    `${reserveTurns} turns remain and this is the LAST extension — it will not be extended ` +
+                    `again, so land the work rather than reaching for more.\n\n` +
+                    (already.length > 0
+                        ? `Already sealed through the write boundary, do NOT redo: [${already.join(", ")}].\n\n`
+                        : `Nothing sealed yet.\n\n`) +
+                    `Close out now: seal what you already have, and state plainly what you did NOT reach so ` +
+                    `the record shows the boundary instead of implying coverage.\n\n${prompt}`;
+                const reserveArgs = withPrompt(withMaxTurns(baseArgs, reserveTurns), continuation);
+                const second = await runTolerantOfBudgetStop(reserveArgs, continuation);
+                // Two streams, two different questions, and conflating them is a bug: the OUTCOME (did the
+                // run complete?) is the last pass's to answer, while the WRITES are cumulative — the first
+                // pass's payloads passed the boundary too, and a continuation that sealed nothing must not
+                // erase them. Concatenating for both would let the first pass's error_max_turns result event
+                // outrank the second's success and fail a run that finished.
+                sealStdout = `${stdout}\n${second.stdout}`;
+                stdout = second.stdout;
+                budgetStopped = second.budgetStopped;
+            }
+            else if (budgetStopped && reserveTurns === 0 && seal !== undefined) {
+                // #turn-budget — the chair hit its budget and the pool had nothing left to extend it (an
+                // empty reserve). Keep-sealed-writes below is unchanged, but the starvation is now VISIBLE:
+                // emit a denial so a parent watching the stream — and the runtime's draw ledger — can
+                // attribute it, rather than a silent no-op that reads like a chair that simply finished.
+                ctx.onEvent?.({
+                    type: "budget_reserve_denied",
+                    raw: { agent: a.slug, requested: ctx.turn_reserve ?? opts.turn_reserve ?? 0, pool_remaining: 0 },
+                });
+            }
             const outcome = finalText(stdout);
-            // #223 — the child reported an error result. Both discriminators are required, and
-            // both are verified against the CLI (see the note on StreamOutcome): `subtype` for a
-            // run that did not complete, `is_error` for an API-error payload riding subtype
-            // "success". Neither is a chair answer, and the CLI exits 0 for the subtype cases —
-            // so without this the partial reasoning seals as if it had succeeded.
-            if (outcome.errorSubtype !== undefined) {
+            // #223 — the child reported an error result. `subtype` catches a run that did not complete;
+            // `is_error` catches an API-error payload riding subtype "success". The CLI exits 0 for both,
+            // so without this the partial reasoning seals as if it had succeeded. Applies to both paths.
+            // A recovered budget stop reaches here with its subtype still set; that is expected and is
+            // not an error for the seal path. The text path gets no such reprieve — its payload IS the
+            // final answer text, and a truncated run's text is exactly the partial reasoning this guards.
+            if (outcome.errorSubtype !== undefined && !budgetStopped) {
                 throw new Error(`claude ended with result subtype "${outcome.errorSubtype}" — the run did not ` +
                     `complete, so any text it emitted is partial reasoning, not an answer`);
             }
@@ -613,9 +915,41 @@ export function makeClaudeInvoker(opts = {}) {
                 throw new Error(`claude flagged its result with is_error — the payload is an error message, not an ` +
                     `answer: ${outcome.apiErrorText.slice(0, 300)}`);
             }
-            // #222 — the stream parsed but carried no answer at all (e.g. only a system/init
-            // event). Report THAT, with the raw stdout as evidence, instead of blaming the model
-            // for emitting no JSON.
+            if (seal) {
+                // THE IN-BAND WRITE BOUNDARY. The chair sealed each output by calling output_write, whose
+                // payload the engine adjudicated against the FULL seal predicate (checkWritable, run in
+                // validate-mode) and whose rejection it corrected in-band. Capture the payloads that
+                // PASSED; the runtime (executeChair) then seals them through its own boundary exactly once.
+                // A chair that got nothing past the boundary produced nothing — fail here, legibly.
+                const blob = captureOutputWrites(sealStdout, sealTypes);
+                if (Object.keys(blob).length === 0) {
+                    throw new ModelOutputContractError(a.slug, budgetStopped
+                        ? `ran out of tool budget (max_tool_calls) before any output_write passed the write ` +
+                            `boundary for [${sealTypes.join(", ")}] — nothing was salvageable`
+                        : `no output_write call passed the write boundary for [${sealTypes.join(", ")}]`);
+                }
+                // The stop is REPORTED, never swallowed. What survived is real and sealed; what the agent
+                // would have gone on to find is unknown, and a caller reading this chair's output as a
+                // complete sweep would be reading a truncation as a finding.
+                if (budgetStopped) {
+                    ctx.onEvent?.({
+                        type: "budget_stop",
+                        raw: {
+                            agent: a.slug,
+                            max_tool_calls: a.max_tool_calls,
+                            sealed_types: Object.keys(blob),
+                            note: "the chair exhausted its tool budget; the outputs it had already passed through " +
+                                "the write boundary were kept, and the sweep is TRUNCATED, not complete",
+                        },
+                    });
+                }
+                return blob;
+            }
+            // TEXT-SEAL PATH (default; every injected-run test). No in-band tool surface, so the payload
+            // is the child's final answer text; the runtime's own seal is this path's write boundary and
+            // its full checkWritable adjudicates the extracted payload.
+            // #222 — the stream parsed but carried no answer at all. Report THAT, with the raw stdout as
+            // evidence, rather than blaming the model for emitting no JSON.
             if (outcome.text.trim() === "") {
                 throw new ModelOutputParseError("the model produced no answer — the stream carried no result text and no assistant text", 0, stdout);
             }
@@ -639,7 +973,10 @@ export function makeClaudeInvoker(opts = {}) {
 // nothing holds is a process nothing can stop.
 function spawnStreaming(bin, args, bounds, onEvent, signal, abortGraceMs = DEFAULT_ABORT_GRACE_MS, 
 /** The prompt, when it is too large for the command line. Written to the child's stdin. */
-stdinPayload) {
+stdinPayload, 
+/** The venue → dispatch wire's deny-by-default child env. When present it REPLACES the inherited
+ *  process.env (no ambient credential leaks into a confined child); absent = inherit, unchanged. */
+childEnv) {
     return new Promise((resolve, reject) => {
         if (signal?.aborted) {
             reject(new Error(`chair child not spawned — gig aborted (${abortReasonText(signal)})`));
@@ -648,7 +985,7 @@ stdinPayload) {
         // stdin is a pipe ONLY when a payload is going down it. Leaving it open otherwise would
         // change the child's TTY detection for every existing caller.
         const stdio = [stdinPayload === undefined ? "ignore" : "pipe", "pipe", "pipe"];
-        const child = spawn(bin, [...args], { stdio });
+        const child = spawn(bin, [...args], { stdio, ...(childEnv ? { env: childEnv } : {}) });
         // Slots 1 and 2 are literally "pipe" above, so both streams exist. Only slot 0 varies,
         // and widening it costs the compiler the overload that proved this.
         const childOut = child.stdout;
@@ -723,8 +1060,12 @@ stdinPayload) {
             const tail = buf.trim();
             buf = "";
             forwardLine(tail);
+            // The stdout travels WITH the failure. A non-zero exit used to discard it, which threw away
+            // the one thing a budget-stopped chair leaves behind: output_write calls that already passed
+            // the engine's write boundary. Whether those are recoverable is a decision for the caller,
+            // which knows the seal mode and the result subtype; it cannot make it without the stream.
             if (code !== 0)
-                reject(new Error(`claude exited ${code}: ${stderr.slice(0, 500)}`));
+                reject(new ChildExitError(`claude exited ${code}: ${stderr.slice(0, 500)}`, stdout));
             else
                 resolve(stdout);
         });