@aragon-agent/cli 0.6.17 → 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;
     }
@@ -73,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
@@ -85,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
@@ -136,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
@@ -145,6 +276,9 @@ export class TeamRuntime {
         const makeHandle = (spec) => createSubagent(spec, subDeps, {
             onUpdate: (run) => this.publish(dispatchId, run),
             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
@@ -196,6 +330,9 @@ export class TeamRuntime {
         signal?.removeEventListener('abort', onAbort);
         for (const handle of handles)
             handle.unsubscribe();
+        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.
@@ -211,6 +348,7 @@ export class TeamRuntime {
             endedAt: Date.now(),
             aborted: this.aborted,
             leadMail: bus.leadMail(),
+            interventions: this.interventions,
             usage,
         };
         this.live = [];
@@ -241,11 +379,19 @@ 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
@@ -254,12 +400,15 @@ export class TeamRuntime {
             run.phase = 'starting';
             run.startedAt = Date.now();
             this.publish(dispatchId, run);
-            // `subagentTimeoutMs: 0` MEANS NO CEILING (main-agent parity): no timer
-            // is armed and `timedOut` can never become true. A wedged child is still
-            // ended by its OWN idle watchdog, which is the exact ceiling the lead
-            // runs under.
+            // 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 = subagentTimeoutMs > 0
+            const timer = !supervised && subagentTimeoutMs > 0
                 ? setTimeout(() => {
                     timedOut = true;
                     handle.abort();
@@ -279,21 +428,46 @@ export class TeamRuntime {
                 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);
@@ -302,17 +476,64 @@ 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.abort();
@@ -320,17 +541,149 @@ export class TeamRuntime {
         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.
@@ -401,6 +754,7 @@ export class TeamRuntime {
             }
         }
         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])
@@ -412,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();
     }
     // -------------------------------------------------------------------------

package/dist/team/subagent.d.ts

@@ -19,7 +19,7 @@ import type { ToolPermission } from '../exec/permission.js';
 import type { ChildReviewProvider } from './child-reviewer.js';
 import { TeamBus } from './bus.js';
 import type { TeamHumanQueue, WatchdogPausable } from './human-queue.js';
-import type { SubagentRun, SubagentSpec } from './types.js';
+import type { OverseerVerdict, SubagentRun, SubagentSpec } from './types.js';
 /**
  * The slice of `Agent` a child is used through.
  *
@@ -98,6 +98,14 @@ export interface SubagentDeps {
     /** Present only when `--confirm` is on AND a human channel exists. */
     humanQueue?: TeamHumanQueue;
     agentFactory: SubagentAgentFactory;
+    /**
+     * Whether the dispatch supervisor is live for THIS dispatch
+     * (team-overseer). Read once per dispatch by the runtime and spread here;
+     * when true the child's OWN idle watchdog is lengthened by
+     * `TEAM_LIMITS.overseerWatchdogFactor`, so the supervisor's soft silence
+     * inspection at `idleTimeoutMs` always precedes the hard abort.
+     */
+    overseerActive?: boolean;
     /**
      * Per-child fast review (main-agent parity): the controller's shared
      * provider, built on the lead's `FastWiring`. ABSENT means the session
@@ -120,6 +128,13 @@ export interface SubagentHooks {
     /** Coalesced at the source (§5.2); phase transitions always pass. */
     onUpdate: (run: SubagentRun) => void;
     onUsage: (label: string, usage: TokenUsage) => void;
+    /**
+     * UNTHROTTLED per-event callback (team-overseer I-OV3). `onUpdate` is
+     * coalesced, so it would lie about silence; the supervisor's soft stall
+     * timer needs one kick per REAL agent event. Called after the phase switch
+     * so the phase read at fire time is current.
+     */
+    onActivity?: () => void;
 }
 export interface SubagentHandle {
     spec: SubagentSpec;
@@ -134,6 +149,20 @@ export interface SubagentHandle {
      * reviewer steers a `<fast_review>` block into a run that is already dying.
      */
     abort: () => void;
+    /**
+     * Whether `abort()` has been called on this handle (team-overseer
+     * I-OV4): the supervisor reads it before steering a nudge, so advice is
+     * never queued into a child that is already dying - the same guard-1 fact
+     * the child's own fast reviewer reads.
+     */
+    isAborted: () => boolean;
+    /**
+     * A terminal supervisor decision awaiting application by the WORKER LOOP
+     * (team-overseer I-OV1). Written by `TeamRuntime` immediately before
+     * `abort()`; read by `runOne` after `prompt()` resolves. NEVER cleared,
+     * so an abort racing the read cannot hide the cause.
+     */
+    overseerVerdict?: OverseerVerdict;
     unsubscribe: () => void;
 }
 /**

package/dist/team/subagent.js

@@ -241,7 +241,9 @@ export function createSubagent(spec, deps, hooks) {
             // (§3.8). The two places a child legitimately blocks on something other
             // than its own LLM or tool — `team_wait` and the confirm queue — pause it
             // explicitly.
-            idleTimeout: deps.config.idleTimeoutMs,
+            idleTimeout: deps.overseerActive === true
+                ? deps.config.idleTimeoutMs * TEAM_LIMITS.overseerWatchdogFactor
+                : deps.config.idleTimeoutMs,
         },
         // SPREAD CONDITIONALLY, never `contextManager: deps.contextManagerFor?.(...)`.
         // With the feature off the options bag has no such key, so the loop's gate
@@ -437,6 +439,10 @@ export function createSubagent(spec, deps, hooks) {
             default:
                 break;
         }
+        // AFTER the switch, so `run.phase` is current when the supervisor's
+        // silence timer consults it (team-overseer I-OV3): a `team_wait` start
+        // must be observable as `waiting` on the very kick that follows it.
+        hooks.onActivity?.();
         emit();
     });
     return {
@@ -450,6 +456,7 @@ export function createSubagent(spec, deps, hooks) {
             abortRequested = true;
             agent.abort();
         },
+        isAborted: () => abortRequested,
         unsubscribe: () => {
             reviewer?.dispose();
             unsubscribe();

package/dist/team/task-tool.js

@@ -47,7 +47,10 @@ const TASK_DESCRIPTION = 'Run several independent subagents in parallel and get
     'a change small enough to just make. Subagents cannot dispatch further subagents and ' +
     'cannot ask the user anything. Give each a description of at most ' +
     `${TEAM_LIMITS.descriptionChars} characters and a complete prompt. Extra entries beyond the ` +
-    'configured maximum are dropped, so keep within it.';
+    'configured maximum are dropped, so keep within it. A supervisor watches the ' +
+    'fan-out: a child that stalls or runs very long may be nudged with guidance ' +
+    'or replaced by a fresh attempt, and the report\'s Supervisor section ' +
+    'records every intervention.';
 export function createTaskTool(deps) {
     return {
         name: 'task',