@aragon-agent/cli 0.6.17 → 0.6.18

package/dist/team/overseer.js

@@ -0,0 +1,348 @@
+/**
+ * The dispatch supervisor (team-overseer).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts`), so no literal in this tree may hold a non-ASCII byte.
+ *
+ * A TIME CEILING ON A CHILD IS AN INSPECTION TRIGGER, NOT A DEATH SENTENCE.
+ * When a child stalls (event silence) or simply runs long (the wall clock),
+ * the supervisor looks at it through ONE bounded fast-tier call and decides:
+ * keep waiting, steer a nudge in to help it recover, rebuild it with an
+ * amended brief, or abandon it with a recorded reason. Only the supervisor
+ * "decides"; the RUNTIME applies (see `runtime.ts`), because every child
+ * lifecycle change must funnel through the worker loop that awaits it
+ * (I-OV1).
+ *
+ * THE TRANSPORT IS THE REVIEWER'S, DELIBERATELY. One `complete` call, no
+ * tools, thinking off, temperature 0, output capped at
+ * `FAST_LIMITS.reviewOutputTokens` and wall clock at
+ * `FAST_LIMITS.reviewTimeoutMs` — a supervision call that could itself hang
+ * would need a second supervisor, which is the regress this design refuses.
+ *
+ * REPAIR, NEVER REJECT (the `normalizeSubagentSpecs` rule). An unparseable
+ * or out-of-budget decision becomes `wait` with the default interval: the
+ * failure mode of a supervisor must be "looked and let it run", never
+ * "looked and killed it" (I-OV2).
+ */
+import { resolveFastTier } from '../fast/resolve.js';
+import { assistantText } from '../fast/review-call.js';
+import { FAST_LIMITS } from '../fast/limits.js';
+import { truncateBytes } from './report.js';
+import { TEAM_LIMITS } from './limits.js';
+/** How many trailing history messages the digest carries. */
+const DIGEST_TAIL_MESSAGES = 8;
+/** Per-message text clamp inside the digest. */
+const DIGEST_MSG_CHARS = 400;
+function messageText(message) {
+    if (message.role === 'assistant') {
+        const parts = [];
+        for (const block of message.content) {
+            if (block.type === 'text')
+                parts.push(block.text);
+            if (block.type === 'tool_call')
+                parts.push(`(tool_call ${block.toolName})`);
+        }
+        return parts.join(' ').trim();
+    }
+    if (typeof message.content === 'string')
+        return message.content;
+    return message.content
+        .filter((p) => p.type === 'text')
+        .map((p) => (p.type === 'text' ? p.text : ''))
+        .join(' ')
+        .trim();
+}
+function clampChars(text, max) {
+    return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 3))}...`;
+}
+/**
+ * Build the bounded text one inspection reads.
+ *
+ * FACTS FIRST, HISTORY SECOND: the byte clamp (`overseerDigestBytes`, via the
+ * same `truncateBytes` the report uses so a CJK tail cannot be split mid
+ * sequence) bites the tail, and the tail is the least decisive part — a
+ * supervisor that cannot see the phase, the retry state and its own memory
+ * is worse than one missing the fifth message back.
+ */
+export function buildChildDigest(input) {
+    const { run, childAlive, trigger, messages, memory, elapsedSec } = input;
+    const lines = [];
+    lines.push(`child: ${run.label} "${run.description}"`);
+    lines.push(`trigger: ${trigger === 'silence' ? 'event silence (suspected stall)' : trigger === 'clock' ? 'wall-clock check' : 'post-mortem (child already ended)'}`);
+    lines.push(`elapsed: ${Math.round(elapsedSec)}s, alive: ${childAlive ? 'yes' : 'no'}`);
+    lines.push(`phase: ${run.phase}, turns: ${run.turns}, toolCalls: ${run.toolCalls}` +
+        (run.lastTool ? `, lastTool: ${run.lastTool}` : ''));
+    if (run.retry)
+        lines.push(`api-retry: attempt ${run.retry.attempt}/${run.retry.maxRetries} (legitimate backoff, not a stall)`);
+    if (run.error)
+        lines.push(`error: ${clampChars(run.error, DIGEST_MSG_CHARS)}`);
+    if (run.filesTouched.length > 0)
+        lines.push(`files: ${run.filesTouched.join(', ')}`);
+    if (memory.length > 0) {
+        lines.push('previous supervisor decisions:');
+        for (const entry of memory) {
+            lines.push(`  [${entry.atSec}s] ${entry.action}: ${clampChars(entry.reason, 120)}`);
+        }
+    }
+    const tail = messages.slice(-DIGEST_TAIL_MESSAGES);
+    if (tail.length > 0) {
+        lines.push('history tail:');
+        for (const message of tail) {
+            const text = clampChars(messageText(message), DIGEST_MSG_CHARS);
+            lines.push(`  ${message.role}: ${text.length > 0 ? text : '(no text)'}`);
+        }
+    }
+    return truncateBytes(lines.join('\n'), TEAM_LIMITS.overseerDigestBytes);
+}
+// ---------------------------------------------------------------------------
+// Decision normalization
+// ---------------------------------------------------------------------------
+const VALID_ACTIONS = new Set(['wait', 'nudge', 'replace', 'abandon']);
+/** Clamp a model-chosen next check into the structural range. */
+export function clampNextCheckMs(ms) {
+    const n = typeof ms === 'number' ? ms : Number.NaN;
+    if (!Number.isFinite(n) || n <= 0)
+        return undefined;
+    return Math.min(TEAM_LIMITS.overseerNextCheckMaxMs, Math.max(TEAM_LIMITS.overseerNextCheckMinMs, Math.round(n)));
+}
+function waitDecision(reason, nextCheckMs) {
+    return {
+        action: 'wait',
+        reason: clampChars(reason, TEAM_LIMITS.overseerReasonChars),
+        ...(nextCheckMs !== undefined ? { nextCheckMs } : {}),
+    };
+}
+/**
+ * Normalize a raw (JSON-parsed or garbage) decision into a safe one.
+ *
+ * `childAlive === false` PHYSICALLY REMOVES two actions: a dead child can be
+ * replaced or abandoned, never waited on or nudged, so those normalize to
+ * `abandon` rather than being rejected — a post-mortem answer the protocol
+ * cannot honour must still produce a decision the runtime can apply.
+ */
+export function normalizeOverseerDecision(raw, childAlive) {
+    const obj = (raw && typeof raw === 'object' ? raw : {});
+    const action = typeof obj.action === 'string' && VALID_ACTIONS.has(obj.action)
+        ? obj.action
+        : 'wait';
+    const reason = typeof obj.reason === 'string' && obj.reason.trim().length > 0
+        ? obj.reason.trim()
+        : 'no reason given';
+    const guidance = typeof obj.guidance === 'string' && obj.guidance.trim().length > 0
+        ? clampChars(obj.guidance.trim(), TEAM_LIMITS.overseerGuidanceChars)
+        : undefined;
+    const nextCheckMs = clampNextCheckMs(obj.nextCheckMs);
+    if (!childAlive && (action === 'wait' || action === 'nudge')) {
+        return {
+            action: 'abandon',
+            reason: clampChars(`child already ended; supervisor answered ${action}: ${reason}`, TEAM_LIMITS.overseerReasonChars),
+        };
+    }
+    return {
+        action,
+        reason: clampChars(reason, TEAM_LIMITS.overseerReasonChars),
+        ...(guidance !== undefined && action === 'nudge' ? { guidance } : {}),
+        ...(action === 'wait' && nextCheckMs !== undefined ? { nextCheckMs } : {}),
+    };
+}
+/**
+ * Parse the model's answer text as one JSON decision object.
+ *
+ * Forgiving on PURPOSE: models wrap JSON in prose and fences. The FIRST `{`
+ * to the LAST `}` is the only span tried, and anything that does not parse is
+ * `wait` — the caller never sees a throw from parsing.
+ */
+export function parseOverseerDecisionText(text, childAlive) {
+    const first = text.indexOf('{');
+    const last = text.lastIndexOf('}');
+    if (first >= 0 && last > first) {
+        try {
+            return normalizeOverseerDecision(JSON.parse(text.slice(first, last + 1)), childAlive);
+        }
+        catch {
+            // Fall through to the safe default.
+        }
+    }
+    return waitDecision('decision unparseable; defaulting to wait');
+}
+const OVERSEER_SYSTEM_PROMPT = [
+    'You are the supervisor of a team of subagents. You are shown ONE subagent',
+    'that crossed a time trigger (event silence or a wall-clock check) and must',
+    'decide what to do with it. Answer with ONE JSON object and nothing else:',
+    '{"action": "wait" | "nudge" | "replace" | "abandon", "reason": "<= 200 chars",',
+    ' "guidance": "<= 1200 chars, nudge only", "nextCheckMs": <ms, wait only>}.',
+    'wait: the child looks healthy or is legitimately blocked (API backoff,',
+    '  waiting on a teammate or a human confirmation) - keep waiting, pick the',
+    '  next check delay.',
+    'nudge: the child is stuck in a way a hint can fix (wrong path, retrying a',
+    '  failing command, circling) - write the hint as guidance.',
+    'replace: the child cannot recover - a fresh child will be built with your',
+    '  reason and guidance prepended to its brief.',
+    'abandon: the task is not worth more attempts - the child is stopped and',
+    '  your reason is reported to the lead.',
+    'A nudge is only delivered after the child finishes its current tool call;',
+    'a long-running tool is not a stall. Prefer the cheapest action that works.',
+].join('\n');
+function buildInspectionRequest(params) {
+    return {
+        model: params.modelId,
+        ...(params.baseUrl ? { baseUrl: params.baseUrl } : {}),
+        apiKey: params.apiKey,
+        systemPrompt: OVERSEER_SYSTEM_PROMPT,
+        messages: [{ role: 'user', content: params.digest, timestamp: Date.now() }],
+        maxTokens: FAST_LIMITS.reviewOutputTokens,
+        thinkingLevel: 'off',
+        temperature: 0,
+        signal: params.signal,
+    };
+}
+/**
+ * The fast-tier-backed provider, mirroring `createChildReviewer`'s shape so
+ * the controller wires it the same way: shared transport, live predicates,
+ * fail-soft (any failure resolves to `wait` — I-OV2).
+ */
+export function createFastOverseerProvider(deps) {
+    const tier = () => resolveFastTier(deps.getConfig(), deps.hasKey);
+    return {
+        active: () => deps.available() && tier().ok,
+        async inspect(req) {
+            const resolved = tier();
+            if (!deps.available() || !resolved.ok) {
+                return waitDecision('fast tier unavailable; defaulting to wait');
+            }
+            const apiKey = deps.getApiKey(resolved.ref.providerId, 'fast');
+            if (apiKey === undefined) {
+                return waitDecision('no fast-tier key; defaulting to wait');
+            }
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(), FAST_LIMITS.reviewTimeoutMs);
+            try {
+                const message = await deps.complete(resolved.ref.providerId, buildInspectionRequest({
+                    digest: req.digest,
+                    modelId: resolved.ref.modelId,
+                    ...(resolved.ref.baseUrl ? { baseUrl: resolved.ref.baseUrl } : {}),
+                    apiKey,
+                    signal: controller.signal,
+                }));
+                return parseOverseerDecisionText(assistantText(message), true);
+            }
+            catch {
+                // INCLUDING a timeout abort: supervision failing is wait, never kill.
+                return waitDecision('inspection call failed; defaulting to wait');
+            }
+            finally {
+                clearTimeout(timer);
+            }
+        },
+    };
+}
+export const OVERSEER_DEFAULT_NEXT_CHECK_MS = TEAM_LIMITS.overseerDefaultCheckMs;
+/**
+ * Per-dispatch supervisor state: memory, budgets and the single-flight guard.
+ *
+ * THE CLASS NEVER TOUCHES A CHILD (I-OV1). It looks and decides; `runtime.ts`
+ * steers, flags, aborts and rebuilds, because only the worker loop can apply
+ * a lifecycle change without orphaning the replacement.
+ */
+export class TeamOverseer {
+    provider;
+    options;
+    memory = new Map();
+    inspections = new Map();
+    replacements = new Map();
+    inFlight = new Set();
+    constructor(provider, options) {
+        this.provider = provider;
+        this.options = options;
+    }
+    /** Never throws: a provider bug must not take the dispatch down. */
+    isActive() {
+        try {
+            return this.provider.active();
+        }
+        catch {
+            return false;
+        }
+    }
+    inspectionsExhausted(label) {
+        return (this.inspections.get(label) ?? 0) >= TEAM_LIMITS.overseerMaxInspectionsPerChild;
+    }
+    replacementsLeft(label) {
+        return (this.replacements.get(label) ?? 0) < TEAM_LIMITS.overseerMaxReplacementsPerChild;
+    }
+    /** Called by the runtime when it APPLIES a replace, not when it merely reads one. */
+    noteReplacement(label) {
+        this.replacements.set(label, (this.replacements.get(label) ?? 0) + 1);
+    }
+    /**
+     * ONE inspection. `null` means QUIET — not active, no budget left, or one
+     * already in flight for this child — and the caller then does nothing,
+     * which is exactly what quiet should do.
+     */
+    async inspect(req) {
+        const label = req.run.label;
+        if (!this.isActive() || this.inspectionsExhausted(label) || this.inFlight.has(label)) {
+            return null;
+        }
+        this.inFlight.add(label);
+        const now = this.options.now?.() ?? Date.now();
+        const digest = buildChildDigest({
+            run: req.run,
+            childAlive: req.childAlive,
+            trigger: req.trigger,
+            messages: req.messages,
+            memory: this.memory.get(label) ?? [],
+            elapsedSec: Math.max(0, (now - (req.run.startedAt ?? now)) / 1000),
+        });
+        let decision;
+        try {
+            decision = await this.provider.inspect({
+                label,
+                goal: req.run.description,
+                digest,
+            });
+        }
+        catch {
+            decision = waitDecision('inspection threw; defaulting to wait');
+        }
+        finally {
+            this.inFlight.delete(label);
+        }
+        this.inspections.set(label, (this.inspections.get(label) ?? 0) + 1);
+        const entries = this.memory.get(label) ?? [];
+        entries.push({
+            atSec: Math.max(0, Math.round((now - this.options.startedAt) / 1000)),
+            action: decision.action,
+            reason: decision.reason,
+        });
+        this.memory.set(label, entries);
+        return decision;
+    }
+}
+// ---------------------------------------------------------------------------
+// Replacement brief
+// ---------------------------------------------------------------------------
+/** Headroom the amended brief keeps over the original prompt's clamp. */
+const REPLACEMENT_NOTE_CHARS = 800;
+/**
+ * Prepend the supervisor's note to a spec's prompt, bounding the TOTAL to
+ * `TEAM_LIMITS.promptChars` so the replacement fits exactly what a
+ * model-supplied spec would have been allowed to carry.
+ *
+ * THE NOTE TELLS THE FRESH CHILD WHAT THE DEAD ONE DID (`filesTouched` is
+ * best-effort, the same caveat the report's conflict warning carries): a
+ * replacement that rewrites a half-written file blind is not a recovery.
+ */
+export function buildReplacementPrompt(spec, decision, previousRun) {
+    const files = previousRun.filesTouched.length > 0
+        ? ` It already wrote to: ${previousRun.filesTouched.join(', ')}.`
+        : '';
+    const guidance = decision.action === 'replace' && decision.guidance !== undefined
+        ? ` Guidance: ${decision.guidance}`
+        : '';
+    const note = clampChars(`[supervisor note] A previous attempt at this task ran ${previousRun.turns} turns ` +
+        `and was replaced. Reason: ${decision.reason}.${files}${guidance} ` +
+        `Verify rather than assume prior work is complete.\n\n`, REPLACEMENT_NOTE_CHARS);
+    const originalBudget = Math.max(0, TEAM_LIMITS.promptChars - note.length);
+    return `${note}${spec.prompt.slice(0, originalBudget)}`;
+}

package/dist/team/report.js

@@ -117,6 +117,11 @@ function buildSection(run) {
     // the only place the lead learns that a child's first attempt died before it
     // did anything (F-4).
     const retried = run.retries ? `, retried ${run.retries}x` : '';
+    // Same head-line position as `retried Nx`, for the same reason: the ONLY
+    // place the lead learns that a supervisor looked at this child (N times) or
+    // rebuilt it (team-overseer §3.7).
+    const overseen = run.interventions ? `, overseer ${run.interventions}` : '';
+    const replaced = run.replacements ? `, replaced ${run.replacements}x` : '';
     // `compacted N` in the same position `retried Nx` uses, and for the same
     // reason (context-auto-compaction-hardening §3.4.4 / W3): this is the ONLY
     // place the lead learns that a child's own history was summarized mid-task, so
@@ -125,7 +130,7 @@ function buildSection(run) {
     const compacted = run.compactions ? `, compacted ${run.compactions}` : '';
     const head = [
         `### ${run.label} "${run.description}"  ${statusBadge(run)}  ${elapsed(run)}, ` +
-            `${run.turns} turns, ${run.toolCalls} tools${retried}${compacted}`,
+            `${run.turns} turns, ${run.toolCalls} tools${retried}${compacted}${overseen}${replaced}`,
     ];
     if (run.filesTouched.length > 0)
         head.push(`files: ${run.filesTouched.join(', ')}`);
@@ -137,6 +142,23 @@ function buildSection(run) {
     const summary = (run.summary ?? '').trim();
     return { head, summary: summary.length > 0 ? summary : '(no summary)' };
 }
+/**
+ * The supervisor's ledger (team-overseer §3.7): one line per APPLIED decision,
+ * so the lead can see who was nudged or replaced, when, and why. Budgeted by
+ * the same `reportMaxBytes` ladder as everything else - it renders as a block,
+ * so trimming it means trimming the blocks, which the ladder already does.
+ */
+function buildOverseer(outcome) {
+    const list = outcome.interventions ?? [];
+    if (list.length === 0)
+        return [];
+    const lines = ['### Supervisor'];
+    for (const item of list) {
+        const at = Math.max(0, Math.round((item.at - outcome.startedAt) / 1000));
+        lines.push(`[${item.trigger} ${at}s] ${item.label}: ${item.action} - ${item.reason}`);
+    }
+    return lines;
+}
 function buildLeadMail(outcome) {
     if (outcome.leadMail.length === 0)
         return [];
@@ -162,6 +184,7 @@ export function buildDispatchReport(outcome, options = {}) {
     const header = buildHeader(outcome, options);
     const sections = outcome.runs.map(buildSection);
     const mail = buildLeadMail(outcome);
+    const overseer = buildOverseer(outcome);
     const summaries = sections.map((s) => truncateBytes(s.summary, TEAM_LIMITS.summaryMaxBytes));
     const trimmed = summaries.map((s, i) => s.length < sections[i].summary.length);
     const render = (bodies) => {
@@ -174,6 +197,8 @@ export function buildDispatchReport(outcome, options = {}) {
             }
             blocks.push(lines.join('\n'));
         });
+        if (overseer.length > 0)
+            blocks.push(overseer.join('\n'));
         if (mail.length > 0)
             blocks.push(mail.join('\n'));
         return blocks.join('\n\n');

package/dist/team/runtime.d.ts

@@ -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,6 +16,16 @@
  * 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 type { ModelRole } from '../config/model-profiles.js';
 import type { ProviderRegistry, SkillRegistry, ToolPolicyDecision, ToolPolicyVerdict } from '@aragon-agent/core';
@@ -23,6 +33,7 @@ import type { AgentMode } from '../agent/agent-mode.js';
 import type { CliConfig } from '../config/schema.js';
 import type { ToolPermission } from '../exec/permission.js';
 import type { TeamHumanQueue } from './human-queue.js';
+import { type OverseerProvider } from './overseer.js';
 import { type SubagentAgentFactory, type SubagentDeps } from './subagent.js';
 import type { DispatchOutcome, SubagentSpec, TeamEventListener, TeamSnapshot } from './types.js';
 export interface TeamRuntimeDeps {
@@ -67,10 +78,17 @@ export interface TeamRuntimeDeps {
      * Passed straight through to `SubagentDeps`; absent means children get none,
      * which is the pre-hardening behaviour exactly. `AgentController` supplies it
      * from `CompactionWiring.childFactory()`, and the closure returns `undefined`
-     * when compaction is unregistered or `compaction.subagents` is false - which is
-     * what lets `subagent.ts` spread nothing at all.
+     * when compaction is unregistered or `compaction.subagents` is false - which
+     * is what lets `subagent.ts` spread nothing at all.
      */
     contextManagerFor?: SubagentDeps['contextManagerFor'];
+    /**
+     * The dispatch supervisor (team-overseer). ABSENT means the session has no
+     * supervision, and every path below is the pre-feature behaviour exactly.
+     * `active()` is read once per dispatch AND once per inspection (inside
+     * `TeamOverseer`), so a mid-dispatch `/fast off` stops the next look.
+     */
+    overseer?: OverseerProvider;
 }
 export declare class TeamRuntime {
     private readonly deps;
@@ -94,6 +112,16 @@ export declare class TeamRuntime {
      * quietly not for the others.
      */
     private readonly pendingBackoffs;
+    /**
+     * 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.
+     */
+    private overseer;
+    /** The soft timers, same lifetime as `overseer`. */
+    private supervision;
+    /** Applied interventions for the in-flight dispatch's outcome. */
+    private interventions;
     constructor(deps: TeamRuntimeDeps);
     subscribe(listener: TeamEventListener): () => void;
     /**
@@ -109,18 +137,55 @@ export declare class TeamRuntime {
     private worker;
     /**
      * 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).
      */
     private runOne;
     /**
-     * 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.
+     */
+    private maybePostMortem;
+    /**
+     * 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.
+     */
+    private replaceChild;
+    /**
+     * 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.
+     */
+    private isBlocked;
+    /**
+     * 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.
      */
-    private replaceForRetry;
+    private inspectAndApply;
+    private applyDecision;
+    /** Record one applied decision on the outcome, the run and the event stream. */
+    private recordIntervention;
     /**
      * The final phase of an attempt, in a FIXED ORDER: aborted, then timed out,
      * then error, then no-summary, then done.