aiden-runtime 4.1.5 → 4.6.0

package/dist/core/v4/subagent/fanout.js

@@ -36,21 +36,22 @@
  *   - destructive tool exposure: caller filters the schemas array
  *     based on `AIDEN_SUBAGENT_ALLOW_DESTRUCTIVE`
  *
- * The orchestrator itself is INTENTIONALLY decoupled from
- * AidenAgent — it takes a `runChild` callback that knows how to run
- * one subagent. The tool wrapper at tools/v4/subagent/subagentFanout
- * supplies the production callback (which constructs an AidenAgent);
- * tests inject a stub that returns canned strings without any
- * provider plumbing. This is what made the offline smoke tractable.
+ * v4.6 Phase 2Q-A — the orchestrator was previously decoupled from
+ * AidenAgent via a `runChild` callback (one closure per fanout call
+ * built the child agent). Post-2Q-A every child flows through the
+ * `spawnSubAgent` primitive, so the legacy `runChild` callback is
+ * gone (deleted in 2R). Behavioural test fakes inject a stub
+ * `SpawnSubAgentDeps` (real `toolRegistry` + mock provider) — see
+ * `tests/v4/subagent/fanout.behavioral.test.ts` for the pattern.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runFanout = runFanout;
-const node_crypto_1 = require("node:crypto");
 const factory_1 = require("../logger/factory");
 const budget_1 = require("./budget");
 const providerRotation_1 = require("./providerRotation");
 const merger_1 = require("./merger");
 const diagnostics_1 = require("./diagnostics");
+const spawnSubAgent_1 = require("./spawnSubAgent");
 // ── Orchestrator ─────────────────────────────────────────────────────────
 async function runFanout(opts) {
     const logger = (opts.logger ?? (0, factory_1.noopLogger)()).child('subagent');
@@ -103,19 +104,21 @@ async function runFanout(opts) {
     const children = [];
     for (let i = 0; i < opts.n; i += 1) {
         const provider = rotation.assignments[i];
-        const prompt = opts.mode === 'ensemble'
-            ? opts.query
-            : buildPartitionPrompt(opts.tasks[i]);
-        const role = opts.mode === 'partition' ? opts.tasks[i].role : undefined;
-        children.push(spawnOne({
+        const task = opts.mode === 'partition' ? opts.tasks[i] : null;
+        const role = task?.role;
+        children.push(spawnViaPrimitive({
             index: i,
-            prompt,
+            query: opts.mode === 'ensemble' ? opts.query : task.goal,
+            context: task?.context,
             role,
             provider,
+            singleProviderWarning: rotation.singleProviderWarning,
             maxIterations: budget.maxIterations,
             perTimeoutMs: budget.perSubagentTimeoutMs,
             wallSignal: wallController.signal,
-            runChild: opts.runChild,
+            spawnDeps: opts.spawnDeps,
+            parentRunId: opts.parentRunId,
+            parentSessionId: opts.parentSessionId,
             logger: logger.child(`#${i}:${provider.providerId}`),
             now,
         }));
@@ -157,60 +160,81 @@ async function runFanout(opts) {
     });
     return { results, merged: merge.merged, diagnostics };
 }
-async function spawnOne(args) {
+/**
+ * Spawn one child via the `spawnSubAgent` primitive and adapt its
+ * envelope to the merger's `SubagentResult` shape. Centralises the
+ * fanout-layer → primitive-layer conversion in one place — every
+ * call site goes through here so a future envelope-shape change
+ * has a single edit point.
+ *
+ * Envelope → SubagentResult mapping:
+ *   - `envelope.summary` → `output` (empty string on failure;
+ *      the merger uses `output.length === 0` for the failed test).
+ *   - `envelope.error`   → `error` (undefined when ok).
+ *   - `envelope.metrics.durationMs` → ignored; we capture wall-clock
+ *      at this layer for diagnostics consistency with v4.1's shape.
+ */
+async function spawnViaPrimitive(args) {
     const startedAt = args.now();
-    // Per-child controller, aborted on wall-cap OR per-child timeout.
-    const childController = new AbortController();
-    const timer = setTimeout(() => childController.abort(), args.perTimeoutMs);
-    const wallHandler = () => childController.abort();
-    if (args.wallSignal.aborted)
-        childController.abort();
-    else
-        args.wallSignal.addEventListener('abort', wallHandler, { once: true });
-    const id = (0, node_crypto_1.randomUUID)();
     args.logger.info('child: spawned', {
-        id,
         provider: `${args.provider.providerId}:${args.provider.modelId}`,
         role: args.role,
         timeoutMs: args.perTimeoutMs,
     });
-    let output = '';
-    let error;
+    // v4.6 Phase 2Q-A-FIX — only forward the per-spawn provider
+    // override when rotation has real diversity (>= 2 distinct
+    // providerIds). For single-provider pools, every child would be
+    // assigned the same providerId, so the override path adds nothing
+    // — and worse, it trips 2P's `resolveChildProvider` rejection when
+    // the parent is a non-FallbackAdapter ("single-provider
+    // configuration" branch). Omitting it lets the child inherit the
+    // parent's adapter, which is the correct effective behavior.
+    const spec = {
+        goal: args.role ? `[role: ${args.role}] ${args.query}` : args.query,
+        context: args.context,
+        maxIterations: args.maxIterations,
+        timeoutMs: args.perTimeoutMs,
+        provider: args.singleProviderWarning ? undefined : args.provider.providerId,
+    };
+    let envelope;
     try {
-        output = await args.runChild({
-            index: args.index,
-            prompt: args.prompt,
-            role: args.role,
-            provider: args.provider,
-            signal: childController.signal,
-            maxIterations: args.maxIterations,
-            logger: args.logger,
+        envelope = await (0, spawnSubAgent_1.spawnSubAgent)(spec, args.spawnDeps, {
+            signal: args.wallSignal,
+            parentRunId: args.parentRunId,
+            parentSessionId: args.parentSessionId,
         });
     }
     catch (err) {
-        error = err instanceof Error ? err.message : String(err);
-        if (childController.signal.aborted) {
-            error = `aborted (timeout=${args.perTimeoutMs}ms or parent abort): ${error}`;
-        }
-        args.logger.warn('child: errored', { error });
-    }
-    finally {
-        clearTimeout(timer);
-        args.wallSignal.removeEventListener('abort', wallHandler);
+        // spawnSubAgent's contract says it never throws — but defend in
+        // depth: a thrown error from the primitive would otherwise sink
+        // the whole Promise.all, which would silently kill sibling
+        // children. Surface as a failed SubagentResult instead.
+        const error = err instanceof Error ? err.message : String(err);
+        args.logger.warn('child: primitive threw', { error });
+        return {
+            index: args.index,
+            providerId: args.provider.providerId,
+            modelId: args.provider.modelId,
+            output: '',
+            error,
+            elapsedMs: args.now() - startedAt,
+        };
     }
     const elapsedMs = args.now() - startedAt;
-    args.logger.info('child: done', { elapsedMs, ok: !error && output.length > 0 });
+    const error = envelope.error ?? undefined;
+    args.logger.info('child: done', {
+        elapsedMs,
+        ok: envelope.ok,
+        status: envelope.status,
+        exitReason: envelope.exitReason,
+        childRunId: envelope.childRunId,
+    });
     return {
         index: args.index,
         providerId: args.provider.providerId,
         modelId: args.provider.modelId,
-        output: error ? '' : output,
+        output: envelope.ok ? (envelope.summary ?? '') : '',
         error,
         elapsedMs,
     };
 }
-function buildPartitionPrompt(task) {
-    const role = task.role ? `Role: ${task.role}\n` : '';
-    const context = task.context ? `\nContext:\n${task.context}\n` : '';
-    return `${role}Goal: ${task.goal}${context}`;
-}

package/dist/core/v4/subagent/spawnPause.js

@@ -0,0 +1,191 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/spawnPause.ts — v4.6 Phase 3A.
+ *
+ * Operator kill-switch for sub-agent spawning. When PAUSED, any new
+ * `spawn_sub_agent` or `subagent_fanout` invocation returns a typed
+ * failure envelope (`errorCode: 'SUBAGENT_SPAWN_PAUSED'`) BEFORE any
+ * runs row is written, child agent built, or provider hit. In-flight
+ * children continue uninterrupted — the gate is at tool-handler
+ * entry only.
+ *
+ * Storage: a file marker at `$aidenHome/spawn.paused` (the
+ * `paths.root` returned by `resolveAidenPaths()`). This choice
+ * differs deliberately from the reference multi-agent system, whose
+ * pause flag is an in-process boolean — Aiden's REPL, daemon, and
+ * MCP server can all coexist on the same machine, so a single
+ * shared marker file is the cheapest way to coordinate pause state
+ * across all three runtimes. The marker survives process restart;
+ * the boot card surfaces a "spawn-paused" indicator so an operator
+ * who forgot they paused last week doesn't sit confused.
+ *
+ * Marker format: a single-line JSON document
+ *   { pausedAt: number; reason: string | null; pausedBy: string }
+ *
+ * Atomic writes: every `pause()` writes to a sibling `.tmp` path
+ * and renames atomically so a concurrent reader can never observe
+ * a half-written file. `status()` tolerates an unreadable marker
+ * (returns `{paused: true}` with no metadata) rather than crashing
+ * — the marker EXISTING is the durable fact; the JSON payload is
+ * forensic detail.
+ *
+ * Module-level singleton: `initSpawnPause({aidenHome})` then
+ * `getSpawnPause()`. Mirrors the `runtimeToggles` pattern in
+ * `core/v4/runtimeToggles.ts` but does NOT route through it —
+ * runtimeToggles is config-yaml backed (no per-toggle metadata
+ * field), and the reason/pausedAt/pausedBy fields are first-class
+ * here.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpawnPauseState = void 0;
+exports.initSpawnPause = initSpawnPause;
+exports.getSpawnPause = getSpawnPause;
+exports._resetSpawnPauseForTests = _resetSpawnPauseForTests;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+// ── Implementation ───────────────────────────────────────────────────────
+const MARKER_FILENAME = 'spawn.paused';
+/**
+ * File-marker-backed pause state. Concurrent processes (REPL, daemon,
+ * MCP server) all read/write the same marker, so flipping pause from
+ * a REPL slash command is observed by an MCP-mode `subagent_fanout`
+ * call within milliseconds (next read).
+ */
+class SpawnPauseState {
+    constructor(opts) {
+        this.markerPath = node_path_1.default.join(opts.aidenHome, MARKER_FILENAME);
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /**
+     * Hot path — called at the top of every `spawn_sub_agent` and
+     * `subagent_fanout` invocation. MUST stay cheap (single
+     * `fs.existsSync`). The metadata read is deferred to `status()`.
+     *
+     * Any error (FS busy, permission, etc.) silently returns
+     * `false` — failing-open is the right default because a paused
+     * state that operators can't query/clear due to FS hiccups would
+     * brick the whole spawning surface.
+     */
+    isPaused() {
+        try {
+            return node_fs_1.default.existsSync(this.markerPath);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Apply the pause marker. Atomic via tmp-file + rename so a
+     * mid-write status read never sees corrupt JSON. Idempotent —
+     * pausing while already paused just overwrites the marker (which
+     * is the right semantic for "re-pause with a fresh reason").
+     */
+    pause(opts) {
+        const payload = {
+            pausedAt: this.now(),
+            reason: opts.reason ?? null,
+            pausedBy: opts.pausedBy,
+        };
+        const tmpPath = `${this.markerPath}.tmp`;
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(this.markerPath), { recursive: true });
+        node_fs_1.default.writeFileSync(tmpPath, JSON.stringify(payload), { encoding: 'utf8' });
+        node_fs_1.default.renameSync(tmpPath, this.markerPath);
+    }
+    /**
+     * Clear the pause marker. Idempotent — ENOENT (already resumed)
+     * is treated as success, so two operators calling resume back-
+     * to-back don't error on the second.
+     */
+    resume() {
+        try {
+            node_fs_1.default.unlinkSync(this.markerPath);
+        }
+        catch (e) {
+            const code = e.code;
+            if (code !== 'ENOENT')
+                throw e;
+        }
+    }
+    /**
+     * Read the current pause state with metadata. When the marker
+     * exists but is unreadable / malformed JSON, returns
+     * `{paused: true}` with no metadata fields — the EXISTENCE of
+     * the marker is the durable contract; the JSON payload is best-
+     * effort forensic detail.
+     */
+    status() {
+        if (!this.isPaused()) {
+            return { paused: false };
+        }
+        let raw;
+        try {
+            raw = node_fs_1.default.readFileSync(this.markerPath, 'utf8');
+        }
+        catch {
+            return { paused: true };
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return { paused: true };
+        }
+        const pausedAt = typeof parsed.pausedAt === 'number' ? parsed.pausedAt : undefined;
+        return {
+            paused: true,
+            pausedAt,
+            reason: parsed.reason ?? null,
+            pausedBy: parsed.pausedBy ?? 'unknown',
+            durationMs: pausedAt !== undefined ? Math.max(0, this.now() - pausedAt) : undefined,
+        };
+    }
+}
+exports.SpawnPauseState = SpawnPauseState;
+// ── Module-level singleton ───────────────────────────────────────────────
+let _singleton = null;
+/**
+ * Initialize the process-wide pause state. Called once at boot
+ * (REPL: `buildAgentRuntime`; daemon: dispatcher bootstrap; MCP:
+ * `wireSubagentFanout`). Subsequent calls REPLACE the singleton —
+ * tests rely on this to swap the marker dir cleanly.
+ */
+function initSpawnPause(opts) {
+    _singleton = new SpawnPauseState(opts);
+    return _singleton;
+}
+/**
+ * Read the current singleton. Throws if `initSpawnPause` hasn't
+ * been called yet — the spawn / fanout tool handlers cannot
+ * function without it, and a silent fallback to "not paused" would
+ * defeat the kill-switch's purpose. Boot wiring is responsible for
+ * calling init before any tool handler can fire.
+ *
+ * For environments that genuinely don't have a marker dir (some
+ * test contexts), call `initSpawnPause({aidenHome: <tmp>})` with
+ * a throwaway path.
+ */
+function getSpawnPause() {
+    if (!_singleton) {
+        throw new Error('spawnPause: not initialized — call initSpawnPause({aidenHome}) at boot. ' +
+            'This usually means a sub-agent tool handler fired before runtime wiring completed.');
+    }
+    return _singleton;
+}
+/**
+ * Test-only — reset the singleton so the next `initSpawnPause`
+ * call wires a fresh state. Production callers should never need
+ * this; `initSpawnPause` is already idempotent for re-init.
+ */
+function _resetSpawnPauseForTests() {
+    _singleton = null;
+}

package/dist/core/v4/subagent/spawnSubAgent.js

@@ -0,0 +1,310 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * core/v4/subagent/spawnSubAgent.ts — v4.6 Phase 1.
+ *
+ * Public spawn primitive. Synchronously runs one child agent to handle
+ * a delegated sub-task, returns a structured `SubAgentResult` envelope.
+ * NEVER throws — every error path produces an envelope with the
+ * appropriate `status` + `error` fields so the parent's LLM can
+ * reason about the failure.
+ *
+ * Contract per `docs/v4.6/phase-1-design.md` §3, §6, §8.
+ *
+ *   - Single child (Phase 1; batch is Phase 2 via subagent_fanout
+ *     refactor)
+ *   - Synchronous: the parent's tool dispatch awaits this Promise
+ *   - Cooperative cancellation: parent's AbortSignal cascades to
+ *     child via a linked AbortController
+ *   - Wall-clock timeout: hard cap via setTimeout → child interrupt
+ *   - Persistence: writes a `runs` row with `spawned_from_run_id` +
+ *     `spawned_from_session_id` linking back to the parent
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.spawnSubAgent = spawnSubAgent;
+const node_crypto_1 = require("node:crypto");
+const childBuilder_1 = require("./childBuilder");
+const factory_1 = require("../logger/factory");
+// ── Constants ─────────────────────────────────────────────────────────────
+const DEFAULT_TIMEOUT_MS = 600000;
+const MIN_TIMEOUT_MS = 1000;
+const MAX_TIMEOUT_MS = 3600000;
+const DEFAULT_MAX_ITERATIONS = 50;
+const MIN_MAX_ITERATIONS = 1;
+const MAX_MAX_ITERATIONS = 200;
+// ── Implementation ────────────────────────────────────────────────────────
+/**
+ * Spawn one child agent. Always returns an envelope; never throws.
+ *
+ * Lifecycle (per §6 state machine):
+ *
+ *   1. Generate child sessionId (flat UUID).
+ *   2. Insert `runs` row with `status: 'running'` + lineage columns.
+ *   3. Build child agent (clones FallbackAdapter, intersects toolsets,
+ *      filters blocklist, fresh ApprovalEngine with auto-deny).
+ *   4. Construct linked AbortController: parent's signal feeds into
+ *      it; a setTimeout on `timeoutMs` also aborts it.
+ *   5. Run `child.runConversation(history, { signal: childCtrl.signal })`.
+ *   6. On return / throw / timeout, classify into the envelope's
+ *      status + exitReason and update the runs row's status.
+ *   7. Clean up timer + signal listener.
+ */
+async function spawnSubAgent(spec, deps, ctx) {
+    const startedAt = Date.now();
+    // ── 1. Clamp inputs ─────────────────────────────────────────────────────
+    const maxIterations = clamp(spec.maxIterations ?? DEFAULT_MAX_ITERATIONS, MIN_MAX_ITERATIONS, MAX_MAX_ITERATIONS);
+    const timeoutMs = clamp(spec.timeoutMs ?? DEFAULT_TIMEOUT_MS, MIN_TIMEOUT_MS, MAX_TIMEOUT_MS);
+    // ── 2. Fresh sessionId + run row ────────────────────────────────────────
+    const childSessionId = (0, node_crypto_1.randomUUID)();
+    // Pre-create the child run row in 'running' state so the envelope
+    // always carries a valid childRunId — even if buildChildAgent throws.
+    let childRunId;
+    try {
+        childRunId = deps.runStore.create({
+            sessionId: childSessionId,
+            instanceId: deps.instanceId,
+            status: 'running',
+            startedAt,
+            spawnedFromRunId: ctx.parentRunId,
+            spawnedFromSessionId: ctx.parentSessionId,
+        });
+    }
+    catch (err) {
+        // Persistence failed before we even started — surface as failed
+        // envelope with a synthetic id of '0' so the contract holds.
+        return failureEnvelope({
+            childRunId: '0',
+            childSessionId,
+            error: `Failed to create child run row: ${errorMessage(err)}`,
+            durationMs: Date.now() - startedAt,
+        });
+    }
+    // ── 3. Build child agent ────────────────────────────────────────────────
+    const logger = deps.logger ?? (0, factory_1.noopLogger)();
+    let agentBundle;
+    try {
+        agentBundle = (0, childBuilder_1.buildChildAgent)({
+            ...deps,
+            // v4.6 Phase 1 observability — pass runStore + childRunId
+            // through so childBuilder can wire onToolCall → run_events
+            // for the child's tool dispatches. Both are optional in
+            // ChildBuilderDeps so unit tests of buildChildAgent stay
+            // dependency-light.
+            runStore: deps.runStore,
+            childRunId,
+            logger,
+        }, {
+            sessionId: childSessionId,
+            goal: spec.goal,
+            context: spec.context,
+            requestedToolsets: spec.toolsets,
+            maxIterations,
+            // v4.6 Phase 2P — per-spawn provider override (per design doc §12.2).
+            providerOverride: spec.provider,
+        });
+    }
+    catch (err) {
+        // v4.6 Phase 2P — distinguish provider-not-found from other build
+        // failures. ProviderNotFoundError carries the failing name + the
+        // list of valid alternatives, surfaced verbatim to the LLM in the
+        // envelope so it can pick a real provider next time. Other build
+        // failures (constructor throws, registry issues, etc.) collapse
+        // to the generic 'error' exitReason.
+        if (err instanceof childBuilder_1.ProviderNotFoundError) {
+            deps.runStore.setStatus(childRunId, 'failed', { finishReason: 'provider_not_found' });
+            return {
+                ok: false,
+                status: 'failed',
+                summary: null,
+                error: err.message,
+                exitReason: 'provider_not_found',
+                metrics: { apiCalls: 0, durationMs: Date.now() - startedAt, tokensIn: 0, tokensOut: 0 },
+                childRunId: String(childRunId),
+                childSessionId,
+            };
+        }
+        deps.runStore.setStatus(childRunId, 'failed', { finishReason: 'error' });
+        return failureEnvelope({
+            childRunId: String(childRunId),
+            childSessionId,
+            error: `Failed to build child agent: ${errorMessage(err)}`,
+            durationMs: Date.now() - startedAt,
+        });
+    }
+    // v4.6 Phase 1 observability — log the child's actual tool catalog
+    // so we can see whether the toolsets-resolution path produced a
+    // sensible set or stripped everything. The single most-load-bearing
+    // diagnostic for the "child returned 0" class of bugs.
+    const childToolNames = agentBundle.agent.tools.map((t) => t.name);
+    logger.info('spawn_sub_agent child built', {
+        childRunId: String(childRunId),
+        childSessionId,
+        toolCount: childToolNames.length,
+        toolNames: childToolNames,
+        requestedToolsets: spec.toolsets ?? null,
+        maxIterations,
+        timeoutMs,
+    });
+    // ── 4. Linked AbortController ───────────────────────────────────────────
+    // Two abort sources cascade into the child's signal:
+    //   (a) parent signal aborts — child aborts.
+    //   (b) timeoutMs elapses — child aborts.
+    // Track which one fired so we can label the envelope as
+    // 'interrupted' vs 'timeout' (the spec distinguishes them).
+    const childCtrl = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        childCtrl.abort();
+    }, timeoutMs);
+    let parentAbortHandler = null;
+    if (ctx.signal) {
+        if (ctx.signal.aborted) {
+            childCtrl.abort();
+        }
+        else {
+            parentAbortHandler = () => childCtrl.abort();
+            ctx.signal.addEventListener('abort', parentAbortHandler, { once: true });
+        }
+    }
+    const cleanupAbortWiring = () => {
+        clearTimeout(timer);
+        if (parentAbortHandler && ctx.signal) {
+            ctx.signal.removeEventListener('abort', parentAbortHandler);
+        }
+    };
+    // ── 5. Run the child ─────────────────────────────────────────────────────
+    // `child.runConversation` propagates the signal into the loop's
+    // between-iteration + pre-tool-call abort checks via the prep
+    // dispatch (commit fd62f96d).
+    let summary = null;
+    let error = null;
+    let status = 'completed';
+    let exitReason = 'completed';
+    let apiCalls = 0;
+    let tokensIn = 0;
+    let tokensOut = 0;
+    try {
+        const result = await agentBundle.agent.runConversation(agentBundle.history, { signal: childCtrl.signal });
+        apiCalls = result.turnCount; // one provider call per turn
+        tokensIn = result.totalUsage.inputTokens;
+        tokensOut = result.totalUsage.outputTokens;
+        // Classify the result per design doc §8.
+        if (result.finishReason === 'interrupted') {
+            // Distinguish timeout from parent-interrupt by which source fired.
+            if (timedOut) {
+                status = 'timeout';
+                exitReason = 'timeout';
+                error = `Sub-agent timed out after ${timeoutMs}ms (maxIterations=${maxIterations})`;
+            }
+            else {
+                status = 'interrupted';
+                exitReason = 'interrupted';
+                error = 'Parent interrupted — child did not finish in time';
+            }
+        }
+        else if (result.finishReason === 'budget_exhausted') {
+            // Hit maxIterations. If the model produced a partial final reply,
+            // we ship it as a 'completed/max_iterations' (partial summary);
+            // otherwise it's a failure.
+            if (result.finalContent && result.finalContent.length > 0) {
+                status = 'completed';
+                exitReason = 'max_iterations';
+                summary = result.finalContent;
+            }
+            else {
+                status = 'failed';
+                exitReason = 'error';
+                error = `Sub-agent hit max_iterations (${maxIterations}) without producing a summary`;
+            }
+        }
+        else if (result.finishReason === 'error') {
+            status = 'failed';
+            exitReason = 'error';
+            error = 'Sub-agent loop reported an internal error';
+        }
+        else if (result.finishReason === 'tool_loop') {
+            // TCE surfaced a tool loop — treat as a failure with structured
+            // payload buried in error string (Phase 1 doesn't yet ship the
+            // capability-card detail into the envelope).
+            status = 'failed';
+            exitReason = 'error';
+            error = `Sub-agent detected a tool loop and stopped: ${result.toolLoopCard?.title ?? 'tool_loop'}`;
+        }
+        else {
+            // 'stop' → natural completion.
+            status = 'completed';
+            exitReason = 'completed';
+            summary = result.finalContent;
+        }
+    }
+    catch (err) {
+        // child.runConversation threw — typically only happens when the
+        // provider call fails after exhausting fallback chain. Surface as
+        // a failed envelope with the error string.
+        status = 'failed';
+        exitReason = 'error';
+        error = `Sub-agent threw: ${errorMessage(err)}`;
+    }
+    finally {
+        cleanupAbortWiring();
+    }
+    // ── 6. Update run row + emit envelope ────────────────────────────────────
+    const dbStatus = status === 'completed' ? 'completed'
+        : status === 'interrupted' ? 'interrupted'
+            : 'failed';
+    deps.runStore.setStatus(childRunId, dbStatus, { finishReason: exitReason });
+    const durationMs = Date.now() - startedAt;
+    const ok = status === 'completed' && exitReason !== 'error';
+    return {
+        ok,
+        status,
+        summary,
+        error,
+        exitReason,
+        metrics: {
+            apiCalls,
+            durationMs,
+            tokensIn,
+            tokensOut,
+        },
+        childRunId: String(childRunId),
+        childSessionId,
+    };
+}
+// ── Helpers ───────────────────────────────────────────────────────────────
+function clamp(n, lo, hi) {
+    if (!Number.isFinite(n))
+        return lo;
+    return Math.max(lo, Math.min(hi, Math.floor(n)));
+}
+function errorMessage(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+/**
+ * Build a failed envelope for pre-run errors (run-row creation,
+ * agent construction). Always carries `summary: null`, `ok: false`,
+ * `status: 'failed'`, `exitReason: 'error'`.
+ */
+function failureEnvelope(opts) {
+    return {
+        ok: false,
+        status: 'failed',
+        summary: null,
+        error: opts.error,
+        exitReason: 'error',
+        metrics: {
+            apiCalls: 0,
+            durationMs: opts.durationMs,
+            tokensIn: 0,
+            tokensOut: 0,
+        },
+        childRunId: opts.childRunId,
+        childSessionId: opts.childSessionId,
+    };
+}