@aragon-agent/cli 0.6.21 → 0.6.23

package/dist/team/overseer.js

@@ -1,34 +1,59 @@
 /**
- * The dispatch supervisor (team-overseer).
+ * The dispatch supervisor (team-overseer, upgraded by subagent-overseer-v2).
  *
  * 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:
+ * When a child stalls (event silence) or a cadence tick comes due, 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 SUPERVISOR IS A NO-LOOP, BOUNDED, REMEMBERED CALLEE - NOT AN AGENT
+ * (subagent-overseer-v2 D-1). The requirement says "a dedicated supervising
+ * subagent on the fast model"; it is satisfied by a per-dispatch, remembered,
+ * cadence-woken caller on the fast tier rather than a real `Agent.prompt()`
+ * loop, because a supervisor that can itself wedge needs a second supervisor.
+ *
+ * TWO INSPECTION SHAPES (D-3). Event silence triggers a SINGLE-child look
+ * (fast reaction to a suspected stall, unchanged from round 1); the cadence
+ * ladder triggers a BATCH look that carries every live child in one digest
+ * and returns one JSON array of per-child decisions. The batch call carries
+ * its own output budget (`overseerBatchOutputTokens`, R-P0-1): a full
+ * ten-child reply does not physically fit in the single-inspection 512
+ * tokens, and a truncated reply would parse to nothing - all wait, exactly
+ * when help is most needed.
+ *
  * 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.
+ * tools, thinking off, temperature 0, output capped (512 single /
+ * 2048 batch) 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).
+ * "looked and killed it" (I-OV2). In a batch, one bad ENTRY degrades only
+ * that entry; a wholly unparseable reply degrades the whole batch to wait
+ * with zero action side effects (R-P0-1 / AC-13).
  */
 import { resolveFastTier } from '../fast/resolve.js';
-import { assistantText } from '../fast/review-call.js';
+import { accumulateUsage, assistantText, usageOf } from '../fast/review-call.js';
 import { FAST_LIMITS } from '../fast/limits.js';
 import { truncateBytes } from './report.js';
 import { TEAM_LIMITS } from './limits.js';
+/**
+ * Bumped whenever either supervisor protocol prompt changes (D-9), so a
+ * behaviour report can be tied to a prompt revision with one grep.
+ * `TEAM_BLOCK_VERSION` covers only the LEAD's `<team>` block, not these.
+ *
+ * v3 adds the turn-cap trigger to the single-inspection prompt (F-8 A'2).
+ */
+export const OVERSEER_PROMPT_VERSION = 'v3-2026-10';
 /** How many trailing history messages the digest carries. */
 const DIGEST_TAIL_MESSAGES = 8;
 /** Per-message text clamp inside the digest. */
@@ -55,6 +80,13 @@ function messageText(message) {
 function clampChars(text, max) {
     return text.length <= max ? text : `${text.slice(0, Math.max(0, max - 3))}...`;
 }
+/** One line per trigger, as the digest names it (a union VALUE, never prose). */
+const TRIGGER_LABELS = {
+    silence: 'event silence (suspected stall)',
+    clock: 'wall-clock check',
+    turncap: 'turn cap reached (inspection trigger, not a stop)',
+    postmortem: 'post-mortem (child already ended)',
+};
 /**
  * Build the bounded text one inspection reads.
  *
@@ -68,7 +100,7 @@ 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(`trigger: ${TRIGGER_LABELS[trigger]}`);
     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}` : ''));
@@ -94,6 +126,51 @@ export function buildChildDigest(input) {
     }
     return truncateBytes(lines.join('\n'), TEAM_LIMITS.overseerDigestBytes);
 }
+/**
+ * The per-child sections of one batch payload (D-3).
+ *
+ * SORTED BY LABEL so the same roster produces the byte-identical payload -
+ * the batch is the one place where ordering is observable to the model and
+ * to every test that asserts on it. Each child's digest is clamped to
+ * `overseerPerChildDigestBytes` (facts first, history tail last - R-P2-5).
+ * The whole-batch ceiling is applied by the joiner in the provider request.
+ */
+export function buildBatchSections(children) {
+    return [...children]
+        .sort((a, b) => a.run.label.localeCompare(b.run.label, 'en'))
+        .map((child) => ({
+        label: child.run.label,
+        goal: child.run.description,
+        digest: truncateBytes(buildChildDigest(child), TEAM_LIMITS.overseerPerChildDigestBytes),
+    }));
+}
+// ---------------------------------------------------------------------------
+// Cadence ladder (D-2) - pure math, so tests assert arithmetic, not timers
+// ---------------------------------------------------------------------------
+/**
+ * The FIRST cadence check, from the D-8 priority: `overseerIntervalMs` when
+ * the user named one; otherwise a positive `subagentTimeoutMs` (compat with
+ * users who already treated it as a trigger); otherwise the structural
+ * default. Read-only derivation - the user's stored config is never
+ * rewritten to "resolve" this.
+ */
+export function resolveOverseerFirstCheckMs(team) {
+    if (team.overseerIntervalMs > 0)
+        return team.overseerIntervalMs;
+    if (team.subagentTimeoutMs > 0)
+        return team.subagentTimeoutMs;
+    return TEAM_LIMITS.overseerDefaultCheckMs;
+}
+/**
+ * The next ladder step after one that produced no action: grow by
+ * `overseerCadenceRatio`, clamped to the structural range. With the shipped
+ * 300 s base the checks land at 300 / 780 / 1548 / 2448 / ... seconds - a
+ * healthy slow child is looked at logarithmically in its run time (AC-11).
+ */
+export function nextOverseerLadderStepMs(previousMs) {
+    const grown = Math.round(previousMs * TEAM_LIMITS.overseerCadenceRatio);
+    return Math.min(TEAM_LIMITS.overseerNextCheckMaxMs, Math.max(TEAM_LIMITS.overseerNextCheckMinMs, grown));
+}
 // ---------------------------------------------------------------------------
 // Decision normalization
 // ---------------------------------------------------------------------------
@@ -119,8 +196,39 @@ function waitDecision(reason, nextCheckMs) {
  * 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.
+ *
+ * The single-inspection char limits (200/1200) are the defaults here; the
+ * batch path calls `normalizeWithLimits` directly with the tighter protocol
+ * limits (R-P0-1).
  */
 export function normalizeOverseerDecision(raw, childAlive) {
+    return normalizeWithLimits(raw, childAlive, {
+        reasonChars: TEAM_LIMITS.overseerReasonChars,
+        guidanceChars: TEAM_LIMITS.overseerGuidanceChars,
+    });
+}
+/**
+ * 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');
+}
+/** Normalize with EXPLICIT limits so the two protocols stay independently tunable. */
+function normalizeWithLimits(raw, childAlive, limits) {
     const obj = (raw && typeof raw === 'object' ? raw : {});
     const action = typeof obj.action === 'string' && VALID_ACTIONS.has(obj.action)
         ? obj.action
@@ -129,7 +237,7 @@ export function normalizeOverseerDecision(raw, childAlive) {
         ? obj.reason.trim()
         : 'no reason given';
     const guidance = typeof obj.guidance === 'string' && obj.guidance.trim().length > 0
-        ? clampChars(obj.guidance.trim(), TEAM_LIMITS.overseerGuidanceChars)
+        ? clampChars(obj.guidance.trim(), limits.guidanceChars)
         : undefined;
     const nextCheckMs = clampNextCheckMs(obj.nextCheckMs);
     if (!childAlive && (action === 'wait' || action === 'nudge')) {
@@ -140,35 +248,41 @@ export function normalizeOverseerDecision(raw, childAlive) {
     }
     return {
         action,
-        reason: clampChars(reason, TEAM_LIMITS.overseerReasonChars),
+        reason: clampChars(reason, limits.reasonChars),
         ...(guidance !== undefined && action === 'nudge' ? { guidance } : {}),
         ...(action === 'wait' && nextCheckMs !== undefined ? { nextCheckMs } : {}),
     };
 }
 /**
- * Parse the model's answer text as one JSON decision object.
+ * Parse the model's answer text as a JSON ARRAY of per-child decisions (D-3).
  *
- * 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.
+ * Same forgiving span rule as the single path - first `[` to last `]` - and
+ * the same failure semantics: a reply that is not an array (prose, a single
+ * object, or TRUNCATED output with no closing `]`) is `[]`, which the caller
+ * turns into all-wait with zero action side effects (R-P0-1 / AC-13). Never
+ * throws.
  */
-export function parseOverseerDecisionText(text, childAlive) {
-    const first = text.indexOf('{');
-    const last = text.lastIndexOf('}');
+export function parseOverseerBatchText(text) {
+    const first = text.indexOf('[');
+    const last = text.lastIndexOf(']');
     if (first >= 0 && last > first) {
         try {
-            return normalizeOverseerDecision(JSON.parse(text.slice(first, last + 1)), childAlive);
+            const parsed = JSON.parse(text.slice(first, last + 1));
+            if (Array.isArray(parsed))
+                return parsed;
         }
         catch {
-            // Fall through to the safe default.
+            // Fall through to the empty batch.
         }
     }
-    return waitDecision('decision unparseable; defaulting to wait');
+    return [];
 }
 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:',
+    'that crossed a supervision trigger (event silence, a wall-clock check, or',
+    'the configured turn cap) and must decide what to do with it. Crossing a',
+    'ceiling does NOT stop the child - your decision does. 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,',
@@ -183,6 +297,30 @@ const OVERSEER_SYSTEM_PROMPT = [
     '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');
+const OVERSEER_BATCH_SYSTEM_PROMPT = [
+    'You are the supervisor of a team of subagents. You are shown EVERY live',
+    'subagent of one dispatch, separated by --- lines, on a periodic check.',
+    'Decide ONCE PER SUBAGENT. Answer with ONE JSON array and nothing else -',
+    'one object per subagent, using exactly the label shown:',
+    '[{"label": "<label>", "action": "wait" | "nudge" | "replace" | "abandon",',
+    '  "reason": "<= 80 chars", "guidance": "<= 400 chars, nudge only",',
+    '  "nextCheckMs": <ms, wait only>}, ...]',
+    'Keep every reason and guidance SHORT: the whole array must fit a small',
+    'output budget and a truncated array helps nobody.',
+    '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 - 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.',
+    'You may use whole-team judgement: a child far behind healthy peers on the',
+    'same brief is a different signal than one slow child alone.',
+    '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,
@@ -196,44 +334,94 @@ function buildInspectionRequest(params) {
         signal: params.signal,
     };
 }
+function buildBatchRequest(params) {
+    return {
+        model: params.modelId,
+        ...(params.baseUrl ? { baseUrl: params.baseUrl } : {}),
+        apiKey: params.apiKey,
+        systemPrompt: OVERSEER_BATCH_SYSTEM_PROMPT,
+        messages: [{ role: 'user', content: params.digest, timestamp: Date.now() }],
+        // NOT FAST_LIMITS.reviewOutputTokens: a ten-child array does not fit 512
+        // tokens, and a truncated reply parses to all-wait (R-P0-1 / AC-13).
+        maxTokens: TEAM_LIMITS.overseerBatchOutputTokens,
+        thinkingLevel: 'off',
+        temperature: 0,
+        signal: params.signal,
+    };
+}
+const NO_USAGE = { inputTokens: 0, outputTokens: 0 };
 /**
  * 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).
+ *
+ * USAGE IS ACCUMULATED HERE (D-7), off every `AssistantMessage` the shared
+ * transport returns, along the same `usageOf` / `accumulateUsage` path the
+ * fast reviewer already proved. A reply without a usage block contributes
+ * nothing rather than a fabricated zero-cost total.
  */
 export function createFastOverseerProvider(deps) {
     const tier = () => resolveFastTier(deps.getConfig(), deps.hasKey);
+    let totalUsage = { ...NO_USAGE };
+    const call = async (build) => {
+        const resolved = tier();
+        if (!deps.available() || !resolved.ok)
+            return null;
+        const apiKey = deps.getApiKey(resolved.ref.providerId, 'fast');
+        if (apiKey === undefined)
+            return null;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), FAST_LIMITS.reviewTimeoutMs);
+        try {
+            const message = await deps.complete(resolved.ref.providerId, build(resolved.ref, apiKey, controller.signal));
+            totalUsage = accumulateUsage(totalUsage, usageOf(message).usage);
+            return assistantText(message);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    };
     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({
+                const text = await call((ref, apiKey, signal) => buildInspectionRequest({
                     digest: req.digest,
-                    modelId: resolved.ref.modelId,
-                    ...(resolved.ref.baseUrl ? { baseUrl: resolved.ref.baseUrl } : {}),
+                    modelId: ref.modelId,
+                    ...(ref.baseUrl ? { baseUrl: ref.baseUrl } : {}),
                     apiKey,
-                    signal: controller.signal,
+                    signal,
                 }));
-                return parseOverseerDecisionText(assistantText(message), true);
+                if (text === null)
+                    return waitDecision('fast tier unavailable; defaulting to wait');
+                return parseOverseerDecisionText(text, true);
             }
             catch {
                 // INCLUDING a timeout abort: supervision failing is wait, never kill.
                 return waitDecision('inspection call failed; defaulting to wait');
             }
-            finally {
-                clearTimeout(timer);
+        },
+        async inspectBatch(req) {
+            try {
+                // The joiner owns the WHOLE-BATCH ceiling (D-3): sections arrive
+                // per-child-clamped and label-sorted; `hardMaxSubagents` means the
+                // clamp is a guard, not a squeeze.
+                const digest = truncateBytes(req.map((r) => `### ${r.label}\n${r.digest}`).join('\n---\n'), TEAM_LIMITS.overseerBatchDigestBytes);
+                const text = await call((ref, apiKey, signal) => buildBatchRequest({
+                    digest,
+                    modelId: ref.modelId,
+                    ...(ref.baseUrl ? { baseUrl: ref.baseUrl } : {}),
+                    apiKey,
+                    signal,
+                }));
+                return text ?? '';
+            }
+            catch {
+                // INCLUDING a timeout abort: supervision failing is wait, never kill.
+                return '';
             }
         },
+        usage: () => ({ ...totalUsage }),
     };
 }
 export const OVERSEER_DEFAULT_NEXT_CHECK_MS = TEAM_LIMITS.overseerDefaultCheckMs;
@@ -243,14 +431,27 @@ export const OVERSEER_DEFAULT_NEXT_CHECK_MS = TEAM_LIMITS.overseerDefaultCheckMs
  * 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.
+ *
+ * LOOKS AND ACTIONS ARE SEPARATE LEDGERS (D-5). A LOOK is cost: every
+ * inspection of a child spends one, including a call that failed softly -
+ * which is what closes G-6 (a flaky transport used to burn the budget the
+ * same as a decision, and the supervisor went quiet exactly when the team
+ * was hardest to see). An ACTION is a mutation (nudge / replace / abandon)
+ * and is counted only when the runtime APPLIES it, through the `note*`
+ * methods below. A label skipped because an inspection is already in flight
+ * spends NOTHING (R-P1-4).
  */
 export class TeamOverseer {
     provider;
     options;
     memory = new Map();
-    inspections = new Map();
+    looks = new Map();
+    nudges = new Map();
     replacements = new Map();
+    abandons = new Map();
     inFlight = new Set();
+    looksTotal = 0;
+    callCount = 0;
     constructor(provider, options) {
         this.provider = provider;
         this.options = options;
@@ -264,24 +465,62 @@ export class TeamOverseer {
             return false;
         }
     }
-    inspectionsExhausted(label) {
-        return (this.inspections.get(label) ?? 0) >= TEAM_LIMITS.overseerMaxInspectionsPerChild;
+    /** Whether ANY inspection of `label` is in flight (single or batch). */
+    isInFlight(label) {
+        return this.inFlight.has(label);
+    }
+    /** Per-child look budget spent (D-5). */
+    looksExhausted(label) {
+        return ((this.looks.get(label) ?? 0) >= TEAM_LIMITS.overseerMaxLooksPerChild ||
+            this.dispatchLooksExhausted());
+    }
+    /** The fool-proof dispatch-wide total (R-P1-6). */
+    dispatchLooksExhausted() {
+        return this.looksTotal >= TEAM_LIMITS.overseerMaxLooksPerDispatch;
+    }
+    nudgesLeft(label) {
+        return (this.nudges.get(label) ?? 0) < TEAM_LIMITS.overseerMaxNudgesPerChild;
     }
     replacementsLeft(label) {
         return (this.replacements.get(label) ?? 0) < TEAM_LIMITS.overseerMaxReplacementsPerChild;
     }
+    abandonsLeft(label) {
+        return (this.abandons.get(label) ?? 0) < TEAM_LIMITS.overseerMaxAbandonsPerChild;
+    }
+    /** Called by the runtime when it APPLIES a nudge, not when it merely reads one. */
+    noteNudge(label) {
+        this.nudges.set(label, (this.nudges.get(label) ?? 0) + 1);
+    }
     /** 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);
     }
+    /** Called by the runtime when it APPLIES an abandon, not when it merely reads one. */
+    noteAbandon(label) {
+        this.abandons.set(label, (this.abandons.get(label) ?? 0) + 1);
+    }
+    /** The provider's own accumulated inspection spend (D-7), zero when unreadable. */
+    usage() {
+        try {
+            return this.provider.usage();
+        }
+        catch {
+            return { ...NO_USAGE };
+        }
+    }
+    /** Provider invocations, including ones that failed softly (D-7). */
+    calls() {
+        return this.callCount;
+    }
     /**
-     * ONE inspection. `null` means QUIET — not active, no budget left, or one
-     * already in flight for this child — and the caller then does nothing,
+     * ONE single-child inspection (the silence-triggered path, round-1
+     * behaviour preserved). `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)) {
+        if (!this.isActive() || this.looksExhausted(label) || this.inFlight.has(label)) {
             return null;
         }
         this.inFlight.add(label);
@@ -295,6 +534,7 @@ export class TeamOverseer {
             elapsedSec: Math.max(0, (now - (req.run.startedAt ?? now)) / 1000),
         });
         let decision;
+        this.callCount += 1;
         try {
             decision = await this.provider.inspect({
                 label,
@@ -308,7 +548,75 @@ export class TeamOverseer {
         finally {
             this.inFlight.delete(label);
         }
-        this.inspections.set(label, (this.inspections.get(label) ?? 0) + 1);
+        this.spendLook(label);
+        this.remember(label, now, decision);
+        return decision;
+    }
+    /**
+     * ONE batch inspection over every requested child (the cadence path, D-3):
+     * a single fast-tier call, a JSON array back, one decision per child.
+     *
+     * SKIPS FIRST, CALLS SECOND (R-P1-4): a label whose single inspection is
+     * still in flight, or whose look budget is spent, simply gets NO entry -
+     * no decision, no look charged, ladder untouched by the caller. A label
+     * that IS carried but whose reply entry is missing or garbage gets `wait`
+     * (repair, never reject). A wholly unparseable or truncated reply is ALL
+     * wait with zero action side effects (R-P0-1 / AC-13).
+     */
+    async inspectBatch(reqs) {
+        const eligible = reqs.filter((req) => !this.inFlight.has(req.run.label) && !this.looksExhausted(req.run.label));
+        if (eligible.length === 0 || !this.isActive())
+            return new Map();
+        const now = this.options.now?.() ?? Date.now();
+        const inputs = eligible.map((req) => ({
+            run: req.run,
+            childAlive: req.childAlive,
+            trigger: 'clock',
+            messages: req.messages,
+            memory: this.memory.get(req.run.label) ?? [],
+            elapsedSec: Math.max(0, (now - (req.run.startedAt ?? now)) / 1000),
+        }));
+        const sections = buildBatchSections(inputs);
+        for (const req of eligible)
+            this.inFlight.add(req.run.label);
+        this.callCount += 1;
+        let raw;
+        try {
+            raw = await this.provider.inspectBatch(sections);
+        }
+        catch {
+            raw = [];
+        }
+        finally {
+            for (const req of eligible)
+                this.inFlight.delete(req.run.label);
+        }
+        const entries = typeof raw === 'string' ? parseOverseerBatchText(raw) : Array.isArray(raw) ? raw : [];
+        const byLabel = new Map();
+        for (const entry of entries) {
+            const label = entry?.label;
+            if (typeof label === 'string' && label.length > 0 && !byLabel.has(label)) {
+                byLabel.set(label, entry);
+            }
+        }
+        const decisions = new Map();
+        for (const input of inputs) {
+            const label = input.run.label;
+            const decision = normalizeWithLimits(byLabel.get(label), input.childAlive, {
+                reasonChars: TEAM_LIMITS.overseerBatchReasonChars,
+                guidanceChars: TEAM_LIMITS.overseerBatchGuidanceChars,
+            });
+            this.spendLook(label);
+            this.remember(label, now, decision);
+            decisions.set(label, decision);
+        }
+        return decisions;
+    }
+    spendLook(label) {
+        this.looks.set(label, (this.looks.get(label) ?? 0) + 1);
+        this.looksTotal += 1;
+    }
+    remember(label, now, decision) {
         const entries = this.memory.get(label) ?? [];
         entries.push({
             atSec: Math.max(0, Math.round((now - this.options.startedAt) / 1000)),
@@ -316,7 +624,6 @@ export class TeamOverseer {
             reason: decision.reason,
         });
         this.memory.set(label, entries);
-        return decision;
     }
 }
 // ---------------------------------------------------------------------------

package/dist/team/report.d.ts

@@ -28,6 +28,15 @@ export interface ReportOptions {
      * THE ONE TABLE, because every child runs the lead's own model
      * (main-agent parity): one tier, one price, one honest total. */
     cost?: ModelCost;
+    /**
+     * The FAST tier's cost table, so the supervisor's own spend line can
+     * state real spend (subagent-overseer-v2 D-7 / R-P1-2). Supplied by
+     * `TaskToolDeps.fastModelCost()`; ABSENT when the fast model is not
+     * priced, in which case the spend line says `pricing unknown` rather
+     * than `$0.00` - unknown pricing is not zero pricing (the C-11 / RV-4
+     * rule the fast tier already follows everywhere else).
+     */
+    fastCost?: ModelCost;
 }
 /**
  * Cut `text` to at most `maxBytes` WITHOUT splitting a UTF-8 sequence.

package/dist/team/report.js

@@ -21,7 +21,9 @@
  * because of one HTTP 429.
  */
 import { computeCost, formatCost, formatDuration, formatTokens } from '../agent/usage.js';
-import { TEAM_LIMITS } from './limits.js';
+import { TEAM_AGGREGATE_LABEL, TEAM_LIMITS } from './limits.js';
+/** The pseudo-label aggregate notices use; reserved at normalization. */
+const SUPERVISOR_TEAM_LABEL = TEAM_AGGREGATE_LABEL;
 function byteLength(text) {
     return Buffer.byteLength(text, 'utf8');
 }
@@ -147,16 +149,42 @@ function buildSection(run) {
  * 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.
+ *
+ * subagent-overseer-v2 appends three aggregates, each AT MOST ONCE (D-7 /
+ * D-10): the fast-tier spend line, a degraded-cadence note and a
+ * went-quiet note. Aggregates, never per-tick rows: a degraded dispatch
+ * ticks for hours and the report's job is the fact, not the log.
  */
-function buildOverseer(outcome) {
+function buildOverseer(outcome, options) {
     const list = outcome.interventions ?? [];
-    if (list.length === 0)
+    const calls = outcome.overseerCalls ?? 0;
+    const degraded = outcome.overseerDegraded === true;
+    // The pseudo-label aggregate (`team`) is a note, not a child's ledger row.
+    const quietChildren = list.filter((item) => item.trigger === 'quiet' && item.label !== SUPERVISOR_TEAM_LABEL).length;
+    if (list.length === 0 && calls === 0 && !degraded)
         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}`);
     }
+    // Honest accounting (D-7): rendered only when calls were actually made,
+    // priced at the FAST table, `pricing unknown` when that table is absent.
+    if (calls > 0 && outcome.overseerUsage !== undefined) {
+        const price = options.fastCost
+            ? formatCost(computeCost(outcome.overseerUsage, options.fastCost))
+            : 'pricing unknown';
+        lines.push(`supervisor: ${calls} call${calls === 1 ? '' : 's'}, ${formatTokens(outcome.overseerUsage.inputTokens)} in / ${formatTokens(outcome.overseerUsage.outputTokens)} out tokens` +
+            ` (fast tier), ${price}.`);
+    }
+    if (degraded) {
+        lines.push(`note: the fast tier was unavailable for ${outcome.overseerDegradedTicks ?? 1}` +
+            ` cadence check(s); children waited unassisted and none were killed.`);
+    }
+    if (quietChildren > 0) {
+        lines.push(`note: supervision went quiet on ${quietChildren}` +
+            ` child${quietChildren === 1 ? '' : 'ren'} after its look budget.`);
+    }
     return lines;
 }
 function buildLeadMail(outcome) {
@@ -184,7 +212,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 overseer = buildOverseer(outcome, options);
     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) => {