@aragon-agent/cli 0.6.21 → 0.6.23

package/dist/team/limits.js

@@ -24,13 +24,20 @@
  * is 72 000 bytes, so a character-denominated cap would let the executor chop
  * the report mid-section and take the failure count with it.
  */
+/**
+ * The two factors of the dispatch-total look budget (R-P1-6), hoisted only so
+ * `TEAM_LIMITS.overseerMaxLooksPerDispatch` can state their product without a
+ * second copy of either number. Not for export: the authority is TEAM_LIMITS.
+ */
+const HARD_MAX_SUBAGENTS = 10;
+const OVERSEER_MAX_LOOKS_PER_CHILD = 12;
 export const TEAM_LIMITS = {
     /**
      * The requirement's ceiling (R-g). Enforced in `clampTeamConfig` AND in
      * `normalizeSubagentSpecs`, so neither a hand-edited file nor a model asking
      * for thirty can exceed it.
      */
-    hardMaxSubagents: 10,
+    hardMaxSubagents: HARD_MAX_SUBAGENTS,
     // --- Spec normalization (§3.3.1) ---
     /** `SubagentSpec.description`, clamped (never rejected). */
     descriptionChars: 60,
@@ -106,13 +113,14 @@ export const TEAM_LIMITS = {
      *  nothing a re-dispatch by the lead would not buy better. */
     maxColdStartRetries: 1,
     retryBackoffMs: 2_000,
-    // --- The dispatch supervisor (team-overseer) ---
+    // --- The dispatch supervisor (team-overseer / subagent-overseer-v2) ---
     /**
-     * Wall-clock budget of everything one inspection may carry. The digest holds
-     * run facts, the supervisor's own memory and the tail of the child's live
-     * history; unbounded, one look at a child that read five big files would
-     * make the "cheap" supervision call cost more than the child (the argument
-     * FAST_LIMITS.digestMaxChars makes, one level up).
+     * Wall-clock budget of everything one SINGLE inspection may carry (the
+     * silence-triggered path). The digest holds run facts, the supervisor's own
+     * memory and the tail of the child's live history; unbounded, one look at a
+     * child that read five big files would make the "cheap" supervision call
+     * cost more than the child (the argument FAST_LIMITS.digestMaxChars makes,
+     * one level up).
      */
     overseerDigestBytes: 8_000,
     /** Clamp on a `nudge` guidance text. Advice, not a second brief. */
@@ -120,11 +128,48 @@ export const TEAM_LIMITS = {
     /** Clamp on the decision `reason` recorded in the report. */
     overseerReasonChars: 200,
     /**
-     * Inspections PER CHILD per dispatch. An indecisive supervisor must stop
-     * burning fast-tier calls; past the budget the child simply runs under its
-     * hard ceilings and the supervisor goes quiet.
+     * Per-child slice of a BATCH digest (D-3 / R-P2-5). 6.7x tighter than the
+     * single-inspection budget above: a batch carries up to ten children in one
+     * call, and memory plus the history tail are the first to give way (the
+     * facts-first assembly order already puts them last).
+     */
+    overseerPerChildDigestBytes: 1_200,
+    /** Whole-batch digest ceiling (D-3): 10 children x 1 200 B fits exactly. */
+    overseerBatchDigestBytes: 12_000,
+    /**
+     * Output budget of ONE batch inspection (R-P0-1). The single-inspection path
+     * keeps `FAST_LIMITS.reviewOutputTokens` (512); a batch must return up to
+     * ten decision objects, and 512 tokens cannot physically hold ten x
+     * (reason <= 200 + guidance <= 1200). A truncated batch reply fails
+     * "first `[` to last `]`" parsing and degrades to all-wait - exactly the
+     * failure this separate, larger budget exists to prevent.
+     */
+    overseerBatchOutputTokens: 2_048,
+    /** Tighter `reason` clamp inside the batch protocol (R-P0-1). */
+    overseerBatchReasonChars: 80,
+    /** Tighter `guidance` clamp inside the batch protocol (R-P0-1). */
+    overseerBatchGuidanceChars: 400,
+    /**
+     * LOOKS per child per dispatch (D-5). A look is cost, not mutation: every
+     * inspection of a child - silence-triggered, cadence tick or post-mortem -
+     * spends one, including a call that failed softly. Twelve with the cadence
+     * ladder covers hours of healthy slow work; past the budget the supervisor
+     * says so once (`trigger: 'quiet'`) and stops waking that child up.
+     */
+    overseerMaxLooksPerChild: 12,
+    /**
+     * LOOKS per dispatch, the fool-proof total (R-P1-6):
+     * hardMaxSubagents x overseerMaxLooksPerChild = 120. A mathematical upper
+     * bound, not a tuning knob - the per-child budget always binds first; this
+     * one exists so a bug cannot loop calls forever. When it trips, the whole
+     * MonitorLoop stops with one aggregate notice.
      */
-    overseerMaxInspectionsPerChild: 4,
+    overseerMaxLooksPerDispatch: HARD_MAX_SUBAGENTS * OVERSEER_MAX_LOOKS_PER_CHILD,
+    /**
+     * NUDGES per child per dispatch (D-5). Advice is cheap but not free: a
+     * supervisor that steers the same child forever is one that never decided.
+     */
+    overseerMaxNudgesPerChild: 3,
     /**
      * Rebuilds PER CHILD per dispatch. One: a replacement that also stalls dies
      * on its own watchdog rather than ping-ponging fresh children at a task the
@@ -132,13 +177,25 @@ export const TEAM_LIMITS = {
      */
     overseerMaxReplacementsPerChild: 1,
     /**
-     * First wall-clock check when `team.subagentTimeoutMs === 0` (the shipped
-     * default): the supervisor still looks even when no ceiling was configured.
+     * Abandons PER CHILD per dispatch (D-5). One, so a supervisor that has
+     * already given up on a brief cannot keep re-killing bodies of it.
+     */
+    overseerMaxAbandonsPerChild: 1,
+    /**
+     * Cadence ladder growth factor (D-2). Each no-action inspection schedules
+     * the next `previous * ratio` out, so a healthy slow child is looked at
+     * logarithmically in its run time rather than every five minutes.
+     */
+    overseerCadenceRatio: 1.6,
+    /**
+     * First cadence check when neither `team.overseerIntervalMs` nor
+     * `team.subagentTimeoutMs` names one (the shipped defaults): the supervisor
+     * still looks even when no ceiling was configured.
      */
     overseerDefaultCheckMs: 300_000,
-    /** Clamp on the model-chosen `nextCheckMs`, lower bound. */
+    /** Clamp on a ladder step / model-chosen `nextCheckMs`, lower bound. */
     overseerNextCheckMinMs: 60_000,
-    /** Clamp on the model-chosen `nextCheckMs`, upper bound. */
+    /** Clamp on a ladder step / model-chosen `nextCheckMs`, upper bound. */
     overseerNextCheckMaxMs: 900_000,
     /**
      * A child's OWN idle watchdog, multiplied by this while the supervisor is
@@ -148,6 +205,16 @@ export const TEAM_LIMITS = {
      */
     overseerWatchdogFactor: 4,
 };
+/**
+ * The pseudo-label the runtime's AGGREGATE supervisor notices travel under
+ * (subagent-overseer-v2 D-5 / R-P1-6): the dispatch-total look-budget notice
+ * is one fact about the whole roster, not a row any child owns. RESERVED at
+ * normalization (`normalizeSubagentSpecs` seeds `dedupeLabel` with it), so a
+ * spec asking for the bare label `team` is handed `team-2` instead - the
+ * report ledger and the exec stream can then never attribute an aggregate
+ * notice to a real child, or swallow that child's own quiet note.
+ */
+export const TEAM_AGGREGATE_LABEL = 'team';
 /**
  * The two comm tools, which are POLICY-EXEMPT inside a child (§3.11).
  *

package/dist/team/normalize.js

@@ -24,7 +24,7 @@
  * honest reading of a stale key is silence, not a report line about a
  * capability that no longer exists.
  */
-import { TEAM_LIMITS } from './limits.js';
+import { TEAM_AGGREGATE_LABEL, TEAM_LIMITS } from './limits.js';
 function asString(value) {
     return typeof value === 'string' ? value : '';
 }
@@ -88,7 +88,12 @@ export function normalizeSubagentSpecs(raw, max) {
         return { specs: [], requested: 0 };
     const requested = raw.length;
     const kept = [];
-    const taken = new Set();
+    // SEEDED WITH THE RESERVED AGGREGATE LABEL (subagent-overseer-v2 D-5 /
+    // R-P1-6): the runtime's dispatch-total supervisor notices travel under
+    // `TEAM_AGGREGATE_LABEL`, so no child may wear that slug - `dedupeLabel`
+    // hands a spec asking for it the suffixed form instead, the same namespace
+    // fix it already applies to any other collision.
+    const taken = new Set([TEAM_AGGREGATE_LABEL]);
     for (let i = 0; i < raw.length; i += 1) {
         const item = raw[i];
         if (!item || typeof item !== 'object')

package/dist/team/overseer.d.ts

@@ -1,33 +1,58 @@
 /**
- * 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 type { AssistantMessage, LLMRequest, Message } from '@aragon-agent/core';
+import type { AssistantMessage, LLMRequest, Message, TokenUsage } from '@aragon-agent/core';
 import type { ModelRole } from '../config/model-profiles.js';
 import type { CliConfig } from '../config/schema.js';
 import type { OverseerAction, OverseerDecision, SubagentRun, SubagentSpec } from './types.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 declare const OVERSEER_PROMPT_VERSION = "v3-2026-10";
 /** One remembered decision, so the second look knows the first happened. */
 export interface OverseerMemoryEntry {
     /** Seconds into the dispatch. */
@@ -40,7 +65,7 @@ export interface ChildDigestInput {
     run: SubagentRun;
     /** False only in the post-mortem inspection, after the child settled. */
     childAlive: boolean;
-    trigger: 'silence' | 'clock' | 'postmortem';
+    trigger: 'silence' | 'clock' | 'turncap' | 'postmortem';
     /** The child's LIVE history (`SubagentAgentLike.state.messages`). */
     messages: readonly Message[];
     memory: readonly OverseerMemoryEntry[];
@@ -57,6 +82,38 @@ export interface ChildDigestInput {
  * is worse than one missing the fifth message back.
  */
 export declare function buildChildDigest(input: ChildDigestInput): string;
+/**
+ * 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 declare function buildBatchSections(children: readonly ChildDigestInput[]): Array<{
+    label: string;
+    goal: string;
+    digest: string;
+}>;
+/**
+ * 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 declare function resolveOverseerFirstCheckMs(team: {
+    overseerIntervalMs: number;
+    subagentTimeoutMs: number;
+}): number;
+/**
+ * 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 declare function nextOverseerLadderStepMs(previousMs: number): number;
 /** Clamp a model-chosen next check into the structural range. */
 export declare function clampNextCheckMs(ms: unknown): number | undefined;
 /**
@@ -66,6 +123,10 @@ export declare function clampNextCheckMs(ms: unknown): number | undefined;
  * 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 declare function normalizeOverseerDecision(raw: unknown, childAlive: boolean): OverseerDecision;
 /**
@@ -76,16 +137,47 @@ export declare function normalizeOverseerDecision(raw: unknown, childAlive: bool
  * `wait` — the caller never sees a throw from parsing.
  */
 export declare function parseOverseerDecisionText(text: string, childAlive: boolean): OverseerDecision;
-/** The slice the runtime needs: "can you look?" and "decide". */
+/**
+ * Parse the model's answer text as a JSON ARRAY of per-child decisions (D-3).
+ *
+ * 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 declare function parseOverseerBatchText(text: string): unknown[];
+/**
+ * The slice the runtime needs: "can you look?", "decide", "what did looking
+ * cost?". The provider is the CALL boundary; `TeamOverseer` owns budgets,
+ * memory and normalization, so a stub in a test scripts decisions by
+ * returning objects or arrays and nothing else.
+ */
 export interface OverseerProvider {
-    /** Live predicate, re-read per dispatch AND per inspection. */
+    /** Live predicate, re-read per tick: this, not the dispatch-time value, decides assisted vs unassisted (R-P0-2). */
     active(): boolean;
-    /** One bounded decision call. Implementations must not throw. */
+    /** One bounded SINGLE-child decision call (silence path). Must not throw. */
     inspect(req: {
         label: string;
         goal: string;
         digest: string;
     }): Promise<OverseerDecision>;
+    /**
+     * One bounded BATCH call (cadence path, D-3). Returns the RAW reply - the
+     * fast provider answers the assistant TEXT - for `TeamOverseer` to parse
+     * and normalize. Must not throw.
+     */
+    inspectBatch(req: ReadonlyArray<{
+        label: string;
+        goal: string;
+        digest: string;
+    }>): Promise<unknown>;
+    /**
+     * Everything this provider has spent on inspection calls (D-7, honest
+     * accounting). Read once by the runtime at dispatch end; there is exactly
+     * one accounting of it and no second aggregation path.
+     */
+    usage(): TokenUsage;
 }
 /** Everything the fast-tier-backed provider needs from the session. */
 export interface FastOverseerDeps {
@@ -102,13 +194,18 @@ export interface FastOverseerDeps {
  * 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 declare function createFastOverseerProvider(deps: FastOverseerDeps): OverseerProvider;
 /** One inspection request, as the runtime builds it. */
 export interface OverseerInspectRequest {
     run: SubagentRun;
     messages: readonly Message[];
-    trigger: 'silence' | 'clock' | 'postmortem';
+    trigger: 'silence' | 'clock' | 'turncap' | 'postmortem';
     childAlive: boolean;
 }
 export interface TeamOverseerOptions {
@@ -123,27 +220,70 @@ export declare const OVERSEER_DEFAULT_NEXT_CHECK_MS: 300000;
  * 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 declare class TeamOverseer {
     private readonly provider;
     private readonly options;
     private readonly memory;
-    private readonly inspections;
+    private readonly looks;
+    private readonly nudges;
     private readonly replacements;
+    private readonly abandons;
     private readonly inFlight;
+    private looksTotal;
+    private callCount;
     constructor(provider: OverseerProvider, options: TeamOverseerOptions);
     /** Never throws: a provider bug must not take the dispatch down. */
     isActive(): boolean;
-    inspectionsExhausted(label: string): boolean;
+    /** Whether ANY inspection of `label` is in flight (single or batch). */
+    isInFlight(label: string): boolean;
+    /** Per-child look budget spent (D-5). */
+    looksExhausted(label: string): boolean;
+    /** The fool-proof dispatch-wide total (R-P1-6). */
+    dispatchLooksExhausted(): boolean;
+    nudgesLeft(label: string): boolean;
     replacementsLeft(label: string): boolean;
+    abandonsLeft(label: string): boolean;
+    /** Called by the runtime when it APPLIES a nudge, not when it merely reads one. */
+    noteNudge(label: string): void;
     /** Called by the runtime when it APPLIES a replace, not when it merely reads one. */
     noteReplacement(label: string): void;
+    /** Called by the runtime when it APPLIES an abandon, not when it merely reads one. */
+    noteAbandon(label: string): void;
+    /** The provider's own accumulated inspection spend (D-7), zero when unreadable. */
+    usage(): TokenUsage;
+    /** Provider invocations, including ones that failed softly (D-7). */
+    calls(): number;
     /**
-     * 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.
      */
     inspect(req: OverseerInspectRequest): Promise<OverseerDecision | null>;
+    /**
+     * 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).
+     */
+    inspectBatch(reqs: readonly OverseerInspectRequest[]): Promise<Map<string, OverseerDecision>>;
+    private spendLook;
+    private remember;
 }
 /**
  * Prepend the supervisor's note to a spec's prompt, bounding the TOTAL to