@aragon-agent/cli 0.6.16 → 0.6.18

package/dist/team/runtime.js

@@ -1,6 +1,6 @@
 /**
  * TeamRuntime — dispatch scheduling, budgets, the `TeamEvent` stream, abort and
- * disposal (team-subagents §3.2 / §3.5 / §3.8).
+ * disposal (team-subagents §3.2 / §3.5 / §3.8; team-overseer §3.4).
  *
  * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
  *
@@ -16,11 +16,104 @@
  * worker loops, awaited with `Promise.allSettled`. No worker abstraction, no
  * queue class, no event-loop trickery — every path is observable from the event
  * stream.
+ *
+ * THE DISPATCH SUPERVISOR (team-overseer) — a time ceiling is an inspection
+ * trigger, not a death sentence. When a supervisor is live for the dispatch,
+ * two SOFT timers per child (wall clock and event silence) fire an inspection;
+ * the supervisor decides wait / nudge / replace / abandon; THIS module applies.
+ * Lifecycle changes are funnelled exclusively through `runOne`, the only place
+ * a child's `prompt()` is awaited (I-OV1): the supervisor may steer, flag and
+ * abort, but a replacement is built by the worker loop or it is built for
+ * nobody. Without a supervisor, every path below is byte for byte the
+ * pre-feature behaviour.
  */
 import { TeamBus } from './bus.js';
 import { TEAM_LIMITS } from './limits.js';
+import { TeamOverseer, buildReplacementPrompt } from './overseer.js';
 import { shouldRetryColdStart } from './retry.js';
 import { createSubagent, defaultSubagentFactory, } from './subagent.js';
+/**
+ * The two soft timers per child (team-overseer §3.2). Timers only — no state,
+ * no decisions; the runtime applies what the supervisor decides.
+ *
+ * Every timer is `unref`'d (the `backoff` argument): a pending supervision
+ * look must not hold the process open on exit.
+ */
+class ChildSupervisor {
+    deps;
+    clocks = new Map();
+    silences = new Map();
+    /** The interval used when a decision did not name one. */
+    defaultCheckMs;
+    constructor(deps) {
+        this.deps = deps;
+        this.defaultCheckMs = Math.max(TEAM_LIMITS.overseerNextCheckMinMs, deps.firstCheckMs);
+    }
+    /** Arm (or re-arm) both windows for a child starting or restarting an attempt. */
+    start(label) {
+        this.armClock(label, this.deps.firstCheckMs);
+        this.armSilence(label);
+    }
+    /** Reset the silence window. A no-op for a child nobody is supervising. */
+    kick(label) {
+        if (this.silences.has(label))
+            this.armSilence(label);
+    }
+    rearmSilence(label) {
+        this.armSilence(label);
+    }
+    rearmClock(label, ms) {
+        this.armClock(label, ms);
+    }
+    clear(label) {
+        const clock = this.clocks.get(label);
+        if (clock !== undefined)
+            clearTimeout(clock);
+        const silence = this.silences.get(label);
+        if (silence !== undefined)
+            clearTimeout(silence);
+        this.clocks.delete(label);
+        this.silences.delete(label);
+    }
+    clearAll() {
+        for (const label of [...this.clocks.keys()])
+            this.clear(label);
+        for (const label of [...this.silences.keys()])
+            this.clear(label);
+    }
+    armClock(label, ms) {
+        const previous = this.clocks.get(label);
+        if (previous !== undefined)
+            clearTimeout(previous);
+        const timer = setTimeout(() => this.fire(label, 'clock'), ms);
+        timer.unref?.();
+        this.clocks.set(label, timer);
+    }
+    armSilence(label) {
+        const previous = this.silences.get(label);
+        if (previous !== undefined)
+            clearTimeout(previous);
+        const timer = setTimeout(() => {
+            // I-OV3: a child legitimately blocked on `team_wait` or the confirm
+            // queue re-arms quietly instead of spending an inspection on a fact the
+            // digest would only re-derive.
+            if (this.deps.isLegitimatelyBlocked(label)) {
+                this.armSilence(label);
+                return;
+            }
+            this.fire(label, 'silence');
+        }, this.deps.idleMs);
+        timer.unref?.();
+        this.silences.set(label, timer);
+    }
+    fire(label, trigger) {
+        if (trigger === 'clock')
+            this.clocks.delete(label);
+        else
+            this.silences.delete(label);
+        this.deps.onFire(label, trigger);
+    }
+}
 export class TeamRuntime {
     deps;
     listeners = new Set();
@@ -43,6 +136,16 @@ export class TeamRuntime {
      * quietly not for the others.
      */
     pendingBackoffs = new Set();
+    /**
+     * The dispatch supervisor, LIVE for the current dispatch only (team-overseer).
+     * Null when the provider is absent/disabled/off, and reset to null at every
+     * dispatch end so nothing supervision-shaped leaks across dispatches.
+     */
+    overseer = null;
+    /** The soft timers, same lifetime as `overseer`. */
+    supervision = null;
+    /** Applied interventions for the in-flight dispatch's outcome. */
+    interventions = [];
     constructor(deps) {
         this.deps = deps;
     }
@@ -65,10 +168,7 @@ export class TeamRuntime {
     // -------------------------------------------------------------------------
     // Dispatch
     // -------------------------------------------------------------------------
-    async dispatch(specs, requested, signal, 
-    /** Carried through from the normalizer so the report can state it (§3.4 /
-     *  R-6). Optional, so every existing caller compiles unchanged. */
-    extra = {}) {
+    async dispatch(specs, requested, signal) {
         this.counter += 1;
         const dispatchId = `d${this.counter}`;
         const config = this.deps.getConfig();
@@ -76,6 +176,30 @@ export class TeamRuntime {
         const startedAt = Date.now();
         this.busy = true;
         this.aborted = false;
+        this.interventions = [];
+        // THE SUPERVISOR IS CREATED PER DISPATCH and read live: provider present,
+        // provider active, policy on. `TeamOverseer.isActive()` re-checks the
+        // provider per inspection, so a mid-dispatch `/fast off` stops the next
+        // look without unwinding anything already applied.
+        this.overseer =
+            this.deps.overseer !== undefined &&
+                this.deps.overseer.active() &&
+                team.overseer
+                ? new TeamOverseer(this.deps.overseer, { startedAt })
+                : null;
+        this.supervision =
+            this.overseer !== null
+                ? new ChildSupervisor({
+                    idleMs: config.idleTimeoutMs,
+                    firstCheckMs: team.subagentTimeoutMs > 0
+                        ? team.subagentTimeoutMs
+                        : TEAM_LIMITS.overseerDefaultCheckMs,
+                    isLegitimatelyBlocked: (label) => this.isBlocked(label),
+                    onFire: (label, trigger) => {
+                        void this.inspectAndApply(dispatchId, label, trigger);
+                    },
+                })
+                : null;
         // DECLARED BEFORE THE BUS, ASSIGNED AFTER THE HANDLES. `canSend` closes over
         // this binding so it reads the LIVE array: F-4 replaces `handles[index]`
         // mid-dispatch, and a captured array or a captured handle would answer for
@@ -88,7 +212,7 @@ export class TeamRuntime {
          * Whether `label` still has a loop that could call `team_send` (F-3 / P0-2).
          *
          * NEGATIVE, over TERMINAL PHASES ONLY. "The child's phase is running" is the
-         * natural way to write this and it is wrong on the SHIPPED DEFAULTS: at
+         * natural way to write this and is wrong on the SHIPPED DEFAULTS: at
          * `maxConcurrent: 3, maxSubagents: 5`, children 4 and 5 sit in `queued` for
          * the first part of every five-way dispatch, and a wait on one of them would
          * be refused with "nobody can answer: a4 already finished". `queued` is not
@@ -131,7 +255,7 @@ export class TeamRuntime {
             confirmTools: config.confirmTools,
             ...(this.deps.humanQueue ? { humanQueue: this.deps.humanQueue } : {}),
             agentFactory: this.deps.agentFactory ?? defaultSubagentFactory,
-            ...(this.deps.resolveTier ? { resolveTier: this.deps.resolveTier } : {}),
+            ...(this.deps.review ? { review: this.deps.review } : {}),
             // Site two of two, and the omission is silent in the same way the policy
             // one above is: declaring it on `TeamRuntimeDeps` and forgetting this line
             // type-checks and forwards nothing, so every child would quietly run with
@@ -139,6 +263,10 @@ export class TeamRuntime {
             ...(this.deps.contextManagerFor
                 ? { contextManagerFor: this.deps.contextManagerFor }
                 : {}),
+            // Same conditional-spread rule: a dispatch without a supervisor builds
+            // the exact pre-feature `SubagentDeps`, and the child's idle watchdog
+            // keeps its un-lengthened ceiling (team-overseer §3.6).
+            ...(this.overseer !== null ? { overseerActive: true } : {}),
         };
         // Hoisted into a factory so a retry can build a fresh child with IDENTICAL
         // wiring (F-4). Replacing the child rather than re-prompting it is the only
@@ -147,11 +275,10 @@ export class TeamRuntime {
         // show the child its brief twice.
         const makeHandle = (spec) => createSubagent(spec, subDeps, {
             onUpdate: (run) => this.publish(dispatchId, run),
-            // `tier` rides along so `App.tsx` can pick the RIGHT cost table for this
-            // event rather than always using the lead's (§3.6 / R-7). Taken from the
-            // SPEC, which the normalizer already downgraded when the tier was
-            // unavailable, so it names the model that actually billed.
-            onUsage: (label, usage) => this.emit({ type: 'usage', dispatchId, label, usage, tier: spec.tier }),
+            onUsage: (label, usage) => this.emit({ type: 'usage', dispatchId, label, usage }),
+            // ONE KICK PER REAL AGENT EVENT, unthrottled (I-OV3): the silence
+            // window resets on evidence, not on a coalesced UI frame.
+            onActivity: () => this.supervision?.kick(spec.label),
         });
         // ASSIGNMENT, not a declaration: a `const` here would shadow the `let` above
         // the bus, `canSend` would see the empty array forever, and every peer would
@@ -179,7 +306,15 @@ export class TeamRuntime {
         // so the override only bites because `task` listens to `ctx.signal` — and a
         // second, independent timer means a signal that never arrives still ends the
         // dispatch.
-        this.dispatchTimer = setTimeout(() => this.abortAll(), team.dispatchTimeoutMs);
+        //
+        // `0` MEANS NO CEILING (main-agent parity): the dispatch lasts as long as
+        // its slowest child and only an Esc ends it early. The lead's idle
+        // watchdog is paused for the whole dispatch either way, exactly as it is
+        // for the lead's own long turns.
+        this.dispatchTimer =
+            team.dispatchTimeoutMs > 0
+                ? setTimeout(() => this.abortAll(), team.dispatchTimeoutMs)
+                : null;
         const runCtx = {
             dispatchId,
             handles,
@@ -195,24 +330,16 @@ export class TeamRuntime {
         signal?.removeEventListener('abort', onAbort);
         for (const handle of handles)
             handle.unsubscribe();
-        // SUMMED PER TIER (fast-model-tier §3.4 / R-7). One total priced at the
-        // lead's table would over-report a Haiku child under a Sonnet lead by
-        // roughly an order of magnitude — and the whole justification for delegating
-        // to a cheaper model is a number in the report this feeds.
-        // `main` IS THE COMPLEMENT OF `fast`, not an equality test. `SubagentRun.tier`
-        // is populated by `createSubagent` from the spec, but a hand-built run in a
-        // test — or a run restored from a session file written before this field
-        // existed — has it `undefined`, and `=== 'main'` would silently drop that
-        // child's spend from the total. Under-reporting is the one failure this
-        // split exists to prevent, so the default direction has to be "counted".
-        const sumTier = (tier) => handles
-            .filter((h) => (tier === 'fast' ? h.run.tier === 'fast' : h.run.tier !== 'fast'))
-            .reduce((acc, h) => ({
+        this.supervision?.clearAll();
+        this.supervision = null;
+        this.overseer = null;
+        // ONE TOTAL, AT THE LEAD'S TABLE. Every child runs the lead's own model
+        // (main-agent parity), so there is exactly one tier to sum and one price to
+        // sum it at; a split would be two answers to one question.
+        const usage = handles.reduce((acc, h) => ({
             inputTokens: acc.inputTokens + h.run.usage.inputTokens,
             outputTokens: acc.outputTokens + h.run.usage.outputTokens,
         }), { inputTokens: 0, outputTokens: 0 });
-        const fastUsage = sumTier('fast');
-        const ranFast = handles.some((h) => h.run.tier === 'fast');
         const outcome = {
             dispatchId,
             runs: handles.map((h) => ({ ...h.run, filesTouched: [...h.run.filesTouched] })),
@@ -221,11 +348,8 @@ export class TeamRuntime {
             endedAt: Date.now(),
             aborted: this.aborted,
             leadMail: bus.leadMail(),
-            usage: sumTier('main'),
-            // ABSENT when no fast child ran, which is what keeps a default session's
-            // outcome shape byte-identical to the pre-feature one.
-            ...(ranFast ? { fastUsage } : {}),
-            ...(extra.downgraded ? { downgraded: extra.downgraded } : {}),
+            interventions: this.interventions,
+            usage,
         };
         this.live = [];
         this.bus = null;
@@ -255,21 +379,41 @@ export class TeamRuntime {
     }
     /**
      * Run one child to a terminal phase, replacing it once if its very first
-     * request died on a transport error before it did anything at all (F-4).
+     * request died on a transport error before it did anything at all (F-4), and
+     * replacing it when the SUPERVISOR decides to (team-overseer §3.4).
+     *
+     * ONE LOOP, ALL LIFECYCLE: the cold-start replacement, the supervisor's
+     * replace and the post-mortem replace all swap `handles[index]` and continue
+     * THIS loop, because the await below is the only place a child is driven and
+     * a handle swapped anywhere else would never be (I-OV1).
      */
     async runOne(ctx, index) {
         const { dispatchId, handles, makeHandle, subagentTimeoutMs } = ctx;
-        for (let attempt = 0;; attempt += 1) {
+        let attempt = 0;
+        for (;;) {
+            attempt += 1;
             const handle = handles[index];
             const { run, agent } = handle;
+            // ABORTS GO THROUGH THE HANDLE (never `agent.abort()` directly): the
+            // handle sets the synchronous `abortRequested` flag the child's fast
+            // reviewer reads as its never-steer-into-a-requested-abort fact.
             run.phase = 'starting';
             run.startedAt = Date.now();
             this.publish(dispatchId, run);
+            // WITH A SUPERVISOR there is no hard wall clock on the child: the
+            // supervisor looks and decides, and the child's own (lengthened) idle
+            // watchdog is the silence backstop. WITHOUT one, the legacy hard timer —
+            // armed exactly as before, `0` meaning no ceiling.
+            const supervised = this.overseer !== null;
+            if (supervised)
+                this.supervision?.start(run.label);
             let timedOut = false;
-            const timer = setTimeout(() => {
-                timedOut = true;
-                agent.abort();
-            }, subagentTimeoutMs);
+            const timer = !supervised && subagentTimeoutMs > 0
+                ? setTimeout(() => {
+                    timedOut = true;
+                    handle.abort();
+                }, subagentTimeoutMs)
+                : null;
             try {
                 await agent.prompt(handle.spec.prompt);
             }
@@ -281,23 +425,49 @@ export class TeamRuntime {
                 run.error = err instanceof Error ? err.message : String(err);
             }
             finally {
-                clearTimeout(timer);
+                if (timer)
+                    clearTimeout(timer);
             }
-            // THE TWO ABORT EXCLUSIONS THAT MAKE THE PREDICATE SAFE. Every abort in
+            const verdict = handle.overseerVerdict ?? null;
+            // THE SUPERVISOR'S REBUILD. Same loop, fresh body, amended brief: the
+            // verdict was set and the child aborted by `inspectAndApply`; here is
+            // where the replacement is actually built and driven. `attempt` resets so
+            // the fresh body gets its own cold-start budget.
+            if (verdict !== null && verdict.action === 'replace' && !this.aborted) {
+                this.replaceChild(dispatchId, handles, index, makeHandle, handle, verdict);
+                attempt = 0;
+                continue;
+            }
+            // THE ABORT EXCLUSIONS THAT MAKE THE PREDICATE SAFE. Every abort in
             // this system reaches the provider as an aborted fetch, and `core` marks
             // an `AbortError` retryable - so Esc, `ctx.signal`, the dispatch timeout
-            // (all three via `this.aborted`) and the per-child timeout (`timedOut`)
-            // are excluded HERE, before `shouldRetryColdStart` is ever consulted.
-            const retryable = !this.aborted && !timedOut && shouldRetryColdStart(run, attempt + 1);
+            // (all three via `this.aborted`), the per-child timeout (`timedOut`) and
+            // now the SUPERVISOR's verdict are excluded HERE, before
+            // `shouldRetryColdStart` is ever consulted.
+            const retryable = !this.aborted &&
+                !timedOut &&
+                verdict === null &&
+                shouldRetryColdStart(run, attempt);
             if (!retryable) {
                 run.endedAt = Date.now();
+                // The supervisor's abandon is an error like any other, with the
+                // supervisor's own reason so the report explains WHO stopped it and why.
+                if (verdict !== null && verdict.action === 'abandon') {
+                    run.error = run.error ?? `overseer abandoned: ${verdict.reason}`;
+                }
                 this.settlePhase(run, timedOut, subagentTimeoutMs);
                 this.publish(dispatchId, run);
+                // ONE post-mortem look at a child that died silently (team-overseer
+                // §3.4): a watchdog death is the "timed out" case the requirement most
+                // wants diagnosed, and replace-after-death is exactly re-assignment.
+                await this.maybePostMortem(ctx, index, handle, verdict);
+                this.supervision?.clear(run.label);
                 return;
             }
-            const fresh = this.replaceForRetry(dispatchId, handles, index, makeHandle);
+            this.replaceChild(dispatchId, handles, index, makeHandle, handle, null);
             await this.backoff(TEAM_LIMITS.retryBackoffMs);
             if (this.aborted) {
+                const fresh = handles[index];
                 fresh.run.phase = 'aborted';
                 fresh.run.endedAt = Date.now();
                 this.publish(dispatchId, fresh.run);
@@ -306,35 +476,214 @@ export class TeamRuntime {
         }
     }
     /**
-     * Swap a cold-started child for a fresh one, carrying only what must survive.
+     * One post-mortem inspection, and possibly ONE replacement driven by a
+     * recursive `runOne` — the worker that called us has already moved on to the
+     * next index, so nobody else will drive the fresh child (I-OV1 holds here
+     * too, one frame deeper). Recursion depth is bounded by the replacement
+     * budget, which is 1.
+     */
+    async maybePostMortem(ctx, index, handle, verdict) {
+        const overseer = this.overseer;
+        if (overseer === null || this.aborted || verdict !== null)
+            return;
+        const { run, agent } = handle;
+        if (run.phase !== 'failed' || run.summary !== undefined)
+            return;
+        if (!overseer.replacementsLeft(run.label))
+            return;
+        const decision = await overseer.inspect({
+            run: { ...run },
+            messages: agent.state.messages,
+            trigger: 'postmortem',
+            childAlive: false,
+        });
+        if (decision === null || this.aborted)
+            return;
+        this.recordIntervention(ctx.dispatchId, run.label, 'postmortem', decision);
+        this.emit({
+            type: 'overseer',
+            dispatchId: ctx.dispatchId,
+            label: run.label,
+            decision,
+            trigger: 'postmortem',
+        });
+        if (decision.action === 'replace' && overseer.replacementsLeft(run.label)) {
+            this.replaceChild(ctx.dispatchId, ctx.handles, index, ctx.makeHandle, handle, {
+                action: 'replace',
+                reason: decision.reason,
+                ...(decision.guidance !== undefined ? { guidance: decision.guidance } : {}),
+            });
+            await this.runOne(ctx, index);
+        }
+    }
+    /**
+     * Swap one child for a fresh one, carrying only what must survive.
      *
      * `this.live` IS `handles`, so the single assignment below also makes
      * `abortAll()` abort the NEW child and makes the outcome carry the new run.
      * Anyone tempted to "clean up" that aliasing into a defensive copy must update
      * both places.
+     *
+     * `verdict === null` is the COLD-START retry (F-4): identical spec, `retries`
+     * carried. A verdict is the SUPERVISOR's replace: an amended brief
+     * (`buildReplacementPrompt`), `replacements` carried, and the supervisor's
+     * budget spent HERE, at the moment the rebuild is real.
      */
-    replaceForRetry(dispatchId, handles, index, makeHandle) {
-        const handle = handles[index];
+    replaceChild(dispatchId, handles, index, makeHandle, handle, verdict) {
         const carried = { ...handle.run.usage };
-        const retries = (handle.run.retries ?? 0) + 1;
+        const retries = (handle.run.retries ?? 0) + (verdict === null ? 1 : 0);
+        const replacements = (handle.run.replacements ?? 0) + (verdict !== null ? 1 : 0);
+        const interventions = handle.run.interventions;
         handle.unsubscribe();
         try {
-            handle.agent.abort();
+            handle.abort();
         }
         catch {
             // Already gone; this must not stop the retry.
         }
-        const fresh = makeHandle(handle.spec);
-        // Provably {0,0} under the predicate above (no turn completed, so no
-        // `turn_end` and no usage event). Carried anyway so that a future relaxation
-        // of the predicate cannot silently under-report spend - the most misleading
-        // failure this feature can produce.
+        const spec = verdict !== null
+            ? {
+                ...handle.spec,
+                prompt: buildReplacementPrompt(handle.spec, {
+                    action: 'replace',
+                    reason: verdict.reason,
+                    ...(verdict.guidance !== undefined ? { guidance: verdict.guidance } : {}),
+                }, handle.run),
+            }
+            : handle.spec;
+        const fresh = makeHandle(spec);
+        // Provably {0,0} under the cold-start predicate above (no turn completed,
+        // so no `turn_end` and no usage event). Carried anyway so that a future
+        // relaxation of the predicate cannot silently under-report spend - the most
+        // misleading failure this feature can produce.
         fresh.run.usage = carried;
         fresh.run.retries = retries;
+        if (replacements > 0)
+            fresh.run.replacements = replacements;
+        if (interventions !== undefined)
+            fresh.run.interventions = interventions;
+        if (verdict !== null)
+            this.overseer?.noteReplacement(handle.run.label);
         handles[index] = fresh;
         this.publish(dispatchId, fresh.run);
         return fresh;
     }
+    // -------------------------------------------------------------------------
+    // Supervision (team-overseer)
+    // -------------------------------------------------------------------------
+    /**
+     * Whether a child's silence is a legitimate wait rather than a stall:
+     * `team_wait` (the comm tool already pauses the child's own watchdog for
+     * exactly this wait) or a confirmation queued on the one human slot.
+     */
+    isBlocked(label) {
+        const handle = this.live.find((h) => h.run.label === label);
+        if (handle !== undefined && handle.run.phase === 'waiting')
+            return true;
+        return this.deps.humanQueue?.isWaiting(label) === true;
+    }
+    /**
+     * One trigger handled: look, then apply. Fired from a supervision timer and
+     * therefore async-and-forgotten; nothing here may throw.
+     *
+     * QUIET (`decision === null` — provider gone, budget spent) CLEARS the
+     * child's timers: supervision that has nothing left to say should stop
+     * waking up, and the child's own hard ceilings take over.
+     */
+    async inspectAndApply(dispatchId, label, trigger) {
+        const overseer = this.overseer;
+        const supervision = this.supervision;
+        if (overseer === null || supervision === null || this.aborted)
+            return;
+        const handle = this.live.find((h) => h.run.label === label);
+        if (handle === undefined)
+            return;
+        const phase = handle.run.phase;
+        if (phase === 'done' || phase === 'failed' || phase === 'aborted')
+            return;
+        try {
+            const decision = await overseer.inspect({
+                run: handle.run,
+                messages: handle.agent.state.messages,
+                trigger,
+                childAlive: true,
+            });
+            if (decision === null || this.aborted) {
+                supervision.clear(label);
+                return;
+            }
+            // The child may have settled while the call was in flight; an
+            // intervention is still recorded (it happened), but nothing is applied.
+            const settled = handle.run.phase === 'done' ||
+                handle.run.phase === 'failed' ||
+                handle.run.phase === 'aborted';
+            this.recordIntervention(dispatchId, label, trigger, decision);
+            this.emit({ type: 'overseer', dispatchId, label, decision, trigger });
+            if (settled) {
+                supervision.clear(label);
+                return;
+            }
+            this.applyDecision(supervision, overseer, handle, label, decision);
+        }
+        catch {
+            // Defence in depth around an async timer callback: an unexpected throw
+            // must not take the dispatch down. The child keeps its timers.
+            supervision.rearmSilence(label);
+        }
+    }
+    applyDecision(supervision, overseer, handle, label, decision) {
+        switch (decision.action) {
+            case 'wait':
+                supervision.rearmClock(label, decision.nextCheckMs ?? supervision.defaultCheckMs);
+                supervision.rearmSilence(label);
+                break;
+            case 'nudge':
+                // I-OV4: never steer into an abort already requested — the same
+                // guard-1 fact the child's fast reviewer reads. Queued steering is
+                // drained at the safe top-of-loop checkpoint by core.
+                if (!handle.isAborted() && decision.guidance !== undefined) {
+                    handle.agent.steer(decision.guidance);
+                }
+                supervision.rearmClock(label, supervision.defaultCheckMs);
+                supervision.rearmSilence(label);
+                break;
+            case 'replace': {
+                // Budget checked BEFORE the verdict is set, so two near-simultaneous
+                // replace decisions cannot both rebuild (the second becomes an
+                // abandon with the budget stated in the reason).
+                handle.overseerVerdict = overseer.replacementsLeft(label)
+                    ? {
+                        action: 'replace',
+                        reason: decision.reason,
+                        ...(decision.guidance !== undefined ? { guidance: decision.guidance } : {}),
+                    }
+                    : { action: 'abandon', reason: `replacement budget exhausted; ${decision.reason}` };
+                supervision.clear(label);
+                handle.abort();
+                break;
+            }
+            case 'abandon':
+                handle.overseerVerdict = { action: 'abandon', reason: decision.reason };
+                supervision.clear(label);
+                handle.abort();
+                break;
+        }
+    }
+    /** Record one applied decision on the outcome, the run and the event stream. */
+    recordIntervention(dispatchId, label, trigger, decision) {
+        this.interventions.push({
+            label,
+            at: Date.now(),
+            action: decision.action,
+            reason: decision.reason,
+            trigger,
+        });
+        const handle = this.live.find((h) => h.run.label === label);
+        if (handle !== undefined) {
+            handle.run.interventions = (handle.run.interventions ?? 0) + 1;
+            this.publish(dispatchId, handle.run);
+        }
+    }
     /**
      * The final phase of an attempt, in a FIXED ORDER: aborted, then timed out,
      * then error, then no-summary, then done.
@@ -346,7 +695,7 @@ export class TeamRuntime {
         if (this.aborted) {
             run.phase = 'aborted';
         }
-        else if (timedOut) {
+        else if (timedOut && subagentTimeoutMs > 0) {
             run.phase = 'failed';
             run.error = run.error ?? `subagent exceeded ${Math.round(subagentTimeoutMs / 1000)}s`;
         }
@@ -398,13 +747,14 @@ export class TeamRuntime {
         this.aborted = true;
         for (const handle of this.live) {
             try {
-                handle.agent.abort();
+                handle.abort();
             }
             catch {
                 // A child that is already gone must not stop the others being aborted.
             }
         }
         this.bus?.cancelAllWaits();
+        this.supervision?.clearAll();
         // Every in-flight retry backoff, not just the last one registered: a
         // provider-wide failure puts up to `maxConcurrent` children here at once.
         for (const release of [...this.pendingBackoffs])
@@ -416,6 +766,9 @@ export class TeamRuntime {
         if (this.dispatchTimer)
             clearTimeout(this.dispatchTimer);
         this.dispatchTimer = null;
+        this.supervision?.clearAll();
+        this.supervision = null;
+        this.overseer = null;
         this.listeners.clear();
     }
     // -------------------------------------------------------------------------