@aragon-agent/cli 0.5.2 → 0.5.4

package/dist/team/human-queue.d.ts

@@ -0,0 +1,55 @@
+/**
+ * TeamHumanQueue — serializes subagent confirmations onto the ONE human slot
+ * (team-subagents §3.11 / I-4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * `App.tsx` holds `humanRequest` as a SINGLE state slot and `resolveHuman`
+ * broadcasts one response to every pending entry, so two children raising a
+ * `--confirm` dialog at the same instant would double-resolve it. This queue is
+ * a plain promise chain that admits one request at a time and prefixes the
+ * summary with the child's label, so the user can always tell WHICH agent is
+ * asking.
+ *
+ * THE WATCHDOG IS PAUSED ON ENQUEUE, NOT ON DISPLAY (D-18 / P0-4). This is
+ * invariant I-3 one level down, and it is the second-most likely way to ship
+ * this feature broken. A child sitting third in the FIFO is emitting nothing,
+ * and its own `idleTimeout` (210 s by default) is armed: a user who takes four
+ * minutes over the first dialog would otherwise lose children 2 and 3 to their
+ * own watchdogs, each printing `[Agent] idle watchdog fired` over the TUI and
+ * each landing in the report as a failure that has nothing to do with the work.
+ * `controller.ts` records fixing exactly this for the LEAD's `--confirm` gate;
+ * repeating it for children would regress a fix this codebase already paid for.
+ * The wait starts when the promise is chained, which is where the time actually
+ * goes — hence enqueue, not display.
+ */
+import type { ConfirmRequest } from '../tools/index.js';
+/** The slice of `Agent` this queue needs. Structural, so tests can stub it. */
+export interface WatchdogPausable {
+    pauseIdleWatchdog(): void;
+    resumeIdleWatchdog(): void;
+}
+export declare class TeamHumanQueue {
+    private readonly confirm;
+    /** The chain. Never rejects: a failed request resolves `false` (deny). */
+    private tail;
+    constructor(confirm: (req: ConfirmRequest) => Promise<boolean>);
+    /**
+     * Ask the human about `req` on behalf of `label`, one at a time.
+     *
+     * @param child  Paused for the whole wait, queue time included. May be `null`
+     *               in the window before the child's `Agent` exists.
+     * @param signal The child's `ctx.signal`. An abort resolves `false` so the
+     *               child is never left owing an answer to a dialog nobody is
+     *               going to reach.
+     */
+    request(child: WatchdogPausable | null, label: string, req: ConfirmRequest, signal?: AbortSignal): Promise<boolean>;
+    /**
+     * Chain `run` after everything already queued.
+     *
+     * The `catch` is what keeps the chain alive: an unhandled rejection here would
+     * poison `this.tail` and every LATER request would reject without ever being
+     * shown, which presents as "the second file write silently did nothing".
+     */
+    private enqueue;
+}

package/dist/team/human-queue.js

@@ -0,0 +1,72 @@
+/**
+ * TeamHumanQueue — serializes subagent confirmations onto the ONE human slot
+ * (team-subagents §3.11 / I-4).
+ *
+ * ASCII ONLY: `src/team/**` is inside the glyph scanner's scope.
+ *
+ * `App.tsx` holds `humanRequest` as a SINGLE state slot and `resolveHuman`
+ * broadcasts one response to every pending entry, so two children raising a
+ * `--confirm` dialog at the same instant would double-resolve it. This queue is
+ * a plain promise chain that admits one request at a time and prefixes the
+ * summary with the child's label, so the user can always tell WHICH agent is
+ * asking.
+ *
+ * THE WATCHDOG IS PAUSED ON ENQUEUE, NOT ON DISPLAY (D-18 / P0-4). This is
+ * invariant I-3 one level down, and it is the second-most likely way to ship
+ * this feature broken. A child sitting third in the FIFO is emitting nothing,
+ * and its own `idleTimeout` (210 s by default) is armed: a user who takes four
+ * minutes over the first dialog would otherwise lose children 2 and 3 to their
+ * own watchdogs, each printing `[Agent] idle watchdog fired` over the TUI and
+ * each landing in the report as a failure that has nothing to do with the work.
+ * `controller.ts` records fixing exactly this for the LEAD's `--confirm` gate;
+ * repeating it for children would regress a fix this codebase already paid for.
+ * The wait starts when the promise is chained, which is where the time actually
+ * goes — hence enqueue, not display.
+ */
+export class TeamHumanQueue {
+    confirm;
+    /** The chain. Never rejects: a failed request resolves `false` (deny). */
+    tail = Promise.resolve();
+    constructor(confirm) {
+        this.confirm = confirm;
+    }
+    /**
+     * Ask the human about `req` on behalf of `label`, one at a time.
+     *
+     * @param child  Paused for the whole wait, queue time included. May be `null`
+     *               in the window before the child's `Agent` exists.
+     * @param signal The child's `ctx.signal`. An abort resolves `false` so the
+     *               child is never left owing an answer to a dialog nobody is
+     *               going to reach.
+     */
+    request(child, label, req, signal) {
+        child?.pauseIdleWatchdog();
+        const queued = this.enqueue(async () => {
+            if (signal?.aborted)
+                return false;
+            return this.confirm({ ...req, summary: `[${label}] ${req.summary}` });
+        });
+        const raced = signal ? Promise.race([queued, abortsToFalse(signal)]) : queued;
+        return raced.finally(() => child?.resumeIdleWatchdog());
+    }
+    /**
+     * Chain `run` after everything already queued.
+     *
+     * The `catch` is what keeps the chain alive: an unhandled rejection here would
+     * poison `this.tail` and every LATER request would reject without ever being
+     * shown, which presents as "the second file write silently did nothing".
+     */
+    enqueue(run) {
+        const next = this.tail.then(run, run).catch(() => false);
+        this.tail = next;
+        return next;
+    }
+}
+/** Resolve `false` when `signal` aborts, with the listener cleaned up after. */
+function abortsToFalse(signal) {
+    if (signal.aborted)
+        return Promise.resolve(false);
+    return new Promise((resolve) => {
+        signal.addEventListener('abort', () => resolve(false), { once: true });
+    });
+}

package/dist/team/limits.d.ts

@@ -0,0 +1,123 @@
+/**
+ * TEAM_LIMITS — the single authority on every bound this subsystem enforces
+ * (team-subagents §3.5 / §3.6).
+ *
+ * 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.
+ *
+ * TWO KINDS OF NUMBER LIVE HERE AND THEY ARE NOT INTERCHANGEABLE.
+ *
+ *  - The `TEAM_LIMITS` entries below are STRUCTURAL: they describe what the
+ *    report format, the message channel and the panel can physically carry, and
+ *    a user has no business tuning them. They are constants.
+ *  - The six `team.*` config keys (`config/schema.ts`) are POLICY: how wide to
+ *    fan out, how long to wait. They are clamped, persisted and user-facing.
+ *
+ * `hardMaxSubagents` sits on the structural side ON PURPOSE even though it
+ * bounds a config key: the requirement caps the fan-out at 10 (R-g), so a
+ * hand-edited `config.json` must not be able to raise it. It is applied twice —
+ * once in `clampTeamConfig` and once in `normalizeSubagentSpecs` — because a
+ * clamp that only runs on the read path leaves a bad value on disk.
+ *
+ * BYTES, NOT CHARACTERS, for every report budget (D-8 / I-9). `ToolExecutor`
+ * truncates combined tool text at 100 000 BYTES; 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 take the failure count with it.
+ */
+export declare 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.
+     */
+    readonly hardMaxSubagents: 10;
+    /** `SubagentSpec.description`, clamped (never rejected). */
+    readonly descriptionChars: 60;
+    /** `SubagentSpec.prompt`, clamped. The child cannot see the conversation, so
+     *  this has to be generous enough to carry a whole brief. */
+    readonly promptChars: 8000;
+    /** Slugified `SubagentSpec.label`. Long enough to be meaningful in the panel,
+     *  short enough that five of them fit one row of an 80-column terminal. */
+    readonly labelChars: 12;
+    readonly reportMaxBytes: 48000;
+    readonly summaryMaxBytes: 6000;
+    /**
+     * Floor a summary is trimmed TO, never below. A section trimmed to nothing is
+     * indistinguishable from a child that reported nothing, which is exactly the
+     * distinction the report exists to preserve.
+     */
+    readonly summaryFloorBytes: 400;
+    /** Deduped `write_file` / `edit_file` paths recorded per child (§3.4). */
+    readonly filesTouchedMax: 30;
+    /** `team_send` calls one child may spend on a whole dispatch. */
+    readonly messagesPerAgent: 6;
+    /** `team_send` calls the whole dispatch may spend. */
+    readonly messagesPerDispatch: 24;
+    /** Minimum gap between one child's sends. */
+    readonly minSendIntervalMs: 15000;
+    /** Quota units a `to: "all"` broadcast costs. */
+    readonly broadcastCost: 2;
+    readonly subjectChars: 80;
+    readonly bodyChars: 800;
+    /** `team_wait` timeout clamp, in seconds. */
+    readonly waitMinSeconds: 5;
+    readonly waitMaxSeconds: 120;
+    readonly waitDefaultSeconds: 30;
+    /**
+     * `agent_update` coalescing window (§5.2). Five children streaming tokens must
+     * not push five React renders per token; phase transitions always pass.
+     */
+    readonly agentUpdateThrottleMs: 120;
+    /** Agent rows the live panel renders before collapsing to `+N more` (§6.1). */
+    readonly panelMaxRows: 5;
+    /** Below this many terminal rows the panel collapses to its header line. */
+    readonly panelCollapseRows: 20;
+    /** Below this many columns the status-bar readout degrades to `[3]` (D-20). */
+    readonly statusCompactCols: 100;
+    /**
+     * STORAGE ceiling for a prose activity tail (P0-1). The most a `SubagentRun`
+     * may carry, NOT the width of the column: `TeamPanel.activityBudget(cols)`
+     * derives the display budget from the terminal and is always <= this.
+     */
+    readonly activityChars: 64;
+    /**
+     * Floor under `activityBudget`. Below roughly 46 columns the roster has bigger
+     * problems than an elided activity line, and a column narrower than this shows
+     * nothing but an ellipsis - at which point the phase word is more informative.
+     */
+    readonly activityMinChars: 12;
+    /** Rolling text buffer kept per child. The only per-token allocation. */
+    readonly activityTailChars: 160;
+    /** Per picked tool argument (P1-4). A path or a command longer than this is
+     *  elided on capture, so a run can never carry more than a few hundred bytes
+     *  of argument however large the real call was. */
+    readonly activityArgChars: 120;
+    /** At or above this many columns the activity line carries a full path or
+     *  command; below it, a basename or a program name. Mirrors `statusCompactCols`.
+     *  This chooses WHICH FACT to show; `activityBudget` chooses how much of it. */
+    readonly activityWideCols: 100;
+    /** Retries of a child that produced NOTHING. One, and not configurable: a
+     *  second retry doubles the worst-case latency of a failing dispatch and buys
+     *  nothing a re-dispatch by the lead would not buy better. */
+    readonly maxColdStartRetries: 1;
+    readonly retryBackoffMs: 2000;
+};
+/**
+ * The two comm tools, which are POLICY-EXEMPT inside a child (§3.11).
+ *
+ * They are not in the lead's registered tool list, so evaluating them against
+ * the lead's `allowed-tools` ceiling would refuse them and dead-end the channel
+ * — the same dead end `SKILL_TOOL_FLOOR` exists to prevent one level up.
+ *
+ * Deliberately NOT added to `HOST_TOOL_NAMES` (P2-5). That constant answers
+ * "can a skill's `allowed-tools` declaration ever take effect?", and these two
+ * are never registered on a lead — so a skill naming them genuinely IS
+ * unenforceable, and `aragon skills doctor` reporting it as such is correct
+ * rather than a gap.
+ */
+export declare const TEAM_SUBAGENT_TOOL_NAMES: ReadonlySet<string>;
+/**
+ * Bumped whenever the wording of either prompt block changes, so a behaviour
+ * report can be tied to a block revision with one grep.
+ */
+export declare const TEAM_BLOCK_VERSION = "v1-2026-07";

package/dist/team/limits.js

@@ -0,0 +1,128 @@
+/**
+ * TEAM_LIMITS — the single authority on every bound this subsystem enforces
+ * (team-subagents §3.5 / §3.6).
+ *
+ * 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.
+ *
+ * TWO KINDS OF NUMBER LIVE HERE AND THEY ARE NOT INTERCHANGEABLE.
+ *
+ *  - The `TEAM_LIMITS` entries below are STRUCTURAL: they describe what the
+ *    report format, the message channel and the panel can physically carry, and
+ *    a user has no business tuning them. They are constants.
+ *  - The six `team.*` config keys (`config/schema.ts`) are POLICY: how wide to
+ *    fan out, how long to wait. They are clamped, persisted and user-facing.
+ *
+ * `hardMaxSubagents` sits on the structural side ON PURPOSE even though it
+ * bounds a config key: the requirement caps the fan-out at 10 (R-g), so a
+ * hand-edited `config.json` must not be able to raise it. It is applied twice —
+ * once in `clampTeamConfig` and once in `normalizeSubagentSpecs` — because a
+ * clamp that only runs on the read path leaves a bad value on disk.
+ *
+ * BYTES, NOT CHARACTERS, for every report budget (D-8 / I-9). `ToolExecutor`
+ * truncates combined tool text at 100 000 BYTES; 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 take the failure count with it.
+ */
+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,
+    // --- Spec normalization (§3.3.1) ---
+    /** `SubagentSpec.description`, clamped (never rejected). */
+    descriptionChars: 60,
+    /** `SubagentSpec.prompt`, clamped. The child cannot see the conversation, so
+     *  this has to be generous enough to carry a whole brief. */
+    promptChars: 8000,
+    /** Slugified `SubagentSpec.label`. Long enough to be meaningful in the panel,
+     *  short enough that five of them fit one row of an 80-column terminal. */
+    labelChars: 12,
+    // --- Report budgeting (§3.7). BYTES. ---
+    reportMaxBytes: 48_000,
+    summaryMaxBytes: 6_000,
+    /**
+     * Floor a summary is trimmed TO, never below. A section trimmed to nothing is
+     * indistinguishable from a child that reported nothing, which is exactly the
+     * distinction the report exists to preserve.
+     */
+    summaryFloorBytes: 400,
+    /** Deduped `write_file` / `edit_file` paths recorded per child (§3.4). */
+    filesTouchedMax: 30,
+    // --- The team bus (§3.6). The "bu neng tai pin fan" clause, in numbers. ---
+    /** `team_send` calls one child may spend on a whole dispatch. */
+    messagesPerAgent: 6,
+    /** `team_send` calls the whole dispatch may spend. */
+    messagesPerDispatch: 24,
+    /** Minimum gap between one child's sends. */
+    minSendIntervalMs: 15_000,
+    /** Quota units a `to: "all"` broadcast costs. */
+    broadcastCost: 2,
+    subjectChars: 80,
+    bodyChars: 800,
+    /** `team_wait` timeout clamp, in seconds. */
+    waitMinSeconds: 5,
+    waitMaxSeconds: 120,
+    waitDefaultSeconds: 30,
+    /**
+     * `agent_update` coalescing window (§5.2). Five children streaming tokens must
+     * not push five React renders per token; phase transitions always pass.
+     */
+    agentUpdateThrottleMs: 120,
+    /** Agent rows the live panel renders before collapsing to `+N more` (§6.1). */
+    panelMaxRows: 5,
+    /** Below this many terminal rows the panel collapses to its header line. */
+    panelCollapseRows: 20,
+    /** Below this many columns the status-bar readout degrades to `[3]` (D-20). */
+    statusCompactCols: 100,
+    // --- Live activity (team-live-activity F-1) ---
+    /**
+     * STORAGE ceiling for a prose activity tail (P0-1). The most a `SubagentRun`
+     * may carry, NOT the width of the column: `TeamPanel.activityBudget(cols)`
+     * derives the display budget from the terminal and is always <= this.
+     */
+    activityChars: 64,
+    /**
+     * Floor under `activityBudget`. Below roughly 46 columns the roster has bigger
+     * problems than an elided activity line, and a column narrower than this shows
+     * nothing but an ellipsis - at which point the phase word is more informative.
+     */
+    activityMinChars: 12,
+    /** Rolling text buffer kept per child. The only per-token allocation. */
+    activityTailChars: 160,
+    /** Per picked tool argument (P1-4). A path or a command longer than this is
+     *  elided on capture, so a run can never carry more than a few hundred bytes
+     *  of argument however large the real call was. */
+    activityArgChars: 120,
+    /** At or above this many columns the activity line carries a full path or
+     *  command; below it, a basename or a program name. Mirrors `statusCompactCols`.
+     *  This chooses WHICH FACT to show; `activityBudget` chooses how much of it. */
+    activityWideCols: 100,
+    // --- Cold-start retry (team-live-activity F-4) ---
+    /** Retries of a child that produced NOTHING. One, and not configurable: a
+     *  second retry doubles the worst-case latency of a failing dispatch and buys
+     *  nothing a re-dispatch by the lead would not buy better. */
+    maxColdStartRetries: 1,
+    retryBackoffMs: 2_000,
+};
+/**
+ * The two comm tools, which are POLICY-EXEMPT inside a child (§3.11).
+ *
+ * They are not in the lead's registered tool list, so evaluating them against
+ * the lead's `allowed-tools` ceiling would refuse them and dead-end the channel
+ * — the same dead end `SKILL_TOOL_FLOOR` exists to prevent one level up.
+ *
+ * Deliberately NOT added to `HOST_TOOL_NAMES` (P2-5). That constant answers
+ * "can a skill's `allowed-tools` declaration ever take effect?", and these two
+ * are never registered on a lead — so a skill naming them genuinely IS
+ * unenforceable, and `aragon skills doctor` reporting it as such is correct
+ * rather than a gap.
+ */
+export const TEAM_SUBAGENT_TOOL_NAMES = new Set(['team_send', 'team_wait']);
+/**
+ * Bumped whenever the wording of either prompt block changes, so a behaviour
+ * report can be tied to a block revision with one grep.
+ */
+export const TEAM_BLOCK_VERSION = 'v1-2026-07';

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,
+    };
+}