@aragon-agent/cli 0.5.8 → 0.5.10

package/dist/launcher.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+/**
+ * The bin entry (cli-auto-update-hardening section 5.1.1).
+ *
+ * ASCII ONLY - this file is inside the glyph scanner's scope (C-19).
+ *
+ * KEEP IT THIS SMALL. Every import here is a module that can crash before the
+ * guard that exists to survive crashes. `node:process` is the only static one,
+ * and `__tests__/update-wiring.test.ts` asserts that on the source text.
+ *
+ * `dist/cli.js` IS UNCHANGED AND KEEPS ITS SHEBANG (R-17 / AC-50). Only the
+ * `bin` mapping moves; `npm start` (`node dist/cli.js`) and any user script that
+ * invokes `dist/cli.js` directly keep working byte for byte.
+ */
+import process from 'node:process';
+try {
+    // DYNAMIC, AND THAT IS THE WHOLE POINT (P1-2 / R-22). A STATIC import of the
+    // guard would put `boot/guard -> update/state -> config/app-paths ->
+    // env-paths` in the bin entry's OWN module graph, and a resolution failure
+    // anywhere in that chain throws during THIS module's evaluation - outside the
+    // `try`, before any line of it runs. "An undeclared dependency" is the first
+    // way section 1.1 says a release bricks itself; a guard whose own import fails
+    // in that exact case has to degrade to "no guard", never to "no CLI".
+    const { runBootGuard } = await import('./boot/guard.js');
+    runBootGuard();
+}
+catch {
+    // A guard that throws must never be the reason the CLI will not start. This is
+    // the one catch in the package that is allowed to be empty: there is no logger
+    // yet, and there is nothing the user could do with the message.
+}
+// The `.catch` is for the IMPORT rejecting, which is precisely the import-time
+// crash H1 exists for and which today produces an unhandled rejection with a
+// stack the user cannot act on. `cli.js` runs `main()` at module scope and
+// installs its own `.catch` for everything after that point.
+//
+// EXITING NON-ZERO HERE IS WHAT FEEDS THE GUARD'S COUNTER (D-30a): the exit hook
+// the guard installed counts non-zero exits, and a module that will not import
+// raises, so it arrives here.
+await import('./cli.js').catch((err) => {
+    process.stderr.write(`${err instanceof Error ? (err.stack ?? err.message) : String(err)}\n`);
+    process.exitCode = 1;
+});

package/dist/logging/install.d.ts

@@ -121,11 +121,25 @@ export type AgentLogEvent = {
         inputTokens?: number;
         outputTokens?: number;
     };
-} | {
+}
+/**
+ * `streamEvent` carries the retry fields OPTIONALLY (llm-api-retry-backoff
+ * §6.8): this union is a deliberately loose structural mirror of core's
+ * `AgentEvent` so a stub controller can satisfy it with an object literal, and
+ * narrowing on `streamEvent.type` inside the handler is what makes the extra
+ * fields safe to read.
+ */
+ | {
     type: 'message_update';
     streamEvent?: {
         type?: string;
         delta?: unknown;
+        attempt?: number;
+        maxRetries?: number;
+        delayMs?: number;
+        errorType?: string;
+        retryAfterMs?: number;
+        discardedToolCallIds?: string[];
     };
 } | {
     type: 'tool_execution_start';

package/dist/logging/install.js

@@ -251,17 +251,50 @@ export function attachAgentEvents(logger, controller) {
                     ms: turnStartedAt > 0 ? Date.now() - turnStartedAt : 0,
                 });
                 break;
-            case 'message_update':
+            case 'message_update': {
+                // API retry (llm-api-retry-backoff §6.8), ABOVE the `trace` line so a
+                // three-minute pause is in the log at the DEFAULT level. Redaction is
+                // unaffected: the payload carries no user content, and `message` is already
+                // the truncated body `classifyHttpError` produces.
+                const se = event.streamEvent;
+                if (se?.type === 'retry_scheduled') {
+                    const cfg = controller.getConfig();
+                    logger.warn('agent', 'llm_retry_scheduled', {
+                        attempt: se.attempt,
+                        maxRetries: se.maxRetries,
+                        delayMs: se.delayMs,
+                        errorType: se.errorType,
+                        retryAfterMs: se.retryAfterMs,
+                        providerId: cfg.provider,
+                        modelId: cfg.model,
+                    });
+                    break;
+                }
+                if (se?.type === 'retry_attempt') {
+                    logger.debug('agent', 'llm_retry_attempt', {
+                        attempt: se.attempt,
+                        maxRetries: se.maxRetries,
+                    });
+                    break;
+                }
+                if (se?.type === 'stream_restart') {
+                    logger.warn('agent', 'llm_stream_restart', {
+                        attempt: se.attempt,
+                        discarded: se.discardedToolCallIds?.length ?? 0,
+                    });
+                    break;
+                }
                 logger.trace('agent', 'stream', {
-                    type: event.streamEvent?.type ?? 'unknown',
+                    type: se?.type ?? 'unknown',
                     // The SIZE of the increment, never the increment. It is what makes a
                     // trace log usable for "where did the time go" without turning it
                     // into a second copy of the conversation.
-                    delta: typeof event.streamEvent?.delta === 'string'
-                        ? event.streamEvent.delta.length
+                    delta: typeof se?.delta === 'string'
+                        ? se.delta.length
                         : undefined,
                 });
                 break;
+            }
             case 'tool_execution_start':
                 logger.debug('tool', 'tool_start', {
                     toolCallId: event.toolCallId,

package/dist/logging/logger.d.ts

@@ -23,7 +23,7 @@
 import type { LogConfig } from '../config/schema.js';
 import { type LogLevelName } from './levels.js';
 /** Closed set, not free text: a typo'd scope is a record nobody can filter on. */
-export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'history';
+export type LogScope = 'cli' | 'config' | 'agent' | 'tool' | 'skills' | 'llm' | 'migrate' | 'log' | 'fast' | 'history' | 'update';
 export interface LogRecord {
     ts: string;
     lv: LogLevelName;

package/dist/session/persist.js

@@ -28,6 +28,37 @@ function defaultStamp() {
     // Filesystem-safe timestamp without punctuation that breaks on Windows.
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/**
+ * Drop the live tool tail on the way to disk (agent-activity-presentation-live
+ * D-24 / AC-34).
+ *
+ * THIS IS THE SERIALIZER, AND IT IS THE ONLY ONE (P1-2). `saveSession` writes
+ * `entries` VERBATIM -- the module doc below says so in those words -- and
+ * `agent/reducer.ts` contains no serializer at all, so a `/save` issued DURING a
+ * run would capture `live` / `liveSeq` / `lastOutputAt` however carefully the
+ * reducer were written.
+ *
+ * Three reasons to drop it, in order of weight: a resumed session's tail
+ * describes a process that no longer exists; the settled `preview` supersedes it
+ * entirely, so it is strictly redundant; and it is the only mutable-while-live
+ * field a tool entry has, so persisting it would force a `normalizeLoadedEntries`
+ * clause -- the class of clause round 1's D-9 exists for.
+ *
+ * STRIPPING RATHER THAN TRUSTING ABSENCE IS WHAT MAKES DECLINING THAT CLAUSE
+ * HONEST. A tool entry saved mid-run keeps `status: 'running'` and
+ * `normalizeLoadedEntries` has no clause for tool entries (it never has -- the
+ * four it carries are all about other kinds). With the tail stripped, `showLive`
+ * is false and the resumed card is byte-identical to what today's build draws
+ * for the same file: one `running` row. With the tail present it would be a
+ * multi-row card describing a process that died with the last session, counting
+ * seconds against a `lastOutputAt` from yesterday.
+ */
+function stripLiveToolOutput(entries) {
+    return entries.map((e) => e.kind === 'tool' &&
+        (e.live !== undefined || e.liveSeq !== undefined || e.lastOutputAt !== undefined)
+        ? { ...e, live: undefined, liveSeq: undefined, lastOutputAt: undefined }
+        : e);
+}
 /**
  * `data` GAINS `todos`, AND WIDENING `SavedSession` ALONE IS NOT ENOUGH (P0-2):
  * the writer below builds its payload from THIS parameter, not from the type, so
@@ -43,7 +74,7 @@ export function saveSession(filePath, data) {
         savedAt: Date.now(),
         model: data.model,
         messages: data.messages,
-        entries: data.entries,
+        entries: stripLiveToolOutput(data.entries),
         todos: data.todos,
     };
     writeFileSync(filePath, `${JSON.stringify(payload, null, 2)}\n`, 'utf-8');
@@ -75,6 +106,31 @@ export function normalizeLoadedEntries(entries) {
         if (entry.kind === 'todo' && entry.live) {
             return { ...entry, live: false, interrupted: true };
         }
+        // THE THIRD CLAUSE (llm-api-retry-backoff §6.4 / R-10 / AC-26). A card saved
+        // mid-wait would resume claiming to be counting down to an instant in the past,
+        // and — worse — it would never settle, so `Transcript`'s MONOTONIC boundary
+        // would never advance past it and every frame for the rest of the session
+        // would re-render the whole tail. `resumeAt` is dropped for the same reason
+        // the phase changes: there is no attempt coming.
+        if (entry.kind === 'retry' && (entry.phase === 'waiting' || entry.phase === 'retrying')) {
+            return { ...entry, phase: 'interrupted', resumeAt: undefined };
+        }
+        // THE FOURTH CLAUSE (fast-model-tier §5.4 / C-5 / AC-28). A review card
+        // saved while its call was open resumes claiming to be running while nothing
+        // is, and — the part that actually costs — it never settles, so
+        // `Transcript`'s MONOTONIC boundary never advances past it and every frame
+        // for the rest of the session re-renders the whole tail.
+        //
+        // `dropped` rather than `failed`: the review did not fail, it never got an
+        // answer, and its critique died with the process.
+        if (entry.kind === 'fast' && entry.live) {
+            return {
+                ...entry,
+                live: false,
+                status: 'dropped',
+                detail: 'interrupted (session resumed)',
+            };
+        }
         return entry;
     });
 }

package/dist/team/normalize.d.ts

@@ -23,6 +23,26 @@ export interface NormalizedSpecs {
     specs: SubagentSpec[];
     /** How many entries the model asked for, before dropping and capping. */
     requested: number;
+    /**
+     * Specs that asked for `model:"fast"` and were downgraded to `main`
+     * (fast-model-tier §3.4 / R-6).
+     *
+     * ADDITIVE: `NormalizedSpecs` GAINS a field, it does not change one, so every
+     * existing caller and test compiles unchanged.
+     */
+    downgraded: number;
+}
+/** Options for the fast tier. Optional for the reason `normalizeSubagentSpecs`
+ *  documents below (RV-14). */
+export interface NormalizeOptions {
+    /**
+     * §3.3's LIVE predicate, evaluated at DISPATCH time (RV-3).
+     *
+     * `fast.delegate: false` and "the tier stopped resolving twenty minutes ago"
+     * are the same observable to the model — a downgrade, counted and reported —
+     * which is the honest reading of both.
+     */
+    fastAvailable?: boolean;
 }
 /**
  * Repair and bound a raw `subagents` array.
@@ -35,5 +55,10 @@ export interface NormalizedSpecs {
  * @param max   The resolved `team.maxSubagents`; further clamped to
  *              `TEAM_LIMITS.hardMaxSubagents` here so a hand-edited config file
  *              cannot raise the requirement's ceiling (R-g).
+ * @param opts  Fast-tier availability. OPTIONAL, DEFAULTING TO `false` (RV-14):
+ *              this function and `NormalizedSpecs` are both exported and both
+ *              have existing callers and tests, so a required third parameter
+ *              would be a breaking edit that buys nothing — and an omitted one
+ *              now means exactly what a pre-feature build meant.
  */
-export declare function normalizeSubagentSpecs(raw: unknown, max: number): NormalizedSpecs;
+export declare function normalizeSubagentSpecs(raw: unknown, max: number, opts?: NormalizeOptions): NormalizedSpecs;

package/dist/team/normalize.js

@@ -76,13 +76,21 @@ function dedupeLabel(label, taken) {
  * @param max   The resolved `team.maxSubagents`; further clamped to
  *              `TEAM_LIMITS.hardMaxSubagents` here so a hand-edited config file
  *              cannot raise the requirement's ceiling (R-g).
+ * @param opts  Fast-tier availability. OPTIONAL, DEFAULTING TO `false` (RV-14):
+ *              this function and `NormalizedSpecs` are both exported and both
+ *              have existing callers and tests, so a required third parameter
+ *              would be a breaking edit that buys nothing — and an omitted one
+ *              now means exactly what a pre-feature build meant.
  */
-export function normalizeSubagentSpecs(raw, max) {
+export function normalizeSubagentSpecs(raw, max, opts = {}) {
     if (!Array.isArray(raw))
-        return { specs: [], requested: 0 };
+        return { specs: [], requested: 0, downgraded: 0 };
     const requested = raw.length;
+    const fastAvailable = opts.fastAvailable === true;
     const kept = [];
     const taken = new Set();
+    /** Parallel to `kept`: did entry `i` ask for the fast tier? */
+    const wantedFast = [];
     for (let i = 0; i < raw.length; i += 1) {
         const item = raw[i];
         if (!item || typeof item !== 'object')
@@ -94,13 +102,25 @@ export function normalizeSubagentSpecs(raw, max) {
         const prompt = clamp(asString(src.prompt), TEAM_LIMITS.promptChars);
         if (prompt.length === 0)
             continue;
+        // REPAIR, NEVER REJECT — this file's own contract. `'fast'` without
+        // availability becomes `'main'` AND IS COUNTED; anything else (a typo, a
+        // model id, `undefined`) is simply `'main'` and is NOT counted, because the
+        // model did not ask for the fast tier and has nothing to be told about.
+        const wantsFast = src.model === 'fast';
+        wantedFast.push(wantsFast);
         kept.push({
             label: dedupeLabel(slugLabel(src.label, kept.length), taken),
             description,
             prompt,
             readOnly: src.readOnly === true,
+            tier: wantsFast && fastAvailable ? 'fast' : 'main',
         });
     }
     const ceiling = Math.max(1, Math.min(Math.floor(max) || 1, TEAM_LIMITS.hardMaxSubagents));
-    return { specs: kept.slice(0, ceiling), requested };
+    const specs = kept.slice(0, ceiling);
+    // COUNTED OVER THE SURVIVORS, not over everything the model wrote: a spec the
+    // cap dropped never ran at all, so reporting it as "ran on the main model"
+    // would be a second, different lie in a line that exists to stop the first.
+    const downgraded = specs.filter((spec, i) => spec.tier === 'main' && wantedFast[i] === true).length;
+    return { specs, requested, downgraded };
 }

package/dist/team/prompt.d.ts

@@ -18,6 +18,17 @@ export { TEAM_BLOCK_VERSION };
 export interface TeamBlockParams {
     maxSubagents: number;
     maxConcurrent: number;
+    /**
+     * Whether `model:"fast"` is honoured on `task` right now (fast-model-tier
+     * §3.8).
+     *
+     * ONE SENTENCE, AND ONLY WHEN IT IS TRUE. `<fast_tier>` carries the full
+     * guidance; this is the cross-reference that stops a model reading
+     * `<team_mode>` in isolation and concluding every child costs the same. With
+     * it absent the block is BYTE-IDENTICAL to the pre-feature output, which is
+     * what `--no-fast` and every existing snapshot depend on.
+     */
+    fastDelegation?: boolean;
 }
 /**
  * The lead's `<team_mode>` block. Under 1200 characters on purpose: it is paid

package/dist/team/prompt.js

@@ -47,6 +47,16 @@ export function buildTeamBlock(params) {
         'report back. Give each one a disjoint set of files to write. Subagents cannot',
         'dispatch further subagents and cannot ask the user anything.',
         '',
+        // THE TRAILING BLANK IS INSIDE THE CONDITIONAL, not outside it. An
+        // unconditional `''` here would add a line to EVERY team-enabled prompt and
+        // silently break the byte-identity `--no-fast` depends on (I-2).
+        ...(params.fastDelegation
+            ? [
+                'A subagent doing mechanical, high-volume work can run on the cheaper fast',
+                'model - see <fast_tier>.',
+                '',
+            ]
+            : []),
         'You get one combined report when they all finish. Read it before deciding what',
         'to do next, and tell the user what the team found in your own words.',
         '</team_mode>',

package/dist/team/report.d.ts

@@ -25,6 +25,24 @@ import type { DispatchOutcome, SubagentRun } from './types.js';
 export interface ReportOptions {
     /** The lead's model cost table, so the header can state real spend (R-5). */
     cost?: ModelCost;
+    /**
+     * The FAST model's cost table (fast-model-tier §3.4 / R-7).
+     *
+     * A SECOND TABLE, not a second number derived from the first. Summing
+     * fast-tier tokens at the lead's price over-reports a Haiku child under a
+     * Sonnet lead by roughly an order of magnitude, and the whole justification
+     * for delegating to a cheaper model is the figure on this line.
+     */
+    fastCost?: ModelCost;
+    /**
+     * The static price table has never heard of the fast model (C-11 / RV-4).
+     *
+     * UNKNOWN PRICING IS NOT ZERO PRICING. `buildRuntimeModel` hands back
+     * `cost: { input: 0, output: 0 }` for an unrecognised id, and the fast tier is
+     * precisely where an unrecognised id is LIKELY — so rendering it as `$0.00`
+     * would make the feature look free while it is spending money.
+     */
+    fastPricingUnknown?: boolean;
 }
 /**
  * Cut `text` to at most `maxBytes` WITHOUT splitting a UTF-8 sequence.

package/dist/team/report.js

@@ -106,6 +106,28 @@ function buildHeader(outcome, options) {
             `(${counts}) in ${formatDuration(durationMs)}.`);
     lines.push(`Tokens: in ${formatTokens(outcome.usage.inputTokens)}, out ` +
         `${formatTokens(outcome.usage.outputTokens)}. Cost: ${formatCost(computeCost(outcome.usage, options.cost))}.`);
+    // A SECOND LINE, NOT A COMBINED TOTAL (fast-model-tier §3.4). Two tiers with
+    // two price tables have two answers, and folding them into one figure is the
+    // misattribution R-7 is about. Present only when a fast child actually ran, so
+    // an ordinary dispatch's header is byte-identical.
+    const fastUsage = outcome.fastUsage;
+    if (fastUsage) {
+        // `unknown` rather than a currency amount when the model has no price table
+        // (RV-4): a lower bound rendered as a total is the same class of lie as
+        // pricing a Haiku child at Sonnet rates.
+        const fastCostLabel = options.fastPricingUnknown
+            ? 'unknown (no price table)'
+            : formatCost(computeCost(fastUsage, options.fastCost));
+        lines.push(`Fast tier: in ${formatTokens(fastUsage.inputTokens)}, out ` +
+            `${formatTokens(fastUsage.outputTokens)}. Cost: ${fastCostLabel}.`);
+    }
+    // THE LINE THAT KEEPS A DOWNGRADE FROM BEING SILENT (R-6). Without it the
+    // model asked for a cheap child, got an expensive one, and has no way to learn
+    // that its cost model is wrong.
+    if (outcome.downgraded && outcome.downgraded > 0) {
+        const n = outcome.downgraded;
+        lines.push(`${n} ${n === 1 ? 'subagent' : 'subagents'} ran on the main model (fast tier off).`);
+    }
     for (const conflict of findFileConflicts(outcome.runs)) {
         const who = conflict.labels.map((l) => `"${l}"`).join(' and ');
         lines.push(`WARNING: agents ${who} both wrote ${conflict.path} - review before trusting either.`);
@@ -117,8 +139,12 @@ 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` : '';
+    // `[fast]` after the LABEL, on the head line, which is never trimmed. Six
+    // bytes, and it is the only place the lead learns which of its children were
+    // cheap — the fact the whole second cost line is about.
+    const tier = run.tier === 'fast' ? ' [fast]' : '';
     const head = [
-        `### ${run.label} "${run.description}"  ${statusBadge(run)}  ${elapsed(run)}, ` +
+        `### ${run.label}${tier} "${run.description}"  ${statusBadge(run)}  ${elapsed(run)}, ` +
             `${run.turns} turns, ${run.toolCalls} tools${retried}`,
     ];
     if (run.filesTouched.length > 0)

package/dist/team/runtime.d.ts

@@ -21,7 +21,7 @@ import type { ProviderRegistry, SkillRegistry, ToolPolicyDecision, ToolPolicyVer
 import type { AgentMode } from '../agent/agent-mode.js';
 import type { CliConfig } from '../config/schema.js';
 import type { TeamHumanQueue } from './human-queue.js';
-import { type SubagentAgentFactory } from './subagent.js';
+import { type SubagentAgentFactory, type SubagentDeps } from './subagent.js';
 import type { DispatchOutcome, SubagentSpec, TeamEventListener, TeamSnapshot } from './types.js';
 export interface TeamRuntimeDeps {
     /** Read LIVE: a settings-screen model or key edit must reach the next dispatch. */
@@ -42,6 +42,12 @@ export interface TeamRuntimeDeps {
     humanQueue?: TeamHumanQueue;
     /** Test seam (§8.1): a stub factory keeps the whole scheduler off the network. */
     agentFactory?: SubagentAgentFactory;
+    /**
+     * Per-tier model resolution (fast-model-tier §3.4). Passed straight through to
+     * `SubagentDeps`; absent means every child runs on the session's model, which
+     * is the pre-feature behaviour.
+     */
+    resolveTier?: SubagentDeps['resolveTier'];
 }
 export declare class TeamRuntime {
     private readonly deps;
@@ -75,7 +81,12 @@ export declare class TeamRuntime {
     isBusy(): boolean;
     /** The live roster, for `/team` status. `null` when nothing is dispatching. */
     snapshot(): TeamSnapshot | null;
-    dispatch(specs: SubagentSpec[], requested: number, signal?: AbortSignal): Promise<DispatchOutcome>;
+    dispatch(specs: SubagentSpec[], requested: number, signal?: AbortSignal, 
+    /** Carried through from the normalizer so the report can state it (§3.4 /
+     *  R-6). Optional, so every existing caller compiles unchanged. */
+    extra?: {
+        downgraded?: number;
+    }): Promise<DispatchOutcome>;
     /** One slot of the pool: take the next index until the list is exhausted. */
     private worker;
     /**

package/dist/team/runtime.js

@@ -65,7 +65,10 @@ export class TeamRuntime {
     // -------------------------------------------------------------------------
     // Dispatch
     // -------------------------------------------------------------------------
-    async dispatch(specs, requested, signal) {
+    async dispatch(specs, requested, signal, 
+    /** Carried through from the normalizer so the report can state it (§3.4 /
+     *  R-6). Optional, so every existing caller compiles unchanged. */
+    extra = {}) {
         this.counter += 1;
         const dispatchId = `d${this.counter}`;
         const config = this.deps.getConfig();
@@ -122,6 +125,7 @@ export class TeamRuntime {
             confirmTools: config.confirmTools,
             ...(this.deps.humanQueue ? { humanQueue: this.deps.humanQueue } : {}),
             agentFactory: this.deps.agentFactory ?? defaultSubagentFactory,
+            ...(this.deps.resolveTier ? { resolveTier: this.deps.resolveTier } : {}),
         };
         // Hoisted into a factory so a retry can build a fresh child with IDENTICAL
         // wiring (F-4). Replacing the child rather than re-prompting it is the only
@@ -130,7 +134,11 @@ export class TeamRuntime {
         // show the child its brief twice.
         const makeHandle = (spec) => createSubagent(spec, subDeps, {
             onUpdate: (run) => this.publish(dispatchId, run),
-            onUsage: (label, usage) => this.emit({ type: 'usage', dispatchId, label, usage }),
+            // `tier` rides along so `App.tsx` can pick the RIGHT cost table for this
+            // event rather than always using the lead's (§3.6 / R-7). Taken from the
+            // SPEC, which the normalizer already downgraded when the tier was
+            // unavailable, so it names the model that actually billed.
+            onUsage: (label, usage) => this.emit({ type: 'usage', dispatchId, label, usage, tier: spec.tier }),
         });
         // 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
@@ -174,6 +182,24 @@ export class TeamRuntime {
         signal?.removeEventListener('abort', onAbort);
         for (const handle of handles)
             handle.unsubscribe();
+        // SUMMED PER TIER (fast-model-tier §3.4 / R-7). One total priced at the
+        // lead's table would over-report a Haiku child under a Sonnet lead by
+        // roughly an order of magnitude — and the whole justification for delegating
+        // to a cheaper model is a number in the report this feeds.
+        // `main` IS THE COMPLEMENT OF `fast`, not an equality test. `SubagentRun.tier`
+        // is populated by `createSubagent` from the spec, but a hand-built run in a
+        // test — or a run restored from a session file written before this field
+        // existed — has it `undefined`, and `=== 'main'` would silently drop that
+        // child's spend from the total. Under-reporting is the one failure this
+        // split exists to prevent, so the default direction has to be "counted".
+        const sumTier = (tier) => handles
+            .filter((h) => (tier === 'fast' ? h.run.tier === 'fast' : h.run.tier !== 'fast'))
+            .reduce((acc, h) => ({
+            inputTokens: acc.inputTokens + h.run.usage.inputTokens,
+            outputTokens: acc.outputTokens + h.run.usage.outputTokens,
+        }), { inputTokens: 0, outputTokens: 0 });
+        const fastUsage = sumTier('fast');
+        const ranFast = handles.some((h) => h.run.tier === 'fast');
         const outcome = {
             dispatchId,
             runs: handles.map((h) => ({ ...h.run, filesTouched: [...h.run.filesTouched] })),
@@ -182,10 +208,11 @@ export class TeamRuntime {
             endedAt: Date.now(),
             aborted: this.aborted,
             leadMail: bus.leadMail(),
-            usage: handles.reduce((acc, h) => ({
-                inputTokens: acc.inputTokens + h.run.usage.inputTokens,
-                outputTokens: acc.outputTokens + h.run.usage.outputTokens,
-            }), { inputTokens: 0, outputTokens: 0 }),
+            usage: sumTier('main'),
+            // ABSENT when no fast child ran, which is what keeps a default session's
+            // outcome shape byte-identical to the pre-feature one.
+            ...(ranFast ? { fastUsage } : {}),
+            ...(extra.downgraded ? { downgraded: extra.downgraded } : {}),
         };
         this.live = [];
         this.bus = null;

package/dist/team/subagent.d.ts

@@ -10,9 +10,10 @@
  * them (§3.11 / R-6). What a child does NOT get is spelled out below, and each
  * omission has a reason that is a correctness boundary rather than caution.
  */
-import { type AgentConfig, type AgentEvent, type AgentTool, type ProviderRegistry, type SkillRegistry, type TokenUsage, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
+import { type AgentConfig, type AgentEvent, type AgentTool, type ModelRef, type ProviderRegistry, type SkillRegistry, type ThinkingLevel, type TokenUsage, type ToolPolicyDecision, type ToolPolicyVerdict } from '@aragon-agent/core';
 import type { AgentMode } from '../agent/agent-mode.js';
 import type { CliConfig } from '../config/schema.js';
+import type { FastTierName } from '../fast/types.js';
 import { TeamBus } from './bus.js';
 import type { TeamHumanQueue, WatchdogPausable } from './human-queue.js';
 import type { SubagentRun, SubagentSpec } from './types.js';
@@ -61,6 +62,23 @@ export interface SubagentDeps {
     /** Present only when `--confirm` is on AND a human channel exists. */
     humanQueue?: TeamHumanQueue;
     agentFactory: SubagentAgentFactory;
+    /**
+     * Which model and thinking level a tier runs on (fast-model-tier §3.4).
+     *
+     * OPTIONAL, defaulting to the session's own model, so every existing caller
+     * and test compiles unchanged and a `--no-fast` session builds children
+     * exactly as it always did.
+     *
+     * `resolveTier('fast')` RETURNS THE MAIN TIER when the fast tier is not
+     * available, which is what makes the two guards agree BY CONSTRUCTION: the
+     * normalizer can never produce a `tier: 'fast'` spec this factory would
+     * refuse, and this factory can never build a child against a `ModelRef` the
+     * tier stopped resolving twenty minutes ago (RV-3 / R-14).
+     */
+    resolveTier?: (tier: FastTierName) => {
+        ref: ModelRef;
+        thinkingLevel: ThinkingLevel;
+    };
 }
 export interface SubagentHooks {
     /** Coalesced at the source (§5.2); phase transitions always pass. */