@aragon-agent/cli 0.6.21 → 0.6.23

package/dist/team/runtime.js

@@ -28,30 +28,48 @@
  * pre-feature behaviour.
  */
 import { TeamBus } from './bus.js';
-import { TEAM_LIMITS } from './limits.js';
-import { TeamOverseer, buildReplacementPrompt } from './overseer.js';
+import { TEAM_AGGREGATE_LABEL, TEAM_LIMITS } from './limits.js';
+import { TeamOverseer, buildReplacementPrompt, nextOverseerLadderStepMs, resolveOverseerFirstCheckMs, } 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.
+ * The pseudo-label aggregate supervisor notices travel under (D-5 / R-P1-6):
+ * `TEAM_AGGREGATE_LABEL`, RESERVED at normalization so no child slug can be
+ * `team`. The reservation is what makes this label a safe namespace - a
+ * colliding child would have the aggregate notice attributed to it in the
+ * ledger and its own quiet note swallowed by the report's aggregate count.
+ */
+const MONITOR_TEAM_LABEL = TEAM_AGGREGATE_LABEL;
+const MONITOR_EXHAUSTED_DECISION = {
+    action: 'wait',
+    reason: 'dispatch look budget exhausted; supervision quiet for the rest of the dispatch',
+};
+/**
+ * The wait a DEGRADED tick announces per child (D-4 / D-10). One shared
+ * object, not a fresh literal per event: it is the same fact every time and
+ * identity makes that obvious to any consumer that looks.
+ */
+const DEGRADED_WAIT_DECISION = {
+    action: 'wait',
+    reason: 'fast tier unavailable; waiting unassisted',
+};
+/**
+ * The per-child SILENCE windows (team-overseer §3.2; subagent-overseer-v2
+ * keeps only this half). Timers only — no state, no decisions; the runtime
+ * applies what the supervisor decides. The wall-clock half moved to
+ * `MonitorLoop`, which owns the cadence ladder for the whole roster.
  *
  * 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. */
+    /** Arm (or re-arm) the silence window for a child starting 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. */
@@ -62,33 +80,16 @@ class ChildSupervisor {
     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)
@@ -101,17 +102,191 @@ class ChildSupervisor {
                 this.armSilence(label);
                 return;
             }
-            this.fire(label, 'silence');
+            this.silences.delete(label);
+            this.deps.onFire(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);
+}
+/**
+ * The cadence ladder (subagent-overseer-v2 D-2): one timer for the whole
+ * roster, per-child `nextAt` / `ladderStep` entries armed at each child's
+ * ACTUAL start (R-P1-5), and a strict one-batch-in-flight rule.
+ *
+ * A SKIPPED LABEL RE-SCHEULES WITHOUT TOUCHING ITS LADDER STEP: the
+ * single-flight guard (R-P1-4) can leave a due `nextAt` in the past while a
+ * silence-triggered inspection of that child is still settling, and a timer
+ * that re-fired at `max(0, due - now)` would busy-loop until it settles. The
+ * recheck delay is invisible to the protocol - no look is spent, the ladder
+ * value does not move - it only keeps the event loop idle.
+ */
+const MONITOR_RECHECK_MS = 500;
+class MonitorLoop {
+    deps;
+    nextAt = new Map();
+    ladderStep = new Map();
+    timer = null;
+    ticking = false;
+    stopped = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Arm the FIRST rung for a child that just started (R-P1-5). */
+    arm(label) {
+        const now = this.deps.now();
+        this.nextAt.set(label, now + this.deps.firstCheckMs);
+        this.ladderStep.set(label, this.deps.firstCheckMs);
+        this.schedule();
+    }
+    /** A wait decision's `nextCheckMs` OVERRIDES the rung and becomes it (D-2). */
+    override(label, ms) {
+        const now = this.deps.now();
+        this.nextAt.set(label, now + ms);
+        this.ladderStep.set(label, ms);
+        this.schedule();
+    }
+    /** Any ACTION resets that child's ladder to the base rung (D-2). */
+    reset(label) {
+        this.arm(label);
+    }
+    /** Grow the rung and schedule the next visit (D-2). */
+    advance(label) {
+        const now = this.deps.now();
+        const step = nextOverseerLadderStepMs(this.ladderStep.get(label) ?? this.deps.firstCheckMs);
+        this.ladderStep.set(label, step);
+        this.nextAt.set(label, now + step);
+        this.schedule();
+    }
+    /** Stop visiting one child (settled, quieted, or its verdict applied). */
+    clear(label) {
+        this.nextAt.delete(label);
+        this.ladderStep.delete(label);
+        this.schedule();
+    }
+    /** Stop the whole loop; the dispatch is over or the total budget is spent. */
+    stop() {
+        this.stopped = true;
+        if (this.timer !== null)
+            clearTimeout(this.timer);
+        this.timer = null;
+        this.nextAt.clear();
+        this.ladderStep.clear();
+    }
+    dispose() {
+        this.stop();
+    }
+    /** The earliest due time among live labels, or null when nothing is armed. */
+    earliestDue() {
+        let earliest = null;
+        for (const [label, at] of this.nextAt) {
+            if (!this.deps.isLive(label))
+                continue;
+            earliest = earliest === null ? at : Math.min(earliest, at);
+        }
+        return earliest;
+    }
+    schedule() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        if (this.stopped || this.ticking)
+            return;
+        const earliest = this.earliestDue();
+        if (earliest === null)
+            return;
+        const delay = Math.max(0, earliest - this.deps.now());
+        const timer = setTimeout(() => {
+            this.timer = null;
+            void this.tick();
+        }, delay);
+        timer.unref?.();
+        this.timer = timer;
+    }
+    async tick() {
+        if (this.ticking || this.stopped)
+            return;
+        const now = this.deps.now();
+        const due = [];
+        for (const [label, at] of [...this.nextAt]) {
+            if (!this.deps.isLive(label)) {
+                // Settled while armed; R-P1-5 also means a re-queued replacement body
+                // re-arms itself at its own start.
+                this.nextAt.delete(label);
+                this.ladderStep.delete(label);
+                continue;
+            }
+            if (now >= at)
+                due.push(label);
+        }
+        if (due.length === 0) {
+            this.schedule();
+            return;
+        }
+        // DEGRADED TICK (D-4 / D-10): no fast tier right now. The children wait
+        // unassisted - announced per child, never killed - and the cadence keeps
+        // running so a `/fast on` restores assistance at the next rung.
+        if (!this.deps.isActive()) {
+            this.deps.onDegraded(due);
+            for (const label of due)
+                this.advance(label);
+            this.schedule();
+            return;
+        }
+        // PER-CHILD QUIET (D-5): budget spent says so once, then stop visiting.
+        const inspectable = [];
+        for (const label of due) {
+            if (this.deps.isExhausted(label)) {
+                this.clear(label);
+                this.deps.onQuiet(label);
+                continue;
+            }
+            inspectable.push(label);
+        }
+        if (inspectable.length === 0) {
+            this.schedule();
+            return;
+        }
+        this.ticking = true;
+        let decisions;
+        try {
+            decisions = await this.deps.inspectBatch(inspectable);
+        }
+        catch {
+            // Defence in depth: `inspectBatch` is fail-soft by contract. Treat the
+            // tick as if every child had answered wait.
+            decisions = new Map();
+        }
+        finally {
+            this.ticking = false;
+        }
+        const after = this.deps.now();
+        for (const label of inspectable) {
+            const decision = decisions.get(label);
+            if (decision === undefined) {
+                // Skipped for single-flight (R-P1-4): no decision, no look, and the
+                // ladder does not move - only the timer must not busy-loop.
+                this.nextAt.set(label, after + MONITOR_RECHECK_MS);
+                continue;
+            }
+            if (decision.action === 'wait' && decision.nextCheckMs !== undefined) {
+                this.override(label, decision.nextCheckMs);
+            }
+            else if (decision.action === 'wait') {
+                this.advance(label);
+            }
+            else {
+                this.reset(label);
+            }
+        }
+        if (this.deps.dispatchExhausted()) {
+            // The fool-proof total (R-P1-6). Stop the whole loop, once, loudly.
+            this.stop();
+            this.deps.onExhausted();
+            return;
+        }
+        this.schedule();
     }
 }
 export class TeamRuntime {
@@ -137,15 +312,30 @@ export class TeamRuntime {
      */
     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.
+     * The dispatch supervisor, LIVE for the current dispatch only
+     * (team-overseer / subagent-overseer-v2). Null when the provider is not
+     * wired or the policy is off, and reset to null at every dispatch end so
+     * nothing supervision-shaped leaks across dispatches.
+     *
+     * THE GATE IS "PROVIDER PRESENT AND POLICY ON" (R-P0-2), deliberately NOT
+     * the provider's live `active()`: a dispatch that STARTS without a fast
+     * tier must still get a MonitorLoop, because the promise this feature
+     * makes is "timeout is never a death sentence" - an unavailable tier
+     * degrades the tick to an announced unassisted wait rather than falling
+     * back to the legacy hard abort. `active()` is re-read every tick.
      */
     overseer = null;
-    /** The soft timers, same lifetime as `overseer`. */
+    /** The per-child silence windows, same lifetime as `overseer`. */
     supervision = null;
+    /** The cadence ladder (subagent-overseer-v2 D-2), same lifetime. */
+    monitor = null;
     /** Applied interventions for the in-flight dispatch's outcome. */
     interventions = [];
+    /** Labels already told the supervisor went quiet on them (D-5, once). */
+    quietNotified = new Set();
+    /** Edge-latched "a tick ran unassisted" (D-10), per dispatch. */
+    overseerDegraded = false;
+    overseerDegradedTicks = 0;
     constructor(deps) {
         this.deps = deps;
     }
@@ -177,29 +367,48 @@ export class TeamRuntime {
         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.quietNotified.clear();
+        this.overseerDegraded = false;
+        this.overseerDegradedTicks = 0;
+        // THE SUPERVISOR IS CREATED PER DISPATCH (R-P0-2): provider wired AND
+        // policy on. `TeamOverseer.isActive()` re-checks the provider per
+        // inspection and per tick, so a mid-dispatch `/fast off` degrades the
+        // NEXT look to an unassisted wait instead of unwinding anything already
+        // applied - and a dispatch that started without the tier is still
+        // supervised, in that degraded, never-kill sense.
+        const supervised = this.deps.overseer !== undefined && team.overseer;
         this.overseer =
-            this.deps.overseer !== undefined &&
-                this.deps.overseer.active() &&
-                team.overseer
+            supervised && this.deps.overseer !== undefined
                 ? 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;
+        this.monitor =
+            this.overseer !== null
+                ? new MonitorLoop({
+                    // D-8: `overseerIntervalMs` wins, then a positive
+                    // `subagentTimeoutMs` (compat), then the structural default.
+                    firstCheckMs: resolveOverseerFirstCheckMs(team),
+                    now: () => Date.now(),
+                    // R-P1-5: only STARTED, UNSETTLED children tick.
+                    isLive: (label) => this.isMonitorLive(label),
+                    isActive: () => this.overseer?.isActive() === true,
+                    isExhausted: (label) => this.overseer?.looksExhausted(label) === true,
+                    dispatchExhausted: () => this.overseer?.dispatchLooksExhausted() === true,
+                    inspectBatch: (labels) => this.monitorInspectBatch(dispatchId, labels),
+                    onDegraded: (labels) => this.noteDegradedTick(dispatchId, labels),
+                    onQuiet: (label) => this.noteQuiet(dispatchId, label),
+                    onExhausted: () => this.noteDispatchExhausted(dispatchId),
+                })
+                : 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
@@ -279,6 +488,18 @@ export class TeamRuntime {
             // 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),
+            // A'2: under supervision the turn cap is ONE inspection, fired from the
+            // child's own `turn_end` at the crossing turn. Async-and-forgotten
+            // exactly like the silence timer's `onFire`: nothing in the child's
+            // event path may block or throw. ABSENT in the legacy regime, which
+            // keeps the hard stop - the hook's presence IS the gate.
+            ...(this.overseer !== null
+                ? {
+                    onTurnCapReached: (label) => {
+                        void this.inspectAndApply(dispatchId, label, 'turncap');
+                    },
+                }
+                : {}),
         });
         // 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
@@ -311,15 +532,24 @@ export class TeamRuntime {
         // 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.
+        //
+        // D-4, NOW FOR THE WHOLE DISPATCH TOO: with the supervisor gate open the
+        // ceiling NEVER arms a hard abort - the cadence ladder is what looks at a
+        // long dispatch, exactly as it already looks at a long child. The legacy
+        // hard `abortAll()` exists ONLY under `team.overseer: false`, the same
+        // regime line `runCtx.subagentTimeoutMs` below draws.
+        const dispatchCeilingMs = team.overseer ? 0 : team.dispatchTimeoutMs;
         this.dispatchTimer =
-            team.dispatchTimeoutMs > 0
-                ? setTimeout(() => this.abortAll(), team.dispatchTimeoutMs)
-                : null;
+            dispatchCeilingMs > 0 ? setTimeout(() => this.abortAll(), dispatchCeilingMs) : null;
         const runCtx = {
             dispatchId,
             handles,
             makeHandle,
-            subagentTimeoutMs: team.subagentTimeoutMs,
+            // D-4: with the supervisor gate open, `subagentTimeoutMs` NEVER arms a
+            // hard abort - 0 here arms no timer, so the key's only remaining role
+            // is the ladder's compat first-check (D-8). The legacy hard abort
+            // exists ONLY under `team.overseer: false`.
+            subagentTimeoutMs: team.overseer ? 0 : team.subagentTimeoutMs,
         };
         const cursor = { next: 0 };
         const workers = Array.from({ length: Math.max(1, Math.min(team.maxConcurrent, handles.length)) }, () => this.worker(runCtx, cursor));
@@ -330,8 +560,17 @@ export class TeamRuntime {
         signal?.removeEventListener('abort', onAbort);
         for (const handle of handles)
             handle.unsubscribe();
+        this.monitor?.dispose();
+        this.monitor = null;
         this.supervision?.clearAll();
         this.supervision = null;
+        // CAPTURED BEFORE THE FIELD IS NULLED: the outcome carries what the
+        // supervisor spent (D-7) and whether any tick ran unassisted (D-10),
+        // both read off the per-dispatch state being torn down here.
+        const overseerUsage = this.overseer?.usage();
+        const overseerCalls = this.overseer?.calls();
+        const overseerDegraded = this.overseerDegraded;
+        const overseerDegradedTicks = this.overseerDegradedTicks;
         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
@@ -350,6 +589,13 @@ export class TeamRuntime {
             leadMail: bus.leadMail(),
             interventions: this.interventions,
             usage,
+            // Honest supervision accounting (D-7 / D-10). `overseerCalls > 0`
+            // with zero usage is a provider that never reported usage - the
+            // report then omits the spend line rather than pricing nothing.
+            ...(overseerUsage !== undefined ? { overseerUsage } : {}),
+            ...(overseerCalls !== undefined ? { overseerCalls } : {}),
+            ...(overseerDegraded ? { overseerDegraded: true } : {}),
+            ...(overseerDegradedTicks > 0 ? { overseerDegradedTicks } : {}),
         };
         this.live = [];
         this.bus = null;
@@ -400,13 +646,20 @@ export class TeamRuntime {
             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.
+            // WITH THE SUPERVISOR GATE OPEN there is no hard wall clock on the
+            // child at all (D-4): the cadence ladder looks and decides, and the
+            // child's own (lengthened) idle watchdog is the silence backstop. The
+            // rung and the silence window are both armed HERE, at the attempt's
+            // actual start (R-P1-5) - a `queued` child has neither. WITHOUT the
+            // gate - `team.overseer: false`, the legacy regime - the hard timer is
+            // armed exactly as before, `0` meaning no ceiling. A provider that is
+            // wired but INACTIVE arms no timer either: the tick degrades to an
+            // announced unassisted wait, never a kill (R-P0-2).
             const supervised = this.overseer !== null;
-            if (supervised)
+            if (supervised) {
                 this.supervision?.start(run.label);
+                this.monitor?.arm(run.label);
+            }
             let timedOut = false;
             const timer = !supervised && subagentTimeoutMs > 0
                 ? setTimeout(() => {
@@ -462,6 +715,7 @@ export class TeamRuntime {
                 // wants diagnosed, and replace-after-death is exactly re-assignment.
                 await this.maybePostMortem(ctx, index, handle, verdict);
                 this.supervision?.clear(run.label);
+                this.monitor?.clear(run.label);
                 return;
             }
             this.replaceChild(dispatchId, handles, index, makeHandle, handle, null);
@@ -534,6 +788,7 @@ export class TeamRuntime {
         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;
+        const lastIntervention = handle.run.lastIntervention;
         handle.unsubscribe();
         try {
             handle.abort();
@@ -562,6 +817,10 @@ export class TeamRuntime {
             fresh.run.replacements = replacements;
         if (interventions !== undefined)
             fresh.run.interventions = interventions;
+        // The badge survives a rebuild (`replaced 5s`) - the panel row does not
+        // reset just because the body under it did.
+        if (lastIntervention !== undefined)
+            fresh.run.lastIntervention = lastIntervention;
         if (verdict !== null)
             this.overseer?.noteReplacement(handle.run.label);
         handles[index] = fresh;
@@ -583,12 +842,14 @@ export class TeamRuntime {
         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.
+     * One SILENCE 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.
+     * A NULL DECISION HAS THREE DISTINCT QUIETS: the look budget is spent ->
+     * say so ONCE and stop supervising this child (D-5); an inspection of this
+     * child is already in flight -> re-arm and let it settle (R-P1-4); the
+     * tier is gone -> clear quietly, because the cadence tick - not the
+     * silence path - owns the degraded announcements (D-4).
      */
     async inspectAndApply(dispatchId, label, trigger) {
         const overseer = this.overseer;
@@ -609,7 +870,17 @@ export class TeamRuntime {
                 childAlive: true,
             });
             if (decision === null || this.aborted) {
-                supervision.clear(label);
+                if (!this.aborted && overseer.looksExhausted(label)) {
+                    this.noteQuiet(dispatchId, label);
+                    supervision.clear(label);
+                    this.monitor?.clear(label);
+                }
+                else if (!this.aborted && overseer.isInFlight(label)) {
+                    supervision.rearmSilence(label);
+                }
+                else {
+                    supervision.clear(label);
+                }
                 return;
             }
             // The child may have settled while the call was in flight; an
@@ -621,9 +892,10 @@ export class TeamRuntime {
             this.emit({ type: 'overseer', dispatchId, label, decision, trigger });
             if (settled) {
                 supervision.clear(label);
+                this.monitor?.clear(label);
                 return;
             }
-            this.applyDecision(supervision, overseer, handle, label, decision);
+            this.applyDecision(handle, label, decision);
         }
         catch {
             // Defence in depth around an async timer callback: an unexpected throw
@@ -631,49 +903,88 @@ export class TeamRuntime {
             supervision.rearmSilence(label);
         }
     }
-    applyDecision(supervision, overseer, handle, label, decision) {
+    applyDecision(handle, label, decision) {
+        const supervision = this.supervision;
+        const overseer = this.overseer;
+        if (supervision === null || overseer === null)
+            return;
         switch (decision.action) {
             case 'wait':
-                supervision.rearmClock(label, decision.nextCheckMs ?? supervision.defaultCheckMs);
+                // A model-chosen interval OVERRIDES the rung and becomes it (D-2);
+                // without one the rung is untouched - the silence window is the only
+                // clock this path re-arms.
+                if (decision.nextCheckMs !== undefined) {
+                    this.monitor?.override(label, decision.nextCheckMs);
+                }
                 supervision.rearmSilence(label);
                 break;
-            case 'nudge':
+            case 'nudge': {
+                // THE NUDGE BUDGET IS CHECKED BEFORE STEERING (D-5): a fourth nudge
+                // is not advice, it is the supervisor refusing to decide - it waits.
+                if (!overseer.nudgesLeft(label)) {
+                    supervision.rearmSilence(label);
+                    break;
+                }
                 // 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);
+                    overseer.noteNudge(label);
                 }
-                supervision.rearmClock(label, supervision.defaultCheckMs);
+                this.monitor?.reset(label);
                 supervision.rearmSilence(label);
                 break;
+            }
             case 'replace': {
-                // Budget checked BEFORE the verdict is set, so two near-simultaneous
+                // Budgets 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)
-                    ? {
+                if (overseer.replacementsLeft(label)) {
+                    handle.overseerVerdict = {
                         action: 'replace',
                         reason: decision.reason,
                         ...(decision.guidance !== undefined ? { guidance: decision.guidance } : {}),
-                    }
-                    : { action: 'abandon', reason: `replacement budget exhausted; ${decision.reason}` };
+                    };
+                }
+                else if (overseer.abandonsLeft(label)) {
+                    handle.overseerVerdict = {
+                        action: 'abandon',
+                        reason: `replacement budget exhausted; ${decision.reason}`,
+                    };
+                    overseer.noteAbandon(label);
+                }
+                else {
+                    // Both mutation budgets spent: the honest reading is wait (I-OV2).
+                    supervision.rearmSilence(label);
+                    this.monitor?.advance(label);
+                    break;
+                }
                 supervision.clear(label);
+                this.monitor?.clear(label);
                 handle.abort();
                 break;
             }
             case 'abandon':
+                if (!overseer.abandonsLeft(label)) {
+                    supervision.rearmSilence(label);
+                    this.monitor?.advance(label);
+                    break;
+                }
                 handle.overseerVerdict = { action: 'abandon', reason: decision.reason };
+                overseer.noteAbandon(label);
                 supervision.clear(label);
+                this.monitor?.clear(label);
                 handle.abort();
                 break;
         }
     }
     /** Record one applied decision on the outcome, the run and the event stream. */
     recordIntervention(dispatchId, label, trigger, decision) {
+        const at = Date.now();
         this.interventions.push({
             label,
-            at: Date.now(),
+            at,
             action: decision.action,
             reason: decision.reason,
             trigger,
@@ -681,9 +992,116 @@ export class TeamRuntime {
         const handle = this.live.find((h) => h.run.label === label);
         if (handle !== undefined) {
             handle.run.interventions = (handle.run.interventions ?? 0) + 1;
+            // The panel's badge (AC-5): ABSOLUTE `at`, same units as `startedAt`
+            // (R-P2-3), so rendering is one subtraction.
+            handle.run.lastIntervention = {
+                action: decision.action,
+                at,
+                reasonHead: decision.reason.slice(0, 60),
+            };
             this.publish(dispatchId, handle.run);
         }
     }
+    // -------------------------------------------------------------------------
+    // The cadence loop's callbacks (subagent-overseer-v2 D-2 / D-3 / D-4)
+    // -------------------------------------------------------------------------
+    /** R-P1-5: a label ticks only once STARTED and not yet settled. */
+    isMonitorLive(label) {
+        const handle = this.live.find((h) => h.run.label === label);
+        if (handle === undefined || handle.run.startedAt === undefined)
+            return false;
+        const phase = handle.run.phase;
+        return phase !== 'done' && phase !== 'failed' && phase !== 'aborted';
+    }
+    /**
+     * One ASSISTED cadence tick: build the batch over the due labels, apply
+     * every returned decision through the same `applyDecision` the silence
+     * path uses (D-3's single application path), and hand the map back so the
+     * loop can move the ladders. Labels the batch skipped (single-flight,
+     * R-P1-4) are absent from the map.
+     */
+    async monitorInspectBatch(dispatchId, labels) {
+        const overseer = this.overseer;
+        if (overseer === null || this.aborted)
+            return new Map();
+        const reqs = [];
+        for (const label of labels) {
+            const handle = this.live.find((h) => h.run.label === label);
+            if (handle === undefined)
+                continue;
+            reqs.push({
+                run: handle.run,
+                messages: handle.agent.state.messages,
+                trigger: 'clock',
+                childAlive: true,
+            });
+        }
+        const decisions = await overseer.inspectBatch(reqs);
+        for (const [label, decision] of decisions) {
+            if (this.aborted)
+                break;
+            const handle = this.live.find((h) => h.run.label === label);
+            const settled = handle === undefined ||
+                handle.run.phase === 'done' ||
+                handle.run.phase === 'failed' ||
+                handle.run.phase === 'aborted';
+            this.recordIntervention(dispatchId, label, 'clock', decision);
+            this.emit({ type: 'overseer', dispatchId, label, decision, trigger: 'clock' });
+            if (settled) {
+                this.monitor?.clear(label);
+                continue;
+            }
+            this.applyDecision(handle, label, decision);
+        }
+        return decisions;
+    }
+    /**
+     * One DEGRADED cadence tick (D-4 / D-10): the fast tier is missing right
+     * now. The children wait unassisted - announced per child through the same
+     * event shape, never killed - and the fact is edge-latched here, NOT in
+     * the interventions ledger.
+     */
+    noteDegradedTick(dispatchId, labels) {
+        this.overseerDegraded = true;
+        this.overseerDegradedTicks += 1;
+        for (const label of labels) {
+            this.emit({
+                type: 'overseer',
+                dispatchId,
+                label,
+                decision: DEGRADED_WAIT_DECISION,
+                trigger: 'clock',
+            });
+        }
+    }
+    /** The supervisor goes quiet on one child, ONCE (D-5 / D-10). */
+    noteQuiet(dispatchId, label) {
+        if (this.quietNotified.has(label))
+            return;
+        this.quietNotified.add(label);
+        const decision = {
+            action: 'wait',
+            reason: 'look budget exhausted; supervision quiet for this child',
+        };
+        this.recordIntervention(dispatchId, label, 'quiet', decision);
+        this.emit({ type: 'overseer', dispatchId, label, decision, trigger: 'quiet' });
+    }
+    /**
+     * The dispatch-wide fool-proof total is spent (R-P1-6): stop the whole
+     * loop and emit ONE aggregate notice under a pseudo-label that is never a
+     * child slug.
+     */
+    noteDispatchExhausted(dispatchId) {
+        this.monitor?.stop();
+        this.recordIntervention(dispatchId, MONITOR_TEAM_LABEL, 'quiet', MONITOR_EXHAUSTED_DECISION);
+        this.emit({
+            type: 'overseer',
+            dispatchId,
+            label: MONITOR_TEAM_LABEL,
+            decision: MONITOR_EXHAUSTED_DECISION,
+            trigger: 'quiet',
+        });
+    }
     /**
      * The final phase of an attempt, in a FIXED ORDER: aborted, then timed out,
      * then error, then no-summary, then done.
@@ -755,6 +1173,10 @@ export class TeamRuntime {
         }
         this.bus?.cancelAllWaits();
         this.supervision?.clearAll();
+        // The cadence loop too: every child is being aborted, so no tick has
+        // anything left to look at (an in-flight batch's decisions are dropped
+        // by the aborted guard in `monitorInspectBatch`).
+        this.monitor?.stop();
         // 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])
@@ -766,6 +1188,8 @@ export class TeamRuntime {
         if (this.dispatchTimer)
             clearTimeout(this.dispatchTimer);
         this.dispatchTimer = null;
+        this.monitor?.dispose();
+        this.monitor = null;
         this.supervision?.clearAll();
         this.supervision = null;
         this.overseer = null;