@aragon-agent/cli 0.5.2 → 0.5.3

package/dist/team/normalize.d.ts

@@ -0,0 +1,39 @@
+/**
+ * `normalizeSubagentSpecs` — pure repair of whatever the model put in the `task`
+ * call (team-subagents §3.3.1).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * MODELLED DIRECTLY ON `human-input.ts::normalizeQuestions`, INCLUDING THE
+ * REASON IT EXISTS. The JSON Schema declares SHAPE, not POLICY: `type` and
+ * `required` stay in the schema because a `subagents` value that is not an array
+ * has nothing for a normalizer to repair. Every BOUND lives in the tool's
+ * `description` (which is what the model reads) and is enforced here (which is
+ * deterministic and unit-tested). Putting `maxItems: 10` in the schema instead
+ * would behave differently depending on whether `ajv` — an OPTIONAL dependency
+ * of `@aragon-agent/core` — happened to install: present, the executor rejects an
+ * eleven-spec call outright and these rules are dead code; absent, the same call
+ * sails straight through to here. One design, two behaviours, selected by
+ * whether an optional install step succeeded.
+ *
+ * NEVER THROWS. Zero survivors is the caller's single hard failure.
+ */
+import type { SubagentSpec } from './types.js';
+export interface NormalizedSpecs {
+    specs: SubagentSpec[];
+    /** How many entries the model asked for, before dropping and capping. */
+    requested: number;
+}
+/**
+ * Repair and bound a raw `subagents` array.
+ *
+ * DROP FIRST, CAP SECOND. Capping first would let a blank entry consume a slot
+ * the model meant for real work — the fan-out would silently be one narrower
+ * than the model believed, and nothing would say so.
+ *
+ * @param raw   Whatever arrived in `params.subagents`.
+ * @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).
+ */
+export declare function normalizeSubagentSpecs(raw: unknown, max: number): NormalizedSpecs;

package/dist/team/normalize.js

@@ -0,0 +1,106 @@
+/**
+ * `normalizeSubagentSpecs` — pure repair of whatever the model put in the `task`
+ * call (team-subagents §3.3.1).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * MODELLED DIRECTLY ON `human-input.ts::normalizeQuestions`, INCLUDING THE
+ * REASON IT EXISTS. The JSON Schema declares SHAPE, not POLICY: `type` and
+ * `required` stay in the schema because a `subagents` value that is not an array
+ * has nothing for a normalizer to repair. Every BOUND lives in the tool's
+ * `description` (which is what the model reads) and is enforced here (which is
+ * deterministic and unit-tested). Putting `maxItems: 10` in the schema instead
+ * would behave differently depending on whether `ajv` — an OPTIONAL dependency
+ * of `@aragon-agent/core` — happened to install: present, the executor rejects an
+ * eleven-spec call outright and these rules are dead code; absent, the same call
+ * sails straight through to here. One design, two behaviours, selected by
+ * whether an optional install step succeeded.
+ *
+ * NEVER THROWS. Zero survivors is the caller's single hard failure.
+ */
+import { TEAM_LIMITS } from './limits.js';
+function asString(value) {
+    return typeof value === 'string' ? value : '';
+}
+function clamp(text, maxChars) {
+    const trimmed = text.trim();
+    return trimmed.length > maxChars ? trimmed.slice(0, maxChars) : trimmed;
+}
+/**
+ * Slugify a label to `[a-z0-9-]{1,12}`. An empty result falls back to the
+ * positional default so a child is never nameless in the panel.
+ */
+function slugLabel(raw, index) {
+    const slug = asString(raw)
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, TEAM_LIMITS.labelChars);
+    return slug.length > 0 ? slug : `a${index + 1}`;
+}
+/**
+ * Make `label` unique within the dispatch, case-insensitively, by appending
+ * `-2`, `-3`, ...
+ *
+ * Two agents the user cannot tell apart in the panel is worse than an ugly
+ * label, and the bus addresses children BY label — a duplicate would make
+ * `team_send` ambiguous, which is a correctness problem rather than a cosmetic
+ * one.
+ */
+function dedupeLabel(label, taken) {
+    const base = label.toLowerCase();
+    if (!taken.has(base)) {
+        taken.add(base);
+        return label;
+    }
+    for (let n = 2; n < 100; n += 1) {
+        const suffix = `-${n}`;
+        const candidate = `${label.slice(0, TEAM_LIMITS.labelChars - suffix.length)}${suffix}`;
+        if (!taken.has(candidate.toLowerCase())) {
+            taken.add(candidate.toLowerCase());
+            return candidate;
+        }
+    }
+    taken.add(base);
+    return label;
+}
+/**
+ * Repair and bound a raw `subagents` array.
+ *
+ * DROP FIRST, CAP SECOND. Capping first would let a blank entry consume a slot
+ * the model meant for real work — the fan-out would silently be one narrower
+ * than the model believed, and nothing would say so.
+ *
+ * @param raw   Whatever arrived in `params.subagents`.
+ * @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).
+ */
+export function normalizeSubagentSpecs(raw, max) {
+    if (!Array.isArray(raw))
+        return { specs: [], requested: 0 };
+    const requested = raw.length;
+    const kept = [];
+    const taken = new Set();
+    for (let i = 0; i < raw.length; i += 1) {
+        const item = raw[i];
+        if (!item || typeof item !== 'object')
+            continue;
+        const src = item;
+        const description = clamp(asString(src.description), TEAM_LIMITS.descriptionChars);
+        if (description.length === 0)
+            continue;
+        const prompt = clamp(asString(src.prompt), TEAM_LIMITS.promptChars);
+        if (prompt.length === 0)
+            continue;
+        kept.push({
+            label: dedupeLabel(slugLabel(src.label, kept.length), taken),
+            description,
+            prompt,
+            readOnly: src.readOnly === true,
+        });
+    }
+    const ceiling = Math.max(1, Math.min(Math.floor(max) || 1, TEAM_LIMITS.hardMaxSubagents));
+    return { specs: kept.slice(0, ceiling), requested };
+}

package/dist/team/panel-rows.d.ts

@@ -0,0 +1,48 @@
+/**
+ * `selectPanelRows` - which children the live roster shows (team-live-activity
+ * F-2).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * THE DEFECT THIS REPLACES. `TeamPanel` took the first `panelMaxRows` runs by
+ * ARRAY INDEX, and the slot pool hands out indices from a shared cursor in
+ * order - so at `maxSubagents: 8, maxConcurrent: 3` the first five rows are the
+ * five that finished first and everything still working sits behind `+3 more`.
+ * The one thing the requirement asks the panel for - show that subagents are
+ * running - is the one thing it stopped doing at the fan-out widths the
+ * requirement explicitly permits.
+ *
+ * Pure: a function of a roster snapshot and a row cap, with no clock, no
+ * terminal and no `Agent` anywhere near it.
+ */
+import type { SubagentRun } from './types.js';
+export interface PanelRows {
+    visible: SubagentRun[];
+    hiddenTotal: number;
+    hiddenRunning: number;
+}
+/**
+ * Rank the roster so that what is VISIBLE is what is HAPPENING.
+ *
+ * Ordering inside each group is chosen for ROW STABILITY, which is the real
+ * usability constraint here: the panel re-renders every 200 ms and a row that
+ * changes position on each tick is unreadable.
+ *  - running: by `startedAt` ascending. `startedAt` changes exactly once in a
+ *    run's life outside of its first assignment - on a cold-start retry (F-4),
+ *    which re-stamps it (P2-4). A retried child therefore moves to the end of
+ *    the running group, once, at the moment it visibly restarts. That is the
+ *    correct reading of the ordering rule rather than an exception to it: the
+ *    group is ordered by "how long has this been going", and a retry resets
+ *    exactly that.
+ *  - queued: original order; that IS the order the pool will start them in.
+ *  - settled: most recently ended first, so the newest result is the one that
+ *    stays on screen as others complete.
+ * A run changes position at most twice in its life - queued -> running ->
+ * settled - and each move carries real information.
+ *
+ * The final tiebreak is the original index. `Array.prototype.sort` is stable in
+ * every Node this package supports, so the tiebreak is not load-bearing; it is
+ * here so the ordering is total and the test can assert it without depending on
+ * that guarantee.
+ */
+export declare function selectPanelRows(runs: SubagentRun[], max: number): PanelRows;

package/dist/team/panel-rows.js

@@ -0,0 +1,75 @@
+/**
+ * `selectPanelRows` - which children the live roster shows (team-live-activity
+ * F-2).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * THE DEFECT THIS REPLACES. `TeamPanel` took the first `panelMaxRows` runs by
+ * ARRAY INDEX, and the slot pool hands out indices from a shared cursor in
+ * order - so at `maxSubagents: 8, maxConcurrent: 3` the first five rows are the
+ * five that finished first and everything still working sits behind `+3 more`.
+ * The one thing the requirement asks the panel for - show that subagents are
+ * running - is the one thing it stopped doing at the fan-out widths the
+ * requirement explicitly permits.
+ *
+ * Pure: a function of a roster snapshot and a row cap, with no clock, no
+ * terminal and no `Agent` anywhere near it.
+ */
+const RUNNING = new Set(['starting', 'thinking', 'tool', 'waiting']);
+const SETTLED = new Set(['done', 'failed', 'aborted']);
+/** 0 running, 1 queued, 2 settled. */
+function group(run) {
+    if (RUNNING.has(run.phase))
+        return 0;
+    if (SETTLED.has(run.phase))
+        return 2;
+    return 1;
+}
+/**
+ * Rank the roster so that what is VISIBLE is what is HAPPENING.
+ *
+ * Ordering inside each group is chosen for ROW STABILITY, which is the real
+ * usability constraint here: the panel re-renders every 200 ms and a row that
+ * changes position on each tick is unreadable.
+ *  - running: by `startedAt` ascending. `startedAt` changes exactly once in a
+ *    run's life outside of its first assignment - on a cold-start retry (F-4),
+ *    which re-stamps it (P2-4). A retried child therefore moves to the end of
+ *    the running group, once, at the moment it visibly restarts. That is the
+ *    correct reading of the ordering rule rather than an exception to it: the
+ *    group is ordered by "how long has this been going", and a retry resets
+ *    exactly that.
+ *  - queued: original order; that IS the order the pool will start them in.
+ *  - settled: most recently ended first, so the newest result is the one that
+ *    stays on screen as others complete.
+ * A run changes position at most twice in its life - queued -> running ->
+ * settled - and each move carries real information.
+ *
+ * The final tiebreak is the original index. `Array.prototype.sort` is stable in
+ * every Node this package supports, so the tiebreak is not load-bearing; it is
+ * here so the ordering is total and the test can assert it without depending on
+ * that guarantee.
+ */
+export function selectPanelRows(runs, max) {
+    const ranked = runs
+        .map((run, index) => ({ run, index }))
+        .sort((a, b) => {
+        const ga = group(a.run);
+        const gb = group(b.run);
+        if (ga !== gb)
+            return ga - gb;
+        if (ga === 0)
+            return (a.run.startedAt ?? 0) - (b.run.startedAt ?? 0) || a.index - b.index;
+        if (ga === 2)
+            return (b.run.endedAt ?? 0) - (a.run.endedAt ?? 0) || a.index - b.index;
+        return a.index - b.index;
+    })
+        .map((e) => e.run);
+    const limit = Math.max(0, max);
+    const visible = ranked.slice(0, limit);
+    const hidden = ranked.slice(limit);
+    return {
+        visible,
+        hiddenTotal: hidden.length,
+        hiddenRunning: hidden.filter((r) => RUNNING.has(r.phase)).length,
+    };
+}

package/dist/team/prompt.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The two system-prompt blocks team mode adds (team-subagents §4.6).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope, and these
+ * strings also reach a model that may be running in a `cmd.exe` terminal.
+ *
+ * BOTH BLOCKS ARE SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what
+ * preserves invariant I-8: with team mode off the prompt is BYTE-IDENTICAL to
+ * the pre-team output for a fixed tool array. An unconditional guidance line
+ * anywhere here would quietly break `--no-team`, `--no-skills` and the plan-mode
+ * snapshot all at once.
+ *
+ * `TEAM_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report.
+ */
+import { TEAM_BLOCK_VERSION } from './limits.js';
+export { TEAM_BLOCK_VERSION };
+export interface TeamBlockParams {
+    maxSubagents: number;
+    maxConcurrent: number;
+}
+/**
+ * The lead's `<team_mode>` block. Under 1200 characters on purpose: it is paid
+ * for on EVERY turn of every team-enabled session, so anything that does not
+ * change a delegation decision does not belong in it.
+ *
+ * "Two to four is the usual size" is where the requirement's "shu liang zi shi
+ * ying" (adaptive count) actually lives. The ceiling is mechanical and enforced
+ * elsewhere; the CHOICE is the model's, and this paragraph is the only thing
+ * that informs it.
+ */
+export declare function buildTeamBlock(params: TeamBlockParams): string;
+export interface SubagentBlockParams {
+    label: string;
+    description: string;
+    /** Sibling labels, excluding this child's own. */
+    peers: string[];
+}
+/**
+ * The child's `<subagent_role>` block.
+ *
+ * "YOUR FINAL MESSAGE IS THE ONLY THING YOUR LEAD SEES" is load-bearing rather
+ * than decorative: `SubagentRun.summary` is literally the last assistant text of
+ * the child's history, so a child that signs off with "Let me know if you want
+ * more detail!" produces a useless report entry and there is no mechanism that
+ * can repair it after the fact. Wording is the only enforcement available, so it
+ * is stated in imperative terms (R-12).
+ */
+export declare function buildSubagentBlock(params: SubagentBlockParams): string;

package/dist/team/prompt.js

@@ -0,0 +1,87 @@
+/**
+ * The two system-prompt blocks team mode adds (team-subagents §4.6).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope, and these
+ * strings also reach a model that may be running in a `cmd.exe` terminal.
+ *
+ * BOTH BLOCKS ARE SPLICED CONDITIONALLY by `buildSystemPrompt`, which is what
+ * preserves invariant I-8: with team mode off the prompt is BYTE-IDENTICAL to
+ * the pre-team output for a fixed tool array. An unconditional guidance line
+ * anywhere here would quietly break `--no-team`, `--no-skills` and the plan-mode
+ * snapshot all at once.
+ *
+ * `TEAM_BLOCK_VERSION` exists so a change to this wording is greppable from a
+ * behaviour report.
+ */
+import { TEAM_BLOCK_VERSION, TEAM_LIMITS } from './limits.js';
+export { TEAM_BLOCK_VERSION };
+/**
+ * The lead's `<team_mode>` block. Under 1200 characters on purpose: it is paid
+ * for on EVERY turn of every team-enabled session, so anything that does not
+ * change a delegation decision does not belong in it.
+ *
+ * "Two to four is the usual size" is where the requirement's "shu liang zi shi
+ * ying" (adaptive count) actually lives. The ceiling is mechanical and enforced
+ * elsewhere; the CHOICE is the model's, and this paragraph is the only thing
+ * that informs it.
+ */
+export function buildTeamBlock(params) {
+    const max = Math.max(1, Math.floor(params.maxSubagents));
+    const concurrent = Math.max(1, Math.min(Math.floor(params.maxConcurrent), max));
+    return [
+        '<team_mode>',
+        `You can delegate to parallel subagents with the task tool (up to ${max} per`,
+        `call, ${concurrent} running at once).`,
+        '',
+        'Delegate when: the work splits into 2+ parts that do not need each other\'s',
+        'output; several areas must be read or searched at once; a long build or test',
+        'run can proceed while another part is investigated.',
+        '',
+        'Do not delegate when: one part needs another part\'s result (do those in order',
+        'yourself); two parts would edit the same file; the whole job is a few edits.',
+        'One well-scoped subagent is better than four vague ones. Two to four is the',
+        'usual size; more than that is rarely faster.',
+        '',
+        'Each subagent starts with no memory of this conversation, so its prompt must',
+        'carry everything it needs: the goal, the files or areas it owns, and what to',
+        'report back. Give each one a disjoint set of files to write. Subagents cannot',
+        'dispatch further subagents and cannot ask the user anything.',
+        '',
+        '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>',
+    ].join('\n');
+}
+/**
+ * The child's `<subagent_role>` block.
+ *
+ * "YOUR FINAL MESSAGE IS THE ONLY THING YOUR LEAD SEES" is load-bearing rather
+ * than decorative: `SubagentRun.summary` is literally the last assistant text of
+ * the child's history, so a child that signs off with "Let me know if you want
+ * more detail!" produces a useless report entry and there is no mechanism that
+ * can repair it after the fact. Wording is the only enforcement available, so it
+ * is stated in imperative terms (R-12).
+ */
+export function buildSubagentBlock(params) {
+    const peers = params.peers.length > 0
+        ? `Teammates: ${params.peers.join(', ')}. You cannot see their conversations and they cannot see yours.`
+        : 'You are the only subagent on this task.';
+    return [
+        '<subagent_role>',
+        `You are subagent "${params.label}" on a team. Your job: ${params.description}.`,
+        peers,
+        '',
+        'Work only on your own task. Do not edit files another subagent owns. You cannot',
+        'delegate further and there is no user to ask - if something is ambiguous, choose',
+        'the most reasonable reading, proceed, and say what you assumed.',
+        '',
+        `To reach a teammate use team_send (at most ${TEAM_LIMITS.messagesPerAgent} messages, one every`,
+        `${Math.round(TEAM_LIMITS.minSendIntervalMs / 1000)} seconds). Their replies arrive attached to your next tool result.`,
+        'Use team_wait only when you genuinely cannot continue without an answer.',
+        '',
+        'END WITH YOUR REPORT. Your final message is the only thing your lead sees. It',
+        'must state: what you did, what you found, every file you changed, and anything',
+        'still open. Be concrete and brief - no preamble, no restating this brief.',
+        '</subagent_role>',
+    ].join('\n');
+}

package/dist/team/report.d.ts

@@ -0,0 +1,58 @@
+/**
+ * `buildDispatchReport` — the single text the lead receives back from `task`
+ * (team-subagents §3.7).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * BUDGETS ARE IN BYTES, NOT CHARACTERS (D-8 / I-9). `ToolExecutor` truncates
+ * combined tool text at 100 000 BYTES and appends `... [truncated]`; a 24 000
+ * character CJK report is 72 000 bytes, so a character-denominated cap would let
+ * the executor chop the report mid-section — and because the header is FIRST,
+ * what it would chop off is the tail, but a report assembled the other way round
+ * would lose its own failure count. Hence the second rule below.
+ *
+ * HEADER FIRST, ALWAYS. When the budget is exhausted the SUMMARIES are trimmed
+ * (longest first, each to a floor, with an explicit `[trimmed]` marker); the
+ * header, the per-agent status lines and the conflict warning are never dropped.
+ * A report that loses its own failure count is worse than one that loses prose.
+ *
+ * A FAILED CHILD NEVER FAILS THE DISPATCH (D-14). Partial results are the normal
+ * outcome of a fan-out; an all-or-nothing result would throw away four successes
+ * because of one HTTP 429.
+ */
+import type { ModelCost } from '@aragon-agent/core';
+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;
+}
+/**
+ * Cut `text` to at most `maxBytes` WITHOUT splitting a UTF-8 sequence.
+ *
+ * Slicing the buffer blindly at a byte offset produces a replacement character
+ * in the middle of a CJK report — the exact failure D-8 exists to prevent, just
+ * one layer lower down.
+ */
+export declare function truncateBytes(text: string, maxBytes: number): string;
+/**
+ * Files written by more than one child.
+ *
+ * PHRASED AS A WARNING, NEVER AS A FACT. `filesTouched` only sees `write_file` /
+ * `edit_file`, so a child that writes through `bash` is invisible to it (R-2).
+ * "review before trusting either" is honest about that; "these two conflict"
+ * would not be.
+ */
+export declare function findFileConflicts(runs: SubagentRun[]): Array<{
+    path: string;
+    labels: string[];
+}>;
+/**
+ * Assemble the report.
+ *
+ * Trimming order: every summary starts clamped to `summaryMaxBytes`; if the
+ * whole document is still over `reportMaxBytes`, the LONGEST summary is halved
+ * repeatedly (never below `summaryFloorBytes`) until it fits or every summary is
+ * at the floor. Only then, as a last resort, are summaries dropped entirely —
+ * and even then the status lines survive, because they carry the failure count.
+ */
+export declare function buildDispatchReport(outcome: DispatchOutcome, options?: ReportOptions): string;

package/dist/team/report.js

@@ -0,0 +1,205 @@
+/**
+ * `buildDispatchReport` — the single text the lead receives back from `task`
+ * (team-subagents §3.7).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * BUDGETS ARE IN BYTES, NOT CHARACTERS (D-8 / I-9). `ToolExecutor` truncates
+ * combined tool text at 100 000 BYTES and appends `... [truncated]`; a 24 000
+ * character CJK report is 72 000 bytes, so a character-denominated cap would let
+ * the executor chop the report mid-section — and because the header is FIRST,
+ * what it would chop off is the tail, but a report assembled the other way round
+ * would lose its own failure count. Hence the second rule below.
+ *
+ * HEADER FIRST, ALWAYS. When the budget is exhausted the SUMMARIES are trimmed
+ * (longest first, each to a floor, with an explicit `[trimmed]` marker); the
+ * header, the per-agent status lines and the conflict warning are never dropped.
+ * A report that loses its own failure count is worse than one that loses prose.
+ *
+ * A FAILED CHILD NEVER FAILS THE DISPATCH (D-14). Partial results are the normal
+ * outcome of a fan-out; an all-or-nothing result would throw away four successes
+ * because of one HTTP 429.
+ */
+import { computeCost, formatCost, formatDuration, formatTokens } from '../agent/usage.js';
+import { TEAM_LIMITS } from './limits.js';
+function byteLength(text) {
+    return Buffer.byteLength(text, 'utf8');
+}
+/**
+ * Cut `text` to at most `maxBytes` WITHOUT splitting a UTF-8 sequence.
+ *
+ * Slicing the buffer blindly at a byte offset produces a replacement character
+ * in the middle of a CJK report — the exact failure D-8 exists to prevent, just
+ * one layer lower down.
+ */
+export function truncateBytes(text, maxBytes) {
+    if (maxBytes <= 0)
+        return '';
+    if (byteLength(text) <= maxBytes)
+        return text;
+    const buf = Buffer.from(text, 'utf8');
+    let end = Math.min(maxBytes, buf.length);
+    // A continuation byte is 0b10xxxxxx; back off until `end` starts a sequence.
+    while (end > 0 && (buf[end] !== undefined) && (buf[end] & 0xc0) === 0x80)
+        end -= 1;
+    return buf.subarray(0, end).toString('utf8');
+}
+/** `ok` / `aborted` / `failed: <reason>` — the bracketed badge on a section head. */
+function statusBadge(run) {
+    if (run.phase === 'aborted')
+        return '[aborted]';
+    if (run.phase === 'failed' || run.error) {
+        return `[failed: ${run.error ?? 'run produced no output'}]`;
+    }
+    if (run.truncated)
+        return '[stopped: turn cap reached]';
+    return '[ok]';
+}
+function elapsed(run) {
+    if (run.startedAt === undefined)
+        return '0.0s';
+    return formatDuration(Math.max(0, (run.endedAt ?? run.startedAt) - run.startedAt));
+}
+function isOk(run) {
+    return run.phase === 'done' && !run.error;
+}
+/**
+ * Files written by more than one child.
+ *
+ * PHRASED AS A WARNING, NEVER AS A FACT. `filesTouched` only sees `write_file` /
+ * `edit_file`, so a child that writes through `bash` is invisible to it (R-2).
+ * "review before trusting either" is honest about that; "these two conflict"
+ * would not be.
+ */
+export function findFileConflicts(runs) {
+    const owners = new Map();
+    for (const run of runs) {
+        for (const path of run.filesTouched) {
+            const list = owners.get(path) ?? [];
+            if (!list.includes(run.label))
+                list.push(run.label);
+            owners.set(path, list);
+        }
+    }
+    const out = [];
+    for (const [path, labels] of owners) {
+        if (labels.length > 1)
+            out.push({ path, labels });
+    }
+    return out.sort((a, b) => a.path.localeCompare(b.path, 'en'));
+}
+function buildHeader(outcome, options) {
+    const lines = [];
+    const durationMs = Math.max(0, outcome.endedAt - outcome.startedAt);
+    if (outcome.aborted) {
+        // FIRST LINE on an abort, so the model cannot present partial work as
+        // complete without having read past it.
+        lines.push(`Team dispatch ABORTED after ${formatDuration(durationMs)}; partial results below.`);
+    }
+    const ok = outcome.runs.filter(isOk).length;
+    const failed = outcome.runs.length - ok;
+    const counts = `${ok} ok, ${failed} failed`;
+    lines.push(outcome.requested > outcome.runs.length
+        ? `Team dispatch: ran ${outcome.runs.length} of ${outcome.requested} requested subagents ` +
+            `(${counts}) in ${formatDuration(durationMs)}.`
+        : `Team dispatch: ${outcome.runs.length} of ${outcome.runs.length} subagents finished ` +
+            `(${counts}) in ${formatDuration(durationMs)}.`);
+    lines.push(`Tokens: in ${formatTokens(outcome.usage.inputTokens)}, out ` +
+        `${formatTokens(outcome.usage.outputTokens)}. Cost: ${formatCost(computeCost(outcome.usage, options.cost))}.`);
+    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.`);
+    }
+    return lines;
+}
+function buildSection(run) {
+    // `retried Nx` on the head line, which is never trimmed. 11 bytes, and it is
+    // 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` : '';
+    const head = [
+        `### ${run.label} "${run.description}"  ${statusBadge(run)}  ${elapsed(run)}, ` +
+            `${run.turns} turns, ${run.toolCalls} tools${retried}`,
+    ];
+    if (run.filesTouched.length > 0)
+        head.push(`files: ${run.filesTouched.join(', ')}`);
+    // A child that tried to reach a teammate and could not is a child whose brief
+    // had a dependency the lead should not have split (F-3). One line, in a
+    // section that is trimmed last, and only when it actually happened.
+    if (run.blockedWaits)
+        head.push(`blocked waits: ${run.blockedWaits} (no teammate could answer)`);
+    const summary = (run.summary ?? '').trim();
+    return { head, summary: summary.length > 0 ? summary : '(no summary)' };
+}
+function buildLeadMail(outcome) {
+    if (outcome.leadMail.length === 0)
+        return [];
+    const lines = ['### Messages to you'];
+    for (const m of outcome.leadMail) {
+        const at = Math.max(0, Math.round((m.at - outcome.startedAt) / 1000));
+        lines.push(`[${m.from} -> lead] "${m.subject}" (${at}s in)`);
+        if (m.body.length > 0)
+            lines.push(m.body);
+    }
+    return lines;
+}
+/**
+ * Assemble the report.
+ *
+ * Trimming order: every summary starts clamped to `summaryMaxBytes`; if the
+ * whole document is still over `reportMaxBytes`, the LONGEST summary is halved
+ * repeatedly (never below `summaryFloorBytes`) until it fits or every summary is
+ * at the floor. Only then, as a last resort, are summaries dropped entirely —
+ * and even then the status lines survive, because they carry the failure count.
+ */
+export function buildDispatchReport(outcome, options = {}) {
+    const header = buildHeader(outcome, options);
+    const sections = outcome.runs.map(buildSection);
+    const mail = buildLeadMail(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) => {
+        const blocks = [header.join('\n')];
+        sections.forEach((section, i) => {
+            const body = bodies[i];
+            const lines = [...section.head];
+            if (body !== null && body !== undefined) {
+                lines.push(trimmed[i] ? `${body}\n[trimmed]` : body);
+            }
+            blocks.push(lines.join('\n'));
+        });
+        if (mail.length > 0)
+            blocks.push(mail.join('\n'));
+        return blocks.join('\n\n');
+    };
+    let bodies = [...summaries];
+    let out = render(bodies);
+    let guard = 0;
+    while (byteLength(out) > TEAM_LIMITS.reportMaxBytes && guard < 200) {
+        guard += 1;
+        let longest = -1;
+        let longestBytes = TEAM_LIMITS.summaryFloorBytes;
+        bodies.forEach((body, i) => {
+            if (body === null)
+                return;
+            const size = byteLength(body);
+            if (size > longestBytes) {
+                longest = i;
+                longestBytes = size;
+            }
+        });
+        if (longest < 0)
+            break; // Every summary is at the floor.
+        const next = Math.max(TEAM_LIMITS.summaryFloorBytes, Math.floor(longestBytes / 2));
+        bodies[longest] = truncateBytes(bodies[longest], next);
+        trimmed[longest] = true;
+        out = render(bodies);
+    }
+    if (byteLength(out) > TEAM_LIMITS.reportMaxBytes) {
+        // Last resort. The header, the status lines and the conflict warning are
+        // still here, which is the whole point of assembling them separately.
+        bodies = bodies.map(() => null);
+        out = render(bodies);
+    }
+    return out;
+}